@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/supply-chain-gates.md

@@ -0,0 +1,106 @@
+# XTend Supply-Chain Gates
+
+- Status: active since `ER-WP-30`
+- Docs Contract: `xtend.docs.supply-chain-gates.v1`
+- Supply-Chain Contract: `xtend.security.supply-chain-gate-plan.v1`
+- Dependency Audit Gate: `xtend.security.dependency-audit-gate.v1`
+- License Policy: `xtend.security.license-policy.v1`
+- Vulnerability Policy: `xtend.security.vulnerability-policy.v1`
+- Release Gate: `xtend.security.release-supply-chain-gate.v1`
+
+## Overview
+
+XTend is prepared for RC1 publish prep as a scoped public package surface.
+Supply-chain gates control dependencies, licenses, vulnerabilities, SBOM,
+provenance, and the installable package surface.
+
+The local default path is offline and reproducible. It does not query the npm
+registry.
+
+## Local Checks
+
+```bash
+node scripts/verify_supply_chain_policy.js --json
+node scripts/run_xtend_tests.js supply-chain --json
+npm run test:supply-chain
+```
+
+The verifier checks:
+
+- `private: false` for RC1 publish prep
+- `license: "Apache-2.0"` for the full XTend stack
+- `publishConfig.provenance = true`
+- export of `security/supply-chain-gate-policy.js`
+- release gate metadata in `package.json`
+- dependency inventory and lockfile requirement
+
+## CI and Release Stages
+
+These commands are planned for CI and release automation:
+
+```bash
+npm audit --audit-level=moderate
+npm sbom --sbom-format=cyclonedx --json
+npm run release:report
+npm run pack:dry-run
+```
+
+`npm audit` and `npm sbom` may need network access. They therefore do not
+belong to the local default test, but to controlled CI/release stages.
+
+## License Policy
+
+The full XTend stack is set to `Apache-2.0`. For RC1 publish prep,
+`private: false` is set; the actual `npm publish` remains a separate owner
+step.
+
+The scoped release manifests are part of the supply-chain gate:
+
+| Package | Manifest |
+|---------|----------|
+| `@ccslabs/xtend` | `package.json` |
+| `@ccslabs/xtend-rmt` | `xtendrmt/package.json` |
+| `@ccslabs/xtend-fabric` | `fabric/package.json` |
+| `@ccslabs/xtend-cli` | `xtend-builder/package.json` |
+| `@ccslabs/xtend-compiler` | `tools/package.json` |
+
+A public release first needs:
+
+- confirmed Apache-2.0 license decision
+- dependency license inventory
+- review of all non-permissive dependency licenses
+- exclusion of AGPL/GPL/UNLICENSED as default third-party dependencies
+
+## Vulnerability Policy
+
+- `critical` blocks every release.
+- `high` blocks release candidates.
+- Production findings from `moderate` upward must be triaged.
+- Known exploits must not remain in release candidates.
+
+## Machine-Readable Policy
+
+```js
+const {
+  createSupplyChainGatePlan,
+  classifyPackageSupplyChain
+} = require('./security/supply-chain-gate-policy');
+```
+
+The policy itself lives in:
+
+```text
+security/supply-chain-gate-policy.js
+```
+
+The local report uses:
+
+```text
+xtend.security.supply-chain-report.v1
+```
+
+## Related Documents
+
+- [XTend Loader](./xtend-loader.md)
+- [Trusted DOM and Sanitizing](./trusted-dom-sanitizing.md)
+- [XTend Fabric Runtime](./xtend-fabric.md)

package/docs/en/surface-manager-authoring-guide.md

@@ -0,0 +1,94 @@
+# SurfaceManager Authoring Guide
+
+- Contract: `xtend.surface.release-handoff.v1`
+- Workpackage: `WP-SM-09`
+- Fixture: `tests/fixtures/rmt-surface-manager-component-lab.rmt`
+- Local gate: `node scripts/run_xtend_tests.js surface-release-handoff --json`
+
+## Goal
+
+This guide describes the recommended authoring path for XTend app shells with SurfaceManager. It connects the early component-metadata path from `WP-SM-01` with the native RMT `surfaces` domain from `WP-SM-08`.
+
+## Authoring Modes
+
+| Mode | When to use | Source |
+|------|-------------|--------|
+| `component-metadata-mvp` | small shells, existing component records, fast migration | `components[*].metadata.surface` |
+| `dual-record-handoff` | transition, tooling comparison, regression against existing runtime | `components[*].metadata.surface` plus `surfaces[*]` |
+| `native-surfaces-preferred` | complex app shells, multi-window, panels, overlay stack | `surfaces[*]` as domain surface source |
+
+## Component Metadata Remains Valid
+
+Existing RMT component records remain compatible:
+
+```json
+{
+  "id": "workbench.inspector",
+  "kind": "custom_element",
+  "adapter": "xtend.component",
+  "tag": "x-surface-window",
+  "schedule": "surface.user-blocking.open",
+  "metadata": {
+    "surface": {
+      "schema": "xtend.surface.record.v1",
+      "id": "surface.inspector",
+      "type": "window",
+      "manager": "workbench.manager",
+      "stateKey": "xtend.surface.inspector.state"
+    }
+  }
+}
+```
+
+This mode is enough when an app shell already runs correctly through `x-surface-manager` and does not need the native RMT surface domain for tooling, migration or cross-record validation.
+
+## Prefer Native Surfaces
+
+For new complex shells, `surfaces[*]` is the target state:
+
+```json
+{
+  "id": "surface.inspector",
+  "schema": "xtend.surface.record.v1",
+  "type": "window",
+  "adapter": "xtend.surface",
+  "manager": "workbench.manager",
+  "component": "workbench.inspector",
+  "route": "workbench",
+  "schedule": "surface.user-blocking.open",
+  "stateKey": "xtend.surface.inspector.state"
+}
+```
+
+Authoring rules:
+
+- `manager` references the `x-surface-manager` component record.
+- `component` references the visible surface component.
+- `route` binds the surface to the app-shell context.
+- `schedule` binds open, layout, persistence or diagnostics to RMT scheduling.
+- `stateKey` remains stable between component metadata and native domain.
+- Historically, `xtend.surface` stayed an adapter handoff until `WP-SM-19`; since the runtime handoff, the productive adapter claim is gateable while the visible UI continues to materialize through the SurfaceManager component family.
+
+## Release Handoff
+
+After `WP-SM-09`, the historical authoring handoff stated:
+
+- component metadata is the stable compatibility path.
+- native `surfaces[*]` is the preferred authoring path for new app shells.
+- dual records are the safe migration mode.
+- the RMT kernel remains host-neutral.
+- the productive `xtend.surface` adapter runtime was follow-up work and has been implemented since `WP-SM-19`.
+
+## WP-SM-19 Runtime Authoring
+
+As of `WP-SM-19`, the productive `xtend.surface` adapter runtime is implemented and gateable through `xtend.surface.runtime-release-handoff.v1`. For new complex app shells, `native-surfaces-preferred` remains the default: `surfaces[*]` describes domain surfaces, while component records provide the visible XTend UI bindings.
+
+Productive authoring rules:
+
+- `surfaces[*]` is the source for new multi-surface app shells.
+- `components[*].metadata.surface` remains compatible for existing shells and dual-record migrations.
+- `x-surface-manager` and the SurfaceController remain the runtime registry.
+- Fabric, XRouter, `xstate` and the RMT kernel remain independent layers.
+- `node scripts/run_xtend_tests.js surface-runtime-release-handoff --json` checks the final runtime handoff.
+
+Details are in [SurfaceManager Runtime Release Handoff](./surface-manager-runtime-release-handoff.md).

package/docs/en/surface-manager-browser-lab.md

@@ -0,0 +1,45 @@
+# SurfaceManager Browser Lab
+
+`WP-SM-18` adds a browser-close lab to the SurfaceManager layer for real app-shell stability. The contract `xtend.surface.browser-lab.v1` intentionally stays framework-native: the fixture uses `x-surface-manager`, `x-surface-window`, `x-side-panel`, `x-modal`, the `SkeletonLoader` from the loader and the existing surface hydration. It is not a Docs-app special case and not a monkeypatch.
+
+## Artifacts
+
+| Artifact | Path |
+| --- | --- |
+| Catalog | `catalog/surface-manager-browser-lab.js` |
+| Browser-lab fixture | `tests/browser/fixtures/surface-manager-browser-lab.html` |
+| Visual baseline | `tests/browser/visual-baselines/surface-manager-browser-lab.dom-baseline.json` |
+| Gate | `node scripts/run_xtend_tests.js surface-browser-lab --json` |
+
+The visual baseline uses `xtend.surface.browser-lab.visual-baseline.v1`. It is JSON-based and pixel-ready: later browser-lab runs can attach real snapshot files, while the local fast gate already checks DOM signatures, states and budgets.
+
+## Gate States
+
+The fixture covers five reproducible states:
+
+| Snapshot | State |
+| --- | --- |
+| `surface-lab-cold-start` | app shell visible before content hydration |
+| `surface-lab-skeleton` | Parsedown content hidden behind SkeletonLoader |
+| `surface-lab-hydrated` | content released, skeleton removed |
+| `surface-lab-route-change` | route-bound surface without shell resize |
+| `surface-lab-modal-stack` | modal stack above SurfaceManager policy |
+
+## Regressions
+
+The report connects `xtend.surface.browser-lab.performance-report.v1` and `xtend.surface.browser-lab.cls-report.v1`. Locally, these risks must fail:
+
+| Risk | Budget |
+| --- | --- |
+| CLS | `<= 0.01` |
+| Layout shift | `<= 1px` |
+| Pop-in of unstyled content | `0` |
+| Open/Focus | `<= 16ms` |
+| Route | `<= 32ms` |
+| Hydrate | `<= 120ms` |
+
+## App-Shell Probes
+
+The lab references the Docs app through `docs/index.php` and the Parsedown/RMT pilot `docs/xtendrmt-parsedown-docs.rmt`. `tests/browser/fixtures/rmt-surface-workbench-smoke.html` also remains a reference workbench in the gate. This lets WP-SM-18 check the production-close app-shell path without moving Parsedown, PHP or workbench-specific behavior into the SurfaceManager.
+
+The SurfaceManager remains a supporting XTend UI layer. It does not create a second registry, replace Fabric or the RMT kernel, or load a remote runtime in the kernel.

package/docs/en/surface-manager-component-lab.md

@@ -0,0 +1,43 @@
+# SurfaceManager Component Lab
+
+- Contract: `xtend.surface.component-lab-fixture.v1`
+- Release contract: `xtend.surface.release-handoff.v1`
+- Fixture: `tests/fixtures/rmt-surface-manager-component-lab.rmt`
+- Gate: `node scripts/run_xtend_tests.js surface-release-handoff --json`
+
+## Purpose
+
+The SurfaceManager Component Lab is the static lab fixture for the SurfaceManager line. It shows how an app shell is described with `x-surface-manager`, `x-surface-window`, `x-side-panel`, a compatible dialog and native `surfaces[*]` records.
+
+The fixture is not a new lab server. It extends the existing Component Lab idea with a surface-specific authoring and migration view.
+
+## Panels
+
+| Panel | Task |
+|-------|------|
+| `surface-preview` | check the visible surface shell with WindowManager and SidePanel components |
+| `native-rmt-inspector` | inspect `surfaces[*]`, `adapters`, `components`, `routes` and `schedules` |
+| `migration-diff` | compare `components[*].metadata.surface` with native surface records |
+| `quality-gates` | make the gate chain from `surface-manager-quality` to `surface-native-rmt` visible |
+| `source-links` | link docs, catalog, fixture, runtime and suite paths |
+
+## Fixture Model
+
+`tests/fixtures/rmt-surface-manager-component-lab.rmt` contains:
+
+- four adapters: `xtend.component`, `xtend.xrouter`, `rmt.state-scheduler-diagnostics`, `xtend.surface`
+- one SurfaceManager component `surface.lab.manager`
+- two windows: `surface.lab.preview` and `surface.lab.rmtInspector`
+- two side panels: `surface.lab.migrationPanel` and `surface.lab.qualityPanel`
+- one dialog: `surface.lab.commandDialog`
+- native `surfaces[*]` records plus matching `components[*].metadata.surface` dual records
+
+The fixture checks the authoring boundary. It does not claim a productive `xtend.surface` runtime.
+
+## Local Flow
+
+```bash
+node scripts/run_xtend_tests.js surface-release-handoff --json
+```
+
+The gate validates the fixture through RMT normalization and semantic graph. Surface IDs, component refs, manager refs, routes and schedules therefore remain visible and machine-checkable.

package/docs/en/surface-manager-controller.md

@@ -0,0 +1,66 @@
+# SurfaceManager Controller
+
+`WP-SM-02` introduces the internal Surface Controller for XTend. It is the runnable foundation for multi-window UIs, but not yet a visible custom element.
+
+- Contract: `xtend.surface.controller.v1`
+- Runtime: `components/xsurfacemanager-controller.js`
+- Types: `components/xsurfacemanager-controller.d.ts`
+- Snapshot: `xtend.surface.snapshot.v1`
+- Gate: `node scripts/run_xtend_tests.js surface-controller --json`
+
+## Role
+
+The controller manages surface records from the `WP-SM-01` authoring model. RMT can therefore continue to describe normal component records with `metadata.surface`; the controller normalizes these records into a runtime registry.
+
+It is intentionally `controller-only-no-custom-element`. `WP-SM-03` builds `x-surface-manager` and `x-surface-window` on top of it.
+
+## API
+
+Important methods:
+
+```js
+const {
+  createSurfaceController
+} = require('./components/xsurfacemanager-controller.js');
+
+const controller = createSurfaceController({
+  managerId: 'workbench.manager',
+  xstate,
+  fabric
+});
+
+controller.registerSurface(surfaceRecord);
+controller.openSurface('workbench.inspector');
+controller.focusSurface('workbench.inspector');
+controller.moveSurface('workbench.inspector', { x: 128, y: 96 });
+controller.resizeSurface('workbench.inspector', { width: 700, height: 460 });
+controller.closeSurface('workbench.inspector');
+
+const snapshot = controller.snapshot();
+```
+
+Supported methods are `registerSurface`, `openSurface`, `closeSurface`, `focusSurface`, `updateSurface`, `moveSurface`, `resizeSurface`, `minimizeSurface`, `maximizeSurface`, `restoreSurface`, `snapshot` and `dispose`.
+
+## State
+
+After every commit, the controller mirrors:
+
+```text
+xtend.surface.registry
+xtend.surface.active
+xtend.surface.<surfaceId>.state
+xtend.surface.<surfaceId>.bounds
+xtend.surface.<surfaceId>.lifecycle
+xtend.surface.diagnostics
+xtend.surface.snapshot
+```
+
+The snapshot contains only layout, lifecycle and UI state. Raw metadata, DOM nodes and content payloads are not serialized.
+
+## Diagnostics
+
+If Fabric is passed in, the controller sends `xtend.surface.diagnostic.v1` events through `emitDiagnostic`. Without Fabric, the controller remains runnable and mirrors diagnostics to xstate.
+
+## Next Step
+
+`WP-SM-03` should build the visible component family on this controller: `x-surface-manager`, `x-surface-window`, first layer containers, events and real window chrome.

package/docs/en/surface-manager-layout-engines.md

@@ -0,0 +1,32 @@
+# SurfaceManager Layout Engines
+
+As of `WP-SM-16`, `x-surface-manager` owns the `xtend.surface.layout-engine.v1` contract for visible, snapshot-compatible surface layouts.
+
+## Engines
+
+| Engine | Purpose |
+|--------|---------|
+| `freeform` | free windows with viewport clamp, snap and simple collision correction |
+| `docked` | side panels and docked surfaces occupy edges; workspace surfaces fill the rest |
+| `split` | open layout surfaces are distributed as split panes |
+| `tile` | open layout surfaces are distributed in a grid |
+| `stacked` | open layout surfaces are shown as an offset stack and used as compact fallback |
+
+## Runtime
+
+- `snapshotSurfaceLayout()` returns `xtend.surface.layout-engine-report.v1`.
+- `applyLayoutEngine(engine)` writes calculated bounds through the existing SurfaceController into the snapshot.
+- `dockSurface()` sets placement/mode and visibly applies a docked or currently active layout engine.
+- `undockSurface()` sets a surface to `floating` and lets it run in freeform mode again.
+- `surface-layout-gap` and `surface-layout-snap` control spacing and the snap grid.
+- compact viewports fall back to `stacked`.
+
+## Boundary
+
+The layout engine remains an XTend UI support layer. The SurfaceController remains the registry and snapshot source, Fabric remains responsible for diagnostics/backpressure, and the RMT kernel imports no XTend types. No second registry is created.
+
+Local gate:
+
+```bash
+node scripts/run_xtend_tests.js surface-layout-engines --json
+```

package/docs/en/surface-manager-lazy-hydration.md

@@ -0,0 +1,63 @@
+# SurfaceManager Lazy Hydration
+
+Docs contract: `xtend.docs.surface-manager-lazy-hydration.v1`
+
+`WP-SM-13` hardens `x-surface-manager` for shell-first apps: surface chrome and app shell can become visible immediately while surface content is skeletonized, loaded and hydrated through the framework-native XTendLoader.
+
+## Contract
+
+- Loading policy: `xtend.surface.loading-policy.v1`
+- Loading report: `xtend.surface.loading-report.v1`
+- Gate: `node scripts/run_xtend_tests.js surface-lazy-hydration --json`
+- Package script: `npm run test:surface-lazy-hydration`
+
+## Policies
+
+`surface-loading-policy` on the manager sets the default policy. Individual surfaces can override it with `data-surface-hydration-policy`.
+
+| Policy | Behavior |
+|--------|----------|
+| `eager` | content is hydrated directly after surface registration |
+| `visible` | content is hydrated as soon as the surface is visible |
+| `open` | content is hydrated when the surface is open |
+| `idle` | content is loaded through `requestIdleCallback` or timeout fallback |
+| `route` | content waits for route signals such as `xtend-route-changed` |
+
+## Runtime
+
+`x-surface-manager` uses no Docs-app special case. The runtime uses the existing loader APIs:
+
+- `XTendLoader.ensureComponent`
+- `XTendLoader.hydrateTree`
+- `XTendLoader.showSkeleton`
+- `XTendLoader.hideSkeleton`
+- `XTendStyleRegistry.ensureRuntimeStyles`
+
+Before hydration, the manager sets `data-xtend-surface-content-ready="false"` and lets the SkeletonLoader cover direct content children. Only after a successful component-ready and `hydrateTree` gate is the skeleton removed. On errors or timeouts, the skeleton remains active so unstyled content does not pop in.
+
+## Parsedown and Remote Slots
+
+Parsedown containers and remote-capable slots are normal surface content. There is no monkeypatch in the Docs app:
+
+```html
+<x-surface-window
+  surface-id="docs.surface"
+  data-surface-hydration-policy="open"
+  open>
+  <section data-xtend-parsedown-container="true">
+    <x-code language="markdown"># Docs</x-code>
+  </section>
+</x-surface-window>
+```
+
+Remote-capable slots can be marked with `data-remote-capable-content-slot="true"`. Lazy hydration loads only the DOM/component scope; remote trust, ownership and capabilities remain reserved for later remote-surface policies.
+
+## Diagnostics
+
+The manager provides:
+
+- `snapshotSurfaceLoading()`
+- `hydrateSurfaceContent(surfaceRef, options)`
+- events `surface-content-loading`, `surface-content-hydrated`, `surface-content-hydration-skipped` and `surface-content-hydration-error`
+
+`snapshotSurfaceLoading()` reports policy, skeleton status, hydration status, tags, unresolved tags, duration and the boundaries `shellFirst`, `protectsUnstyledContent` and `createsSecondRegistry: false`.

package/docs/en/surface-manager-migration-guide.md

@@ -0,0 +1,113 @@
+# SurfaceManager Migration Guide
+
+- Contract: `xtend.surface.release-handoff.v1`
+- Native Domain: `xtend.rmt.surfaces-domain.v1`
+- Adapter Handoff: `xtend.surface.adapter.v1`
+- Gate: `node scripts/run_xtend_tests.js surface-release-handoff --json`
+
+## Goal
+
+This guide describes the additive migration from surface metadata in component records to native RMT surface records. The migration intentionally avoids a big bang: existing `components[*].metadata.surface` records remain valid while new app shells are authored in RMT vNext. `surfaces[*]` is the runtime and compatibility output, not the new manual authoring surface.
+
+## Migration Steps
+
+| Step | Result |
+|------|--------|
+| `inventory-component-metadata-surfaces` | capture all existing `metadata.surface` records and state keys |
+| `stabilize-surface-ids-and-state-keys` | freeze IDs, `type`, `manager` and `stateKey` |
+| `add-native-surfaces-records` | add parallel `surfaces[*]` records with the same identity |
+| `keep-dual-records-during-handoff` | compare component metadata and native records in the gate |
+| `switch-authoring-default-to-vnext-surfaces` | write new complex shells as `surface ... component ...` in RMT vNext |
+| `close-xtend-surface-runtime-after-adapter-implementation` | close the historical adapter handoff from `WP-SM-09` through `WP-SM-19` runtime gates |
+
+## vNext Target Shape
+
+```rmt
+template workbench.surfaceMigration {
+  state workbench.properties type object initial null
+
+  portal surface.root root "#workbench-root" layer surface
+
+  surface surface.properties kind side-panel component x-side-panel {
+    source state workbench.properties
+    portal surface.root
+
+    lane visible weight 70 {
+      hydrate properties-panel from state workbench.properties
+    }
+  }
+}
+```
+
+## Before: Legacy Component Metadata
+
+```json
+{
+  "id": "workbench.properties",
+  "tag": "x-side-panel",
+  "metadata": {
+    "surface": {
+      "schema": "xtend.surface.record.v1",
+      "id": "surface.properties",
+      "type": "side-panel",
+      "manager": "workbench.manager",
+      "stateKey": "xtend.surface.properties.state"
+    }
+  }
+}
+```
+
+## After: Dual Record as Runtime Output
+
+```json
+{
+  "surfaces": [
+    {
+      "id": "surface.properties",
+      "schema": "xtend.surface.record.v1",
+      "type": "side-panel",
+      "adapter": "xtend.surface",
+      "manager": "workbench.manager",
+      "component": "workbench.properties",
+      "route": "workbench",
+      "schedule": "surface.visible.render",
+      "stateKey": "xtend.surface.properties.state"
+    }
+  ]
+}
+```
+
+During the handoff, the component metadata remains in the component record and can optionally point to the native record with `nativeRecord`. New examples should show the vNext target shape; dual records serve as migration evidence.
+
+## Review Checklist
+
+- Every native surface has a stable `id`.
+- `component` points to exactly one component record.
+- `manager` points to the `x-surface-manager` record.
+- `route` and `schedule` resolve to native RMT records.
+- `stateKey` is identical between `components[*].metadata.surface` and `surfaces[*]`.
+- `xtend.surface` is declared as `surface_adapter` and has been promoted for production through the runtime gates since `WP-SM-19`.
+- The gates `surface-native-rmt`, `surface-release-handoff` and `surface-runtime-release-handoff` are green.
+
+Details for the generic RMT migration are in [XTendRMT Native Migration Guide](./xtendrmt-migration-guide.md). Surface authoring details are in [SurfaceManager Authoring Guide](./surface-manager-authoring-guide.md).
+
+## WP-SM-19 Runtime Migration Notes
+
+`WP-SM-19` accepts `xtend.surface.runtime-migration-notes.v1` as the final migration line for the production Surface Runtime.
+
+Extended gate order for migrations:
+
+```bash
+node scripts/run_xtend_tests.js surface-adapter-runtime --json
+node scripts/run_xtend_tests.js surface-native-materialization --json
+node scripts/run_xtend_tests.js surface-persistence --json
+node scripts/run_xtend_tests.js surface-lazy-hydration --json
+node scripts/run_xtend_tests.js surface-route-lifecycle --json
+node scripts/run_xtend_tests.js surface-stack-policy --json
+node scripts/run_xtend_tests.js surface-layout-engines --json
+node scripts/run_xtend_tests.js surface-remote-policy --json
+node scripts/run_xtend_tests.js surface-browser-lab --json
+node scripts/run_xtend_tests.js surface-runtime-release-handoff --json
+```
+
+Existing `components[*].metadata.surface` records remain allowed. The target state for new shells is still RMT vNext; `surfaces[*]` remains the verifiable output because tooling, materialization, persistence, routing, remote policy and browser-lab stability can be verified together there.

package/docs/en/surface-manager-native-rmt-surfaces.md

@@ -0,0 +1,38 @@
+# SurfaceManager Native RMT Surfaces
+
+`WP-SM-08` introduces `xtend.rmt.surfaces-domain.v1` and the adapter handoff `xtend.surface.adapter.v1`.
+
+## Local Gate
+
+```bash
+node scripts/run_xtend_tests.js surface-native-rmt --json
+npm run test:surface-native-rmt
+```
+
+## Domain
+
+`surfaces` is an optional top-level domain in `.rmt` documents. A surface record continues to reference normal RMT domains:
+
+- `adapter`: `xtend.surface`
+- `manager`: `x-surface-manager` component record
+- `component`: visible surface component, for example `x-surface-window`, `x-side-panel`, `x-modal`, `x-dialog` or `x-drawer`
+- `route`: route record
+- `schedule`: schedule record
+
+The fixture `tests/fixtures/rmt-surface-native-domain.rmt` shows six surface records: two windows, one side panel, modal, dialog and drawer.
+
+## Adapter
+
+`xtend.surface` can be registered as a `surface_adapter`. In `WP-SM-08`, `runtimeImplemented: false` was intentional and the adapter remained a handoff contract. Since `WP-SM-19`, the productive runtime line is gateable in the [SurfaceManager Runtime Release Handoff](./surface-manager-runtime-release-handoff.md): the runtime consumes `surfaces[*]`, calls the SurfaceController and keeps DOM, xstate and Fabric outside the RMT kernel.
+
+## Migration
+
+Existing component records with `metadata.surface` remain valid. New native records can be maintained in parallel as long as `id`, `type`, `manager`, `component`, `route`, `schedule` and `stateKey` stay aligned.
+
+## Tooling
+
+Schema, type artifact, normalizer, semantic graph, completion provider and linter understand `surfaces`. This allows the Language Server to reference surface records and offer completion for `surfaces[*].component`, `surfaces[*].adapter`, `surfaces[*].route`, `surfaces[*].schedule` and `surfaces[*].type`.
+
+## Handoff
+
+`WP-SM-09` finalizes docs, Component Lab and migration guide on this contract base. The closure is in [SurfaceManager Release Handoff](./surface-manager-release-handoff.md) (`docs/surface-manager-release-handoff.md`) and is checked through `node scripts/run_xtend_tests.js surface-release-handoff --json`.

package/docs/en/surface-manager-overlay-bridge.md

@@ -0,0 +1,53 @@
+# SurfaceManager Overlay Bridge
+
+`WP-SM-06` introduces `xtend.surface.overlay-stack-bridge.v1`. The bridge makes `x-modal`, `x-dialog` and `x-drawer` optionally compatible with the `x-surface-manager` surface stack.
+
+## What Changes
+
+`x-surface-manager` now also registers these elements in the `overlays` slot:
+
+- `x-modal` as surface type `modal`
+- `x-dialog` as surface type `dialog`
+- `x-drawer` as surface type `drawer`
+
+Existing overlay APIs remain available. A modal can still be controlled through `open()` and `close()`, and a drawer through `openDrawer()` and `closeDrawer()`. The legacy events `modal-opened`, `dialog-opened` and `drawer-opened` remain visible.
+
+## Command Bridge
+
+Overlays can use a `surface-overlay-command` event inside the manager:
+
+```js
+manager.dispatchEvent(new CustomEvent('surface-overlay-command', {
+  bubbles: true,
+  composed: true,
+  detail: {
+    surfaceId: 'settings.dialog',
+    command: 'open'
+  }
+}));
+```
+
+Supported commands are the existing surface operations such as `open`, `close`, `focus` and `update`. The manager uses the same controller stack as windows and side panels.
+
+## Stack Behavior
+
+The bridge mirrors the surface snapshot into overlay CSS custom properties:
+
+- `--surface-overlay-z`
+- `--surface-overlay-backdrop-z`
+
+Outside a SurfaceManager, `x-modal`, `x-dialog` and `x-drawer` keep their previous default z-indices.
+
+## RMT and Lifecycle
+
+At this stage, RMT remains on `xtend.component`. The bridge internally creates `xtend.surface.record.v1`, but it does not yet activate a native `xtend.surface` domain.
+
+The local gate:
+
+```bash
+node scripts/run_xtend_tests.js surface-overlay-bridge --json
+```
+
+## Boundary
+
+`WP-SM-06` prepares stack compatibility. Browser, a11y, performance and visual smokes follow in `WP-SM-07`; the native RMT `surfaces` domain follows later in `WP-SM-08`.