@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/xtend-loader.md

@@ -0,0 +1,265 @@
+# XTend Loader
+
+## Overview
+
+The canonical XTend loader is `xtend-loader.js`.
+
+It is a local ES module entry for XTend UI and handles dynamic loading of the manifest, Core modules, explicitly preloaded components, components used in the DOM and `api.js`.
+
+`xtend-dev.js` is now only a legacy stub. New demos, browser smokes, scaffold output and official examples use `xtend-loader.js`.
+
+Since `ER-WP-05`, the default demo and fixture paths are formally fixed to the canonical loader or to deliberately classified special smokes. Since `ER-WP-18`, the loader measures manifest load, module load and Custom Element definition through local performance marks. Since `ER-WP-28`, it validates manifest and module URLs against `xtend.security.loader-policy.v1`, `xtend.security.manifest-policy.v1` and `xtend.security.import-policy.v1`.
+
+## Integration
+
+```html
+<script type="module" src="./xtend-loader.js"></script>
+```
+
+Optionally, a local manifest can be set:
+
+```html
+<script
+  type="module"
+  src="./xtend-loader.js"
+  data-manifest="./components/manifest.json">
+</script>
+```
+
+By default, the loader uses:
+
+```text
+components/manifest.json
+```
+
+## Contract
+
+The loader contract is:
+
+```text
+xtend.loader.contract.v1
+```
+
+Security contracts:
+
+```text
+xtend.security.loader-policy.v1
+xtend.security.manifest-policy.v1
+xtend.security.import-policy.v1
+```
+
+Near the browser, the loader exposes this surface:
+
+```js
+window.XTendLoader
+```
+
+The automatic boot promise is available under:
+
+```js
+window.__XTendLoaderBootPromise
+```
+
+## Verbose Mode
+
+The PROD loader is quiet in the console by default. The loader file contains a direct flag near the top:
+
+```js
+const verbose_mode = 'auto';
+```
+
+Supported values:
+
+| Value | Behavior |
+|-------|----------|
+| `'true'` | Verbose is permanently active. Loader module operations and connected Core runtime logs are printed in the browser console. |
+| `'false'` | Verbose is locked. It can only be re-enabled by changing the loader file. |
+| `'auto'` | Verbose is off on first start and can be enabled in the browser console for the current tab session. |
+
+Browser console:
+
+```js
+XTendLoader.verbose(true)
+XTendLoader.verbose(false)
+XTendLoader.verbose()
+```
+
+Alternatively:
+
+```js
+XTendLoader.enableVerbose()
+XTendLoader.disableVerbose()
+XTendLoader.getVerboseState()
+```
+
+In `auto`, the loader stores the console decision in `sessionStorage`. After `XTendLoader.verbose(true)`, a reload is enough to also see the initial module-loading operations in the same browser session. `XTendLoader.verbose(false)` makes the session quiet again.
+
+Structured diagnostics (`xtend-loader-diagnostic`) and performance events (`xtend-loader-performance`) remain available independently of verbose mode.
+
+## How It Works
+
+1. The loader initializes `xtend.loader.style-registry.v1` and injects runtime-critical styles for tokens, UI effects, skeletons and undefined XTend Custom Elements.
+2. It waits for window load.
+3. It validates `data-manifest` or `components/manifest.json` against the loader policy.
+4. It loads the manifest and resolves manifest URLs relative to the manifest URL.
+5. It validates every manifest record against the manifest and import policies.
+6. It can version module URLs through `data-module-cache-bust` so live systems do not pull stale component modules from the browser cache.
+7. It loads `xstate` and then `x-theme` when both are listed in the manifest. `xstate` is deliberately not cache-busted so no second state module instance is created.
+8. It loads entries from `<meta name="xtend-preload">`.
+9. It detects XTend tags used in the DOM and loads visible components immediately.
+10. It observes non-visible components through `IntersectionObserver`.
+11. It provides `xtend.loader.skeleton-loader.v1` for shell, route and dynamic subtree fallbacks.
+12. It validates and imports local `api.js`, then calls `api.initXTendAPI(manifest)`.
+
+## StyleRegistry
+
+The loader exports the native StyleRegistry:
+
+```js
+window.XTendStyleRegistry
+window.XTendLoader.styles
+```
+
+When `xtend-loader.js` is evaluated, the loader immediately calls `ensureRuntimeStyles()`. This ensures the critical CSS rules exist before components are imported or hydrated. `xtend.css` remains the canonical standard file name for host theming and docs/app layout, but it is no longer a hard requirement for skeletons, UI effects, base tokens or FOUC protection for undefined XTend Custom Elements.
+
+Hosts can read the theme stylesheet state:
+
+```js
+XTendLoader.getThemeStylesheetState()
+```
+
+Components can register their own styles and apply them to shadow roots:
+
+```js
+const style = XTendLoader.defineComponentStyle('x-example', ':host { display: block; }');
+XTendLoader.adoptStyle(this.shadowRoot, style);
+```
+
+## SkeletonLoader
+
+The loader exports a native SkeletonLoader for shell-first apps:
+
+```js
+window.XTendLoader.showSkeleton(target, { lines: 8, schedule: 'docs.page.hydrate' });
+window.XTendLoader.hideSkeleton(target);
+```
+
+Hosts can show undefined XTend Custom Elements as skeletons through `data-xtend-skeleton`. Known XTend tags without skeleton opt-in remain invisible until definition so Light DOM text does not flash unstyled. These rules come from the StyleRegistry and also work without external `xtend.css`.
+
+## Preload
+
+Components can still be explicitly preloaded:
+
+```html
+<meta name="xtend-preload" content="x-router,x-link,x-dialog,x-modal">
+```
+
+The values are component IDs from the manifest, not free-form URLs.
+
+## Live Deployment Cache Busting
+
+Shell apps can load the loader, manifest and component modules with a version:
+
+```html
+<script
+  type="module"
+  src="/xtend-loader.js?v=20260507"
+  data-manifest="/components/manifest.json?v=20260507"
+  data-module-cache-bust="20260507">
+</script>
+```
+
+The loader appends this value to manifest modules as the `xtend-cache` query parameter. `xstate` is excluded because components import it themselves through `./xstate.js` and XTend should keep exactly one state instance.
+
+## Manifest Example
+
+```json
+{
+  "xstate": "./xstate.js",
+  "x-theme": "./xtheme.js",
+  "x-router": "./xrouter.js",
+  "x-link": "./xlink.js",
+  "x-dialog": "./xdialog.js",
+  "x-modal": "./xmodal.js"
+}
+```
+
+## Legacy Strategy
+
+`xtend-dev.js` remains as a compatibility stub for a short migration phase.
+
+The stub:
+
+- warns in the console
+- imports `./xtend-loader.js`
+- contains no loader logic of its own
+
+Default demos and tests must no longer use the legacy name as the canonical loader path.
+
+## Security and Runtime Boundaries
+
+The loader remains local and ESM-based.
+
+CDN is not a default or test path. Since `ER-WP-03`, `api.js`, `components/manifest.json`, Core components and browser fixtures use repo-local XTend paths. Since `ER-WP-05`, reference and browser gates also verify that default demos do not fall back to `xtend-dev.js` or XTend CDN bridges. Since `ER-WP-28`, the loader refuses external manifest and module URLs, `javascript:`, `data:`, `blob:`, mismatched file extensions and path traversal with structured security diagnostics.
+
+The loader emits structured local diagnostics as the `xtend-loader-diagnostic` event and thereby prepares later integration with `XTend-Fabric`.
+
+Security refusals use these codes:
+
+- `xtend.security.loader.refused`
+- `xtend.security.manifest.invalid`
+- `xtend.security.import.refused`
+
+## Performance Measurements
+
+The loader creates `performance.mark` and `performance.measure` entries for:
+
+| Measure | Phase |
+|---------|-------|
+| `xtend.loader.manifest` | `load` |
+| `xtend.loader.module` | `load` |
+| `xtend.component.define` | `define` |
+
+After module load, `xtend.component.define` briefly waits for `customElements.whenDefined(tag)`, but does not block the loader permanently when a manifest entry does not register a Custom Element.
+
+In addition, it emits a local event for every measurement:
+
+```js
+window.addEventListener('xtend-loader-performance', (event) => {
+  console.log(event.detail.name, event.detail.durationMs);
+});
+```
+
+The boot promise contains the local loader measurements:
+
+```js
+const boot = await window.__XTendLoaderBootPromise;
+console.log(boot.performanceMeasurements);
+```
+
+Fabric telemetry snapshots normalize these entries as `xtend.performance.measurement.v1`.
+
+## Gates
+
+Relevant local checks:
+
+```bash
+npm run dev:local
+npm run test:browser:local
+node scripts/run_xtend_tests.js browser --json
+node scripts/run_xtend_tests.js manifest-import-policy --json
+node scripts/run_xtend_tests.js fabric-performance-measurements --json
+node scripts/run_xtend_tests.js references --json
+npm test
+```
+
+`npm run dev:local` starts `scripts/serve_xtend_dev.js` on port `4173`. The browser-smoke harness uses the same server module in test mode with port `0`.
+
+## Further Topics
+
+- [Manifest Format](./manifest.md)
+- [Manifest Import Policy](./manifest-import-policy.md)
+- [Performance Measurements](./performance-measurements.md)
+- [API Integration](./api.md)
+- [Component Development](./components.md)
+- [Best Practices](./best-practices.md)

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

@@ -0,0 +1,38 @@
+# XTend Policy Types
+
+- Contract: `xtend.type-exports.policy-declarations.v1`
+- Workpackage: `WP-TypeExports-05`
+- Gate: `node scripts/run_xtend_tests.js type-exports-policy --json`
+- Report: `.xtend-test-results/xtend-type-exports-policy-report.json`
+- Boundary: `types-only-no-runtime-imports`
+- Boundary: `no-rmt-kernel-import-of-xtend-types`
+- Boundary: `declarations-follow-js-runtime-surface`
+
+## Purpose
+
+`WP-TypeExports-05` makes the Fabric, a11y and security policy APIs importable for TypeScript consumers. The JS runtime remains unchanged; `package.json#exports` only adds package-native `types` conditions.
+
+## Declaration Pack
+
+| Area | Package export | Declaration |
+| --- | --- | --- |
+| Fabric Runtime | `./fabric` | `./fabric/xtend-fabric.d.ts` |
+| Fabric/RMT Policy | `./fabric/rmt-lane-mapping`, `./fabric/hydration-policy` | `./fabric/*.d.ts` |
+| A11y Policies | `./a11y/screenreader-signals`, `./a11y/motion-contrast-policy`, `./a11y/runtime-a11y-contract` | `./a11y/*.d.ts` |
+| Security Policies | `./security/manifest-import-policy`, `./security/trusted-dom-policy`, `./security/supply-chain-gate-policy` | `./security/*.d.ts` |
+
+The shared type core is in `fabric/xtend-policy-public-types.d.ts` and includes `XtendPolicyDiagnostic`, `XtendPolicyReport`, `XtendFabricFiberInput`, `XtendA11ySignal` and `XtendSecurityClassification`.
+
+## Drift Gate
+
+The gate verifies:
+
+- every policy package export condition points to the expected `.d.ts`
+- every declaration file exists and exports the runtime symbols of the corresponding JS module
+- central diagnostic, report, fiber, a11y and security classification types remain present
+- Fabric/a11y/security runtime files import no `.d.ts`
+- no policy introduces runtime dependencies into components, loader, API or RMT kernel
+
+## Handoff
+
+`WP-TypeExports-06` can now type Builder, Scaffold and Component Lab program APIs. The policy pack continues the pattern for integration modules: existing JS runtime, narrow declaration facades, package-native `types` conditions and a drift gate against export deviations.

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

@@ -0,0 +1,40 @@
+# XTend RMT Types
+
+- Contract: `xtend.type-exports.rmt-declarations.v1`
+- Workpackage: `WP-TypeExports-04`
+- Gate: `node scripts/run_xtend_tests.js type-exports-rmt --json`
+- Report: `.xtend-test-results/xtend-type-exports-rmt-report.json`
+- Boundary: `types-only-no-runtime-imports`
+- Boundary: `no-rmt-kernel-import-of-xtend-types`
+- Boundary: `declarations-follow-js-runtime-surface`
+
+## Purpose
+
+`WP-TypeExports-04` makes the XTendRMT runtime, browser entry and RMT language/tooling exports importable for TypeScript consumers. `./rmt` and `./rmt/browser` point through a `types` condition to `./xtendrmt/rmt-core.d.ts`, while `./rmt/dom-descriptor-renderer`, `./rmt/state-selector-runtime`, `./rmt/action-effect-runtime`, `./rmt/event-routing-runtime` and `./rmt/surface-resource-graph-runtime` have their own narrow runtime declarations.
+
+## Declaration Pack
+
+| Area | Package export | Declaration |
+| --- | --- | --- |
+| RMT Runtime | `./rmt`, `./rmt/browser` | `./xtendrmt/rmt-core.d.ts` |
+| RMT App Platform Runtime | `./rmt/dom-descriptor-renderer`, `./rmt/state-selector-runtime`, `./rmt/action-effect-runtime`, `./rmt/event-routing-runtime`, `./rmt/surface-resource-graph-runtime` | `./xtendrmt/rmt-dom-descriptor-renderer.d.ts`, `./xtendrmt/rmt-state-selector-runtime.d.ts`, `./xtendrmt/rmt-action-effect-runtime.d.ts`, `./xtendrmt/rmt-event-routing-runtime.d.ts`, `./xtendrmt/rmt-surface-resource-graph-runtime.d.ts` |
+| Source Model and Parser | `./rmt-language/source-model`, `./rmt-language/parser` | `tools/rmt-language/*.d.ts` |
+| vNext Compiler and Contracts | `./rmt-language/vnext-*` | `tools/rmt-language/vnext-*.d.ts` |
+| Tooling Services | `./rmt-language/diagnostics`, `./rmt-language/app-platform-tooling`, `./rmt-language/completions`, `./rmt-language/hover`, `./rmt-language/symbols`, `./rmt-language/definitions`, `./rmt-language/code-actions` | service facades with shared RMT tooling types |
+| LSP, Linter, Editor | `./rmt-language-server`, `./rmt-linter/*`, `./rmt-editor/vscode` | LSP/CLI/editor facades |
+
+The shared type core is in `tools/rmt-language/rmt-tooling-public-types.d.ts` and includes `RmtToolingDiagnostic`, `RmtTextEdit`, `RmtWorkspaceEdit`, `RmtLanguageServiceReport` and `RmtJsonRpcMessage`.
+
+## Drift Gate
+
+The gate verifies:
+
+- every RMT package export condition points to the expected `.d.ts`
+- every declaration file exists and exports the runtime symbols of the corresponding JS module
+- central diagnostic, range, edit, completion, hover, symbol, definition, code-action and JSON-RPC types remain present
+- RMT runtime files import no `.d.ts`
+- RMT kernel imports no XTend UI types, loader, API, Fabric, a11y or security runtime surfaces
+
+## Handoff
+
+`WP-TypeExports-05` can now type Fabric, a11y and security policy APIs. The RMT pack is the reference for P1 integration modules: narrow declarations, existing JS runtime, package-native `types` conditions and a drift gate against export deviations.

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

@@ -0,0 +1,36 @@
+# XTend Vendor and Utility Types
+
+- Contract: `xtend.type-exports.vendor-facades.v1`
+- Workpackage: `WP-TypeExports-08`
+- Gate: `node scripts/run_xtend_tests.js type-exports-vendor --json`
+- Report: `.xtend-test-results/xtend-type-exports-vendor-report.json`
+
+## Purpose
+
+`WP-TypeExports-08` closes the remaining type-facade gaps on edge modules. The facades are intentionally narrow: XTend does not copy the full Prism or Turndown type world, but describes only the stable usage boundary inside the project.
+
+## Facades
+
+- `./components/prism.d.ts` describes the global and CommonJS-capable Prism facade with `highlight`, `highlightElement`, `highlightAllUnder`, `hooks`, `languages` and `Token`.
+- `./components/turndown.d.ts` describes the browser-global facade `window.TurndownService` for side-effect imports and local Markdown conversion.
+- `./design-tokens/xtend-design-tokens.d.ts` describes the productive design-token contract `xtend.design-tokens.product-contract.v1`, theme packs, density packs and validators.
+- `./design-tokens/xtheme-token-alias-layer.d.ts` describes the XTheme alias layer `xtend.theme.token-alias-layer.v1`, legacy bridges, component aliases and validators.
+
+## Theme JSON
+
+`./design-tokens/themes/enterprise-light` remains a JSON boundary. The example theme is exported as a data artifact and does not require its own runtime declaration. Consumers that import JSON should use their project configuration for JSON modules.
+
+## Non-Goals
+
+- No full typing of the entire Prism language list.
+- No adoption of external vendor internals into XTend namespace types.
+- No runtime change to `components/prism.js`, `components/turndown.js`, `design-tokens/xtend-design-tokens.js` or `design-tokens/xtheme-token-alias-layer.js`.
+
+## Drift Gate
+
+```bash
+node scripts/run_xtend_tests.js type-exports-vendor --json
+npm run test:type-exports-vendor
+```
+
+The gate verifies that `./design-tokens` and `./design-tokens/xtheme-token-alias-layer` have a `types` condition, that the component vendor files have their own `.d.ts` facades, that no component `.js` file remains without a declaration-gap decision, and that the facades do not copy runtime imports or vendor implementation details.