# Expression and component library extensibility

Status: agreed extension goals and responsibilities. The first slice supports declarative expression libraries supplied explicitly by the Host; see the [slice guide](quality-slice.md). A general SDK, manifest, dynamic loading, and executable-extension isolation are not yet settled.

Scope update: user extension mechanisms in this document apply only to HTML. Mermaid, pseudocode, text trees, and diff use built-in implementations and do not accept external elements, component libraries, or custom display Adapters; see [built-in forms](native-forms.md).

## Goal

Users can add domain expression elements, composition recipes, and their own component libraries. Extensions satisfying the existing adaptation contract should be registered without modifying the core engine or adding branches keyed to library names.

The first default catalog is not a permanently closed enumeration. Built-in libraries should use the extension contract too, without privileged paths unavailable to user extensions.

## Separation of responsibilities

| Layer | Owns | Must not own |
| --- | --- | --- |
| Expression library | Element meaning, content constraints, use cases, recipes, examples | Global coordinates, connector routing, whole-artifact quality verdicts |
| Display adaptation and component library | Form-specific component mappings, style resources, measurement, connection anchors, adjustable capabilities | Business relationship changes, bypassing core checks, assuming every form is supported |
| Core engine | Extension discovery and resolution, orchestration, layout, defect detection, repair budgets, final checks | A hard-coded domain catalog or user component names |

```text
Default / user expression libraries
  → Element references and recipes
  → Agent selects and organizes content
  → Core resolves selected elements and versions
  → Display adaptation uses built-in / user components
  → Measurement → layout → repair → final checks
```

The core depends on the extension contract rather than a particular library. Display adaptation may use a component library, but explaining an element's meaning should not require React, HTML, or a specific UI framework.

## Information the extension contract must cover

- **Identity and compatibility**: library namespace, version, element identifier, content schema version, and required core capabilities. Exact field names and version policy remain SDK design work.
- **Agent-discoverable references**: meanings, suitable and unsuitable uses, input constraints, recipes, and complete examples. Discovery should be limited to enabled libraries when requested.
- **Display capabilities**: supported HTML environments, components, resources, and expression limits. User components are not mapped into the other four built-in forms.
- **Layout participation**: where applicable, content dimensions, resizing limits, text bounds, connection anchors, avoidance regions, and permitted wrapping or layout changes. Text-oriented content supplies the relevant measurement and structural constraints without pretending to be graph nodes.
- **Semantic and quality constraints**: immutable meaning, permitted adjustments, and minimal acceptance examples. Extensions may add specialized checks but cannot disable applicable core quality gates.

Component libraries may supply fonts, colors, and internal styling. Actual dimensions must be measured after resources are ready; guessed fixed dimensions are not evidence. The agent references components and semantic properties, while the engine owns overall layout.

## Composition and lifecycle

An artifact may reference multiple libraries. Namespaced identities distinguish elements; loading order must not overwrite same-named elements. Record library and adaptation versions in artifact evidence for reproducibility.

Missing libraries, incompatible versions, unsupported forms, and unavailable measurements must produce explicit capability errors, not silent replacement with a same-named built-in element. Loaded does not mean quality-verified.

An existing component library needs appropriate adaptation. Installing an arbitrary UI package does not automatically provide connector avoidance or layout guarantees. When new capabilities exceed the current contract, evolve that contract explicitly instead of adding library-specific exceptions to the engine.

Installation sources, update policy, dependency loading, and execution constraints for executable extensions require separate design before implementation. This document does not assume a marketplace or authorize automatic downloading and execution of arbitrary user packages.

## Example: team architecture components

A user library defines service and message-queue elements and recipes for request flow and consumer retries. Its HTML adaptation uses the team's service-card and queue components and supplies measurements and connection anchors. If the agent chooses Mermaid, it expresses those concepts using built-in nodes and relations without referencing team components.

The agent selects elements, relationships, and the display form. Without knowing the team's component names, the engine can use adaptation results to check label occlusion, node overlap, and connector endpoints, then repair within the permitted range.

## Validation required for the first implementation

Use at least one minimal example library outside the core source to validate registration, discovery, composition, measurement, and quality checks. It should contain a custom element and one display adaptation, and be addable or removable without changing the core. The [team example](../examples/team-library.mjs) currently verifies declarative property mapping and composition of built-in visual styles; arbitrary UI components and executable display adaptations remain unimplemented.