@ccslabs/xtend 0.1.0-rc.1

package/docs/utils/parsedown.php

@@ -0,0 +1,298 @@
+<?php
+
+/**
+ * Lightweight Parsedown-compatible adapter for the local XTend docs app.
+ *
+ * The original Docs host expects the public Parsedown API surface:
+ * - new Parsedown()
+ * - setSafeMode(true)
+ * - text($markdown)
+ *
+ * This adapter intentionally keeps the surface tiny and safe for local
+ * development. It supports the Markdown constructs used by the XTend docs
+ * without adding a Composer/runtime dependency to the repository.
+ */
+class Parsedown
+{
+    private bool $safeMode = false;
+
+    public function setSafeMode($safeMode): self
+    {
+        $this->safeMode = (bool) $safeMode;
+        return $this;
+    }
+
+    public function text($text): string
+    {
+        $lines = preg_split('/\r\n|\r|\n/', (string) $text);
+        $html = [];
+        $paragraph = [];
+        $listType = null;
+        $table = [];
+        $inCode = false;
+        $codeFence = '';
+        $codeLines = [];
+
+        $flushParagraph = function () use (&$html, &$paragraph): void {
+            if (!$paragraph) return;
+            $content = trim(implode(' ', $paragraph));
+            if ($content !== '') {
+                $html[] = '<p>' . $this->inline($content) . '</p>';
+            }
+            $paragraph = [];
+        };
+
+        $flushList = function () use (&$html, &$listType): void {
+            if ($listType) {
+                $html[] = '</' . $listType . '>';
+                $listType = null;
+            }
+        };
+
+        $flushTable = function () use (&$html, &$table): void {
+            if (!$table) return;
+            $html[] = $this->renderTable($table);
+            $table = [];
+        };
+
+        foreach ($lines as $line) {
+            $raw = rtrim($line, "\r\n");
+
+            if ($inCode) {
+                if (preg_match('/^\s*```\s*$/', $raw)) {
+                    $html[] = '<pre><code' . ($codeFence ? ' class="language-' . $this->escapeAttribute($codeFence) . '"' : '') . '>'
+                        . $this->escapeHtml(implode("\n", $codeLines))
+                        . '</code></pre>';
+                    $inCode = false;
+                    $codeFence = '';
+                    $codeLines = [];
+                } else {
+                    $codeLines[] = $raw;
+                }
+                continue;
+            }
+
+            if (preg_match('/^\s*```\s*([A-Za-z0-9_-]+)?\s*$/', $raw, $matches)) {
+                $flushParagraph();
+                $flushList();
+                $flushTable();
+                $inCode = true;
+                $codeFence = $matches[1] ?? '';
+                $codeLines = [];
+                continue;
+            }
+
+            if (trim($raw) === '') {
+                $flushParagraph();
+                $flushList();
+                $flushTable();
+                continue;
+            }
+
+            if ($this->isHorizontalRule($raw)) {
+                $flushParagraph();
+                $flushList();
+                $flushTable();
+                $html[] = '<hr>';
+                continue;
+            }
+
+            if (preg_match('/^\s{0,3}(#{1,6})\s+(.+?)\s*#*\s*$/', $raw, $matches)) {
+                $flushParagraph();
+                $flushList();
+                $flushTable();
+                $level = strlen($matches[1]);
+                $content = trim($matches[2]);
+                $id = $this->slug($content);
+                $html[] = '<h' . $level . ($id ? ' id="' . $this->escapeAttribute($id) . '"' : '') . '>'
+                    . $this->inline($content)
+                    . '</h' . $level . '>';
+                continue;
+            }
+
+            if (preg_match('/^\s{0,3}>\s?(.*)$/', $raw, $matches)) {
+                $flushParagraph();
+                $flushList();
+                $flushTable();
+                $html[] = '<blockquote><p>' . $this->inline($matches[1]) . '</p></blockquote>';
+                continue;
+            }
+
+            if ($this->isTableLine($raw)) {
+                $flushParagraph();
+                $flushList();
+                $table[] = $raw;
+                continue;
+            }
+
+            if (preg_match('/^\s*[-*+]\s+(.+)$/', $raw, $matches)) {
+                $flushParagraph();
+                $flushTable();
+                if ($listType !== 'ul') {
+                    $flushList();
+                    $listType = 'ul';
+                    $html[] = '<ul>';
+                }
+                $html[] = '<li>' . $this->inline(trim($matches[1])) . '</li>';
+                continue;
+            }
+
+            if (preg_match('/^\s*\d+[.)]\s+(.+)$/', $raw, $matches)) {
+                $flushParagraph();
+                $flushTable();
+                if ($listType !== 'ol') {
+                    $flushList();
+                    $listType = 'ol';
+                    $html[] = '<ol>';
+                }
+                $html[] = '<li>' . $this->inline(trim($matches[1])) . '</li>';
+                continue;
+            }
+
+            $flushList();
+            $flushTable();
+            $paragraph[] = trim($raw);
+        }
+
+        if ($inCode) {
+            $html[] = '<pre><code' . ($codeFence ? ' class="language-' . $this->escapeAttribute($codeFence) . '"' : '') . '>'
+                . $this->escapeHtml(implode("\n", $codeLines))
+                . '</code></pre>';
+        }
+
+        $flushParagraph();
+        $flushList();
+        $flushTable();
+
+        return implode("\n", $html);
+    }
+
+    private function inline(string $text): string
+    {
+        $escaped = $this->safeMode ? $this->escapeHtml($text) : $text;
+        $tokens = [];
+
+        $escaped = preg_replace_callback('/`([^`]+)`/', function ($matches) use (&$tokens) {
+            $token = "\x1A" . count($tokens) . "\x1A";
+            $tokens[$token] = '<code>' . $this->escapeHtml($matches[1]) . '</code>';
+            return $token;
+        }, $escaped);
+
+        $escaped = preg_replace_callback('/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/', function ($matches) {
+            $alt = $this->escapeAttribute($matches[1]);
+            $src = $this->sanitizeUrl($matches[2]);
+            $title = isset($matches[3]) ? ' title="' . $this->escapeAttribute($matches[3]) . '"' : '';
+            return '<img src="' . $this->escapeAttribute($src) . '" alt="' . $alt . '"' . $title . '>';
+        }, $escaped);
+
+        $escaped = preg_replace_callback('/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/', function ($matches) {
+            $href = $this->sanitizeUrl($matches[2]);
+            $title = isset($matches[3]) ? ' title="' . $this->escapeAttribute($matches[3]) . '"' : '';
+            return '<a href="' . $this->escapeAttribute($href) . '"' . $title . '>' . $matches[1] . '</a>';
+        }, $escaped);
+
+        $escaped = preg_replace('/\*\*([^*]+)\*\*/', '<strong>$1</strong>', $escaped);
+        $escaped = preg_replace('/__([^_]+)__/', '<strong>$1</strong>', $escaped);
+        $escaped = preg_replace('/\*([^*]+)\*/', '<em>$1</em>', $escaped);
+        $escaped = preg_replace('/_([^_]+)_/', '<em>$1</em>', $escaped);
+
+        return strtr($escaped, $tokens);
+    }
+
+    private function renderTable(array $lines): string
+    {
+        if (count($lines) < 2 || !$this->isSeparatorLine($lines[1])) {
+            return '<p>' . $this->inline(implode(' ', array_map('trim', $lines))) . '</p>';
+        }
+
+        $headers = $this->splitTableRow($lines[0]);
+        $align = $this->splitTableRow($lines[1]);
+        $rows = array_slice($lines, 2);
+        $html = ['<table>', '<thead><tr>'];
+
+        foreach ($headers as $index => $header) {
+            $style = $this->tableAlignStyle($align[$index] ?? '');
+            $html[] = '<th' . $style . '>' . $this->inline(trim($header)) . '</th>';
+        }
+
+        $html[] = '</tr></thead>';
+        if ($rows) {
+            $html[] = '<tbody>';
+            foreach ($rows as $row) {
+                $html[] = '<tr>';
+                foreach ($this->splitTableRow($row) as $index => $cell) {
+                    $style = $this->tableAlignStyle($align[$index] ?? '');
+                    $html[] = '<td' . $style . '>' . $this->inline(trim($cell)) . '</td>';
+                }
+                $html[] = '</tr>';
+            }
+            $html[] = '</tbody>';
+        }
+
+        $html[] = '</table>';
+        return implode('', $html);
+    }
+
+    private function isTableLine(string $line): bool
+    {
+        return str_contains($line, '|');
+    }
+
+    private function isSeparatorLine(string $line): bool
+    {
+        return (bool) preg_match('/^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$/', $line);
+    }
+
+    private function isHorizontalRule(string $line): bool
+    {
+        return (bool) preg_match('/^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/', $line);
+    }
+
+    private function splitTableRow(string $line): array
+    {
+        $line = trim($line);
+        $line = trim($line, '|');
+        return array_map('trim', explode('|', $line));
+    }
+
+    private function tableAlignStyle(string $marker): string
+    {
+        $marker = trim($marker);
+        if (str_starts_with($marker, ':') && str_ends_with($marker, ':')) {
+            return ' style="text-align:center"';
+        }
+        if (str_ends_with($marker, ':')) {
+            return ' style="text-align:right"';
+        }
+        if (str_starts_with($marker, ':')) {
+            return ' style="text-align:left"';
+        }
+        return '';
+    }
+
+    private function sanitizeUrl(string $url): string
+    {
+        $url = trim($url);
+        if (preg_match('/^\s*(javascript|vbscript|data):/i', $url)) {
+            return '#';
+        }
+        return $url;
+    }
+
+    private function slug(string $text): string
+    {
+        $slug = strtolower(strip_tags($text));
+        $slug = preg_replace('/[^a-z0-9]+/i', '-', $slug);
+        return trim((string) $slug, '-');
+    }
+
+    private function escapeHtml(string $value): string
+    {
+        return htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
+    }
+
+    private function escapeAttribute(string $value): string
+    {
+        return htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
+    }
+}

package/docs/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`
+
+Diese Seite beschreibt den aktuellen XTend-Plan fuer visuelle und browsernahe Regression. ER-WP-35 fuehrt noch keinen Screenshot-Runner ein. Stattdessen erzeugt XTend einen stabilen Prioritaetsplan, der pro Manifest-Komponente festlegt, welche Browser-Smokes, Viewports, Theme-Varianten, visuellen Zustaende und Performance-Profile zuerst automatisiert werden muessen.
+
+## Lokal pruefen
+
+```bash
+node scripts/run_xtend_tests.js regression-priority
+node scripts/run_xtend_tests.js regression-priority --json
+npm run test:regression-priority
+```
+
+Der Gate ist Teil des lokalen Test-Runners und nutzt die Component Catalog Coverage Matrix als Quelle. Er bleibt CDN-frei und braucht keine externe Browser-Automation.
+
+## Mindestabdeckung
+
+Jede Komponente im Plan erhaelt:
+
+- Viewports: `desktop-1280`, `mobile-390`
+- Theme-/Preference-Varianten: `light`, `dark`, `forced-colors`, `reduced-motion`
+- Performance-Profil: `xtend.performance.component-profile.v1`
+- Handoff-Gates: `browser`, `performance-regression`, `catalog-coverage`, `references`
+
+P0-Komponenten wie `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` und `x-lightbox` werden als `p0-browser-critical` eingeordnet. P1-Komponenten wie `x-status` und `x-progress` bilden die visuelle und Performance-Baseline. P2-Komponenten bleiben als Long-Tail sichtbar.
+
+## Profil-Regeln
+
+| Profil | Browser-Smokes | Visuelle Zustaende |
+|--------|----------------|--------------------|
+| `routing` | Route-Wechsel, 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-Abschluss
+
+Der Plan haelt die frueheren Boundary-Luecken nachvollziehbar, aber nicht mehr als offene RC1-Restpunkte:
+
+- 0 Manifest-Eintraege brauchen noch Suite-, Fixture- oder Type-Nacharbeit.
+- `xstate` ist seit `WP-E13-05` als Runtime-Boundary geschlossen.
+- `x-utils` ist seit `WP-E13-05` als Utility-Boundary geschlossen.
+- Die 40 sichtbaren Runtime-/UI-Komponenten behalten explizite Performance-Profile; `xstate` und `x-utils` werden nicht kuenstlich zu visuellen Profiltraegern umgedeutet.
+
+Damit ist klar, dass `ER-WP-35` priorisiert, aber die eigentliche Screenshot-/Pixel-Regression an CI und Release Readiness uebergibt.
+
+## Snapshot Automation Contract
+
+Seit `WP-E12-10` ist der naechste Schritt ueber `xtend.epic12.visual-snapshot-automation-contract.v1` festgelegt:
+
+```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
+```
+
+Der Snapshot-Contract uebernimmt die 360 Kombinationen aus der Component Shell Theme Matrix und beschreibt `shell-structure`, `visual-state`, `theme-token-state`, `motion-density-state`, `viewport-layout`, `focus-a11y-state` und `rmt-shell-descriptor` als Snapshot Scopes. Die Diff-Strategie ist `dom-first-pixel-ready`: DOM-Struktur und CSS Token werden mit Toleranz `0` behandelt. Seit `WP-E12-11` vergleicht `xtend.epic12.visual-snapshot-runner.v1` die lokale Fixture gegen eine textuelle JSON DOM-Baseline. Pixel-Diff ist als `optional-local-pixel-diff` vorbereitet und bleibt ausserhalb des Node-Contract-Gates. Seit `WP-E12-12` werden diese CSS Token als `xtend.design-tokens.product-contract.v1` produktisiert und ueber dieselben `--xtend-*` Namen in `x-theme`, Theme Matrix und Snapshot Baseline geprueft.
+
+## Handoff
+
+- `WP-E12-10`: Visual Snapshot Automation Contract ist abgeschlossen.
+- `WP-E12-11`: lokales Snapshot Fixture und DOM-first Runner ist abgeschlossen.
+- `WP-E12-12`: Enterprise Design System Token Productization ist abgeschlossen.
+- `ER-WP-36`: CI Workflow fuer Default Gates und Regression Priority Gate produktisieren.
+- `ER-WP-38`: Release Checklist um Browser-/Visual-Regression, Artefakte und SemVer-Risiken erweitern.
+- `ER-WP-39`: Enterprise Adoption Guide mit QS-Empfehlungen und Baseline-Strategie ist abgeschlossen.
+- `ER-WP-40`: Docs-App mit RMT Parsedown Scheduling Pilot ist abgeschlossen.
+
+Die maschinenlesbare Umsetzung liegt in `catalog/component-regression-priority.js`. Die Architekturentscheidung liegt in `development/XTend-Visuelle-und-Browsernahe-Regression-Prioritaetsplan.md`.

package/docs/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`
+- Lokaler 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`
+
+## Zweck
+
+Visual Owner Artifacts verbinden die bestehende DOM-first Visual Snapshot Automation mit einem reproduzierbaren Screenshot-/Pixel-Artefaktpfad fuer RC1. Der lokale Gate validiert Contract, Manifest und DOM-Snapshot-Zustand. Die eigentliche Screenshot-Erzeugung bleibt optional und gehoert in stabile Browser- oder CI-Umgebungen.
+
+## Pfadkonvention
+
+```text
+.xtend-test-results/visual-snapshots/rc1/{family}/{viewport}/{theme}/{density}/{motion}.png
+```
+
+Der Report liegt unter:
+
+```text
+.xtend-test-results/visual-snapshots/rc1/visual-owner-artifact-report.json
+```
+
+Die Fixture bleibt `tests/browser/fixtures/visual-snapshots-fixture.html`, die DOM-Baseline bleibt `tests/browser/visual-baselines/visual-snapshots.dom-baseline.json`.
+
+## Lokale Nutzung
+
+```bash
+npm run test:epic13-visual-owner-artifact
+```
+
+Der lokale Modus ist `static-artifact-manifest-plus-dom-snapshot-gate`. `pixelDiffRequiredInLocalGate`, `screenshotRequiredInLocalGate` und `binaryBaselineCommitted` sind `false`.
+
+## Beziehung zu vorhandenen Gates
+
+- Die DOM-Struktur kommt aus [Visual Snapshot Automation](./visual-snapshot-automation.md).
+- Die PROD-nahe Browser-/CSP-Vorbereitung kommt aus [PROD Browser CSP Smokes](./prod-browser-csp-smokes.md).
+- Das Owner-Artefakt bleibt `optional-browser-driver-or-ci-artifact`, bis eine stabile Browser-Capture-Umgebung als verpflichtender Release-Gate entschieden wird.
+
+## Handoff
+
+`WP-E13-08` ist abgeschlossen. `WP-E13-09` hat `xtend.epic13.rmt-production-readiness.v1` unter [RMT Production Readiness](./rmt-production-readiness.md) gebuendelt. `WP-E13-10` hat [Docs RMT Production Hardening](./docs-rmt-production-hardening.md) abgeschlossen. `WP-E13-11` hat [Trusted DOM Boundary Browser Proof](./trusted-dom-boundary-browser-proof.md) und `xtend.epic13.trusted-dom-boundary.v1` abgeschlossen. `WP-E13-12` hat [RC1 Migration Notes](./rc1-migration-notes.md) und `xtend.epic13.rc1-migration-notes-semver.v1` abgeschlossen. `WP-E13-13` hat [RC1 Gate Matrix und CI-Handoff](./rc1-gate-matrix-ci-handoff.md) und `xtend.epic13.rc1-gate-matrix-ci-handoff.v1` abgeschlossen.

package/docs/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 ist die Epic-12-Linie fuer lokale visuelle Regression. `WP-E12-10` definiert Scopes, Matrix, Toleranzen und Artefaktpolitik. `WP-E12-11` setzt darauf einen lokalen DOM-first Snapshot Runner mit JSON-Baseline auf.
+
+## Lokal pruefen
+
+```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
+```
+
+Der Gate ist local-only, CDN-frei und nutzt keine externen Browserdienste.
+
+## Matrix
+
+Der Contract uebernimmt die 360 Kombinationen der 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-Familien: `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`
+
+Die RMT-Grenze bleibt `no-rmt-kernel-import-of-xtend-types`: RMT beschreibt und scheduled Shells, importiert aber keine XTend-Typen in den Kernel.
+
+Ab `WP-E12-12` nutzt die Snapshot-Fixture dieselben Produkt-Tokens wie `x-theme` und die Component Shell Theme Matrix. Die DOM-Baseline trackt `--xtend-surface`, `--xtend-text`, `--xtend-color-primary`, `--xtend-density-spacing` und `--xtend-radius`; lokale Fixture-Namen wie `--snapshot-*` sind entfernt.
+
+## Diff-Strategie
+
+`WP-E12-10` legt `dom-first-pixel-ready` fest, `WP-E12-11` fuehrt den lokalen DOM-Diff aus:
+
+- DOM-Struktur und CSS Token haben Toleranz `0`.
+- Pixel-Diff ist vorbereitet als `optional-local-pixel-diff`, laeuft im Node-Contract-Gate aber nicht.
+- Maximaler Pixel-Mismatch ist `0.01`.
+- Layout Shift ist auf `1px` begrenzt.
+- Vor Capture muss der Runner auf Custom Elements, Fonts, Loader-Abschluss und einen Animation Frame warten.
+
+## Artefakte
+
+| Artefakt | Pfad |
+|----------|------|
+| 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` |
+
+Die Baseline ist in `WP-E12-11` textuell und reviewbar. Binary- oder Screenshot-Baselines bleiben einem optionalen lokalen Pixel-Diff-Modus vorbehalten.
+
+## RC1 Visual Owner Artifact
+
+Ab `WP-E13-08` nutzt [Visual Owner Artifacts](./visual-owner-artifacts.md) diese DOM-first Linie als Quelle fuer `xtend.epic13.visual-owner-artifact.v1`. Der lokale Gate `node scripts/run_xtend_tests.js epic13-visual-owner-artifact --json` normalisiert Artifact Root, Report-Pfad, Screenshot-Template und Viewports. Die Screenshot-/Pixel-Erzeugung bleibt `optional-browser-driver-or-ci-artifact`.
+
+## RC0 Adoption Update
+
+Seit `WP-E12-15` verweist der [RC0 Adoption Guide](./rc0-adoption-guide.md) auf diesen DOM-first Snapshot-Pfad als RC0-Baseline. Component Authors behandeln `visual-snapshots`, `design-tokens` und `component-shell-theme-matrix` gemeinsam als lokale Review-Kette; Pixel-Baselines bleiben optional und duerfen den lokalen RC0 Dry Run nicht blockieren.

package/docs/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`
+
+## Zweck
+
+`api.d.ts` beschreibt die oeffentliche Core-API aus `api.js`: `initXTendAPI(manifest)`, den globalen Namespace `window.XTend.*`, die Legacy-Aliase und das Event `xtend-api-ready`. Die Declaration ist types-only; `api.js` bleibt runtime-unveraendert.
+
+## Namespace
+
+Der zentrale Namespace-Typ heisst `XTendNamespace`.
+
+| API | Typ |
+| --- | --- |
+| `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-Aliase
+
+`api.d.ts` typisiert weiterhin die bestehenden globalen Komfort-Aliase:
+
+- `window.XTheme`
+- `window.XToast`
+- `window.XAlert`
+- `window.XDialog`
+- `window.XModal`
+- `window.showToast`
+- `window.showAlert`
+- `window.showDialog`
+- `window.showModal`
+
+## Event
+
+`WindowEventMap` enthaelt `xtend-api-ready` mit `XTendApiReadyDetail`. Der Payload meldet, ob Toast, Alert, Dialog, Modal und Theme APIs initialisiert sind.
+
+## Package Export
+
+Der Package-Export `./api` besitzt ab `WP-TypeExports-03` die `types`-Condition `./api.d.ts`. `browser` und `default` zeigen weiter auf `./api.js`.
+
+## Drift Gate
+
+Der Gate `type-exports-api` prueft:
+
+- `api.d.ts` existiert und ist im Package enthalten.
+- `./api` zeigt per `types` auf `./api.d.ts`.
+- `initXTendAPI`, `window.XTend.*`, Legacy-Aliase und `xtend-api-ready` sind in Runtime und Declaration sichtbar.
+- `api.js` importiert keine Declaration-Datei.

package/docs/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` typisiert die Builder-, Scaffold- und Component-Lab-Programm-APIs, ohne die CLI oder die Generatoren nach TypeScript zu portieren.
+
+Die gemeinsame Grundlage liegt in `./xtend-builder/builder-public-types.d.ts`:
+
+- `XtendBuilderComponentInput`
+- `XtendBuilderComponentPlan`
+- `XtendBuilderComponentFilesResult`
+- `XtendBuilderWorkflow`
+- `XtendBuilderComponentLabPlan`
+
+## Declaration Pack
+
+Die Root- und Workflow-APIs sind ueber diese Facades stabilisiert:
+
+- `./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- und Preview-Consumer erhalten eigene Contracts:
+
+- `./xtend-builder/preview/component-preview.d.ts`
+- `./xtend-builder/preview/component-lab.d.ts`
+- `./xtend-builder/preview/component-lab-ux-inspector.d.ts`
+
+Die bereits exportierten Typing- und UX-Contract-Module sind als schmale Facades abgebildet, darunter `component-shell-contract`, `component-styling-contract`, `component-network-contract`, `rmt-shell-authoring-contract`, `rmt-dsl-authoring-polish`, die Form-/Feedback-/Navigation-/Overlay-/Layout-UX Contracts und `component-ux-performance-contract`.
+
+## Package Exports
+
+Die Package-Exports `./builder`, `./builder/*` sowie die expliziten Builder-Subexports erhalten `types`-Conditions. Beispiel:
+
+```json
+"./builder": {
+  "types": "./xtend-builder/scaffold.d.ts",
+  "default": "./xtend-builder/scaffold.js"
+}
+```
+
+`./builder/*` bleibt als generischer Anschluss fuer repo-lokale Builder-Module erhalten und zeigt auf `./xtend-builder/*.d.ts`.
+
+## Boundary
+
+Die Declarations bleiben `types-only-no-runtime-imports`. Sie importieren keine Builder-Runtime, keine Komponenten, keinen RMT-Kernel und keine Loader-/API-Laufzeit. Der lokale Gate vergleicht Runtime-Exports, Package-`types`-Conditions, vorhandene Declaration-Dateien und die gemeinsame Builder-Type-Basis.

package/docs/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`
+
+## Zweck
+
+Catalog-Module beschreiben XTend-Gates, Handoffs, Release-Plaene und SurfaceManager-Runtime-Scopes als maschinenlesbare Plan-/Report-Strukturen. `WP-TypeExports-07` fuehrt dafuer ein gemeinsames Declaration-Pattern ein, damit neue Catalogs nicht pro Property neu typisiert werden muessen.
+
+`./catalog/catalog-public-types.d.ts` definiert die gemeinsamen Basistypen `XtendCatalogPlan`, `XtendCatalogReport`, `XtendCatalogGate`, `XtendCatalogFactory`, `XtendCatalogValidator` und `XtendCatalogDiagnostic`. Die einzelnen Catalog-Facades exportieren die Runtime-Symbole des jeweiligen `.js`-Moduls und binden Funktionen wie `create*Plan`, `create*Report`, `create*Gate` und `validate*Plan` an diese Basistypen.
+
+## Package Surface
+
+Alle oeffentlichen `./catalog/*` Package-Exports besitzen nun eine eigene `types`-Condition. Beispiele:
+
+```json
+"./catalog/epic13-package-export-lock": {
+  "types": "./catalog/epic13-package-export-lock.d.ts",
+  "default": "./catalog/epic13-package-export-lock.js"
+}
+```
+
+Das Runtime-Ziel bleibt unveraendert. Die Declarations importieren keine Runtime-Dateien und sind als Consumer-Facades gedacht.
+
+## Catalog Familien
+
+Der Gate klassifiziert drei fuer XTend wichtige Catalog-Familien:
+
+- SurfaceManager-Catalogs bleiben interne XTend-UI-Unterstuetzung und dokumentieren App-Shell-, Surface-, Routing- und Runtime-Handoffs.
+- Epic-Catalogs beschreiben Workpackage-, Gate- und Contract-Plaene ueber mehrere Epics hinweg.
+- Release-Catalogs bündeln Handoff-, Readiness-, Export-Lock- und Migration-Entscheidungen.
+
+Die SurfaceManager-Catalogs ersetzen keine Fabric-, RMT-Kernel- oder Runtime-Schicht. Sie bleiben deklarative Plaene und Reports, die UI-Surfaces unterstuetzen.
+
+## Drift Gate
+
+```bash
+node scripts/run_xtend_tests.js type-exports-catalog --json
+npm run test:type-exports-catalog
+```
+
+Der Gate prueft, dass Package-Catalogs ihre `types`-Conditions besitzen, dass alle Catalog-Runtime-Exports in den `.d.ts`-Facades auftauchen, dass SurfaceManager-/Epic-/Release-Catalogs klassifiziert sind und dass keine Runtime-Dateien Declaration-Imports erhalten.