@ccslabs/xtend 0.1.0-rc.1

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

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

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

@@ -0,0 +1,47 @@
+# SurfaceManager Window Runtime
+
+`WP-SM-03` macht den SurfaceManager erstmals sichtbar: `x-surface-manager` verwaltet den Controller und `x-surface-window` ist die erste WindowManager-Surface.
+
+- Contract: `xtend.surface.window-runtime.v1`
+- Manager: `components/xsurfacemanager.js`
+- Window: `components/xsurfacewindow.js`
+- Controller: `components/xsurfacemanager-controller.js`
+- Gate: `node scripts/run_xtend_tests.js surface-manager --json`
+
+## Beispiel
+
+```html
+<x-surface-manager id="workbench" manager-id="workbench.manager">
+  <x-surface-window
+    slot="windows"
+    surface-id="workbench.inspector"
+    label="Inspector"
+    open
+    draggable
+    resizable
+    initial-x="96"
+    initial-y="88"
+    initial-width="520"
+    initial-height="360">
+    <section>Inspector content</section>
+  </x-surface-window>
+</x-surface-manager>
+```
+
+## Manager
+
+`x-surface-manager` bietet `registerSurface`, `openSurface`, `closeSurface`, `focusSurface`, `updateSurface`, `moveSurface`, `resizeSurface`, `minimizeSurface`, `maximizeSurface`, `restoreSurface` und `snapshot`.
+
+Slots: `windows`, `panels`, `overlays`, `default`.
+
+Events: `surface-manager-ready`, `surface-registered`, `surface-opened`, `surface-closed`, `surface-focused`, `surface-updated`, `surface-layout-changed`.
+
+## Window
+
+`x-surface-window` bietet `toSurfaceRecord`, `applySurfaceSnapshot`, `openWindow`, `closeWindow`, `focusWindow`, `minimizeWindow`, `maximizeWindow` und `restoreWindow`.
+
+Das Element sendet `surface-window-command`. Der Manager fuehrt daraus die Controller-Operation aus und spiegelt den Snapshot zurueck.
+
+## Handoff
+
+`WP-SM-04` erweitert diese Runtime um `x-side-panel` und responsive Surface Modes. Die Window-Runtime bleibt der erste Multi Window Beweis und darf keine zweite Registry neben dem Controller einfuehren.

package/docs/surface-manager-workbench-fixture.md

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

package/docs/third-party-design-authoring.md

@@ -0,0 +1,406 @@
+# Drittanbieter Design Authoring
+
+Docs Contract: `xtend.enterprise.third-party-authoring-guide.v1`
+
+Workpackage: `ECH-WP-11`
+
+Lokaler Gate:
+
+```bash
+node scripts/run_xtend_tests.js enterprise-third-party-authoring-guide --json
+npm run test:enterprise-third-party-authoring-guide
+```
+
+Dieser Guide richtet sich an Teams, die XTend-Komponenten in ein eigenes Corporate Design, White-Label-Produkt oder internes Enterprise Designsystem einbinden wollen. Der Zielpfad ist: XTend bleibt optisch hochwertig und eigenstaendig, aber alle sichtbaren Entscheidungen laufen ueber XTend.css, XTheme, CSS Parts, Slots, Attribute oder Icon Packs. Forks von Komponenten sind kein regulaerer Skinning-Pfad.
+
+## Prinzipien
+
+1. Corporate Tokens zuerst definieren, dann Komponententokens ableiten.
+2. XTend Signature UI als Qualitaetsbasis behalten, aber Markenfarbe, Typografie, Radius, Elevation und Dichte bewusst ersetzen.
+3. Shadow-DOM-Interna nicht selektieren. Skinning passiert ueber CSS Custom Properties und `::part(...)`.
+4. Light, Dark, High Contrast, Forced Colors, Reduced Motion, Comfortable, Compact und Dense sind Pflichtvarianten.
+5. Controls verwenden `x-icon`, Inline-SVG oder tokenisierte CSS-Grafik, nie sichtbare Textzeichen.
+6. Status, Active, Error, Disabled und Focus duerfen nicht nur ueber Farbe kommunizieren.
+
+## XTend.css Override Patterns
+
+Corporate Overrides gehoeren in eine eigene Cascade Layer. Dadurch bleiben Host-Tokens nachvollziehbar, und Produktteams koennen XTend-Updates einspielen, ohne Shadow-DOM-Regeln zu kopieren.
+
+```css
+@layer xtend-customer {
+  :root {
+    --acme-ink: #17231f;
+    --acme-muted: #5f6b64;
+    --acme-canvas: #f7f4ee;
+    --acme-panel: #fffdf8;
+    --acme-action: #0e6e8f;
+    --acme-action-strong: #173f35;
+    --acme-warm: #b56b35;
+    --acme-edge: rgba(23, 35, 31, 0.22);
+    --acme-radius-control: 0.35rem;
+    --acme-radius-panel: 0.55rem;
+    --acme-focus: 3px solid var(--acme-warm);
+    --acme-font-body: "Aptos", "Segoe UI", system-ui, sans-serif;
+    --acme-font-display: "Aptos Display", "Aptos", "Segoe UI", system-ui, sans-serif;
+    --acme-font-code: "Cascadia Code", "SFMono-Regular", Consolas, monospace;
+
+    --xtend-surface: var(--acme-canvas);
+    --xtend-surface-muted: var(--acme-panel);
+    --xtend-text: var(--acme-ink);
+    --xtend-color-primary: var(--acme-action);
+    --xtend-border-color: var(--acme-edge);
+    --xtend-focus-outline: var(--acme-focus);
+    --xtend-radius: var(--acme-radius-panel);
+    --xtend-font-family: var(--acme-font-body);
+    --xtend-font-family-body: var(--acme-font-body);
+    --xtend-font-family-heading: var(--acme-font-display);
+    --xtend-font-family-control: var(--acme-font-body);
+    --xtend-font-family-code: var(--acme-font-code);
+  }
+
+  :root[data-theme="dark"] {
+    --acme-ink: #f6f1e8;
+    --acme-muted: #d4c9b8;
+    --acme-canvas: #121916;
+    --acme-panel: #1c2823;
+    --acme-action: #8bd4e6;
+    --acme-action-strong: #b56b35;
+    --acme-edge: rgba(246, 241, 232, 0.2);
+  }
+
+  :root[data-theme="high-contrast"] {
+    --acme-ink: #ffffff;
+    --acme-muted: #ffffff;
+    --acme-canvas: #000000;
+    --acme-panel: #000000;
+    --acme-action: #ffff00;
+    --acme-action-strong: #ffffff;
+    --acme-edge: #ffffff;
+    --acme-focus: 3px solid #ffff00;
+  }
+
+  :root[data-theme="forced-colors"] {
+    --acme-ink: CanvasText;
+    --acme-muted: CanvasText;
+    --acme-canvas: Canvas;
+    --acme-panel: Canvas;
+    --acme-action: Highlight;
+    --acme-action-strong: Highlight;
+    --acme-edge: CanvasText;
+    --acme-focus: 2px solid Highlight;
+  }
+}
+```
+
+## XTheme Token Bridge
+
+`x-theme` und `window.XTend.theme` sind der Runtime-Pfad fuer Theme-Wechsel, Density, Reduced Motion und Forced Colors. Ein Corporate Theme sollte dieselben Werte setzen wie XTend.css, damit statische CSS-Overrides und Runtime-Wechsel identisch bleiben.
+
+```js
+window.XTend.theme.registerTheme('acme-enterprise', {
+  '--xtend-surface-page': '#f7f4ee',
+  '--xtend-surface-panel': '#fffdf8',
+  '--xtend-surface-raised': '#ffffff',
+  '--xtend-text-primary': '#17231f',
+  '--xtend-text-muted': '#5f6b64',
+  '--xtend-color-action': '#0e6e8f',
+  '--xtend-color-action-hover': '#173f35',
+  '--xtend-text-on-action': '#fffaf0',
+  '--xtend-border-subtle': 'rgba(23, 35, 31, 0.22)',
+  '--xtend-radius-control': '0.35rem',
+  '--xtend-radius-panel': '0.55rem',
+  '--xtend-space-control-gap': '0.55rem',
+  '--xtend-elevation-2': '0 14px 34px rgba(23, 35, 31, 0.14)',
+  '--xtend-font-family-body': '"Aptos", "Segoe UI", system-ui, sans-serif',
+  '--xtend-font-family-heading': '"Aptos Display", "Aptos", "Segoe UI", system-ui, sans-serif',
+  '--xtend-header-surface': 'var(--xtend-surface-panel)',
+  '--xtend-header-menu-surface': 'var(--xtend-surface-raised)',
+  '--xtend-button-primary-surface': 'var(--xtend-color-action)',
+  '--xtend-button-primary-text': 'var(--xtend-text-on-action)',
+  '--xtend-menu-item-hover-surface': 'rgba(181, 107, 53, 0.14)',
+  '--xtend-drawer-overlay-surface': 'rgba(23, 35, 31, 0.45)',
+  '--xtend-modal-overlay-surface': 'rgba(23, 35, 31, 0.45)',
+  '--xtend-icon-color': 'currentColor'
+});
+
+window.XTend.theme.setTheme('acme-enterprise');
+window.XTend.theme.setDensity('compact');
+```
+
+Pflichtmodi:
+
+| Modus | Regel |
+|-------|-------|
+| `light` | Text, Icons, Controls und Focus muessen auf hellen Flaechen lesbar bleiben |
+| `dark` | keine hart gesetzten Light-Flaechen ohne dunklen Text-Fallback |
+| `high-contrast` | aktive und fehlerhafte Zustaende brauchen Form, Border oder Marker |
+| `forced-colors` | Systemfarben wie `Canvas`, `CanvasText`, `Highlight`, `HighlightText`, `ButtonFace`, `ButtonText` verwenden |
+
+Density-Presets:
+
+| Density | Einsatz |
+|---------|---------|
+| `comfortable` | Default fuer gemischte Enterprise-Shells |
+| `compact` | Toolbars, Datendichte, Workbench-Shells |
+| `dense` | Navigation, Filterleisten, Tabellenumfelder |
+
+## CSS Parts
+
+CSS Parts sind Skinning API. Verwende sie fuer Zonen, nicht fuer private Shadow-DOM-Strukturen.
+
+```css
+@layer xtend-customer {
+  x-header::part(root) {
+    border-block-end: 1px solid var(--acme-edge);
+  }
+
+  x-header::part(menu-surface),
+  x-drawer::part(surface),
+  x-modal::part(surface),
+  x-dialog::part(surface),
+  x-popover::part(surface) {
+    border: 1px solid var(--acme-edge);
+    border-radius: var(--acme-radius-panel);
+  }
+
+  x-button::part(control),
+  x-menu::part(item) {
+    border-radius: var(--acme-radius-control);
+  }
+
+  x-icon::part(icon),
+  x-header::part(trigger-icon) {
+    color: currentColor;
+  }
+}
+```
+
+Regel: Ein `::part(...)` darf Corporate-Optik setzen, aber keine semantische Bedienbarkeit entfernen. Focus, Disabled, Busy, Active und Error muessen erhalten bleiben.
+
+## Icon Pack Registrierung
+
+Produkticons gehoeren in ein lokales Icon Pack. Remote-CDNs sind kein XTend-Default-Pfad.
+
+```js
+window.XTend.icons.register({
+  id: 'acme',
+  label: 'Acme Enterprise Icons',
+  cdnAllowed: false,
+  icons: {
+    product: {
+      aliases: ['brand-mark'],
+      nodes: [
+        { tag: 'path', attrs: { d: 'M12 3 21 8v8l-9 5-9-5V8Z' } }
+      ]
+    },
+    command: {
+      nodes: [
+        { tag: 'path', attrs: { d: 'M5 7h14M5 12h14M5 17h14' } }
+      ]
+    }
+  }
+});
+```
+
+Controls brauchen ein echtes Button-Element, einen zugaenglichen Namen und getrennte Parts fuer Control und Icon. Sichtbare Zeichen wie `X`, `+`, `-`, `...` oder Emoji sind als Control-Grafik nicht erlaubt.
+
+## Layout Modes
+
+Layoutvarianten sind Public API. Host-Apps sollen Modi deklarativ setzen und per Token feinjustieren.
+
+```html
+<x-header
+  menu-mode="side-panel"
+  menu-placement="end"
+  menu-modal
+  menu-width="min(30rem, 92vw)"
+  menu-max-height="calc(100dvh - 2rem)"
+  menu-align="stretch">
+  <span slot="title">Acme Operations</span>
+  <x-link slot="nav" href="/overview" aria-current="page">Overview</x-link>
+  <x-link slot="nav" href="/control-room">Control Room</x-link>
+</x-header>
+```
+
+`x-header` unterstuetzt `drawer`, `side-panel`, `popover`, `fullscreen` und `inline-main`. Modale Varianten brauchen Escape, Focus Return und bei Focus Trap einen sichtbaren Backdrop. Nicht-modale Varianten duerfen den Hauptinhalt nicht aus dem Lesefluss nehmen.
+
+Overlay-nahe Komponenten nutzen gemeinsame Skinning-Zonen:
+
+| Komponente | Modi/Variante | Pflichtparts |
+|------------|---------------|--------------|
+| `x-drawer` | Drawer/Overlay | `surface`, `backdrop`, `close`, `content` |
+| `x-side-panel` | docked, pinned, overlay, collapsed | `surface`, `backdrop`, `close`, `content` |
+| `x-modal` | modal overlay | `surface`, `backdrop`, `close`, `content` |
+| `x-dialog` | modal dialog | `surface`, `backdrop`, `close`, `content` |
+| `x-popover` | non-modal oder `modal` | `surface`, `backdrop`, `close`, `content` |
+
+## A11y-Dos and Donts
+
+| Do | Dont |
+|----|------|
+| sichtbaren `focus-visible` Ring ueber Token erhalten | Fokus durch `outline: none` ohne Ersatz entfernen |
+| `prefers-reduced-motion` bis in Overlay- und Feedback-Komponenten respektieren | Motion nur in Light Mode testen |
+| `forced-colors` mit `Canvas`, `CanvasText`, `Highlight` und `HighlightText` pruefen | Markenfarben in Forced Colors erzwingen |
+| Active, Selected, Error und Disabled nicht nur ueber Farbe darstellen | Status nur durch Rot/Gruen kommunizieren |
+| Long Labels mit `overflow-wrap` und stabiler Control-Hoehe absichern | Text in Buttons, Tabs oder Menues clippen |
+| Icon Controls mit `aria-label`, `part="... control"` und `part="... icon"` authoren | sichtbare Textglyphen als Close/Menu/Disclosure verwenden |
+
+Status- und Routeninformationen muessen in jedem Theme lesbar bleiben und nicht nur ueber Farbe kommunizieren. Nutze Border, Marker, Unterstreichung, Icon, Text oder Form als zweites Signal.
+
+## Vollstaendiges Fremdtheme-Beispiel
+
+Dieses Beispiel kombiniert XTend.css, XTheme, CSS Parts, Icon Pack, Header Mode, Density und A11y-Modi. Es ist bewusst nicht blau-generisch: die Palette mischt Tinte, warmes Panel, kuehles Action-Blau, tiefes Gruen und Kupfer-Akzent.
+
+```html
+<html data-theme="light" data-xtend-density="compact">
+  <head>
+    <link rel="stylesheet" href="/xtend.css">
+    <style>
+      @layer xtend-customer {
+        :root {
+          --acme-ink: #17231f;
+          --acme-canvas: #f7f4ee;
+          --acme-panel: #fffdf8;
+          --acme-action: #0e6e8f;
+          --acme-action-strong: #173f35;
+          --acme-warm: #b56b35;
+          --acme-edge: rgba(23, 35, 31, 0.22);
+          --acme-focus: 3px solid var(--acme-warm);
+          --acme-font-body: "Aptos", "Segoe UI", system-ui, sans-serif;
+          --acme-font-display: "Aptos Display", "Aptos", "Segoe UI", system-ui, sans-serif;
+
+          --xtend-surface: var(--acme-canvas);
+          --xtend-surface-muted: var(--acme-panel);
+          --xtend-text: var(--acme-ink);
+          --xtend-border-color: var(--acme-edge);
+          --xtend-color-primary: var(--acme-action);
+          --xtend-focus-outline: var(--acme-focus);
+          --xtend-font-family-body: var(--acme-font-body);
+          --xtend-font-family-heading: var(--acme-font-display);
+          --xtend-header-surface: var(--acme-panel);
+          --xtend-header-menu-surface: #ffffff;
+          --xtend-header-menu-backdrop: rgba(23, 35, 31, 0.45);
+          --xtend-button-primary-surface: var(--acme-action);
+          --xtend-button-primary-text: #fffaf0;
+          --xtend-menu-item-hover-surface: rgba(181, 107, 53, 0.14);
+          --xtend-nav-current-indicator: var(--acme-warm);
+          --xtend-overlay-surface: #ffffff;
+          --xtend-overlay-text: var(--acme-ink);
+          --xtend-overlay-backdrop: rgba(23, 35, 31, 0.45);
+        }
+
+        :root[data-theme="dark"] {
+          --acme-ink: #f6f1e8;
+          --acme-canvas: #121916;
+          --acme-panel: #1c2823;
+          --acme-action: #8bd4e6;
+          --acme-action-strong: #b56b35;
+          --acme-edge: rgba(246, 241, 232, 0.2);
+          --xtend-button-primary-text: #121916;
+        }
+
+        :root[data-theme="forced-colors"] {
+          --acme-ink: CanvasText;
+          --acme-canvas: Canvas;
+          --acme-panel: Canvas;
+          --acme-action: Highlight;
+          --acme-action-strong: Highlight;
+          --acme-warm: Highlight;
+          --acme-edge: CanvasText;
+          --xtend-button-primary-text: HighlightText;
+          --xtend-overlay-backdrop: Canvas;
+        }
+
+        @media (prefers-reduced-motion: reduce) {
+          :root {
+            --xtend-motion-duration-fast: 0ms;
+            --xtend-motion-duration-base: 0ms;
+          }
+        }
+
+        x-header::part(root),
+        x-modal::part(surface),
+        x-drawer::part(surface) {
+          border: 1px solid var(--acme-edge);
+        }
+
+        x-header::part(trigger-icon),
+        x-button::part(icon),
+        x-menu::part(disclosure-icon) {
+          color: currentColor;
+        }
+      }
+    </style>
+    <script type="module" src="/xtend-loader.js" data-manifest="/components/manifest.json"></script>
+  </head>
+  <body>
+    <x-theme></x-theme>
+    <x-header menu-mode="side-panel" menu-placement="end" menu-modal>
+      <span slot="title">Acme Operations</span>
+      <x-link slot="nav" href="/overview" aria-current="page">Overview</x-link>
+      <x-link slot="nav" href="/reports">Reports</x-link>
+      <x-button slot="actions" variant="primary">
+        <x-icon pack="acme" name="command" decorative></x-icon>
+        Command
+      </x-button>
+    </x-header>
+  </body>
+</html>
+```
+
+## P0 Token-/Part-Referenz
+
+Jede P0-Komponente muss in diesem Guide eine Token-/Part-Referenz haben. Die Detailtabellen bleiben in den Komponentendokumenten, damit sie neben Attributen, Slots, Events und A11y-Regeln gepflegt werden.
+
+| Komponente | Doku | Alias Prefix | Token-/Part-Tabelle | Pflichtparts |
+|------------|------|--------------|---------------------|--------------|
+| `x-theme` | [xtheme](./components/xtheme.md) | `--xtend-theme-` | `Zentrale XTend-Tokens` / [Design Tokens](./design-tokens.md) | `root` |
+| `x-header` | [xheader](./components/xheader.md) | `--xtend-header-` | `ECH-WP-07 Token-Tabelle und signatureDesign`, `ECH-WP-09 Token-Tabelle und Navigation States` | `root`, `brand`, `trigger`, `trigger-icon`, `menu`, `menu-surface`, `backdrop` |
+| `x-icon` | [xicon](./components/xicon.md) | `--xtend-icon-` | `Styling & Theming`, `ECH-WP-04 Control-Regel` | `root`, `control`, `icon` |
+| `x-button` | [xbutton](./components/xbutton.md) | `--xtend-button-` | `Styling & Theming` | `root`, `control`, `label`, `icon` |
+| `x-menu` | [xmenu](./components/xmenu.md) | `--xtend-menu-` | `ECH-WP-09 Token-Tabelle und Navigation States` | `root`, `nav`, `item`, `disclosure-icon` |
+| `x-drawer` | [xdrawer](./components/xdrawer.md) | `--xtend-drawer-` | `ECH-WP-06 Overlay-Paritaet` | `root`, `surface`, `backdrop`, `close`, `content` |
+| `x-side-panel` | [xsidepanel](./components/xsidepanel.md) | `--xtend-side-panel-` | `ECH-WP-06 Overlay-Paritaet` | `root`, `surface`, `backdrop`, `close`, `content` |
+| `x-modal` | [xmodal](./components/xmodal.md) | `--xtend-modal-` | `ECH-WP-06 Overlay-Paritaet` | `root`, `surface`, `backdrop`, `close`, `content` |
+| `x-dialog` | [xdialog](./components/xdialog.md) | `--xtend-dialog-` | `ECH-WP-06 Overlay-Paritaet` | `root`, `surface`, `backdrop`, `close`, `content` |
+| `x-popover` | [xpopover](./components/xpopover.md) | `--xtend-popover-` | `ECH-WP-06 Overlay-Paritaet` | `root`, `surface`, `backdrop`, `close`, `content` |
+| `x-toast` | [xtoast](./components/xtoast.md) | `--xtend-toast-` | `Styling & Theming` | `root`, `surface`, `content`, `close`, `icon` |
+
+## Migration von Legacy Token-Namen
+
+Legacy Tokens bleiben als Bridge sichtbar, sollen in neuen Corporate Themes aber auf die normalisierte Alias-Schicht gemappt werden.
+
+| Legacy Token | Neuer Alias |
+|--------------|-------------|
+| `--xtend-glass-bg` | `--xtend-surface-overlay` |
+| `--xtend-shadow` | `--xtend-elevation-2` |
+| `--xtend-radius` | `--xtend-radius-md` |
+| `--xtend-font-family` | `--xtend-font-family-body` |
+| `--xtend-overlay-bg` | `--xtend-surface-overlay` |
+| `--xtend-border-color` | `--xtend-border-subtle` |
+| `--header-bg` | `--xtend-header-surface` |
+| `--header-fg` | `--xtend-header-text` |
+| `--drawer-bg` | `--xtend-drawer-surface` |
+| `--drawer-color` | `--xtend-drawer-text` |
+| `--button-text-color` | `--xtend-button-text` |
+
+Migrationsregel: Alte Namen duerfen als Fallback bleiben, aber neue Dokumentation, neue Themes und neue Komponenten muessen die `--xtend-*` Alias-Kette fuehren. Entfernen oder Umbenennen von Public Parts und Tokens braucht Migration Notes.
+
+## Abnahme fuer Corporate Themes
+
+Vor der Uebergabe an ein Host-Designsystem sollten diese Gates laufen:
+
+```bash
+node scripts/run_xtend_tests.js enterprise-third-party-authoring-guide --json
+node scripts/run_xtend_tests.js xtheme-token-alias-layer --json
+node scripts/run_xtend_tests.js enterprise-component-style-audit --json
+node scripts/run_xtend_tests.js enterprise-visual-dom-snapshot-matrix --json
+node scripts/run_xtend_tests.js enterprise-component-flex-release-handoff --json
+node scripts/run_xtend_tests.js component-shell-theme-matrix --json
+```
+
+Die Abnahme ist erst belastbar, wenn Light, Dark, High Contrast, Forced Colors, Reduced Motion, Comfortable, Compact und Dense im selben Corporate Theme geprueft wurden.
+
+## Release Handoff
+
+Ab `ECH-WP-12` fuehrt [Enterprise Component Flex Release Handoff](./enterprise-component-flex-release-handoff.md) den Contract `xtend.enterprise.component-flex-release-handoff.v1`. Er verbindet SemVer-Bewertung, Deprecated Aliases, Migration Notes, Release Checklist und Adoption Risiken fuer Corporate Themes. Der lokale Gate `node scripts/run_xtend_tests.js enterprise-component-flex-release-handoff --json` muss vor Release Owner Review gruen sein; Publishing bleibt bis dahin durch `private-until-release-owner-acceptance` blockiert.

package/docs/trusted-dom-boundary-browser-proof.md

@@ -0,0 +1,32 @@
+# Trusted DOM Boundary Browser Proof
+
+- Contract: `xtend.epic13.trusted-dom-boundary.v1`
+- Fixture: `tests/browser/fixtures/epic13-trusted-dom-boundary-smoke.html`
+- Gate: `node scripts/run_xtend_tests.js epic13-trusted-dom-boundary --json`
+
+## Ziel
+
+Dieser RC1-Gate beweist, dass Parsedown HTML und RMT `htmlFragment` nicht ungeprueft in die DOM-Sinks der Docs-App laufen. Die App rendert weiter Shell-first ueber RMT, aber der Host Adapter sanitized Content, bevor er in den Content-Slot geschrieben wird.
+
+## Regeln
+
+- `parsedownHtml` braucht `xtend.security.trusted-dom-sanitizer.v1`.
+- RMT `htmlFragment` braucht `xtend.security.sanitizing-boundary.v1`.
+- RMT `dom_descriptor` bleibt der bevorzugte Pfad fuer strukturierte Templates.
+- Der RMT Kernel importiert keinen Sanitizer, kein PHP/Parsedown und keine XTend-Typen.
+
+Geblockt werden `script`, `iframe`, Inline-Event-Handler, `javascript:` URLs und `srcdoc`.
+
+## Browsernaher Smoke
+
+Die Fixture legt absichtlich feindliche Inhalte in `window.xtendDocsPages` ab und laedt danach `docs/utils/pageloader.js`. Der Smoke prueft, dass:
+
+- der Content-Slot `data-rmt-sanitized="true"` traegt
+- `data-rmt-trusted-dom-proof="xtend.epic13.trusted-dom-boundary.v1"` gesetzt ist
+- Script-Elemente, Event-Handler, JavaScript-URLs und `srcdoc` entfernt sind
+- sicherer Parsedown-Text erhalten bleibt
+- die Shell weiterhin Shell-first gerendert wird
+
+## Handoff
+
+`WP-E13-11` ist abgeschlossen. `WP-E13-12` ist mit [RC1 Migration Notes](./rc1-migration-notes.md) und `xtend.epic13.rc1-migration-notes-semver.v1` abgeschlossen. `WP-E13-13` ist mit [RC1 Gate Matrix und CI-Handoff](./rc1-gate-matrix-ci-handoff.md) und `xtend.epic13.rc1-gate-matrix-ci-handoff.v1` abgeschlossen.

package/docs/trusted-dom-sanitizing.md

@@ -0,0 +1,110 @@
+# Trusted DOM und Sanitizing
+
+- Contract: `xtend.docs.trusted-dom-sanitizing.v1`
+- Security Policy: `xtend.security.trusted-dom-policy.v1`
+- Sanitizing Boundary: `xtend.security.sanitizing-boundary.v1`
+- Sanitizer Contract: `xtend.security.trusted-dom-sanitizer.v1`
+- Maschinenlesbarer Contract: `security/trusted-dom-policy.js`
+
+## Ziel
+
+XTend behandelt dynamisches Markup als eigene Trust Boundary. Das betrifft besonders RMT `html_fragment`, RMT Template Authoring und die Parsedown-basierte Docs-App.
+
+Diese Seite beschreibt die Entwicklerregel: Markup wird zuerst klassifiziert, dann in einen passenden DOM-Sink geschrieben. Rohe HTML-Strings duerfen nicht nebenbei ueber `innerHTML` landen.
+
+## Markup-Klassen
+
+| Klasse | Quelle | Default |
+|--------|--------|---------|
+| `text` | Labels, Markdown-Text, Body Copy | `textContent` |
+| `attribute` | `aria-label`, `href`, `slot`, `data-*` | validierter `setAttribute` |
+| `structuredTemplate` | RMT `dom_descriptor`, Component Trees | Nodes via `replaceChildren` |
+| `htmlFragment` | RMT `html_fragment` | Sanitizing Boundary |
+| `parsedownHtml` | HTML aus `docs/index.php` / Parsedown | Sanitizing Boundary |
+
+## Erlaubte und eingeschraenkte Sinks
+
+Erlaubt:
+
+- `textContent`
+- validierter `setAttribute`
+- `classList`
+- `dataset` ohne Secrets und ohne Codewerte
+- `append` und `replaceChildren` mit Nodes
+
+Eingeschraenkt:
+
+- `innerHTML`
+- `insertAdjacentHTML`
+- `template.innerHTML`
+
+Diese eingeschraenkten Sinks brauchen `xtend.security.sanitizing-boundary.v1`.
+Browsernahe Docs-/RMT-Sinks muessen zusaetzlich den Sanitizer Contract `xtend.security.trusted-dom-sanitizer.v1` ausweisen.
+
+Verboten im Default:
+
+- Inline-Handler wie `onclick`
+- `eval`
+- `new Function`
+- dynamische Script-Tags aus RMT-, Manifest-, Event- oder Docs-Daten
+
+## RMT Templates
+
+Fuer XTendRMT gilt:
+
+- `dom_descriptor` ist bevorzugt.
+- `html_fragment` ist erlaubt, aber nur mit Trusted-DOM-Boundary.
+- Events nutzen `actionRef`, `commandName`, `routeRef` oder typed Payloads.
+- Der RMT Kernel plant Records und Diagnostics, aber sanitized kein HTML selbst.
+- Host Adapter besitzen den DOM-Sink.
+
+```json
+{
+  "id": "settings.shell",
+  "mode": "html_fragment",
+  "markup": "<x-card></x-card>",
+  "security": {
+    "markupClass": "htmlFragment",
+    "trustBoundary": "xtend.security.sanitizing-boundary.v1",
+    "sink": "trustedDomBoundary"
+  }
+}
+```
+
+## Parsedown Docs-App
+
+Die Docs-App rendert Markdown ueber `docs/index.php` und `docs/utils/parsedown.php`. `Parsedown::setSafeMode(true)` bleibt Pflicht, ersetzt aber keine Trusted-DOM-Policy. Die App Shell selbst wird inzwischen Shell-first aus `docs.app.shell` im RMT-Dokument erzeugt; Parsedown HTML wird danach nur in den `data-rmt-slot="content"` Slot eingesetzt.
+
+Regel:
+
+- Markdown-Dateien sind Content.
+- Parsedown-Ausgabe ist `parsedownHtml`.
+- RMT rendert Shell-Descriptoren und darf Parsedown-Arbeit schedulen.
+- `docs.rich-content` und `docs.media.lazy` bereiten spaetere Rich-HTML- und XPlayer-Tutorial-Slots vor.
+- Sanitizing und DOM-Sinks bleiben Host-Verantwortung.
+- `WP-E13-11` prueft diese Boundary browsernah mit [Trusted DOM Boundary Browser Proof](./trusted-dom-boundary-browser-proof.md), `xtend.epic13.trusted-dom-boundary.v1` und `node scripts/run_xtend_tests.js epic13-trusted-dom-boundary --json`.
+
+## Diagnostics
+
+Spaetere Implementierungen sollen diese Codes nutzen:
+
+- `xtend.security.trusted_dom.required`
+- `xtend.security.sanitizer.missing`
+- `xtend.security.sink.refused`
+- `xtend.security.attribute.refused`
+- `xtend.security.event.refused`
+
+## Gates
+
+```bash
+node --check security/trusted-dom-policy.js
+node scripts/run_xtend_tests.js epic13-trusted-dom-boundary --json
+node scripts/run_xtend_tests.js references --json
+```
+
+## Weiterfuehrende Dokumente
+
+- [XTendRMT Native Authoring](./xtendrmt-native-authoring.md)
+- [Trusted DOM Boundary Browser Proof](./trusted-dom-boundary-browser-proof.md)
+- [XTendRMT Parsedown Scheduling Pilot](./xtendrmt-parsedown-scheduling.md)
+- [XTendRMT App-DSL Reference](./xtendrmt-app-dsl.md)