@ccslabs/xtend 0.1.0-rc.1

package/docs/rmt-vnext-remote-surfaces.md

@@ -0,0 +1,90 @@
+# RMT vNext Remote Surfaces
+
+RMT vNext beschreibt Remote Surfaces als deklarative Enterprise-MFE-Contracts.
+Der RMT-Kernel fuehrt keine Remote Runtime aus und laedt keine Netzwerkquellen.
+Hosts koennen aus dem Contract konkrete Loader-, Mount-, Sandbox- und Rollback-
+Entscheidungen ableiten.
+Boundary: no-remote-runtime-execution-in-rmt-kernel.
+
+## Contract
+
+```js
+schema: "xtend.rmt.vnext-remote-surface.v1"
+manifestSchema: "xtend.rmt.vnext-remote-surface-manifest.v1"
+securitySchema: "xtend.rmt.vnext-remote-security-policy.v1"
+compilerSchema: "xtend.rmt.vnext-remote-compiler.v1"
+```
+
+Eine Remote Surface muss explizit deklarieren:
+
+- `owner` als verantwortliches Team oder Produkt.
+- `version` und `versionRange` fuer aktive und erwartete Versionen.
+- `origin` und `integrity` fuer Manifest- und Artefaktbindung.
+- `trustBoundary` und Sandbox-/CSP-Anforderungen.
+- `fallback` auf eine lokale Surface oder ein blockierendes Verhalten.
+- `exposes` als Lane- und Shell-Target-Bindings.
+- `emits` und `consumes` als typisierte Cross-Surface-Events.
+
+## Authoring
+
+```rmt
+remote surface checkout.cart from remote "@xtend/checkout-cart" {
+  owner: "checkout-platform"
+  version: "^3.1.0"
+
+  remote {
+    origin: "https://mfe.xtend.invalid/checkout"
+    integrity: "sha256-demo-integrity"
+  }
+
+  trust boundary enterprise.remote.strict {
+    sandbox: ["allow-scripts"]
+    capabilities: ["surface.mount", "event.emit", "event.consume"]
+  }
+
+  exposes {
+    critical -> shell.slot:sidebar.cart
+    idle -> shell.slot:background.prefetch
+  }
+
+  fallback surface panel.checkoutFallback
+
+  emits checkout.cart.updated.v1 {
+    owner: "checkout-platform"
+    payload: "xtend.schemas.cartUpdated.v1"
+    scope: lane critical -> shell.slot:sidebar.cart
+  }
+
+  consumes user.session.changed.v1 {
+    owner: "identity-platform"
+    payload: "xtend.schemas.userSessionChanged.v1"
+    scope: shell -> checkout.cart
+  }
+}
+```
+
+Das Beispiel ist absichtlich JSON-nah: alle fachlichen Fakten koennen stabil in
+Core JSON serialisiert werden. Die Sprache bleibt dabei lesbar genug fuer
+Produktteams und strikt genug fuer Gate-Suites.
+
+## Boundaries
+
+- Kein Remote-Code wird im RMT-Kernel ausgefuehrt.
+- Kein Netzwerkzugriff ist fuer Language-Layer-Gates erlaubt.
+- Remote Surfaces sind deny-by-default, bis Owner, Version, Integrity,
+  Trust Boundary und Fallback vollstaendig sind.
+- SurfaceManager bleibt Runtime-Orchestrierung; `surface.registry` bleibt der
+  deklarative Enterprise-MFE-Index.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-remote-manifest --json
+node scripts/run_xtend_tests.js rmt-vnext-remote-security --json
+node scripts/run_xtend_tests.js rmt-vnext-remote-compiler --json
+node scripts/run_xtend_tests.js rmt-vnext-remote-compatibility --json
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-release --json
+```
+
+Die Enterprise Demo liegt in `xtendrmt/rmt-vnext-enterprise-mfe-demo.rmt`; der
+byte-stabile Core Output liegt in `xtendrmt/rmt-vnext-enterprise-mfe-demo.core.json`.

package/docs/rmt-vnext-surface-registry-enterprise.md

@@ -0,0 +1,76 @@
+# RMT vNext Enterprise Surface Registry
+
+`surface.registry` ist der gemeinsame Enterprise-MFE-Index fuer lokale und
+remote Surfaces. Er ist kein Runtime-Manager und kein globaler Event Bus,
+sondern ein auditierbarer Snapshot fuer Ownership, Discoverability, aktive
+Versionen, Shell Targets, Lanes, Fallbacks und Event-Fakten.
+
+## Contract
+
+```js
+schema: "xtend.rmt.vnext-enterprise-surface-registry.v1"
+surfaceSchema: "xtend.rmt.vnext-enterprise-surface.v1"
+targetReadiness: "rmt-vnext-enterprise-mfe-ready"
+```
+
+Der Registry-Snapshot beantwortet die Enterprise-Fragen:
+
+- Welche Surfaces existieren zur Laufzeit?
+- Welches Team besitzt welche Surface?
+- Welche Version ist aktiv und welche Range wurde erwartet?
+- Welche Shell Targets und Lanes sind gebunden?
+- Welche Surfaces sind lokal, remote oder Fallback?
+- Welche Events duerfen eine Surface verlassen oder erreichen?
+- Welche Degradation-Policy gilt bei Inkompatibilitaet?
+
+## Registry Shape
+
+```json
+{
+  "schema": "xtend.rmt.vnext-enterprise-surface-registry.v1",
+  "registryId": "enterprise:xtend.enterprise-mfe.demo",
+  "surfaceCount": 4,
+  "localSurfaceCount": 3,
+  "remoteSurfaceCount": 1,
+  "indexes": {
+    "byOwner": {
+      "checkout-platform": ["surface:panel.checkoutFallback", "remote:checkout.cart"]
+    },
+    "byShellTarget": {
+      "shell.slot:sidebar.cart": ["remote:checkout.cart"]
+    }
+  }
+}
+```
+
+Die Registry darf von Hosts und Operations-Tools gelesen werden. Sie bleibt aber
+ein Language-Layer-Artefakt und erzeugt keine impliziten Runtime-Verbindungen.
+
+## Ownership
+
+Jede Surface braucht einen fachlichen Owner. Der Owner verantwortet:
+
+- Version Range und aktive Version.
+- Fallback-Flaeche oder blockierenden Degradation-Pfad.
+- Event Ownership und Payload Ownership.
+- Security Policy und Trust Boundary.
+- Migrationshinweise fuer Legacy-Surface-Fakten.
+
+## Discoverability
+
+Discoverability entsteht ueber stabile Indizes, nicht ueber Laufzeit-Heuristik.
+Die Registry muss mindestens nach Surface Name, Owner, Shell Target, Lane,
+Status, Remote ID und Fallback aufloesbar sein. Das Demo-Szenario validiert dies
+ueber `tools/rmt-language/vnext-enterprise-fixtures.js`.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-registry --json
+node scripts/run_xtend_tests.js rmt-vnext-degradation --json
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-fixtures --json
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-release --json
+```
+
+Der operative Handoff ist in `docs/rmt-vnext-enterprise-mfe-handoff.md`
+zusammengefasst.

package/docs/screenreader-signals.md

@@ -0,0 +1,56 @@
+# Screenreader Signals
+
+- Contract: `xtend.docs.screenreader-signals.v1`
+- Runtime-/Gate-Contract: `xtend.a11y.screenreader-signals.v1`
+- Signal Record: `xtend.a11y.screenreader-signal.v1`
+- Gate: `node scripts/run_xtend_tests.js screenreader-signals --json`
+
+## Zweck
+
+Screenreader-Signale machen sichtbar, welche UI-Zustandswechsel nicht still bleiben duerfen. Der Contract beschreibt `aria-live`, Statusregionen, Errorregionen und Announcements, ohne eine bestimmte UI-Runtime in XTendRMT einzubetten.
+
+XTend nutzt den Contract fuer Komponenten und Scaffold-Artefakte. XTendRMT kann die resultierende A11y-Arbeit ueber Fabric-Lane `a11y`, Fiber `a11y.announce` und Schedule `a11y.user-blocking.announce` schedulen.
+
+## Signalarten
+
+| Signal | Live Region | Region | Typischer Einsatz |
+|--------|-------------|--------|-------------------|
+| `status-announcement` | `polite` | `status` | Toasts, Alerts, Submit-Erfolg |
+| `dismissal-announcement` | `polite` | `status` | Toast/Alert wurde geschlossen |
+| `validation-error-summary` | `assertive` | `error` | Formular- oder Input-Fehler |
+| `submit-status` | `polite` | `status` | Formular erfolgreich verarbeitet |
+| `dialog-context` | `none` | `dialog` | Dialog-/Modal-Kontext via Rolle und Label |
+| `focus-return` | `none` | `focus` | Fokus geht nach Overlay-Schluss zur Quelle zurueck |
+| `route-change-announcement` | `polite` | `status` | Route wurde gewechselt |
+
+## Komponentenpflichten
+
+Feedback-Komponenten deklarieren Statussignale und setzen eine Live-Region. Fehlerzustaende duerfen assertiv sein, muessen aber reviewbar bleiben.
+
+Form-Komponenten deklarieren mindestens `validation-error-summary` und `submit-status`. Errorregionen brauchen eine klare Quelle und duerfen leere Announcements nicht als Erfolg werten.
+
+Overlay-Komponenten deklarieren `dialog-context` und `focus-return`. Sie brauchen nicht zwingend `aria-live`, weil der Screenreader-Kontext ueber `role="dialog"`, `aria-modal`, `aria-labelledby` und Fokusmanagement entsteht.
+
+## Scaffold
+
+Neue Scaffold-Komponenten enthalten den Screenreader-Contract in:
+
+- `xtendScaffoldA11yProfile.screenreader.signalContract`
+- Manifest-Key `screenreaderSignals`
+- Component-Doku Abschnitt `Screenreader-Signale`
+- Fixture-Ergebnis `screenreaderSignals`
+- Type Contract `ScreenreaderSignalContract`
+
+## Verifikation
+
+```bash
+npm run test:screenreader-signals
+node scripts/run_xtend_tests.js screenreader-signals --json
+node scripts/run_xtend_tests.js a11y-hydration --json
+```
+
+Der Gate prueft die Contract-Fabrik, reale Feedback-/Form-/Overlay-Komponenten, Scaffold-Ausgaben und Package-Metadaten.
+
+## Grenzen
+
+Der Contract ist kein Ersatz fuer manuelle Screenreader-Abnahme. Er verhindert aber, dass relevante Status-, Fehler- oder Overlay-Signale unbenannt bleiben.

package/docs/supply-chain-gates.md

@@ -0,0 +1,100 @@
+# XTend Supply-Chain Gates
+
+- Status: Active ab `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`
+
+## Uebersicht
+
+XTend ist fuer RC1-Publish-Prep als scoped Public-Package-Flaeche vorbereitet. Supply-Chain-Gates kontrollieren dafuer Dependencies, Lizenzen, Vulnerabilities, SBOM, Provenance und die installierbare Package-Oberflaeche.
+
+Der lokale Default-Pfad ist offline und reproduzierbar. Er fragt keine npm Registry ab.
+
+## Lokale Checks
+
+```bash
+node scripts/verify_supply_chain_policy.js --json
+node scripts/run_xtend_tests.js supply-chain --json
+npm run test:supply-chain
+```
+
+Der Verify prueft:
+
+- `private: false` fuer RC1-Publish-Prep
+- `license: "Apache-2.0"` fuer den kompletten XTend-Stack
+- `publishConfig.provenance = true`
+- Export von `security/supply-chain-gate-policy.js`
+- Release-Gate-Metadaten in `package.json`
+- Dependency-Inventar und Lockfile-Pflicht
+
+## CI-/Release-Stufen
+
+Diese Kommandos sind fuer CI und Release Automation geplant:
+
+```bash
+npm audit --audit-level=moderate
+npm sbom --sbom-format=cyclonedx --json
+npm run release:report
+npm run pack:dry-run
+```
+
+`npm audit` und `npm sbom` koennen Netzwerkzugriff benoetigen. Sie gehoeren deshalb nicht in den lokalen Default-Test, sondern in kontrollierte CI-/Release-Stufen.
+
+## License Policy
+
+Der komplette XTend-Stack ist auf `Apache-2.0` gesetzt. Fuer RC1-Publish-Prep ist `private: false` gesetzt; der eigentliche `npm publish` bleibt ein separater Owner-Schritt.
+
+Die scoped Release-Manifests sind Teil des Supply-Chain-Gates:
+
+| 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` |
+
+Ein oeffentlicher Release braucht vorher:
+
+- bestaetigte Apache-2.0 License-Entscheidung
+- Dependency-License-Inventar
+- Review aller nicht-permissiven Dependency-Lizenzen
+- Ausschluss von AGPL/GPL/UNLICENSED als Default-Third-Party-Abhaengigkeiten
+
+## Vulnerability Policy
+
+- `critical` blockiert jeden Release.
+- `high` blockiert Release Candidates.
+- Production-Findings ab `moderate` muessen triagiert werden.
+- bekannte Exploits duerfen nicht in Release Candidates verbleiben.
+
+## Maschinenlesbare Policy
+
+```js
+const {
+  createSupplyChainGatePlan,
+  classifyPackageSupplyChain
+} = require('./security/supply-chain-gate-policy');
+```
+
+Die Policy selbst liegt in:
+
+```text
+security/supply-chain-gate-policy.js
+```
+
+Der lokale Report nutzt:
+
+```text
+xtend.security.supply-chain-report.v1
+```
+
+## Weiterfuehrende Dokumente
+
+- [XTend Loader](./xtend-loader.md)
+- [Trusted DOM und Sanitizing](./trusted-dom-sanitizing.md)
+- [XTend-Fabric Runtime](./xtend-fabric.md)

package/docs/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`
+
+## Ziel
+
+Dieser Guide beschreibt den empfohlenen Authoring-Pfad fuer XTend App Shells mit SurfaceManager. Er verbindet den fruehen Component-Metadata-Pfad aus `WP-SM-01` mit der nativen RMT `surfaces` Domain aus `WP-SM-08`.
+
+## Authoring-Modi
+
+| Modus | Wann nutzen | Quelle |
+|-------|-------------|--------|
+| `component-metadata-mvp` | Kleine Shells, bestehende Component Records, schnelle Migration | `components[*].metadata.surface` |
+| `dual-record-handoff` | Uebergang, Tooling-Vergleich, Regression gegen bestehende Runtime | `components[*].metadata.surface` plus `surfaces[*]` |
+| `native-surfaces-preferred` | Komplexe App Shells, Multi Window, Panels, Overlay Stack | `surfaces[*]` als fachliche Surface-Quelle |
+
+## Component-Metadata bleibt gueltig
+
+Bestehende RMT Component Records bleiben kompatibel:
+
+```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"
+    }
+  }
+}
+```
+
+Dieser Modus reicht, wenn eine App Shell ueber `x-surface-manager` bereits korrekt laeuft und keine native RMT Surface-Domain fuer Tooling, Migration oder Cross-Record-Validierung gebraucht wird.
+
+## Native Surfaces bevorzugen
+
+Fuer neue komplexe Shells ist `surfaces[*]` der Zielzustand:
+
+```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-Regeln:
+
+- `manager` referenziert den `x-surface-manager` Component Record.
+- `component` referenziert die sichtbare Surface-Komponente.
+- `route` bindet die Surface an den App-Shell-Kontext.
+- `schedule` bindet Open, Layout, Persistenz oder Diagnostics an RMT Scheduling.
+- `stateKey` bleibt stabil zwischen Component-Metadata und nativer Domain.
+- Historisch blieb `xtend.surface` bis `WP-SM-19` ein Adapter-Handoff; seit dem Runtime-Handoff ist der produktive Adapter-Claim gatebar, waehrend die sichtbare UI weiterhin ueber die SurfaceManager-Komponentenfamilie materialisiert wird.
+
+## Release-Handoff
+
+Nach `WP-SM-09` galt fuer den historischen Authoring-Handoff:
+
+- Component-Metadata ist stabiler Compatibility-Pfad.
+- Native `surfaces[*]` ist der bevorzugte Authoring-Pfad fuer neue App Shells.
+- Dual Records sind der sichere Migrationsmodus.
+- Der RMT Kernel bleibt host-neutral.
+- Die produktive `xtend.surface` Adapter Runtime war Folgearbeit und ist seit `WP-SM-19` umgesetzt.
+
+## WP-SM-19 Runtime Authoring
+
+Ab `WP-SM-19` ist die produktive `xtend.surface` Adapter Runtime umgesetzt und ueber `xtend.surface.runtime-release-handoff.v1` gatebar. Fuer neue komplexe App Shells bleibt `native-surfaces-preferred` der Default: `surfaces[*]` beschreibt die fachlichen Surfaces, waehrend Component Records die sichtbaren XTend-UI-Bindings liefern.
+
+Produktive Authoring-Regeln:
+
+- `surfaces[*]` ist die Quelle fuer neue Multi-Surface-App-Shells.
+- `components[*].metadata.surface` bleibt fuer bestehende Shells und Dual-Record-Migrationen kompatibel.
+- `x-surface-manager` und der SurfaceController bleiben die Runtime-Registry.
+- Fabric, XRouter, `xstate` und RMT-Kernel bleiben eigenstaendige Schichten.
+- `node scripts/run_xtend_tests.js surface-runtime-release-handoff --json` prueft den finalen Runtime-Handoff.
+
+Details stehen im [SurfaceManager Runtime Release Handoff](./surface-manager-runtime-release-handoff.md).

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

@@ -0,0 +1,45 @@
+# SurfaceManager Browser Lab
+
+`WP-SM-18` ergaenzt die SurfaceManager-Schicht um ein browsernahes Lab fuer echte App-Shell-Stabilitaet. Der Contract `xtend.surface.browser-lab.v1` bleibt bewusst framework-nativ: Das Fixture nutzt `x-surface-manager`, `x-surface-window`, `x-side-panel`, `x-modal`, den `SkeletonLoader` aus dem Loader und die bestehende Surface-Hydration. Es ist keine Doku-App-Sonderloesung und kein Monkeypatch.
+
+## Artefakte
+
+| Artefakt | Pfad |
+| --- | --- |
+| 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` |
+
+Die Visual Baseline verwendet `xtend.surface.browser-lab.visual-baseline.v1`. Sie ist JSON-basiert und pixel-ready: spaetere Browser-Lab-Laeufe koennen echte Snapshot-Dateien anhaengen, waehrend der lokale Fast-Gate bereits DOM-Signaturen, States und Budgets prueft.
+
+## Gate-Zustaende
+
+Das Fixture deckt fuenf reproduzierbare Zustaende ab:
+
+| Snapshot | Zustand |
+| --- | --- |
+| `surface-lab-cold-start` | App Shell sichtbar vor Content-Hydration |
+| `surface-lab-skeleton` | Parsedown-Content hinter SkeletonLoader verborgen |
+| `surface-lab-hydrated` | Content freigegeben, Skeleton entfernt |
+| `surface-lab-route-change` | Route-bound Surface ohne Shell-Resize |
+| `surface-lab-modal-stack` | Modal Stack ueber SurfaceManager-Policy |
+
+## Regressionen
+
+Der Report verbindet `xtend.surface.browser-lab.performance-report.v1` und `xtend.surface.browser-lab.cls-report.v1`. Lokal muessen folgende Risiken fehlschlagen:
+
+| Risiko | Budget |
+| --- | --- |
+| CLS | `<= 0.01` |
+| Layout Shift | `<= 1px` |
+| Pop-In von ungestyltem Content | `0` |
+| Open/Focus | `<= 16ms` |
+| Route | `<= 32ms` |
+| Hydrate | `<= 120ms` |
+
+## App-Shell-Proben
+
+Das Lab referenziert die Docs-App ueber `docs/index.php` und den Parsedown/RMT-Pilot `docs/xtendrmt-parsedown-docs.rmt`. Zusaetzlich bleibt `tests/browser/fixtures/rmt-surface-workbench-smoke.html` als Referenz-Workbench im Gate. Dadurch prueft WP-SM-18 den produktnahen App-Shell-Pfad, ohne Parsedown, PHP oder Workbench-spezifisches Verhalten in den SurfaceManager zu verschieben.
+
+Der SurfaceManager bleibt eine unterstuetzende XTend-UI-Schicht. Er erzeugt keine zweite Registry, ersetzt nicht Fabric oder den RMT-Kernel und laedt keine Remote Runtime im Kernel.

package/docs/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`
+
+## Zweck
+
+Das SurfaceManager Component Lab ist die statische Lab-Fixture fuer die SurfaceManager-Linie. Es zeigt, wie eine App Shell mit `x-surface-manager`, `x-surface-window`, `x-side-panel`, einem kompatiblen Dialog und nativen `surfaces[*]` Records beschrieben wird.
+
+Die Fixture ist kein neuer Lab-Server. Sie erweitert den bestehenden Component-Lab-Gedanken um Surface-spezifische Authoring- und Migrationssicht.
+
+## Panels
+
+| Panel | Aufgabe |
+|-------|---------|
+| `surface-preview` | sichtbare Surface Shell mit WindowManager- und SidePanel-Komponenten pruefen |
+| `native-rmt-inspector` | `surfaces[*]`, `adapters`, `components`, `routes` und `schedules` inspizieren |
+| `migration-diff` | `components[*].metadata.surface` mit nativen Surface Records vergleichen |
+| `quality-gates` | Gate-Kette von `surface-manager-quality` bis `surface-native-rmt` sichtbar machen |
+| `source-links` | Doku-, Katalog-, Fixture-, Runtime- und Suite-Pfade verlinken |
+
+## Fixture-Modell
+
+`tests/fixtures/rmt-surface-manager-component-lab.rmt` enthaelt:
+
+- vier Adapter: `xtend.component`, `xtend.xrouter`, `rmt.state-scheduler-diagnostics`, `xtend.surface`
+- eine SurfaceManager-Komponente `surface.lab.manager`
+- zwei Windows: `surface.lab.preview` und `surface.lab.rmtInspector`
+- zwei SidePanels: `surface.lab.migrationPanel` und `surface.lab.qualityPanel`
+- einen Dialog: `surface.lab.commandDialog`
+- native `surfaces[*]` Records plus passende `components[*].metadata.surface` Dual Records
+
+Die Fixture prueft die Authoring-Boundary. Sie behauptet keine produktive `xtend.surface` Runtime.
+
+## Lokaler Ablauf
+
+```bash
+node scripts/run_xtend_tests.js surface-release-handoff --json
+```
+
+Der Gate validiert die Fixture ueber RMT-Normalisierung und Semantic Graph. Damit bleiben Surface-IDs, Component-Refs, Manager-Refs, Routes und Schedules sichtbar und maschinenpruefbar.

package/docs/surface-manager-controller.md

@@ -0,0 +1,66 @@
+# SurfaceManager Controller
+
+`WP-SM-02` fuehrt den internen Surface Controller fuer XTend ein. Er ist der lauffaehige Unterbau fuer Multi Window Oberflaechen, aber noch kein sichtbares 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`
+
+## Rolle
+
+Der Controller verwaltet Surface Records aus dem `WP-SM-01` Authoring-Modell. RMT kann also weiterhin normale Component Records mit `metadata.surface` beschreiben; der Controller normalisiert diese Records zu einer Laufzeit-Registry.
+
+Er ist bewusst `controller-only-no-custom-element`. `WP-SM-03` baut darauf `x-surface-manager` und `x-surface-window`.
+
+## API
+
+Wichtige Methoden:
+
+```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();
+```
+
+Unterstuetzt werden `registerSurface`, `openSurface`, `closeSurface`, `focusSurface`, `updateSurface`, `moveSurface`, `resizeSurface`, `minimizeSurface`, `maximizeSurface`, `restoreSurface`, `snapshot` und `dispose`.
+
+## State
+
+Nach jedem Commit spiegelt der Controller:
+
+```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
+```
+
+Der Snapshot enthaelt nur Layout-, Lifecycle- und UI-State. Raw Metadata, DOM Nodes und Content-Payloads werden nicht serialisiert.
+
+## Diagnostics
+
+Wenn Fabric uebergeben wird, sendet der Controller `xtend.surface.diagnostic.v1` Events ueber `emitDiagnostic`. Ohne Fabric bleibt der Controller trotzdem lauffaehig und spiegelt Diagnostics nach xstate.
+
+## Naechster Schritt
+
+`WP-SM-03` sollte die sichtbare Komponentenfamilie auf diesem Controller aufbauen: `x-surface-manager`, `x-surface-window`, erste Layer-Container, Events und echte Window-Chrome.

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

@@ -0,0 +1,32 @@
+# SurfaceManager Layout Engines
+
+Ab `WP-SM-16` besitzt `x-surface-manager` den Contract `xtend.surface.layout-engine.v1` fuer sichtbare, snapshot-kompatible Surface Layouts.
+
+## Engines
+
+| Engine | Zweck |
+|--------|-------|
+| `freeform` | freie Fenster mit Viewport-Clamp, Snap und einfacher Kollisionskorrektur |
+| `docked` | SidePanels und docked Surfaces belegen Ränder, Workspace-Surfaces fuellen den Rest |
+| `split` | offene Layout-Surfaces werden als Split Panes verteilt |
+| `tile` | offene Layout-Surfaces werden in einem Raster verteilt |
+| `stacked` | offene Layout-Surfaces werden als versetzter Stack dargestellt und als kompakter Fallback genutzt |
+
+## Runtime
+
+- `snapshotSurfaceLayout()` liefert `xtend.surface.layout-engine-report.v1`.
+- `applyLayoutEngine(engine)` schreibt berechnete Bounds ueber den bestehenden SurfaceController in den Snapshot.
+- `dockSurface()` setzt Placement/Mode und wendet eine docked oder aktuell aktive Layout Engine sichtbar an.
+- `undockSurface()` setzt eine Surface auf `floating` und laesst sie wieder im Freeform-Modus laufen.
+- `surface-layout-gap` und `surface-layout-snap` steuern Abstaende und Snap-Raster.
+- kompakte Viewports fallen auf `stacked` zurueck.
+
+## Boundary
+
+Die Layout Engine bleibt eine XTend-UI-Unterstuetzungsschicht. Der SurfaceController bleibt Registry- und Snapshot-Quelle, Fabric bleibt fuer Diagnostics/Backpressure zustaendig, und der RMT Kernel importiert keine XTend-Typen. Es entsteht keine zweite Registry.
+
+Lokaler Gate:
+
+```bash
+node scripts/run_xtend_tests.js surface-layout-engines --json
+```

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

@@ -0,0 +1,63 @@
+# SurfaceManager Lazy Hydration
+
+Docs Contract: `xtend.docs.surface-manager-lazy-hydration.v1`
+
+`WP-SM-13` haertet `x-surface-manager` fuer shell-first Apps: Surface Chrome und App Shell koennen sofort sichtbar werden, waehrend Surface Content ueber den framework-nativen XTendLoader skeletonisiert, geladen und hydriert wird.
+
+## 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` am Manager setzt die Default-Policy. Einzelne Surfaces koennen sie mit `data-surface-hydration-policy` ueberschreiben.
+
+| Policy | Verhalten |
+|--------|-----------|
+| `eager` | Content wird direkt nach der Surface-Registrierung hydriert. |
+| `visible` | Content wird hydriert, sobald die Surface sichtbar ist. |
+| `open` | Content wird hydriert, wenn die Surface geoeffnet ist. |
+| `idle` | Content wird ueber `requestIdleCallback` oder Timeout-Fallback geladen. |
+| `route` | Content wartet auf Route-Signale wie `xtend-route-changed`. |
+
+## Runtime
+
+`x-surface-manager` nutzt keine Doku-App-Sonderloesung. Die Runtime greift auf die vorhandenen Loader-APIs zu:
+
+- `XTendLoader.ensureComponent`
+- `XTendLoader.hydrateTree`
+- `XTendLoader.showSkeleton`
+- `XTendLoader.hideSkeleton`
+- `XTendStyleRegistry.ensureRuntimeStyles`
+
+Vor der Hydration setzt der Manager `data-xtend-surface-content-ready="false"` und laesst den SkeletonLoader direkte Content-Kinder verdecken. Erst nach erfolgreichem Component-Ready- und `hydrateTree`-Gate wird der Skeleton entfernt. Bei Fehlern oder Timeouts bleibt der Skeleton aktiv, damit kein ungestylter Content aufpoppt.
+
+## Parsedown und Remote Slots
+
+Parsedown-Container und remote-faehige Slots sind normale Surface-Inhalte. Es gibt kein Monkeypatch in der Doku-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-faehige Slots koennen mit `data-remote-capable-content-slot="true"` markiert werden. Die Lazy-Hydration laedt dabei nur den DOM-/Komponenten-Scope; Remote Trust, Ownership und Capabilities bleiben spaeteren Remote-Surface-Policies vorbehalten.
+
+## Diagnostics
+
+Der Manager bietet:
+
+- `snapshotSurfaceLoading()`
+- `hydrateSurfaceContent(surfaceRef, options)`
+- Events `surface-content-loading`, `surface-content-hydrated`, `surface-content-hydration-skipped` und `surface-content-hydration-error`
+
+`snapshotSurfaceLoading()` meldet Policy, Skeleton-Status, Hydration-Status, Tags, unresolved Tags, Dauer und die Boundaries `shellFirst`, `protectsUnstyledContent` und `createsSecondRegistry: false`.