@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/XTend-ADR.md

@@ -0,0 +1,221 @@
+# XTend Architecture Decision Record
+
+- Status: Accepted
+- Date: May 8, 2026
+- Contract: `xtend.docs.architecture-decision-record.v2`
+- Type: product architecture baseline for XTend UI, XTend-Fabric and XTendRMT
+
+## Purpose
+
+This ADR replaces the earlier architecture snapshot from the first epics. The old version still described a platform in transition: Core consolidation, loader rename, RMT fusion, test harness and component coverage were partly still target states at that time.
+
+Today's decision describes the current architecture contract for XTend as an enterprise web framework:
+
+- XTend UI is the Web Component and UI Builder product.
+- XTendRMT is scheduler, runtime kernel, templating engine and native `.rmt` authoring language.
+- XTend-Fabric is the host-near protection, telemetry, lane and reporter layer.
+- The Docs App is an XTend app with an RMT-generated shell and Parsedown as a scheduled content component.
+- RMT tooling, linter and language server are part of the authoring platform.
+
+## Decision
+
+XTend continues as a **manifest- and state-centered Web Components framework** with RMT-first app authoring, Fabric boundary and TypeScript-first Component Platform.
+
+Documentation, manifest and runtime APIs must be maintained as one connected contract going forward.
+
+The architecture deliberately separates five responsibilities:
+
+| Layer | Responsibility | May know about | Must not do |
+|-------|----------------|----------------|-------------|
+| XTend UI | Custom Elements, shells, styling, a11y, UX and host components | Manifest, Loader, Component Contracts, Fabric Context | implement RMT kernel semantics |
+| XTend Loader | local ESM imports, manifest policy, bootstrap, component loading | Manifest, Import Policy, Runtime API | force CDN fallbacks or silently load external sources |
+| XTend-Fabric | error boundaries, telemetry, reporter adapters, fibers, lanes, backpressure | XTend Runtime, optional RMT Adapter Results | parse RMT documents or replace XTendRMT |
+| XTendRMT | `.rmt` source, DSL domains, scheduling, templates, routes, diagnostics | neutral adapter records and host capabilities | directly import XTend, XRouter, DOM, React, Vue or `xstate` |
+| Tooling | linter, LSP, snippets, reports, editor bridges | RMT Source Model, Parser, Rule Engine, Schema | maintain separate semantics beside the RMT language core |
+
+## Architecture Principles
+
+### 1. Native Web Standards Remain the Core
+
+XTend is based on Custom Elements, Shadow DOM, slots, CSS Custom Properties and ES modules. Build and TypeScript artifacts must not hide this runtime behind a proprietary abstraction model.
+
+Components remain real Web Components. Integrations for React, Vue or custom hosts are adapters or host conventions, not replacements for the native surface.
+
+### 2. State-Centered UI
+
+`xstate` remains the host-near state boundary for XTend UI. State is the observable truth for UI states, route mirrors, theme context, feedback, component states and diagnostics.
+
+The **Digital Twin Principle** remains binding: relevant UI actions must write back into a traceable state, event or diagnostic record. Local flags may only be derived render caches.
+
+### 3. RMT-First, but Framework-Agnostic
+
+New app shells, routes, templates and scheduling policies should primarily be described in native `.rmt` documents. `.rmt.json` remains only an edge-case fallback for hosts without a suitable MIME type or for legacy paths.
+
+RMT is still not an XTend submodule. XTend is a first-class host, but not a required host. The RMT kernel sees adapter records such as `xtend.component` or `xtend.xrouter`, but imports no XTend components and performs no DOM work itself.
+
+### 4. Shell-First Rendering
+
+App shells should render stably first. Content, Markdown, rich HTML, media and heavy components are scheduled or lazily loaded afterward.
+
+The Docs App is the reference path: RMT creates the shell, Parsedown is a scheduled content component. Later content such as XPlayer tutorials or rich-content blocks can be added to the same scheduling structure.
+
+### 5. Fabric as Safety and Telemetry Layer
+
+XTend-Fabric is the global host safety layer for error boundaries, reporter adapters, telemetry, lane/fiber context, backpressure and quality signals.
+
+Fabric may ingest RMT adapter results and scheduler signals, but it must not replace the RMT kernel. This keeps the boundary clear:
+
+```text
+RMT Kernel -> Adapter / Bridge Result -> XTend-Fabric -> XTend UI / Reporter
+```
+
+### 6. Performance by Design
+
+Performance is not a later optimization step. Components must declare their hydration, visibility, idle, busy and measurement profiles. Loader, Fabric and RMT may use these profiles for scheduling and diagnostics.
+
+The accepted baselines are:
+
+- local ESM instead of CDN dependency
+- manifest-based import policy
+- lazy, idle and visible hydration policies
+- performance regression gates
+- component-level performance profiles
+- shell-first rendering for initial app setup
+
+### 7. A11y by Design
+
+A11y is part of the Component Contract. New components must treat keyboard behavior, focus, ARIA, screen-reader signals, reduced motion, contrast and visible states as product surface.
+
+RMT may describe a11y-relevant shell and component metadata. Concrete execution remains with XTend UI and the host adapters.
+
+### 8. Tooling Is Part of the Product
+
+RMT is not only a runtime format, but an authoring language. Therefore linter, AI-agent repair report, snippets, LSP, editor bridges and release gates belong to the platform.
+
+The language server uses the same semantics as `xt rmt lint`; editor integrations must not maintain a second RMT rule world.
+
+## System View
+
+```text
+App / Host
+  |
+  | local ESM + manifest policy
+  v
+XTend Loader
+  |
+  +-- XTend UI Components
+  |     +-- x-router / x-link
+  |     +-- x-header / x-menu / x-icon / x-hero / ...
+  |     +-- form, feedback, overlay, media and layout components
+  |
+  +-- xstate / xtheme / api.js
+  |
+  +-- XTend-Fabric
+        |
+        +-- telemetry, fibers, lanes, reporter adapters
+        |
+        +-- optional RMT adapter results
+
+XTendRMT
+  |
+  +-- .rmt source model
+  +-- templates, routes, components, schedules, adapters
+  +-- linter, language server, snippets, diagnostics
+  |
+  +-- host adapters: xtend.component, xtend.xrouter, docs.parsedown, custom hosts
+```
+
+## Runtime Decisions
+
+### Loader and Manifest
+
+The canonical loader is `xtend-loader.js`. It is local, ESM-based and manifest-driven. External CDNs are not the normal path. Manifest URLs and component imports are subject to the import policy.
+
+### Components
+
+Components follow Component Contract v2 and the Epic 11 UX shell line:
+
+- TypeScript-first source when new components are created
+- public types
+- RMT metadata
+- Fabric boundary
+- a11y and performance profile
+- component fixture
+- component suite
+- docs page
+
+`x-icon` is the reference case for a framework-agnostic extension: internal Core icon pack, local Lucide extension, pack registry and RMT-compatible adapter without a CDN requirement.
+
+### Routing
+
+`x-router` remains the XTend UI routing component. RMT can declare routes and pass them to XRouter through the `xtend.xrouter` adapter. Page titles, route metadata and shell-near navigation may be described in RMT.
+
+### Docs App
+
+The Docs App is not only documentation, but a product example. It should show:
+
+- shell-first rendering with RMT
+- Parsedown as a scheduled content component
+- stable navigation with `x-router`
+- Quick Start, RMT Authoring, linter and LSP as the official developer journey
+- no app-specific parallel logic when a missing capability belongs in XTend components
+
+## Non-Goals
+
+This decision explicitly does not mean:
+
+- XTend becomes a React/Vue replacement with its own virtual DOM.
+- RMT becomes bound to XTend.
+- Fabric becomes the parser, router or scheduler kernel.
+- `.rmt.json` is promoted as the preferred authoring format.
+- Editor plugins may introduce their own RMT semantics.
+- Components may treat a11y or performance as optional polish for later.
+
+## Consequences
+
+1. New architecture work must first be assigned to a layer: Loader, XTend UI, Fabric, RMT, Tooling or Docs.
+2. When XTend-specific behavior is needed in RMT, an adapter contract is created, not a kernel special case.
+3. When an app needs special logic, first check whether a generic Component, Fabric or RMT capability is missing.
+4. New documentation must recommend native `.rmt` files. `.rmt.json` may only be described as a fallback.
+5. Every new first-class component needs RMT, Fabric, a11y, performance, type and test coverage.
+6. Release and reference gates remain part of the architecture contract.
+
+## Binding Gates
+
+The architecture baseline is protected by local gates:
+
+```bash
+node scripts/run_xtend_tests.js architecture
+node scripts/run_xtend_tests.js references --json
+node scripts/run_xtend_tests.js rmt-compatibility --json
+node scripts/run_xtend_tests.js epic14-lsp-handoff --json
+npm run test:release:full:report
+```
+
+For focused work, the specialized gates remain authoritative:
+
+| Area | Gate |
+|------|------|
+| Core architecture | `node scripts/run_xtend_tests.js architecture` |
+| Component Catalog | `npm run test:catalog-coverage` |
+| RMT Tooling | `npm run test:rmt-tooling` |
+| LSP Handoff | `npm run test:epic14-lsp-handoff` |
+| Docs references | `node scripts/run_xtend_tests.js references --json` |
+
+## Accepted Follow-up Decisions
+
+This ADR integrates the results of the previous individual decisions:
+
+- Loader and local development: `xtend.loader.local-development.adr.v1`
+- XTend-Fabric: `xtend.fabric.adr.v1`
+- Security Trust Boundaries: `xtend.security.trust-boundaries.adr.v1`
+- XTendRMT First-Class Fusion: `development/ADR-XTendRMT-First-Class-Fusion.md`
+- RMT Tooling and LSP Handoff: `xtend.epic14.lsp-handoff.v1`
+
+The individual ADRs remain valid as detail sources. This document is the current Docs App baseline for the overall picture.
+
+## Conclusion
+
+XTend is no longer a loose component package, but a connected platform made of Web Components, loader, state, Fabric, RMT and authoring tooling.
+
+The most important product path is no longer just broadening the surface, but consistently maturing this platform: native `.rmt` authoring experience, better editor support, stable component shells, a11y, performance, security and traceable release gates.

package/docs/en/a11y-keyboard-smokes.md

@@ -0,0 +1,68 @@
+# A11y Keyboard Smokes
+
+Contract:
+
+```text
+xtend.docs.a11y-keyboard-smokes.v1
+xtend.a11y.browser-keyboard-smoke.v1
+```
+
+Starting with `ER-WP-24`, XTend verifies central accessibility interactions in
+a browser-near way. The gate does not replace manual screen reader reviews, but
+it prevents focus and keyboard paths from silently dropping out of core
+components.
+
+## Fixture
+
+The self-checking browser fixture lives here:
+
+```text
+tests/browser/fixtures/a11y-focus-keyboard-smoke.html
+```
+
+It uses:
+
+- `xtend-loader.js`
+- `data-manifest="/tests/browser/fixtures/components/manifest.json"`
+- local component modules
+- `window.__xtendA11yKeyboardSmokeResult`
+
+## Covered Paths
+
+| Area | Component | Expectation |
+|------|-----------|-------------|
+| Routing | `x-link` + `x-router` | `Enter` and `Space` navigate, `aria-current` follows the route |
+| Form | `x-input` + `x-form` | focus is delegated, input syncs `xstate` and form data |
+| Tabs | `x-tabs` | `ArrowRight`, `ArrowLeft`, and `Enter` remain operable |
+| Overlay | `x-modal` | initial focus, focus trap, `Escape`, and focus restore work |
+
+`x-dialog` uses the same overlay contract and is checked source-side for focus
+trap, `Escape`, and focus restore.
+
+## Local Gates
+
+```bash
+node scripts/run_xtend_tests.js browser --json
+node scripts/run_xtend_tests.js a11y-hydration --json
+```
+
+Optionally, the browser smoke can be run with Safari WebDriver:
+
+```bash
+XTEND_BROWSER_SMOKE_DRIVER=safari node scripts/run_xtend_tests.js browser
+```
+
+The default run stays deterministic and does not require an external browser.
+
+## Component Authors
+
+New or modernized components should derive their a11y path from the profile:
+
+- Routing and commands: `Enter`, optional `Space`, active ARIA state.
+- Overlays: initial focus, focus trap, `Escape`, focus restore.
+- Form controls: delegated focus, input events, state/form synchronization.
+- Composite widgets: arrow keys and current ARIA state.
+
+Scaffolded components receive an `xtend.a11y.profile.v1` starting with
+`ER-WP-23`. ER-WP-24 provides the browser-near gate that such profiles can
+later attach to component-by-component.

package/docs/en/about.md

@@ -0,0 +1,25 @@
+# About This Documentation Web App
+
+This web application provides interactive documentation for the XTend Web
+Framework and is built entirely on modern Web Components. It offers a modular,
+fast, and developer-friendly interface for engineers and users.
+
+## Open Source Projects Used
+
+### Parsedown
+
+This application uses **Parsedown** by Emanuil Rusev for Markdown processing.
+
+> (c) Emanuil Rusev  
+> http://erusev.com
+
+### XRouter PHP
+
+Routing and server-side logic are based on a PHP implementation of XRouter,
+developed by **CCS Networks**. The project is now available under the name
+**xrouter.php**.
+
+---
+
+Further information and credits are available in the respective component
+documentation.

package/docs/en/api.md

@@ -0,0 +1,171 @@
+# XTend API
+
+## Overview
+
+`api.js` is the orchestration layer between the loader, core components, and
+global helper APIs. It initializes the XTend APIs idempotently, hardens the
+shared UI state, and loads API-relevant components from the manifest.
+
+## Initialization
+
+The loader imports `api.js` after loading the manifest and then calls
+`initXTendAPI(manifest)`.
+
+```js
+const api = await import('./api.js');
+await api.initXTendAPI(manifest);
+```
+
+## Contract of `initXTendAPI(manifest)`
+
+- initializes `ui` in `xstate` defensively and does not destroy existing UI
+  state on repeated calls
+- provides theme state (`theme`, `themes`) only when it does not already exist
+- loads API-relevant core modules through manifest URLs as ES modules
+- rebinds the global helpers to the `window.XTend` namespace if the API is
+  initialized again
+
+## Global APIs
+
+After successful initialization, these APIs are available:
+
+- `window.XTheme`
+- `window.XToast`
+- `window.XAlert`
+- `window.XDialog`
+- `window.XModal`
+
+The APIs are also mirrored under `window.XTend`:
+
+- `window.XTend.theme`
+- `window.XTend.toast`
+- `window.XTend.alert`
+- `window.XTend.dialog`
+- `window.XTend.modal`
+- `window.XTend.compliance`
+
+Legacy helpers remain available:
+
+- `window.showToast`
+- `window.showAlert`
+- `window.showDialog`
+- `window.showModal`
+
+## Compliance API
+
+`window.XTend.compliance` describes the productive core review contract.
+Available methods:
+
+- `getChecklist()`
+- `getCoreContracts()`
+- `getThemeTokens(themeName?)`
+
+The runtime also mirrors this metadata into `xstate`:
+
+- `xtend.compliance.version`
+- `xtend.compliance.checklist`
+- `xtend.compliance.contracts`
+
+## UI State
+
+The API manages the shared UI state under `xstate.get('ui')`.
+
+```js
+{
+  toasts: [],
+  alerts: [],
+  dialogs: [],
+  modals: []
+}
+```
+
+The API updates this state incrementally. Re-initialization no longer resets
+active UI entries.
+
+## Theme API
+
+`window.XTheme` is the public theme facade. Important methods:
+
+- `getCurrentTheme()`
+- `getAvailableThemes()`
+- `setTheme(themeName)`
+- `set(name, value)`
+- `get(name)`
+- `subscribe(fn)`
+- `registerTheme(name, properties)`
+- `loadExternalTheme(themeName, cssUrl)`
+- `toggleDarkMode()`
+
+`set(name, value)` is the compatibility facade:
+
+- `set('dark')` switches to a theme
+- `set('--primary-color', '#0e4e81')` sets a CSS variable for the current theme
+
+## Dialog and Modal Flags
+
+The API writes open state compatibly for existing call sites:
+
+- Dialog: `dialog-open-<id>`, `xdialog-open-<id>`
+- Modal: `modal-open-<id>`
+
+The canonical target path from the contract matrix remains relevant for new
+work:
+
+- `xtend.component.x-dialog.<id>.open`
+- `xtend.component.x-modal.<id>.open`
+
+## XTendRMT Runtime API
+
+XTendRMT is not part of `api.js`, but the public XTend developer docs include
+the productive integration path. Runtime factories live in artifacts under
+`xtendrmt/`:
+
+- `createRmtFormat`
+- `createRmtXRouterAdapter`
+- `createRmtXtendComponentAdapter`
+- `createRmtStateSchedulerDiagnosticsBridge`
+
+ESM:
+
+```js
+import {
+  createRmtFormat,
+  createRmtXRouterAdapter,
+  createRmtXtendComponentAdapter,
+  createRmtStateSchedulerDiagnosticsBridge
+} from './xtendrmt/rmt-runtime.esm.js';
+```
+
+Browser classic:
+
+```html
+<script src="/xtendrmt/rmt-runtime.browser.js"></script>
+<script type="module">
+  const format = window.AppModules.createRmtFormat();
+  const rmt = window.xtend.rmt;
+</script>
+```
+
+RMT-adjacent XTend integrations should use these factories instead of private
+demo bridges or direct kernel coupling. Details are in
+[XTendRMT Runtime Bridge](./xtendrmt-runtime-bridge.md).
+
+## Notes
+
+- `api.js` is runtime orchestration, not a static component list.
+- The API expects a consistent manifest and already available `xstate`
+  bootstrap infrastructure.
+- Components should still preferably be used declaratively; the API is meant
+  for dynamic flows.
+- After core changes, run `node scripts/verify_xtend_core_contracts.js`.
+
+## Related Topics
+
+- [Manifest Format](./manifest.md)
+- [XTend Loader](./xtend-loader.md)
+- [xrouter](./components/xrouter.md)
+- [xlink](./components/xlink.md)
+- [xtheme](./components/xtheme.md)
+- [Core Migration Guide](./core-migration-guide.md)
+- [XTendRMT Developer Overview](./xtendrmt-overview.md)
+- [XTendRMT Runtime Bridge](./xtendrmt-runtime-bridge.md)

package/docs/en/best-practices.md

@@ -0,0 +1,125 @@
+# Best Practices for XTend
+
+These recommendations help you build XTend projects that are robust,
+performant, and maintainable for human developers and AI coding agents alike.
+
+---
+
+## Component Usage
+
+- **Prefer declarative usage:** Use XTend components directly in HTML whenever
+  possible, not only dynamically through JavaScript.
+- **Lazy loading:** Build pages so components load only when needed
+  (viewport, user interaction).
+- **Shadow DOM:** Use Shadow DOM for style encapsulation and conflict
+  prevention.
+- **Slots and attributes:** Use slots and attributes for flexible, reusable
+  components.
+
+---
+
+## State Management
+
+- **Use xstate:** Share global and local state through the central state
+  management module.
+- **Subscriptions:** React to state changes with `xstate.subscribe` instead of
+  expensive DOM queries.
+
+---
+
+## Theming and Styling
+
+- **CSS custom properties:** Use variables for colors, spacing, and similar
+  values so design stays flexible.
+- **Use xtheme:** Apply global styles and theme changes centrally through the
+  theme module.
+- **Dark/light mode:** Support both modes and respect system preferences.
+
+---
+
+## Accessibility
+
+- **ARIA roles:** Use meaningful ARIA attributes and roles.
+- **Keyboard navigation:** Ensure every interactive component is operable by
+  keyboard.
+- **Focus management:** Dialogs, modals, and menus should place and restore
+  focus correctly.
+
+---
+
+## Performance
+
+- **Minimized manifest:** Remove unused components from the manifest for
+  production builds.
+- **Small bundles:** Keep components modular and small to optimize load time.
+- **IntersectionObserver:** Use lazy loading for large or rarely used
+  components.
+
+---
+
+## Development and Maintenance
+
+- **Documentation:** Every component should have its own current Markdown
+  documentation.
+- **Naming conventions:** Keep the `x` prefix and use descriptive names.
+- **Testing:** Test components in isolation and together.
+- **Cross references:** Maintain cross-links in the docs for better orientation.
+
+---
+
+## Testing Requirement for New Components
+
+- **Choose a profile:** Assign every new or modernized component to a profile
+  from `development/XTend-Component-Level-Teststandard.md`.
+- **Keep artifacts complete:** Component, docs, component suite, fixture, type
+  definition, and manifest entry are required unless an exception is explicitly
+  justified.
+- **Use scaffold as the default path:** `XTend-Scaffold` must use the testing
+  requirement from `development/XTend-Testpflicht-und-Scaffold-Anschluss.md` as
+  its blueprint.
+- **Run local gates:** Use at least `node scripts/run_xtend_tests.js components`,
+  `a11y-hydration`, `references`, and for RMT-compatible scaffold artifacts
+  `rmt-compatibility`; when core behavior is involved, also run `core`,
+  `architecture`, and `browser`.
+- **No placeholder tests:** Test files without real assertions do not satisfy
+  the testing requirement.
+
+## XTendRMT-Compatible Development
+
+- **Prefer native domains:** New RMT-adjacent work uses `adapters`,
+  `components`, `routes`, `schedules`, and `templates` instead of operational
+  `manifest.metadata` blocks.
+- **Keep the kernel boundary:** XTend, XRouter, DOM, `window.XTend`, and
+  `xstate` belong in adapters or host code, not in the RMT kernel.
+- **Use productive factories:** Use `createRmtXRouterAdapter`,
+  `createRmtXtendComponentAdapter`, and
+  `createRmtStateSchedulerDiagnosticsBridge` instead of private demo bridge
+  logic.
+- **Check multi-host behavior:** XTend is a first-class host, but not a required
+  host. A non-XTend path such as `vanilla.component` should be considered for
+  framework-adjacent changes.
+- **Respect Trusted DOM:** RMT `dom_descriptor` is preferred. RMT
+  `html_fragment` and Parsedown HTML need
+  `xtend.security.sanitizing-boundary.v1`; raw `innerHTML` sinks do not belong
+  in components or adapters.
+- **Respect the Docs App:** The official docs use Parsedown as parser host, but
+  render their shell shell-first through RMT. New docs convenience features
+  should use `docs/xtendrmt-parsedown-scheduling.md`, `docs.app.shell`, and the
+  existing RMT schedules instead of building a second SPA layer next to the host
+  adapter.
+- **Run gates:** For RMT-adjacent changes, run at least
+  `node scripts/run_xtend_tests.js rmt-compatibility --json`,
+  `node scripts/run_xtend_tests.js references --json`, and, for browser paths,
+  `node scripts/run_xtend_tests.js browser --json`.
+
+---
+
+## AI Optimization
+
+- **Consistent API:** Keep methods and attributes consistent and descriptive.
+- **Example code:** Add concrete code examples to every doc.
+- **Semantic structure:** Use clear headings, tables, and lists for AI parsing.
+
+---
+
+*Last updated: May 5, 2026*