@ccslabs/xtend 0.1.0-rc.1

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

@@ -0,0 +1,94 @@
+# 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`
+
+## Ziel
+
+Dieser Guide beschreibt die additive Migration von Surface-Metadata in Component Records zu nativen RMT Surface Records. Die Migration ist bewusst ohne Big Bang: bestehende `components[*].metadata.surface` Records bleiben gueltig, waehrend neue App Shells `surfaces[*]` bevorzugen.
+
+## Migrationsschritte
+
+| Schritt | Ergebnis |
+|---------|----------|
+| `inventory-component-metadata-surfaces` | alle bestehenden `metadata.surface` Records und State Keys erfassen |
+| `stabilize-surface-ids-and-state-keys` | IDs, `type`, `manager` und `stateKey` einfrieren |
+| `add-native-surfaces-records` | parallele `surfaces[*]` Records mit gleicher Identitaet anlegen |
+| `keep-dual-records-during-handoff` | Component-Metadata und native Records im Gate vergleichen |
+| `switch-authoring-default-to-surfaces-domain` | neue komplexe Shells direkt in `surfaces[*]` schreiben |
+| `close-xtend-surface-runtime-after-adapter-implementation` | historisches Adapter-Handoff aus `WP-SM-09` durch `WP-SM-19` Runtime-Gates schliessen |
+
+## Vorher
+
+```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"
+    }
+  }
+}
+```
+
+## Nachher als Dual Record
+
+```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"
+    }
+  ]
+}
+```
+
+Die Component-Metadata bleibt waehrend des Handoffs im Component Record und verweist optional mit `nativeRecord` auf den nativen Record.
+
+## Review-Checkliste
+
+- Jede native Surface besitzt einen stabilen `id`.
+- `component` zeigt auf genau einen Component Record.
+- `manager` zeigt auf den `x-surface-manager` Record.
+- `route` und `schedule` loesen auf native RMT Records auf.
+- `stateKey` ist identisch zwischen `components[*].metadata.surface` und `surfaces[*]`.
+- `xtend.surface` ist als `surface_adapter` deklariert und seit `WP-SM-19` ueber die Runtime-Gates produktiv beworben.
+- Die Gates `surface-native-rmt`, `surface-release-handoff` und `surface-runtime-release-handoff` sind gruen.
+
+Details zur generischen RMT-Migration stehen in [XTendRMT Native Migration Guide](./xtendrmt-migration-guide.md). Details zum Surface-Authoring stehen in [SurfaceManager Authoring Guide](./surface-manager-authoring-guide.md).
+
+## WP-SM-19 Runtime Migration Notes
+
+`WP-SM-19` akzeptiert `xtend.surface.runtime-migration-notes.v1` als finale Migrationslinie fuer die produktive Surface Runtime.
+
+Erweiterte Gate-Reihenfolge fuer Migrationen:
+
+```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
+```
+
+Bestehende `components[*].metadata.surface` Records bleiben erlaubt. Der Zielzustand fuer neue Shells ist dennoch `surfaces[*]`, weil Tooling, Materialisierung, Persistenz, Routing, Remote Policy und Browser-Lab-Stabilitaet dort gemeinsam pruefbar sind.

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

@@ -0,0 +1,38 @@
+# SurfaceManager Native RMT Surfaces
+
+`WP-SM-08` fuehrt `xtend.rmt.surfaces-domain.v1` und den Adapter-Handoff `xtend.surface.adapter.v1` ein.
+
+## Lokaler Gate
+
+```bash
+node scripts/run_xtend_tests.js surface-native-rmt --json
+npm run test:surface-native-rmt
+```
+
+## Domain
+
+`surfaces` ist eine optionale Top-Level-Domain in `.rmt` Dokumenten. Ein Surface Record referenziert weiter normale RMT-Domains:
+
+- `adapter`: `xtend.surface`
+- `manager`: `x-surface-manager` Component Record
+- `component`: sichtbare Surface-Komponente, zum Beispiel `x-surface-window`, `x-side-panel`, `x-modal`, `x-dialog` oder `x-drawer`
+- `route`: Route Record
+- `schedule`: Schedule Record
+
+Die Fixture `tests/fixtures/rmt-surface-native-domain.rmt` zeigt sechs Surface Records: zwei Windows, ein SidePanel, Modal, Dialog und Drawer.
+
+## Adapter
+
+`xtend.surface` ist als `surface_adapter` registrierbar. In `WP-SM-08` war `runtimeImplemented: false` Absicht und der Adapter blieb ein Handoff-Contract. Seit `WP-SM-19` ist die produktive Runtime-Linie im [SurfaceManager Runtime Release Handoff](./surface-manager-runtime-release-handoff.md) gatebar: Die Runtime konsumiert `surfaces[*]`, ruft den SurfaceController und haelt DOM, xstate und Fabric ausserhalb des RMT Kernels.
+
+## Migration
+
+Bestehende Component Records mit `metadata.surface` bleiben gueltig. Neue native Records koennen parallel gefuehrt werden, solange `id`, `type`, `manager`, `component`, `route`, `schedule` und `stateKey` stabil zusammenpassen.
+
+## Tooling
+
+Schema, Type Artifact, Normalizer, Semantic Graph, Completion Provider und Linter kennen `surfaces`. Damit kann der Language Server Surface Records referenzieren und Completion fuer `surfaces[*].component`, `surfaces[*].adapter`, `surfaces[*].route`, `surfaces[*].schedule` und `surfaces[*].type` anbieten.
+
+## Handoff
+
+`WP-SM-09` finalisiert Docs, Component Lab und Migration Guide auf dieser Contract-Basis. Der Abschluss liegt in [SurfaceManager Release Handoff](./surface-manager-release-handoff.md) (`docs/surface-manager-release-handoff.md`) und wird ueber `node scripts/run_xtend_tests.js surface-release-handoff --json` geprueft.

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

@@ -0,0 +1,53 @@
+# SurfaceManager Overlay Bridge
+
+`WP-SM-06` fuehrt `xtend.surface.overlay-stack-bridge.v1` ein. Die Bridge macht `x-modal`, `x-dialog` und `x-drawer` optional kompatibel mit dem `x-surface-manager` Surface Stack.
+
+## Was sich aendert
+
+`x-surface-manager` registriert im `overlays` Slot nun auch:
+
+- `x-modal` als Surface Type `modal`
+- `x-dialog` als Surface Type `dialog`
+- `x-drawer` als Surface Type `drawer`
+
+Die bestehenden Overlay APIs bleiben erhalten. Ein Modal kann weiter ueber `open()` und `close()` gesteuert werden, ein Drawer weiter ueber `openDrawer()` und `closeDrawer()`. Die Legacy Events `modal-opened`, `dialog-opened` und `drawer-opened` bleiben sichtbar.
+
+## Command Bridge
+
+Overlays koennen innerhalb des Managers ein `surface-overlay-command` Event nutzen:
+
+```js
+manager.dispatchEvent(new CustomEvent('surface-overlay-command', {
+  bubbles: true,
+  composed: true,
+  detail: {
+    surfaceId: 'settings.dialog',
+    command: 'open'
+  }
+}));
+```
+
+Unterstuetzt werden die vorhandenen Surface-Operationen wie `open`, `close`, `focus` und `update`. Der Manager nutzt dafuer denselben Controller Stack wie Windows und SidePanels.
+
+## Stack-Verhalten
+
+Die Bridge spiegelt den Surface Snapshot in Overlay CSS Custom Properties:
+
+- `--surface-overlay-z`
+- `--surface-overlay-backdrop-z`
+
+Ausserhalb eines SurfaceManagers behalten `x-modal`, `x-dialog` und `x-drawer` ihre bisherigen Default-z-Indizes.
+
+## RMT und Lifecycle
+
+RMT bleibt fuer diese Stufe bei `xtend.component`. Die Bridge erzeugt intern `xtend.surface.record.v1`, aber sie aktiviert noch keine native `xtend.surface` Domain.
+
+Der lokale Gate:
+
+```bash
+node scripts/run_xtend_tests.js surface-overlay-bridge --json
+```
+
+## Abgrenzung
+
+`WP-SM-06` bereitet die Stack-Kompatibilitaet vor. Browser-, A11y-, Performance- und Visual-Smokes folgen in `WP-SM-07`; die native RMT `surfaces` Domain folgt spaeter in `WP-SM-08`.

package/docs/surface-manager-persistence.md

@@ -0,0 +1,30 @@
+# SurfaceManager Persistence
+
+`x-surface-manager` kann Surface-Layouts unter einem `restore-key` speichern und beim naechsten Start wieder ueber den SurfaceController einspielen.
+
+## Attribute
+
+| Attribut | Werte | Zweck |
+| --- | --- | --- |
+| `restore-key` | string | Stabiler Schluessel fuer das App-Shell-Layout |
+| `persistence-mode` | `none`, `memory`, `session`, `local` | Storage-Backend fuer Snapshots |
+| `restore-policy` | `auto`, `manual`, `reset` | Auto-Restore beim Connect oder manuelle Steuerung |
+
+Ohne `restore-key` bleibt Persistenz aus. Mit `restore-key` und ohne explizites `persistence-mode` nutzt die Runtime `session`.
+
+## API
+
+- `snapshotPersistence()` gibt den aktiven Persistenzcontract zurueck.
+- `persistSnapshot(snapshot, options)` speichert einen layout-only Snapshot.
+- `restorePersistedSnapshot(options)` liest und hydriert einen gespeicherten Snapshot.
+- `clearPersistedSnapshot(options)` entfernt den gespeicherten Snapshot.
+- `resetSurfaceLayout(options)` loescht Persistenz und registriert die deklarierten Surface-Elemente neu.
+
+Gespeichert wird `xtend.surface.persisted-snapshot.v1`. Content-Payloads werden nicht persistiert; erhalten bleiben Surface IDs, Bounds, Stack, Active Surface, Panel Modes, Status und Content-Refs.
+
+## Boundaries
+
+- Der SurfaceController bleibt die einzige Registry-Wahrheit.
+- Restore laeuft ueber Controller-Operationen, nicht durch direktes Mutieren einer zweiten Registry.
+- Ungueltige oder inkompatible Snapshots fuehren zu einem kontrollierten Skip mit Diagnostic.
+- Der RMT-Kernel importiert keine XTend-Komponenten.

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

@@ -0,0 +1,51 @@
+# SurfaceManager Quality Gates
+
+`WP-SM-07` fuehrt `xtend.surface.quality-gates.v1` ein. Der Gate prueft den SurfaceManager ueber vier Domaenen: Browser, A11y, Performance und Visual.
+
+## Lokale 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
+```
+
+Die Domain-Gates laufen ueber denselben Contract und koennen gezielt in lokalen Checks oder CI-Matrizen referenziert werden.
+
+## Browser
+
+Das Fixture `tests/browser/fixtures/surface-manager-quality-smoke.html` baut eine gemischte Surface-Oberflaeche:
+
+- zwei `x-surface-window`
+- ein `x-side-panel`
+- ein `x-modal`
+- ein `x-dialog`
+- ein `x-drawer`
+
+Overlays werden ueber `surface-overlay-command` geoeffnet und in denselben Surface Stack aufgenommen.
+
+## A11y
+
+Der Gate prueft Contract- und Fixture-Signale fuer:
+
+- Rollen: `application`, `dialog`, `complementary`
+- `aria-live` Status
+- Focus Restore
+- Escape-Topmost-Verhalten
+- Tab Focus Trap
+- Reduced Motion
+- Forced Colors und sichtbaren Fokus
+
+## Performance
+
+Der Contract definiert Budgets fuer Open/Close, Focus, Layout Transition, Snapshot und Registration. Das Browser-Fixture setzt zusaetzlich die Performance-Messung `surface-quality-open-close`.
+
+## Visual
+
+Die DOM-Baseline `tests/browser/visual-baselines/surface-manager-quality.dom-baseline.json` deckt Desktop, Mobile, Topmost Overlay und Forced Colors ab. Sie bleibt bewusst JSON-only, damit der lokale Gate stabil ohne Browser-Pixel-Diff laufen kann.
+
+## Handoff
+
+`WP-SM-08` kann auf den Quality-Gates aufsetzen und die native RMT `surfaces` Domain gegen dieselben sichtbaren Stack-Zustaende validieren.

package/docs/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
+
+Die erste SurfaceManager-Linie ist mit `WP-SM-09` authoring- und gatebereit. XTend kann App Shells mit Multi Window, SidePanels, Overlay-Kompatibilitaet, Quality Gates und nativen RMT Surface Records beschreiben.
+
+Historische `WP-SM-09` Release Boundary:
+
+```text
+no-public-runtime-claim-for-xtend.surface-adapter-yet
+```
+
+Das bedeutete im `WP-SM-09` Authoring-Handoff: `surfaces[*]` und `xtend.surface.adapter.v1` waren stabiler Handoff fuer Tooling und die naechste Runtime-Arbeit. Seit `WP-SM-19` ist diese Runtime-Arbeit ueber [SurfaceManager Runtime Release Handoff](./surface-manager-runtime-release-handoff.md) geschlossen und der produktive `xtend.surface` Adapter-Claim gatebar.
+
+## Gate-Kette
+
+```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
+
+Bereit:
+
+- App-Shell Authoring ueber Component Records und Surface-Metadata
+- native `surfaces[*]` Records fuer komplexe Workbench-Oberflaechen
+- Component Lab Fixture fuer Surface Preview, Native RMT Inspector, Migration Diff, Quality Gates und Source Links
+- Migration Guide fuer `components[*].metadata.surface` zu `surfaces[*]`
+- lokale statische Gates fuer RMT-Normalisierung, Semantic Graph, Docs und Referenzpfade
+
+Historische Folgearbeit aus `WP-SM-09`:
+
+- produktive `xtend.surface` Adapter Runtime, geschlossen durch `WP-SM-19`
+- optionaler Browser-Lab-Server oder visuelle Pixel-Baselines
+- weitere Surface-Typen wie docked workspaces, command palettes und split panes
+- Release-Hardening gegen echte App-Shell-Projekte
+
+## WP-SM-19 Runtime-Handoff
+
+`WP-SM-19` schliesst diese Folgearbeit fuer die produktive Runtime-Linie ab. Der neue Contract `xtend.surface.runtime-release-handoff.v1` dokumentiert die produktive Runtime-Linie aus Adapter Runtime, nativer Materialisierung, Persistenz, Lazy Hydration, Route Lifecycle, Stack Policy, Layout Engines, Remote Policy und Browser Lab.
+
+```bash
+node scripts/run_xtend_tests.js surface-runtime-release-handoff --json
+```
+
+Damit bleibt `WP-SM-09` der historische Authoring-Handoff, waehrend `WP-SM-19` den produktiven Runtime-Claim gatebar macht. Offene Scopes wie projektbezogene Pixel-Artefakte, Release-Owner-Signoff vor npm Publish und optionale weitere Surface-Typen bleiben im Runtime-Handoff explizit benannt.
+
+## Referenzen
+
+- [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/surface-manager-remote-policy.md

@@ -0,0 +1,54 @@
+# SurfaceManager Remote Policy Bridge
+
+`WP-SM-17` bindet E16 Remote-Surface-Records an die XTend-UI-Surface-Runtime an. Der Contract `xtend.surface.remote-policy-bridge.v1` gehoert zum `x-surface-manager`; der RMT Kernel bleibt deklarativ und fuehrt keine Remote Runtime aus.
+
+## Entscheidungen
+
+Remote Surfaces werden hostseitig in genau eine Entscheidung ueberfuehrt. Die akzeptierte Trust Boundary lautet `xtend.security.remote-surface.v1`.
+
+- `mounted`: Owner, Version, Origin, Integrity, Trust Boundary, Capabilities, Sandbox/CSP und Event-Governance sind passend.
+- `degraded`: eine Policy-Verletzung liegt vor, aber ein expliziter Fallback ist verfuegbar.
+- `refused`: die Surface darf nicht registriert werden, weil eine harte Policy-Verletzung ohne Fallback vorliegt.
+
+Der SurfaceController bleibt die einzige Registry. Die Policy Bridge legt keine zweite Registry an; sie fuehrt nur Host-Entscheidungen, Diagnostics und Fallback-Mapping.
+
+## Manager API
+
+- `evaluateRemoteSurfacePolicy(record, options)` prueft einen Remote Surface Record ohne Commit.
+- `applyRemoteSurfacePolicy(record, options)` prueft und registriert bei `commit: true` eine gemountete oder degradierte Surface.
+- `registerRemoteSurface(record, options)` ist der produktive Mount-Pfad fuer `xtend.surface`.
+- `snapshotRemoteSurfacePolicy()` liefert `xtend.surface.remote-policy-report.v1`.
+- `governRemoteSurfaceEvent(event, payload, options)` prueft Cross-Surface Events ohne impliziten globalen Event-Bus.
+
+Wichtige Host-Attribute:
+
+- `remote-surface-policy="strict|audit|off"`
+- `remote-origin-allowlist="https://cdn.example"`
+- `remote-capabilities="surface.mount,event.emit,event.consume"`
+
+## Adapter Boundary
+
+Der `xtend.surface` Adapter konsumiert E16 Remote-Surface-Records, normalisiert sie als Surface-Intent und reicht sie an den SurfaceManager weiter. Er materialisiert hoechstens eine lokale Shell oder einen Fallback. Er laedt keine Remote Bundles, startet kein `import()` und fuehrt kein Remote Runtime Loading im RMT Kernel aus.
+
+## Diagnostics
+
+Policy-Verletzungen sind diagnostizierbar, darunter:
+
+- `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
+```
+
+Der Gate prueft Runtime-Methoden, Public Types, RMT-Adapter-Anbindung, Enterprise-MFE-Fixture, Degradation/Fallback, Event-Governance, Package-Metadaten und die Boundaries `keine zweite Registry` sowie `kein Remote Runtime Loading im RMT Kernel`.

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

@@ -0,0 +1,86 @@
+# SurfaceManager RMT Authoring
+
+Docs Contract: `xtend.docs.surface-manager-rmt-authoring.v1`
+
+Der SurfaceManager ist der geplante XTend App-Shell-Baustein fuer Multi Window Oberflaechen, SidePanels und spaetere Surface-Typen in einer SPA. `WP-SM-01` definiert zuerst das RMT Authoring Model; Runtime-Komponenten folgen in den naechsten Paketen.
+
+## Entscheidung
+
+SurfaceManager wird als RMT-native Komponentenfamilie aufgebaut:
+
+- `x-surface-manager`
+- `x-surface-window`
+- `x-side-panel`
+
+Fabric bleibt darunter fuer Lanes, Fibers, Diagnostics und Telemetry. Der SurfaceManager ersetzt Fabric nicht.
+
+## MVP Authoring
+
+Der MVP nutzt vorhandene RMT `components` Records mit `metadata.surfaceManager` und `metadata.surface`:
+
+```json
+{
+  "id": "workbench.manager",
+  "kind": "custom_element",
+  "adapter": "xtend.component",
+  "tag": "x-surface-manager",
+  "schedule": "surface.visible.render",
+  "metadata": {
+    "surfaceManager": {
+      "schema": "xtend.surface.manager.v1",
+      "stateKey": "xtend.surface.registry",
+      "defaultLayer": "workspace"
+    }
+  }
+}
+```
+
+```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",
+      "type": "window",
+      "manager": "workbench.manager",
+      "stateKey": "xtend.surface.inspector.state"
+    }
+  }
+}
+```
+
+`xtend.surface` und eine native RMT `surfaces` Domain sind reserviert, aber noch nicht aktiv.
+
+## Schedules
+
+| Schedule | Lane | Zweck |
+|----------|------|-------|
+| `surface.visible.render` | `visible` | Manager und sichtbare Surface Shell rendern |
+| `surface.user-blocking.open` | `user-blocking` | Surface oeffnen und Fokus setzen |
+| `surface.user-blocking.close` | `user-blocking` | Surface schliessen und Fokus restaurieren |
+| `surface.transition.layout` | `transition` | Move, Resize, Docking und Snap committen |
+| `surface.background.persist` | `background` | Layout Snapshot persistieren |
+| `surface.diagnostics.snapshot` | `diagnostics` | Registry, Stack und Telemetry snapshotten |
+| `a11y.user-blocking.announce` | `user-blocking` | Surface Status fuer Screenreader ansagen |
+
+## Fixture
+
+Das Referenzdokument liegt in:
+
+```text
+tests/fixtures/rmt-surface-manager-workbench.rmt
+```
+
+Es beschreibt eine Shell-first Workbench mit zwei `x-surface-window` Records und einem `x-side-panel` Record.
+
+## Gate
+
+```bash
+node scripts/run_xtend_tests.js rmt-surface-authoring --json
+```
+
+Der Gate prueft `xtend.rmt.surface-authoring.v1`, das Fixture, Package-/Scaffold-Hooks, Runner-Registrierung, Docs und die RMT-Core-Normalisierung ohne Browser- oder Netzwerkpflicht.

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

@@ -0,0 +1,59 @@
+# SurfaceManager Route Lifecycle
+
+Docs Contract: `xtend.docs.surface-manager-route-lifecycle.v1`
+
+`WP-SM-14` bindet Surfaces an XRouter-Routen, ohne eine zweite Routing- oder Surface-Registry einzufuehren. XRouter bleibt Route-State-Quelle. SurfaceManager bleibt Lifecycle-Quelle fuer Surfaces.
+
+## Contract
+
+- Route Lifecycle: `xtend.surface.route-lifecycle.v1`
+- Report: `xtend.surface.route-lifecycle-report.v1`
+- XRouter Bezug: `xtend.rmt.xrouter-adapter.v1`
+- Gate: `node scripts/run_xtend_tests.js surface-route-lifecycle --json`
+
+## Manager
+
+Route-Lifecycles sind explizit. Ein Manager reagiert nur, wenn `route-aware` gesetzt ist:
+
+```html
+<x-surface-manager
+  manager-id="app.manager"
+  route-aware="true"
+  route-lifecycle-policy="open-close">
+  ...
+</x-surface-manager>
+```
+
+`snapshotRouteLifecycle()` liefert einen Report mit Route-State, Surface-Policy, Match-Status und den Boundaries `controllerRemainsRegistryTruth`, `xrouterOwnsRouteState` und `createsSecondRegistry: false`.
+
+`applyRouteLifecycle(routeInput, options)` kann von Tests, Host-Adaptern oder XRouter-Events genutzt werden. Der normale Runtime-Pfad reagiert auf `route-changed`, `routechange`, `xrouter-after-navigate`, `xtend-route-changed`, `popstate` und `hashchange`.
+
+## Surface Policies
+
+Surfaces werden ueber `data-surface-route` und `data-surface-route-policy` gebunden:
+
+| Policy | Match | Kein Match |
+|--------|-------|------------|
+| `global` | bleibt unveraendert | bleibt unveraendert |
+| `open-close` | open/restore und route-hydrate | close |
+| `open-collapse` | open/restore/expand und route-hydrate | SidePanels collapse, Windows minimize |
+| `open-minimize` | open/restore und route-hydrate | minimize, mit Collapse-Fallback |
+| `open-keep` | open/restore und route-hydrate | bleibt offen |
+| `hydrate-only` | route-hydrate | kein Lifecycle-Wechsel |
+| `manual` | kein automatischer Wechsel | kein automatischer Wechsel |
+
+globale Surfaces, Command Palettes oder Persistenz-Surfaces koennen mit `data-surface-route-policy="global"` oder `data-surface-route-persistent="true"` routewechselstabil bleiben.
+
+## RMT
+
+RMT-materialisierte Surfaces tragen Route-Informationen als DOM-Attribute:
+
+- `data-surface-route`
+- `data-surface-route-policy`
+- `data-surface-hydration-policy="route"` als Default, wenn eine Surface eine Route besitzt und keine explizite Hydration-Policy gesetzt ist
+
+Der RMT Kernel importiert keine XTend-Typen. Der Adapter materialisiert nur Attribute; die Runtime-Entscheidung bleibt im SurfaceManager.
+
+## Keine konkurrierenden Lifecycle-Quellen
+
+Standalone `x-side-panel route-aware` behaelt seinen alten Fallback. Sobald ein Panel aber von `x-surface-manager` verwaltet wird, delegiert es Routewechsel an den Manager. Damit gibt es fuer verwaltete Surfaces keine konkurrierenden Lifecycle-Quellen.

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

@@ -0,0 +1,69 @@
+# SurfaceManager Runtime Release Handoff
+
+`WP-SM-19` finalisiert die Surface Runtime als produktive XTend-UI-Schicht fuer App Shells. Der Contract `xtend.surface.runtime-release-handoff.v1` buendelt die Arbeit aus `WP-SM-10` bis `WP-SM-18` und macht den Runtime-Claim lokal gatebar.
+
+## Produktive 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` |
+
+Der abschliessende Gate ist:
+
+```bash
+node scripts/run_xtend_tests.js surface-runtime-release-handoff --json
+```
+
+## Authoring
+
+Neue komplexe App Shells sollen native `surfaces[*]` nutzen. `components[*].metadata.surface` bleibt als Compatibility-Pfad bestehen, vor allem fuer bestehende Fixtures und additive Migrationen.
+
+Der produktive Pfad ist:
+
+1. Surface Records in `surfaces[*]` modellieren.
+2. Component Records als Manager- und Content-Bindings referenzieren.
+3. Route, Schedule, State Key und Restore Key stabil halten.
+4. `surface-adapter-runtime` und `surface-native-materialization` pruefen.
+5. App-Shell-Stabilitaet ueber `surface-browser-lab` pruefen.
+
+## Release Gate Matrix
+
+Der Runtime-Handoff erwartet die bestehende Baseline plus die gehaertete Runtime-Linie:
+
+```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` haelt fest:
+
+- bestehende Component-Metadata-Surfaces bleiben lauffaehig
+- die Workbench- und Browser-Lab-Fixtures bleiben im Gate
+- Docs-App Parsedown bleibt Host-Boundary und wird nicht in SurfaceManager verschoben
+- Remote Runtime Loading bleibt ausserhalb des RMT-Kernels
+- SurfaceManager ersetzt weder Fabric noch den RMT Kernel
+- SurfaceController bleibt die einzige Registry
+
+## Offene Scopes
+
+Diese Punkte sind bewusst nicht Teil des Runtime-Claims:
+
+- `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
+
+Die Klassifizierung fuer den aktuellen Stand lautet `0.x-minor-with-migration-notes`. Vor externem Publish bleiben Release-Owner-Signoff, Changelog und die allgemeine Release Checklist erforderlich.

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

@@ -0,0 +1,36 @@
+# SurfaceManager SidePanel Runtime
+
+`WP-SM-04` fuehrt `x-side-panel` als native Surface-Komponente ein. Der Contract `xtend.surface.side-panel-runtime.v1` erweitert die Window Runtime um App-Shell-nahe SidePanels mit Docking, Pinning, Collapse, Overlay und responsive Fullscreen-Verhalten.
+
+## Komponenten
+
+- `x-surface-manager`: erkennt `x-side-panel` im `panels`-Slot und verarbeitet `surface-panel-command`.
+- `x-side-panel`: erzeugt `xtend.surface.record.v1` mit `type: "side-panel"`.
+- `components/xsurfacemanager-controller.js`: bleibt die einzige Registry- und Snapshot-Wahrheit.
+
+## Modes
+
+| Mode | Einsatz |
+|------|---------|
+| Docked | dauerhafte App-Shell-Seitenleiste |
+| Pinned | geoeffnetes, persistentes Panel |
+| Overlay | temporaeres Panel ueber dem Workspace |
+| Collapsed | kompakte Panel-Leiste |
+| Fullscreen | responsive Fallback fuer kleine Viewports |
+
+Placements: `left`, `right`, `bottom`, `inline`.
+
+## Commands
+
+`x-side-panel` sendet `surface-panel-command` mit `open`, `close`, `focus`, `resize`, `pin`, `unpin`, `collapse`, `expand`, `dock`, `restore` oder `update`.
+
+Der Manager mappt diese Commands auf `openSurface`, `closeSurface`, `focusSurface`, `resizeSurface`, `updateSurface`, `pinSurface`, `collapseSurface`, `expandSurface`, `dockSurface` und `restoreSurface`.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js surface-side-panel --json
+npm run test:surface-side-panel -- --json
+```
+
+`WP-SM-05` baut darauf das RMT-first Workbench Fixture mit zwei Windows, SidePanel, route-bound Content und shared Surface Snapshot.