@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/rmt-php-ssr-adapter.md

@@ -0,0 +1,118 @@
+# RMT PHP/Laravel SSR Adapter
+
+The PHP SSR adapter is the Laravel-compatible host layer for RMT vNext. It is a
+portable single-file PHP 8.1+ module at `xtendrmt/rmt-php-ssr-adapter.php`.
+This first slice does not require Composer or a Laravel service provider.
+
+Schema: `xtend.rmt.php-ssr-adapter.v1`
+
+The adapter is wire-compatible with the
+[RMT Node SSR Adapter](./rmt-node-ssr-adapter.md). Both backends emit the same
+client-facing render result, hydration payload, RenderMan chunk, and JSONL
+frame schemas: `xtend.rmt.node-ssr-render-result.v1`,
+`xtend.rmt.node-ssr-hydration-payload.v1`, and
+`xtend.rmt.node-ssr-jsonl-frame.v1`.
+
+## Role in the Stack
+
+RMT describes the app. XTend Components remain the UI building blocks. The PHP
+adapter serializes server-side Light DOM, capability markers, lazy import
+hints, and hydration payloads without instantiating custom elements on the
+server.
+
+It intentionally avoids:
+
+- server-side Shadow DOM rendering
+- private component maps
+- docs-app coupling
+- a PHP RMT compiler
+- implicit network access
+- HTML output without a trust boundary
+
+## Public API
+
+```php
+require __DIR__ . '/xtendrmt/rmt-php-ssr-adapter.php';
+
+$adapter = createRmtPhpSsrAdapter([
+    'manifest' => $manifest,
+    'endpointHandlers' => [
+        'ssr.hero' => fn () => [
+            'html' => '<x-hero>Hero</x-hero>',
+            'trustBoundary' => 'xtend.security.sanitizing-boundary.v1',
+        ],
+    ],
+]);
+
+$result = $adapter->render(['coreDocument' => $coreDocument]);
+```
+
+`render(...)` handles Core Documents, Prepared Templates, and DOM Descriptors
+directly. `.rmt` source requires an injected `compileRmtVNextSource` host
+bridge. Without that bridge the adapter reports
+`rmt.php_ssr.compiler_required`.
+
+## Laravel Helpers
+
+```php
+return $adapter->toLaravelResponse($result);
+
+return $adapter->toLaravelStreamedResponse([
+    'coreDocument' => $coreDocument,
+]);
+```
+
+When Laravel or Symfony response classes are available, the adapter uses them.
+Without the framework it degrades to plain arrays, so the same file works in
+Laravel, smaller PHP hosts, and tests.
+
+## JSONL Streaming
+
+`streamJsonl(...)` returns newline-delimited JSON with
+`xtend.rmt.node-ssr-jsonl-frame.v1`. Supported frame types are `start`,
+`component`, `html`, `hydration`, `diagnostic`, `complete`, and `error`.
+
+Each frame carries the same fields as the Node adapter: `requestId`,
+`sequence`, `operationId`, `variant`, `capability`, `lane`, `chunkKey`,
+`payload`, and `diagnostics`. The XTend browser runtime does not need to know
+whether Node or PHP/Laravel produced the stream.
+
+## Data Sources and Trust Boundaries
+
+Server data must come through explicit host hooks:
+
+- `resolveDataSource`
+- `endpointHandlers`
+- `staticDataSources`
+- `fixtures`
+- `fetchAdapter`
+- `laravelContainerResolver`
+
+HTML fragments need a boundary such as
+`xtend.security.sanitizing-boundary.v1` or
+`xtend.security.streaming-boundary.v1`. Unsafe URLs, event attributes,
+`srcdoc`, and blocked tags are diagnosed and removed by the fallback sanitizer.
+Production hosts can inject `sanitizeHtmlOutput`.
+
+## Docs App Integration
+
+The Docs app now uses the adapter directly in `docs/index.php` for shell-first
+prehydration.
+
+- Contract: `xtend.docs.php-ssr-prehydration.v1`
+- vNext source: `docs/xtendrmt-docs-shell-vnext.rmt`
+- Compiler bridge: `scripts/compile_rmt_vnext_bridge.js`
+- JSONL endpoint:
+  `index.php?xtend-docs-rmt-ssr=shell&format=jsonl&page={slug}&locale={locale}`
+
+The host injects `compileRmtVNextSource` through the Node bridge. Parsedown
+stays a host boundary and only fills the content slot, while the shell comes
+from RMT primitives, hydration, and RenderMan chunks.
+
+## Gates
+
+```bash
+npm run test:rmt-php-ssr-adapter
+npm run test:docs-php-ssr-prehydration
+node scripts/run_xtend_tests.js rmt-php-ssr-adapter --json
+```

package/docs/en/rmt-production-readiness.md

@@ -0,0 +1,63 @@
+# RMT Production Readiness
+
+- Contract: `xtend.epic13.rmt-production-readiness.v1`
+- Report: `xtend.epic13.rmt-production-readiness-report.v1`
+- Workpackage: `WP-E13-09`
+- Local gate: `node scripts/run_xtend_tests.js epic13-rmt-production-readiness --json`
+- Package script: `npm run test:epic13-rmt-production-readiness`
+- Publish boundary: `private-until-release-owner-acceptance`
+
+## Purpose
+
+`WP-E13-09` bundles the RMT-first app path for RC1. The package brings the existing RMT gates together into a production-close interface: shell-first app shell, native RMT routes, XTend components through adapters, Fabric/lane ingestion, lifecycle telemetry, diagnostics and XTendRMT artifact parity.
+
+The bundle adds no new app features. It makes visible that XTend apps can be templated completely in RMT while the RMT kernel remains framework-agnostic.
+
+## Source Gates
+
+```bash
+npm run test:rmt-compatibility
+npm run test:rmt-first-class-app
+npm run test:rmt-first-demo-app
+npm run test:rmt-artifact-parity
+npm run test:rmt-component-fabric-ingestion
+npm run test:rmt-component-lifecycle-telemetry
+npm run test:epic13-visual-owner-artifact
+```
+
+The local WP09 gate checks these source gates as a static RC1 bundle. It requires no network access and no external browser.
+
+## Readiness Domains
+
+| Domain | Evidence |
+| --- | --- |
+| Shell-first app shell | `tests/fixtures/rmt-first-class-xtend-app.rmt`, `xtendrmt/rmt-first-demo-app.rmt` |
+| Routing | `xtend.xrouter` adapter and RMT `routes` records |
+| Components | `xtend.component` adapter and RMT `components` records |
+| Fabric/Lane | `xtend.component.fabric-lane-ingestion.v2` |
+| Lifecycle Telemetry | `xtend.component.lifecycle-telemetry.v1` |
+| Diagnostics | `rmt.state-scheduler-diagnostics` and Fabric snapshots |
+| Artifact Parity | `xtend.rmt.artifact-parity.v1` |
+| Kernel Boundary | `no-rmt-kernel-import-of-xtend-types` |
+
+## Boundary
+
+RMT owns app records, routes, schedules, templates and metadata. XTend execution remains in host adapters:
+
+- XTend components are not imported into the RMT kernel.
+- XRouter is connected through `xtend.xrouter`.
+- Fabric/lane and telemetry signals are ingested, but not modeled as hard kernel dependencies.
+- React, Vue, Vanilla and custom hosts can use their own adapters.
+
+## References
+
+- [RMT-first XTend Apps](./rmt-first-xtend-apps.md)
+- [RMT-first Demo App](./rmt-first-demo-app.md)
+- [XTendRMT App DSL](./xtendrmt-app-dsl.md)
+- [XTendRMT Native Authoring](./xtendrmt-native-authoring.md)
+- [XTend-Fabric RMT Lane Mapping](./xtend-fabric-rmt-lane-mapping.md)
+- [Visual Owner Artifacts](./visual-owner-artifacts.md)
+
+## Handoff
+
+`WP-E13-09` is complete. `WP-E13-10` added [Docs RMT Production Hardening](./docs-rmt-production-hardening.md) and hardened the Docs app RMT Parsedown shell for production-close extensions. `WP-E13-11` completed [Trusted DOM Boundary Browser Proof](./trusted-dom-boundary-browser-proof.md) and `xtend.epic13.trusted-dom-boundary.v1`. `WP-E13-12` completed [RC1 Migration Notes](./rc1-migration-notes.md) and `xtend.epic13.rc1-migration-notes-semver.v1`. `WP-E13-13` completed [RC1 Gate Matrix and CI Handoff](./rc1-gate-matrix-ci-handoff.md) and `xtend.epic13.rc1-gate-matrix-ci-handoff.v1`.

package/docs/en/rmt-state-selector-runtime.md

@@ -0,0 +1,34 @@
+# RMT State Selector Runtime
+
+- Contract: `xtend.epic18.rmt-state-selector-runtime.v1`
+- Fixture: `tests/fixtures/rmt-state-selector-runtime.rmt`
+- Runtime: `xtendrmt/rmt-state-selector-runtime.js`
+- Types: `xtendrmt/rmt-state-selector-runtime.d.ts`
+- Local gate: `node scripts/run_xtend_tests.js rmt-state-selector-runtime --json`
+- Workpackage: `WP-E18-07`
+
+The State Selector Runtime makes app state declaratively usable for RMT templates. It defines typed state records, evaluates selectors and derived values, dispatches reducer commands and creates a render-context model for the DOM Descriptor Renderer from `WP-E18-05`/`WP-E18-06`.
+
+## Primitives
+
+| Primitive | Purpose |
+|-----------|---------|
+| `state` | typed app states such as collection, selection, filter, UI and loading |
+| `selector` | derived, reusable views on state, for example filtered lists |
+| `derive` | individual derived values such as selection count or detail label |
+| `reducer` | command-driven state changes without product-local mini-frameworks |
+| `xstateBridge` | injected host bridge to `xstate`, without runtime import |
+| `preservePatchPlan` | distinguishes structural rerenders from attribute/component-state sync |
+| `stateBindings` | updates attributes, classes and properties of existing DOM nodes |
+
+## Preserve Rules
+
+States with `preserve: "attribute-sync"` or `preserve: "component-state"` may preserve DOM islands. Selection or UI changes can therefore sync attributes such as `aria-selected`, classes such as `is-selected` or component properties without materializing lists again.
+
+Structural selectors, for example `selector.filtered-items`, may request a rerender instead. Filter or collection changes therefore stay correct, while pure selection changes can preserve focus, scroll and component instances.
+
+## XState Boundary
+
+The runtime does not import `xstate`. Host code can inject a compatible target with `set`, `setState`, `get`, `getState` or `subscribe`. The bridge mirrors state, selector and derived keys into that target, but also remains runnable with an internal snapshot.
+
+`WP-E18-08` can build actions, effects, datasources and resource runtime on top of this.

package/docs/en/rmt-surface-resource-graph-runtime.md

@@ -0,0 +1,68 @@
+# RMT Surface Resource Graph Runtime
+
+- Contract: `xtend.epic18.rmt-surface-resource-graph-runtime.v1`
+- Gate: `node scripts/run_xtend_tests.js rmt-surface-resource-graph-runtime --json`
+- Workpackage: `WP-E18-10`
+- Handoff: `WP-E18-11`
+
+## Goal
+
+The Surface Resource Graph Runtime makes dynamic app layouts modelable in RMT as a generic platform capability. Developers can create their own surface models from arbitrary records, manage bounds and focus, stack overlays through portals and clean up instance-owned resources without writing a product-local registry or shell-specific repaint logic.
+
+The Media Manager remains only a proof of need. The runtime knows no product surface list and imports no XTend components.
+
+## Keyed Surface Repeater
+
+`surface` definitions can declare `source`, `repeat` and `key`. The runtime creates stable surface instances such as `surface.workspace:alpha` from this. When materializing again with the same keys, runtime state, bounds, focus order, resource status and persistence data are preserved.
+
+Important operations:
+
+- `materialize(recordsBySource)`: creates or reuses surface instances.
+- `openSurface(id)`: opens an instance and acquires its resources.
+- `minimizeSurface(id)`: minimizes without discarding DOM or resource state.
+- `restoreSurface(id)`: restores bounds and open state.
+- `closeSurface(id)`: closes by policy without necessarily destroying.
+- `destroySurface(id)`: releases instance-owned resources and detaches the event owner.
+
+## Portal Layer Stack
+
+Portals describe layer and policy boundaries for tooltips, toasts, popovers, lightboxes, menus, dialogs and other overlay kinds. `openOverlay` places overlay instances in their portal and assigns a stable stack order through `zIndexStart` and `zStep`. `closeTopOverlay` closes the topmost dismissible overlay entry per portal or globally.
+
+The portal policy is generic:
+
+- `stacked` for normal app surfaces.
+- `modal` and `nonmodal` for blocking and non-blocking overlays.
+- `toast-region` for feedback layers.
+- `clipping-escape` for viewport-fixed layers such as tooltips.
+
+## Resource Ownership
+
+Resources are injected through the WP-E18-08 Resource Manager. The surface runtime has no own adapters, but calls `acquireMany` and `releaseOwner` per surface or overlay instance.
+
+This creates clear rules:
+
+- Minimize preserves resources and component state.
+- Close can optionally release resources.
+- Destroy releases resources of the affected instance.
+- Overlay close releases overlay resources.
+- Destroying a surface additionally calls `eventRuntime.detachOwner(owner)`.
+
+## Persistence
+
+`persistSnapshot` returns a snapshot with surface state, bounds, focus, open overlays and portal metadata. An optional persistence adapter can store this snapshot. `hydrateSnapshot` later plays it back into already materialized instances.
+
+## Boundaries
+
+- No product surface taxonomy as framework default.
+- No product-local registry repaint obligation.
+- No XTend component imports in the RMT kernel.
+- Normal UI stays with DOM descriptors and component templates; HTML string renderers remain a separate Trusted DOM boundary.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js rmt-surface-resource-graph-runtime --json
+node scripts/run_xtend_tests.js rmt-app-platform-authoring rmt-dom-descriptor-renderer rmt-component-template-primitives rmt-state-selector-runtime rmt-action-effect-runtime rmt-event-routing-runtime rmt-surface-resource-graph-runtime --json
+```
+
+`WP-E18-11` builds on this with Scaffold, linter, LSP and diagnostics so surface, overlay, portal and resource graphs become visible and checkable already during authoring.

package/docs/en/rmt-tooling-release-gates.md

@@ -0,0 +1,77 @@
+# RMT Tooling Release Gates
+
+- Status: productively prepared as of `WP-E14-15`
+- Contract: `xtend.epic14.rmt-tooling.v1`
+- Gate record contract: `xtend.epic14.rmt-tooling-gate.record.v1`
+- Report contract: `xtend.epic14.rmt-tooling-report.v1`
+- Local gate: `node scripts/run_xtend_tests.js epic14-rmt-tooling --json`
+
+## Purpose
+
+The RMT Tooling Gates bundle the native `.rmt` authoring path for pull requests, release candidates and AI agents. They do not check the RMT runtime, but the language layer: source model, parser, semantic graph, linter, CLI, completion, navigation, LSP, code actions, agent report, editor packaging, regression fixtures and documentation.
+
+## Commands
+
+```bash
+npm run test:rmt-linter
+npm run test:rmt-language-server
+npm run test:pr:rmt
+npm run test:pr:rmt:report
+npm run test:rmt-tooling
+npm run test:rmt-tooling:report
+node scripts/run_xtend_tests.js epic14-rmt-tooling --json
+```
+
+`npm run test:pr:rmt` is an optional add-on gate for RMT-close pull requests. The global PR gate stays lean, but can be extended specifically for DSL, linter, LSP or agent-report changes.
+
+`npm run test:rmt-tooling` is the release bundle gate for Epic 14. It runs without network access and uses only repo-local fixtures, docs and tooling modules.
+
+## Release Bundle
+
+The release bundle covers:
+
+- `rmt-source-model`
+- `rmt-parser`
+- `rmt-semantic-graph`
+- `rmt-linter-rules`
+- `rmt-linter-cli`
+- `rmt-completions`
+- `rmt-navigation`
+- `rmt-language-server`
+- `rmt-code-actions`
+- `rmt-agent-report`
+- `rmt-editor-packaging`
+- `rmt-language-regression`
+- `rmt-tooling-docs`
+
+## Package Surface
+
+The package surface for RMT tooling is exported through `package.json`. Especially relevant for tooling consumers are:
+
+- `xtend/rmt-language/source-model`
+- `xtend/rmt-language/parser`
+- `xtend/rmt-language/diagnostics`
+- `xtend/rmt-language/completions`
+- `xtend/rmt-language/code-actions`
+- `xtend/rmt-language-server`
+- `xtend/rmt-linter/cli`
+- `xtend/rmt-linter/reporter`
+- `xtend/rmt-language/snippets`
+
+The gate `epic14-rmt-tooling` checks that this surface does not drift unnoticed and that `xtend.epic14RmtTooling` contains the active scripts, suites and handoff metadata.
+
+## CI Handoff
+
+The global full release line remains:
+
+```bash
+npm run test:release:full:report
+```
+
+RMT Tooling is additionally registered as its own release gate in `xtend.releaseGates`:
+
+```bash
+npm run test:rmt-tooling
+```
+
+This lets release owners, CI systems and AI agents prove the RMT language tools separately without coupling the RMT kernel to XTend runtime types.

package/docs/en/rmt-vnext-authoring.md

@@ -0,0 +1,102 @@
+# RMT vNext Authoring Guide
+
+- Contract: `xtend.rmt.vnext-release-handoff.v1`
+- Syntax Contract: `xtend.rmt.vnext.grammar.v1`
+- Core Output: `xtend.rmt.core-format.vnext.v1`
+
+RMT vNext is the human-friendly syntax for XTend apps. You can write a complete UI shell in RMT: state, selectors, data sources, actions, events, portals, overlays, resources, surfaces, and Fabric lanes live in a single `.rmt` source and compile deterministically into Core and kernel records.
+
+## Basic Shape
+
+```rmt
+template media.manager {
+  state selectedItem type object initial null
+
+  selector visibleItems from datasource library {
+    output card-list
+  }
+
+  datasource library from fixture records.media-items {
+    contract "media.item.v1[]"
+  }
+
+  action select-item {
+    input id string
+    reduce state.selectedItem = input.id
+    emit media.item.selected with action select-item
+  }
+
+  portal app root "#app-root" layer surface
+
+  surface library kind workspace component x-cards {
+    repeat from selector visibleItems
+    key item.id
+    portal app
+
+    lane visible weight 80 {
+      hydrate x-cards from selector visibleItems
+    }
+
+    on card-click target item -> action select-item {
+      payload id from item.id
+    }
+  }
+}
+```
+
+## App Shell Only in RMT
+
+A vNext app should not split itself across RMT, App Platform JSON, and host code. RMT is the authoring place for route and shell structure, visible surfaces, overlay portals, state, selectors, actions, event payloads, resource ownership, cleanup, and Fabric lanes.
+
+The host provides components, router, browser APIs, and external data. This boundary keeps the kernel framework-neutral while still making the app fully describable.
+
+## XTend UI Compatibility
+
+RMT vNext Component Primitives target the existing XTend component stack. A
+surface such as `component x-select` lowers to a DOM descriptor and is then
+resolved through the Component Capability Registry, not through a product-
+specific renderer. The registry reads `components/manifest.json`,
+`xtendComponentContract`, `xtendRmtMetadata`, public events,
+`observedAttributes`, slots, parts, form association, accessibility profiles,
+and performance profiles.
+
+That gives RMT access to all 44 public manifest entries while keeping 40
+renderable UI components on their normal Web Component lifecycle. Infrastructure
+modules such as `x-theme` and `xstate` remain host services, not normal surface
+elements. Product code should bind through public attributes, properties,
+events, parts, slots, and state bridges instead of patching `shadowRoot` or
+private component maps.
+
+See [RMT vNext Component Primitives and XTend UI](./rmt-vnext-component-primitives.md).
+
+## Editor DX
+
+The Language Server understands vNext primitives directly:
+
+- completions for primitive keywords and clause-aware suggestions
+- hover with Core pointer and primitive information
+- document symbols for `states`, `selectors`, `actions`, `surfaces`, `portals`, `overlays`, and `resources`
+- code actions for safe repairs
+- safe fix-all for `source.fixAll.rmt.vnext.primitives`
+- manual handoffs for kernel and host boundaries
+
+The `rmt-vnext-primitive-shell` snippet creates a small app shell with state, selector, action, portal, surface, lane, and event payload contract.
+
+## Local Checks
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-parser rmt-vnext-compiler rmt-vnext-tooling --json
+node scripts/run_xtend_tests.js rmt-vnext-compatibility --json
+node scripts/run_xtend_tests.js rmt-vnext-component-primitives --json
+node scripts/run_xtend_tests.js rmt-vnext-release --json
+```
+
+## Boundaries
+
+- RMT vNext does not execute host runtime inside the kernel.
+- Conditions are declarative and allow no function calls.
+- Imports are static and stay package-root-bound.
+- Legacy JSON remains compatible, but it is not the preferred authoring path.
+- XTend, XRouter, DOM, and browser details belong in adapters.
+- XTend Component integration goes through public contracts and the Component
+  Capability Registry, not direct kernel imports or Shadow-DOM monkeypatching.

package/docs/en/rmt-vnext-component-primitives.md

@@ -0,0 +1,185 @@
+# RMT vNext Component Primitives and XTend UI
+
+- Schema: `xtend.rmt.component-capability-registry.v1`
+- Report schema: `xtend.rmt.component-capability-registry-report.v1`
+- Runtime: `xtendrmt/rmt-component-capability-registry.js`
+- Export: `@ccslabs/xtend/rmt/component-capability-registry`
+- Local gate: `node scripts/run_xtend_tests.js rmt-vnext-component-primitives --json`
+- Aggregate gate: `npm run test:rmt-vnext-primitives:report`
+
+RMT vNext and XTend UI are not parallel stacks. The Component Primitives connect
+RMT templates, kernel records, the DOM Descriptor Renderer, and the public XTend
+Web Components through one capability registry. RMT describes shell, state,
+surfaces, events, and lifecycle intent; XTend Components provide the concrete UI
+building blocks, accessibility profiles, parts, slots, events, and performance
+profiles.
+
+## Source-to-Sea Flow
+
+```text
+.rmt template
+  -> RMT compiler and Core records
+  -> Kernel records and Fabric lanes
+  -> DOM Descriptor Renderer
+  -> Component Capability Registry
+  -> XTend Component from components/manifest.json
+  -> Browser DOM and component lifecycle
+```
+
+The RMT kernel does not import XTend components or XTend types. The registry
+reads the manifest, Component Contracts, `xtendRmtMetadata`,
+`observedAttributes`, events, slots, parts, form association, accessibility
+profiles, and performance profiles. It normalizes those signals into one matrix
+for all 44 public entries in `components/manifest.json`.
+
+## Matrix
+
+| Area | Coverage |
+| --- | --- |
+| Manifest entries | 44 |
+| Renderable public UI components | 40 |
+| Non-visual special cases | 4 |
+| RMT metadata | 42 entries |
+| Component Contracts | 40 entries |
+| Form-associated components | 6 |
+
+The non-visual special cases are `x-theme`, `xstate`, `x-utils`, and
+`x-rmt-lifecycle-demo-build`. `x-theme` and `xstate` are infrastructure
+modules; hosts and loaders consume them as services, but normal RMT app UI does
+not render them as surface elements. `x-utils` remains a utility module, and
+the lifecycle demo build remains a demo artifact.
+
+## Component Families
+
+| Family | Tags |
+| --- | --- |
+| Form | `x-calendar`, `x-checkbox`, `x-form`, `x-input`, `x-radio`, `x-select`, `x-textarea` |
+| Navigation | `x-router`, `x-link`, `x-menu`, `x-drawer` |
+| Overlay/Surface | `x-dialog`, `x-lightbox`, `x-modal`, `x-popover`, `x-side-panel`, `x-surface-manager`, `x-surface-window`, `x-toast`, `x-tooltip` |
+| Media/Feedback/Layout | `x-alert`, `x-button`, `x-cards`, `x-code`, `x-icon`, `x-masonry`, `x-player`, `x-progress`, `x-spinner`, `x-status`, `x-summary`, `x-type`, `x-writer` |
+| Theme/Layout | `x-footer`, `x-header`, `x-hero`, `x-section`, `x-tabs` |
+| Infrastructure | `x-theme`, `xstate`, `x-utils`, `x-rmt-lifecycle-demo-build` |
+
+The higher-risk families `form`, `navigation`, `overlay-surface`,
+`media-feedback-layout`, and `theme-layout` stay marked for representative
+browser smokes. The default gate verifies the broad matrix in a fake-DOM runtime
+and keeps browser flakiness out of the fast primitive gate.
+
+## Runtime API
+
+```js
+import {
+  createRmtComponentCapabilityRegistry
+} from '@ccslabs/xtend/rmt/component-capability-registry';
+import {
+  createRmtDomDescriptorRenderer
+} from '@ccslabs/xtend/rmt/dom-descriptor-renderer';
+
+const registry = createRmtComponentCapabilityRegistry({
+  manifest,
+  sourceTexts,
+  importer: async (modulePath) => import(`/components/${modulePath.replace(/^\.\//u, '')}`)
+});
+
+const descriptor = registry.buildComponentDescriptor({
+  tag: 'x-select',
+  id: 'plan-select',
+  key: 'settings:plan',
+  attributes: {
+    name: 'plan',
+    value: 'pro'
+  },
+  slots: {
+    label: { text: 'Plan' }
+  },
+  events: {
+    'select-changed': 'settings.plan.changed'
+  }
+});
+
+const renderer = createRmtDomDescriptorRenderer({ documentTarget: document });
+
+renderer.renderKeyed(root, [descriptor], {
+  componentRegistry: registry,
+  dispatchEvent(event) {
+    actions.dispatch(event.action, event.payload);
+  },
+  stateBridge: {
+    read(key) {
+      return state.read(key);
+    },
+    write(key, value) {
+      state.write(key, value);
+    }
+  }
+});
+```
+
+Key registry functions:
+
+| Function | Purpose |
+| --- | --- |
+| `resolveComponentCapability(tag)` | Returns normalized capabilities for a manifest tag. |
+| `listCapabilities(filter)` | Lists capabilities by family or visual kind. |
+| `buildComponentDescriptor(input)` | Builds a DOM descriptor for an XTend component with capability markers. |
+| `bindComponentInstance(element, binding, options)` | Connects events, form state, and the state bridge through public DOM APIs. |
+| `ensureComponentLoaded(tag, options)` | Runs lazy import through an explicit importer. |
+| `createMatrixReport()` | Creates the compatibility report for CI and local diagnosis. |
+
+## Event and State Bridge
+
+Form controls provide `value`, `checked`, `validity`, `dataset`, and file
+metadata in the safe payload record `xtend.rmt.component-event-payload.v1`.
+For form families, `input` and `change` are inferred when no explicit event
+binding is present.
+
+Navigation, overlays, feedback, and layout components are also connected through
+public events and properties. Product code does not need to reach into
+`shadowRoot`, read private component maps, or add component-specific renderers.
+
+## Renderer Integration
+
+The DOM Descriptor Renderer accepts `componentRegistry` in `render(...)` and
+`renderKeyed(...)`. For `type: "component"`, the registry normalizes tag,
+attributes, properties, slots, parts, and event bindings. Keyed reuse remains
+intact, and unkeyed repeat UI remains diagnosable.
+
+Normal RMT app UI does not use HTML sinks. `innerHTML`, `outerHTML`,
+`insertAdjacentHTML`, `document.write`, `createContextualFragment`, unsafe URLs,
+and inline event sinks stay blocked by the No-Manual-HTML gate and the Trusted
+DOM Boundary.
+
+## Architecture Rules
+
+- Component Contracts remain the source of truth.
+- RMT extends XTend UI through metadata and runtime bridges, not monkeypatching.
+- Lazy import runs only through the manifest and explicit importers.
+- The RMT kernel stays framework-neutral and imports no XTend types.
+- Overlays, surfaces, and portals need resource ownership and cleanup.
+- `x-player` uses the public Player Contract for play/pause, state bridge,
+  theme tokens, and parts; product code does not patch Shadow DOM.
+- Infrastructure modules such as `x-theme` and `xstate` are consumed as
+  services, not rendered as normal surface elements.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-component-primitives --json
+npm run test:rmt-vnext-primitives:report
+node scripts/run_xtend_tests.js component-ux-browser-smokes --json
+node scripts/run_xtend_tests.js type-exports-rmt --json
+```
+
+The fast primitive gate verifies the registry, matrix, renderer binding,
+package exports, type declarations, lazy import, state roundtrip, and negative
+boundaries against Shadow-DOM patches, manual HTML sinks, and direct component
+imports.
+
+## Related Docs
+
+- [RMT vNext Authoring Guide](./rmt-vnext-authoring.md)
+- [RMT DOM Descriptor Renderer](./rmt-dom-descriptor-renderer.md)
+- [RMT Component Template Primitives](./rmt-component-template-primitives.md)
+- [XTend Components](./components.md)
+- [Component Platform](./component-platform.md)
+- [XTend-Fabric RMT Lane Mapping](./xtend-fabric-rmt-lane-mapping.md)