# Extensions: configuration and capability contracts

Practical responsibilities from nodes/marks and commands to profiles, layout and selection.

## Configuration and composition

| Entry/hook | Result or responsibility | Constraint |
| --- | --- | --- |
| `Extension.create(config)` | Behavior definition | No schema node |
| `Node.create()` / `Mark.create()` | Node/mark definition | Node content/group and mark restrictions enter one schema |
| `.configure(options)` | Configured extension | Assemble per instance rather than mutating shared options |
| `.extend(config)` | Extended definition | Replace intentionally; verify parent-hook invocation and ordering |
| `addOptions()` | Defaults | Options are not persistent document data |
| `addStorage()` | Instance state | Persist business attributes in schema where required |
| `addExtensions()` | Child extensions | Composition point with unique schema owners |
| `addAttributes()` / `addGlobalAttributes()` | Attributes | Define defaults, parsing, serialization and migration |
| `addCommands()` | Raw command factories | Augment `Commands<ReturnType>` for direct/chain/can modes |
| `addKeyboardShortcuts()` | Key handlers | Use the same commands and return handling results |
| `addInputRules()` / `addPasteRules()` | Rules | Verify schema and history behavior |
| `addProseMirrorPlugins()` | PM plugins | Use the same `@quirekit/pm` identity |

See [custom behavior](/en/plugins/custom) and the [complete content extension](/en/build/extension).

## Capability owners

| Hook | Consumer | What is not automatic |
| --- | --- | --- |
| `addViewAdapters()` | Core mount lifetime | Schema does not provide input/painting |
| `addDocumentProfiles()` | Engine facet resolution | Core does not interpret Word fields or units |
| `addLayoutProviders()` | View/Engine | HTML CSS does not become Canvas layout |
| `addSelectionAdapters()` | Structured selection and command targets | Drawing is not selection correctness |
| `addDocx()` | Instance `editor.docx` | JSON persistence does not establish DOCX round trips |
| `addAccessibility()` | Accessibility owner | Drawing text does not provide accessible semantics |
| `addAiCapabilities()` | AI core | Features supply facts and described commands, not model tools/prompts |

Product UI hooks such as `addRibbonItems` require a consuming product registry. Pure Core does not create chrome from these declarations. See [product plugins](/en/build/product-plugin).

## Profiles and providers

Profiles supply model-wide page, paragraph, table and drawing semantics. Each facet has one owner; missing facets use neutral defaults. A profile is distinct from a custom Node's layout provider.

### QuireDocumentProfileRegistration

`@quirekit/core/document-profile` · MIT

Document-profile registration owned by an extension.

A profile supplies document-model semantics (for example Word paragraph
formatting or page sections) to a layout engine through named facets. Core
treats the payload as opaque; the consuming engine validates its shape.

```ts
export interface QuireDocumentProfileRegistration<Profile = unknown> {
    readonly id: string;
    readonly facets: readonly string[];
    readonly profile: Profile;
}
```

**id** — Stable profile identifier used for diagnostics and lookup.

**facets** — Facet names this profile supplies; each facet may have only one owner.

**profile** — Opaque profile payload consumed by the layout engine.

Providers declare node types and capabilities and return products with source ranges and snapshot identity. Use public subpaths; an internal type name is not necessarily exported at the package root.

### QuireLayoutProviderRegistration

`@quirekit/core/layout-provider` · MIT

Renderer-neutral provider registration owned by an extension.

```ts
export interface QuireLayoutProviderRegistration<Provider = unknown> {
    readonly id: string;
    readonly nodeTypes: readonly string[];
    readonly capabilities: readonly QuireLayoutProviderCapabilityKind[];
    readonly provider: Provider;
    readonly layoutDependency?: QuireLayoutDependency | undefined;
}
```

**id** — Stable provider identifier used for diagnostics and lookup.

**nodeTypes** — ProseMirror node type names handled by the provider.

**capabilities** — Capability classes implemented by the provider.

**provider** — Opaque provider payload consumed by a capability-owned integration.

**layoutDependency** — Optional proof covering this concrete provider and all mutable dependencies.

### createQuireLayoutProviderRegistration

`@quirekit/view-engine/layout-provider` · AGPL-3.0-only

Wraps one typed layout provider in renderer-neutral Core registration metadata.

Core can diagnose provider ids and node ownership without opening the
provider payload. View authority later verifies that the repeated metadata
still agrees with the typed payload before execution.
@param provider - Provider algorithm and its explicit capability declaration.
@returns Core registration carrying the unchanged typed provider payload.

```ts
function createQuireLayoutProviderRegistration(provider: QuireLayoutProvider): QuireViewLayoutProviderRegistration
```

See [complete source](/en/build/extension) for measurement → child flow → retained regions and selection. `layoutDependency: { kind: 'document' }` is valid only for a concrete provider that reads no undeclared external mutable state, not as a general performance switch.