@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/de/xtend-loader.md

@@ -0,0 +1,265 @@
+# XTend Loader
+
+## Uebersicht
+
+Der kanonische XTend Loader ist `xtend-loader.js`.
+
+Er ist ein lokaler ES-Modul-Entry fuer XTend UI und uebernimmt das dynamische Laden von Manifest, Core-Modulen, explizit vorgeladenen Komponenten, DOM-verwendeten Komponenten und `api.js`.
+
+`xtend-dev.js` ist nur noch ein Legacy-Stub. Neue Demos, Browser-Smokes, Scaffold-Ausgaben und offizielle Beispiele verwenden `xtend-loader.js`.
+
+Seit `ER-WP-05` sind die Default-Demo- und Fixture-Pfade formal auf den kanonischen Loader beziehungsweise bewusst klassifizierte Spezial-Smokes festgelegt. Seit `ER-WP-18` misst der Loader Manifest Load, Modul-Load und Custom Element Definition ueber lokale Performance Marks. Seit `ER-WP-28` validiert er Manifest- und Modul-URLs gegen `xtend.security.loader-policy.v1`, `xtend.security.manifest-policy.v1` und `xtend.security.import-policy.v1`.
+
+## Einbindung
+
+```html
+<script type="module" src="./xtend-loader.js"></script>
+```
+
+Optional kann ein lokales Manifest gesetzt werden:
+
+```html
+<script
+  type="module"
+  src="./xtend-loader.js"
+  data-manifest="./components/manifest.json">
+</script>
+```
+
+Der Loader nutzt standardmaessig:
+
+```text
+components/manifest.json
+```
+
+## Contract
+
+Der Loader Contract lautet:
+
+```text
+xtend.loader.contract.v1
+```
+
+Security Contracts:
+
+```text
+xtend.security.loader-policy.v1
+xtend.security.manifest-policy.v1
+xtend.security.import-policy.v1
+```
+
+Browsernah stellt der Loader diese Oberflaeche bereit:
+
+```js
+window.XTendLoader
+```
+
+Die automatische Boot-Promise liegt unter:
+
+```js
+window.__XTendLoaderBootPromise
+```
+
+## Verbose Mode
+
+Der PROD-Loader ist standardmaessig konsolenruhig. Die Loader-Datei enthaelt dafuer oben eine direkte Flag:
+
+```js
+const verbose_mode = 'auto';
+```
+
+Unterstuetzte Werte:
+
+| Wert | Verhalten |
+|------|-----------|
+| `'true'` | Verbose ist dauerhaft aktiv. Loader-Modulvorgaenge und angeschlossene Core-Runtime-Logs werden in der Browserkonsole ausgegeben. |
+| `'false'` | Verbose ist gesperrt. Es kann nur durch eine Aenderung der Loader-Datei wieder aktiviert werden. |
+| `'auto'` | Verbose ist beim ersten Start aus und kann in der Browserkonsole fuer die laufende Tab-Session aktiviert werden. |
+
+Browser-Konsole:
+
+```js
+XTendLoader.verbose(true)
+XTendLoader.verbose(false)
+XTendLoader.verbose()
+```
+
+Alternativ:
+
+```js
+XTendLoader.enableVerbose()
+XTendLoader.disableVerbose()
+XTendLoader.getVerboseState()
+```
+
+In `auto` speichert der Loader die Konsolenentscheidung in `sessionStorage`. Nach `XTendLoader.verbose(true)` reicht ein Reload, um auch die initialen Modul-Ladevorgaenge derselben Browser-Session zu sehen. `XTendLoader.verbose(false)` schaltet die Session wieder ruhig.
+
+Structured Diagnostics (`xtend-loader-diagnostic`) und Performance Events (`xtend-loader-performance`) bleiben vom Verbose Mode unabhaengig verfuegbar.
+
+## Funktionsweise
+
+1. Der Loader initialisiert `xtend.loader.style-registry.v1` und injiziert Runtime-Critical Styles fuer Tokens, UI-Effects, Skeletons und undefinierte XTend Custom Elements.
+2. Er wartet auf den Window-Load.
+3. Er validiert `data-manifest` oder `components/manifest.json` gegen die Loader Policy.
+4. Er laedt das Manifest und loest Manifest-URLs relativ zur Manifest-URL auf.
+5. Er validiert jeden Manifest Record gegen die Manifest- und Import-Policy.
+6. Er kann Modul-URLs ueber `data-module-cache-bust` versionieren, damit Livesysteme keine stale Component-Module aus dem Browsercache ziehen.
+7. Er laedt `xstate` und danach `x-theme`, sofern beide im Manifest stehen. `xstate` wird bewusst nicht cache-gebustet, damit keine zweite State-Modulinstanz entsteht.
+8. Er laedt Eintraege aus `<meta name="xtend-preload">`.
+9. Er erkennt im DOM verwendete XTend-Tags und laedt sichtbare Komponenten sofort.
+10. Er beobachtet nicht sichtbare Komponenten per `IntersectionObserver`.
+11. Er stellt `xtend.loader.skeleton-loader.v1` fuer Shell-, Route- und dynamische Subtree-Fallbacks bereit.
+12. Er validiert und importiert lokal `api.js`, dann ruft er `api.initXTendAPI(manifest)` auf.
+
+## StyleRegistry
+
+Der Loader exportiert die native StyleRegistry:
+
+```js
+window.XTendStyleRegistry
+window.XTendLoader.styles
+```
+
+Beim Auswerten von `xtend-loader.js` ruft der Loader `ensureRuntimeStyles()` sofort auf. Dadurch sind die kritischen CSS-Regeln vorhanden, bevor Komponenten importiert oder hydriert werden. `xtend.css` bleibt der kanonische Standard-Dateiname fuer Host-Theming und Docs-/App-Layout, ist aber keine harte Voraussetzung mehr fuer Skeletons, UI-Effects, Basis-Tokens oder den FOUC-Schutz undefinierter XTend Custom Elements.
+
+Hosts koennen den Theme-Status auslesen:
+
+```js
+XTendLoader.getThemeStylesheetState()
+```
+
+Komponenten koennen eigene Styles registrieren und auf Shadow Roots anwenden:
+
+```js
+const style = XTendLoader.defineComponentStyle('x-example', ':host { display: block; }');
+XTendLoader.adoptStyle(this.shadowRoot, style);
+```
+
+## SkeletonLoader
+
+Der Loader exportiert einen nativen SkeletonLoader fuer Shell-first Apps:
+
+```js
+window.XTendLoader.showSkeleton(target, { lines: 8, schedule: 'docs.page.hydrate' });
+window.XTendLoader.hideSkeleton(target);
+```
+
+Hosts koennen noch nicht definierte XTend Custom Elements ueber `data-xtend-skeleton` als Skeleton anzeigen. Bekannte XTend-Tags ohne Skeleton-Opt-in bleiben bis zur Definition unsichtbar, damit Light-DOM-Text nicht ungestylt aufblitzt. Diese Regeln kommen aus der StyleRegistry und funktionieren auch ohne externes `xtend.css`.
+
+## Preload
+
+Komponenten koennen weiterhin explizit vorgeladen werden:
+
+```html
+<meta name="xtend-preload" content="x-router,x-link,x-dialog,x-modal">
+```
+
+Die Werte sind Component IDs aus dem Manifest, keine freien URLs.
+
+## Live-Deployment Cache Busting
+
+Shell-Apps koennen Loader, Manifest und Component-Module versioniert laden:
+
+```html
+<script
+  type="module"
+  src="/xtend-loader.js?v=20260507"
+  data-manifest="/components/manifest.json?v=20260507"
+  data-module-cache-bust="20260507">
+</script>
+```
+
+Der Loader haengt diesen Wert als `xtend-cache` Query-Parameter an Manifest-Module an. `xstate` bleibt davon ausgenommen, weil Komponenten es selbst ueber `./xstate.js` importieren und XTend genau eine State-Instanz behalten soll.
+
+## Manifest-Beispiel
+
+```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-Strategie
+
+`xtend-dev.js` bleibt fuer eine kurze Migrationsphase als Kompatibilitaetsstub erhalten.
+
+Der Stub:
+
+- warnt in der Konsole
+- importiert `./xtend-loader.js`
+- enthaelt keine eigene Loader-Logik mehr
+
+Default-Demos und Tests duerfen den Legacy-Namen nicht mehr als kanonischen Loaderpfad verwenden.
+
+## Security- und Runtime-Grenzen
+
+Der Loader bleibt lokal und ESM-basiert.
+
+CDN ist kein Default- oder Testpfad. Seit `ER-WP-03` nutzen `api.js`, `components/manifest.json`, Core-Komponenten und Browser-Fixtures repo-lokale XTend-Pfade. Seit `ER-WP-05` pruefen Reference- und Browser-Gates zudem, dass Default-Demos nicht auf `xtend-dev.js` oder XTend-CDN-Bruecken zurueckfallen. Seit `ER-WP-28` verweigert der Loader externe Manifest- und Modul-URLs, `javascript:`, `data:`, `blob:`, nicht passende Dateiendungen und Path-Traversal mit strukturierten Security-Diagnostics.
+
+Der Loader emittiert strukturierte lokale Diagnostics als `xtend-loader-diagnostic` Event und bereitet damit die spaetere Anbindung an `XTend-Fabric` vor.
+
+Security Refusals nutzen diese Codes:
+
+- `xtend.security.loader.refused`
+- `xtend.security.manifest.invalid`
+- `xtend.security.import.refused`
+
+## Performance Measurements
+
+Der Loader erzeugt `performance.mark` und `performance.measure` Eintraege fuer:
+
+| Measure | Phase |
+|---------|-------|
+| `xtend.loader.manifest` | `load` |
+| `xtend.loader.module` | `load` |
+| `xtend.component.define` | `define` |
+
+`xtend.component.define` wartet nach dem Modul-Load kurz auf `customElements.whenDefined(tag)`, blockiert den Loader aber nicht dauerhaft, falls ein Manifest-Eintrag kein Custom Element registriert.
+
+Zusaetzlich emittiert er fuer jede Messung ein lokales Event:
+
+```js
+window.addEventListener('xtend-loader-performance', (event) => {
+  console.log(event.detail.name, event.detail.durationMs);
+});
+```
+
+Die Boot-Promise enthaelt die lokalen Loader-Messwerte:
+
+```js
+const boot = await window.__XTendLoaderBootPromise;
+console.log(boot.performanceMeasurements);
+```
+
+Die Fabric-Telemetry-Snapshots normalisieren diese Eintraege als `xtend.performance.measurement.v1`.
+
+## Gates
+
+Relevante lokale 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` startet `scripts/serve_xtend_dev.js` auf Port `4173`. Der Browser-Smoke-Harness nutzt dasselbe Servermodul im Testmodus mit Port `0`.
+
+## Weiterfuehrende Themen
+
+- [Manifest-Format](./manifest.md)
+- [Manifest Import Policy](./manifest-import-policy.md)
+- [Performance Measurements](./performance-measurements.md)
+- [API-Integration](./api.md)
+- [Komponenten-Entwicklung](./components.md)
+- [Best Practices](./best-practices.md)

package/docs/de/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`
+
+## Zweck
+
+`WP-TypeExports-05` macht die Fabric-, A11y- und Security-Policy-APIs fuer TypeScript-Consumer importierbar. Die JS-Runtime bleibt unveraendert; `package.json#exports` ergaenzt nur package-native `types`-Conditions.
+
+## Declaration Pack
+
+| Bereich | 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` |
+
+Der gemeinsame Typkern liegt in `fabric/xtend-policy-public-types.d.ts` und enthaelt `XtendPolicyDiagnostic`, `XtendPolicyReport`, `XtendFabricFiberInput`, `XtendA11ySignal` und `XtendSecurityClassification`.
+
+## Drift Gate
+
+Der Gate prueft:
+
+- jede Policy Package-Export-Condition zeigt auf die erwartete `.d.ts`
+- jede Declaration-Datei existiert und exportiert die Runtime-Symbole des zugehoerigen JS-Moduls
+- zentrale Diagnostic-, Report-, Fiber-, A11y- und Security-Klassifikationstypen bleiben vorhanden
+- Fabric/A11y/Security Runtime-Dateien importieren keine `.d.ts`
+- keine Policy fuehrt Runtime-Abhaengigkeiten in Komponenten, Loader, API oder RMT-Kernel ein
+
+## Handoff
+
+`WP-TypeExports-06` kann nun Builder-, Scaffold- und Component-Lab-Programm-APIs typisieren. Das Policy-Pack setzt das Muster fuer Integrationsmodule fort: bestehende JS-Runtime, schmale Declaration-Facades, package-native `types`-Conditions und ein Drift-Gate gegen Export-Abweichungen.

package/docs/de/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`
+
+## Zweck
+
+`WP-TypeExports-04` macht die XTendRMT Runtime, den Browser-Entry und die RMT-Language-/Tooling-Exports fuer TypeScript-Consumer importierbar. `./rmt` und `./rmt/browser` zeigen per `types`-Condition auf `./xtendrmt/rmt-core.d.ts`, waehrend `./rmt/dom-descriptor-renderer`, `./rmt/state-selector-runtime`, `./rmt/action-effect-runtime`, `./rmt/event-routing-runtime` und `./rmt/surface-resource-graph-runtime` eigene schmale Runtime-Declarations besitzen.
+
+## Declaration Pack
+
+| Bereich | 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 und Parser | `./rmt-language/source-model`, `./rmt-language/parser` | `tools/rmt-language/*.d.ts` |
+| vNext Compiler und 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 mit gemeinsamen RMT-Tooling-Typen |
+| LSP, Linter, Editor | `./rmt-language-server`, `./rmt-linter/*`, `./rmt-editor/vscode` | LSP-/CLI-/Editor-Facades |
+
+Der gemeinsame Typkern liegt in `tools/rmt-language/rmt-tooling-public-types.d.ts` und enthaelt unter anderem `RmtToolingDiagnostic`, `RmtTextEdit`, `RmtWorkspaceEdit`, `RmtLanguageServiceReport` und `RmtJsonRpcMessage`.
+
+## Drift Gate
+
+Der Gate prueft:
+
+- jede RMT Package-Export-Condition zeigt auf die erwartete `.d.ts`
+- jede Declaration-Datei existiert und exportiert die Runtime-Symbole des zugehoerigen JS-Moduls
+- zentrale Diagnostic-, Range-, Edit-, Completion-, Hover-, Symbol-, Definition-, CodeAction- und JSON-RPC-Typen bleiben vorhanden
+- RMT Runtime-Dateien importieren keine `.d.ts`
+- RMT-Kernel importiert keine XTend-UI-Typen, Loader, API, Fabric, A11y oder Security Runtime-Oberflaechen
+
+## Handoff
+
+`WP-TypeExports-05` kann nun Fabric-, A11y- und Security-Policy-APIs typisieren. Das RMT-Pack ist dabei die Referenz fuer P1-Integrationsmodule: schmale Declarations, bestehende JS-Runtime, package-native `types`-Conditions und ein Drift-Gate gegen Export-Abweichungen.

package/docs/de/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`
+
+## Zweck
+
+`WP-TypeExports-08` schliesst die verbleibenden Type-Facade-Luecken an Randmodulen. Die Facades sind absichtlich schmal: XTend kopiert keine vollstaendige Prism- oder Turndown-Typwelt, sondern beschreibt nur die stabile Nutzungsgrenze im Projekt.
+
+## Facades
+
+- `./components/prism.d.ts` beschreibt die globale und CommonJS-faehige Prism-Fassade mit `highlight`, `highlightElement`, `highlightAllUnder`, `hooks`, `languages` und `Token`.
+- `./components/turndown.d.ts` beschreibt die Browser-Global-Fassade `window.TurndownService` fuer Side-Effect-Imports und lokale Markdown-Konvertierung.
+- `./design-tokens/xtend-design-tokens.d.ts` beschreibt den produktiven Design-Token-Contract `xtend.design-tokens.product-contract.v1`, Theme Packs, Density Packs und Validatoren.
+- `./design-tokens/xtheme-token-alias-layer.d.ts` beschreibt den XTheme Alias Layer `xtend.theme.token-alias-layer.v1`, Legacy Bridges, Component Aliases und Validatoren.
+
+## Theme JSON
+
+`./design-tokens/themes/enterprise-light` bleibt eine JSON-Boundary. Das Beispiel-Theme wird als Datenartefakt exportiert und benoetigt keine eigene Runtime-Declaration. Consumer, die JSON importieren, sollen ihre Projektkonfiguration fuer JSON-Module nutzen.
+
+## Nicht-Ziele
+
+- Keine Volltypisierung der gesamten Prism-Sprachliste.
+- Keine Uebernahme fremder Vendor-Interna in XTend-Namespace-Typen.
+- Keine Runtime-Aenderung an `components/prism.js`, `components/turndown.js`, `design-tokens/xtend-design-tokens.js` oder `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
+```
+
+Der Gate prueft, dass `./design-tokens` und `./design-tokens/xtheme-token-alias-layer` eine `types`-Condition besitzen, dass die Komponenten-Vendor-Dateien eigene `.d.ts`-Facades haben, dass keine Component-`.js`-Datei ohne Declaration-Gap bleibt und dass die Facades keine Runtime-Imports oder Vendor-Implementierungsdetails kopieren.