@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/rmt-vnext-cross-surface-events.md

@@ -0,0 +1,59 @@
+# RMT vNext Cross Surface Events
+
+Cross-surface events connect areas of the app shell without introducing an implicit global event bus. Every direction, target and payload schema is described explicitly and secured through governance diagnostics. Boundary: no implicit global event bus.
+
+## Contract
+
+```js
+schema: "xtend.rmt.vnext-cross-surface-event-protocol.v1"
+reportSchema: "xtend.rmt.vnext-cross-surface-event-report.v1"
+governanceSchema: "xtend.rmt.vnext-event-governance-policy.v1"
+```
+
+An event must define:
+
+- `event` as a versioned name, for example `checkout.cart.updated.v1`.
+- `owner` as the team responsible for event and version maintenance.
+- `payload.schema` as stable payload ID.
+- `direction` as `outbound` or `inbound`.
+- `scope` as lane, surface or shell target binding.
+- `delivery` with TTL, correlation and idempotency when required.
+
+## Direction
+
+`emits` describes outbound events from a surface. `consumes` describes inbound events. The shell may forward these bindings, but not interpret them freely. This keeps it visible whether a user action affects several areas of the shell.
+
+## Scope
+
+Events are constrained to lanes and shell targets:
+
+```rmt
+emits checkout.cart.updated.v1 {
+  owner: "checkout-platform"
+  payload: "xtend.schemas.cartUpdated.v1"
+  direction: outbound
+  scope: lane critical -> shell.slot:sidebar.cart
+}
+```
+
+An event without clear scope is blocked or diagnosed in the E16 gate. This prevents the same implicit coupling pressure that makes micro-frontend systems hard to maintain without discipline.
+
+## Governance
+
+The governance model checks:
+
+- event owner and payload owner.
+- cross-team events.
+- delivery mode, TTL, `correlationId` and `idempotencyKey`.
+- sensitivity and review obligations.
+- degradation behavior for events from a blocked or degraded surface.
+
+## Gates
+
+```bash
+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-enterprise-release --json
+```
+
+The enterprise demo covers `checkout.cart.updated.v1` and `user.session.changed.v1` as typed, directed cross-surface events.

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

@@ -0,0 +1,62 @@
+# RMT vNext Enterprise MFE Handoff
+
+Epic 16 closes RMT vNext for enterprise MFE authoring with remote surfaces, surface discoverability, cross-surface events, security policies, versioning and graceful degradation.
+
+## 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 remain contract artifacts. A productive runtime loader is follow-up work in the host or runtime adapter path.
+- `surface.registry` makes ownership, active versions and shell bindings visible, but replaces no SurfaceManager.
+- Cross-surface events need typed payloads, clear owners and explicit direction.
+- Graceful degradation is mandatory. Systems without fallback or blocking model are not considered enterprise-ready.
+- Migration from legacy surface facts remains `report-only` by default; preview is opt-in and described through `xtend.rmt.vnext-remote-surface-migration.v1`.
+
+## Accepted Residuals
+
+- No productive remote runtime loader in the RMT kernel.
+- No real network integration in local language-layer gates.
+- No implicit global event-bus semantics.
+- No public runtime claim for hosts that do not implement the contract yet.
+
+The local closure gate is:
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-enterprise-release --json
+```

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

@@ -0,0 +1,64 @@
+# RMT vNext Fabric Bridge Evidence
+
+- Contract: `xtend.rmt.vnext.fabric-bridge-evidence.v1`
+- Workpackage: `RMT-VNEXT-PRIM-05`
+- Status: `completed`
+- Source: Media Manager downstream transfer, `2026-05-19`
+
+## Goal
+
+`RMT-VNEXT-PRIM-05` proves that vNext-authored primitives reach the Fabric runtime space without pulling Fabric or XTend host imports into the RMT kernel.
+
+The gate is intentionally available as its own slice beside the source-to-sea gate. Source-to-sea checks the full object lifecycle into the browser; this gate checks the Fabric bridge itself:
+
+```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
+
+The evidence is created by `createRmtVNextFabricBridgeEvidence(...)` and embedded into the fullstack report through `createRmtVNextSourceToSeaEvidence(...)`.
+
+The PRIM-05 contract includes:
+
+- `xtend.fabric.rmt-lane-mapping.v1` for translating RMT lanes into Fabric schedules;
+- a primary `xtend.fabric.fiber.v1` from the PRIM-04 kernel fiber;
+- a lane matrix for `user-blocking`, `transition`, `idle`, `background` and `diagnostics`;
+- `xtend.component.lifecycle-telemetry.v1` from the XTend component host adapter;
+- `component.mount`, `component.hydrate`, `route.navigate` and `route.render` from the productive Fabric fiber instrumentations;
+- an `xtend.fabric.telemetry-snapshot.v1` that contains all expected schedule refs;
+- browser markers for Fabric lane, Fabric fiber, Fabric schedule and host-adapter telemetry.
+
+## Gate Rules
+
+The gate fails when:
+
+- the Fabric/RMT lane resolution provides no mapping;
+- the primary Fabric fiber is not completed;
+- kernel schedule, kernel fiber and source pointer are not preserved in fiber metadata;
+- one of the matrix lanes is missing or writes no telemetry schedule;
+- host-adapter telemetry does not appear in the Fabric snapshot;
+- route or component fiber does not come from the productive instrumentations;
+- browser markers for lane, fiber, schedule or host telemetry are missing;
+- the RMT kernel contains host or Fabric imports.
+
+## Local 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` is complete once this gate is green. `RMT-VNEXT-PRIM-06` keeps source-to-sea as optional browser evidence: browser execution can run locally or through manual CI dispatch and write the browser execution evidence as a release artifact.

package/docs/en/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 is additive. Existing JSON-close `.rmt` and `.rmt.json` documents remain parseable and normalizable. New authoring files should use the vNext syntax and compile to `xtend.rmt.core-format.vnext.v1`.
+
+## Migration Mode
+
+The default mode is `report-only`. It creates a migration report, checks the legacy roundtrip and shows boundary warnings, but does not automatically rewrite a file.
+
+`preview` is opt-in and additionally creates a vNext authoring draft.
+
+```js
+const {
+  createMigrationReport
+} = require('./tools/rmt-language/vnext-compatibility');
+
+const report = createMigrationReport({
+  text: source,
+  filePath: 'app.rmt'
+}, {
+  migrationMode: 'preview'
+});
+```
+
+## Compatible Warnings
+
+These warnings do not block migration:
+
+- `rmt.document.extension.fallback-used`
+- `rmt.vnext.migration.opt_in_required`
+- `rmt.vnext.migration.lossy_domain`
+
+`lossy_domain` means: the legacy domain is semantically compatible, but cannot automatically be translated into source-stable vNext authoring. Examples include adapter contracts, complex templates or router metadata.
+
+## Hard Errors
+
+These cases block the affected entry:
+
+- Legacy JSON cannot be parsed.
+- Legacy JSON cannot be normalized.
+- vNext source does not compile.
+- The semantic legacy roundtrip is not stable.
+
+## Recommended Migration
+
+1. Run `rmt-vnext-compatibility` against existing fixtures.
+2. Read reports with `migrationMode: "report-only"` and triage boundary warnings.
+3. Create `preview` for individual files.
+4. Manually review the preview draft and bring it to vNext authoring conventions.
+5. Run parser, compiler, regression and release gate.
+
+```bash
+node scripts/run_xtend_tests.js rmt-vnext-compatibility rmt-vnext-regression rmt-vnext-release --json
+```
+
+## Handoff
+
+This epic delivers syntax, compiler, tooling, compatibility, regression and release handoff. Productive runtime adapters for vNext Core and a formatter/writer belong in follow-up epics.

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

@@ -0,0 +1,174 @@
+# RMT vNext Primitive Authoring Tooling
+
+- Contract: `xtend.rmt.vnext.primitive-authoring-tooling.v1`
+- Workpackage: `RMT-VNEXT-PRIM-07`
+- Status: `completed`
+- Source: Media Manager downstream transfer, `2026-05-19`
+
+## Goal
+
+`RMT-VNEXT-PRIM-07` makes the new primitive syntax visible in the developer experience. App authors should not have to search legacy JSON for state, selectors, actions, events, surfaces, portals, overlays and resources: completions, hover, document symbols and snippets lead directly through RMT vNext.
+
+## Tooling Surface
+
+The first PRIM-07 slice extends `tools/rmt-language/vnext-tooling.js`. The module now also indexes primitive domains from PRIM-04:
+
+- `states`
+- `selectors`
+- `actions`
+- `effects`
+- `portals`
+- `overlays`
+- `resources`
+
+Existing domains such as `surfaces`, `events` and `dataSources` remain available and are enriched for primitive records.
+
+## Completions
+
+New completion contexts:
+
+| Context | Purpose |
+| --- | --- |
+| `vnext-primitive-keywords` | top-level primitive keywords such as `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 and lifecycle clauses |
+| `vnext-primitive-resource-kinds` | `object-url`, `stream`, `observer`, `timer`, `lazy-import` |
+| `vnext-primitive-overlay-kinds` | `tooltip`, `toast`, `popover`, `lightbox`, `menu`, `dialog` |
+
+When a pointer is inside a primitive domain, the tooling automatically chooses the matching context.
+
+### Cursor-Near Completion
+
+The second PRIM-07 slice makes completion usable without an explicit `xtend.context`. `getRmtVNextToolingCompletions(...)` now accepts an LSP position, resolves the source-map pointer from it when possible, and evaluates the current line plus the partial word before the cursor.
+
+Covered authoring cases:
+
+- `state ... {` directly returns state clauses such as `initial`.
+- `resource ... kind ` returns resource kinds such as `lazy-import`.
+- Partial words in action blocks, for example `red`, prioritize action clauses such as `reduce`.
+
+The language server forwards `textDocument/completion.position` to the vNext tooling. This gives editors primitive completions even when they do not set XTend-specific additional parameters.
+
+## Hover
+
+Hover uses the PRIM-04 Core records and source maps. Examples:
+
+- `State: media.records`
+- `Action: media.select`
+- `Resource: lightbox.import`
+
+The hover output still contains Core pointers so editor, compiler and runtime evidence can trace the same primitive ID.
+
+## Document Symbols
+
+Document symbols now contain primitive namespaces:
+
+```text
+states
+selectors
+actions
+portals
+overlays
+resources
+surfaces
+events
+```
+
+This lets an editor navigate a granular app shell from the outline without opening legacy records.
+
+## Code Actions
+
+The third PRIM-07 slice provides safe quick fixes for primitive diagnostics from `getRmtVNextToolingCodeActions(...)` and through `textDocument/codeAction` in the language server.
+
+Supported first repairs:
+
+- `rmt.vnext.primitive.owner-missing`: adds `owner surface.<id>` to a resource declaration when a surface exists in the document.
+- `rmt.vnext.primitive.unkeyed-repeat`: adds `key instance.id` after a `repeat from selector` clause.
+- `rmt.vnext.primitive.payload-contract-missing`: adds a payload contract for event bindings or `emit` statements.
+
+The next slice extends these repairs for the most common authoring gaps:
+
+- `rmt.vnext.primitive.initial-missing`: adds a safe initial value or a small `initial {}` block.
+- `rmt.vnext.primitive.resource-kind-missing`: adds `kind object-url` as a conservative resource default.
+- `rmt.vnext.primitive.unknown-reference` for selector references: creates a source-preserving selector stub from the first available state.
+- `rmt.vnext.primitive.unknown-reference` for portal references: creates a portal stub with stable `root` and `layer surface`.
+
+The action-authoring slice also adds:
+
+- `rmt.vnext.primitive.action-reducer-missing`: adds a `reduce state.<id> = input.<name>` target before the action end.
+- `rmt.vnext.primitive.effect-source-missing`: adds `datasource <id>` to an `effect fetch`.
+- `rmt.vnext.primitive.kernel-boundary`: deliberately creates no text edit, but a command-action handoff so Kernel/Fabric imports are moved into a host adapter.
+
+The actions are intentionally source-preserving text edits. They fix the obvious authoring gap and leave further semantic problems visible instead of synthetically rewriting whole primitive blocks.
+
+### Code-Action Previews and Fix-All
+
+The next PRIM-07 slice makes the quick fixes more editor-friendly:
+
+- Every code action carries an `xtend.rmt.vnext.primitive-code-action-preview.v1` preview with affected URIs, edit count, first changed source-line excerpt and before/after lines.
+- Safe text-edit actions are additionally grouped into `source.fixAll.rmt.vnext.primitives`.
+- Fix-All remains limited to actions with `safe: true` and `edit`.
+  Manual command handoffs such as `kernel-boundary` are not applied automatically.
+- The language server forwards the preview in the `CodeAction.data.preview` field so editors can show a repair before applying the WorkspaceEdit.
+
+### Command Handoff
+
+Manual boundary cases now also get a stable editor experience:
+
+- The language server reports `executeCommandProvider.commands` with `xtend.rmt.vnext.extractKernelImport`.
+- `workspace/executeCommand` creates an `xtend.rmt.vnext.primitive-command-handoff.v1` result for this command.
+- The result remains `safe: false`, `edit: null` and `status: "manual_handoff"` because Kernel/Fabric imports must not be written automatically into RMT vNext source.
+- The handoff names the boundary `no-kernel-fabric-imports-in-vnext-source` and lists the target location `xtend-rmt-host-adapter` so editors can show a clear manual apply path.
+
+### VS Code Bridge Apply Experience
+
+The VS Code bridge now offers the first visible authoring experience for the three apply paths:
+
+- `XTendRMT: Show vNext Primitive Apply Experience` renders an `xtend.rmt.editor.vscode-primitive-authoring-experience.v1` report in the Output Channel.
+- `XTendRMT: Show vNext Primitive Code Action Preview` shows the preview excerpt of a single code action.
+- `XTendRMT: Show vNext Primitive Command Handoff` shows manual boundary handoffs without WorkspaceEdit.
+
+The bridge deliberately stays thin: it classifies actions already provided by the language server into `workspace-edit`, `fix-all` and `manual-command`, and makes these paths visible. The LSP remains the source of truth for diagnostics, preview and command handoff.
+
+### Active VS Code Document Integration
+
+The final PRIM-07 slice connects the bridge to the active `.rmt` document:
+
+- `createActiveDocumentPrimitiveAuthoringExperience(...)` reads the active document, starts the local RMT Language Server in-process and calls `textDocument/codeAction` against real LSP diagnostics.
+- `XTendRMT: Show vNext Primitive Apply Experience` can build a QuickPick selection for preview, Fix-All and manual handoffs directly from the active document when no report is passed in.
+- `applyPrimitiveAuthoringWorkspaceEdit(...)` applies only safe WorkspaceEdits. `kernel-boundary` actions remain blocked because they carry `edit: null` and must be moved into a host adapter.
+- `XTendRMT: Apply Safe vNext Primitive Fix-All` applies only `source.fixAll.rmt.vnext.primitives`. If no safe Fix-All is available, the bridge renders the current apply report instead of blindly applying individual edits.
+
+PRIM-07 is therefore no longer only an LSP/docs package: the editor bridge can select, preview and safely apply vNext primitive repairs from real source context, while boundary handoffs remain visible and manual.
+
+## Snippet
+
+New snippet:
+
+```text
+RMT vNext Primitive Shell
+```
+
+Prefix:
+
+```text
+rmt-vnext-primitive-shell
+```
+
+The snippet creates a small app shell with state, selector, action, portal, surface, visible lane and event payload contract.
+
+## Local 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);"
+```
+
+The global runner executes `rmt-vnext-tooling` and `rmt-editor-packaging` as release gates. The VS Code bridge is checked through `node scripts/run_xtend_tests.js rmt-editor-packaging --json` against active-document CodeActions, Safe Fix-All and blocked Kernel Boundary handoffs.
+
+## Next Handoff
+
+`RMT-VNEXT-PRIM-07` is complete. Further editor work can build on this bridge, for example real LanguageClient packaging or UI-specific preview panels; the vNext primitive authoring path itself is release-gated.

package/docs/en/rmt-vnext-primitive-grammar-design.md

@@ -0,0 +1,268 @@
+# RMT vNext Primitive Grammar Design
+
+- Contract: `xtend.rmt.vnext-primitive-grammar-design.v1`
+- Workpackage: `RMT-VNEXT-PRIM-01`
+- Status: `completed`
+- Parent backlog: [RMT vNext Primitive Compiler Backlog](./rmt-vnext-primitives-compiler-backlog.md)
+- Design fixture: `tests/rmt-language/fixtures/vnext-primitives-grammar-design.rmt`
+
+## Goal
+
+This slice defines the vNext syntax used to author App Platform primitives directly in RMT. It is deliberately a grammar-design contract. Parser/AST implementation is complete in `RMT-VNEXT-PRIM-02`; the first semantic-graph layer started in `RMT-VNEXT-PRIM-03`. Compiler lowering follows in `RMT-VNEXT-PRIM-04`.
+
+The syntax must move app authors out of legacy/JSON authoring. A normal app-shell developer should be able to declare state, selectors, actions, events, data sources, surfaces, overlays, portals and resources in a readable RMT vNext file.
+
+## Design Principles
+
+- **vNext first:** The human-friendly DSL is the primary authoring surface. JSON remains compiler output or migration input.
+- **Kernel-neutral:** Syntax can reference XTend components, but the RMT kernel imports no XTend, Fabric or browser modules.
+- **App graph before runtime:** References, ownership, payload contracts and trust boundaries must be verifiable from the source graph.
+- **Source-map capable:** Every primitive declaration needs a stable source range and a primitive ID.
+- **Composable:** App shell, UI templates, state, events and resources may be declared separately, but must connect into one app graph.
+- **Legacy in the background:** Classic Core/scaffold artifacts may still be targets, but developers should not have to edit them.
+
+## Top-Level Grammar
+
+A vNext file can still use `import`, `template`, `surface` and `remote`. Primitive declarations are new. They are preferred inside a `template` block, but may also be authored at top level for reusable libraries.
+
+```rmt
+template media.manager {
+  state media.records type MediaRecord[] initial []
+
+  selector media.filtered from state media.records {
+    where record.kind == state.media.filters.kind || state.media.filters.kind == "all"
+    sort by record.name asc
+  }
+
+  datasource media.index from endpoint "/api/media?pageSize=200" {
+    method GET
+    contract MediaIndex
+    result records
+  }
+
+  action media.select {
+    input mediaId string
+    reduce state.media.selection.activeId = input.mediaId
+    emit media.selected with mediaId input.mediaId
+  }
+
+  portal surface.root root "#media-manager-root" layer surface
+  overlay feedback.toast kind toast portal surface.root
+  resource player.stream kind stream owner surface.player source state.media.selection.activeId
+
+  surface media.explorer kind window component x-surface-window {
+    source selector media.filtered
+    key record.id
+    portal surface.root
+
+    lane visible weight 80 {
+      hydrate explorer-list from selector media.filtered
+    }
+
+    on click "[data-media-id]" -> action media.select {
+      payload mediaId from target.dataset.mediaId
+    }
+  }
+}
+```
+
+## Primitive Forms
+
+### State
+
+```rmt
+state media.filters type object preserve {
+  initial {
+    query ""
+    kind "all"
+    collection "all"
+  }
+}
+```
+
+Lowering target:
+
+- `core.state[]`
+- source-map entry with `primitiveType: "state"`
+- optional XState bridge hint for host adapters
+
+### Selector
+
+```rmt
+selector media.filtered from state media.records {
+  where record.kind == state.media.filters.kind || state.media.filters.kind == "all"
+  where contains(record.name, state.media.filters.query)
+  sort by record.name asc
+  output MediaRecord[]
+}
+```
+
+Restriction for PRIM-01: functions such as `contains()` are allowed as declarative selector operators, but not as arbitrary JS calls. PRIM-02 must model them as dedicated AST nodes.
+
+Lowering target:
+
+- `core.selectors[]`
+- references to `core.state[]`
+- diagnostic for unknown state or record paths
+
+### DataSource
+
+```rmt
+datasource media.index from endpoint "/api/media?pageSize=200" {
+  method GET
+  contract MediaIndex
+  result records
+  fallback fixture media.fixture
+}
+```
+
+Lowering target:
+
+- `core.dataSources[]`
+- App Platform report domain `dataSources`
+- optional SSR/fixture fallback
+
+### Action and Effect
+
+```rmt
+action media.reindex {
+  status state.actionStatus.reindex
+  effect fetch datasource media.reindex
+  on success -> reduce state.media.records = result.records
+  on success -> emit media.index.loaded with count result.records.length
+  on error -> overlay feedback.toast message error.message tone "danger"
+}
+```
+
+Lowering target:
+
+- `core.actions[]`
+- `core.effects[]` or action-scoped `effects`
+- event/feedback result routing
+- resource ownership for async handles
+
+### Event Binding
+
+```rmt
+on click "[data-command='scan']" -> action media.reindex {
+  preventDefault true
+  payload source from target.dataset.command
+}
+
+on xplayer-play target player.surface -> action media.playback.started {
+  payload mediaId from detail.mediaId
+  payload surfaceId from surface.id
+}
+```
+
+Lowering target:
+
+- `core.events[]`
+- payload contract
+- DOM/custom event routing metadata
+- source pointer for every payload mapping
+
+### Surface
+
+```rmt
+surface media.player kind window component x-surface-window {
+  repeat from selector player.instances
+  key instance.surfaceId
+  portal surface.root
+  bounds x 920 y 96 width 760 height 500
+  preserve on minimize
+  destroy releases resource player.stream
+
+  lane visible weight 90 {
+    hydrate player-view from selector media.activeRecord
+  }
+}
+```
+
+Lowering target:
+
+- `core.surfaces[]`
+- `core.lanes[]`
+- `core.operations[]`
+- Surface Graph Runtime records
+- keyed repeater diagnostics
+
+### Portal and Overlay
+
+```rmt
+portal overlay.root root "body" layer overlay z 1000 {
+  focus policy restore
+  pointer policy passthrough
+  scroll policy lock-when-modal
+}
+
+overlay media.lightbox kind lightbox portal overlay.root {
+  escape close topmost
+  focus trap
+  resource lightbox.import
+}
+```
+
+Lowering target:
+
+- `core.portals[]`
+- `core.overlays[]`
+- portal reference diagnostics
+- overlay stack policy
+
+### Resource
+
+```rmt
+resource lightbox.import kind lazy-import owner overlay.media.lightbox {
+  import "@ccslabs/xtend/components/xlightbox"
+}
+
+resource preview.objectUrl kind object-url owner surface.media.player {
+  source selector media.activeRecord
+  dispose on surface.destroy
+}
+```
+
+Lowering target:
+
+- `core.resources[]`
+- owner-scoped lifecycle records
+- teardown diagnostics for ownerless resources
+
+## AST Node Names
+
+PRIM-02 should produce at least these node types:
+
+| Syntax | AST Node |
+|--------|----------|
+| `state` | `RmtStateDeclaration` |
+| `selector` | `RmtSelectorDeclaration` |
+| `datasource` | `RmtDataSourceDeclaration` |
+| `action` | `RmtActionDeclaration` |
+| `effect` | `RmtEffectStatement` |
+| `on ... -> action ...` | `RmtEventBinding` with payload block |
+| `surface ... kind ... component ...` | `RmtSurfaceDeclaration` with primitive metadata |
+| `portal` | `RmtPortalDeclaration` |
+| `overlay` | `RmtOverlayDeclaration` |
+| `resource` | `RmtResourceDeclaration` |
+| `template` primitive block | `RmtTemplateDeclaration.body[]` |
+
+## Minimum Diagnostic Scope
+
+The grammar slice defines these error classes for PRIM-02/03:
+
+| Code | Meaning |
+|------|---------|
+| `rmt.vnext.primitive.unknown-reference` | Primitive references an unknown state, selector, action, portal, resource or surface. |
+| `rmt.vnext.primitive.owner-missing` | Resource or overlay has no stable owner. |
+| `rmt.vnext.primitive.unkeyed-repeat` | Surface or template repeats records without `key`. |
+| `rmt.vnext.primitive.payload-contract-missing` | Event binds an action without payload contract or mapping. |
+| `rmt.vnext.primitive.unsafe-html` | Template uses HTML without Trusted DOM boundary. |
+| `rmt.vnext.primitive.kernel-boundary` | Primitive requires a kernel import from XTend, Fabric or browser runtime. |
+
+## Acceptance for PRIM-01
+
+- This document defines a coherent vNext syntax for all P0 primitive families.
+- The fixture `tests/rmt-language/fixtures/vnext-primitives-grammar-design.rmt` shows the same syntax scope in a compact app shell.
+- The backlog marks `RMT-VNEXT-PRIM-01` as `in_progress`.
+- PRIM-02 can start directly with parser/AST work without reopening the syntax question.