@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/de/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/de/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/de/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/de/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/de/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/de/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/de/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/de/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`.

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

@@ -0,0 +1,122 @@
+# 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 in RMT vNext authoriert werden. `surfaces[*]` ist der
+Runtime- und Compatibility-Output, nicht die neue Handarbeit.
+
+## 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-vnext-surfaces` | neue komplexe Shells als `surface ... component ...` in RMT vNext schreiben |
+| `close-xtend-surface-runtime-after-adapter-implementation` | historisches Adapter-Handoff aus `WP-SM-09` durch `WP-SM-19` Runtime-Gates schliessen |
+
+## vNext-Zielbild
+
+```rmt
+template workbench.surfaceMigration {
+  state workbench.properties type object initial null
+
+  portal surface.root root "#workbench-root" layer surface
+
+  surface surface.properties kind side-panel component x-side-panel {
+    source state workbench.properties
+    portal surface.root
+
+    lane visible weight 70 {
+      hydrate properties-panel from state workbench.properties
+    }
+  }
+}
+```
+
+## Vorher: Legacy Component Metadata
+
+```json
+{
+  "id": "workbench.properties",
+  "tag": "x-side-panel",
+  "metadata": {
+    "surface": {
+      "schema": "xtend.surface.record.v1",
+      "id": "surface.properties",
+      "type": "side-panel",
+      "manager": "workbench.manager",
+      "stateKey": "xtend.surface.properties.state"
+    }
+  }
+}
+```
+
+## Nachher: Dual Record als Runtime-Output
+
+```json
+{
+  "surfaces": [
+    {
+      "id": "surface.properties",
+      "schema": "xtend.surface.record.v1",
+      "type": "side-panel",
+      "adapter": "xtend.surface",
+      "manager": "workbench.manager",
+      "component": "workbench.properties",
+      "route": "workbench",
+      "schedule": "surface.visible.render",
+      "stateKey": "xtend.surface.properties.state"
+    }
+  ]
+}
+```
+
+Die Component-Metadata bleibt waehrend des Handoffs im Component Record und
+verweist optional mit `nativeRecord` auf den nativen Record. Neue Beispiele
+sollen das vNext-Zielbild zeigen; Dual Records dienen als Migrationsevidence.
+
+## 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 RMT vNext; `surfaces[*]` bleibt der
+pruefbare Output, weil Tooling, Materialisierung, Persistenz, Routing, Remote
+Policy und Browser-Lab-Stabilitaet dort gemeinsam pruefbar sind.

package/docs/de/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.