@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/de/visual-browser-regression.md

@@ -0,0 +1,83 @@
+# Visual Browser Regression
+
+- Contract: `xtend.docs.visual-browser-regression.v1`
+- Plan Contract: `xtend.catalog.component-regression-priority-plan.v1`
+- Gate Contract: `xtend.catalog.component-regression-priority-gate.v1`
+- Snapshot Contract: `xtend.epic12.visual-snapshot-automation-contract.v1`
+- Workpackage: `ER-WP-35`
+
+Diese Seite beschreibt den aktuellen XTend-Plan fuer visuelle und browsernahe Regression. ER-WP-35 fuehrt noch keinen Screenshot-Runner ein. Stattdessen erzeugt XTend einen stabilen Prioritaetsplan, der pro Manifest-Komponente festlegt, welche Browser-Smokes, Viewports, Theme-Varianten, visuellen Zustaende und Performance-Profile zuerst automatisiert werden muessen.
+
+## Lokal pruefen
+
+```bash
+node scripts/run_xtend_tests.js regression-priority
+node scripts/run_xtend_tests.js regression-priority --json
+npm run test:regression-priority
+```
+
+Der Gate ist Teil des lokalen Test-Runners und nutzt die Component Catalog Coverage Matrix als Quelle. Er bleibt CDN-frei und braucht keine externe Browser-Automation.
+
+## Mindestabdeckung
+
+Jede Komponente im Plan erhaelt:
+
+- Viewports: `desktop-1280`, `mobile-390`
+- Theme-/Preference-Varianten: `light`, `dark`, `forced-colors`, `reduced-motion`
+- Performance-Profil: `xtend.performance.component-profile.v1`
+- Handoff-Gates: `browser`, `performance-regression`, `catalog-coverage`, `references`
+
+P0-Komponenten wie `x-router`, `x-link`, `x-modal`, `x-input`, `x-select`, `x-checkbox`, `x-radio`, `x-textarea`, `x-tooltip`, `x-popover`, `x-drawer`, `x-form`, `x-calendar`, `x-writer`, `x-dialog` und `x-lightbox` werden als `p0-browser-critical` eingeordnet. P1-Komponenten wie `x-status` und `x-progress` bilden die visuelle und Performance-Baseline. P2-Komponenten bleiben als Long-Tail sichtbar.
+
+## Profil-Regeln
+
+| Profil | Browser-Smokes | Visuelle Zustaende |
+|--------|----------------|--------------------|
+| `routing` | Route-Wechsel, Keyboard Navigation, History State, RMT Route Adapter | Initial Route, Active Route, RMT Scheduled Route |
+| `form` | Input Sync, Validation Feedback, Keyboard Entry, Form Submit | Default, Focus, Invalid, Disabled |
+| `overlay` | Focus Trap, Escape Close, Scroll Lock, Focus Restore | Closed, Open, Focus Trapped, Reduced Motion Open |
+| `feedback` | Live Region, Dismiss Timer, Reduced Motion | Info, Warning, Error, Dismissed |
+| `interactive` | Keyboard Activation, Focus Visible, Mobile Tap | Default, Hover, Focus Visible, Active, Disabled |
+| `media` | Media Controls, Poster Load, Fullscreen Toggle | Poster, Playing, Controls Focus |
+| `theme` | Theme Switch, Token Contrast, Forced Colors | Light Theme, Dark Theme, Forced Colors |
+| `display` | Layout Stability, Responsive Overflow | Default Layout, Narrow Layout |
+| `iconography` | Layout Stability, Theme Token Color | Default Layout, High Contrast CurrentColor |
+| `utility` | Utility Integration Probe | Helper Ready |
+
+## Boundary-Abschluss
+
+Der Plan haelt die frueheren Boundary-Luecken nachvollziehbar, aber nicht mehr als offene RC1-Restpunkte:
+
+- 0 Manifest-Eintraege brauchen noch Suite-, Fixture- oder Type-Nacharbeit.
+- `xstate` ist seit `WP-E13-05` als Runtime-Boundary geschlossen.
+- `x-utils` ist seit `WP-E13-05` als Utility-Boundary geschlossen.
+- Die 42 sichtbaren Runtime-/UI-Komponenten behalten explizite Performance-Profile; `xstate` und `x-utils` werden nicht kuenstlich zu visuellen Profiltraegern umgedeutet.
+
+Damit ist klar, dass `ER-WP-35` priorisiert, aber die eigentliche Screenshot-/Pixel-Regression an CI und Release Readiness uebergibt.
+
+## Snapshot Automation Contract
+
+Seit `WP-E12-10` ist der naechste Schritt ueber `xtend.epic12.visual-snapshot-automation-contract.v1` festgelegt:
+
+```bash
+node scripts/run_xtend_tests.js visual-snapshot-automation --json
+npm run test:visual-snapshot-automation
+node scripts/run_xtend_tests.js visual-snapshots --json
+npm run test:visual-snapshots
+node scripts/run_xtend_tests.js design-tokens --json
+npm run test:design-tokens
+```
+
+Der Snapshot-Contract uebernimmt die 360 Kombinationen aus der Component Shell Theme Matrix und beschreibt `shell-structure`, `visual-state`, `theme-token-state`, `motion-density-state`, `viewport-layout`, `focus-a11y-state` und `rmt-shell-descriptor` als Snapshot Scopes. Die Diff-Strategie ist `dom-first-pixel-ready`: DOM-Struktur und CSS Token werden mit Toleranz `0` behandelt. Seit `WP-E12-11` vergleicht `xtend.epic12.visual-snapshot-runner.v1` die lokale Fixture gegen eine textuelle JSON DOM-Baseline. Pixel-Diff ist als `optional-local-pixel-diff` vorbereitet und bleibt ausserhalb des Node-Contract-Gates. Seit `WP-E12-12` werden diese CSS Token als `xtend.design-tokens.product-contract.v1` produktisiert und ueber dieselben `--xtend-*` Namen in `x-theme`, Theme Matrix und Snapshot Baseline geprueft.
+
+## Handoff
+
+- `WP-E12-10`: Visual Snapshot Automation Contract ist abgeschlossen.
+- `WP-E12-11`: lokales Snapshot Fixture und DOM-first Runner ist abgeschlossen.
+- `WP-E12-12`: Enterprise Design System Token Productization ist abgeschlossen.
+- `ER-WP-36`: CI Workflow fuer Default Gates und Regression Priority Gate produktisieren.
+- `ER-WP-38`: Release Checklist um Browser-/Visual-Regression, Artefakte und SemVer-Risiken erweitern.
+- `ER-WP-39`: Enterprise Adoption Guide mit QS-Empfehlungen und Baseline-Strategie ist abgeschlossen.
+- `ER-WP-40`: Docs-App mit RMT Parsedown Scheduling Pilot ist abgeschlossen.
+
+Die maschinenlesbare Umsetzung liegt in `catalog/component-regression-priority.js`. Die Architekturentscheidung liegt in `development/XTend-Visuelle-und-Browsernahe-Regression-Prioritaetsplan.md`.

package/docs/de/visual-owner-artifacts.md

@@ -0,0 +1,46 @@
+# Visual Owner Artifacts
+
+- Contract: `xtend.epic13.visual-owner-artifact.v1`
+- Manifest Contract: `xtend.epic13.visual-owner-artifact-manifest.v1`
+- Report: `xtend.epic13.visual-owner-artifact-report.v1`
+- Workpackage: `WP-E13-08`
+- Lokaler Gate: `node scripts/run_xtend_tests.js epic13-visual-owner-artifact --json`
+- Package Script: `npm run test:epic13-visual-owner-artifact`
+- Manifest: `tests/browser/visual-baselines/rc1-visual-owner-artifact.manifest.json`
+- Publish Boundary: `private-until-release-owner-acceptance`
+
+## Zweck
+
+Visual Owner Artifacts verbinden die bestehende DOM-first Visual Snapshot Automation mit einem reproduzierbaren Screenshot-/Pixel-Artefaktpfad fuer RC1. Der lokale Gate validiert Contract, Manifest und DOM-Snapshot-Zustand. Die eigentliche Screenshot-Erzeugung bleibt optional und gehoert in stabile Browser- oder CI-Umgebungen.
+
+## Pfadkonvention
+
+```text
+.xtend-test-results/visual-snapshots/rc1/{family}/{viewport}/{theme}/{density}/{motion}.png
+```
+
+Der Report liegt unter:
+
+```text
+.xtend-test-results/visual-snapshots/rc1/visual-owner-artifact-report.json
+```
+
+Die Fixture bleibt `tests/browser/fixtures/visual-snapshots-fixture.html`, die DOM-Baseline bleibt `tests/browser/visual-baselines/visual-snapshots.dom-baseline.json`.
+
+## Lokale Nutzung
+
+```bash
+npm run test:epic13-visual-owner-artifact
+```
+
+Der lokale Modus ist `static-artifact-manifest-plus-dom-snapshot-gate`. `pixelDiffRequiredInLocalGate`, `screenshotRequiredInLocalGate` und `binaryBaselineCommitted` sind `false`.
+
+## Beziehung zu vorhandenen Gates
+
+- Die DOM-Struktur kommt aus [Visual Snapshot Automation](./visual-snapshot-automation.md).
+- Die PROD-nahe Browser-/CSP-Vorbereitung kommt aus [PROD Browser CSP Smokes](./prod-browser-csp-smokes.md).
+- Das Owner-Artefakt bleibt `optional-browser-driver-or-ci-artifact`, bis eine stabile Browser-Capture-Umgebung als verpflichtender Release-Gate entschieden wird.
+
+## Handoff
+
+`WP-E13-08` ist abgeschlossen. `WP-E13-09` hat `xtend.epic13.rmt-production-readiness.v1` unter [RMT Production Readiness](./rmt-production-readiness.md) gebuendelt. `WP-E13-10` hat [Docs RMT Production Hardening](./docs-rmt-production-hardening.md) abgeschlossen. `WP-E13-11` hat [Trusted DOM Boundary Browser Proof](./trusted-dom-boundary-browser-proof.md) und `xtend.epic13.trusted-dom-boundary.v1` abgeschlossen. `WP-E13-12` hat [RC1 Migration Notes](./rc1-migration-notes.md) und `xtend.epic13.rc1-migration-notes-semver.v1` abgeschlossen. `WP-E13-13` hat [RC1 Gate Matrix und CI-Handoff](./rc1-gate-matrix-ci-handoff.md) und `xtend.epic13.rc1-gate-matrix-ci-handoff.v1` abgeschlossen.

package/docs/de/visual-snapshot-automation.md

@@ -0,0 +1,87 @@
+# Visual Snapshot Automation
+
+- Contract: `xtend.epic12.visual-snapshot-automation-contract.v1`
+- Entry Contract: `xtend.epic12.visual-snapshot-automation-entry.v1`
+- Automation Report Contract: `xtend.epic12.visual-snapshot-automation-report.v1`
+- Runner Contract: `xtend.epic12.visual-snapshot-runner.v1`
+- Fixture Contract: `xtend.epic12.visual-snapshot-fixture.v1`
+- Runner Report Contract: `xtend.epic12.visual-snapshot-runner-report.v1`
+- Design Token Contract: `xtend.design-tokens.product-contract.v1`
+- Workpackages: `WP-E12-10`, `WP-E12-11`, `WP-E12-12`
+- Contract Gate: `node scripts/run_xtend_tests.js visual-snapshot-automation --json`
+- Snapshot Gate: `node scripts/run_xtend_tests.js visual-snapshots --json`
+
+XTend Visual Snapshot Automation ist die Epic-12-Linie fuer lokale visuelle Regression. `WP-E12-10` definiert Scopes, Matrix, Toleranzen und Artefaktpolitik. `WP-E12-11` setzt darauf einen lokalen DOM-first Snapshot Runner mit JSON-Baseline auf.
+
+## Lokal pruefen
+
+```bash
+node scripts/run_xtend_tests.js visual-snapshot-automation
+node scripts/run_xtend_tests.js visual-snapshot-automation --json
+npm run test:visual-snapshot-automation
+node scripts/run_xtend_tests.js visual-snapshots --json
+npm run test:visual-snapshots
+node scripts/run_xtend_tests.js design-tokens --json
+npm run test:design-tokens
+```
+
+Der Gate ist local-only, CDN-frei und nutzt keine externen Browserdienste.
+
+## Matrix
+
+Der Contract uebernimmt die 360 Kombinationen der Component Shell Theme Matrix:
+
+- Themes: `light`, `dark`, `high-contrast`, `forced-colors`
+- Motion: `default-motion`, `reduced-motion`
+- Density: `comfortable`, `compact`, `dense`
+- Viewports: `desktop-1280`, `tablet-768`, `mobile-390`
+- UX-Familien: `form-controls`, `feedback-status`, `navigation-routing`, `overlay-interaction`, `layout-display-media`
+
+## Snapshot Scopes
+
+- `shell-structure`
+- `visual-state`
+- `theme-token-state`
+- `motion-density-state`
+- `viewport-layout`
+- `focus-a11y-state`
+- `rmt-shell-descriptor`
+
+Die RMT-Grenze bleibt `no-rmt-kernel-import-of-xtend-types`: RMT beschreibt und scheduled Shells, importiert aber keine XTend-Typen in den Kernel.
+
+Ab `WP-E12-12` nutzt die Snapshot-Fixture dieselben Produkt-Tokens wie `x-theme` und die Component Shell Theme Matrix. Die DOM-Baseline trackt `--xtend-surface`, `--xtend-text`, `--xtend-color-primary`, `--xtend-density-spacing` und `--xtend-radius`; lokale Fixture-Namen wie `--snapshot-*` sind entfernt.
+
+## Diff-Strategie
+
+`WP-E12-10` legt `dom-first-pixel-ready` fest, `WP-E12-11` fuehrt den lokalen DOM-Diff aus:
+
+- DOM-Struktur und CSS Token haben Toleranz `0`.
+- Pixel-Diff ist vorbereitet als `optional-local-pixel-diff`, laeuft im Node-Contract-Gate aber nicht.
+- Maximaler Pixel-Mismatch ist `0.01`.
+- Layout Shift ist auf `1px` begrenzt.
+- Vor Capture muss der Runner auf Custom Elements, Fonts, Loader-Abschluss und einen Animation Frame warten.
+
+## Artefakte
+
+| Artefakt | Pfad |
+|----------|------|
+| Contract | `development/XTend-Visual-Snapshot-Automation-Contract.md` |
+| Plan | `tests/browser/visual-snapshot-automation-plan.js` |
+| Automation Suite | `tests/browser/visual_snapshot_automation_suite.js` |
+| Runner | `tests/browser/visual-snapshots-runner.js` |
+| Fixture | `tests/browser/fixtures/visual-snapshots-fixture.html` |
+| DOM Baseline | `tests/browser/visual-baselines/visual-snapshots.dom-baseline.json` |
+| Snapshot Suite | `tests/browser/visual_snapshots_suite.js` |
+| Output Root | `.xtend-test-results/visual-snapshots` |
+| Report Path | `.xtend-test-results/visual-snapshots/visual-snapshots-report.json` |
+| RC1 Owner Manifest | `tests/browser/visual-baselines/rc1-visual-owner-artifact.manifest.json` |
+
+Die Baseline ist in `WP-E12-11` textuell und reviewbar. Binary- oder Screenshot-Baselines bleiben einem optionalen lokalen Pixel-Diff-Modus vorbehalten.
+
+## RC1 Visual Owner Artifact
+
+Ab `WP-E13-08` nutzt [Visual Owner Artifacts](./visual-owner-artifacts.md) diese DOM-first Linie als Quelle fuer `xtend.epic13.visual-owner-artifact.v1`. Der lokale Gate `node scripts/run_xtend_tests.js epic13-visual-owner-artifact --json` normalisiert Artifact Root, Report-Pfad, Screenshot-Template und Viewports. Die Screenshot-/Pixel-Erzeugung bleibt `optional-browser-driver-or-ci-artifact`.
+
+## RC0 Adoption Update
+
+Seit `WP-E12-15` verweist der [RC0 Adoption Guide](./rc0-adoption-guide.md) auf diesen DOM-first Snapshot-Pfad als RC0-Baseline. Component Authors behandeln `visual-snapshots`, `design-tokens` und `component-shell-theme-matrix` gemeinsam als lokale Review-Kette; Pixel-Baselines bleiben optional und duerfen den lokalen RC0 Dry Run nicht blockieren.

package/docs/de/xtend-api-types.md

@@ -0,0 +1,55 @@
+# XTend API Types
+
+- Contract: `xtend.type-exports.api-declarations.v1`
+- Workpackage: `WP-TypeExports-03`
+- Gate: `node scripts/run_xtend_tests.js type-exports-api --json`
+- Report: `.xtend-test-results/xtend-type-exports-api-report.json`
+- Declaration: `api.d.ts`
+
+## Zweck
+
+`api.d.ts` beschreibt die oeffentliche Core-API aus `api.js`: `initXTendAPI(manifest)`, den globalen Namespace `window.XTend.*`, die Legacy-Aliase und das Event `xtend-api-ready`. Die Declaration ist types-only; `api.js` bleibt runtime-unveraendert.
+
+## Namespace
+
+Der zentrale Namespace-Typ heisst `XTendNamespace`.
+
+| API | Typ |
+| --- | --- |
+| `window.XTend.compliance` | `XTendComplianceApi` |
+| `window.XTend.theme` | `XTendThemeApi` |
+| `window.XTend.toast` | `XTendToastApi` |
+| `window.XTend.alert` | `XTendAlertApi` |
+| `window.XTend.dialog` | `XTendDialogApi` |
+| `window.XTend.modal` | `XTendModalApi` |
+
+## Legacy-Aliase
+
+`api.d.ts` typisiert weiterhin die bestehenden globalen Komfort-Aliase:
+
+- `window.XTheme`
+- `window.XToast`
+- `window.XAlert`
+- `window.XDialog`
+- `window.XModal`
+- `window.showToast`
+- `window.showAlert`
+- `window.showDialog`
+- `window.showModal`
+
+## Event
+
+`WindowEventMap` enthaelt `xtend-api-ready` mit `XTendApiReadyDetail`. Der Payload meldet, ob Toast, Alert, Dialog, Modal und Theme APIs initialisiert sind.
+
+## Package Export
+
+Der Package-Export `./api` besitzt ab `WP-TypeExports-03` die `types`-Condition `./api.d.ts`. `browser` und `default` zeigen weiter auf `./api.js`.
+
+## Drift Gate
+
+Der Gate `type-exports-api` prueft:
+
+- `api.d.ts` existiert und ist im Package enthalten.
+- `./api` zeigt per `types` auf `./api.d.ts`.
+- `initXTendAPI`, `window.XTend.*`, Legacy-Aliase und `xtend-api-ready` sind in Runtime und Declaration sichtbar.
+- `api.js` importiert keine Declaration-Datei.

package/docs/de/xtend-builder-types.md

@@ -0,0 +1,55 @@
+# XTend Builder Types
+
+Status: `completed`  
+Workpackage: `WP-TypeExports-06`  
+Schema: `xtend.type-exports.builder-declarations.v1`  
+Gate: `node scripts/run_xtend_tests.js type-exports-builder --json`
+
+## Scope
+
+`WP-TypeExports-06` typisiert die Builder-, Scaffold- und Component-Lab-Programm-APIs, ohne die CLI oder die Generatoren nach TypeScript zu portieren.
+
+Die gemeinsame Grundlage liegt in `./xtend-builder/builder-public-types.d.ts`:
+
+- `XtendBuilderComponentInput`
+- `XtendBuilderComponentPlan`
+- `XtendBuilderComponentFilesResult`
+- `XtendBuilderWorkflow`
+- `XtendBuilderComponentLabPlan`
+
+## Declaration Pack
+
+Die Root- und Workflow-APIs sind ueber diese Facades stabilisiert:
+
+- `./xtend-builder/scaffold.d.ts`
+- `./xtend-builder/lib/cli.d.ts`
+- `./xtend-builder/blueprints/component-blueprint.contract.d.ts`
+- `./xtend-builder/generators/component-plan.d.ts`
+- `./xtend-builder/generators/component-files.d.ts`
+- `./xtend-builder/generators/registry.d.ts`
+- `./xtend-builder/workflows/developer-workflow.d.ts`
+
+Component-Lab- und Preview-Consumer erhalten eigene Contracts:
+
+- `./xtend-builder/preview/component-preview.d.ts`
+- `./xtend-builder/preview/component-lab.d.ts`
+- `./xtend-builder/preview/component-lab-ux-inspector.d.ts`
+
+Die bereits exportierten Typing- und UX-Contract-Module sind als schmale Facades abgebildet, darunter `component-shell-contract`, `component-styling-contract`, `component-network-contract`, `rmt-shell-authoring-contract`, `rmt-dsl-authoring-polish`, die Form-/Feedback-/Navigation-/Overlay-/Layout-UX Contracts und `component-ux-performance-contract`.
+
+## Package Exports
+
+Die Package-Exports `./builder`, `./builder/*` sowie die expliziten Builder-Subexports erhalten `types`-Conditions. Beispiel:
+
+```json
+"./builder": {
+  "types": "./xtend-builder/scaffold.d.ts",
+  "default": "./xtend-builder/scaffold.js"
+}
+```
+
+`./builder/*` bleibt als generischer Anschluss fuer repo-lokale Builder-Module erhalten und zeigt auf `./xtend-builder/*.d.ts`.
+
+## Boundary
+
+Die Declarations bleiben `types-only-no-runtime-imports`. Sie importieren keine Builder-Runtime, keine Komponenten, keinen RMT-Kernel und keine Loader-/API-Laufzeit. Der lokale Gate vergleicht Runtime-Exports, Package-`types`-Conditions, vorhandene Declaration-Dateien und die gemeinsame Builder-Type-Basis.

package/docs/de/xtend-catalog-types.md

@@ -0,0 +1,44 @@
+# XTend Catalog Types
+
+- Contract: `xtend.type-exports.catalog-declarations.v1`
+- Workpackage: `WP-TypeExports-07`
+- Gate: `node scripts/run_xtend_tests.js type-exports-catalog --json`
+- Report: `.xtend-test-results/xtend-type-exports-catalog-report.json`
+
+## Zweck
+
+Catalog-Module beschreiben XTend-Gates, Handoffs, Release-Plaene und SurfaceManager-Runtime-Scopes als maschinenlesbare Plan-/Report-Strukturen. `WP-TypeExports-07` fuehrt dafuer ein gemeinsames Declaration-Pattern ein, damit neue Catalogs nicht pro Property neu typisiert werden muessen.
+
+`./catalog/catalog-public-types.d.ts` definiert die gemeinsamen Basistypen `XtendCatalogPlan`, `XtendCatalogReport`, `XtendCatalogGate`, `XtendCatalogFactory`, `XtendCatalogValidator` und `XtendCatalogDiagnostic`. Die einzelnen Catalog-Facades exportieren die Runtime-Symbole des jeweiligen `.js`-Moduls und binden Funktionen wie `create*Plan`, `create*Report`, `create*Gate` und `validate*Plan` an diese Basistypen.
+
+## Package Surface
+
+Alle oeffentlichen `./catalog/*` Package-Exports besitzen nun eine eigene `types`-Condition. Beispiele:
+
+```json
+"./catalog/epic13-package-export-lock": {
+  "types": "./catalog/epic13-package-export-lock.d.ts",
+  "default": "./catalog/epic13-package-export-lock.js"
+}
+```
+
+Das Runtime-Ziel bleibt unveraendert. Die Declarations importieren keine Runtime-Dateien und sind als Consumer-Facades gedacht.
+
+## Catalog Familien
+
+Der Gate klassifiziert drei fuer XTend wichtige Catalog-Familien:
+
+- SurfaceManager-Catalogs bleiben interne XTend-UI-Unterstuetzung und dokumentieren App-Shell-, Surface-, Routing- und Runtime-Handoffs.
+- Epic-Catalogs beschreiben Workpackage-, Gate- und Contract-Plaene ueber mehrere Epics hinweg.
+- Release-Catalogs bündeln Handoff-, Readiness-, Export-Lock- und Migration-Entscheidungen.
+
+Die SurfaceManager-Catalogs ersetzen keine Fabric-, RMT-Kernel- oder Runtime-Schicht. Sie bleiben deklarative Plaene und Reports, die UI-Surfaces unterstuetzen.
+
+## Drift Gate
+
+```bash
+node scripts/run_xtend_tests.js type-exports-catalog --json
+npm run test:type-exports-catalog
+```
+
+Der Gate prueft, dass Package-Catalogs ihre `types`-Conditions besitzen, dass alle Catalog-Runtime-Exports in den `.d.ts`-Facades auftauchen, dass SurfaceManager-/Epic-/Release-Catalogs klassifiziert sind und dass keine Runtime-Dateien Declaration-Imports erhalten.

package/docs/de/xtend-fabric-rmt-lane-mapping.md

@@ -0,0 +1,143 @@
+# XTend-Fabric RMT Lane Mapping
+
+- Status: produktiver Mapping-Contract ab `ER-WP-13`
+- Contract: `xtend.docs.xtend-fabric-rmt-lane-mapping.v1`
+- Mapping Contract: `xtend.fabric.rmt-lane-mapping.v1`
+- Runtime: `fabric/rmt-lane-mapping.js`
+- Test: `tests/fabric/fabric_rmt_lane_mapping_suite.js`
+
+## Zweck
+
+`fabric/rmt-lane-mapping.js` verbindet Fabric-Lanes mit RMT Schedule Policies, ohne XTend in den RMT Kernel einzubauen.
+
+Fabric beschreibt UI-Arbeit semantisch: `user-blocking`, `a11y`, `visible`, `transition`, `idle`, `background`, `diagnostics`. RMT bleibt host-neutral und sieht weiterhin nur Schedule Records mit `endpointName`, `scope`, `lane`, `priority`, `deadlineMs`, `preferIdle`, `coalesceKey` und `budgetClass`.
+
+Seit `WP-E13-09` referenziert [RMT Production Readiness](./rmt-production-readiness.md) dieses Mapping unter `xtend.epic13.rmt-production-readiness.v1`, damit RMT-first Apps Fabric/Lane-Signale produktionsnah ingestieren koennen, ohne die RMT-Kernel-Boundary zu verletzen.
+
+## Lane Mapping
+
+| Fabric-Lane | RMT Schedule Lane | Grund |
+|-------------|-------------------|-------|
+| `user-blocking` | `user-blocking` | Eingabe, Navigation und Fokus sind kritisch |
+| `a11y` | `user-blocking` | Screenreader- und Fokus-Signale sind user-facing; RMT hat noch keine eigene `a11y` Lane |
+| `visible` | `visible` | sichtbare Component-Arbeit |
+| `transition` | `transition` | Route- und UI-Uebergaenge |
+| `idle` | `idle` | nicht sichtbare Hydration und Follow-up |
+| `background` | `background` | best-effort Arbeit |
+| `diagnostics` | `diagnostics` | Telemetry und Snapshots |
+
+`a11y` bleibt also eine Fabric-Lane. Das erzeugte RMT Schedule Record traegt die RMT-Lane `user-blocking` und bewahrt `metadata.fabricLane = "a11y"`, damit Reporter und spaetere Adapter die urspruengliche Semantik sehen koennen.
+
+## API
+
+```js
+const mapping = window.XTendFabricRmtLaneMapping.createFabricRmtLaneMapping();
+
+const result = mapping.resolveFiber({
+  kind: 'component.hydrate',
+  lane: 'idle',
+  scope: 'x-alert#secondary',
+  componentRef: 'x-alert'
+});
+```
+
+Wichtige Funktionen:
+
+| API | Zweck |
+|-----|-------|
+| `createFabricRmtLaneMapping(options)` | erzeugt ein Mapping-Objekt mit Lane-Map und Schedule Records |
+| `createRmtScheduleRecords(options)` | erzeugt host-neutrale RMT Schedule Records fuer Fabric-Lanes |
+| `resolveRmtScheduleForFiber(fiber, options)` | loest eine Fiber auf ein Schedule Record auf |
+| `normalizeFabricLaneForRmt(lane)` | uebersetzt eine einzelne Fabric-Lane in eine RMT-Lane |
+
+## Beispiel Schedule Records
+
+```json
+{
+  "schema": "xtend.fabric.rmt-lane-schedule.v1",
+  "id": "component.idle.hydrate",
+  "endpointName": "xtendrmt.component.hydrate",
+  "scope": "xtend.fabric.idle",
+  "lane": "idle",
+  "priority": 35,
+  "deadlineMs": 500,
+  "preferIdle": true,
+  "coalesceKey": "xtend.fabric.idle",
+  "budgetClass": "background",
+  "metadata": {
+    "contract": "xtend.fabric.rmt-lane-mapping.v1",
+    "fabricLane": "idle",
+    "rmtLane": "idle"
+  }
+}
+```
+
+Seit `ER-WP-20` gibt es zusaetzlich `component.lazy.hydrate` fuer unterhalb des Fold oder bei Backpressure verschobene Hydration. Die RMT-Lane bleibt `idle`; der Unterschied liegt in `scheduleRef`, Scope und Coalescing.
+
+```json
+{
+  "schema": "xtend.fabric.rmt-lane-schedule.v1",
+  "id": "a11y.user-blocking.announce",
+  "endpointName": "xtendrmt.a11y.announce",
+  "scope": "xtend.fabric.a11y",
+  "lane": "user-blocking",
+  "priority": 95,
+  "deadlineMs": 80,
+  "preferIdle": false,
+  "coalesceKey": "xtend.fabric.a11y.announce",
+  "budgetClass": "critical",
+  "metadata": {
+    "contract": "xtend.fabric.rmt-lane-mapping.v1",
+    "fabricLane": "a11y",
+    "rmtLane": "user-blocking",
+    "reason": "RMT schedules-domain has no dedicated a11y lane in xtend.rmt.schedules-domain.v1."
+  }
+}
+```
+
+## Kernel Boundary
+
+Das Mapping importiert keinen XTendRMT Kernel und parst keine `.rmt` Dokumente. Es kann bereits normalisierte Schedule Records aus einem Host oder Test-Fixture entgegennehmen und `scheduleRef` oder `endpointNameHint` darauf aufloesen.
+
+Erlaubt:
+
+- Fabric-Fiber auf RMT Schedule Records mappen
+- generierte Schedule Records als App-/Adapter-Hints verwenden
+- bestehende `schedules[*]` Records aus normalisierten RMT-Dokumenten referenzieren
+- `metadata.fabricLane` fuer Diagnostics und Reporter erhalten
+
+Nicht erlaubt:
+
+- RMT Runtime oder Kernel in Fabric importieren
+- `a11y` als RMT-Kernel-Lane erzwingen
+- XTend-Komponenten im RMT Kernel ausfuehren
+- RMT Schema-Validierung in Fabric duplizieren
+
+## Adapter-Ingestion
+
+Ab Epic 10 / `WP-E10-05` nutzt der produktive `xtend.component` Adapter dieselbe Semantik als Runtime-Context. Der Contract heisst `xtend.component.fabric-lane-ingestion.v2`.
+
+Precedence im Adapter:
+
+1. `rmt.schedule-record`
+2. `rmt.component-metadata`
+3. `fabric.runtime-override`
+4. `component.static-contract`
+5. `scaffold.blueprint-default`
+
+Der Adapter importiert Fabric nicht in den RMT Kernel. Er loest beim Mounting und bei Hydration nur den Fabric Context auf, setzt `result.metadata.fabric` und markiert DOM-Hosts mit `data-xtend-fabric-lane`, `data-xtend-rmt-lane`, `data-xtend-fabric-fiber`, `data-xtend-fabric-source` und `data-rmt-endpoint`.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js fabric-lane-mapping --json
+node scripts/run_xtend_tests.js rmt-component-fabric-ingestion --json
+node scripts/run_xtend_tests.js hydration-policy --json
+npm run test:fabric-lanes
+npm run test:rmt-component-fabric-ingestion
+npm run test:hydration-policy
+node scripts/run_xtend_tests.js references --json
+npm test
+```
+
+`ER-WP-20` ist darauf aufgebaut und haertet Lazy/Idle/Visible Hydration Policies mit konkreten `scheduleRef`-Entscheidungen. Route Render und XRouter Navigation bleiben ueber `ER-WP-15` korrelierbar.