@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/de/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/de/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/de/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/de/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/de/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/de/surface-manager-rmt-authoring.md

@@ -0,0 +1,102 @@
+# SurfaceManager RMT Authoring
+
+Docs Contract: `xtend.docs.surface-manager-rmt-authoring.v1`
+
+Der SurfaceManager ist der 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
+
+Neue SurfaceManager-Beispiele werden vNext-first geschrieben. Der Compiler kann
+daraus weiterhin vorhandene RMT `components` Records mit
+`metadata.surfaceManager` und `metadata.surface` erzeugen:
+
+```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` und eine native RMT `surfaces` Domain bleiben die Runtime-
+Projektion dieses vNext-Pfads. Legacy `components[*].metadata.surface` ist
+Migrationsquelle und Mirror, aber nicht mehr die bevorzugte Schreibform.
+
+## 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. Die naechste Dokumentationslinie sollte dieselbe
+Workbench als RMT-vNext-Draft zeigen und die Records nur noch als
+Compiler-/Compatibility-Output fuehren.
+
+## 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/de/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/de/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/de/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.

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

@@ -0,0 +1,39 @@
+# SurfaceManager Stack Policy
+
+Ab `WP-SM-15` besitzt `x-surface-manager` den Contract `xtend.surface.stack-policy.v1` fuer gemischte Surface-Stacks aus Windows, SidePanels, Dialogen, Modals und Drawern.
+
+## Ziel
+
+`modal-policy` wird produktiv auf Manager-Ebene ausgewertet. Der SurfaceController bleibt die Registry-Quelle, waehrend der Manager die UI-nahe Stack-Policy auf vorhandene XTend-Komponenten anwendet:
+
+- `snapshotStackPolicy()` liefert den aktuellen Report `xtend.surface.stack-policy-report.v1`.
+- `applyStackPolicy()` wendet Layer Tokens, aktive Modalitaet, Inert, `aria-hidden`, `aria-modal`, Focus Trap, Focus Restore, Escape-Prioritaet und Scroll Lock an.
+- bestehende Overlay-Komponenten behalten ihre lokalen APIs und Focus-/Escape-Implementierungen.
+
+## Modal Policies
+
+| Policy | Wirkung |
+|--------|---------|
+| `topmost` | die oberste modale Surface erhaelt aktive Modalitaet |
+| `none` | keine Manager-Modalitaet, keine Inert- oder Scroll-Lock-Regel |
+| `all-modal` | jede offene Surface kann als modal behandelt werden, aktiv ist die oberste |
+| `surface-modal` | alle als modal deklarierten Surfaces werden erkannt, aktiv ist die oberste modale Surface |
+
+## Laufzeitregeln
+
+- Focus Restore: Beim Aktivieren einer modalen Surface merkt sich der Manager das vorherige Fokusziel und stellt es nach Close wieder her.
+- Inert: Hintergrund-Surfaces erhalten `data-surface-inert="manager"`, `inert` und `aria-hidden`, solange eine aktive modale Surface existiert.
+- Escape: Ein dokumentweiter Capture-Handler schliesst die aktive modale Surface oder sonst die oberste schliessbare Surface.
+- Scroll Lock: Aktive Modalitaet setzt `data-xtend-surface-scroll-lock` auf `html` und `body`.
+- Layer Tokens: Jede Surface erhaelt `data-surface-layer-token`, `--surface-layer-z` und kompatible Komponenten-Z-Variablen.
+- Diagnostics: fehlende Labels, fehlende Fokusziele und Modalitaet unterhalb nicht-modaler Surfaces werden im Stack-Policy-Report sichtbar.
+
+## Boundary
+
+Die Stack Policy ist eine unterstuetzende XTend-UI-Schicht. Sie erzeugt keine zweite Registry, ersetzt weder Fabric noch den RMT Kernel und veraendert nicht die SurfaceController-Wahrheit. RMT kann `modal-policy` deklarieren, aber die Laufzeitentscheidung bleibt beim `x-surface-manager`.
+
+Lokaler Gate:
+
+```bash
+node scripts/run_xtend_tests.js surface-stack-policy --json
+```

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

@@ -0,0 +1,47 @@
+# SurfaceManager Window Runtime
+
+`WP-SM-03` macht den SurfaceManager erstmals sichtbar: `x-surface-manager` verwaltet den Controller und `x-surface-window` ist die erste 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`
+
+## Beispiel
+
+```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` bietet `registerSurface`, `openSurface`, `closeSurface`, `focusSurface`, `updateSurface`, `moveSurface`, `resizeSurface`, `minimizeSurface`, `maximizeSurface`, `restoreSurface` und `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` bietet `toSurfaceRecord`, `applySurfaceSnapshot`, `openWindow`, `closeWindow`, `focusWindow`, `minimizeWindow`, `maximizeWindow` und `restoreWindow`.
+
+Das Element sendet `surface-window-command`. Der Manager fuehrt daraus die Controller-Operation aus und spiegelt den Snapshot zurueck.
+
+## Handoff
+
+`WP-SM-04` erweitert diese Runtime um `x-side-panel` und responsive Surface Modes. Die Window-Runtime bleibt der erste Multi Window Beweis und darf keine zweite Registry neben dem Controller einfuehren.

package/docs/de/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` fuehrt die erste RMT-first Workbench fuer den SurfaceManager ein. Sie rendert eine App Shell aus RMT, bindet den SurfaceManager an eine Route und zeigt zwei Windows plus SidePanel mit gemeinsamem Snapshot.
+
+## Artefakte
+
+| Pfad | Zweck |
+|------|-------|
+| `xtendrmt/surface-workbench.rmt` | RMT-Dokument mit App Shell, Route, SurfaceManager, zwei Windows, SidePanel und Content |
+| `tests/browser/fixtures/rmt-surface-workbench-smoke.html` | Host-/Smoke-Fixture ohne manuelle Surface-Komponenten |
+| `xtendrmt/surface-workbench.js` | Workbench Renderer fuer `dom_descriptor`, Slots, Routes und Snapshot |
+| `tests/browser/fixtures/rmt-surface-workbench-smoke.html` | vorbereiteter Browser-Smoke fuer spaetere Surface-Gates |
+
+## Modell
+
+Die Workbench nutzt weiter den MVP-Pfad aus `xtend.rmt.surface-authoring.v1`: Surfaces sind normale `components` Records mit `metadata.surface`. Die native RMT `surfaces` Domain bleibt reserviert.
+
+Enthalten sind:
+
+- `workbench.manager` als `x-surface-manager`
+- `workbench.inspector` und `workbench.editor` als zwei Windows
+- `workbench.properties` als `x-side-panel`
+- `app.router` als route-bound Outlet
+- `workbench` als Route fuer Surface Content
+- `xtend.surface.snapshot` als shared Surface Snapshot Key
+
+## Runtime
+
+`xtendrmt/surface-workbench.js` rendert nur strukturierte DOM Nodes. Der Renderer verwendet kein `innerHTML`, sondern `renderDomDescriptor`, `renderSurfaceWorkbenchFromDocument` und `root.replaceChildren(shellFragment)`.
+
+Der Snapshot wird ueber `collectSurfaceSnapshot(root)` gelesen. Wenn `x-surface-manager.snapshot()` verfuegbar ist, kommt der Snapshot direkt vom Manager; andernfalls liefert das Fixture einen DOM-Fallback fuer statische Gates.
+
+## Gate
+
+```bash
+node scripts/run_xtend_tests.js surface-workbench-fixture --json
+```
+
+Der Gate prueft Contract, RMT-Normalisierung, Host-Boundary, Runtime-Boundary, route-bound Content, zwei Windows, SidePanel, shared Surface Snapshot, Package-/Scaffold-Metadaten, Docs und Runner-Registrierung.