@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/rmt-vnext-authoring.md

@@ -3,19 +3,46 @@
 - Contract: `xtend.rmt.vnext-release-handoff.v1`
 - Syntax Contract: `xtend.rmt.vnext.grammar.v1`
 - Core Output: `xtend.rmt.core-format.vnext.v1`
-- Reference Demo: `xtendrmt/rmt-vnext-reference-demo.rmt`
-- Gate: `node scripts/run_xtend_tests.js rmt-vnext-release --json`
 
-RMT vNext ist die neue deklarative Authoring-Syntax fuer XTendRMT. Sie bleibt JSON-nah im Ergebnis, ist aber als menschenfreundliche DSL geschrieben und kompiliert deterministisch in das vNext Core Format.
+RMT vNext ist die menschenfreundliche Syntax fuer XTend Apps. Du kannst eine
+vollstaendige UI-Shell in RMT schreiben: State, Selectors, DataSources,
+Actions, Events, Portals, Overlays, Resources, Surfaces und Fabric-Lanes
+liegen in einer `.rmt` Quelle und werden deterministisch in Core- und
+Kernel-Records kompiliert.
 
 ## Grundform
 
 ```rmt
-template xtend.vnext.reference {
-  surface root {
-    lane critical weight 10 {
-      hydrate app-shell
-      hydrate hero-panel when route.visible == true
+template media.manager {
+  state selectedItem type object initial null
+
+  selector visibleItems from datasource library {
+    output card-list
+  }
+
+  datasource library from fixture records.media-items {
+    contract "media.item.v1[]"
+  }
+
+  action select-item {
+    input id string
+    reduce state.selectedItem = input.id
+    emit media.item.selected with action select-item
+  }
+
+  portal app root "#app-root" layer surface
+
+  surface library kind workspace component x-cards {
+    repeat from selector visibleItems
+    key item.id
+    portal app
+
+    lane visible weight 80 {
+      hydrate x-cards from selector visibleItems
+    }
+
+    on card-click target item -> action select-item {
+      payload id from item.id
     }
   }
 }
@@ -25,36 +52,119 @@ Die wichtigsten Bausteine:
 
 | Syntax | Zweck |
 | --- | --- |
-| `template` | gruppiert eine orchestrierte App- oder Dokument-Shell |
-| `surface` | beschreibt Zielbereiche wie `root`, Dialoge, Overlays oder Panels |
+| `template` | gruppiert eine App- oder Dokument-Shell |
+| `state` | beschreibt persistenten oder transienten App-Zustand |
+| `selector` | leitet UI-nahe Views aus State oder DataSources ab |
+| `datasource` | bindet Fixture-, Endpoint-, SSE- oder Worker-Quellen an |
+| `action` | beschreibt User- und Systemaktionen mit Reducern und Effects |
+| `on ... -> action ...` | routet DOM- oder Custom-Events in Actions |
+| `portal` | benennt Mount-Ziele fuer Surfaces und Overlays |
+| `surface` | beschreibt sichtbare UI-Objekte, Listen, Panels oder Pages |
+| `overlay` | beschreibt Toasts, Dialoge, Menues, Popovers und Lightboxes |
+| `resource` | beschreibt Besitz, Import, Stream, Timer und Cleanup |
 | `lane` | steuert Prioritaet, Scheduling und Backpressure |
 | `mount`, `hydrate`, `prewarm`, `dispose` | Lifecycle-Operationen |
 | `when` | deklarative Conditions ohne Funktionsaufrufe oder Eval |
 | `slot` | Composition innerhalb einer Operation |
-| `on ... -> action ...` | Event zu Action-Referenz |
-| `from endpoint/sse/worker` | Data-Source-Referenz |
 | `trust boundary` und `sanitize` | Security-Policy fuer unsichere Daten |
 | `stream` | inkrementelle Streaming-Operation |
 
+## App Shell nur in RMT
+
+Eine vNext-App soll nicht zwischen RMT, App-Platform-JSON und Host-Code
+zerfallen. RMT ist der Authoring-Ort fuer:
+
+- Route- und Shell-Struktur
+- sichtbare Surfaces und Overlay-Portale
+- State- und Selector-Modell
+- Actions, Effects und Event-Payloads
+- Resource Ownership und Cleanup
+- Fabric-Lanes fuer sichtbare, user-blocking, transition, idle,
+  background- und diagnostics-Arbeit
+
+Der Host stellt Komponenten, Router, Browser-APIs und externe Daten bereit.
+Diese Grenze haelt den Kernel framework-neutral und macht die App trotzdem
+vollstaendig beschreibbar.
+
+## XTend UI-Kompatibilitaet
+
+RMT vNext Component Primitives zielen auf den bestehenden XTend-Component-
+Stack. Eine Surface wie `component x-select` wird zu einem DOM Descriptor
+abgesenkt und dann ueber die Component Capability Registry aufgeloest, nicht
+ueber einen produktspezifischen Renderer. Die Registry liest
+`components/manifest.json`, `xtendComponentContract`, `xtendRmtMetadata`,
+public Events, `observedAttributes`, Slots, Parts, Form-Assoziation,
+Accessibility-Profile und Performance-Profile.
+
+Damit erreicht RMT alle 44 public Manifest-Eintraege, waehrend 40 renderbare
+UI-Komponenten ihren normalen Web-Component-Lifecycle behalten. Infrastruktur-
+module wie `x-theme` und `xstate` bleiben Host-Services, keine normalen
+Surface-Elemente. Produktcode soll ueber public Attribute, Properties, Events,
+Parts, Slots und State-Bridges binden, statt `shadowRoot` oder private
+Component-Maps zu patchen.
+
+Details stehen in
+[RMT vNext Component Primitives und XTend UI](./rmt-vnext-component-primitives.md).
+
+## Editor-DX
+
+Der Language Server erkennt vNext-Primitives direkt:
+
+- Completions fuer Primitive-Keywords und klauselnahe Vorschlaege
+- Hover mit Core Pointer und Primitive-Informationen
+- Document Symbols fuer `states`, `selectors`, `actions`, `surfaces`,
+  `portals`, `overlays` und `resources`
+- Code Actions fuer sichere Reparaturen
+- Safe Fix-All fuer `source.fixAll.rmt.vnext.primitives`
+- manuelle Uebergaben fuer Kernel-/Host-Boundaries
+
+Das Snippet `rmt-vnext-primitive-shell` erzeugt eine kleine App Shell mit
+State, Selector, Action, Portal, Surface, Lane und Event-Payload-Contract.
+
+## Migration aus Legacy-Records
+
+Legacy- und App-Platform-JSON bleiben lesbar, sind aber nicht der normale
+Authoring-Pfad. Fuer vorhandene App-Platform-Primitive-Records gibt es:
+
+- `createAppPlatformPrimitiveMigrationPreview(...)` fuer einen vNext-Draft
+- `createAppPlatformPrimitiveMigrationApplyPlan(...)` fuer einen manuellen
+  Apply-Plan ohne automatisches Schreiben
+- `report-only`, `preview-ready`, `apply-plan-ready` und `blocked` als
+  klare Statuswerte
+
+Details stehen in [RMT vNext Primitive Migration](./rmt-vnext-primitive-migration.md).
+
 ## Reference Demo
 
-Die vollstaendige Referenz liegt in `xtendrmt/rmt-vnext-reference-demo.rmt`. Sie deckt Templates, Surfaces, gewichtete Lanes, Conditions, Slots, Events, Endpoint/SSE/Worker Sources, Security Policies und Streaming ab.
+Die vollstaendige Referenz liegt in `xtendrmt/rmt-vnext-reference-demo.rmt`.
+Sie deckt Templates, Surfaces, gewichtete Lanes, Conditions, Slots, Events,
+Endpoint/SSE/Worker Sources, Security Policies und Streaming ab.
 
-Der stabile Compiler-Output liegt in `xtendrmt/rmt-vnext-reference-demo.core.json`. Eine absichtliche Aenderung am Compiler oder an der Syntax muss beide Dateien und die Release-Gates bewusst aktualisieren.
+Der stabile Compiler-Output liegt in
+`xtendrmt/rmt-vnext-reference-demo.core.json`. Wenn Syntax oder Compiler
+absichtlich geaendert werden, muessen Quelle und Core-Output gemeinsam
+aktualisiert werden.
 
 ## Lokal pruefen
 
 ```bash
+node scripts/run_xtend_tests.js rmt-vnext-parser rmt-vnext-compiler rmt-vnext-tooling --json
+node scripts/run_xtend_tests.js rmt-vnext-compatibility --json
+node scripts/run_xtend_tests.js rmt-vnext-component-primitives --json
 node scripts/run_xtend_tests.js rmt-vnext-release --json
-node scripts/run_xtend_tests.js rmt-vnext-parser rmt-vnext-compiler rmt-vnext-regression --json
 ```
 
-Der Release-Gate prueft Docs, Reference Demo, Core-Output, Release-Matrix, Handoff und Referenzpfade. Fuer schnelle Authoring-Checks reichen Parser, Compiler und Regression-Gate.
+Fuer App-Shell-Arbeit reichen normalerweise Parser, Compiler, Tooling und
+Compatibility. Release-Gates pruefen zusaetzlich Referenzdemo, Core-Output,
+Migration und Referenzpfade.
 
 ## Grenzen
 
 - RMT vNext fuehrt keine Host-Runtime im Kernel aus.
 - Conditions sind deklarativ und erlauben keine Funktionsaufrufe.
 - Imports sind statisch und bleiben package-root-gebunden.
-- Legacy JSON bleibt lesbar, Migration bleibt opt-in.
-- Produktive Runtime-Adapter fuer vNext Core sind Folgearbeit, nicht Teil dieses Syntax-Epics.
+- Legacy JSON bleibt kompatibel, aber nicht der bevorzugte Authoring-Pfad.
+- XTend-, XRouter-, DOM- und Browser-Details gehoeren in Adapter.
+- XTend-Component-Integration laeuft ueber public Contracts und die Component
+  Capability Registry, nicht ueber direkte Kernel-Imports oder
+  Shadow-DOM-Monkeypatching.

package/docs/rmt-vnext-component-primitives.md

@@ -0,0 +1,188 @@
+# RMT vNext Component Primitives und XTend UI
+
+- Schema: `xtend.rmt.component-capability-registry.v1`
+- Report Schema: `xtend.rmt.component-capability-registry-report.v1`
+- Runtime: `xtendrmt/rmt-component-capability-registry.js`
+- Export: `@ccslabs/xtend/rmt/component-capability-registry`
+- Local Gate: `node scripts/run_xtend_tests.js rmt-vnext-component-primitives --json`
+- Aggregat: `npm run test:rmt-vnext-primitives:report`
+
+RMT vNext und XTend UI sind keine Parallelwelten. Die Component Primitives
+verbinden RMT-Templates, Kernel Records, DOM Descriptor Renderer und die
+public XTend Web Components ueber eine gemeinsame Capability Registry. RMT
+beschreibt Shell, State, Surfaces, Events und Lifecycle; XTend Components
+liefern die konkreten UI-Bausteine, Accessibility-Profile, Parts, Slots,
+Events und Performance-Profile.
+
+## Source-to-Sea-Fluss
+
+```text
+.rmt template
+  -> RMT Compiler und Core Records
+  -> Kernel Records und Fabric Lanes
+  -> DOM Descriptor Renderer
+  -> Component Capability Registry
+  -> XTend Component aus components/manifest.json
+  -> Browser DOM und Component Lifecycle
+```
+
+Der RMT-Kernel importiert keine XTend-Komponenten und keine XTend-Typen. Die
+Registry liest Manifest, Component Contracts, `xtendRmtMetadata`,
+`observedAttributes`, Events, Slots, Parts, Form-Assoziation sowie A11y- und
+Performance-Profile. Daraus entsteht eine normalisierte Matrix fuer alle 42
+public Eintraege aus `components/manifest.json`.
+
+## Matrix
+
+| Bereich | Abdeckung |
+| --- | --- |
+| Manifest-Eintraege | 44 |
+| Renderbare public UI-Komponenten | 40 |
+| Nicht-visuelle Sonderfaelle | 4 |
+| RMT-Metadaten | 42 Eintraege |
+| Component Contracts | 40 Eintraege |
+| Form-associated Components | 6 |
+
+Nicht-visuelle Sonderfaelle sind `x-theme`, `xstate`, `x-utils` und
+`x-rmt-lifecycle-demo-build`. `x-theme` und `xstate` sind Infrastrukturmodule;
+sie werden ueber Host-/Loader-Dienste genutzt, aber nicht als normale RMT-App-
+UI gerendert. `x-utils` bleibt Utility-Modul, der Lifecycle-Demo-Build bleibt
+Demo-Artefakt.
+
+## Component-Familien
+
+| Familie | Tags |
+| --- | --- |
+| Form | `x-calendar`, `x-checkbox`, `x-form`, `x-input`, `x-radio`, `x-select`, `x-textarea` |
+| Navigation | `x-router`, `x-link`, `x-menu`, `x-drawer` |
+| Overlay/Surface | `x-dialog`, `x-lightbox`, `x-modal`, `x-popover`, `x-side-panel`, `x-surface-manager`, `x-surface-window`, `x-toast`, `x-tooltip` |
+| Media/Feedback/Layout | `x-alert`, `x-button`, `x-cards`, `x-code`, `x-icon`, `x-masonry`, `x-player`, `x-progress`, `x-spinner`, `x-status`, `x-summary`, `x-type`, `x-writer` |
+| Theme/Layout | `x-footer`, `x-header`, `x-hero`, `x-section`, `x-tabs` |
+| Infrastruktur | `x-theme`, `xstate`, `x-utils`, `x-rmt-lifecycle-demo-build` |
+
+Die risikoreichen Familien `form`, `navigation`, `overlay-surface`,
+`media-feedback-layout` und `theme-layout` bleiben fuer representative Browser
+Smokes markiert. Der Default-Gate prueft die breite Matrix fake-DOM-nah und
+haelt Browser-Flakiness aus dem schnellen Primitive-Gate heraus.
+
+## Runtime API
+
+```js
+import {
+  createRmtComponentCapabilityRegistry
+} from '@ccslabs/xtend/rmt/component-capability-registry';
+import {
+  createRmtDomDescriptorRenderer
+} from '@ccslabs/xtend/rmt/dom-descriptor-renderer';
+
+const registry = createRmtComponentCapabilityRegistry({
+  manifest,
+  sourceTexts,
+  importer: async (modulePath) => import(`/components/${modulePath.replace(/^\.\//u, '')}`)
+});
+
+const descriptor = registry.buildComponentDescriptor({
+  tag: 'x-select',
+  id: 'plan-select',
+  key: 'settings:plan',
+  attributes: {
+    name: 'plan',
+    value: 'pro'
+  },
+  slots: {
+    label: { text: 'Plan' }
+  },
+  events: {
+    'select-changed': 'settings.plan.changed'
+  }
+});
+
+const renderer = createRmtDomDescriptorRenderer({ documentTarget: document });
+
+renderer.renderKeyed(root, [descriptor], {
+  componentRegistry: registry,
+  dispatchEvent(event) {
+    actions.dispatch(event.action, event.payload);
+  },
+  stateBridge: {
+    read(key) {
+      return state.read(key);
+    },
+    write(key, value) {
+      state.write(key, value);
+    }
+  }
+});
+```
+
+Wichtige Registry-Funktionen:
+
+| Funktion | Zweck |
+| --- | --- |
+| `resolveComponentCapability(tag)` | Liefert normalisierte Capabilities fuer einen Manifest-Tag. |
+| `listCapabilities(filter)` | Listet Capabilities nach Familie oder Visual Kind. |
+| `buildComponentDescriptor(input)` | Baut einen DOM Descriptor fuer XTend-Komponenten inklusive Capability-Markern. |
+| `bindComponentInstance(element, binding, options)` | Verbindet Events, Form-State und State Bridge ueber public DOM APIs. |
+| `ensureComponentLoaded(tag, options)` | Fuehrt lazy Import ueber einen expliziten Importer aus. |
+| `createMatrixReport()` | Erzeugt den Compatibility-Report fuer CI und lokale Diagnose. |
+
+## Event- und State-Bridge
+
+Form Controls liefern `value`, `checked`, `validity`, `dataset` und Datei-
+Metadaten in einem sicheren Payload-Record
+`xtend.rmt.component-event-payload.v1`. Fuer Form-Familien werden `input` und
+`change` ergaenzt, wenn keine explizite Event-Bindung gesetzt ist.
+
+Navigation, Overlays, Feedback- und Layout-Komponenten bleiben ebenfalls ueber
+public Events und Properties angebunden. Produktcode muss nicht in
+`shadowRoot` greifen, keine privaten Component-Maps lesen und keine
+komponentenspezifischen Renderer einbauen.
+
+## Renderer-Integration
+
+Der DOM Descriptor Renderer akzeptiert `componentRegistry` in
+`render(...)` und `renderKeyed(...)`. Bei `type: "component"` werden Tag,
+Attribute, Properties, Slots, Parts und Event-Bindings ueber die Registry
+normalisiert. Keyed Reuse bleibt erhalten, unkeyed Repeat-UI wird weiterhin
+diagnostiziert.
+
+Normale RMT-App-UI nutzt keine HTML-Sinks. `innerHTML`, `outerHTML`,
+`insertAdjacentHTML`, `document.write`, `createContextualFragment` und
+unsichere URL-/Inline-Event-Sinks bleiben durch den No-Manual-HTML-Gate und
+die Trusted-DOM-Boundary gesperrt.
+
+## Architekturregeln
+
+- Component Contracts bleiben die Quelle der Wahrheit.
+- RMT erweitert XTend UI ueber Metadaten und Runtime-Bridges, nicht ueber
+  Monkeypatching.
+- Lazy Import laeuft nur ueber Manifest und explizite Importer.
+- Der RMT-Kernel bleibt framework-neutral und importiert keine XTend-Typen.
+- Overlays, Surfaces und Portals brauchen Resource Ownership und Cleanup.
+- `x-player` nutzt den public Player Contract fuer Play/Pause, State Bridge,
+  Theme Tokens und Parts; Produktcode patcht kein Shadow DOM.
+- Infrastrukturmodule wie `x-theme` und `xstate` werden als Services genutzt,
+  nicht als normale Surface-Elemente.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-component-primitives --json
+npm run test:rmt-vnext-primitives:report
+node scripts/run_xtend_tests.js component-ux-browser-smokes --json
+node scripts/run_xtend_tests.js type-exports-rmt --json
+```
+
+Das schnelle Primitive-Gate prueft Registry, Matrix, Renderer-Bindung,
+Package-Exports, Type Declarations, Lazy Import, State Roundtrip und negative
+Grenzen gegen Shadow-DOM-Patches, manuelle HTML-Sinks und direkte Component-
+Imports.
+
+## Verwandte Doku
+
+- [RMT vNext Authoring Guide](./rmt-vnext-authoring.md)
+- [RMT DOM Descriptor Renderer](./rmt-dom-descriptor-renderer.md)
+- [RMT Component Template Primitives](./rmt-component-template-primitives.md)
+- [XTend Components](./components.md)
+- [Component Platform](./component-platform.md)
+- [XTend-Fabric RMT Lane Mapping](./xtend-fabric-rmt-lane-mapping.md)

package/docs/rmt-vnext-fabric-bridge-evidence.md

@@ -0,0 +1,81 @@
+# RMT vNext Fabric Bridge Evidence
+
+- Contract: `xtend.rmt.vnext.fabric-bridge-evidence.v1`
+- Workpackage: `RMT-VNEXT-PRIM-05`
+- Status: `completed`
+- Quelle: Media-Manager-Downstream-Transfer, `2026-05-19`
+
+## Ziel
+
+`RMT-VNEXT-PRIM-05` beweist, dass vNext-authorierte Primitives den Fabric-
+Runtime-Raum erreichen, ohne Fabric- oder XTend-Host-Imports in den RMT-Kernel
+zu ziehen.
+
+Das Gate ist absichtlich als eigene Scheibe neben dem Source-to-Sea-Gate
+verfuegbar. Source-to-Sea prueft den gesamten Objekt-Lifecycle bis Browser;
+dieses Gate prueft die Fabric-Bruecke selbst:
+
+```text
+vNext source
+  -> PRIM-04 kernel schedule/fiber
+  -> Fabric/RMT lane mapping
+  -> xtend.fabric.fiber.v1
+  -> xtend.fabric.telemetry-snapshot.v1
+  -> host adapter telemetry
+  -> route/component fiber instrumentation
+  -> browser-visible Fabric markers
+```
+
+## Evidence
+
+Die Evidence wird von `createRmtVNextFabricBridgeEvidence(...)` erzeugt und
+ueber `createRmtVNextSourceToSeaEvidence(...)` in den Fullstack-Report
+eingebettet.
+
+Der PRIM-05-Contract umfasst:
+
+- `xtend.fabric.rmt-lane-mapping.v1` fuer die Uebersetzung von RMT-Lanes in
+  Fabric-Schedules;
+- eine primaere `xtend.fabric.fiber.v1` aus dem PRIM-04 Kernel-Fiber;
+- eine Lane-Matrix fuer `user-blocking`, `transition`, `idle`, `background`
+  und `diagnostics`;
+- `xtend.component.lifecycle-telemetry.v1` aus dem XTend Component Host-
+  Adapter;
+- `component.mount`, `component.hydrate`, `route.navigate` und `route.render`
+  aus den produktiven Fabric-Fiber-Instrumentations;
+- einen `xtend.fabric.telemetry-snapshot.v1`, der alle erwarteten Schedule Refs
+  enthaelt;
+- Browser-Marker fuer Fabric Lane, Fabric Fiber, Fabric Schedule und Host-
+  Adapter-Telemetrie.
+
+## Gate-Regeln
+
+Das Gate schlaegt fehl, wenn:
+
+- die Fabric/RMT-Lane-Aufloesung kein Mapping liefert;
+- die primaere Fabric-Fiber nicht abgeschlossen ist;
+- Kernel-Schedule, Kernel-Fiber und Source-Pointer nicht in Fiber-Metadaten
+  erhalten bleiben;
+- eine der Matrix-Lanes fehlt oder keinen Telemetry-Schedule schreibt;
+- Host-Adapter-Telemetrie nicht im Fabric-Snapshot erscheint;
+- Route- oder Component-Fiber nicht aus den produktiven Instrumentations
+  stammen;
+- Browser-Marker fuer Lane, Fiber, Schedule oder Host-Telemetrie fehlen;
+- der RMT-Kernel Host- oder Fabric-Imports enthaelt.
+
+## Lokale Gates
+
+```bash
+node --check tools/rmt-language/vnext-source-to-sea.js
+node --check tests/rmt-language/rmt_vnext_fabric_bridge_suite.js
+node scripts/run_xtend_tests.js rmt-vnext-fabric-bridge --json
+node scripts/run_xtend_tests.js rmt-vnext-source-to-sea --json
+npm run test:rmt-vnext-primitives:report
+```
+
+## Handoff
+
+`RMT-VNEXT-PRIM-05` ist abgeschlossen, sobald dieses Gate gruen ist.
+`RMT-VNEXT-PRIM-06` fuehrt Source-to-Sea als optionale Browser-Evidence weiter:
+Browser-Execution kann lokal oder per manuellem CI-Dispatch laufen und die
+Browser-Execution-Evidence als Release-Artefakt schreiben.