@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/typescript-components.md

@@ -0,0 +1,63 @@
+# TypeScript Components
+
+XTend introduces new components TypeScript-first. Runtime artifacts remain local ES modules under `components/`, while the source of truth lives under `src/components/<tag>/`.
+
+Contract: `xtend.scaffold.typescript-component-blueprint.v1`
+
+Since `WP-E10-16`, this guide is part of the Epic 10 release handoff `xtend.epic10.release-handoff.v1`. New components must prove not only TypeScript source, but also RMT metadata, Fabric boundary, a11y, performance, fixture, docs and local gates.
+
+## Source Layout
+
+| File | Purpose |
+|------|---------|
+| `<tag>.ts` | custom element source with static RMT, Fabric, a11y and performance metadata |
+| `<tag>.contract.ts` | Component Contract v2 |
+| `<tag>.rmt.ts` | RMT component metadata for `xtend.component` |
+| `<tag>.a11y.ts` | a11y profile |
+| `<tag>.performance.ts` | performance profile |
+| `<tag>.fixture.ts` | typed fixture data |
+
+## Builder
+
+The builder renders the new artifact group in dry run:
+
+```bash
+node xtend-builder/scaffold.js component-files --tag x-example --profile display --feature state --json
+```
+
+The local gate is:
+
+```bash
+node scripts/run_xtend_tests.js builder-typescript-blueprint --json
+```
+
+## Required Gates as of WP-E10-16
+
+```bash
+node scripts/run_xtend_tests.js component-contract-v2 --json
+node scripts/run_xtend_tests.js epic10-platform-gates --json
+node scripts/run_xtend_tests.js epic10-release-handoff --json
+```
+
+New components additionally run through their component-level suite, catalog coverage, a11y, performance and visual regression gates.
+
+As of `WP-TypeExports-09`, the productive TypeExports handoff is also part of the release view:
+
+```bash
+npm run test:type-exports:release
+```
+
+New TypeScript-first components must therefore deliver not only runtime and component-contract artifacts, but also cover their public package surface through `components/*.d.ts`, an explicit package `types` condition or a documented `types-not-required` boundary.
+
+## RMT and Fabric
+
+Every new component needs an `xtend.component` RMT record and a Fabric boundary. The canonical runtime boundary for Fabric context is `adapter-injection-via-xtend-component-resolveFabricContext`; `window.XTendFabric` is a host convenience surface and not the component contract.
+
+## Boundaries
+
+- no CDN imports
+- no new runtime dependencies for core components
+- no productive TypeScript compiler in the blueprint package
+- no automatic file output without review
+- RMT kernel boundary: `no-rmt-kernel-import-of-xtend-types`
+- TypeExports boundary: `declarations-follow-js-runtime-surface`

package/docs/en/visual-browser-regression.md

@@ -0,0 +1,83 @@
+# Visual Browser Regression
+
+- Contract: `xtend.docs.visual-browser-regression.v1`
+- Plan contract: `xtend.catalog.component-regression-priority-plan.v1`
+- Gate contract: `xtend.catalog.component-regression-priority-gate.v1`
+- Snapshot contract: `xtend.epic12.visual-snapshot-automation-contract.v1`
+- Workpackage: `ER-WP-35`
+
+This page describes the current XTend plan for visual and browser-close regression. ER-WP-35 does not introduce a screenshot runner yet. Instead, XTend creates a stable priority plan that defines per manifest component which browser smokes, viewports, theme variants, visual states and performance profiles must be automated first.
+
+## Check Locally
+
+```bash
+node scripts/run_xtend_tests.js regression-priority
+node scripts/run_xtend_tests.js regression-priority --json
+npm run test:regression-priority
+```
+
+The gate is part of the local test runner and uses the Component Catalog Coverage Matrix as its source. It remains CDN-free and needs no external browser automation.
+
+## Minimum Coverage
+
+Every component in the plan receives:
+
+- viewports: `desktop-1280`, `mobile-390`
+- theme/preference variants: `light`, `dark`, `forced-colors`, `reduced-motion`
+- performance profile: `xtend.performance.component-profile.v1`
+- handoff gates: `browser`, `performance-regression`, `catalog-coverage`, `references`
+
+P0 components such as `x-router`, `x-link`, `x-modal`, `x-input`, `x-select`, `x-checkbox`, `x-radio`, `x-textarea`, `x-tooltip`, `x-popover`, `x-drawer`, `x-form`, `x-calendar`, `x-writer`, `x-dialog` and `x-lightbox` are classified as `p0-browser-critical`. P1 components such as `x-status` and `x-progress` form the visual and performance baseline. P2 components remain visible as long tail.
+
+## Profile Rules
+
+| Profile | Browser smokes | Visual states |
+|---------|----------------|---------------|
+| `routing` | route changes, keyboard navigation, history state, RMT route adapter | initial route, active route, RMT scheduled route |
+| `form` | input sync, validation feedback, keyboard entry, form submit | default, focus, invalid, disabled |
+| `overlay` | focus trap, Escape close, scroll lock, focus restore | closed, open, focus trapped, reduced motion open |
+| `feedback` | live region, dismiss timer, reduced motion | info, warning, error, dismissed |
+| `interactive` | keyboard activation, focus visible, mobile tap | default, hover, focus visible, active, disabled |
+| `media` | media controls, poster load, fullscreen toggle | poster, playing, controls focus |
+| `theme` | theme switch, token contrast, forced colors | light theme, dark theme, forced colors |
+| `display` | layout stability, responsive overflow | default layout, narrow layout |
+| `iconography` | layout stability, theme token color | default layout, high-contrast currentColor |
+| `utility` | utility integration probe | helper ready |
+
+## Boundary Closure
+
+The plan keeps the earlier boundary gaps traceable, but no longer treats them as open RC1 residuals:
+
+- 0 manifest entries still need suite, fixture or type follow-up.
+- `xstate` is closed as a runtime boundary since `WP-E13-05`.
+- `x-utils` is closed as a utility boundary since `WP-E13-05`.
+- The 42 visible runtime/UI components keep explicit performance profiles; `xstate` and `x-utils` are not artificially reinterpreted as visual profile carriers.
+
+This makes it clear that `ER-WP-35` prioritizes, while handing the actual screenshot/pixel regression to CI and release readiness.
+
+## Snapshot Automation Contract
+
+Since `WP-E12-10`, the next step is defined through `xtend.epic12.visual-snapshot-automation-contract.v1`:
+
+```bash
+node scripts/run_xtend_tests.js visual-snapshot-automation --json
+npm run test:visual-snapshot-automation
+node scripts/run_xtend_tests.js visual-snapshots --json
+npm run test:visual-snapshots
+node scripts/run_xtend_tests.js design-tokens --json
+npm run test:design-tokens
+```
+
+The snapshot contract takes over the 360 combinations from the Component Shell Theme Matrix and describes `shell-structure`, `visual-state`, `theme-token-state`, `motion-density-state`, `viewport-layout`, `focus-a11y-state` and `rmt-shell-descriptor` as snapshot scopes. The diff strategy is `dom-first-pixel-ready`: DOM structure and CSS tokens are handled with tolerance `0`. Since `WP-E12-11`, `xtend.epic12.visual-snapshot-runner.v1` compares the local fixture against a textual JSON DOM baseline. Pixel diff is prepared as `optional-local-pixel-diff` and remains outside the Node contract gate. Since `WP-E12-12`, these CSS tokens are productized as `xtend.design-tokens.product-contract.v1` and checked through the same `--xtend-*` names in `x-theme`, Theme Matrix and Snapshot Baseline.
+
+## Handoff
+
+- `WP-E12-10`: Visual Snapshot Automation Contract is complete.
+- `WP-E12-11`: local snapshot fixture and DOM-first runner are complete.
+- `WP-E12-12`: Enterprise Design System Token Productization is complete.
+- `ER-WP-36`: productize CI workflow for default gates and regression priority gate.
+- `ER-WP-38`: extend release checklist with browser/visual regression, artifacts and SemVer risks.
+- `ER-WP-39`: Enterprise Adoption Guide with QA recommendations and baseline strategy is complete.
+- `ER-WP-40`: Docs app with RMT Parsedown Scheduling Pilot is complete.
+
+The machine-readable implementation is in `catalog/component-regression-priority.js`. The architecture decision is in `development/XTend-Visuelle-und-Browsernahe-Regression-Prioritaetsplan.md`.

package/docs/en/visual-owner-artifacts.md

@@ -0,0 +1,46 @@
+# Visual Owner Artifacts
+
+- Contract: `xtend.epic13.visual-owner-artifact.v1`
+- Manifest contract: `xtend.epic13.visual-owner-artifact-manifest.v1`
+- Report: `xtend.epic13.visual-owner-artifact-report.v1`
+- Workpackage: `WP-E13-08`
+- Local gate: `node scripts/run_xtend_tests.js epic13-visual-owner-artifact --json`
+- Package script: `npm run test:epic13-visual-owner-artifact`
+- Manifest: `tests/browser/visual-baselines/rc1-visual-owner-artifact.manifest.json`
+- Publish boundary: `private-until-release-owner-acceptance`
+
+## Purpose
+
+Visual Owner Artifacts connect the existing DOM-first Visual Snapshot Automation with a reproducible screenshot/pixel artifact path for RC1. The local gate validates contract, manifest and DOM snapshot state. Actual screenshot generation remains optional and belongs in stable browser or CI environments.
+
+## Path Convention
+
+```text
+.xtend-test-results/visual-snapshots/rc1/{family}/{viewport}/{theme}/{density}/{motion}.png
+```
+
+The report is stored at:
+
+```text
+.xtend-test-results/visual-snapshots/rc1/visual-owner-artifact-report.json
+```
+
+The fixture remains `tests/browser/fixtures/visual-snapshots-fixture.html`; the DOM baseline remains `tests/browser/visual-baselines/visual-snapshots.dom-baseline.json`.
+
+## Local Usage
+
+```bash
+npm run test:epic13-visual-owner-artifact
+```
+
+The local mode is `static-artifact-manifest-plus-dom-snapshot-gate`. `pixelDiffRequiredInLocalGate`, `screenshotRequiredInLocalGate` and `binaryBaselineCommitted` are `false`.
+
+## Relationship to Existing Gates
+
+- The DOM structure comes from [Visual Snapshot Automation](./visual-snapshot-automation.md).
+- The production-close browser/CSP preparation comes from [PROD Browser CSP Smokes](./prod-browser-csp-smokes.md).
+- The owner artifact remains `optional-browser-driver-or-ci-artifact` until a stable browser-capture environment is chosen as a required release gate.
+
+## Handoff
+
+`WP-E13-08` is complete. `WP-E13-09` bundled `xtend.epic13.rmt-production-readiness.v1` under [RMT Production Readiness](./rmt-production-readiness.md). `WP-E13-10` completed [Docs RMT Production Hardening](./docs-rmt-production-hardening.md). `WP-E13-11` completed [Trusted DOM Boundary Browser Proof](./trusted-dom-boundary-browser-proof.md) and `xtend.epic13.trusted-dom-boundary.v1`. `WP-E13-12` completed [RC1 Migration Notes](./rc1-migration-notes.md) and `xtend.epic13.rc1-migration-notes-semver.v1`. `WP-E13-13` completed [RC1 Gate Matrix and CI Handoff](./rc1-gate-matrix-ci-handoff.md) and `xtend.epic13.rc1-gate-matrix-ci-handoff.v1`.

package/docs/en/visual-snapshot-automation.md

@@ -0,0 +1,87 @@
+# Visual Snapshot Automation
+
+- Contract: `xtend.epic12.visual-snapshot-automation-contract.v1`
+- Entry contract: `xtend.epic12.visual-snapshot-automation-entry.v1`
+- Automation report contract: `xtend.epic12.visual-snapshot-automation-report.v1`
+- Runner contract: `xtend.epic12.visual-snapshot-runner.v1`
+- Fixture contract: `xtend.epic12.visual-snapshot-fixture.v1`
+- Runner report contract: `xtend.epic12.visual-snapshot-runner-report.v1`
+- Design token contract: `xtend.design-tokens.product-contract.v1`
+- Workpackages: `WP-E12-10`, `WP-E12-11`, `WP-E12-12`
+- Contract gate: `node scripts/run_xtend_tests.js visual-snapshot-automation --json`
+- Snapshot gate: `node scripts/run_xtend_tests.js visual-snapshots --json`
+
+XTend Visual Snapshot Automation is the Epic 12 line for local visual regression. `WP-E12-10` defines scopes, matrix, tolerances and artifact policy. `WP-E12-11` builds a local DOM-first snapshot runner with JSON baseline on top of that.
+
+## Check Locally
+
+```bash
+node scripts/run_xtend_tests.js visual-snapshot-automation
+node scripts/run_xtend_tests.js visual-snapshot-automation --json
+npm run test:visual-snapshot-automation
+node scripts/run_xtend_tests.js visual-snapshots --json
+npm run test:visual-snapshots
+node scripts/run_xtend_tests.js design-tokens --json
+npm run test:design-tokens
+```
+
+The gate is local-only, CDN-free and uses no external browser services.
+
+## Matrix
+
+The contract adopts the 360 combinations of the Component Shell Theme Matrix:
+
+- themes: `light`, `dark`, `high-contrast`, `forced-colors`
+- motion: `default-motion`, `reduced-motion`
+- density: `comfortable`, `compact`, `dense`
+- viewports: `desktop-1280`, `tablet-768`, `mobile-390`
+- UX families: `form-controls`, `feedback-status`, `navigation-routing`, `overlay-interaction`, `layout-display-media`
+
+## Snapshot Scopes
+
+- `shell-structure`
+- `visual-state`
+- `theme-token-state`
+- `motion-density-state`
+- `viewport-layout`
+- `focus-a11y-state`
+- `rmt-shell-descriptor`
+
+The RMT boundary remains `no-rmt-kernel-import-of-xtend-types`: RMT describes and schedules shells, but imports no XTend types into the kernel.
+
+As of `WP-E12-12`, the snapshot fixture uses the same product tokens as `x-theme` and the Component Shell Theme Matrix. The DOM baseline tracks `--xtend-surface`, `--xtend-text`, `--xtend-color-primary`, `--xtend-density-spacing` and `--xtend-radius`; local fixture names such as `--snapshot-*` have been removed.
+
+## Diff Strategy
+
+`WP-E12-10` defines `dom-first-pixel-ready`; `WP-E12-11` performs the local DOM diff:
+
+- DOM structure and CSS tokens have tolerance `0`.
+- Pixel diff is prepared as `optional-local-pixel-diff`, but does not run in the Node contract gate.
+- Maximum pixel mismatch is `0.01`.
+- Layout shift is limited to `1px`.
+- Before capture, the runner must wait for custom elements, fonts, loader completion and one animation frame.
+
+## Artifacts
+
+| Artifact | Path |
+|----------|------|
+| Contract | `development/XTend-Visual-Snapshot-Automation-Contract.md` |
+| Plan | `tests/browser/visual-snapshot-automation-plan.js` |
+| Automation suite | `tests/browser/visual_snapshot_automation_suite.js` |
+| Runner | `tests/browser/visual-snapshots-runner.js` |
+| Fixture | `tests/browser/fixtures/visual-snapshots-fixture.html` |
+| DOM baseline | `tests/browser/visual-baselines/visual-snapshots.dom-baseline.json` |
+| Snapshot suite | `tests/browser/visual_snapshots_suite.js` |
+| Output root | `.xtend-test-results/visual-snapshots` |
+| Report path | `.xtend-test-results/visual-snapshots/visual-snapshots-report.json` |
+| RC1 owner manifest | `tests/browser/visual-baselines/rc1-visual-owner-artifact.manifest.json` |
+
+The baseline is textual and reviewable in `WP-E12-11`. Binary or screenshot baselines remain reserved for an optional local pixel-diff mode.
+
+## RC1 Visual Owner Artifact
+
+As of `WP-E13-08`, [Visual Owner Artifacts](./visual-owner-artifacts.md) uses this DOM-first line as the source for `xtend.epic13.visual-owner-artifact.v1`. The local gate `node scripts/run_xtend_tests.js epic13-visual-owner-artifact --json` normalizes artifact root, report path, screenshot template and viewports. Screenshot/pixel creation remains `optional-browser-driver-or-ci-artifact`.
+
+## RC0 Adoption Update
+
+Since `WP-E12-15`, the [RC0 Adoption Guide](./rc0-adoption-guide.md) references this DOM-first snapshot path as RC0 baseline. Component authors treat `visual-snapshots`, `design-tokens` and `component-shell-theme-matrix` together as a local review chain; pixel baselines remain optional and must not block the local RC0 dry run.

package/docs/en/xtend-api-types.md

@@ -0,0 +1,55 @@
+# XTend API Types
+
+- Contract: `xtend.type-exports.api-declarations.v1`
+- Workpackage: `WP-TypeExports-03`
+- Gate: `node scripts/run_xtend_tests.js type-exports-api --json`
+- Report: `.xtend-test-results/xtend-type-exports-api-report.json`
+- Declaration: `api.d.ts`
+
+## Purpose
+
+`api.d.ts` describes the public core API from `api.js`: `initXTendAPI(manifest)`, the global namespace `window.XTend.*`, the legacy aliases and the event `xtend-api-ready`. The declaration is types-only; `api.js` remains unchanged at runtime.
+
+## Namespace
+
+The central namespace type is `XTendNamespace`.
+
+| API | Type |
+| --- | --- |
+| `window.XTend.compliance` | `XTendComplianceApi` |
+| `window.XTend.theme` | `XTendThemeApi` |
+| `window.XTend.toast` | `XTendToastApi` |
+| `window.XTend.alert` | `XTendAlertApi` |
+| `window.XTend.dialog` | `XTendDialogApi` |
+| `window.XTend.modal` | `XTendModalApi` |
+
+## Legacy Aliases
+
+`api.d.ts` continues to type the existing global convenience aliases:
+
+- `window.XTheme`
+- `window.XToast`
+- `window.XAlert`
+- `window.XDialog`
+- `window.XModal`
+- `window.showToast`
+- `window.showAlert`
+- `window.showDialog`
+- `window.showModal`
+
+## Event
+
+`WindowEventMap` contains `xtend-api-ready` with `XTendApiReadyDetail`. The payload reports whether toast, alert, dialog, modal and theme APIs are initialized.
+
+## Package Export
+
+As of `WP-TypeExports-03`, the package export `./api` has the `types` condition `./api.d.ts`. `browser` and `default` continue to point to `./api.js`.
+
+## Drift Gate
+
+The gate `type-exports-api` checks:
+
+- `api.d.ts` exists and is included in the package.
+- `./api` points to `./api.d.ts` through `types`.
+- `initXTendAPI`, `window.XTend.*`, legacy aliases and `xtend-api-ready` are visible in runtime and declaration.
+- `api.js` imports no declaration file.

package/docs/en/xtend-builder-types.md

@@ -0,0 +1,55 @@
+# XTend Builder Types
+
+Status: `completed`  
+Workpackage: `WP-TypeExports-06`  
+Schema: `xtend.type-exports.builder-declarations.v1`  
+Gate: `node scripts/run_xtend_tests.js type-exports-builder --json`
+
+## Scope
+
+`WP-TypeExports-06` types the Builder, Scaffold and Component Lab program APIs without porting the CLI or generators to TypeScript.
+
+The shared basis lives in `./xtend-builder/builder-public-types.d.ts`:
+
+- `XtendBuilderComponentInput`
+- `XtendBuilderComponentPlan`
+- `XtendBuilderComponentFilesResult`
+- `XtendBuilderWorkflow`
+- `XtendBuilderComponentLabPlan`
+
+## Declaration Pack
+
+The root and workflow APIs are stabilized through these facades:
+
+- `./xtend-builder/scaffold.d.ts`
+- `./xtend-builder/lib/cli.d.ts`
+- `./xtend-builder/blueprints/component-blueprint.contract.d.ts`
+- `./xtend-builder/generators/component-plan.d.ts`
+- `./xtend-builder/generators/component-files.d.ts`
+- `./xtend-builder/generators/registry.d.ts`
+- `./xtend-builder/workflows/developer-workflow.d.ts`
+
+Component Lab and preview consumers receive their own contracts:
+
+- `./xtend-builder/preview/component-preview.d.ts`
+- `./xtend-builder/preview/component-lab.d.ts`
+- `./xtend-builder/preview/component-lab-ux-inspector.d.ts`
+
+The already exported typing and UX contract modules are represented as narrow facades, including `component-shell-contract`, `component-styling-contract`, `component-network-contract`, `rmt-shell-authoring-contract`, `rmt-dsl-authoring-polish`, the form/feedback/navigation/overlay/layout UX contracts and `component-ux-performance-contract`.
+
+## Package Exports
+
+The package exports `./builder`, `./builder/*` and the explicit builder subexports receive `types` conditions. Example:
+
+```json
+"./builder": {
+  "types": "./xtend-builder/scaffold.d.ts",
+  "default": "./xtend-builder/scaffold.js"
+}
+```
+
+`./builder/*` remains a generic connection for repo-local builder modules and points to `./xtend-builder/*.d.ts`.
+
+## Boundary
+
+The declarations remain `types-only-no-runtime-imports`. They import no builder runtime, components, RMT kernel or loader/API runtime. The local gate compares runtime exports, package `types` conditions, existing declaration files and the shared builder type base.

package/docs/en/xtend-catalog-types.md

@@ -0,0 +1,44 @@
+# XTend Catalog Types
+
+- Contract: `xtend.type-exports.catalog-declarations.v1`
+- Workpackage: `WP-TypeExports-07`
+- Gate: `node scripts/run_xtend_tests.js type-exports-catalog --json`
+- Report: `.xtend-test-results/xtend-type-exports-catalog-report.json`
+
+## Purpose
+
+Catalog modules describe XTend gates, handoffs, release plans and SurfaceManager runtime scopes as machine-readable plan/report structures. `WP-TypeExports-07` introduces a shared declaration pattern so new catalogs do not need to type every property from scratch.
+
+`./catalog/catalog-public-types.d.ts` defines the shared base types `XtendCatalogPlan`, `XtendCatalogReport`, `XtendCatalogGate`, `XtendCatalogFactory`, `XtendCatalogValidator` and `XtendCatalogDiagnostic`. The individual catalog facades export the runtime symbols of the respective `.js` module and bind functions such as `create*Plan`, `create*Report`, `create*Gate` and `validate*Plan` to these base types.
+
+## Package Surface
+
+All public `./catalog/*` package exports now have their own `types` condition. Examples:
+
+```json
+"./catalog/epic13-package-export-lock": {
+  "types": "./catalog/epic13-package-export-lock.d.ts",
+  "default": "./catalog/epic13-package-export-lock.js"
+}
+```
+
+The runtime target remains unchanged. The declarations import no runtime files and are intended as consumer facades.
+
+## Catalog Families
+
+The gate classifies three catalog families that matter for XTend:
+
+- SurfaceManager catalogs remain internal XTend UI support and document app-shell, surface, routing and runtime handoffs.
+- Epic catalogs describe workpackage, gate and contract plans across multiple epics.
+- Release catalogs bundle handoff, readiness, export-lock and migration decisions.
+
+The SurfaceManager catalogs do not replace Fabric, the RMT kernel or a runtime layer. They remain declarative plans and reports that support UI surfaces.
+
+## Drift Gate
+
+```bash
+node scripts/run_xtend_tests.js type-exports-catalog --json
+npm run test:type-exports-catalog
+```
+
+The gate verifies that package catalogs have their `types` conditions, that all catalog runtime exports appear in the `.d.ts` facades, that SurfaceManager/epic/release catalogs are classified and that runtime files receive no declaration imports.

package/docs/en/xtend-fabric-rmt-lane-mapping.md

@@ -0,0 +1,143 @@
+# XTend-Fabric RMT Lane Mapping
+
+- Status: production mapping contract starting with `ER-WP-13`
+- Contract: `xtend.docs.xtend-fabric-rmt-lane-mapping.v1`
+- Mapping Contract: `xtend.fabric.rmt-lane-mapping.v1`
+- Runtime: `fabric/rmt-lane-mapping.js`
+- Test: `tests/fabric/fabric_rmt_lane_mapping_suite.js`
+
+## Purpose
+
+`fabric/rmt-lane-mapping.js` connects Fabric lanes with RMT schedule policies without building XTend into the RMT kernel.
+
+Fabric describes UI work semantically: `user-blocking`, `a11y`, `visible`, `transition`, `idle`, `background`, `diagnostics`. RMT remains host-neutral and still sees only schedule records with `endpointName`, `scope`, `lane`, `priority`, `deadlineMs`, `preferIdle`, `coalesceKey` and `budgetClass`.
+
+Since `WP-E13-09`, [RMT Production Readiness](./rmt-production-readiness.md) references this mapping under `xtend.epic13.rmt-production-readiness.v1` so RMT-first apps can ingest Fabric/Lane signals in a production-oriented way without violating the RMT kernel boundary.
+
+## Lane Mapping
+
+| Fabric Lane | RMT Schedule Lane | Reason |
+|-------------|-------------------|--------|
+| `user-blocking` | `user-blocking` | input, navigation and focus are critical |
+| `a11y` | `user-blocking` | screen-reader and focus signals are user-facing; RMT does not yet have a dedicated `a11y` lane |
+| `visible` | `visible` | visible component work |
+| `transition` | `transition` | route and UI transitions |
+| `idle` | `idle` | non-visible hydration and follow-up |
+| `background` | `background` | best-effort work |
+| `diagnostics` | `diagnostics` | telemetry and snapshots |
+
+`a11y` therefore remains a Fabric lane. The generated RMT schedule record carries the RMT lane `user-blocking` and preserves `metadata.fabricLane = "a11y"` so reporters and later adapters can see the original semantics.
+
+## API
+
+```js
+const mapping = window.XTendFabricRmtLaneMapping.createFabricRmtLaneMapping();
+
+const result = mapping.resolveFiber({
+  kind: 'component.hydrate',
+  lane: 'idle',
+  scope: 'x-alert#secondary',
+  componentRef: 'x-alert'
+});
+```
+
+Important functions:
+
+| API | Purpose |
+|-----|---------|
+| `createFabricRmtLaneMapping(options)` | creates a mapping object with lane map and schedule records |
+| `createRmtScheduleRecords(options)` | creates host-neutral RMT schedule records for Fabric lanes |
+| `resolveRmtScheduleForFiber(fiber, options)` | resolves a fiber to a schedule record |
+| `normalizeFabricLaneForRmt(lane)` | translates one Fabric lane into an RMT lane |
+
+## Example Schedule Records
+
+```json
+{
+  "schema": "xtend.fabric.rmt-lane-schedule.v1",
+  "id": "component.idle.hydrate",
+  "endpointName": "xtendrmt.component.hydrate",
+  "scope": "xtend.fabric.idle",
+  "lane": "idle",
+  "priority": 35,
+  "deadlineMs": 500,
+  "preferIdle": true,
+  "coalesceKey": "xtend.fabric.idle",
+  "budgetClass": "background",
+  "metadata": {
+    "contract": "xtend.fabric.rmt-lane-mapping.v1",
+    "fabricLane": "idle",
+    "rmtLane": "idle"
+  }
+}
+```
+
+Since `ER-WP-20`, there is also `component.lazy.hydrate` for hydration deferred below the fold or under backpressure. The RMT lane remains `idle`; the difference is in `scheduleRef`, scope and coalescing.
+
+```json
+{
+  "schema": "xtend.fabric.rmt-lane-schedule.v1",
+  "id": "a11y.user-blocking.announce",
+  "endpointName": "xtendrmt.a11y.announce",
+  "scope": "xtend.fabric.a11y",
+  "lane": "user-blocking",
+  "priority": 95,
+  "deadlineMs": 80,
+  "preferIdle": false,
+  "coalesceKey": "xtend.fabric.a11y.announce",
+  "budgetClass": "critical",
+  "metadata": {
+    "contract": "xtend.fabric.rmt-lane-mapping.v1",
+    "fabricLane": "a11y",
+    "rmtLane": "user-blocking",
+    "reason": "RMT schedules-domain has no dedicated a11y lane in xtend.rmt.schedules-domain.v1."
+  }
+}
+```
+
+## Kernel Boundary
+
+The mapping imports no XTendRMT kernel and parses no `.rmt` documents. It can already accept normalized schedule records from a host or test fixture and resolve `scheduleRef` or `endpointNameHint` against them.
+
+Allowed:
+
+- map Fabric fibers to RMT schedule records
+- use generated schedule records as app/adapter hints
+- reference existing `schedules[*]` records from normalized RMT documents
+- preserve `metadata.fabricLane` for diagnostics and reporters
+
+Not allowed:
+
+- import the RMT runtime or kernel into Fabric
+- force `a11y` as an RMT kernel lane
+- execute XTend components in the RMT kernel
+- duplicate RMT schema validation in Fabric
+
+## Adapter Ingestion
+
+Starting with Epic 10 / `WP-E10-05`, the production `xtend.component` adapter uses the same semantics as runtime context. The contract is `xtend.component.fabric-lane-ingestion.v2`.
+
+Precedence in the adapter:
+
+1. `rmt.schedule-record`
+2. `rmt.component-metadata`
+3. `fabric.runtime-override`
+4. `component.static-contract`
+5. `scaffold.blueprint-default`
+
+The adapter does not import Fabric into the RMT kernel. During mounting and hydration it only resolves the Fabric context, sets `result.metadata.fabric` and marks DOM hosts with `data-xtend-fabric-lane`, `data-xtend-rmt-lane`, `data-xtend-fabric-fiber`, `data-xtend-fabric-source` and `data-rmt-endpoint`.
+
+## Gates
+
+```bash
+node scripts/run_xtend_tests.js fabric-lane-mapping --json
+node scripts/run_xtend_tests.js rmt-component-fabric-ingestion --json
+node scripts/run_xtend_tests.js hydration-policy --json
+npm run test:fabric-lanes
+npm run test:rmt-component-fabric-ingestion
+npm run test:hydration-policy
+node scripts/run_xtend_tests.js references --json
+npm test
+```
+
+`ER-WP-20` builds on this and hardens lazy/idle/visible hydration policies with concrete `scheduleRef` decisions. Route render and XRouter navigation remain correlatable through `ER-WP-15`.