@ccslabs/xtend 0.1.0-rc.1

package/docs/component-platform.md

@@ -0,0 +1,159 @@
+# XTend Component Platform
+
+Contract: `xtend.docs.component-platform.v1`
+
+Diese Seite beschreibt den aktuellen Epic-10-Stand fuer neue XTend-Komponenten. Neue Komponenten werden TypeScript-first geplant, lokal als ESM-Artefakte ausgeliefert und als RMT-first Authoring-Ziele vorbereitet. RMT bleibt dabei Framework-agnostisch: XTend-Komponenten sind `xtend.component` Records, aber der RMT-Kernel importiert keine XTend-Klassen oder Typen.
+
+Seit `WP-E10-16` ist Epic 10 abgeschlossen. Der Release-Handoff liegt in [Epic 10 Release Handoff](./epic10-release-handoff.md), und vollstaendige App-Authoring-Regeln liegen in [RMT-first XTend Apps](./rmt-first-xtend-apps.md). Seit `WP-E11-17` sind die sichtbaren UX-Regeln in [Component UX Authoring](./component-ux-authoring.md), [Component UX App Authoring](./component-ux-app-authoring.md), [Component UX Gates](./component-ux-gates.md) und [Component Long-Tail Migration](./component-long-tail-migration.md) zusammengefuehrt.
+
+## Plattform-Schichten
+
+- TypeScript Source liegt unter `src/components/<tag>/`
+- Runtime-Artefakte bleiben lokale ESM-Dateien unter `components/`
+- Public Types bleiben `.d.ts` Artefakte unter `components/`
+- RMT Metadata liegt als eigenes `ts-rmt` Artefakt vor
+- Fabric, Telemetry, Lanes, A11y und Performance sind Pflichtdomains im `xtend.component.contract.v2`
+- der Builder erzeugt Contract-, Source-, RMT-, A11y-, Performance- und Fixture-Artefakte als Dry-Run
+
+## P0-Komponentenwelle
+
+WP-E10-08 legt die erste P0-Komponentenwelle als `xtend.epic10.p0-component-wave.v1` fest.
+
+| Komponente | Paket | Schwerpunkt |
+|------------|-------|-------------|
+| `x-select` | `WP-E10-09` | Select Control, Option Slots, Value Events |
+| `x-checkbox` | `WP-E10-09` | Binary Input, checked/indeterminate State |
+| `x-radio` | `WP-E10-09` | Radio Group Coordination und Keyboard Navigation |
+| `x-textarea` | `WP-E10-10` | Long-Form Input, Validation, Counter |
+| `x-status` | `WP-E10-10` | Live Region, Validation Feedback, Scheduler Status |
+| `x-progress` | `WP-E10-10` | Async Progress, Hydration/Task Feedback |
+| `x-tooltip` | `WP-E10-11` | leichte Overlay-Hilfe und describedby Mapping |
+| `x-popover` | `WP-E10-11` | interaktives, verankertes Overlay |
+| `x-drawer` | `WP-E10-11` | App-Shell Navigation und Side Panels |
+
+`x-select`, `x-checkbox`, `x-radio`, `x-textarea`, `x-status`, `x-progress`, `x-tooltip`, `x-popover` und `x-drawer` sind seit `WP-E10-11` als TypeScript-first Referenzlinie umgesetzt und bilden die erste P0-Welle mit `enterprise-ready` Catalog-Status.
+
+## Component Lab und RMT Inspector
+
+`WP-E10-12` legt das Component Lab als Shell-first RMT-Pilot an. Das Lab nutzt `tests/fixtures/rmt-component-lab-pilot.rmt` und das Plan-Modul `xtend-builder/preview/component-lab.js`, um alle neun `enterprise-ready` Komponenten lokal inspizierbar zu machen.
+
+Die Pilot-Oberflaeche besteht aus:
+
+- Component Preview fuer Fixture, Docs, Types und Contract-Pfade
+- RMT Inspector fuer `manifest`, `adapters`, `components`, `routes`, `schedules`, `templates` und `diagnostics`
+- Telemetry Panel fuer `snapshot.componentTelemetry`
+- A11y- und Performance-Hinweisen aus Component Contract v2
+- Source Links auf Runtime, TS Source, RMT Metadata, Fixture, Docs und Suite
+
+Der lokale Gate lautet:
+
+```bash
+node scripts/run_xtend_tests.js component-lab-rmt-inspector --json
+```
+
+## RMT-first Demo-App
+
+`WP-E10-13` liefert mit `xtendrmt-rmt-first-demo.html` und `xtendrmt/rmt-first-demo-app.rmt` die erste produktive RMT-first Demo-App ohne manuelle Shell. Die Hostseite stellt nur einen `data-rmt-host="rmt-first-demo"` Root, den lokalen XTend Loader, das lokale Manifest und die RMT Runtime bereit.
+
+Die App Shell, Navigation, Routen, Seiten-Templates, Component Records, Schedules, Fabric Lanes und Diagnostics werden aus dem RMT-Dokument gerendert. Die Demo nutzt die komplette Epic-10 P0-Welle: `x-select`, `x-checkbox`, `x-radio`, `x-textarea`, `x-status`, `x-progress`, `x-tooltip`, `x-popover` und `x-drawer`.
+
+Der lokale Gate lautet:
+
+```bash
+node scripts/run_xtend_tests.js rmt-first-demo-app --json
+```
+
+## Existing Component Metadata
+
+`WP-E10-14` zieht bestehende priorisierte Komponenten als `js-legacy` Contract Overlay in die RMT/Fabric-Linie. Der maschinenlesbare Katalog liegt in `catalog/epic10-existing-component-metadata.js` und nutzt die Migration Strategy `js-legacy-contract-overlay-no-runtime-rewrite`.
+
+Die Zielkomponenten sind `x-router`, `x-link`, `x-input`, `x-form`, `x-modal`, `x-dialog`, `x-tabs`, `x-toast` und `x-alert`. Jede Komponente erhaelt Contract-v2-, RMT-, Fabric-, Telemetry-, Lane-, A11y- und Performance-Metadata, ohne dass die Runtime in diesem Paket umgebaut werden muss.
+
+Der lokale Gate lautet:
+
+```bash
+node scripts/run_xtend_tests.js existing-component-metadata --json
+```
+
+## Epic 10 Platform Gates
+
+`WP-E10-15` buendelt die Plattformregeln als `xtend.epic10.platform-gates.v1`. Der maschinenlesbare Plan liegt in `catalog/epic10-platform-gates.js` und verbindet Component Contract v2, Existing Component Metadata, RMT-first Demo-App, Browser-Smokes, A11y, Performance und Visual Regression.
+
+Der Fast-PR-Pfad enthaelt `component-contract-v2`, `epic10-p0-component-wave`, `component-lab-rmt-inspector`, `rmt-first-demo-app`, `existing-component-metadata`, `browser`, `a11y-hydration`, `screenreader-signals`, `motion-contrast`, `regression-priority` und `references`. Release-only Performance bleibt ueber `fabric-performance-measurements`, `performance-regression` und `hydration-policy` getrennt.
+
+Der lokale Gate lautet:
+
+```bash
+node scripts/run_xtend_tests.js epic10-platform-gates --json
+```
+
+## Epic 10 Release Handoff
+
+`WP-E10-16` finalisiert die kanonische Guide-Struktur und den Abschlusscontract `xtend.epic10.release-handoff.v1`. Der maschinenlesbare Plan liegt in `catalog/epic10-release-handoff.js`.
+
+Die kanonische Component-Fabric-Boundary ist `adapter-injection-via-xtend-component-resolveFabricContext`. `window.XTendFabric` bleibt Host-Komfort- und Enterprise-Integrationsflaeche, aber Komponenten beziehen Fabric-, Lane- und Fiber-Kontext ueber den `xtend.component` Adapter.
+
+Der lokale Gate lautet:
+
+```bash
+node scripts/run_xtend_tests.js epic10-release-handoff --json
+```
+
+## Epic 11 Enterprise UX Handoff
+
+`WP-E11-18` finalisiert die sichtbare Component-UX-Reife als `xtend.epic11.enterprise-ux-handoff.v1`. Der maschinenlesbare Plan liegt in `catalog/epic11-enterprise-ux-handoff.js`.
+
+Der Abschlussmodus lautet `completed-with-accepted-long-tail-handoff`: Shell, Styling, Runtime-A11y, Performance, Component Network, RMT Shell Authoring, Component Lab, Browser-Smokes, Theme-Matrix und Authoring Guides sind als Produktlinie akzeptiert. Nach `WP-E12-09` sind `x-tabs`, `x-theme`, `x-button` und `x-menu` runtime-seitig geschlossen; `xstate` besitzt Suite, Fixture, Types und Adapter-Boundary-Probe; `x-utils` besitzt Utility Contract, Import Policy, Fixture und Types. Seit `WP-E13-05` sind `xstate` als Runtime-Boundary und `x-utils` als Utility-Boundary fuer RC1 geschlossen.
+
+Der lokale Gate lautet:
+
+```bash
+node scripts/run_xtend_tests.js epic11-enterprise-ux-handoff --json
+```
+
+## RMT First-Class Support
+
+Jede neue Komponente muss als RMT Component Record authorbar sein:
+
+- Adapter: `xtend.component`
+- Template-Modus: `dom_descriptor`
+- Event Binding: `dom-event-to-rmt-command`
+- Pflicht-Schedules: `component.visible.mount`, Hydration Schedule und `diagnostics.snapshot`
+- Kernel Boundary: `no-rmt-kernel-import-of-xtend-types`
+
+RMT beschreibt also Komponente, Props, Attribute, Slots, Events, Hydration und Schedule. XTend fuehrt die Custom Elements lokal aus.
+
+## Fabric, Telemetry und Lanes
+
+Neue Komponenten muessen Fabric-Kontext aufnehmen koennen. Dazu gehoeren:
+
+- `@xtend-fabric` Boundary
+- Lifecycle-Operationen `mount`, `hydrate`, `render`, `update`, `event`, `error`, `unmount`
+- Telemetry Snapshot `xtend.fabric.telemetry-snapshot.v1`
+- Backpressure-faehige Messpunkte
+- deterministische Lane-Precedence aus RMT, Component Metadata, Fabric Override und Blueprint Default
+
+## A11y und Performance
+
+A11y ist kein nachgelagerter Test. Form Controls brauchen Labels, Error Regions, Keyboard-Verhalten und Screenreader-Signale. Feedback-Komponenten brauchen Live Regions und non-color Statussignale. Overlays brauchen Escape, Fokus-Rueckgabe und Reduced Motion.
+
+Performance ist ebenfalls Contract-Bestandteil. Jede Komponente muss Budgetklasse, Lane, Hydration Policy und kritische Messpunkte deklarieren.
+
+## Lokale Gates
+
+```bash
+node scripts/run_xtend_tests.js component-ux-authoring-docs --json
+node scripts/run_xtend_tests.js component-long-tail-migration --json
+node scripts/run_xtend_tests.js epic11-enterprise-ux-handoff --json
+node scripts/run_xtend_tests.js component-shell-theme-matrix --json
+node scripts/run_xtend_tests.js component-ux-browser-smokes --json
+node scripts/run_xtend_tests.js epic10-p0-component-wave --json
+node scripts/run_xtend_tests.js component-lab-rmt-inspector --json
+node scripts/run_xtend_tests.js rmt-first-demo-app --json
+node scripts/run_xtend_tests.js existing-component-metadata --json
+node scripts/run_xtend_tests.js epic10-platform-gates --json
+node scripts/run_xtend_tests.js epic10-release-handoff --json
+node scripts/run_xtend_tests.js builder-typescript-blueprint --json
+node scripts/run_xtend_tests.js component-contract-v2 --json
+node scripts/run_xtend_tests.js references --json
+```

package/docs/component-ux-app-authoring.md

@@ -0,0 +1,130 @@
+# Component UX App Authoring
+
+Docs Contract: `xtend.docs.component-ux-app-authoring.v1`
+
+Dieser Guide richtet sich an App-Autorinnen und App-Autoren, die XTend-Komponenten in RMT-first Apps einsetzen. Die App kann vollstaendig in RMT templated werden; XTend liefert lokale Web Components und XTendRMT orchestriert Shell, Routes, Templates, Schedules und Diagnostics.
+
+## Grundregeln
+
+- Die App Shell rendert `shell-first`.
+- XTend-Komponenten werden als `xtend.component` Records beschrieben.
+- XRouter wird ueber den Router-Adapter angebunden.
+- Templates verwenden bevorzugt `dom_descriptor`.
+- Events werden als `dom-event-to-rmt-command` gebunden.
+- Hydration, Fabric-Lane, Fiber und Diagnostics bleiben schedulebare Metadata.
+- Der RMT-Kernel importiert keine XTend-Klassen oder XTend-Typen.
+
+Boundary:
+
+```text
+no-rmt-kernel-import-of-xtend-types
+```
+
+## Minimaler Component Record
+
+```json
+{
+  "id": "settings.feedback.status",
+  "kind": "custom_element",
+  "adapter": "xtend.component",
+  "tag": "x-status",
+  "props": {
+    "type": "success",
+    "label": "Scheduler",
+    "message": "Ready"
+  },
+  "a11y": {
+    "role": "status",
+    "live": "polite"
+  },
+  "style": {
+    "theme": "dark",
+    "density": "compact"
+  },
+  "schedule": "component.visible.mount",
+  "fabric": {
+    "lane": "visible",
+    "fiber": "component.mount"
+  }
+}
+```
+
+## App-Shell-Muster
+
+```json
+{
+  "manifest": {
+    "metadata": {
+      "contractVersion": "xtend.rmt.first-class-app-authoring.v1",
+      "renderMode": "shell-first"
+    }
+  },
+  "adapters": [
+    { "id": "xtend.component", "kind": "component" },
+    { "id": "xtend.xrouter", "kind": "router" }
+  ],
+  "routes": [
+    { "id": "dashboard", "path": "/", "template": "dashboard.page" }
+  ],
+  "templates": [
+    {
+      "id": "dashboard.page",
+      "mode": "dom_descriptor",
+      "children": [
+        { "component": "settings.feedback.status" }
+      ]
+    }
+  ],
+  "schedules": [
+    {
+      "id": "dashboard.visible.mount",
+      "lane": "visible",
+      "endpoint": "xtend.component.mount",
+      "metadata": {
+        "theme": "dark",
+        "density": "compact",
+        "motion": "reduced-motion"
+      }
+    }
+  ]
+}
+```
+
+## UX-Regeln fuer Apps
+
+| Dimension | App-Regel |
+| --- | --- |
+| Shell | Hostseite stellt nur den Root, Loader, Manifest und RMT Runtime bereit |
+| Routing | Routen kommen aus RMT und werden ueber XRouter aktiviert |
+| Theme | `light`, `dark`, `high-contrast` und `forced-colors` bleiben App-States |
+| Motion | `reduced-motion` muss bis in Overlays, Feedback und Media sichtbar sein |
+| Density | `comfortable`, `compact` und `dense` duerfen Layout nicht brechen |
+| A11y | Route Announcements, Live Regions, Error Regions und Focus Restore sind Teil der App |
+| Performance | Hydration Policies und Fabric-Lanes sind Schedule-Daten, keine Host-Sonderlogik |
+
+## Gates fuer App-Autoren
+
+```bash
+node scripts/run_xtend_tests.js rmt-first-class-app --json
+node scripts/run_xtend_tests.js rmt-shell-authoring-ux --json
+node scripts/run_xtend_tests.js component-ux-browser-smokes --json
+node scripts/run_xtend_tests.js component-shell-theme-matrix --json
+node scripts/run_xtend_tests.js browser --json
+```
+
+Fuer PRs ist der gemeinsame schnelle Pfad:
+
+```bash
+npm run test:pr
+```
+
+## Wann ein App-Pfad reif ist
+
+Ein RMT-first XTend App-Pfad gilt als reif, wenn:
+
+- die Shell nicht manuell aus statischem XTend-Markup zusammengesetzt wird,
+- Komponenten ueber `xtend.component` Records kommen,
+- Route, Theme, Motion, Density und Hydration in RMT sichtbar sind,
+- Browser-Smokes die Kernjourneys abdecken,
+- die Component Shell Theme Matrix nicht bricht,
+- keine externen CDN- oder Importmap-Abhaengigkeiten eingefuehrt werden.

package/docs/component-ux-authoring.md

@@ -0,0 +1,96 @@
+# Component UX Authoring
+
+Docs Contract: `xtend.docs.component-ux-authoring.v1`
+
+Dieser Guide ist die kanonische Arbeitsanleitung fuer XTend-Komponentenautorinnen und -autoren nach `WP-E11-16`. Er uebersetzt die Epic-11-Vertraege in konkrete Regeln fuer neue und modernisierte Web Components.
+
+## Grundsatz
+
+Eine XTend-Komponente ist erst dann UX-reif, wenn ihre sichtbare Shell, ihr Styling, ihre A11y, ihre Performance, ihr Component Network, ihre RMT-Autorierbarkeit und ihre browsernahen Smokes zusammenpassen. Einzelne Komponenten duerfen klein bleiben, aber ihre Contracts muessen vollstaendig sein.
+
+Die technische Boundary bleibt:
+
+```text
+no-rmt-kernel-import-of-xtend-types
+```
+
+RMT darf XTend-Komponenten schedulen, rendern und konfigurieren. Der RMT-Kernel importiert aber keine XTend-Klassen oder XTend-Typen.
+
+## Pflichtcontracts
+
+| Contract | Zweck | Gate |
+| --- | --- | --- |
+| `xtend.component.shell.v1` | Root, DOM-Modus, States, Slots, Parts, Focus und Lifecycle | `component-shell-contract` |
+| `xtend.component.styling.v1` | Tokens, CSS Parts, Variants, Size, Density und Theme Bridges | `component-styling-contract` |
+| `xtend.component.runtime-a11y.v1` | Keyboard, Focus, ARIA, Screenreader und High Contrast | `runtime-a11y-contract` |
+| `xtend.component.ux-performance.v1` | Shell-, Hydration-, Render-, Event- und Interaction-Budgets | `component-ux-performance` |
+| `xtend.component.network.v1` | Events, Commands, Form Association, Router Context und Feedback | `component-network-contract` |
+| `xtend.rmt.shell-authoring.v1` | Shell, Style, A11y, Variants, Commands und Events in RMT | `rmt-shell-authoring-ux` |
+| `xtend.epic11.component-lab-ux-inspector.v1` | Preview, RMT Inspector, State, A11y, Performance und Source Links | `component-lab-ux-inspector` |
+| `xtend.epic11.component-ux-browser-smokes.v1` | reale UX-Journeys fuer priorisierte Familien | `component-ux-browser-smokes` |
+| `xtend.epic11.component-shell-theme-matrix.v1` | Theme, Motion, Density, Viewport und Visual States | `component-shell-theme-matrix` |
+
+## Authoring-Reihenfolge
+
+1. Familie waehlen: `form-controls`, `feedback-status`, `navigation-routing`, `overlay-interaction` oder `layout-display-media`.
+2. Shell Contract definieren: Root, Slots, States, Parts, Focus und Lifecycle festlegen.
+3. Styling als API behandeln: Tokens, Parts, Variants, Size und Density dokumentieren.
+4. A11y zuerst modellieren: Keyboard, Labels, ARIA, Live Regions, Focus Restore und Screenreader-Signale festlegen.
+5. Performance-Profil setzen: Lane, Hydration Policy, kritische Messpunkte und Budgetklasse festlegen.
+6. Component Network beschreiben: Events, Commands, Form Association, Router Context oder Feedback-Kanaele definieren.
+7. RMT-Authoring ergaenzen: `xtend.component` Record, `dom_descriptor`, Schedules, Commands und Events pflegen.
+8. Fabric-Kontext akzeptieren: Lane, Fiber und Telemetry ueber Adapterdaten aufnehmen.
+9. Component Lab sichtbar machen: Preview, Docs, Types, Fixture, State, A11y und Performance verlinken.
+10. Browser- und Theme-Matrix pruefen: lokale Smokes und Shell-Matrix laufen lassen.
+
+## Familienregeln
+
+| Familie | Minimum |
+| --- | --- |
+| Form Controls | Label, Help Text, Error Region, Required/Invalid, Form Association, Value Event, Keyboard Entry |
+| Feedback/Status | Live Region, Role, Tone, Dismiss/Timeout, non-color Status, Reduced Motion |
+| Navigation/Routing | Active State, `aria-current`, Keyboard Activation, Route Announcement, Focus Restore, Tablist ARIA und roving `tabindex` |
+| Overlay/Interaction | Initial Focus, Focus Trap, Escape, Focus Restore, Scroll Lock, Reduced Motion |
+| Layout/Display/Media | Responsive Slots, Stable Layout, Lazy/Visible Hydration, Media Shell, Code/Display Semantics |
+
+## Theme Matrix
+
+Jede priorisierte Shell muss in der Component Shell Theme Matrix darstellbar bleiben:
+
+- Themes: `light`, `dark`, `high-contrast`, `forced-colors`
+- Motion: `default-motion`, `reduced-motion`
+- Density: `comfortable`, `compact`, `dense`
+- Viewports: `desktop-1280`, `tablet-768`, `mobile-390`
+
+Der Gate prueft aktuell `360` Shell-Kombinationen:
+
+Seit `WP-E12-03` ist `x-tabs` Teil der Navigation/Routing-Matrix und muss Arrow-Key, `Home`, `End`, `aria-controls`, `role=tabpanel`, `aria-selected` und sichtbaren Fokus in Browser-Smokes und Theme-Matrix halten.
+
+```bash
+node scripts/run_xtend_tests.js component-shell-theme-matrix --json
+```
+
+## Lokale Gates
+
+```bash
+node scripts/run_xtend_tests.js component-shell-contract --json
+node scripts/run_xtend_tests.js component-styling-contract --json
+node scripts/run_xtend_tests.js runtime-a11y-contract --json
+node scripts/run_xtend_tests.js component-ux-performance --json
+node scripts/run_xtend_tests.js component-network-contract --json
+node scripts/run_xtend_tests.js rmt-shell-authoring-ux --json
+node scripts/run_xtend_tests.js component-lab-ux-inspector --json
+node scripts/run_xtend_tests.js component-ux-browser-smokes --json
+node scripts/run_xtend_tests.js component-shell-theme-matrix --json
+node scripts/run_xtend_tests.js references --json
+```
+
+## Definition of Done
+
+- Docs, `.d.ts`, Fixture, Component Suite und RMT Metadata existieren.
+- Shell, Styling, A11y, Performance und Network Contracts sind sichtbar.
+- Events sind `bubbles: true` und `composed: true`, wenn Hosts oder RMT sie konsumieren sollen.
+- Commands sind deklarierbar und nicht nur private Methoden.
+- Theme, Density und Motion sind nicht hart im Shadow DOM versteckt.
+- Browser-Smoke oder Theme-Matrix deckt den relevanten sichtbaren Pfad ab.
+- Kein neuer Pfad fuehrt eine harte XTend-Abhaengigkeit in den RMT-Kernel ein.

package/docs/component-ux-gates.md

@@ -0,0 +1,45 @@
+# Component UX Gates
+
+Docs Contract: `xtend.docs.component-ux-gates.v1`
+
+Diese Seite beschreibt die lokale Gate-Kette fuer Epic 11. Sie verbindet Authoring Guides, Browser-Smokes, Theme-Matrix, RMT Shell Authoring, Component Lab und Reference-Gates.
+
+## Gate-Gruppen
+
+| Gruppe | Gate | Zweck |
+| --- | --- | --- |
+| Foundation | `component-shell-contract` | Component Shell Contract `xtend.component.shell.v1` |
+| Foundation | `component-styling-contract` | Styling Contract `xtend.component.styling.v1` |
+| Foundation | `runtime-a11y-contract` | Runtime A11y `xtend.component.runtime-a11y.v1` |
+| Foundation | `component-ux-performance` | Performance Profile `xtend.component.ux-performance.v1` |
+| Foundation | `component-network-contract` | Component Network `xtend.component.network.v1` |
+| RMT | `rmt-shell-authoring-ux` | RMT Shell Authoring `xtend.rmt.shell-authoring.v1` |
+| Lab | `component-lab-ux-inspector` | Component Lab UX Inspector `xtend.epic11.component-lab-ux-inspector.v1` |
+| Browser | `component-ux-browser-smokes` | Browser UX Smokes `xtend.epic11.component-ux-browser-smokes.v1` |
+| Visual | `component-shell-theme-matrix` | Component Shell Theme Matrix `xtend.epic11.component-shell-theme-matrix.v1` |
+| Docs | `component-ux-authoring-docs` | Component UX Authoring Docs `xtend.epic11.component-ux-authoring-docs.v1` |
+| Migration | `component-long-tail-migration` | Legacy Long-Tail Migration `xtend.epic11.legacy-long-tail-migration.v1` |
+| Handoff | `epic11-enterprise-ux-handoff` | Epic 11 Enterprise UX Handoff `xtend.epic11.enterprise-ux-handoff.v1` |
+| References | `references` | Dokumentations- und Demo-Referenzpfade |
+
+## Schneller Epic-11-Check
+
+```bash
+node scripts/run_xtend_tests.js component-network-contract rmt-shell-authoring-ux form-controls-ux feedback-status-ux navigation-routing-ux overlay-interaction-ux layout-display-media-ux component-lab-ux-inspector component-ux-browser-smokes component-shell-theme-matrix component-ux-authoring-docs component-long-tail-migration epic11-enterprise-ux-handoff references --json
+```
+
+## PR-Gate
+
+Der PR-Gate enthaelt die Component-UX-Doku, damit neue Guides nicht neben der produktiven Gate-Kette veralten:
+
+```bash
+npm run test:pr
+```
+
+## Release-Hinweis
+
+`component-shell-theme-matrix` ist noch kein Screenshot-Diff-Runner. Es ist der deterministische, lokale Contract fuer spaetere visuelle Snapshot-Automation. Bis echte Snapshots angeschlossen sind, bleibt diese Matrix die verbindliche Quelle fuer Theme-, Motion-, Density- und Viewport-Pflichten.
+
+## Handoff
+
+Nach `WP-E11-18` ist Epic 11 im Modus `completed-with-accepted-long-tail-handoff` abgeschlossen. Die Legacy Long-Tail Migration ist als Plan gatebar; offene Umsetzungen bleiben bewusst in Wellen priorisiert.

package/docs/components/x-rmt-lifecycle-demo-build.md

@@ -0,0 +1,60 @@
+# x-rmt-lifecycle-demo-build - XTend Komponente
+
+## Uebersicht
+
+`<x-rmt-lifecycle-demo-build>` ist die aus `xtendrmt/rmt-lifecycle-demo.rmt` erzeugte RC1-Test-Build-Komponente. Sie dient als lokaler, manifestierter Nachweis fuer den RMT-vNext-App-Build-Pfad und verbindet Root-Lifecycle, Template-Extension, Scheduler-Handschlag, A11y-Profil und Performance-Profil in einem Custom Element.
+
+## Verwendung
+
+```html
+<x-rmt-lifecycle-demo-build
+  variant="rc1"
+  aria-label="RMT Lifecycle Demo Build">
+  Lifecycle Demo
+</x-rmt-lifecycle-demo-build>
+<script type="module" src="/components/x-rmt-lifecycle-demo-build.js"></script>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `variant` | String | Markiert die lokale Demo-Variante fuer Fixtures und Browser-Smokes. |
+| `aria-label` | String | Pflichtname fuer die semantische `region` im Shadow DOM. |
+
+## Scaffold Contracts
+
+Die generierte Komponente exposes folgende statische Contracts:
+
+- `xtendScaffoldWiring` mit `xtend.scaffold.feature-wiring.v1`
+- `xtendScaffoldExtensionPoints` mit `xtend.scaffold.component-extension-points.v1`
+- `xtendScaffoldA11yProfile` mit `xtend.a11y.profile.v1`
+- `xtendScaffoldPerformanceProfile` mit `xtend.performance.component-profile.v1`
+
+Der Root-Lifecycle nutzt `xtend.rmt.root-handshake.v1` und bleibt ueber Scheduler Endpoint Hints an den XTend Host Adapter gekoppelt. Der RMT Kernel liest die XTend-Komponente nicht direkt, sondern behandelt Component Refs, Templates und Events als Daten.
+
+## Events
+
+| Event | Beschreibung |
+|-------|--------------|
+| `rmt-lifecycle-demo-build-ready` | im Scaffold-Wiring deklarierter Ready-Kanal fuer Host-Adapter. |
+| `rmt-lifecycle-demo-build-changed` | im Scaffold-Wiring deklarierter State-Change-Kanal fuer Host-Adapter. |
+
+## A11y-Profil
+
+Das A11y-Profil setzt `role="region"`, verlangt ein `aria-label`, beschreibt Screenreader-Signale fuer semantische Region und Statusaenderungen und fuehrt Reduced-Motion-/Forced-Colors-Regeln im Shadow DOM.
+
+## Performance-Profil
+
+Das Performance-Profil nutzt `xtend.performance.component-profile.v1`, `budgetClass: critical`, `lane: user-blocking` und `hydrationPolicy: visible`. Kritische Messpunkte sind Loader, Mount, Hydration, Render, Update, State-Sync und Event-Action.
+
+## RC1 Build Boundary
+
+Die Komponente ist absichtlich ein Build-Artefakt aus dem RMT-vNext-Pfad:
+
+- Source: `xtendrmt/rmt-lifecycle-demo.rmt`
+- Generator: `xtend-builder/generators/rmt-build.js`
+- Build-Komponente: `components/x-rmt-lifecycle-demo-build.js`
+- Browser Smoke: `tests/browser/fixtures/rmt-lifecycle-demo-rmt-build-smoke.html`
+
+Damit ist sie Teil der RC1-Test-Build-Recovery: Manifest, Docs, Suite, Fixture und Public Types bleiben im Component Catalog sichtbar.

package/docs/components/xalert.md

@@ -0,0 +1,81 @@
+# xalert - XTend Komponente
+
+## Uebersicht
+
+`<x-alert>` ist die prominente Feedback-Komponente fuer laenger sichtbare Hinweise, Warnungen und Fehler. Im Unterschied zu Toasts kann ein Alert blockierend oder explizit schliessbar auftreten.
+
+## Verwendung
+
+```html
+<x-alert type="error" closable overlay aria-label="Fehlerhinweis">
+  Ein Fehler ist aufgetreten
+</x-alert>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `type` | string | `info`, `success`, `warning`, `error` |
+| `closable` | boolean | zeigt einen Schliessen-Button |
+| `duration` | number | optionale Auto-Close-Dauer |
+| `overlay` | boolean | zeigt den Alert als zentriertes Overlay |
+| `aria-label` | string | Screenreader-Label |
+
+## Events
+
+| Event | Beschreibung |
+|-------|--------------|
+| `alert-shown` | nach dem Anzeigen des Alerts |
+| `alert-dismissed` | nach dem Schliessen des Alerts |
+
+## State-Contract
+
+Die Instanz spiegelt ihren Zustand kompatibel in `xstate`:
+
+- `xtend.component.x-alert.<id>`
+- `xalert-state-<id>`
+
+Das Event-Detail enthaelt unter anderem:
+
+```js
+{
+  id: 'alert-abc123',
+  type: 'error',
+  closable: true,
+  overlay: true,
+  dismissed: false,
+  reason: 'connected'
+}
+```
+
+## Runtime-Contract
+
+- API-gemanagte Alerts werden aggregiert in `xstate.get('ui').alerts`
+- die Instanz selbst fuehrt ihren Lifecycle ueber `alert-shown` und `alert-dismissed`
+- API und Komponente sprechen keine separaten Close-Pfade mehr
+
+## Feedback Status UX ab WP-E11-09
+
+`<x-alert>` stellt `xtendFeedbackStatusUxProfile` mit `xtend.component.feedback-status-ux-profile.v1` bereit. Das Profil beschreibt `x-alert` als laenger sichtbare Feedback-Shell mit `alert-shown`, `alert-dismissed`, `xalert-state-<id>`, `a11y.announce`, Fabric-Lane `a11y` und RMT Shell Authoring.
+
+Fehler und Warnungen nutzen assertive Live Regions; neutrale und erfolgreiche Hinweise bleiben polite. Event-Details enthalten `source: 'x-alert'` und `stateKey`, sodass Form-, Router- oder RMT-Adapter Alerts konsistent schedulen und diagnostizieren koennen.
+
+## Kontrastfarben
+
+`<x-alert>` nutzt solide Kontrastfarben ohne Farbverlaeufe. Die Varianten `info`, `success`, `warning` und `error` setzen jeweils eigene Tokens fuer Hintergrund, Text, Border und Accent, damit Alerts in Light- und Dark-Mode lesbar bleiben und ihre Signalwirkung behalten.
+
+Die wichtigsten Theme-Tokens sind:
+
+- `--xtend-alert-info-bg`, `--xtend-alert-info-fg`, `--xtend-alert-info-border`, `--xtend-alert-info-accent`
+- `--xtend-alert-success-bg`, `--xtend-alert-success-fg`, `--xtend-alert-success-border`, `--xtend-alert-success-accent`
+- `--xtend-alert-warning-bg`, `--xtend-alert-warning-fg`, `--xtend-alert-warning-border`, `--xtend-alert-warning-accent`
+- `--xtend-alert-error-bg`, `--xtend-alert-error-fg`, `--xtend-alert-error-border`, `--xtend-alert-error-accent`
+
+Fuer Dark-Mode koennen dieselben Tokens mit dem Suffix `-dark` ueberschrieben werden, etwa `--xtend-alert-error-bg-dark`.
+
+## Hinweise
+
+- Alerts sind fuer inhaltlich wichtigere, laenger sichtbare oder blockierende Rueckmeldungen gedacht
+- `window.XAlert.show()` ist der bevorzugte Einstieg fuer API-gemanagte Alerts
+- fuer kurze, nicht blockierende Hinweise ist `x-toast` die passendere Komponente

package/docs/components/xbutton.md

@@ -0,0 +1,103 @@
+# xbutton – XTend Komponente
+
+> **Siehe auch:** [xalert](./xalert.md), [xstate](./xstate.md), [xtheme](./xtheme.md)
+
+## Uebersicht
+
+`<x-button>` ist der interaktive Basisbutton fuer XTend Apps. Die Komponente bietet Varianten, Groessen, Ladezustand, dekorative Icons, Focus-Visible-Styles, Reduced-Motion-/Forced-Colors-Pfade und seit `WP-E12-06` ein explizites Performance- und Interaction-Budget.
+
+## Features
+
+- Varianten: `primary`, `secondary`, `danger`
+- Groessen: `small`, normal, `large`
+- Ladezustand ueber `loading` und `aria-busy`
+- Disabled-/Busy-Guards fuer Click- und Keyboard-Aktivierung
+- Touch Target Token `--xtend-button-min-touch-target`
+- State-Integration ueber `xbutton-state-<id>`
+- Fabric-kompatible Events `button-interaction` und `button-performance-measured`
+- Slot-Fallback bleibt erhalten, damit spaet nachgereichte Inhalte wie `x-icon` sauber hydrieren
+
+## Verwendung
+
+```html
+<x-button variant="primary" size="large" icon="/icons/save.svg">Speichern</x-button>
+<x-button loading aria-label="Speichern laeuft">Bitte warten...</x-button>
+<x-button aria-label="Theme wechseln"><x-icon name="sun" decorative></x-icon></x-button>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `disabled` | Boolean | Deaktiviert Interaktion und setzt `aria-disabled` |
+| `label` | String | Fallback-Text, wenn kein Slot-Inhalt vorhanden ist |
+| `variant` | String | `primary`, `secondary`, `danger` oder Custom-Klasse |
+| `size` | String | `small`, normal oder `large` |
+| `icon` | String | SVG-String oder Icon-URL |
+| `loading` | Boolean | Zeigt Spinner, sperrt Interaktion und setzt Busy-State |
+| `aria-label` | String | Zugänglicher Name fuer Screenreader |
+| `aria-busy` | Boolean | Expliziter Busy-Status ohne zwingenden Loading-Spinner |
+
+## Events
+
+| Event | Beschreibung |
+|-------|--------------|
+| `click` | weitergeleiteter Click der internen Button-Shell |
+| `focus` / `blur` | weitergeleitete Focus-Events |
+| `loading-start` | `loading` wurde aktiviert |
+| `loading-end` | `loading` wurde deaktiviert |
+| `button-interaction` | Fabric-kompatible Interaktionsmessung fuer Click/Keyboard |
+| `button-performance-measured` | Performance-Messpunkt nach Hydration, Update oder Interaktion |
+
+## API
+
+| Methode | Zweck |
+|---------|-------|
+| `setLoading(loading, options?)` | toggelt den Ladezustand programmatisch |
+| `getPerformanceBudget()` | liefert die ms-Budgets des Performance-Profils |
+| `getInteractionBudget()` | liefert Click-, Keyboard-, Busy- und Touch-Target-Budgets |
+| `snapshotPerformance()` | liefert den aktuellen Snapshot `xtend.component.performance-snapshot.v1` |
+
+## Performance-Profil
+
+`x-button` besitzt das Runtime-Profil `xtend.performance.component-profile.v1` mit:
+
+- `budgetClass`: `interactive-small`
+- `lane`: `user-blocking`
+- `hydrationPolicy`: `visible`
+- `criticalMeasurements`: `xtend.component.hydrate`, `xtend.component.render`, `xtend.component.update`, `xtend.event.handler`, `xtend.interaction.click`, `xtend.interaction.keyboard`
+- `budgetsMs`: `hydrate`, `renderUpdate`, `eventAction`, `keyboardAction`, `busyToggle`, `stateSync`
+
+Damit kann der Button von Fabric, Regression-Gates und spaeteren RMT Shells als kleine, user-blocking Interaktion geplant werden.
+
+## RMT und Fabric
+
+Die Komponente deklariert `xtendRmtMetadata` mit `adapter: 'xtend.component'`, `templateMode: 'dom_descriptor'`, `eventBindingMode: 'dom-event-to-rmt-command'` und der Boundary `no-rmt-kernel-import-of-xtend-types`. RMT kann den Button damit authoren und schedulen, ohne XTend-Typen in den Kernel zu importieren.
+
+Fabric konsumiert:
+
+- `button-interaction`
+- `button-performance-measured`
+- `snapshotPerformance()`
+- State-Key `xbutton-state-<id>`
+
+## Styling & Theming
+
+```css
+x-button {
+  --primary-color: #007bff;
+  --focus-color: #80bfff;
+  --xtend-button-min-touch-target: 44px;
+}
+```
+
+Der Button respektiert `prefers-reduced-motion` und `forced-colors`. In Forced-Colors-Modus werden Systemfarben, sichtbarer Fokus und ein textuelles Busy-Signal genutzt.
+
+## Accessibility
+
+- nativer Button im Shadow DOM mit `role="button"`
+- sichtbarer `:focus-visible` Zustand
+- `aria-disabled` und `aria-busy`
+- dekorative Icons mit leerem `alt`
+- minimale Touch-Zielflaeche ueber Token
+- Keyboard-Aktivierung ueber native Button-Semantik plus Messpunkt fuer `Enter` und `Space`