@hueest/xray 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,9 +1,19 @@
 import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
+import * as v from "valibot";
 /** App code imports plates from here, e.g. `import plate from 'virtual:xray/plates/my-banner'`. */
 const VIRTUAL_PREFIX = "virtual:xray/plates/";
 /** Marks the rendered skeleton root; carries the plate name. Also a dev capture marker. */
 const ROOT_ATTR = "data-xr-root";
+/**
+* Marks an OUTERMOST skeleton root that is a stitch continuation (ADR 0020): a
+* standalone `<Skeleton>` replacing a stitch a still-showing parent skeleton was
+* just rendering. BASE_CSS reveals such a root instantly (no `--xr-skeleton-delay`,
+* no fade) so the bones do not flash away and back. Never present on a nested
+* stitch (which inherits the parent's reveal and has no `@starting-style` of its
+* own) nor on an ordinary top-level skeleton (which keeps the normal delay).
+*/
+const ROOT_INSTANT_ATTR = "data-xr-instant";
 const SPEC_GATE = 2e7;
 /** Fixed renderer-owned classes every rendered node carries. */
 const ROOT_CLASS = "xr-root";
@@ -14,10 +24,17 @@ const LEAF_CLASS = "xr-leaf";
    opacity property and every leaf reads it. Hundreds of independent infinite
    opacity animations would pin the compositor and cook the CPU. */
 @property --xr-o { syntax: "<number>"; inherits: true; initial-value: 1 }
+/* The reveal channel (ADR 0016): a second inherited opacity factor the leaf
+   multiplies into --xr-o. Transitioning THIS (not opacity directly) sidesteps
+   the animation-vs-transition collision ADR 0012 flagged. initial-value 1 (NOT
+   0) is the degradation floor: without @starting-style the reveal can never be
+   driven 0->1, so it must REST at 1 (fully visible). The delay-hide below is
+   pure progressive enhancement layered on top. */
+@property --xr-reveal { syntax: "<number>"; inherits: true; initial-value: 1 }
 .${ROOT_CLASS} {
-  --xr-bone-highlight: #f4f4f5;
+  --xr-bone-highlight-color: #f4f4f5;
   display: contents;
-  animation: var(--xr-anim, xr-pulse) var(--xr-duration, 1.2s) ease-in-out infinite alternate;
+  animation: var(--xr-bone-animation, xr-pulse) var(--xr-bone-animation-duration, 1.2s) ease-in-out infinite alternate;
 }
 /* No pointer-events:none — it blocks inspecting bones in devtools and buys
    nothing (no real content to click). border-color: a node may capture
@@ -25,34 +42,67 @@ const LEAF_CLASS = "xr-leaf";
    a captured display:list-item would otherwise paint. */
 .${NODE_CLASS} { border-color: transparent; list-style: none }
 .${LEAF_CLASS} {
-  background: var(--xr-fill, var(--xr-bone, #e4e4e7));
-  border-radius: var(--xr-radius, 4px);
-  opacity: var(--xr-o);
+  background: var(--xr-bone-fill, var(--xr-bone-color, #e4e4e7));
+  border-radius: var(--xr-bone-border-radius, 4px);
+  /* Composed opacity (ADR 0016): the pulse channel times the reveal channel.
+     Never transition opacity directly (the pulse animation owns it). */
+  opacity: calc(var(--xr-o) * var(--xr-reveal));
 }
 /* Per-kind defaults: text reads as rounded bars, media as blocks. Re-theme any
    kind via [data-xr-root] .${LEAF_CLASS}-text { ... }. */
-.${LEAF_CLASS}-text { border-radius: var(--xr-radius-text, 999px) }
-.${LEAF_CLASS}-media { border-radius: var(--xr-radius-media, var(--xr-radius, 4px)) }
+.${LEAF_CLASS}-text { border-radius: var(--xr-bone-text-border-radius, 999px) }
+.${LEAF_CLASS}-media { border-radius: var(--xr-bone-media-border-radius, var(--xr-bone-border-radius, 4px)) }
 @keyframes xr-pulse {
-  from { --xr-o: var(--xr-pulse-max, 1) }
-  to { --xr-o: var(--xr-pulse-min, 0.5) }
+  from { --xr-o: var(--xr-bone-pulse-opacity-max, 1) }
+  to { --xr-o: var(--xr-bone-pulse-opacity-min, 0.5) }
+}
+/* Reveal delay-hide (ADR 0016), a progressive enhancement guarded so it can NEVER
+   strand a skeleton invisible (open Q3). @starting-style is the trigger: only a
+   browser that supports it enters this block at all, and such a browser also
+   honors @property + transitions, so the 0->1 reveal completes. The @supports
+   selector(...) probe is the broadest cross-engine @starting-style feature test
+   available. Without support the block is skipped entirely and --xr-reveal stays
+   at its initial-value 1 = fully visible instant skeleton. INSIDE the block we
+   start at 0 and transition to 1 after the delay: invisible for
+   --xr-skeleton-delay, then a --xr-skeleton-transition-duration fade-in; a fast
+   load unmounts before the delay elapses and the skeleton is never seen. */
+@supports (selector(:has(*))) {
+  /* The delay-hide applies to every root EXCEPT a stitch continuation (ADR 0020).
+     Scoping with :not([data-xr-instant]) keeps an ordinary top-level skeleton
+     byte-identical to before: it still mounts at --xr-reveal 0 and fades in after
+     the delay. The transition/initial-1 rest state matches the original. */
+  .${ROOT_CLASS}:not([${ROOT_INSTANT_ATTR}]) {
+    --xr-reveal: 1;
+    transition: --xr-reveal var(--xr-skeleton-transition-duration, 150ms) linear var(--xr-skeleton-delay, 250ms);
+  }
+  @starting-style { .${ROOT_CLASS}:not([${ROOT_INSTANT_ATTR}]) { --xr-reveal: 0 } }
+  /* A stitch continuation (ADR 0020) reveals INSTANTLY: it was already visible as a
+     stitch under a still-showing parent, so re-paying the delay would flash it away
+     and back. No @starting-style and no transition — it rests at fully visible from
+     its first frame, matching how the stitch inherited the parent's reveal. */
+  .${ROOT_CLASS}[${ROOT_INSTANT_ATTR}] { --xr-reveal: 1 }
+}
+/* Reduced motion (open Q2): keep the anti-flash delay + min-duration (they are
+   not motion), drop only the FADE — collapse the reveal transition to instant and
+   kill the pulse animation (as before). */
+@media (prefers-reduced-motion: reduce) {
+  .${ROOT_CLASS} { animation: none; --xr-skeleton-transition-duration: 0s }
 }
-@media (prefers-reduced-motion: reduce) { .${ROOT_CLASS} { animation: none } }
 /* Dark + high-contrast bone defaults. Guarded: light-dark() is an invalid value
    without support and would drop the declaration — see the note above; remove
    this @supports once widely available (2026-11-13). */
 @supports (color: light-dark(#000, #fff)) {
-  .${ROOT_CLASS} { --xr-bone-highlight: light-dark(#f4f4f5, #52525b) }
-  .${LEAF_CLASS} { background: var(--xr-fill, var(--xr-bone, light-dark(#e4e4e7, #3f3f46))) }
+  .${ROOT_CLASS} { --xr-bone-highlight-color: light-dark(#f4f4f5, #52525b) }
+  .${LEAF_CLASS} { background: var(--xr-bone-fill, var(--xr-bone-color, light-dark(#e4e4e7, #3f3f46))) }
   @media (prefers-contrast: more) {
-    .${LEAF_CLASS} { background: var(--xr-fill, var(--xr-bone, light-dark(#d4d4d8, #52525b))) }
+    .${LEAF_CLASS} { background: var(--xr-bone-fill, var(--xr-bone-color, light-dark(#d4d4d8, #52525b))) }
   }
 }
-/* Derive the sheen highlight from --xr-bone so re-theming one token updates both.
-   Relative color isn't widely available yet; the static highlight above is the
-   fallback (sheen just looks flatter), so no hard guard is needed. */
+/* Derive the sheen highlight from --xr-bone-color so re-theming one token updates
+   both. Relative color isn't widely available yet; the static highlight above is
+   the fallback (sheen just looks flatter), so no hard guard is needed. */
 @supports (color: oklch(from red l c h)) {
-  .${ROOT_CLASS} { --xr-bone-highlight: oklch(from var(--xr-bone, #e4e4e7) calc(l + 0.08) c h) }
+  .${ROOT_CLASS} { --xr-bone-highlight-color: oklch(from var(--xr-bone-color, #e4e4e7) calc(l + 0.08) c h) }
 }`.trim();
 /** The (unserialized) plate an import resolves to before anything has been captured. */
 function emptyPlate(name) {
@@ -182,7 +232,7 @@ function regimeFor(width, breakpoints) {
 * Pure data-in/data-out — runs at plugin load (node) and in tests.
 */
 function classify(rules, tree, plateName) {
-	const classBase = `${CLASS_PREFIX}${cssSafe(plateName)}-`;
+	const classBase = `${CLASS_PREFIX}${encodePlateName(plateName)}-`;
 	const sorted = rules.toSorted((a, b) => Number(b.layered ?? false) - Number(a.layered ?? false) || a.spec - b.spec || a.order - b.order);
 	const nameForKey = /* @__PURE__ */ new Map();
 	const body = /* @__PURE__ */ new Map();
@@ -256,9 +306,23 @@ function render(node, classes) {
 }
 /** Content-class prefix; distinct from the fixed `xr-root/node/leaf` base words. */
 const CLASS_PREFIX = "xr-";
-/** Make a plate name safe to embed in a class token (plate names are already constrained). */
-function cssSafe(name) {
-	return name.replace(/[^\w-]/g, "_");
+/**
+* Encode a plate name into a class-token prefix, injectively. This prefix *is*
+* the isolation boundary across stitched plates (ADR 0007), so distinct plate
+* names must never produce the same prefix — a collision would let one plate's
+* `<style>` block reorder another's classes.
+*
+* Plate names are constrained by `isValidPlateName`: each path segment is
+* `\w+(-\w+)*` (word chars with single interior hyphens, no doubled or edge
+* hyphen) and segments are joined by `/`. The slash is the only char that is
+* not class-safe, so rendering it as `--` is enough — and because no segment
+* holds a literal `--` or an edge hyphen, no `-` ever abuts a `/`, so every
+* `--` in the prefix unambiguously came from a `/`, making the map injective.
+* Keeping `/` visually as `--` also leaves nested names readable in the
+* generated CSS (`product--card`).
+*/
+function encodePlateName(name) {
+	return name.replace(/\//g, "--");
 }
 /**
 * What the class identity keys on, alongside media + declarations:
@@ -382,7 +446,8 @@ function remapRules(rules, idMap) {
 function addCapture(file, name, capture, breakpoints) {
 	const allBreakpoints = [...new Set([...file?.breakpoints ?? [], ...breakpoints])].toSorted((a, b) => a - b);
 	const spanKey = (width) => JSON.stringify(regimeFor(width, allBreakpoints));
-	const views = [...file?.views ?? [], capture];
+	const { diagnostics: _diagnostics, ...persisted } = capture;
+	const views = [...file?.views ?? [], persisted];
 	const byView = /* @__PURE__ */ new Map();
 	for (const view of views) byView.set(spanKey(view.width), view);
 	return {
@@ -393,6 +458,425 @@ function addCapture(file, name, capture, breakpoints) {
 	};
 }
 //#endregion
+//#region src/diagnostics.ts
+/**
+* Build a single diagnostic record with its canonical message, for callers
+* outside the walk that surface a diagnostic directly (e.g. the client mapping
+* `CaptureTooLargeError`, or the server reporting an invalid committed plate).
+* Uses the same message table as the collector so the text is identical
+* everywhere. `detail` must never carry user CSS or captured text.
+*/
+function makeDiagnostic(code, options) {
+	return {
+		code,
+		message: DIAGNOSTIC_MESSAGES[code],
+		...options?.count !== void 0 ? { count: options.count } : {},
+		...options?.detail !== void 0 ? { detail: options.detail } : {}
+	};
+}
+/**
+* The human-readable message per code, shared verbatim by browser and server so
+* their text cannot drift. Messages describe the omission and its fidelity
+* cost; none echoes user CSS or captured text. `formatDiagnostic` appends the
+* aggregate count and any short detail.
+*/
+const DIAGNOSTIC_MESSAGES = {
+	"unreadable-stylesheet": "could not read a stylesheet (likely cross-origin); rules from it were not captured",
+	"unreadable-import": "could not read an @import (likely cross-origin); its rules were not captured",
+	"skipped-dynamic-pseudo": "skipped interaction pseudo-class selectors (:hover, :focus, etc.) — a static skeleton never enters those states",
+	"skipped-pseudo-element": "skipped pseudo-element selectors (::before, ::after, etc.) — v1 has no box to map them onto",
+	"unsupported-rule": "skipped CSS rules of a kind the serializer does not lift",
+	"dropped-tag": "dropped hidden or non-visual elements (display:none, visibility:hidden, script/style/etc.)",
+	"pruned-run": "collapsed long runs of similar siblings (a list/grid) to their first few items to keep the plate small",
+	"too-large": "capture exceeded the node limit and was skipped; the <Skeleton> likely sits too high in the tree",
+	"invalid-plate-file": "a committed plate file could not be read (corrupt JSON, wrong shape, or a version mismatch) and was ignored"
+};
+/**
+* The single shared formatter. Renders one diagnostic to a stable one-line
+* string used IDENTICALLY by the browser console and the Vite server output, so
+* the two can never disagree. Shape: `<message> (<count>)[: <detail>]`. Count is
+* omitted when 1 or absent; detail is appended only when present and is never
+* user content.
+*/
+function formatDiagnostic(diagnostic) {
+	const count = diagnostic.count !== void 0 && diagnostic.count > 1 ? ` (${diagnostic.count})` : "";
+	const detail = diagnostic.detail !== void 0 ? `: ${diagnostic.detail}` : "";
+	return `${diagnostic.message}${count}${detail}`;
+}
+/** The grouped-warning header for a plate's diagnostics, shared by browser and server. */
+function diagnosticsHeader(name) {
+	return `[xray] "${name}" captured with reduced fidelity:`;
+}
+//#endregion
+//#region src/name.ts
+/**
+* Plate-name validation, shared by the Vite plugin (`index.ts`) and the
+* Node-only POST validator (`validate.ts`).
+*
+* Lives in its own dependency-free module so `validate.ts` can reuse it without
+* importing the plugin entry (which would be a cycle), and so the regex stays
+* the single source of truth for what a plate name may be — the same rule the
+* loader, the file watcher, the coverage reader, the POST endpoint, and the
+* ref-graph emitter all gate on.
+*
+* @module
+*/
+/**
+* Names come from import specifiers and POST bodies — keep them inside the plates dir.
+*
+* Each path segment is `\w+(-\w+)*` — word chars with single interior hyphens,
+* never doubled and never at a segment edge — and segments are joined by `/`.
+* The class-prefix encoder (`classify.ts`) renders `/` as `--` to keep nested
+* names readable, and that prefix is the isolation boundary across stitched
+* plates (ADR 0007), so the encoding must be injective. Banning a literal `--`
+* and any edge hyphen guarantees no `-` ever abuts a `/`, so every `--` in the
+* prefix came from exactly one `/` — making distinct names always map to
+* distinct prefixes (else e.g. `a/-b` and `a-/b` would both encode to `a---b`).
+*
+* @internal
+*/
+function isValidPlateName(name) {
+	return /^\w+(?:-\w+)*(?:\/\w+(?:-\w+)*)*$/.test(name);
+}
+//#endregion
+//#region src/css.ts
+/**
+* Pure CSS plumbing shared by both extraction strategies: which properties are
+* layout (vs paint), approximate selector specificity for cascade-preserving
+* ordering, and rendering scoped rules back to a single plate CSS string.
+*/
+const EXACT_PROPS = new Set([
+	"display",
+	"position",
+	"float",
+	"clear",
+	"box-sizing",
+	"top",
+	"right",
+	"bottom",
+	"left",
+	"width",
+	"height",
+	"block-size",
+	"inline-size",
+	"aspect-ratio",
+	"order",
+	"flex",
+	"gap",
+	"row-gap",
+	"column-gap",
+	"line-height",
+	"font",
+	"font-size",
+	"font-family",
+	"font-weight",
+	"font-style",
+	"white-space",
+	"text-align",
+	"text-indent",
+	"vertical-align",
+	"letter-spacing",
+	"word-spacing",
+	"word-break",
+	"overflow-wrap",
+	"text-wrap",
+	"transform",
+	"transform-origin",
+	"translate",
+	"scale",
+	"rotate",
+	"table-layout",
+	"border-collapse",
+	"border-spacing",
+	"caption-side",
+	"column-count",
+	"column-width",
+	"columns",
+	"column-span",
+	"column-fill",
+	"writing-mode",
+	"direction",
+	"contain",
+	"content-visibility",
+	"container",
+	"container-type",
+	"container-name",
+	"visibility"
+]);
+const PATTERN_PROPS = [
+	/^(margin|padding)(-(top|right|bottom|left|block|inline))?(-(start|end))?$/,
+	/^inset(-(block|inline))?(-(start|end))?$/,
+	/^border(-(top|right|bottom|left|block|inline))?(-(start|end))?-(width|style)$/,
+	/^border(-(top|bottom)-(left|right))?-radius$/,
+	/^border-(start|end)-(start|end)-radius$/,
+	/^grid(-|$)/,
+	/^flex-/,
+	/^(min|max)-(width|height|block-size|inline-size)$/,
+	/^(align|justify|place)-(items|content|self)$/,
+	/^overflow(-[xy])?$/
+];
+/** Layout properties are the only declarations a plate carries; paint stays out (ADR 0003). */
+function isLayoutProp(prop) {
+	if (prop.startsWith("--")) return false;
+	if (EXACT_PROPS.has(prop)) return true;
+	return PATTERN_PROPS.some((re) => re.test(prop));
+}
+//#endregion
+//#region src/validate.ts
+/**
+* Structural validation of a posted capture, plus a single-CSS-declaration
+* validator, for the dev `/__xray` endpoint.
+*
+* NODE-ONLY (see the capture-input-validation plan and ADR 0008). This module
+* imports `valibot`, which must NEVER reach the browser bundles: the dev capture
+* client, the HUD, the React adapters, and the framework-neutral `core` surface
+* all ship to a browser, and none of them needs to validate an inbound payload.
+* Only the Vite plugin (`index.ts`, the package `.` entry, built with
+* `platform: 'node'`) imports this file, which keeps valibot out of every
+* browser-facing dist chunk. Do NOT import this from `plate.ts`, `css.ts`, or
+* anything a render/browser path also imports, and do NOT re-export these
+* helpers from any public subpath — they stay private until a `doctor`-style
+* tool creates a concrete external need (the plan's decisions).
+*
+* The endpoint accepts ONLY the payload shape xray itself produces. The dev
+* client always posts a `captureRegime` result, so this schema is calibrated to
+* what that emits — finite ids, the layout declarations `filterLayoutDecls`
+* produces, the gate/fallback/leaf rule tiers, media/container condition stacks
+* — and rejects everything else with a generic error. POST-time validation is
+* necessary but not sufficient: a committed `plates/<name>.json` is also
+* untrusted (hand-edited or from git), so the render path independently escapes
+* raw-text `<style>` terminators (css-escape.ts).
+*
+* @module
+*/
+/**
+* Bounds chosen to be far above any real capture yet small enough that a hostile
+* payload cannot exhaust memory or wedge the merge. A `<Skeleton>` set too high
+* is already caught by the per-capture node guard and the serialized-size cap;
+* these are the structural ceilings the schema enforces before either runs.
+*/
+const MAX_TREE_NODES = 5e4;
+const MAX_RULES = 5e4;
+const MAX_RULE_IDS = 5e4;
+const MAX_DECLS_PER_RULE = 1e3;
+const MAX_CONDITIONS = 64;
+const MAX_BREAKPOINTS = 256;
+const MAX_TREE_DEPTH = 1e3;
+/** A single declaration is `prop: value [!important]`; real ones are short. */
+const MAX_DECL_LENGTH = 2e3;
+/** A media/container condition string, generously bounded. */
+const MAX_CONDITION_LENGTH = 1e3;
+/** Diagnostic strings are dev console text, not plate content; keep them small. */
+const MAX_DIAGNOSTIC_MESSAGE = 1e3;
+const MAX_DIAGNOSTIC_DETAIL = 1e3;
+/**
+* ASCII control characters (C0 range + DEL). Written with escaped code points so
+* this module stays a TEXT file: a literal control byte makes git treat it as
+* binary and hides its lines from `grep`. The class is identical in meaning to
+* the previous literal-byte one (NUL through 0x1F, plus 0x7F).
+*/
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/u;
+/**
+* Raw-text / markup terminators that must never appear in generated CSS, even
+* when no bare `<`/`>` is present: HTML comment delimiters, a CDATA opener, and
+* a `</style` raw-text terminator. Shared by the declaration and condition
+* validators (case-insensitive).
+*/
+const RAW_TEXT_TERMINATORS = /<!--|-->|<!\[cdata\[|<\/style/iu;
+/**
+* Accept only a SINGLE CSS declaration of the form `property: value` with an
+* optional trailing `!important`, and only for a layout property the capture
+* path would emit. This is the same allowlist `filterLayoutDecls` applies
+* (`isLayoutProp`), so a posted payload cannot persist paint- or
+* script-adjacent junk the real capture would never produce.
+*
+* Rejects anything that could escape the single-declaration context or the
+* `<style>` raw-text context downstream: rule braces (`{`/`}`), markup angle
+* brackets (`<`/`>`), HTML comment / CDATA delimiters, a `</style` terminator,
+* ASCII control characters, and any extra semicolon-separated declaration. A
+* lone trailing `;` is tolerated (some serializers add one); a second
+* declaration after it is not.
+*/
+function isValidDeclaration(decl) {
+	if (typeof decl !== "string") return false;
+	if (decl.length === 0 || decl.length > MAX_DECL_LENGTH) return false;
+	if (CONTROL_CHARS.test(decl)) return false;
+	if (/[{}<>]/.test(decl)) return false;
+	if (RAW_TEXT_TERMINATORS.test(decl)) return false;
+	const trimmed = decl.trim().replace(/;\s*$/, "");
+	if (trimmed.includes(";")) return false;
+	const colon = trimmed.indexOf(":");
+	if (colon <= 0) return false;
+	const prop = trimmed.slice(0, colon).trim().toLowerCase();
+	const value = trimmed.slice(colon + 1).trim();
+	if (value.length === 0) return false;
+	if (value.replace(/\s*!\s*important\s*$/i, "").trim().length === 0) return false;
+	return isLayoutProp(prop);
+}
+/**
+* Accept only a media/container condition (prelude) of the shape xray actually
+* emits, and reject anything that could break OUT of the `@media`/`@container`
+* prelude into a top-level rule when `classify` interpolates it RAW into the
+* generated CSS (`@media <condition> { ... }`). The capture path produces:
+* synthesized span conditions `(min-width: 768px)` / `(max-width: 767.98px)`,
+* author media text such as `screen and (min-width: 768px)`,
+* `(orientation: landscape)`, comma media lists `screen, print`, and container
+* queries like `(min-width: 400px)`, a named `sidebar (min-width: 400px)`, or a
+* style query `style(--x: 1)`. Authors may also use Media Queries Level 4 range
+* syntax, which browsers serialize into `mediaText`/`containerQuery` verbatim
+* (`(width >= 600px)`, `(400px < width <= 700px)`), so a condition can legitimately
+* carry a bare `<`/`>` — those are allowed.
+*
+* Rejects: rule braces (`{`/`}`) and a `;` — the CSS-rule breakout vectors —
+* CSS comment delimiters (`/*` / `*\/`), the raw-text/markup terminators
+* (`</style`, `<!--`, `-->`, `<![CDATA[`), ASCII control characters, and any
+* over-length string.
+*/
+function isValidCondition(condition) {
+	if (typeof condition !== "string") return false;
+	if (condition.length === 0 || condition.length > MAX_CONDITION_LENGTH) return false;
+	if (CONTROL_CHARS.test(condition)) return false;
+	if (/[{};]/.test(condition)) return false;
+	if (condition.includes("/*") || condition.includes("*/")) return false;
+	if (RAW_TEXT_TERMINATORS.test(condition)) return false;
+	return true;
+}
+/** A finite integer id (plate-local node id), bounded to a sane range. */
+const idSchema = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(Number.MAX_SAFE_INTEGER));
+/** A finite number, no NaN/Infinity (valibot's `number()` already rejects NaN). */
+const finiteNumber = v.pipe(v.number(), v.finite());
+const conditionList = v.pipe(v.array(v.pipe(v.string(), v.check(isValidCondition, "invalid condition"))), v.maxLength(MAX_CONDITIONS));
+const leafSchema = v.picklist([
+	"text",
+	"media",
+	"box"
+]);
+/**
+* Recursive `PlateNode`. `id` is required (every captured node has one);
+* `leaf`, `ref`, and `kids` are optional and mutually constrained by the tree
+* shape the capture emits. `ref` (a stitch) must name a valid plate. Depth and
+* child-count are bounded so a deeply nested or fanned-out payload cannot blow
+* the stack or memory before the node guard runs.
+*/
+const plateNodeSchema = v.pipe(v.object({
+	id: idSchema,
+	leaf: v.optional(leafSchema),
+	ref: v.optional(v.pipe(v.string(), v.check(isValidPlateName, "invalid stitch ref"))),
+	kids: v.optional(v.pipe(v.array(v.lazy(() => plateNodeSchema)), v.maxLength(MAX_TREE_NODES)))
+}), v.check((node) => treeWithinLimits(node), "tree exceeds size or depth limits"));
+function treeWithinLimits(root) {
+	let count = 0;
+	const walk = (node, depth) => {
+		if (depth > MAX_TREE_DEPTH) return false;
+		if (++count > MAX_TREE_NODES) return false;
+		if (typeof node !== "object" || node === null) return true;
+		const kids = node.kids;
+		if (!Array.isArray(kids)) return true;
+		for (const kid of kids) if (!walk(kid, depth + 1)) return false;
+		return true;
+	};
+	return walk(root, 0);
+}
+const plateRuleSchema = v.object({
+	ids: v.pipe(v.array(idSchema), v.maxLength(MAX_RULE_IDS)),
+	decls: v.pipe(v.array(v.pipe(v.string(), v.check(isValidDeclaration, "invalid declaration"))), v.maxLength(MAX_DECLS_PER_RULE)),
+	media: v.optional(conditionList),
+	container: v.optional(conditionList),
+	layered: v.optional(v.boolean()),
+	spec: finiteNumber,
+	order: finiteNumber
+});
+/**
+* The TRANSIENT, dev-only diagnostics that ride on a posted capture
+* (plate.ts / diagnostics.ts). Validated LOOSELY and kept as a KNOWN key so a
+* valid post is not rejected AND the field survives parsing for the server to
+* log before `addCapture` strips it. `code` is checked against the closed
+* DiagnosticCode set; message/detail are bounded strings, never plate content.
+*/
+const diagnosticCode = v.picklist([
+	"unreadable-stylesheet",
+	"unreadable-import",
+	"skipped-dynamic-pseudo",
+	"skipped-pseudo-element",
+	"unsupported-rule",
+	"dropped-tag",
+	"pruned-run",
+	"too-large",
+	"invalid-plate-file"
+]);
+const diagnosticSchema = v.object({
+	code: diagnosticCode,
+	message: v.pipe(v.string(), v.maxLength(MAX_DIAGNOSTIC_MESSAGE)),
+	count: v.optional(finiteNumber),
+	detail: v.optional(v.pipe(v.string(), v.maxLength(MAX_DIAGNOSTIC_DETAIL)))
+});
+/**
+* A `ViewCapture`: a measured width plus an optional `[min, max)` span, the
+* recursive tree, and the rule list. `min < max` when both are present (a
+* zero-width or inverted span is never captured). `diagnostics` is an optional,
+* loosely-validated, transient array preserved through parsing (see above).
+*/
+const viewCaptureSchema = v.pipe(v.object({
+	width: finiteNumber,
+	min: v.optional(finiteNumber),
+	max: v.optional(finiteNumber),
+	tree: plateNodeSchema,
+	rules: v.pipe(v.array(plateRuleSchema), v.maxLength(MAX_RULES)),
+	diagnostics: v.optional(v.pipe(v.array(diagnosticSchema), v.maxLength(MAX_CONDITIONS)))
+}), v.check((c) => c.min === void 0 || c.max === void 0 || c.min < c.max, "capture span min must be below max"));
+/**
+* The full `/__xray` POST body: a valid plate name, the view capture, and the
+* optional union of detected breakpoints (finite positive numbers, deduped and
+* sorted — the same normalization `addCapture` performs, so an unsorted or
+* duplicated post is accepted and normalized rather than rejected).
+*/
+const incomingCaptureSchema = v.object({
+	name: v.pipe(v.string(), v.check(isValidPlateName, "invalid plate name")),
+	capture: viewCaptureSchema,
+	breakpoints: v.optional(v.pipe(v.array(v.pipe(finiteNumber, v.minValue(0))), v.maxLength(MAX_BREAKPOINTS), v.transform((bps) => [...new Set(bps)].toSorted((a, b) => a - b))))
+});
+/**
+* Parse a posted body against the schema. Returns the normalized payload on
+* success or `null` on any structural failure — the caller maps that to a
+* generic `400` and NEVER echoes the payload or its CSS (the plan's error-
+* response decision). Validation throws nothing the caller must format.
+*/
+function parseIncomingCapture(value) {
+	const result = v.safeParse(incomingCaptureSchema, value);
+	return result.success ? result.output : null;
+}
+/**
+* The committed `plates/<name>.json` shape (plate.ts). REUSES `viewCaptureSchema`
+* — and therefore the same strict declaration and condition validators — so a
+* file on disk is held to exactly the trust boundary a POST is: committed plates
+* are untrusted (hand-edited or arriving via git), and `classify` interpolates
+* their `decls`/`media`/`container` into generated CSS just the same. `v` must be
+* the current `PLATE_VERSION` and `name` a valid plate name. `breakpoints` are
+* finite non-negative numbers, bounded but NOT renormalized (the file is the
+* source of truth; the merge layer owns ordering). The persisted `ViewCapture`
+* never carries `diagnostics` (stripped before write), and the schema already
+* makes that field optional, so a file without it is accepted.
+*/
+const plateFileSchema = v.object({
+	v: v.literal(1),
+	name: v.pipe(v.string(), v.check(isValidPlateName, "invalid plate name")),
+	breakpoints: v.pipe(v.array(v.pipe(finiteNumber, v.minValue(0))), v.maxLength(MAX_BREAKPOINTS)),
+	views: v.pipe(v.array(viewCaptureSchema), v.maxLength(MAX_RULES))
+});
+/**
+* Parse a committed plate file against the SAME schema a POST goes through.
+* Returns the typed `PlateFile` on success or `null` on any structural failure
+* (corrupt JSON object, wrong shape, version mismatch, an injected declaration
+* or media/container condition). The disk readers map `null` to an empty plate
+* and the `invalid-plate-file` diagnostic — they never throw, so a malformed or
+* hostile committed plate degrades to empty rather than breaking the build or
+* smuggling raw CSS through `classify`.
+*/
+function parsePlateFile(value) {
+	const result = v.safeParse(plateFileSchema, value);
+	return result.success ? result.output : null;
+}
+//#endregion
 //#region src/index.ts
 /**
 * Vite plugin entry point for xray.
@@ -432,8 +916,11 @@ function xrayVitePlugin(options = {}) {
 	const settleCap = options.settleCap ?? 5e3;
 	const maxNodes = options.maxNodes ?? 4e3;
 	const hud = options.hud ?? false;
+	const recordMode = options.fixtures?.record ?? "manual";
+	const replayMode = options.fixtures?.replay ?? false;
 	let root = process.cwd();
 	const platePath = (name) => resolve(root, platesDir, `${name}.json`);
+	const fixturePath = (name) => resolve(root, platesDir, `${name}.fixture.json`);
 	return [{
 		name: "xray:data",
 		configResolved(config) {
@@ -460,7 +947,7 @@ function xrayVitePlugin(options = {}) {
 		transformIndexHtml: {
 			order: "pre",
 			handler() {
-				if (!capture && !hud) return void 0;
+				if (!capture && !hud && replayMode === false && recordMode === "manual") return;
 				return [{
 					tag: "script",
 					attrs: {
@@ -476,7 +963,7 @@ function xrayVitePlugin(options = {}) {
 		},
 		load(id) {
 			if (id !== RESOLVED_BOOT_ID) return void 0;
-			return bootstrapCode(delay, settleCap, maxNodes, hud, capture);
+			return bootstrapCode(delay, settleCap, maxNodes, hud, capture, recordMode, replayMode);
 		},
 		configureServer(server) {
 			const dir = () => resolve(root, platesDir);
@@ -495,6 +982,15 @@ function xrayVitePlugin(options = {}) {
 					res.end(JSON.stringify(readCoverage(dir())));
 					return;
 				}
+				if (req.method === "GET" && req.url === "/fixtures") {
+					res.setHeader("content-type", "application/json");
+					res.end(JSON.stringify(readFixtures(dir())));
+					return;
+				}
+				if (req.url === "/fixture") {
+					handleFixturePost(req, res, fixturePath);
+					return;
+				}
 				handleCapturePost(req, res, server, platePath);
 			});
 		}
@@ -504,22 +1000,42 @@ function xrayVitePlugin(options = {}) {
 * The injected dev module: boot the client, POST captures back, optionally
 * mount the HUD. The client installs first so the HUD finds the light box store.
 */
-function bootstrapCode(delay, settleCap, maxNodes, hud, capture) {
+function bootstrapCode(delay, settleCap, maxNodes, hud, capture, recordMode, replayMode) {
 	return [
-		`import { installXrayClient } from '@hueest/xray/client'`,
-		...hud ? [`import { installXrayHud } from '@hueest/xray/hud'`] : [],
+		`import { installXrayClient } from '@hueest/xray/internal/client'`,
+		...hud ? [`import { installXrayHud } from '@hueest/xray/internal/hud'`] : [],
 		"installXrayClient({",
 		`  delay: ${delay},`,
 		`  settleCap: ${settleCap},`,
 		`  maxNodes: ${maxNodes},`,
 		`  capture: ${capture},`,
+		`  record: ${JSON.stringify(recordMode)},`,
+		`  replay: ${JSON.stringify(replayMode)},`,
+		"  recordFixtureSink(payload) {",
+		`    return fetch('${ENDPOINT}/fixture', {`,
+		"      method: 'POST',",
+		"      headers: { 'content-type': 'application/json' },",
+		"      body: JSON.stringify(payload),",
+		"    }).then((response) => {",
+		"      if (!response.ok) throw new Error('xray fixture POST failed: ' + response.status)",
+		"    })",
+		"  },",
 		"  sink(payload) {",
-		`    void fetch('${ENDPOINT}', {`,
+		`    return fetch('${ENDPOINT}', {`,
 		"      method: 'POST',",
 		"      headers: { 'content-type': 'application/json' },",
 		"      body: JSON.stringify(payload),",
+		"    }).then((response) => {",
+		"      if (!response.ok) throw new Error('xray sink POST failed: ' + response.status)",
 		"    })",
 		"  },",
+		"  refreshCoverage() {",
+		`    return fetch('${ENDPOINT}/coverage')`,
+		"      .then((response) => response.json())",
+		"      .then((coverage) => {",
+		"        for (const [name, c] of Object.entries(coverage)) globalThis.__XRAY__?.coverage?.set(name, c)",
+		"      })",
+		"  },",
 		"})",
 		...hud ? ["installXrayHud()"] : [],
 		`void fetch('${ENDPOINT}/coverage')`,
@@ -528,6 +1044,10 @@ function bootstrapCode(delay, settleCap, maxNodes, hud, capture) {
 		"    for (const [name, c] of Object.entries(coverage)) globalThis.__XRAY__?.coverage?.set(name, c)",
 		"  })",
 		"  .catch(() => {})",
+		`void fetch('${ENDPOINT}/fixtures')`,
+		"  .then((response) => response.json())",
+		"  .then((fixtures) => { globalThis.__XRAY__?.fixtures?.seed?.(fixtures) })",
+		"  .catch(() => {})",
 		"if (import.meta.hot) {",
 		"  import.meta.hot.on('xray:plate', (data) => {",
 		"    globalThis.__XRAY__?.updatePlate?.(data.name, data.plate)",
@@ -537,35 +1057,40 @@ function bootstrapCode(delay, settleCap, maxNodes, hud, capture) {
 		""
 	].join("\n");
 }
+/**
+* Print a plate's diagnostics to the Vite server output using the SAME grouped
+* header + shared formatter the browser console uses (diagnostics.ts), so the
+* two can never drift. Prefers Vite's logger (it preserves the formatting);
+* falls back to `console.warn`. No-op when there are no diagnostics.
+*/
+function reportServerDiagnostics(server, name, diagnostics) {
+	if (!diagnostics || diagnostics.length === 0) return;
+	const text = [diagnosticsHeader(name), ...diagnostics.map((d) => formatDiagnostic(d))].join("\n");
+	const logger = server.config?.logger;
+	if (logger) logger.warn(text);
+	else console.warn(text);
+}
 /** A committed plate file past this is almost always a `<Skeleton>` set too high. */
 const MAX_PLATE_BYTES = 2e6;
+/**
+* Hard ceiling on the POST body we will buffer. A single posted capture is one
+* view (smaller than the accumulated plate file the `MAX_PLATE_BYTES` cap
+* guards), so this sits above the plate cap with headroom and exists only to
+* stop an oversized or runaway body from being read into memory. Enforced both
+* up front from `content-length` and while streaming, so a lying or absent
+* `content-length` cannot get past it. The dev endpoint is local and
+* unauthenticated, so this is the real backstop, not the header.
+*/
+const MAX_BODY_BYTES = 4e6;
+/** The only content type the capture client posts; anything else is rejected up front. */
+function isJsonContentType(value) {
+	const header = Array.isArray(value) ? value[0] : value;
+	if (typeof header !== "string") return false;
+	return /^application\/json\b/i.test(header.trim());
+}
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
-function isNumberArray(value) {
-	return Array.isArray(value) && value.every((item) => typeof item === "number");
-}
-function isStringArray(value) {
-	return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-function isLeafKind(value) {
-	return value === "text" || value === "media" || value === "box";
-}
-function isPlateNode(value) {
-	return isRecord(value) && typeof value.id === "number" && (!("leaf" in value) || isLeafKind(value.leaf)) && (!("ref" in value) || typeof value.ref === "string") && (!("kids" in value) || Array.isArray(value.kids) && value.kids.every(isPlateNode));
-}
-function isPlateRule(value) {
-	return isRecord(value) && isNumberArray(value.ids) && isStringArray(value.decls) && typeof value.spec === "number" && typeof value.order === "number" && (!("media" in value) || isStringArray(value.media)) && (!("container" in value) || isStringArray(value.container)) && (!("layered" in value) || typeof value.layered === "boolean");
-}
-function isViewCapture(value) {
-	return isRecord(value) && typeof value.width === "number" && (!("min" in value) || typeof value.min === "number") && (!("max" in value) || typeof value.max === "number") && isPlateNode(value.tree) && Array.isArray(value.rules) && value.rules.every(isPlateRule);
-}
-function isPlateFile(value) {
-	return isRecord(value) && typeof value.v === "number" && typeof value.name === "string" && isNumberArray(value.breakpoints) && Array.isArray(value.views) && value.views.every(isViewCapture);
-}
-function isIncomingCapture(value) {
-	return isRecord(value) && typeof value.name === "string" && isViewCapture(value.capture) && (!("breakpoints" in value) || isNumberArray(value.breakpoints));
-}
 /** Send the merged plate (and its disk coverage) over the HMR event so the
 * client hot-swaps it in place and the HUD updates its band display. */
 function announcePlate(ws, name, plateFile) {
@@ -620,6 +1145,123 @@ function readCoverage(dir) {
 	}
 	return out;
 }
+/** The on-disk Fixture sidecar shape (ADR 0015): version, plate name, and the
+* OPAQUE devalue string. The node side never parses `data` — it is the browser
+* dev client's job (it has the live runtime). */
+const FIXTURE_VERSION = 1;
+const FIXTURE_SUFFIX = ".fixture.json";
+/** A recorded Fixture sidecar — `data` is the verbatim devalue string, treated
+* as opaque text server-side. */
+function isFixtureFile(value) {
+	return isRecord(value) && typeof value.v === "number" && typeof value.name === "string" && typeof value.data === "string";
+}
+/**
+* All recorded Fixtures as `{ <name>: <devalueString> }`, read from the
+* `<name>.fixture.json` sidecars (ADR 0015). The map values are the OPAQUE
+* devalue strings exactly as written — the node side never parses them; the
+* browser dev client owns the devalue decode. The `.fixture.json` suffix keeps
+* these distinct from Plate files (`isValidPlateName` rejects the dotted name, so
+* `readCoverage` never picks them up — Fixtures never leak into Plate coverage).
+*
+* @internal
+*/
+function readFixtures(dir) {
+	const out = {};
+	let entries;
+	try {
+		entries = readdirSync(dir, {
+			recursive: true,
+			encoding: "utf8"
+		});
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		const rel = entry.replaceAll("\\", "/");
+		if (!rel.endsWith(FIXTURE_SUFFIX)) continue;
+		const name = rel.slice(0, -13);
+		if (!isValidPlateName(name)) continue;
+		let raw;
+		try {
+			raw = readFileSync(resolve(dir, rel), "utf8");
+		} catch {
+			continue;
+		}
+		try {
+			const parsed = JSON.parse(raw);
+			if (isFixtureFile(parsed) && parsed.v === FIXTURE_VERSION) out[name] = parsed.data;
+		} catch {}
+	}
+	return out;
+}
+/**
+* Write a recorded Fixture sidecar (ADR 0015). Reuses the capture endpoint's
+* front-door checks (method, content type, declared/streamed size cap) and the
+* `isValidPlateName` gate, but treats the devalue `data` payload as OPAQUE TEXT:
+* it is validated only as a string and written verbatim, never eval'd or parsed
+* server-side. The sidecar lives NEXT TO the Plate but is never merged into it,
+* so the persisted Plate stays purely structural.
+*
+* @internal
+*/
+function handleFixturePost(req, res, fixturePath) {
+	if (req.method !== "POST") {
+		res.statusCode = 405;
+		res.end();
+		return;
+	}
+	if (!isJsonContentType(req.headers?.["content-type"])) {
+		res.statusCode = 415;
+		res.end("unsupported media type");
+		return;
+	}
+	const declared = Number(Array.isArray(req.headers?.["content-length"]) ? req.headers["content-length"][0] : req.headers?.["content-length"]);
+	if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+		res.statusCode = 413;
+		res.end("payload too large");
+		return;
+	}
+	let body = "";
+	let bytes = 0;
+	let aborted = false;
+	req.on("data", (chunk) => {
+		if (aborted) return;
+		const text = typeof chunk === "string" ? chunk : chunk?.toString() ?? "";
+		bytes += Buffer.byteLength(text);
+		if (bytes > MAX_BODY_BYTES) {
+			aborted = true;
+			res.statusCode = 413;
+			res.end("payload too large");
+			req.destroy?.();
+			return;
+		}
+		body += text;
+	});
+	req.on("end", () => {
+		if (aborted) return;
+		try {
+			const raw = JSON.parse(body);
+			if (!isRecord(raw) || typeof raw.name !== "string" || !isValidPlateName(raw.name) || typeof raw.data !== "string") {
+				res.statusCode = 400;
+				res.end("invalid fixture payload");
+				return;
+			}
+			const file = fixturePath(raw.name);
+			const sidecar = {
+				v: FIXTURE_VERSION,
+				name: raw.name,
+				data: raw.data
+			};
+			mkdirSync(dirname(file), { recursive: true });
+			writeFileSync(file, `${JSON.stringify(sidecar, null, 1)}\n`);
+			res.statusCode = 204;
+			res.end();
+		} catch {
+			res.statusCode = 400;
+			res.end("invalid fixture payload");
+		}
+	});
+}
 /**
 * Fold a posted capture into its plate file and hot-swap the plate in place.
 *
@@ -631,20 +1273,46 @@ function handleCapturePost(req, res, server, platePath) {
 		res.end();
 		return;
 	}
+	if (!isJsonContentType(req.headers?.["content-type"])) {
+		res.statusCode = 415;
+		res.end("unsupported media type");
+		return;
+	}
+	const declared = Number(Array.isArray(req.headers?.["content-length"]) ? req.headers["content-length"][0] : req.headers?.["content-length"]);
+	if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+		res.statusCode = 413;
+		res.end("payload too large");
+		return;
+	}
 	let body = "";
+	let bytes = 0;
+	let aborted = false;
 	req.on("data", (chunk) => {
-		body += typeof chunk === "string" ? chunk : chunk?.toString() ?? "";
+		if (aborted) return;
+		const text = typeof chunk === "string" ? chunk : chunk?.toString() ?? "";
+		bytes += Buffer.byteLength(text);
+		if (bytes > MAX_BODY_BYTES) {
+			aborted = true;
+			res.statusCode = 413;
+			res.end("payload too large");
+			req.destroy?.();
+			return;
+		}
+		body += text;
 	});
 	req.on("end", () => {
+		if (aborted) return;
 		try {
-			const payload = JSON.parse(body);
-			if (!isIncomingCapture(payload) || !isValidPlateName(payload.name)) {
+			const payload = parseIncomingCapture(JSON.parse(body));
+			if (!payload) {
 				res.statusCode = 400;
 				res.end("invalid capture payload");
 				return;
 			}
+			reportServerDiagnostics(server, payload.name, payload.capture.diagnostics);
 			const file = platePath(payload.name);
-			const existing = readPlateFile(file);
+			const { plateFile: existing, invalid } = loadPlateFile(file);
+			if (invalid) reportServerDiagnostics(server, payload.name, [makeDiagnostic("invalid-plate-file", { detail: `${payload.name}.json` })]);
 			const next = addCapture(existing, payload.name, payload.capture, payload.breakpoints ?? []);
 			const serialized = `${JSON.stringify(next, null, 1)}\n`;
 			if (existing !== null && `${JSON.stringify(existing, null, 1)}\n` === serialized) {
@@ -663,33 +1331,47 @@ function handleCapturePost(req, res, server, platePath) {
 			announcePlate(server.ws, payload.name, next);
 			res.statusCode = 204;
 			res.end();
-		} catch (error) {
+		} catch {
 			res.statusCode = 400;
-			res.end(error instanceof Error ? error.message : "invalid capture payload");
+			res.end("invalid capture payload");
 		}
 	});
 }
+function readPlateFile(file) {
+	return loadPlateFile(file).plateFile;
+}
 /**
-* Names come from import specifiers and POST bodies — keep them inside the plates dir.
-*
-* @internal
+* Read and validate a committed plate file, distinguishing "no file" from
+* "file present but unreadable". `invalid` is true ONLY when the file exists
+* but is corrupt JSON, the wrong shape, or a version mismatch — a missing file
+* is the normal pre-capture state and is not flagged. Callers use `invalid` to
+* warn (same diagnostics vocabulary) that an existing plate was ignored.
 */
-function isValidPlateName(name) {
-	return /^[\w-]+(\/[\w-]+)*$/.test(name);
-}
-function readPlateFile(file) {
+function loadPlateFile(file) {
 	let raw;
 	try {
 		raw = readFileSync(file, "utf8");
 	} catch {
-		return null;
+		return {
+			plateFile: null,
+			invalid: false
+		};
 	}
 	try {
-		const plateFile = JSON.parse(raw);
-		if (!isPlateFile(plateFile) || plateFile.v !== 1) return null;
-		return plateFile;
+		const plateFile = parsePlateFile(JSON.parse(raw));
+		if (!plateFile) return {
+			plateFile: null,
+			invalid: true
+		};
+		return {
+			plateFile,
+			invalid: false
+		};
 	} catch {
-		return null;
+		return {
+			plateFile: null,
+			invalid: true
+		};
 	}
 }
 /**
@@ -723,4 +1405,4 @@ function renderPlateModule(merged) {
 	return `${refs.map((name, i) => `import __xr${i} from ${JSON.stringify(VIRTUAL_PREFIX + name)}`).join("\n")}\nexport default Object.assign(${json}, { refs: { ${refs.map((name, i) => `${JSON.stringify(name)}: __xr${i}`).join(", ")} } })`;
 }
 //#endregion
-export { addCapture, collectRefs, handleCapturePost, isValidPlateName, mergeViews, readCoverage, renderPlateModule, xrayVitePlugin };
+export { addCapture, collectRefs, handleCapturePost, handleFixturePost, isValidPlateName, mergeViews, readCoverage, readFixtures, renderPlateModule, xrayVitePlugin };