@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

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

@@ -0,0 +1,30 @@
+# SurfaceManager Persistence
+
+`x-surface-manager` can save surface layouts under a `restore-key` and restore them through the SurfaceController on the next start.
+
+## Attributes
+
+| Attribute | Values | Purpose |
+| --- | --- | --- |
+| `restore-key` | string | Stable key for the app-shell layout |
+| `persistence-mode` | `none`, `memory`, `session`, `local` | Storage backend for snapshots |
+| `restore-policy` | `auto`, `manual`, `reset` | Auto-restore on connect or manual control |
+
+Without `restore-key`, persistence stays disabled. With `restore-key` and no explicit `persistence-mode`, the runtime uses `session`.
+
+## API
+
+- `snapshotPersistence()` returns the active persistence contract.
+- `persistSnapshot(snapshot, options)` stores a layout-only snapshot.
+- `restorePersistedSnapshot(options)` reads and hydrates a stored snapshot.
+- `clearPersistedSnapshot(options)` removes the stored snapshot.
+- `resetSurfaceLayout(options)` clears persistence and registers the declared surface elements again.
+
+The stored format is `xtend.surface.persisted-snapshot.v1`. Content payloads are not persisted; surface IDs, bounds, stack, active surface, panel modes, status and content refs are preserved.
+
+## Boundaries
+
+- The SurfaceController remains the only source of registry truth.
+- Restore runs through controller operations, not by directly mutating a second registry.
+- Invalid or incompatible snapshots lead to a controlled skip with diagnostics.
+- The RMT kernel imports no XTend components.

package/docs/en/surface-manager-quality-gates.md

@@ -0,0 +1,51 @@
+# SurfaceManager Quality Gates
+
+`WP-SM-07` introduces `xtend.surface.quality-gates.v1`. The gate checks the SurfaceManager across four domains: browser, a11y, performance and visual.
+
+## Local Gates
+
+```bash
+node scripts/run_xtend_tests.js surface-manager-quality --json
+node scripts/run_xtend_tests.js surface-manager-browser --json
+node scripts/run_xtend_tests.js surface-manager-a11y --json
+node scripts/run_xtend_tests.js surface-manager-performance --json
+node scripts/run_xtend_tests.js surface-manager-visual --json
+```
+
+The domain gates run through the same contract and can be referenced specifically in local checks or CI matrices.
+
+## Browser
+
+The fixture `tests/browser/fixtures/surface-manager-quality-smoke.html` builds a mixed surface UI:
+
+- two `x-surface-window`
+- one `x-side-panel`
+- one `x-modal`
+- one `x-dialog`
+- one `x-drawer`
+
+Overlays are opened through `surface-overlay-command` and added to the same surface stack.
+
+## A11y
+
+The gate checks contract and fixture signals for:
+
+- roles: `application`, `dialog`, `complementary`
+- `aria-live` status
+- focus restore
+- Escape topmost behavior
+- Tab focus trap
+- reduced motion
+- forced colors and visible focus
+
+## Performance
+
+The contract defines budgets for open/close, focus, layout transition, snapshot and registration. The browser fixture additionally sets the performance measurement `surface-quality-open-close`.
+
+## Visual
+
+The DOM baseline `tests/browser/visual-baselines/surface-manager-quality.dom-baseline.json` covers desktop, mobile, topmost overlay and forced colors. It intentionally remains JSON-only so the local gate can run stably without browser pixel diff.
+
+## Handoff
+
+`WP-SM-08` can build on the quality gates and validate the native RMT `surfaces` domain against the same visible stack states.

package/docs/en/surface-manager-release-handoff.md

@@ -0,0 +1,68 @@
+# SurfaceManager Release Handoff
+
+- Contract: `xtend.surface.release-handoff.v1`
+- Report: `xtend.surface.release-handoff-report.v1`
+- Workpackage: `WP-SM-09`
+- Local gate: `node scripts/run_xtend_tests.js surface-release-handoff --json`
+- Package script: `npm run test:surface-release-handoff`
+
+## Status
+
+The first SurfaceManager line is authoring-ready and gate-ready with `WP-SM-09`. XTend can describe app shells with multi-window, side panels, overlay compatibility, quality gates and native RMT surface records.
+
+Historical `WP-SM-09` release boundary:
+
+```text
+no-public-runtime-claim-for-xtend.surface-adapter-yet
+```
+
+In the `WP-SM-09` authoring handoff, this meant: `surfaces[*]` and `xtend.surface.adapter.v1` were a stable handoff for tooling and the next runtime work. Since `WP-SM-19`, this runtime work has been closed through [SurfaceManager Runtime Release Handoff](./surface-manager-runtime-release-handoff.md), and the productive `xtend.surface` adapter claim is gateable.
+
+## Gate Chain
+
+```bash
+node scripts/run_xtend_tests.js rmt-surface-authoring --json
+node scripts/run_xtend_tests.js surface-controller --json
+node scripts/run_xtend_tests.js surface-manager --json
+node scripts/run_xtend_tests.js surface-side-panel --json
+node scripts/run_xtend_tests.js surface-workbench-fixture --json
+node scripts/run_xtend_tests.js surface-overlay-bridge --json
+node scripts/run_xtend_tests.js surface-manager-quality --json
+node scripts/run_xtend_tests.js surface-native-rmt --json
+node scripts/run_xtend_tests.js surface-release-handoff --json
+```
+
+## Handoff
+
+Ready:
+
+- app-shell authoring through component records and surface metadata
+- native `surfaces[*]` records for complex workbench UIs
+- Component Lab fixture for surface preview, native RMT inspector, migration diff, quality gates and source links
+- migration guide from `components[*].metadata.surface` to `surfaces[*]`
+- local static gates for RMT normalization, semantic graph, docs and reference paths
+
+Historical follow-up work from `WP-SM-09`:
+
+- productive `xtend.surface` adapter runtime, closed by `WP-SM-19`
+- optional browser-lab server or visual pixel baselines
+- additional surface types such as docked workspaces, command palettes and split panes
+- release hardening against real app-shell projects
+
+## WP-SM-19 Runtime Handoff
+
+`WP-SM-19` closes this follow-up work for the productive runtime line. The new contract `xtend.surface.runtime-release-handoff.v1` documents the productive runtime line made of adapter runtime, native materialization, persistence, lazy hydration, route lifecycle, stack policy, layout engines, remote policy and browser lab.
+
+```bash
+node scripts/run_xtend_tests.js surface-runtime-release-handoff --json
+```
+
+`WP-SM-09` therefore remains the historical authoring handoff, while `WP-SM-19` makes the productive runtime claim gateable. Open scopes such as project-specific pixel artifacts, release-owner signoff before npm publish and optional additional surface types remain explicitly named in the runtime handoff.
+
+## References
+
+- [SurfaceManager Authoring Guide](./surface-manager-authoring-guide.md)
+- [SurfaceManager Component Lab](./surface-manager-component-lab.md)
+- [SurfaceManager Migration Guide](./surface-manager-migration-guide.md)
+- [SurfaceManager Native RMT Surfaces](./surface-manager-native-rmt-surfaces.md)
+- [SurfaceManager Runtime Release Handoff](./surface-manager-runtime-release-handoff.md)

package/docs/en/surface-manager-remote-policy.md

@@ -0,0 +1,54 @@
+# SurfaceManager Remote Policy Bridge
+
+`WP-SM-17` connects E16 remote-surface records to the XTend UI surface runtime. The contract `xtend.surface.remote-policy-bridge.v1` belongs to `x-surface-manager`; the RMT kernel remains declarative and executes no remote runtime.
+
+## Decisions
+
+Remote surfaces are converted host-side into exactly one decision. The accepted trust boundary is `xtend.security.remote-surface.v1`.
+
+- `mounted`: owner, version, origin, integrity, trust boundary, capabilities, sandbox/CSP and event governance match.
+- `degraded`: a policy violation exists, but an explicit fallback is available.
+- `refused`: the surface may not be registered because a hard policy violation exists without fallback.
+
+The SurfaceController remains the only registry. The policy bridge creates no second registry; it only manages host decisions, diagnostics and fallback mapping.
+
+## Manager API
+
+- `evaluateRemoteSurfacePolicy(record, options)` checks a remote surface record without commit.
+- `applyRemoteSurfacePolicy(record, options)` checks and registers a mounted or degraded surface with `commit: true`.
+- `registerRemoteSurface(record, options)` is the productive mount path for `xtend.surface`.
+- `snapshotRemoteSurfacePolicy()` returns `xtend.surface.remote-policy-report.v1`.
+- `governRemoteSurfaceEvent(event, payload, options)` checks cross-surface events without an implicit global event bus.
+
+Important host attributes:
+
+- `remote-surface-policy="strict|audit|off"`
+- `remote-origin-allowlist="https://cdn.example"`
+- `remote-capabilities="surface.mount,event.emit,event.consume"`
+
+## Adapter Boundary
+
+The `xtend.surface` adapter consumes E16 remote-surface records, normalizes them as surface intent and forwards them to the SurfaceManager. It materializes at most a local shell or fallback. It loads no remote bundles, starts no `import()` and executes no remote runtime loading in the RMT kernel.
+
+## Diagnostics
+
+Policy violations are diagnosable, including:
+
+- `xtend.surface.remote-policy.owner-missing`
+- `xtend.surface.remote-policy.version-missing`
+- `xtend.surface.remote-policy.origin-not-allowed`
+- `xtend.surface.remote-policy.integrity-missing`
+- `xtend.surface.remote-policy.trust-boundary-refused`
+- `xtend.surface.remote-policy.capability-refused`
+- `xtend.surface.remote-policy.event-payload-missing`
+- `xtend.surface.remote-policy.event-scope-refused`
+- `xtend.surface.remote-policy.degradation-blocked`
+- `xtend.surface.remote-policy.fallback-missing`
+
+## Gate
+
+```bash
+node scripts/run_xtend_tests.js surface-remote-policy --json
+```
+
+The gate checks runtime methods, public types, RMT adapter connection, enterprise MFE fixture, degradation/fallback, event governance, package metadata and the boundaries `no second registry` and `no remote runtime loading in the RMT kernel`.

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

@@ -0,0 +1,89 @@
+# SurfaceManager RMT Authoring
+
+Docs contract: `xtend.docs.surface-manager-rmt-authoring.v1`
+
+The SurfaceManager is the XTend app-shell building block for multi-window UIs, side panels and later surface types in an SPA. `WP-SM-01` first defines the RMT authoring model; runtime components follow in the next packages.
+
+## Decision
+
+SurfaceManager is built as an RMT-native component family:
+
+- `x-surface-manager`
+- `x-surface-window`
+- `x-side-panel`
+
+Fabric remains underneath for lanes, fibers, diagnostics and telemetry. SurfaceManager does not replace Fabric.
+
+## MVP Authoring
+
+New SurfaceManager examples are written vNext-first. The compiler can still generate existing RMT `components` records with `metadata.surfaceManager` and `metadata.surface` from them:
+
+```rmt
+template workbench.surfaces {
+  state workbench.selection type object initial null
+
+  portal surface.root root "#workbench-root" layer surface
+
+  surface workbench.manager kind workspace component x-surface-manager {
+    portal surface.root
+
+    lane visible weight 90 {
+      mount x-surface-manager
+      hydrate surface-manager from endpoint surface.visible.render
+    }
+  }
+
+  surface workbench.inspector kind window component x-surface-window {
+    source state workbench.selection
+    portal surface.root
+
+    lane user-blocking weight 95 {
+      hydrate inspector-window from endpoint surface.user-blocking.open
+    }
+
+    lane transition weight 55 {
+      hydrate inspector-layout from endpoint surface.transition.layout
+    }
+  }
+
+  surface workbench.details kind panel component x-side-panel {
+    portal surface.root
+
+    lane visible weight 70 {
+      hydrate details-panel from state workbench.selection
+    }
+  }
+}
+```
+
+`xtend.surface` and a native RMT `surfaces` domain remain the runtime projection of this vNext path. Legacy `components[*].metadata.surface` is migration source and mirror, but no longer the preferred authoring form.
+
+## Schedules
+
+| Schedule | Lane | Purpose |
+|----------|------|---------|
+| `surface.visible.render` | `visible` | render manager and visible surface shell |
+| `surface.user-blocking.open` | `user-blocking` | open surface and set focus |
+| `surface.user-blocking.close` | `user-blocking` | close surface and restore focus |
+| `surface.transition.layout` | `transition` | commit move, resize, docking and snap |
+| `surface.background.persist` | `background` | persist layout snapshot |
+| `surface.diagnostics.snapshot` | `diagnostics` | snapshot registry, stack and telemetry |
+| `a11y.user-blocking.announce` | `user-blocking` | announce surface status for screenreaders |
+
+## Fixture
+
+The reference document is located at:
+
+```text
+tests/fixtures/rmt-surface-manager-workbench.rmt
+```
+
+It describes a shell-first workbench with two `x-surface-window` records and one `x-side-panel` record. The next documentation line should show the same workbench as an RMT vNext draft and keep the records only as compiler/compatibility output.
+
+## Gate
+
+```bash
+node scripts/run_xtend_tests.js rmt-surface-authoring --json
+```
+
+The gate checks `xtend.rmt.surface-authoring.v1`, the fixture, package/scaffold hooks, runner registration, docs and RMT core normalization without browser or network requirements.

package/docs/en/surface-manager-route-lifecycle.md

@@ -0,0 +1,59 @@
+# SurfaceManager Route Lifecycle
+
+Docs contract: `xtend.docs.surface-manager-route-lifecycle.v1`
+
+`WP-SM-14` binds surfaces to XRouter routes without introducing a second routing or surface registry. XRouter remains the route-state source. SurfaceManager remains the lifecycle source for surfaces.
+
+## Contract
+
+- Route lifecycle: `xtend.surface.route-lifecycle.v1`
+- Report: `xtend.surface.route-lifecycle-report.v1`
+- XRouter relation: `xtend.rmt.xrouter-adapter.v1`
+- Gate: `node scripts/run_xtend_tests.js surface-route-lifecycle --json`
+
+## Manager
+
+Route lifecycles are explicit. A manager reacts only when `route-aware` is set:
+
+```html
+<x-surface-manager
+  manager-id="app.manager"
+  route-aware="true"
+  route-lifecycle-policy="open-close">
+  ...
+</x-surface-manager>
+```
+
+`snapshotRouteLifecycle()` returns a report with route state, surface policy, match status and the boundaries `controllerRemainsRegistryTruth`, `xrouterOwnsRouteState` and `createsSecondRegistry: false`.
+
+`applyRouteLifecycle(routeInput, options)` can be used by tests, host adapters or XRouter events. The normal runtime path reacts to `route-changed`, `routechange`, `xrouter-after-navigate`, `xtend-route-changed`, `popstate` and `hashchange`.
+
+## Surface Policies
+
+Surfaces are bound through `data-surface-route` and `data-surface-route-policy`:
+
+| Policy | Match | No match |
+|--------|-------|----------|
+| `global` | remains unchanged | remains unchanged |
+| `open-close` | open/restore and route-hydrate | close |
+| `open-collapse` | open/restore/expand and route-hydrate | side panels collapse, windows minimize |
+| `open-minimize` | open/restore and route-hydrate | minimize, with collapse fallback |
+| `open-keep` | open/restore and route-hydrate | remains open |
+| `hydrate-only` | route-hydrate | no lifecycle change |
+| `manual` | no automatic change | no automatic change |
+
+Global surfaces, command palettes or persistence surfaces can remain stable across route changes with `data-surface-route-policy="global"` or `data-surface-route-persistent="true"`.
+
+## RMT
+
+RMT-materialized surfaces carry route information as DOM attributes:
+
+- `data-surface-route`
+- `data-surface-route-policy`
+- `data-surface-hydration-policy="route"` as default when a surface has a route and no explicit hydration policy is set
+
+The RMT kernel imports no XTend types. The adapter materializes only attributes; the runtime decision remains in the SurfaceManager.
+
+## No Competing Lifecycle Sources
+
+Standalone `x-side-panel route-aware` keeps its old fallback. However, as soon as a panel is managed by `x-surface-manager`, it delegates route changes to the manager. Managed surfaces therefore have no competing lifecycle sources.

package/docs/en/surface-manager-runtime-release-handoff.md

@@ -0,0 +1,69 @@
+# SurfaceManager Runtime Release Handoff
+
+`WP-SM-19` finalizes the surface runtime as a productive XTend UI layer for app shells. The contract `xtend.surface.runtime-release-handoff.v1` bundles the work from `WP-SM-10` through `WP-SM-18` and makes the runtime claim locally gateable.
+
+## Productive Runtime Claims
+
+| Claim | Gate |
+| --- | --- |
+| `productive-xtend-surface-adapter-runtime` | `surface-adapter-runtime` |
+| `native-surfaces-materialize-xtend-ui-components` | `surface-native-materialization` |
+| `restore-key-snapshot-hydration` | `surface-persistence` |
+| `shell-first-skeleton-hydration` | `surface-lazy-hydration` |
+| `xrouter-bound-surface-lifecycle` | `surface-route-lifecycle` |
+| `modal-focus-inert-stack-policy` | `surface-stack-policy` |
+| `layout-engines-docking-split-tile-stacked` | `surface-layout-engines` |
+| `remote-surface-trust-policy` | `surface-remote-policy` |
+| `browser-lab-visual-stability` | `surface-browser-lab` |
+
+The final gate is:
+
+```bash
+node scripts/run_xtend_tests.js surface-runtime-release-handoff --json
+```
+
+## Authoring
+
+New complex app shells should use native `surfaces[*]`. `components[*].metadata.surface` remains as a compatibility path, especially for existing fixtures and additive migrations.
+
+The productive path is:
+
+1. Model surface records in `surfaces[*]`.
+2. Reference component records as manager and content bindings.
+3. Keep route, schedule, state key and restore key stable.
+4. Check `surface-adapter-runtime` and `surface-native-materialization`.
+5. Check app-shell stability through `surface-browser-lab`.
+
+## Release Gate Matrix
+
+The runtime handoff expects the existing baseline plus the hardened runtime line:
+
+```bash
+node scripts/run_xtend_tests.js rmt-surface-authoring surface-controller surface-manager surface-side-panel surface-workbench-fixture surface-overlay-bridge surface-manager-quality surface-native-rmt surface-release-handoff --json
+node scripts/run_xtend_tests.js surface-adapter-runtime surface-native-materialization surface-persistence surface-lazy-hydration surface-route-lifecycle surface-stack-policy surface-layout-engines surface-remote-policy surface-browser-lab surface-runtime-release-handoff --json
+```
+
+## Compatibility Notes
+
+`xtend.surface.runtime-compatibility-notes.v1` records:
+
+- existing component-metadata surfaces remain runnable
+- workbench and browser-lab fixtures remain in the gate
+- Docs app Parsedown remains a host boundary and is not moved into SurfaceManager
+- remote runtime loading remains outside the RMT kernel
+- SurfaceManager replaces neither Fabric nor the RMT kernel
+- SurfaceController remains the only registry
+
+## Open Scopes
+
+These points are intentionally not part of the runtime claim:
+
+- `project-specific-pixel-artifact-storage`
+- `release-owner-signoff-before-public-npm-publish`
+- `optional-command-palette-and-workspace-surface-types`
+- `remote-runtime-loading-remains-out-of-scope`
+- `docs-app-php-parsedown-host-boundary-remains`
+
+## SemVer
+
+The classification for the current state is `0.x-minor-with-migration-notes`. Before external publish, release-owner signoff, changelog and the general release checklist remain required.

package/docs/en/surface-manager-side-panel-runtime.md

@@ -0,0 +1,36 @@
+# SurfaceManager SidePanel Runtime
+
+`WP-SM-04` introduces `x-side-panel` as a native surface component. The contract `xtend.surface.side-panel-runtime.v1` extends the window runtime with app-shell-close side panels for docking, pinning, collapse, overlay and responsive fullscreen behavior.
+
+## Components
+
+- `x-surface-manager`: detects `x-side-panel` in the `panels` slot and processes `surface-panel-command`.
+- `x-side-panel`: creates `xtend.surface.record.v1` with `type: "side-panel"`.
+- `components/xsurfacemanager-controller.js`: remains the only registry and snapshot truth.
+
+## Modes
+
+| Mode | Use |
+|------|-----|
+| Docked | persistent app-shell sidebar |
+| Pinned | open, persistent panel |
+| Overlay | temporary panel above the workspace |
+| Collapsed | compact panel rail |
+| Fullscreen | responsive fallback for small viewports |
+
+Placements: `left`, `right`, `bottom`, `inline`.
+
+## Commands
+
+`x-side-panel` sends `surface-panel-command` with `open`, `close`, `focus`, `resize`, `pin`, `unpin`, `collapse`, `expand`, `dock`, `restore` or `update`.
+
+The manager maps these commands to `openSurface`, `closeSurface`, `focusSurface`, `resizeSurface`, `updateSurface`, `pinSurface`, `collapseSurface`, `expandSurface`, `dockSurface` and `restoreSurface`.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js surface-side-panel --json
+npm run test:surface-side-panel -- --json
+```
+
+`WP-SM-05` builds on this with the RMT-first workbench fixture containing two windows, a side panel, route-bound content and a shared surface snapshot.

package/docs/en/surface-manager-stack-policy.md

@@ -0,0 +1,39 @@
+# SurfaceManager Stack Policy
+
+As of `WP-SM-15`, `x-surface-manager` owns the `xtend.surface.stack-policy.v1` contract for mixed surface stacks made of windows, side panels, dialogs, modals and drawers.
+
+## Goal
+
+`modal-policy` is evaluated productively at manager level. The SurfaceController remains the registry source while the manager applies the UI-close stack policy to existing XTend components:
+
+- `snapshotStackPolicy()` returns the current report `xtend.surface.stack-policy-report.v1`.
+- `applyStackPolicy()` applies layer tokens, active modality, inert, `aria-hidden`, `aria-modal`, focus trap, focus restore, Escape priority and scroll lock.
+- existing overlay components keep their local APIs and focus/Escape implementations.
+
+## Modal Policies
+
+| Policy | Effect |
+|--------|--------|
+| `topmost` | the topmost modal surface receives active modality |
+| `none` | no manager modality, no inert or scroll-lock rule |
+| `all-modal` | every open surface can be treated as modal; the topmost one is active |
+| `surface-modal` | all surfaces declared as modal are recognized; the topmost modal surface is active |
+
+## Runtime Rules
+
+- Focus restore: when a modal surface is activated, the manager remembers the previous focus target and restores it after close.
+- Inert: background surfaces receive `data-surface-inert="manager"`, `inert` and `aria-hidden` while an active modal surface exists.
+- Escape: a document-wide capture handler closes the active modal surface or otherwise the topmost closable surface.
+- Scroll lock: active modality sets `data-xtend-surface-scroll-lock` on `html` and `body`.
+- Layer tokens: every surface receives `data-surface-layer-token`, `--surface-layer-z` and compatible component z variables.
+- Diagnostics: missing labels, missing focus targets and modality below non-modal surfaces become visible in the stack-policy report.
+
+## Boundary
+
+The stack policy is a supporting XTend UI layer. It creates no second registry, replaces neither Fabric nor the RMT kernel, and does not change SurfaceController truth. RMT can declare `modal-policy`, but the runtime decision remains with `x-surface-manager`.
+
+Local gate:
+
+```bash
+node scripts/run_xtend_tests.js surface-stack-policy --json
+```

package/docs/en/surface-manager-window-runtime.md

@@ -0,0 +1,47 @@
+# SurfaceManager Window Runtime
+
+`WP-SM-03` makes the SurfaceManager visible for the first time: `x-surface-manager` manages the controller, and `x-surface-window` is the first WindowManager surface.
+
+- Contract: `xtend.surface.window-runtime.v1`
+- Manager: `components/xsurfacemanager.js`
+- Window: `components/xsurfacewindow.js`
+- Controller: `components/xsurfacemanager-controller.js`
+- Gate: `node scripts/run_xtend_tests.js surface-manager --json`
+
+## Example
+
+```html
+<x-surface-manager id="workbench" manager-id="workbench.manager">
+  <x-surface-window
+    slot="windows"
+    surface-id="workbench.inspector"
+    label="Inspector"
+    open
+    draggable
+    resizable
+    initial-x="96"
+    initial-y="88"
+    initial-width="520"
+    initial-height="360">
+    <section>Inspector content</section>
+  </x-surface-window>
+</x-surface-manager>
+```
+
+## Manager
+
+`x-surface-manager` provides `registerSurface`, `openSurface`, `closeSurface`, `focusSurface`, `updateSurface`, `moveSurface`, `resizeSurface`, `minimizeSurface`, `maximizeSurface`, `restoreSurface` and `snapshot`.
+
+Slots: `windows`, `panels`, `overlays`, `default`.
+
+Events: `surface-manager-ready`, `surface-registered`, `surface-opened`, `surface-closed`, `surface-focused`, `surface-updated`, `surface-layout-changed`.
+
+## Window
+
+`x-surface-window` provides `toSurfaceRecord`, `applySurfaceSnapshot`, `openWindow`, `closeWindow`, `focusWindow`, `minimizeWindow`, `maximizeWindow` and `restoreWindow`.
+
+The element sends `surface-window-command`. The manager turns it into the controller operation and mirrors the snapshot back.
+
+## Handoff
+
+`WP-SM-04` extends this runtime with `x-side-panel` and responsive surface modes. The window runtime remains the first multi-window proof and must not introduce a second registry beside the controller.

package/docs/en/surface-manager-workbench-fixture.md

@@ -0,0 +1,43 @@
+# SurfaceManager Workbench Fixture
+
+Docs contract: `xtend.docs.surface-manager-workbench-fixture.v1`
+
+Runtime contract: `xtend.surface.workbench-fixture.v1`
+
+`WP-SM-05` introduces the first RMT-first workbench for the SurfaceManager. It renders an app shell from RMT, binds the SurfaceManager to a route and shows two windows plus a side panel with a shared snapshot.
+
+## Artifacts
+
+| Path | Purpose |
+|------|---------|
+| `xtendrmt/surface-workbench.rmt` | RMT document with app shell, route, SurfaceManager, two windows, side panel and content |
+| `tests/browser/fixtures/rmt-surface-workbench-smoke.html` | host/smoke fixture without manual surface components |
+| `xtendrmt/surface-workbench.js` | workbench renderer for `dom_descriptor`, slots, routes and snapshot |
+| `tests/browser/fixtures/rmt-surface-workbench-smoke.html` | prepared browser smoke for later surface gates |
+
+## Model
+
+The workbench continues to use the MVP path from `xtend.rmt.surface-authoring.v1`: surfaces are normal `components` records with `metadata.surface`. The native RMT `surfaces` domain remains reserved.
+
+Included:
+
+- `workbench.manager` as `x-surface-manager`
+- `workbench.inspector` and `workbench.editor` as two windows
+- `workbench.properties` as `x-side-panel`
+- `app.router` as route-bound outlet
+- `workbench` as route for surface content
+- `xtend.surface.snapshot` as shared surface snapshot key
+
+## Runtime
+
+`xtendrmt/surface-workbench.js` renders only structured DOM nodes. The renderer does not use `innerHTML`; it uses `renderDomDescriptor`, `renderSurfaceWorkbenchFromDocument` and `root.replaceChildren(shellFragment)`.
+
+The snapshot is read via `collectSurfaceSnapshot(root)`. If `x-surface-manager.snapshot()` is available, the snapshot comes directly from the manager; otherwise the fixture provides a DOM fallback for static gates.
+
+## Gate
+
+```bash
+node scripts/run_xtend_tests.js surface-workbench-fixture --json
+```
+
+The gate checks contract, RMT normalization, host boundary, runtime boundary, route-bound content, two windows, side panel, shared surface snapshot, package/scaffold metadata, docs and runner registration.