@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/components/xutils.md

@@ -0,0 +1,161 @@
+# xutils - XTend Utility Module
+
+## Overview
+
+`x-utils` is a manifest-managed utility module, not its own Custom Element
+surface. The module exports `XUtils` and additionally exposes `window.XUtils`
+in the browser. It collects small DOM, event, a11y, format, and low-code
+helpers for XTend components and demos.
+
+## Import
+
+```js
+import { XUtils } from './components/xutils.js';
+
+const button = XUtils.create('button', {
+  textContent: 'Save'
+});
+```
+
+In the browser, after loading the module:
+
+```js
+window.XUtils.find('[data-action="save"]');
+```
+
+## DOM and Event API
+
+| Method | Description |
+|--------|-------------|
+| `find(selector, root?)` | returns the first matching element |
+| `findAll(selector, root?)` | returns all matching elements as an array |
+| `create(tag, props?)` | creates an element and assigns properties |
+| `on(el, type, handler, opts?)` | registers a listener and returns a cleanup function |
+| `delegate(root, selector, type, handler)` | delegates events within a container |
+
+## A11y and UI Helpers
+
+| Method | Description |
+|--------|-------------|
+| `setAria(el, attrs)` | sets `aria-*` attributes from an object |
+| `focusTrap(container)` | focuses the first focusable element in the container |
+| `fadeIn(el, duration?)` | simple opacity animation |
+| `fadeOut(el, duration?)` | simple opacity animation |
+| `resolveUiEffects(input?)` | normalizes opt-in UI effects from body attribute, loader option, or RMT |
+| `prepareUiEffects(input?)` | prepares an opt-in UI effect, for example body fade |
+| `releaseUiEffects(input?)` | releases a prepared UI effect |
+| `isMobile()` | checks the local mobile breakpoint |
+
+## Format and Data Helpers
+
+| Method | Description |
+|--------|-------------|
+| `hexToRgb(hex)` | converts hex colors to RGB values |
+| `contrastColor(hex)` | returns black or white as contrast color |
+| `formatDate(date, locale?)` | formats a date |
+| `formatNumber(num, locale?)` | formats a number |
+| `uniqueId(prefix?)` | creates a simple runtime ID |
+| `deepClone(obj)` | creates a JSON-based copy |
+
+## XTemplate Recipes
+
+`XUtils.XTemplate` contains small low-code recipes for simple DOM fragments:
+
+```js
+const card = XUtils.XTemplate.card({
+  title: 'Status',
+  content: 'All systems ready'
+});
+
+const action = XUtils.XTemplate.button({
+  label: 'Refresh',
+  onClick: () => window.location.reload()
+});
+```
+
+Current recipes:
+
+| Recipe | Description |
+|--------|-------------|
+| `card(opts)` | creates a simple card structure |
+| `button(opts)` | creates a button |
+| `modal(opts)` | creates a simple modal structure |
+
+## Contract
+
+- `x-utils` exists as a manifest entry, but remains a utility module.
+- It does not register `customElements.define()`.
+- `docs/components/xutils.md` is the canonical docs slug for the source
+  basename `xutils.js`.
+- Runtime tag and manifest key remain `x-utils` for the Catalog Matrix.
+
+## Utility Boundary Contract
+
+Since `WP-E12-09`, `x-utils` is gateable as a non-visual utility boundary:
+
+- Utility Schema: `xtend.utility.module-contract.v1`
+- Import Policy Schema: `xtend.utility.import-policy.v1`
+- Import Policy Result Schema: `xtend.utility.import-policy-result.v1`
+- Boundary Probe Schema: `xtend.utility.boundary-probe.v1`
+- Kernel Boundary: `no-rmt-kernel-import-of-xtend-types`
+
+The runtime provides three explicit contract APIs:
+
+| Method | Description |
+|--------|-------------|
+| `getUtilityContract()` | returns categories, exports, globals, and methods of the utility surface |
+| `snapshotUtilityContract()` | returns a stable boundary snapshot for fixtures and catalog gates |
+| `assertLocalImport(specifier)` | checks whether an import specifier is local and policy-compliant |
+
+```js
+const local = XUtils.assertLocalImport('/components/xbutton.js');
+const blocked = XUtils.assertLocalImport('https://cdn.ccs-networks.de/xtend/components/xstate.js');
+
+console.log(local.allowed);   // true
+console.log(blocked.allowed); // false
+```
+
+`assertLocalImport()` also dispatches `xutils:import-policy-check` in the
+browser. The event is intended for test, Fabric, and security harnesses; the
+RMT kernel still does not import `x-utils`.
+
+## UI Effects Boundary
+
+Since `xtend.utility.ui-effects.v1`, `x-utils` encapsulates opt-in effects that
+can influence the app shell. The global loader no longer hides the body by
+default. Fade-in must be explicitly enabled:
+
+```html
+<body xt-ui-effects="fade-in">
+```
+
+RMT hosts can describe the same effect as a non-visual intent:
+
+```json
+{
+  "id": "app.ui-effects",
+  "kind": "ui_effects",
+  "tag": "ui-effects",
+  "props": {
+    "effect": "fade-in"
+  }
+}
+```
+
+The host side remains the place of execution. RMT describes only the intent;
+`XUtils.prepareUiEffects()` and `XUtils.releaseUiEffects()` set the DOM
+attributes `data-xt-ui-effects`, `data-xt-ui-effects-state`, and
+`data-xt-ui-effects-ready`. For environments without RMT, the body attribute is
+enough. For shell-first apps that want no effect, no attribute is needed, or
+`xt-ui-effects="none"` can be set explicitly.
+
+## Notes
+
+- New components should prefer their own component APIs and XTend-Fabric gates
+  for productive UI contracts.
+- `x-utils` remains a small helper-module path for existing code, demos, and
+  simple DOM work.
+- Suite, fixture, and utility typing have existed since `WP-E12-09`.
+- Since `WP-E13-05`, `x-utils` is classified as `closed-as-utility-boundary`.
+  A separate visual performance profile is not an open RC1 task for this
+  utility boundary.

package/docs/en/components/xwriter.md

@@ -0,0 +1,106 @@
+# xwriter - XTend Component
+
+> **See also:** [xcode](./xcode.md), [xinput](./xinput.md)
+
+## Overview
+
+`<x-writer>` is a component for rich-text editing and simple WYSIWYG editors.
+It supports formatting, theming, state integration, autosave, export, and API
+integration.
+
+---
+
+## Features
+
+- Rich-text editing (bold, italic, lists, links, colors, sizes)
+- State integration through xstate
+- Theming through CSS custom properties
+- Autosave (local or API)
+- Export as Markdown/HTML
+- Drag and drop for images/text
+- API integration (save to server)
+
+---
+
+## Usage
+
+```html
+<x-writer></x-writer>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `value` | String | initial text content (property, not attribute) |
+| `api` | String | API endpoint for saving, for example `/api/save` or `local` for LocalStorage |
+| `method` | String | HTTP method for API (default: `POST`) |
+| `autosave` | Number | autosave interval in ms, for example `10000` for 10s |
+| `storage-key` | String | key for LocalStorage (default: `xwriter-content`) |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `writer:change` | emitted on text change, detail: `{html, markdown, plain}` |
+| `writer:save` | after save (local/API), detail: `{status, response}` |
+| `writer:autosave` | after autosave |
+| `writer:export` | after export, detail: `{filename, success}` |
+| `writer:error` | on errors, detail: `{error}` |
+
+---
+
+## API
+
+- **Set/read text:** `element.value = 'Text'` (property, not attribute)
+- **State integration:** automatic through xstate
+- **Save:**
+  - Local: `<x-writer api="local"></x-writer>`
+  - API: `<x-writer api="/api/save" method="POST"></x-writer>`
+- **Export:** through export button (Markdown/HTML)
+
+## Form Controls UX from WP-E11-08
+
+`<x-writer>` exposes `xtendFormControlUxProfile` with
+`xtend.component.form-control-ux-profile.v1`. The profile describes rich text
+as a form-control-adjacent UX surface with `writer:change`, `writer:error`,
+`xwriter-content`, `component.idle.hydrate`, Fabric lane `idle`, and RMT shell
+authoring. `x-form` can consume `writer:change` and aggregate the value into
+`xform-data-<id>`.
+
+---
+
+## Example: Dynamic JS
+
+```js
+const writer = document.createElement('x-writer');
+writer.value = 'Hello world!';
+document.body.appendChild(writer);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-writer {
+  --writer-bg: #fff;
+  --writer-color: #222;
+  /* See CSS for more custom properties */
+}
+```
+
+---
+
+## Accessibility
+
+- Semantic HTML, ARIA
+- Keyboard operation
+
+---
+
+*Last updated: July 16, 2025*

package/docs/en/components.md

@@ -0,0 +1,151 @@
+# Component Development with XTend
+
+XTend components are reusable Web Components. In RMT-first apps they are not
+the app architecture itself: RMT describes the shell, state, actions, events,
+surfaces, and scheduling; XTend Components materialize the visible UI.
+
+See also [x-router](./components/xrouter.md), [x-link](./components/xlink.md),
+and the [RMT vNext Authoring Guide](./rmt-vnext-authoring.md).
+
+## Core Principles
+
+- Every visual component is an ES module and is loaded through the manifest.
+- The manifest key is the canonical runtime and catalog name.
+- For Custom Elements, the tag name matches the manifest key, for example
+  `x-button`, `x-input`, `x-summary`.
+- Existing source files follow the module basename without the hyphen, for
+  example `xbutton.js` for `x-button`.
+- Components remain independent, configurable, and host-neutral.
+- RMT can reference, mount, hydrate, and connect components to events, but it
+  does not import them into the kernel.
+
+## Role in RMT-Authored Apps
+
+| Layer | Responsibility |
+| --- | --- |
+| RMT vNext | describes app shell, surfaces, state, actions, events, and lanes |
+| XTend Component | renders UI and encapsulates Shadow DOM, attributes, properties, and events |
+| Host Adapter | connects RMT records to real Custom Elements and browser DOM |
+| Fabric | runs hydration, render, user-blocking, and idle work as fibers |
+
+An RMT surface can, for example, declare `component x-cards`. The host adapter
+loads `x-cards` through the manifest, mounts the Custom Element, and wires event
+payloads into RMT actions.
+
+The RMT vNext Component Capability Registry makes this adapter path generic. It
+reads the manifest, Component Contracts, `xtendRmtMetadata`,
+`observedAttributes`, events, slots, parts, form association, accessibility
+profiles, and performance profiles, then exposes capabilities for every public
+manifest component. New components remain normal Web Components; RMT
+compatibility depends on stable public contracts instead of host monkeypatching.
+
+## Component Structure
+
+A typical component contains:
+
+- a class that extends `HTMLElement` or a local base class
+- Shadow DOM or controlled Light DOM
+- styles through CSS custom properties, parts, or local Shadow DOM rules
+- attributes and properties for configuration
+- custom events for communication
+- registration through `customElements.define(...)`
+
+### Minimal Example
+
+```js
+class XButton extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.shadowRoot.innerHTML = `
+      <button part="button"><slot></slot></button>
+      <style>
+        :host { display: inline-flex; }
+        button { padding: 0.5rem 0.75rem; }
+      </style>
+    `;
+  }
+}
+
+customElements.define('x-button', XButton);
+```
+
+## Naming Rules
+
+| Layer | Rule | Example |
+| --- | --- | --- |
+| Manifest key | canonical runtime and catalog name | `x-summary` |
+| Custom Element tag | identical to the manifest key | `<x-summary>` |
+| Source file | module basename from the manifest path | `xsummary.js` |
+| Component docs | source basename plus `.md` | `docs/components/xsummary.md` |
+| Docs menu slug | `components-` plus source basename | `components-xsummary` |
+
+Exceptions stay intentionally small: `xstate` is a platform state module,
+`x-utils` is a utility module without a Custom Element, and `x-theme` provides
+the theme facade.
+
+## Best Practices
+
+- Use Shadow DOM, parts, and CSS custom properties for encapsulation and
+  theming.
+- Keep attributes, properties, and events stable and documented.
+- Dispatch events with clear `detail` payloads so RMT actions can consume them
+  safely.
+- Avoid global DOM assumptions in components; app structure belongs in RMT.
+- Use `x-icon` for local icons, icon packs, and controlled URL sources.
+- Plan hydration deliberately: visible UI belongs in visible lanes, less urgent
+  work belongs in idle or lazy paths.
+
+## Example with Attribute and Event
+
+```js
+class XCounterButton extends HTMLElement {
+  static get observedAttributes() {
+    return ['value'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.shadowRoot.innerHTML = `
+      <button part="button" type="button"></button>
+    `;
+    this.shadowRoot.querySelector('button').addEventListener('click', () => {
+      const value = Number(this.getAttribute('value') || 0) + 1;
+      this.setAttribute('value', String(value));
+      this.dispatchEvent(new CustomEvent('counter-change', {
+        bubbles: true,
+        detail: { value }
+      }));
+    });
+  }
+
+  attributeChangedCallback() {
+    const button = this.shadowRoot && this.shadowRoot.querySelector('button');
+    if (button) button.textContent = `Counter ${this.getAttribute('value') || 0}`;
+  }
+}
+
+customElements.define('x-counter-button', XCounterButton);
+```
+
+In RMT, this event can be bound to an action as
+`on counter-change -> action ...`.
+
+## Testing and Debugging
+
+- Components can be tested directly in HTML.
+- Use `xtend-loader.js` and the local dev server for manual tests.
+- Use RMT surfaces when you want to test component behavior in the app
+  lifecycle.
+- For API and typing questions, see [Public Component Types](./public-component-types.md).
+
+## Related Topics
+
+- [Manifest Format](./manifest.md)
+- [XTend Loader](./xtend-loader.md)
+- [RMT vNext Authoring Guide](./rmt-vnext-authoring.md)
+- [RMT vNext Component Primitives and XTend UI](./rmt-vnext-component-primitives.md)
+- [Component Platform](./component-platform.md)
+- [Component UX Authoring](./component-ux-authoring.md)
+- [API Integration](./api.md)

package/docs/en/conditional-network-evidence-ci.md

@@ -0,0 +1,38 @@
+# Conditional Network Evidence CI
+
+Contract: `xtend.epic13.conditional-network-evidence-ci.v1`
+
+Status: `accepted-conditional-network-evidence-ci`
+
+Workpackage: `DPF-WP-03-conditional-network-evidence-ci`
+
+## Goal
+
+This package productizes audit and SBOM evidence for CI and release owners. The local gate remains network-free; the CI job can run `npm audit --audit-level=moderate` and `npm sbom --sbom-format=cyclonedx --json`, or write an owner deferral in the `xtend.epic13.conditional-network-deferral.v1` format when network access is unavailable.
+
+## Local Gate
+
+```bash
+node scripts/run_xtend_tests.js epic13-conditional-network-evidence-ci --json
+npm run test:epic13-conditional-network-evidence-ci
+```
+
+## Capture
+
+```bash
+npm run conditional-network:evidence
+```
+
+Without `XTEND_CONDITIONAL_NETWORK_EXECUTE=1`, the capture writes local deferral artifacts. In CI, `.github/workflows/xtend-default-gates.yml` sets `XTEND_CONDITIONAL_NETWORK_EXECUTE=1`, installs workspace links via `npm ci --ignore-scripts --no-audit --fund=false`, uses `XTEND_CONDITIONAL_NETWORK_USE_NPX_NPM10=1` for stable SBOM output and uploads the artifacts:
+
+- `.xtend-test-results/xtend-npm-audit-report.json`
+- `.xtend-test-results/xtend-npm-sbom.json`
+- `.xtend-test-results/xtend-conditional-network-evidence-report.json`
+
+## Boundaries
+
+Dependency upgrades, vulnerability fixes and public publish are not included. Publish remains blocked by `private-until-release-owner-acceptance` until audit/SBOM has been executed or accepted as deferred by the owner.
+
+The separate GitHub Actions job `npm-publish-next` runs through `workflow_dispatch` with `publish_to_npm=true` or after `release: published` and allows no deferrals: it sets `XTEND_CONDITIONAL_NETWORK_ALLOW_DEFERRAL=0`, repeats `release:report`, pack and audit/SBOM evidence, and then runs `npm publish --tag next --provenance --access public`.
+
+The next step is `DPF-WP-04-visual-pixel-evidence-storage`.

package/docs/en/conditional-network-evidence.md

@@ -0,0 +1,50 @@
+# Conditional Network Evidence
+
+`xtend.epic13.conditional-network-evidence.v1` describes how RC1 handles network gates without blocking local development.
+
+Local gate:
+
+```bash
+node scripts/run_xtend_tests.js epic13-conditional-network-evidence --json
+```
+
+or:
+
+```bash
+npm run test:epic13-conditional-network-evidence
+```
+
+## Commands
+
+| Command | Artifact |
+|---------|----------|
+| `npm audit --audit-level=moderate` | `.xtend-test-results/xtend-npm-audit-report.json` |
+| `npm sbom --sbom-format=cyclonedx --json` | `.xtend-test-results/xtend-npm-sbom.json` |
+
+The aggregated report is stored at `.xtend-test-results/xtend-conditional-network-evidence-report.json`.
+
+## Local Behavior
+
+The local gate does not automatically execute the network commands. Instead, it verifies that XTend has a stable evidence/deferral format for offline, sandbox and CI environments.
+
+As of `DPF-WP-03`, [Conditional Network Evidence CI](./conditional-network-evidence-ci.md) productizes the CI job and capture command `npm run conditional-network:evidence` under `xtend.epic13.conditional-network-evidence-ci.v1`. The job can execute the audit/SBOM commands or place owner deferrals in the same artifact paths.
+
+Default reason for local deferrals:
+
+```text
+network-restricted-local-default
+```
+
+Other allowed reasons:
+
+- `sandbox-network-unavailable`
+- `registry-auth-unavailable`
+- `owner-approved-offline-run`
+
+## Publish Boundary
+
+`private-until-release-owner-acceptance` remains active. Deferred network evidence is a review signal, but not a publish approval.
+
+`WP-E13-04` is complete. [Package Export Lock](./package-export-lock.md) describes how `npm run pack:dry-run` and the export surface are locked for RC1. `WP-E13-05` is complete; `WP-E13-06` completed the [Hydration Performance Closure](./hydration-performance-closure.md). `WP-E13-07` prepared the [PROD Browser CSP Smokes](./prod-browser-csp-smokes.md). `WP-E13-08` normalized [Visual Owner Artifacts](./visual-owner-artifacts.md). `WP-E13-09` can now start.
+
+Further reading: [Release Owner Acceptance](./release-owner-acceptance.md).

package/docs/en/core-migration-guide.md

@@ -0,0 +1,110 @@
+# XTend Core Migration Guide
+
+## Overview
+
+This guide summarizes the production Core standards from Epic 01. It serves as a migration aid for legacy call sites and as a reference for new XTend Core changes.
+
+## Verification
+
+The current Core contract can be verified automatically:
+
+```bash
+node scripts/verify_xtend_core_contracts.js
+```
+
+## Runtime Standards
+
+- `window.XTend.compliance` provides the checklist, contract overview and theme tokens.
+- central design tokens are registered per theme through `xtheme` and mirrored onto `document.documentElement`.
+- overlay and feedback components respect `prefers-reduced-motion`, focus standards and canonical XTend state keys.
+
+## RMT Templating Migration Starting with Epic 04
+
+RMT templating is additive and opt-in. Existing XTend apps, classic HTML/JS integrations and existing Web Component usage remain valid. An app only uses XTendRMT when it deliberately registers an `.rmt` document, an RMT root handshake, a template record or a host adapter.
+
+The binding migration note is in `development/XTendRMT-Migrations-und-Framework-Agnostik-Leitplanken.md`.
+The current product overview is in `docs/xtendrmt-overview.md`. The production native authoring model starting with Epic 05 is in `docs/xtendrmt-native-authoring.md`; the App DSL reference is in `docs/xtendrmt-app-dsl.md`; Runtime Bridge and adapters are described in `docs/xtendrmt-runtime-bridge.md`. The migration from metadata paths to top-level domains is in `docs/xtendrmt-migration-guide.md`.
+
+| Starting Point | Migration Path |
+|----------------|----------------|
+| XTend-only app | keep running unchanged; activate RMT only for new roots or template pilots |
+| XTend with XRouter | prepare route records, production adapter execution in Epic 05 |
+| XTend next to React/Vue | use RMT as scheduler or template transport, keep host adapters separate |
+| Vanilla or custom host | declare custom scheduler endpoints, assume no XTend capabilities |
+| Legacy demo | classify and verify, do not silently turn it into the RMT product contract |
+
+Review rules for RMT-compatible changes:
+
+- no XTend runtime imports in the RMT kernel
+- no forced migration for existing apps
+- no new XTend template language beside RMT
+- `kernelVisible: false` for XTend-specific adapter data
+- use production bridge factories instead of private demo bridge logic
+- historical scaffold artifacts with `bridgeRuntime: reserved-for-Epic-05` remain readable as the Epic 04 handoff, but are no longer the operative bridge status
+- `node scripts/run_xtend_tests.js rmt-compatibility --json` and `node scripts/run_xtend_tests.js references --json` as minimum gates
+
+## Native RMT Routes and Components Starting with Epic 05
+
+New App DSL documents should keep operative routing, component and scheduling data in native top-level domains:
+
+- `manifest.metadata.routes -> routes`
+- `manifest.metadata.components -> components`
+- `manifest.metadata.schedules -> schedules`
+- `xtend.xrouter` remains the router adapter
+- `xtend.component` remains the component adapter
+- `rmt.state-scheduler-diagnostics` remains the bridge adapter
+
+`manifest.metadata` remains valid for description, handoff and historical demo notes, but should not carry new operative route or component bridges. Template-only documents remain compatible.
+
+Production execution uses:
+
+- `createRmtFormat().normalizeDocument(...)`
+- `createRmtFormat().createRuntimeRegistries(...)`
+- `createRmtXRouterAdapter(...)`
+- `createRmtXtendComponentAdapter(...)`
+- `createRmtStateSchedulerDiagnosticsBridge(...)`
+
+The Docs App itself remains Parsedown-based, but now renders its app shell shell-first from RMT. The scheduling and shell path has been described as the official pilot since `ER-WP-40` in `docs/xtendrmt-parsedown-scheduling.md` and `docs/xtendrmt-parsedown-docs.rmt`.
+
+## Legacy to Canonical
+
+| Area | Legacy | Canonical | Status |
+|------|--------|-----------|--------|
+| Dialog Open | `dialog-open-<id>` | `xtend.component.x-dialog.<id>.open` | Legacy remains compatible |
+| Dialog Open | `xdialog-open-<id>` | `xtend.component.x-dialog.<id>.open` | Legacy remains compatible |
+| Modal Open | `modal-open-<id>` | `xtend.component.x-modal.<id>.open` | Legacy remains compatible |
+| Theme Current | `theme` | `xtend.theme.current` | both are mirrored |
+| Theme List | `themes` | `xtend.theme.available` | both are mirrored |
+| Router Last Navigation | `router-navigated` | `xtend.router.lastNavigated` | both are mirrored |
+| Alert State | `xalert-state-<id>` | `xtend.component.x-alert.<id>` | Legacy remains compatible |
+
+## What New Core Changes Must Consider
+
+- new UI flows need an explicit `xstate` twin
+- docs, API, type definitions and runtime must use the same contract
+- new components or larger Core changes must run against the compliance checklist and the verification script
+
+## Design Tokens
+
+The central tokens come from `xtheme` and can be adjusted per theme:
+
+- `--xtend-color-primary`
+- `--xtend-color-primary-dark`
+- `--xtend-color-accent`
+- `--xtend-glass-bg`
+- `--xtend-glass-blur`
+- `--xtend-shadow`
+- `--xtend-border`
+- `--xtend-radius`
+- `--xtend-font-family`
+- `--xtend-focus-outline`
+- `--xtend-surface`
+- `--xtend-surface-muted`
+- `--xtend-text`
+- `--xtend-overlay-bg`
+
+## Notes for Existing Integrations
+
+- Existing legacy open flags for dialog and modal do not have to be removed immediately, but should no longer be introduced in new code.
+- New API-near integrations should prefer `window.XTend.*` over unnamespaced helpers.
+- For Core reviews, the checklist in `development/XTend-Core-Compliance-Checklist.md` is the operative source.