@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/de/rmt-vnext-enterprise-mfe-handoff.md

@@ -0,0 +1,70 @@
+# RMT vNext Enterprise MFE Handoff
+
+Epic 16 schliesst RMT vNext fuer Enterprise-MFE-Authoring mit Remote Surfaces,
+Surface Discoverability, Cross Surface Events, Security Policies, Versionierung
+und Graceful Degradation ab.
+
+## Contract
+
+```js
+schema: "xtend.rmt.vnext-enterprise-release-handoff.v1"
+reportSchema: "xtend.rmt.vnext-enterprise-release-handoff-report.v1"
+gateMatrixSchema: "xtend.rmt.vnext-enterprise-release-gate-matrix.v1"
+targetReadiness: "rmt-vnext-enterprise-mfe-ready"
+```
+
+## Release Assets
+
+- Authoring Guide: `docs/rmt-vnext-remote-surfaces.md`
+- Registry Reference: `docs/rmt-vnext-surface-registry-enterprise.md`
+- Event Protocol Reference: `docs/rmt-vnext-cross-surface-events.md`
+- Operational Handoff: `docs/rmt-vnext-enterprise-mfe-handoff.md`
+- Demo Source: `xtendrmt/rmt-vnext-enterprise-mfe-demo.rmt`
+- Core Output: `xtendrmt/rmt-vnext-enterprise-mfe-demo.core.json`
+- Browser Smoke: `tests/browser/fixtures/rmt-vnext-enterprise-mfe-smoke.html`
+- Fixture Matrix: `tests/rmt-language/fixtures/vnext-enterprise-mfe-fixture-matrix.json`
+
+## Release Gate Matrix
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-remote-manifest --json
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-registry --json
+node scripts/run_xtend_tests.js rmt-vnext-degradation --json
+node scripts/run_xtend_tests.js rmt-vnext-remote-security --json
+node scripts/run_xtend_tests.js rmt-vnext-cross-surface-events --json
+node scripts/run_xtend_tests.js rmt-vnext-event-governance --json
+node scripts/run_xtend_tests.js rmt-vnext-remote-compiler --json
+node scripts/run_xtend_tests.js rmt-vnext-remote-tooling --json
+node scripts/run_xtend_tests.js rmt-vnext-remote-compatibility --json
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-fixtures --json
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-release --json
+node scripts/run_xtend_tests.js references --json
+node scripts/run_xtend_tests.js browser --json
+```
+
+## Operational Notes
+
+- Remote Surfaces bleiben Contract-Artefakte. Ein produktiver Runtime Loader ist
+  Folgearbeit im Host- oder Runtime-Adapter-Pfad.
+- `surface.registry` macht Ownership, aktive Versionen und Shell Bindings
+  sichtbar, ersetzt aber keinen SurfaceManager.
+- Cross Surface Events benoetigen typisierte Payloads, klare Owner und explizite
+  Richtung.
+- Graceful Degradation ist verpflichtend. Systeme ohne Fallback- oder
+  Blockierungsmodell gelten nicht als Enterprise-ready.
+- Migration aus Legacy-Surface-Fakten bleibt `report-only` per Default; Preview
+  ist opt-in und wird ueber `xtend.rmt.vnext-remote-surface-migration.v1`
+  beschrieben.
+
+## Accepted Residuals
+
+- Kein produktiver Remote Runtime Loader im RMT-Kernel.
+- Keine echte Netzwerk-Integration in lokalen Language-Layer-Gates.
+- Keine implizite globale Event-Bus-Semantik.
+- Kein Public-Runtime-Claim fuer Hosts, die den Contract noch nicht umsetzen.
+
+Der lokale Abschluss-Gate ist:
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-release --json
+```

package/docs/de/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.

package/docs/de/rmt-vnext-migration-notes.md

@@ -0,0 +1,62 @@
+# RMT vNext Migration Notes
+
+- Contract: `xtend.rmt.vnext-release-handoff.v1`
+- Compatibility Contract: `xtend.rmt.vnext-compatibility-matrix.v1`
+- Migration Report: `xtend.rmt.vnext-migration-report.v1`
+- Gate: `node scripts/run_xtend_tests.js rmt-vnext-compatibility --json`
+
+RMT vNext ist additiv. Bestehende JSON-nahe `.rmt` und `.rmt.json` Dokumente bleiben parse- und normalisierbar. Neue Authoring-Dateien sollten die vNext-Syntax verwenden und nach `xtend.rmt.core-format.vnext.v1` kompilieren.
+
+## Migrationsmodus
+
+Der Standardmodus ist `report-only`. Er erzeugt einen Migrationsreport, prueft den Legacy-Roundtrip und zeigt Boundary-Warnungen, schreibt aber keine Datei automatisch um.
+
+`preview` ist opt-in und erzeugt zusaetzlich einen vNext Authoring-Draft.
+
+```js
+const {
+  createMigrationReport
+} = require('./tools/rmt-language/vnext-compatibility');
+
+const report = createMigrationReport({
+  text: source,
+  filePath: 'app.rmt'
+}, {
+  migrationMode: 'preview'
+});
+```
+
+## Kompatible Warnungen
+
+Diese Warnungen blockieren Migration nicht:
+
+- `rmt.document.extension.fallback-used`
+- `rmt.vnext.migration.opt_in_required`
+- `rmt.vnext.migration.lossy_domain`
+
+`lossy_domain` bedeutet: Die Legacy-Domaene ist fachlich kompatibel, aber nicht automatisch source-stabil in vNext Authoring uebersetzbar. Beispiele sind Adapter-Contracts, komplexe Templates oder Router-Metadaten.
+
+## Harte Fehler
+
+Diese Faelle blockieren den betroffenen Eintrag:
+
+- Legacy JSON kann nicht geparst werden.
+- Legacy JSON kann nicht normalisiert werden.
+- vNext Source kompiliert nicht.
+- Der semantische Legacy-Roundtrip ist nicht stabil.
+
+## Empfohlene Migration
+
+1. `rmt-vnext-compatibility` gegen bestehende Fixtures ausfuehren.
+2. Reports mit `migrationMode: "report-only"` lesen und Boundary-Warnungen triagieren.
+3. Fuer einzelne Dateien `preview` erzeugen.
+4. Den Preview-Draft manuell pruefen und auf vNext-Authoring-Konventionen bringen.
+5. Parser, Compiler, Regression und Release-Gate ausfuehren.
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-compatibility rmt-vnext-regression rmt-vnext-release --json
+```
+
+## Handoff
+
+Dieses Epic liefert Syntax, Compiler, Tooling, Compatibility, Regression und Release-Handoff. Produktive Runtime-Adapter fuer vNext Core und ein Formatter/Writer gehoeren in Folge-Epics.

package/docs/de/rmt-vnext-primitive-authoring-tooling.md

@@ -0,0 +1,247 @@
+# RMT vNext Primitive Authoring Tooling
+
+- Contract: `xtend.rmt.vnext.primitive-authoring-tooling.v1`
+- Workpackage: `RMT-VNEXT-PRIM-07`
+- Status: `completed`
+- Quelle: Media-Manager-Downstream-Transfer, `2026-05-19`
+
+## Ziel
+
+`RMT-VNEXT-PRIM-07` macht die neue Primitive-Syntax in der Developer
+Experience sichtbar. App-Autoren sollen State, Selectors, Actions, Events,
+Surfaces, Portals, Overlays und Resources nicht in Legacy-JSON suchen muessen:
+Completions, Hover, Document Symbols und Snippets fuehren direkt durch RMT
+vNext.
+
+## Tooling Surface
+
+Die erste PRIM-07-Scheibe erweitert `tools/rmt-language/vnext-tooling.js`.
+Das Modul indexiert nun auch Primitive-Domains aus PRIM-04:
+
+- `states`
+- `selectors`
+- `actions`
+- `effects`
+- `portals`
+- `overlays`
+- `resources`
+
+Bestehende Domains wie `surfaces`, `events` und `dataSources` bleiben erhalten
+und werden fuer Primitive-Records angereichert.
+
+## Completions
+
+Neue Completion-Kontexte:
+
+| Context | Zweck |
+| --- | --- |
+| `vnext-primitive-keywords` | top-level Primitive-Keywords wie `state`, `selector`, `action`, `surface`, `resource` |
+| `vnext-primitive-state-clauses` | `type`, `preserve`, `initial` |
+| `vnext-primitive-selector-clauses` | `from state`, `where`, `find`, `sort by`, `output` |
+| `vnext-primitive-action-clauses` | `input`, `reduce`, `effect fetch datasource`, `on success`, `on error`, `emit` |
+| `vnext-primitive-surface-clauses` | `source selector`, `repeat from selector`, `key`, `portal`, `bounds`, `lane visible`, Event- und Lifecycle-Klauseln |
+| `vnext-primitive-resource-kinds` | `object-url`, `stream`, `observer`, `timer`, `lazy-import` |
+| `vnext-primitive-overlay-kinds` | `tooltip`, `toast`, `popover`, `lightbox`, `menu`, `dialog` |
+
+Wenn ein Pointer in einer Primitive-Domain liegt, waehlt das Tooling den
+passenden Kontext automatisch.
+
+### Cursor-nahe Completion
+
+Die zweite PRIM-07-Scheibe macht Completion ohne expliziten
+`xtend.context` nutzbar. `getRmtVNextToolingCompletions(...)` akzeptiert nun
+eine LSP-Position, loest daraus wenn moeglich den Source-Map-Pointer auf und
+wertet die aktuelle Zeile sowie das Teilwort vor dem Cursor aus.
+
+Abgedeckte Authoring-Faelle:
+
+- `state ... {` liefert direkt State-Klauseln wie `initial`.
+- `resource ... kind ` liefert Resource-Kinds wie `lazy-import`.
+- Teilwoerter in Action-Bloecken, z. B. `red`, priorisieren Action-Klauseln
+  wie `reduce`.
+
+Der Language Server reicht `textDocument/completion.position` an das vNext-
+Tooling weiter. Damit bekommen Editoren Primitive-Completions auch dann, wenn
+sie keine XTend-spezifischen Zusatzparameter setzen.
+
+## Hover
+
+Hover nutzt die PRIM-04-Core-Records und Source Maps. Beispiele:
+
+- `State: media.records`
+- `Action: media.select`
+- `Resource: lightbox.import`
+
+Die Hover-Ausgabe enthaelt weiterhin Core Pointer, damit Editor, Compiler und
+Runtime-Evidence dieselbe Primitive-ID nachvollziehen koennen.
+
+## Document Symbols
+
+Document Symbols enthalten nun Primitive-Namespaces:
+
+```text
+states
+selectors
+actions
+portals
+overlays
+resources
+surfaces
+events
+```
+
+Damit kann ein Editor eine granulare App Shell aus der Outline heraus
+navigieren, ohne Legacy-Records zu oeffnen.
+
+## Code Actions
+
+Die dritte PRIM-07-Scheibe liefert sichere Quick-Fixes fuer Primitive-
+Diagnosen aus `getRmtVNextToolingCodeActions(...)` und ueber
+`textDocument/codeAction` im Language Server.
+
+Unterstuetzte erste Reparaturen:
+
+- `rmt.vnext.primitive.owner-missing`: ergaenzt `owner surface.<id>` an einer
+  Resource-Deklaration, wenn eine Surface im Dokument vorhanden ist.
+- `rmt.vnext.primitive.unkeyed-repeat`: ergaenzt `key instance.id` nach einer
+  `repeat from selector`-Klausel.
+- `rmt.vnext.primitive.payload-contract-missing`: ergaenzt einen
+  Payload-Contract fuer Event-Bindings oder `emit`-Statements.
+
+Die naechste Scheibe erweitert diese Reparaturen um die haeufigsten
+Authoring-Luecken:
+
+- `rmt.vnext.primitive.initial-missing`: ergaenzt einen sicheren initial-Wert
+  oder einen kleinen `initial {}`-Block.
+- `rmt.vnext.primitive.resource-kind-missing`: ergaenzt `kind object-url` als
+  konservativen Resource-Default.
+- `rmt.vnext.primitive.unknown-reference` fuer Selector-Referenzen: erzeugt
+  einen source-erhaltenden Selector-Stub aus dem ersten vorhandenen State.
+- `rmt.vnext.primitive.unknown-reference` fuer Portal-Referenzen: erzeugt einen
+  Portal-Stub mit stabilem `root` und `layer surface`.
+
+Die Action-Authoring-Scheibe ergaenzt ausserdem:
+
+- `rmt.vnext.primitive.action-reducer-missing`: ergaenzt ein
+  `reduce state.<id> = input.<name>`-Ziel vor dem Action-Ende.
+- `rmt.vnext.primitive.effect-source-missing`: ergaenzt
+  `datasource <id>` an einem `effect fetch`.
+- `rmt.vnext.primitive.kernel-boundary`: erzeugt bewusst keinen Textedit,
+  sondern ein Command-Action-Handoff, damit Kernel-/Fabric-Imports in einen
+  Host-Adapter ausgelagert werden.
+
+Die Actions sind absichtlich source-erhaltende Textedits. Sie reparieren die
+naheliegende Authoring-Luecke und lassen weitergehende semantische Probleme
+sichtbar, statt ganze Primitive-Bloecke synthetisch umzuschreiben.
+
+### Code-Action-Previews und Fix-All
+
+Die naechste PRIM-07-Scheibe macht die Quick-Fixes editorfreundlicher:
+
+- Jede Code Action traegt eine `xtend.rmt.vnext.primitive-code-action-preview.v1`
+  Preview mit betroffenen URIs, Edit-Anzahl, erstem veraenderten Source-Line-
+  Ausschnitt und Vorher-/Nachher-Zeilen.
+- Sichere Textedit-Actions werden zusaetzlich in
+  `source.fixAll.rmt.vnext.primitives` zusammengefasst.
+- Das Fix-All bleibt auf Actions mit `safe: true` und `edit` begrenzt.
+  Manuelle Command-Handoffs wie `kernel-boundary` werden nicht automatisch
+  angewendet.
+- Der Language Server gibt die Preview im `CodeAction.data.preview`-Feld
+  weiter, damit Editoren eine Reparatur anzeigen koennen, bevor sie den
+  WorkspaceEdit anwenden.
+
+### Command-Handoff
+
+Manuelle Boundary-Faelle bekommen jetzt ebenfalls eine stabile Editor-
+Erfahrung:
+
+- Der Language Server meldet `executeCommandProvider.commands` mit
+  `xtend.rmt.vnext.extractKernelImport`.
+- `workspace/executeCommand` erzeugt fuer diesen Command ein
+  `xtend.rmt.vnext.primitive-command-handoff.v1` Ergebnis.
+- Das Ergebnis bleibt `safe: false`, `edit: null` und `status:
+  "manual_handoff"`, weil Kernel-/Fabric-Imports nicht automatisch in RMT
+  vNext-Source geschrieben werden duerfen.
+- Der Handoff benennt die Boundary
+  `no-kernel-fabric-imports-in-vnext-source` und fuehrt den Zielort
+  `xtend-rmt-host-adapter`, damit Editoren einen klaren manuellen Apply-Pfad
+  anzeigen koennen.
+
+### VS Code Bridge Apply Experience
+
+Die VS-Code-Bridge bietet nun eine erste sichtbare Authoring-Erfahrung fuer
+die drei Apply-Pfade:
+
+- `XTendRMT: Show vNext Primitive Apply Experience` rendert einen
+  `xtend.rmt.editor.vscode-primitive-authoring-experience.v1` Report im
+  Output Channel.
+- `XTendRMT: Show vNext Primitive Code Action Preview` zeigt den Preview-
+  Ausschnitt einer einzelnen Code Action.
+- `XTendRMT: Show vNext Primitive Command Handoff` zeigt manuelle Boundary-
+  Handoffs ohne WorkspaceEdit.
+
+Die Bridge bleibt bewusst duenn: sie klassifiziert bereits vom Language Server
+gelieferte Actions in `workspace-edit`, `fix-all` und `manual-command` und
+macht diese Pfade sichtbar. Der LSP bleibt die Source of Truth fuer Diagnose,
+Preview und Command-Handoff.
+
+### Aktive VS-Code-Dokument-Integration
+
+Die abschliessende PRIM-07-Scheibe verbindet die Bridge mit dem aktiven
+`.rmt`-Dokument:
+
+- `createActiveDocumentPrimitiveAuthoringExperience(...)` liest das aktive
+  Dokument, startet den lokalen RMT Language Server in-process und ruft
+  `textDocument/codeAction` gegen echte LSP-Diagnosen ab.
+- `XTendRMT: Show vNext Primitive Apply Experience` kann ohne uebergebenen
+  Report direkt aus dem aktiven Dokument eine QuickPick-Auswahl fuer Preview,
+  Fix-All und manuelle Handoffs aufbauen.
+- `applyPrimitiveAuthoringWorkspaceEdit(...)` wendet nur sichere
+  WorkspaceEdits an. `kernel-boundary`-Actions bleiben blockiert, weil sie
+  `edit: null` tragen und in einen Host-Adapter ueberfuehrt werden muessen.
+- `XTendRMT: Apply Safe vNext Primitive Fix-All` wendet ausschliesslich
+  `source.fixAll.rmt.vnext.primitives` an. Wenn kein sicherer Fix-All
+  verfuegbar ist, rendert die Bridge den aktuellen Apply-Report statt blind
+  einzelne Edits auszufuehren.
+
+Damit ist PRIM-07 nicht mehr nur ein LSP-/Dokumentationspaket: Die
+Editor-Bruecke kann vNext-Primitive-Reparaturen aus echtem Source-Kontext
+auswaehlen, previewen und sicher anwenden, waehrend Boundary-Handoffs sichtbar
+und manuell bleiben.
+
+## Snippet
+
+Neues Snippet:
+
+```text
+RMT vNext Primitive Shell
+```
+
+Prefix:
+
+```text
+rmt-vnext-primitive-shell
+```
+
+Das Snippet erzeugt eine kleine App Shell mit State, Selector, Action, Portal,
+Surface, sichtbarer Lane und Event-Payload-Contract.
+
+## Lokale Gates
+
+```bash
+node --check tools/rmt-language/vnext-tooling.js
+node --check tests/rmt-language/rmt_vnext_tooling_suite.js
+node -e "const suite=require('./tests/rmt-language/rmt_vnext_tooling_suite'); const result=suite.runRmtVNextToolingSuite({rootDir:process.cwd()}); process.exit(result.ok ? 0 : 1);"
+```
+
+Der globale Runner fuehrt `rmt-vnext-tooling` und `rmt-editor-packaging` als
+Release-Gates aus. Die VS-Code-Bridge wird ueber
+`node scripts/run_xtend_tests.js rmt-editor-packaging --json` gegen aktive
+Dokument-CodeActions, Safe-Fix-All und blockierte Kernel-Boundary-Handoffs
+geprueft.
+
+## Naechster Handoff
+
+`RMT-VNEXT-PRIM-07` ist abgeschlossen. Weitere Editor-Arbeit kann auf dieser
+Bridge aufsetzen, etwa echte LanguageClient-Verpackung oder UI-spezifische
+Preview-Panels; der vNext-Primitive-Authoring-Pfad selbst ist release-gated.