@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/de/components/xmodal.md

@@ -0,0 +1,82 @@
+# xmodal - XTend Komponente
+
+## Uebersicht
+
+`<x-modal>` ist die state-getriebene Modal-Komponente fuer XTend. Sie wird vor allem ueber `window.XModal.show()` verwendet, kann aber auch direkt im DOM mit Attributen und Slots betrieben werden.
+
+## Verwendung
+
+```html
+<x-modal title="Hinweis" open>
+  <p>Modal-Inhalt</p>
+</x-modal>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `open` | boolean | Modal ist geoeffnet |
+| `overlay` | boolean | zeigt einen Overlay-Hintergrund |
+| `title` | string | Titel des Modals |
+| `content` | string | textueller Inhalt |
+| `actions` | string | JSON-Array fuer Action-Buttons |
+
+## Slots
+
+| Slot | Beschreibung |
+|------|--------------|
+| default | Hauptinhalt des Modals |
+| `actions` | optionaler Action-Bereich |
+
+## Events
+
+| Event | Beschreibung |
+|-------|--------------|
+| `modal-opened` | nach erfolgreichem Oeffnen |
+| `modal-closed` | nach erfolgreichem Schliessen |
+| `modal-action` | wenn ein konfigurierte Action ausgewaehlt wird |
+
+## API
+
+- `element.open()`
+- `element.close()`
+
+Open-State wird ueber dieselben Pfade gefuehrt:
+
+- `xtend.component.x-modal.<id>.open`
+- `modal-open-<id>`
+
+## Runtime-Contract
+
+- API-gemanagte Modals lesen Titel, Inhalt und Aktionen aus `xstate.get('ui').modals`
+- ESC, Overlay-Klick und Close-Button schreiben den Open-State zurueck
+- API-gemanagte Modals entfernen sich nach dem Schliessen aus `ui.modals` und aus dem DOM
+- direkt eingebettete Overlay-Modals werden waehrend `open` in eine `document.body` Portal-Schicht gehoben, damit Blur und Overlay den gesamten Viewport abdecken
+
+## Hinweise
+
+- `modal-action` enthaelt die ausgewaehlte Action-Definition im Event-Detail
+- fuer API-gemanagte Modals ist `window.XModal.show()` der bevorzugte Einstieg
+- der Focus-Ruecksprung zum zuletzt aktiven Element ist Teil des Standardverhaltens
+
+## Overlay Interaction UX Profil
+
+Seit `WP-E11-11` deklariert `<x-modal>` das Runtime-Profil `xtend.component.overlay-interaction-ux-profile.v1` ueber `xtendOverlayInteractionUxProfile`.
+
+| Feld | Wert |
+|------|------|
+| Family | `modal-dialog` |
+| State Key | `modal-open-<id>` |
+| Schedule | `overlay.stack.open` |
+| Commands | `open`, `close`, `focus-trap`, `apply-inert`, `lock-scroll`, `snapshot` |
+
+Das Profil legt Focus Trap, Rueckfokus, Escape-Topmost-Regel, Background-Inert, balanced Scroll Lock und eine dokumentweite Portal-Schicht fest. RMT beschreibt diese Regeln shell-first ueber `tests/fixtures/rmt-overlay-interaction-ux.rmt`; der RMT-Kernel importiert weiterhin keine XTend-Typen.
+
+Die Portal-Schicht ist dokumentweit: Wenn ein Modal mit `overlay` in verschachtelten App-Shells, XRouter-Routen oder transformierten Layout-Containern geoeffnet wird, wird der Host temporaer unter `document.body` geparkt und nach dem Schliessen an seine urspruengliche Position zurueckgesetzt. Dadurch bleibt die Slot-Faehigkeit erhalten, waehrend Overlay und Blur nicht auf den lokalen `main`- oder Route-Container begrenzt sind.
+
+## ECH-WP-06 Overlay-Paritaet
+
+`x-modal` expose `surface`, `backdrop`, `close` und `content` als gemeinsame Overlay-Parts. `overlay` bleibt als Alias fuer `backdrop` erhalten. Host-Themes koennen Backdrop, Surface, Text, Elevation, Radius, Z-Index, Action-Text, Close-Flaeche und Focus Ring ueber `--xtend-overlay-*`, `--modal-*` oder `--xmodal-*` Tokens steuern.
+
+`x-modal` ist modal: Focus Trap, Background-Inert, Scroll Lock, Escape und Rueckfokus sind Teil des Standardpfads. Ein Modal ohne `overlay` behält die Surface-Parts, rendert aber keinen visuellen Backdrop.

package/docs/de/components/xplayer.md

@@ -0,0 +1,104 @@
+# xplayer – XTend Komponente
+
+> **Siehe auch:** [xlightbox](./xlightbox.md)
+
+## Übersicht
+
+`<x-player>` ist eine vielseitige Media-Player-Komponente für Audio und Video. Sie unterstützt Playlists, Custom Controls, Theming, State-Integration, Download, Media-Chooser und Vollbild.
+
+---
+
+## Features
+- Wiedergabe von Audio/Video
+- Playlists und Media-Controls
+- Download-Button (optional)
+- Media-Chooser (Quellenauswahl)
+- Poster-Bild für Videos
+- Vollbildmodus
+- State-Integration via xstate
+- Theming via CSS Custom Properties
+
+---
+
+## Verwendung
+
+```html
+<x-player src="song.mp3" type="audio"></x-player>
+<x-player src="video.mp4" poster="cover.jpg" type="video" title="Demo Video" downloadable="true"></x-player>
+```
+
+---
+
+## Attribute
+| Attribut         | Typ     | Beschreibung                                              |
+|------------------|---------|----------------------------------------------------------|
+| `src`            | String  | Media-URL (Audio/Video)                                  |
+| `poster`         | String  | Vorschaubild für Video                                   |
+| `type`           | String  | Medientyp (`audio` oder `video`, Standard: `video`)      |
+| `media-chooser`  | String  | `true` für Quellenauswahl (Dropdown)                     |
+| `downloadable`   | String  | `true` für Download-Button                               |
+| `autoplay`       | Boolean | Autoplay beim Laden                                      |
+| `title`          | String  | Titelanzeige im Player                                   |
+| `height`         | String  | Höhe (z.B. `360`)                                        |
+| `width`          | String  | Breite (z.B. `640`)                                      |
+
+---
+
+## Events
+| Event             | Beschreibung                                 |
+|-------------------|----------------------------------------------|
+| `xplayer-play`    | Wiedergabe gestartet, Detail: `{ currentTime }` |
+| `xplayer-pause`   | Wiedergabe pausiert, Detail: `{ currentTime }`  |
+| `xplayer-mute`    | Stummschaltung geändert, Detail: `{ muted }`   |
+| `xplayer-volume`  | Lautstärke geändert, Detail: `{ volume }`      |
+
+---
+
+## API
+- **Abspielen:** `element.play()`
+- **Pausieren:** `element.pause()`
+- **State-Integration:** Automatisch via xstate
+- **Vollbild:** `element.requestFullscreen()`
+
+---
+
+## Beispiel: Dynamisch per JS
+
+```js
+const player = document.createElement('x-player');
+player.setAttribute('src', 'song.mp3');
+document.body.appendChild(player);
+player.play();
+```
+
+---
+
+## Styling & Theming
+
+```css
+x-player {
+  --primary-color: #4fc3f7;
+  --border-radius: 8px;
+  /* Weitere Custom Properties siehe CSS */
+}
+```
+
+---
+
+## Accessibility
+- Semantisches HTML, ARIA
+- Tastaturbedienung
+
+---
+
+*Letzte Aktualisierung: 16. Juli 2025*
+
+## Layout Display Media UX Profil
+
+`x-player` stellt ab `WP-E11-12` das Profil `xtend.component.layout-display-media-ux-profile.v1` bereit. Media kann dadurch shell-first gerendert und erst ueber `media.lazy.load` bzw. `media.playback.user` geplant werden. Der State-Key lautet `xplayer-state-<id>`.
+
+- Profil-Getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `media.lazy.load`
+- Events: `xplayer-play`, `xplayer-pause`, `xplayer-fullscreen`, `xplayer-pip`
+- Snapshot: `snapshot()`
+- CSS Parts: `root`, `media`, `controls`, `progress`, `overlay`

package/docs/de/components/xpopover.md

@@ -0,0 +1,67 @@
+# xpopover - XTend Komponente
+
+> **Siehe auch:** [xtooltip](./xtooltip.md), [xdrawer](./xdrawer.md), [xdialog](./xdialog.md), [xmodal](./xmodal.md)
+
+## Uebersicht
+
+`<x-popover>` ist ein interaktives, verankertes Overlay aus `WP-E10-11`. Es eignet sich fuer Filter, Menues, Toolbars und kontextuelle Aktionen, kann modal betrieben werden und bleibt als Custom Element ueber RMT beschreibbar.
+
+## Verwendung
+
+```html
+<x-popover id="filters" placement="bottom" modal label="Filter options">
+  <button slot="trigger" type="button">Open filters</button>
+  <p>Filter content can be mounted by RMT.</p>
+  <button slot="actions" type="button">Apply</button>
+</x-popover>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `open` | Boolean | oeffnet das Popover kontrolliert |
+| `placement` | String | `top`, `right`, `bottom` oder `left` |
+| `modal` | Boolean | aktiviert Focus Trap und `aria-modal` |
+| `anchor` | String | vorbereitetes Anchor-Mapping fuer RMT Authoring |
+| `label` | String | zugaenglicher Name fuer den Dialog |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `popover-opened` | `{ id, open, source, placement, modal }` |
+| `popover-closed` | `{ id, open, source, placement, modal }` |
+
+## API
+
+- `show()`
+- `hide()`
+- `toggle()`
+
+## State, RMT und Fabric
+
+`<x-popover>` schreibt nach `xpopover-open-<id>`. RMT nutzt `xtend.rmt.component-contract.v1`, `dom_descriptor` Templates und kann Events als `dom-event-to-rmt-command` binden. Fuer interaktive UIs ist die Lane `user-blocking`; der Kernel Boundary bleibt `no-rmt-kernel-import-of-xtend-types`.
+
+## A11y und Performance
+
+Das Popover nutzt `role="dialog"`, `aria-expanded`, `aria-controls`, optional `aria-modal` und Focus Return. `Escape`, Outside Click und `focus-return` sind Pflichtsignale. Das Performance-Profil ist `xtend.performance.component-profile.v1` mit `budgetClass: 'overlay-medium'`, `lane: 'user-blocking'` und `hydrationPolicy: 'visible'`.
+
+## Overlay Interaction UX Profil
+
+Seit `WP-E11-11` deklariert `<x-popover>` das Runtime-Profil `xtend.component.overlay-interaction-ux-profile.v1` ueber `xtendOverlayInteractionUxProfile`.
+
+| Feld | Wert |
+|------|------|
+| Family | `popover` |
+| State Key | `xpopover-open-<id>` |
+| Schedule | `overlay.position.update` |
+| Commands | `show`, `hide`, `toggle`, `focus-trap`, `snapshot` |
+
+Das Profil trennt die leichte Anchor-Schicht vom modal optionalen Betrieb. Focus Trap wird nur bei `modal` aktiviert, Escape schliesst das oberste Popover und Outside Click bleibt als bewusstes Dismiss-Verhalten dokumentiert.
+
+## ECH-WP-06 Overlay-Paritaet
+
+`x-popover` expose `surface`, `backdrop`, `close` und `content` als gemeinsame Overlay-Parts. Der Backdrop wird nur bei `modal` sichtbar; der Close-Button ist tokenisiert und kann ueber `--popover-close-display` sowie `--xpopover-close-*` an Corporate-Patterns angepasst werden.
+
+Der Default bleibt nicht-modal: kein Inert und kein Scroll Lock. Mit `modal` aktiviert das Popover Backdrop, Focus Trap, Escape und Rueckfokus. Surface, Text, Border, Elevation, Radius, Backdrop und Z-Index laufen ueber `--xtend-overlay-*`, `--popover-*` oder `--xpopover-*` Tokens.

package/docs/de/components/xprogress.md

@@ -0,0 +1,56 @@
+# xprogress - XTend Komponente
+
+> **Siehe auch:** [xstatus](./xstatus.md), [xspinner](./xspinner.md), [xstate](./xstate.md)
+
+## Uebersicht
+
+`<x-progress>` ist das RMT-first Progress-Control aus `WP-E10-10`. Es visualisiert determinate und indeterminate Fortschritte, meldet Fortschrittsereignisse an Fabric/Telemetry und kann in Shell-first RMT-Templates fuer Hydration, Upload, Route- oder Worker-Aufgaben eingesetzt werden.
+
+## Verwendung
+
+```html
+<x-progress id="route-progress" value="64" max="100" status="Hydrating route" busy>
+  <span slot="label">Route hydration</span>
+</x-progress>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `value` | Number | aktueller Wert |
+| `max` | Number | Maximalwert |
+| `label` | String | Label ohne Slot |
+| `status` | String | Statusmeldung fuer Screenreader und UI |
+| `indeterminate` | Boolean | aktiviert unbestimmten Fortschritt |
+| `busy` | Boolean | setzt `aria-busy` |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `progress-changed` | `{ value, max, percent, source: 'x-progress' }` |
+| `progress-complete` | `{ value, max, percent: 100, source: 'x-progress' }` |
+
+## API
+
+- `element.value`
+- `element.max`
+- `element.percent`
+- `element.setProgress(value)`
+- `element.complete()`
+- `element.reset()`
+
+## State, RMT und Fabric
+
+`<x-progress>` schreibt nach `xprogress-value-<id>` und ist fuer `feedback.progress.update` vorbereitet. Die RMT-Metadaten nutzen `xtend.rmt.component-contract.v1`, `adapter: 'xtend.component'` und `kernelBoundary: 'no-rmt-kernel-import-of-xtend-types'`. Dadurch kann RMT Progress als scheduled UI-Feedback behandeln, waehrend XTend die Web Component rendert.
+
+## A11y und Performance
+
+Das Control nutzt `role="progressbar"`, `aria-valuenow`, `aria-valuemax`, `aria-valuetext`, `aria-busy` und eine polite Statusregion. Das Performance-Profil ist `xtend.performance.component-profile.v1` mit `budgetClass: 'feedback-small'`, `lane: 'background'` und `hydrationPolicy: 'visible'`.
+
+## Feedback Status UX ab WP-E11-09
+
+`<x-progress>` stellt `xtendFeedbackStatusUxProfile` mit `xtend.component.feedback-status-ux-profile.v1` bereit. Das Profil beschreibt Progress als scheduled Feedback mit `progress-changed`, `progress-complete`, `xprogress-value-<id>`, `feedback.progress.update`, Fabric-Lane `background`, A11y-Lane `a11y` und RMT Shell Authoring.
+
+Determinate und indeterminate Progress-Zustaende duerfen nicht nur ueber Farbe oder Animation vermittelt werden. `aria-valuetext`, die Statusregion und Reduced-Motion-Regeln bleiben deshalb Teil der Public UX-Oberflaeche.

package/docs/de/components/xradio.md

@@ -0,0 +1,103 @@
+# xradio – XTend Komponente
+
+> **Siehe auch:** [xform](./xform.md), [xinput](./xinput.md), [xstate](./xstate.md)
+
+## Uebersicht
+
+`<x-radio>` vervollstaendigt die TypeScript-first Selection Controls aus `WP-E10-09`. Die Komponente koordiniert Gruppen ueber `name`, unterstuetzt Keyboard-Navigation und liefert RMT-, Fabric-, A11y- und Performance-Metadaten fuer RMT-first Apps.
+
+## Verwendung
+
+```html
+<x-radio id="plan-starter" name="plan" value="starter">
+  <span slot="label">Starter</span>
+</x-radio>
+<x-radio id="plan-pro" name="plan" value="pro" checked>
+  <span slot="label">Pro</span>
+</x-radio>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `name` | String | Gruppen- und Formularname |
+| `value` | String | Wert des Radio-Controls |
+| `checked` | Boolean | aktueller Auswahlzustand |
+| `required` | Boolean | aktiviert Validierung |
+| `disabled` | Boolean | deaktiviert das Control |
+| `label` | String | ARIA-/Textlabel ohne Slot |
+
+## Slots
+
+| Slot | Zweck |
+|------|-------|
+| `label` | sichtbares Label |
+| `hint` | zusaetzlicher Hinweistext |
+| `error` | Validierungsfehler |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `radio-changed` | `{ checked, value, name, source: 'x-radio' }` |
+| `radio-invalid` | `{ checked, value, name, message, source: 'x-radio' }` |
+
+## API
+
+- `element.checked`
+- `element.value`
+- `element.name`
+- `element.check()`
+- `element.checkValidity()`
+- `element.reportValidity()`
+- `element.validate()`
+- `element.reset()`
+- `element.focus()`
+
+## State, RMT und Fabric
+
+`<x-radio>` schreibt den Einzelzustand nach `xradio-checked-<id>` und den Gruppenwert nach `xradio-value-<name>`. Die RMT-Metadaten nutzen `xtend.rmt.component-contract.v1`; RMT kann eine Radio-Gruppe als DOM-Descriptor templaten und die UI ueber `xtend.component` schedulen, ohne XTend in den RMT-Kernel zu importieren.
+
+## A11y und Performance
+
+Die Komponente nutzt `role="radio"`, `aria-checked`, `aria-describedby`, Space-Aktivierung sowie Arrow-Key-Navigation innerhalb der Gruppe. Das Performance-Profil ist `xtend.performance.component-profile.v1` mit `budgetClass: 'interactive-small'`, `lane: 'user-blocking'` und `hydrationPolicy: 'visible'`.
+
+## Form Controls UX ab WP-E11-08
+
+`<x-radio>` stellt `xtendFormControlUxProfile` mit `xtend.component.form-control-ux-profile.v1` bereit. Das Profil verbindet Label, Hint, Error, `radio-changed`, `radio-invalid`, `xradio-value-<name>`, `ui.user-blocking.input`, Fabric-Lane `user-blocking` und RMT Shell Authoring.
+
+## ECH-WP-08 Form Theme/A11y Hardening
+
+`signatureDesign`: Enterprise-Radio-Option mit robuster nativer Fokusfuehrung, gruppensicherer Validierung und separat themebarem Selection-Icon.
+
+| Token | Zweck |
+| --- | --- |
+| `--xtend-form-text` | Host-Textfarbe |
+| `--xtend-form-control-surface` | Native Control-Flaeche |
+| `--xtend-form-control-text` | Control-Text-Fallback |
+| `--xtend-form-label-text` | Label |
+| `--xtend-form-helper-text` | Helper |
+| `--xtend-form-error-text` | Fehlertext |
+| `--xtend-form-error-surface` | Fehlerflaeche |
+| `--xtend-form-error-border` | Fehlerkante und Marker |
+| `--xtend-form-focus-ring` | Focus-Outline |
+| `--xtend-form-radius` | Radio-/Error-Radius |
+| `--xtend-form-gap` | Label-/Helper-Abstand |
+| `--xtend-form-font-family` | Form-Typografie |
+| `--xtend-form-control-font-size` | Label-Schrift |
+| `--xtend-form-helper-font-size` | Helper/Error-Schrift |
+| `--xtend-form-icon-color` | Radio-Akzent |
+
+Density-Profile: `comfortable`, `compact`, `dense`. Invalid ist nicht farb-only und wird per `aria-invalid` gespiegelt.
+
+```css
+[data-xtend-form-theme="enterprise-foreign"] x-radio {
+  --xtend-form-icon-color: #8f4f2a;
+  --xtend-form-label-text: #22312c;
+  --xtend-form-helper-text: #596861;
+  --xtend-form-error-text: #7d231c;
+  --xtend-form-error-border: #a64036;
+  --xtend-form-focus-ring: 3px solid #8f4f2a;
+}
+```

package/docs/de/components/xrouter.md

@@ -0,0 +1,260 @@
+# xrouter - XTend Komponente
+
+## Uebersicht
+
+`<x-router>` ist der clientseitige Router fuer XTend-SPAs. Er verarbeitet deklarative `<x-route>`-Definitionen, unterstuetzt Hash- und History-Mode und synchronisiert Navigation mit `xstate`.
+
+## Kernverhalten
+
+- nur direkte `<x-route>`-Kinder von `<x-router>` gelten als Top-Level-Routen
+- Nested Routes werden ausschliesslich ueber direkte Kind-Routen der jeweiligen Elternroute verarbeitet
+- Navigation kann deklarativ, per `x-link` oder programmatisch ueber `xstate.set('router-navigate', '/ziel')` angestossen werden
+
+## Verwendung
+
+```html
+<x-router mode="history">
+  <x-route path="/" component="x-home" import="/components/xhome.js" title="Home"></x-route>
+  <x-route path="/docs" component="x-docs" import="/components/xdocs.js" title="Docs">
+    <x-route path=":topic" component="x-doc-topic" import="/components/xdoctopic.js" title-template="{{params.topic}} | XTend Docs"></x-route>
+  </x-route>
+  <x-route path="*" component="x-notfound" import="/components/xnotfound.js"></x-route>
+</x-router>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `mode` | string | `hash` oder `history` |
+| `routesrc` | string | optionale JSON-Quelle fuer Routen |
+| `skeleton` | string | aktiviert einen nativen Route-Skeleton-Fallback waehrend Import, Definition und Hydration |
+| `skeleton-lines` | number | Anzahl der Skeleton-Zeilen fuer den Route-Fallback |
+| `skeleton-min-height` | string | stabile Mindesthoehe des Route-Fallbacks |
+| `title-template` / `document-title-template` | string | globales Template fuer den Dokumenttitel, z.B. `{{title}} | App` |
+| `title-prefix` / `title-suffix` | string | einfacher Prefix/Suffix fuer Routentitel ohne Template |
+| `default-title` | string | Fallback, wenn eine Route keinen Titel definiert |
+
+## Document Title Rewrite und SEO Meta
+
+XRouter schreibt nach jedem erfolgreichen Route-Match den Browser-Titel und die SEO-Metatags `description` und `keywords`. Dadurch bleibt eine SPA nicht auf dem Initialtitel stehen, und RMT-Routen koennen Titelinformationen ohne XTend-spezifische Runtime-Imports liefern.
+
+Direkte Route-Attribute:
+
+```html
+<x-router mode="hash" document-title-template="{{title}} | XTend">
+  <x-route
+    path="/components/x-router"
+    component="x-doc-page"
+    title="XRouter"
+    document-title="XRouter Routing und SEO"
+    meta-description="Routing, Seitentitel und RMT Route Metadata"
+    meta-keywords="xtend, xrouter, rmt">
+  </x-route>
+</x-router>
+```
+
+RMT kann dieselben Werte ueber Route-Records und `metadata` liefern:
+
+```json
+{
+  "id": "settings",
+  "path": "/settings",
+  "router": "xtend.xrouter",
+  "component": "page.settings",
+  "metadata": {
+    "title": "Settings",
+    "documentTitle": "Settings | XTend App",
+    "metaDescription": "Einstellungen der XTend RMT App",
+    "seo": {
+      "keywords": ["xtend", "rmt", "routing"]
+    }
+  }
+}
+```
+
+Unterstuetzte Template-Variablen sind `{{title}}`, `{{routeTitle}}`, `{{documentTitle}}`, `{{path}}`, `{{routeId}}`, `{{component}}`, `{{params.name}}`, `{{query.name}}` und `{{metadata.name}}`. Bei Nested Routes gewinnt die Leaf-Route, damit Deep Links eigene Titel bekommen.
+
+## Events
+
+| Event | Beschreibung |
+|-------|--------------|
+| `xrouter-before-navigate` | cancelable, vor programmatischer Router-Navigation |
+| `route-changed` | wird nach erfolgreicher Navigation emittiert |
+| `routechange` | Legacy-Alias zu `route-changed` |
+| `xrouter-after-navigate` | Legacy-Window-Event nach dem Rendern einer Route |
+| `route-announced` | wird nach dem Schreiben der Route-Live-Region emittiert |
+| `xrouter-skeleton-shown` / `xrouter-skeleton-hidden` | markieren den nativen Route-Skeleton-Lifecycle |
+| `xrouter-route-hydrated` | wird nach Loader-basierter Hydration des gerenderten Route-Subtrees emittiert |
+| `xrouter-title-updated` | wird nach dem Schreiben von `document.title` und SEO-Metatags emittiert |
+| `xrouter-scroll-boundary-normalized` | wird emittiert, wenn der Router nach einem Route-Wechsel eine stale Scrollposition oder eine Deadzone unterhalb des Contentbereichs korrigiert |
+| `xrouter-navigation-overlays-closed` | wird emittiert, wenn der Router vor einem Route-Render offene App-Shell-Overlays wie `x-header` schliesst |
+
+## XState-Keys
+
+- `router-navigate`: programmatischer Navigationseingang
+- `router-navigated`: zuletzt angestossener Zielpfad
+- `router-current`: aktuell gerenderte Route
+- `router-rendered`: zuletzt erfolgreich gerenderte Route
+- `router-scroll-boundary`: Legacy-Snapshot der letzten Scroll-Boundary-Pruefung
+- `router-closed-navigation-overlays`: Legacy-Snapshot der vor dem Route-Render geschlossenen Navigationsoverlays
+- `xtend.router.current`: kanonischer Route Context
+- `xtend.router.announcement`: zuletzt angekuendigte Route
+- `xtend.router.documentMeta`: zuletzt gesetzter Dokumenttitel und SEO-Metatags
+- `xtend.router.skeleton`: aktueller Route-Skeleton-Lifecycle
+- `xtend.router.scrollBoundary`: kanonischer Snapshot der letzten Scroll-Boundary-Pruefung
+- `xtend.router.closedNavigationOverlays`: kanonischer Snapshot der vor dem Route-Render geschlossenen Navigationsoverlays
+
+Die kanonischen Spiegelpfade werden ebenfalls gepflegt:
+
+- `xtend.router.lastNavigated`
+- `xtend.router.current`
+- `xtend.router.lastRendered`
+
+## Route-Detail
+
+`route-changed` und `xrouter-after-navigate` liefern ein Detailobjekt mit:
+
+```js
+{
+  path: '/docs/router',
+  routeId: 'docs-topic',
+  component: 'x-doc-topic',
+  params: { topic: 'router' },
+  query: {},
+  template: 'docs.topic.shell',
+  scheduleRef: 'route.visible.render',
+  title: 'Router',
+  documentTitle: 'Router | XTend Docs',
+  meta: {
+    schema: 'xtend.router.document-meta.v1',
+    scheduleRef: 'route.document.title.rewrite'
+  },
+  metadata: {}
+}
+```
+
+Bei Nested Routes ist `component` die Leaf-Route; `params` werden aus der kompletten Match-Kette zusammengefuehrt.
+
+## Skeleton und Lazy Hydration
+
+XRouter kann Route-Komponenten shell-first laden:
+
+```html
+<x-router mode="hash" skeleton="article" skeleton-lines="8" skeleton-min-height="20rem">
+  <x-route
+    path="/docs"
+    component="xtend-doc-page"
+    import="/docs/utils/pageloader.js"
+    hydrate-schedule="docs.page.hydrate">
+  </x-route>
+</x-router>
+```
+
+Wenn der Component-Tag noch nicht definiert ist, nutzt XRouter zuerst das explizite `import` der Route. Fehlt ein Import, delegiert er an `window.XTendLoader.ensureComponent(componentTag)`, sodass Manifest-Komponenten route-nativ lazy geladen werden koennen. Nach dem Rendern hydriert XRouter den Route-Subtree ueber `window.XTendLoader.hydrateTree(...)`.
+
+## Navigation Routing UX Profil
+
+`<x-router>` stellt `xtendNavigationRoutingUxProfile` mit `xtend.component.navigation-routing-ux-profile.v1` bereit. Das Profil beschreibt `x-router` als Router-Outlet mit `route-changed`, `route-announced`, `xrouter-before-navigate`, `xtend.router.current`, `route.visible.render`, `route.focus.restore`, `a11y.announce`, Fabric-Lane `transition` und RMT Shell Authoring.
+
+Nach erfolgreichem Rendern fokussiert der Router sein Outlet und schreibt eine polite, atomare Live Region. Dadurch koennen RMT und Fabric Route-Render, Focus Restore und Screenreader-Announcement getrennt schedulen, ohne dass der RMT-Kernel XTend-Interna importiert.
+
+Die neuen Diagnostics-Details enthalten `source: 'x-router'`, `stateKey` und `scheduleRef`, sodass `x-link`, Feedback-Komponenten und RMT-Scheduler denselben Route Context teilen koennen.
+
+## Scroll Boundary, Overlays und Deadzone-Schutz
+
+Vor jedem erfolgreichen Route-Render schliesst `<x-router>` offene Navigationsoverlays, die einen stabilen Komponentenvertrag fuer `isMenuOpen()` und `toggleMenu(false, options)` anbieten. Aktuell wird dadurch vor allem `x-header` stabilisiert: Ein geoeffnetes Menue bleibt kein Layoutfaktor der vorherigen Seite und erzeugt beim Wechsel auf eine kuerzere Route keine Deadzone.
+
+Nach dem Render setzt `<x-router>` die native Scroll Restoration auf `manual`, scrollt zum Seitenanfang oder zum angegebenen `scroll-to`-Ziel und prueft die Dokumenthoehe in Microtask-, Frame- und Settled-Timeout-Phasen erneut. Wenn der Browser noch eine stale Scrollposition aus der vorherigen, laengeren Route haelt oder die aktuelle Position hinter dem neuen maximalen Scrollbereich liegt, normalisiert der Router die Position und schreibt einen Snapshot nach `xtend.router.scrollBoundary`.
+
+Der Snapshot folgt `xtend.router.scroll-boundary.v1` und enthaelt unter anderem `path`, `phase`, `strategy`, `viewportHeight`, `scrollHeight`, `maxScrollTop`, `previousTop`, `normalizedTop`, `normalized` und `deadzoneDetected`. Dadurch koennen Fabric/RMT-Diagnostics Deadzones sichtbar machen, ohne App-spezifische Scroll-Hacks zu brauchen.
+
+## RMT / XTendRMT Adapter
+
+Seit Epic 05 / `WP-E05-10` kann XRouter native RMT Routes ueber den Adapter-Contract `xtend.rmt.xrouter-adapter.v1` konsumieren.
+
+```js
+const adapter = window.xtend.rmt.createRmtXRouterAdapter({ routerElement });
+adapter.registerRoutes(runtimeRegistry);
+adapter.navigate({ routeId: 'home' }, { mapping });
+```
+
+Die stabile Adapter-ID ist `xtend.xrouter`. Der Adapter konsumiert `routeRegistry.byRouter["xtend.xrouter"]`, mappt `RmtRouteRegistryEntry` auf XRouter-kompatible Records und ruft am Zielrouter `registerRoutes(...)` bzw. `navigate(...)` auf.
+
+`<x-router>` stellt dafuer bereit:
+
+- `registerRoutes(routes, options)`
+- `navigate(to, options)`
+- `reuse-component` als opt-in fuer InsularHydration bei SPA-Routen, deren Ziel denselben Component-Tag nutzt und `updateRoute(context)` oder `routeChangedCallback(context)` implementiert
+
+RMT-relevante Route-Daten werden als Attribute auf `<x-route>` erhalten:
+
+- `data-rmt-route-id`
+- `data-rmt-router`
+- `data-rmt-template`
+- `data-rmt-schedule`
+- `data-rmt-params`
+- `data-rmt-query`
+- `data-rmt-metadata`
+
+XRouter bleibt damit produktiver Adapter fuer RMT Routes, aber kein RMT-Kernelwissen.
+
+Weitere Details:
+
+- [XTendRMT App-DSL Reference](../xtendrmt-app-dsl.md)
+- [XTendRMT Runtime Bridge](../xtendrmt-runtime-bridge.md)
+- [XTendRMT Native Authoring Guide](../xtendrmt-native-authoring.md)
+
+## Hinweise
+
+- `routesrc` wird vor dem ersten Rendern geladen.
+- Lazy Loading erfolgt ueber das `import`-Attribut der jeweiligen Route.
+- Guards (`before-enter`) und Lifecycle-Hooks bleiben unterstuetzt.
+- Mit `reuse-component` kann eine App-Shell ihre Route-Komponente behalten; XRouter aktualisiert dann Params, Query und State und feuert `xrouter-route-reused`.
+- RMT-Schedule-Refs werden ueber `data-rmt-schedule` an Route-Details weitergereicht.
+- Scroll-Boundary-Normalisierung laeuft zentral im Router und sollte nicht in App-Shells dupliziert werden.
+- Router-Aenderungen im Core sollten gegen `node scripts/verify_xtend_core_contracts.js` geprueft werden.
+
+## ECH-WP-09 Token-Tabelle und Navigation States
+
+`signatureDesign`: `x-router` ist die ruhige Route-Outlet-Basis fuer Enterprise-Shells. Der Router selbst delegiert Active/Current/Selected an `x-link`, `x-menu`, `x-tabs` und `x-header`, stellt aber denselben Navigation-State-Contract, Route Announcements und Focus Restore bereit.
+
+| Token | Zweck |
+| --- | --- |
+| `--xtend-nav-surface` | optionale Outlet-/Route-Surface |
+| `--xtend-nav-text` | Outlet-Text und vererbte Navigationsfarbe |
+| `--xtend-nav-border-color` | geteilte Navigationskante fuer Route-Shells |
+| `--xtend-nav-radius` | geteilte Radius-Vorgabe |
+| `--xtend-nav-gap` | geteilte Navigation-Abstaende |
+| `--xtend-nav-font-family` | vererbte Navigationstypografie |
+| `--xtend-nav-font-size` | vererbte Navigationstextgroesse |
+| `--xtend-nav-active-surface` | Active/Current/Selected Flaeche fuer angeschlossene Navigation |
+| `--xtend-nav-active-text` | Active/Current/Selected Text |
+| `--xtend-nav-current-indicator` | nicht farb-only Current-Indikator |
+| `--xtend-nav-hover-surface` | Hover-Flaeche fuer angeschlossene Navigation |
+| `--xtend-nav-focus-ring` | Route-Focus und Navigation-Focus |
+| `--xtend-nav-disabled-opacity` | Disabled-Dimmung fuer angeschlossene Navigation |
+
+## ECH-WP-09 Keyboard-Verhalten
+
+Der Router fokussiert nach dem Rendern das Outlet und emittiert `route-announced` ueber eine polite Live Region. Link- und Menue-Keyboard-Verhalten bleibt in den jeweiligen Navigationselementen; der Router haelt den Route Context `xtend.router.current`, sodass Active/Current/Selected per `aria-current="page"` und `aria-selected="true"` synchronisiert werden koennen.
+
+## ECH-WP-09 Fremdtheme
+
+```css
+[data-xtend-nav-theme="enterprise-foreign"] x-router {
+  --xtend-nav-surface: transparent;
+  --xtend-nav-text: #17231f;
+  --xtend-nav-border-color: rgba(23, 35, 31, 0.22);
+  --xtend-nav-radius: 0.35rem;
+  --xtend-nav-gap: 0.45rem;
+  --xtend-nav-font-family: "Aptos", "Segoe UI", sans-serif;
+  --xtend-nav-font-size: 1rem;
+  --xtend-nav-active-surface: #173f35;
+  --xtend-nav-active-text: #fffaf0;
+  --xtend-nav-current-indicator: #b56b35;
+  --xtend-nav-hover-surface: rgba(181, 107, 53, 0.14);
+  --xtend-nav-focus-ring: 3px solid #b56b35;
+  --xtend-nav-disabled-opacity: 0.44;
+}
+```