@hueest/xray 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,10 +1,17 @@
 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";
-const SPEC_GATE = 2e7;
+/**
+* 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";
 /** Fixed renderer-owned classes every rendered node carries. */
 const ROOT_CLASS = "xr-root";
 const NODE_CLASS = "xr-node";
@@ -14,10 +21,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,39 +39,75 @@ 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);
-}
-/* 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)) }
+  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: a single text LINE reads as a rounded bar; a multi-line
+   text BLOCK as a soft rect (a tall pill misreads as a button); media carries
+   the author radius, defaulting to the same soft rect. Re-theme any kind via
+   [data-xr-root] .${LEAF_CLASS}-text { ... }. */
+.${LEAF_CLASS}-text { border-radius: var(--xr-bone-text-border-radius, 999px) }
+.${LEAF_CLASS}-text-block { border-radius: var(--xr-bone-text-block-border-radius, var(--xr-bone-border-radius, 4px)) }
+.${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) {
 	return {
-		v: 1,
+		v: 2,
 		name,
 		tree: null,
 		css: ""
@@ -78,12 +128,13 @@ function nodeClass(node) {
 	return NODE_CLASS + (node.leaf ? ` ${LEAF_CLASS} ${LEAF_CLASS}-${node.leaf}` : "") + (node.cls ? ` ${node.cls}` : "");
 }
 /**
-* Whether this subtree holds a stitch (`ref`) anywhere — a stitched subtree
-* can't collapse to a flat string, since a `ref` resolves to a child plate at
-* render time and must stay a mount point.
+* Whether this subtree holds a render-time DYNAMIC node anywhere — a stitch
+* (`ref`, a mount point resolved to a child plate) or a template (`count`, a cell
+* the adapter repeats). Either keeps the subtree from collapsing to one flat
+* string, since both are expanded at render rather than baked into the markup.
 */
-function hasStitch(node) {
-	return node.ref !== void 0 || (node.kids?.some(hasStitch) ?? false);
+function hasDynamic(node) {
+	return node.ref !== void 0 || node.count !== void 0 || (node.kids?.some(hasDynamic) ?? false);
 }
 /** Serialize a stitch-free subtree to one HTML string (caller guarantees no `ref` below). */
 function toHtml(node) {
@@ -91,10 +142,13 @@ function toHtml(node) {
 	return `<div class="${nodeClass(node)}">${kids}</div>`;
 }
 /**
-* Serialize a node list into chunks: each maximal stitch-free run becomes one
-* HTML `string`; a `ref` node becomes `{ r }`; a node that isn't itself a stitch
-* but holds one deeper stays a real element (`{ c, k }`) and recurses. Mirrors
-* the element shape the runtime renderer would otherwise build per node.
+* Serialize a node list into chunks: each maximal run with no render-time dynamic
+* node becomes one HTML `string`; a `ref` node becomes `{ r }`; a `count` node
+* becomes `{ t: html, n }` (its cell's HTML once + the repeat count); a node that
+* isn't itself dynamic but holds one deeper stays a real element (`{ c, k }`) and
+* recurses. Mirrors the element shape the runtime renderer would otherwise build
+* per node. A `count` cell is guaranteed stitch-free by the capture pass, so its
+* `toHtml` is a plain string the adapter repeats.
 */
 function toChunks(nodes) {
 	const out = [];
@@ -106,12 +160,16 @@ function toChunks(nodes) {
 		}
 	};
 	for (const node of nodes) {
-		if (!hasStitch(node)) {
+		if (!hasDynamic(node)) {
 			buf += toHtml(node);
 			continue;
 		}
 		flush();
 		if (node.ref !== void 0) out.push({ r: node.ref });
+		else if (node.count !== void 0) out.push({
+			t: toHtml(node),
+			n: node.count
+		});
 		else out.push({
 			c: nodeClass(node),
 			k: toChunks(node.kids ?? [])
@@ -148,217 +206,15 @@ function serializePlate(merged) {
 		css
 	};
 }
-//#endregion
-//#region src/breakpoints.ts
-/** The view interval `[min, max)` a given viewport width falls into. */
-function regimeFor(width, breakpoints) {
-	let min;
-	let max;
-	for (const bp of breakpoints) if (bp <= width) min = bp;
-	else {
-		max = bp;
-		break;
-	}
-	return {
-		...min === void 0 ? {} : { min },
-		...max === void 0 ? {} : { max }
-	};
-}
-//#endregion
-//#region src/classify.ts
-/**
-* Turn id-form rules + an id-tree into the shipped plate: each distinct
-* `(tier, media, declarations)` becomes one class, named by a per-plate
-* sequential id (`[data-xr-root] .xr-<plate>-<n>`), and every node carries the
-* class tokens it needs instead of an id (ADR 0007). The id is a plain counter,
-* not a content hash: the plate prefix already keeps tokens disjoint across plates
-* (the stitch-isolation guarantee), so a per-plate counter is collision-free by
-* construction — and low-entropy ids compress far better than random hashes
-* (~31% smaller brotli on a real plate; see the ADR 0007 amendment). Rules stay
-* unlayered; the existing cascade is reproduced by emission order (losers
-* first), so the classes are emitted in `(layered, spec, order)` order exactly
-* as `renderRules` did.
-*
-* 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 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();
-	const usage = /* @__PURE__ */ new Map();
-	const emitOrder = [];
-	const nodeClasses = /* @__PURE__ */ new Map();
-	for (const rule of sorted) {
-		if (rule.decls.length === 0) continue;
-		const decls = rule.decls.join("; ");
-		const media = rule.media ?? [];
-		const container = rule.container ?? [];
-		const tier = SPEC_FOLD === "full" ? String(rule.spec) : tierLabel(rule.spec);
-		const key = `${rule.layered ? "l" : ""} ${tier} ${media.join(" && ")} ${container.join(" && ")} ${decls}`;
-		let name = nameForKey.get(key);
-		if (name === void 0) {
-			name = classBase + nameForKey.size.toString(36);
-			nameForKey.set(key, name);
-			body.set(name, {
-				media,
-				container,
-				decls
-			});
-			usage.set(name, {
-				root: false,
-				desc: false
-			});
-			emitOrder.push(name);
-		}
-		const ids = rule.ids.length === 0 ? [0] : rule.ids;
-		for (const id of ids) {
-			const u = usage.get(name);
-			if (!u) throw new Error(`missing usage entry for ${name}`);
-			if (id === 0) u.root = true;
-			else u.desc = true;
-			let list = nodeClasses.get(id);
-			if (!list) {
-				list = [];
-				nodeClasses.set(id, list);
-			}
-			if (!list.includes(name)) list.push(name);
-		}
-	}
-	const lines = [];
-	for (const name of emitOrder) {
-		const item = body.get(name);
-		const u = usage.get(name);
-		if (!item || !u) throw new Error(`missing class body for ${name}`);
-		const { media, container, decls } = item;
-		const sels = [];
-		if (u.root) sels.push(`[${ROOT_ATTR}].${name}`);
-		if (u.desc) sels.push(`[${ROOT_ATTR}] .${name}`);
-		let text = `${sels.join(", ")} { ${decls} }`;
-		for (const condition of media.toReversed()) text = `@media ${condition} { ${text} }`;
-		for (const condition of container.toReversed()) text = `@container ${condition} { ${text} }`;
-		lines.push(text);
-	}
-	return {
-		tree: render(tree, nodeClasses),
-		css: lines.join("\n")
-	};
-}
-/** Strip ids, attach content-class tokens — the shipped tree shape (ADR 0007). */
-function render(node, classes) {
-	const out = {};
-	if (node.leaf) out.leaf = node.leaf;
-	if (node.ref !== void 0) out.ref = node.ref;
-	const cls = classes.get(node.id);
-	if (cls && cls.length > 0) out.cls = cls.join(" ");
-	if (node.kids) out.kids = node.kids.map((kid) => render(kid, classes));
-	return out;
-}
-/** 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, "_");
-}
-/**
-* What the class identity keys on, alongside media + declarations:
-*  - `'tier'`: the discrete cascade tier — smaller (more bodies dedupe), but a
-*    rare same-tier inversion within the continuous `author` band can mis-order
-*    one property on one node (ADR 0007). The default.
-*  - `'full'`: the exact `spec` — provably no inversion, marginally larger.
-* One-line flip if QA ever surfaces a mis-order.
-*/
-const SPEC_FOLD = "full";
-function tierLabel(spec) {
-	if (spec <= -2) return "ctx";
-	if (spec === -1) return "fb";
-	if (spec >= 2e7) return "gate";
-	if (spec >= 1e7) return "inl";
-	if (spec >= 9e6) return "leaf";
-	return "au";
-}
-//#endregion
-//#region src/merge.ts
 /**
-* Turn the per-view captures in a plate file into the one plate a Skeleton
-* renders.
-*
-* Each view is kept whole — its own subtree, its own ids, its own rules —
-* and shown only across the viewport range it owns, via `@media display:none`
-* gates. We do NOT merge the views' trees into one. An earlier design (ADR
-* 0004) did, sharing common structure and forking the rest, but aligning two
-* genuinely-different DOM trees (mobile stacked vs desktop two-column) without
-* stable keys proved unreliable: every heuristic mis-paired some nodes and
-* remapped one view's rules onto another's elements, corrupting both. A lone
-* capture is pixel-faithful; keeping each view lone preserves that. The cost
-* is a larger plate (roughly the sum of the views) — bounded by the plate
-* size cap — in exchange for correctness.
-*
-* Pure data-in/data-out — runs in node (plugin load) and in tests.
-*/
-function mergeViews(file) {
-	const views = file.views;
-	if (views.length === 0) return emptyPlate(file.name);
-	if (views.length === 1) {
-		const [only] = views;
-		if (!only) return emptyPlate(file.name);
-		const { tree, css } = classify(only.rules, only.tree, file.name);
-		return {
-			v: 1,
-			name: file.name,
-			tree,
-			css
-		};
-	}
-	const starts = views.map((r) => regimeFor(r.width, file.breakpoints).min ?? 0);
-	let nextId = 1;
-	const rootKids = [];
-	const rules = [];
-	views.forEach((view, i) => {
-		const idMap = /* @__PURE__ */ new Map();
-		const kids = (view.tree.kids ?? []).map((kid) => cloneWithIds(kid, idMap, () => nextId++));
-		rootKids.push(...kids);
-		rules.push(...remapRules(view.rules, idMap));
-		const lo = i === 0 ? 0 : starts[i] ?? 0;
-		const hi = i === views.length - 1 ? Number.POSITIVE_INFINITY : starts[i + 1] ?? 0;
-		for (const kid of kids) {
-			if (lo > 0) rules.push(gate(kid.id, `(max-width: ${lo - .02}px)`));
-			if (hi !== Number.POSITIVE_INFINITY) rules.push(gate(kid.id, `(min-width: ${hi}px)`));
-		}
-	});
-	const { tree, css } = classify(rules, {
-		id: 0,
-		kids: rootKids
-	}, file.name);
-	return {
-		v: 1,
-		name: file.name,
-		tree,
-		css
-	};
-}
-function gate(id, condition) {
-	return {
-		ids: [id],
-		decls: ["display: none !important"],
-		media: [condition],
-		spec: SPEC_GATE,
-		order: id
-	};
-}
-/** Deep-clone a captured subtree into fresh ids, recording the mapping. */
-function cloneWithIds(node, idMap, allocate) {
-	const id = allocate();
-	idMap.set(node.id, id);
-	const kids = node.kids?.map((kid) => cloneWithIds(kid, idMap, allocate));
-	return {
-		id,
-		...node.leaf ? { leaf: node.leaf } : {},
-		...node.ref !== void 0 ? { ref: node.ref } : {},
-		...kids ? { kids } : {}
-	};
-}
-/** Distinct plate names referenced by the tree's stitches, in first-seen order. */
+* Distinct plate names referenced by the tree's stitches, in first-seen order.
+* Walks a `RenderNode` tree (the stored, post-classify shape), so it drives the
+* gen-side stitch import graph straight off a `StoredPlate.tree`
+* (`renderPlateModule`, index.ts). Relocated here from the now-deleted `merge.ts`
+* in the ADR 0022 cutover — it is the one node-side primitive that survived the
+* `mergeViews`/`addCapture` removal (the multi-View merge/gate now lives in the
+* in-browser `serializePlateIR`, project.ts).
+*/
 function collectRefs(tree) {
 	const names = [];
 	const seen = /* @__PURE__ */ new Set();
@@ -372,26 +228,245 @@ function collectRefs(tree) {
 	if (tree) visit(tree);
 	return names;
 }
-function remapRules(rules, idMap) {
-	return rules.map((rule) => ({
-		...rule,
-		ids: rule.ids.map((id) => idMap.get(id) ?? id)
-	}));
-}
-/** Fold a fresh capture into the plate file: union breakpoints, one capture per view. */
-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 byView = /* @__PURE__ */ new Map();
-	for (const view of views) byView.set(spanKey(view.width), view);
+//#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 {
-		v: 1,
-		name,
-		breakpoints: allBreakpoints,
-		views: [...byView.values()].toSorted((a, b) => a.width - b.width)
+		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, opacity:0, script/style/etc.)",
+	"dropped-subset": "dropped bones wholly inside a larger solid bone — the superset renders the same area (overlapping bones collapse to their union)",
+	"dropped-cropped": "dropped bones below the fold (off-screen at capture, in the viewport or a scroll container); real content fills in below without shifting the visible skeleton",
+	"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/validate.ts
+/**
+* Structural validation of a posted/committed `StoredPlate`, plus the
+* single-CSS-declaration / media-condition validators, for the dev `/__xray`
+* endpoint and disk reads.
+*
+* 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 artifact shape xray itself produces. After the
+* ADR 0022 cutover the dev client posts a finished `StoredPlate` — the whole
+* Plate already projected in the browser (`serializePlateIR`) — so `parseStoredPlate`
+* is the single validator: a post-classify `RenderNode` tree plus an
+* already-classified css blob, guarded for `<style>`-breakout only (the per-decl
+* allowlist no longer applies to a finished css string; see `isValidPlateCss`).
+* The per-declaration / per-condition validators (`isValidDeclaration` /
+* `isValidCondition`) remain exported helpers — the css blob already passed them
+* AT CAPTURE TIME in the browser. Validation is necessary but not sufficient: a
+* committed `StoredPlate` 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_BREAKPOINTS = 256;
+const MAX_TREE_DEPTH = 1e3;
+/**
+* A template node's repeat count (Phase 2). Far above any real feed, yet bounded
+* so a hostile `count` cannot drive an unbounded render-time string `.repeat`.
+*/
+const MAX_TEMPLATE_COUNT = 1e4;
+/** A single declaration is `prop: value [!important]`; real ones are short. */
+const MAX_DECL_LENGTH = 2e3;
+/**
+* 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;
+/** A finite number, no NaN/Infinity (valibot's `number()` already rejects NaN). */
+const finiteNumber = v.pipe(v.number(), v.finite());
+const leafSchema = v.picklist([
+	"text",
+	"text-block",
+	"media",
+	"box"
+]);
+/**
+* Depth + total-node guard shared by the recursive node schema. The recursive
+* `array(lazy(...))` bounds breadth per level; this guards total depth so a long
+* thin chain cannot recurse without limit, and the running `count` bounds the
+* total node budget so a fanned-out payload cannot exhaust memory.
+*/
+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);
+}
+/** A finished plate's css blob, generously bounded (post-classify, whole-plate). */
+const MAX_PLATE_CSS_LENGTH = 4e6;
+/**
+* A NUL byte — the one control character that must never reach the rendered
+* `<style>`. Unlike the per-declaration validator, the whole-plate css blob
+* legitimately carries newlines/tabs (`classify` joins rules with `\n`), so the
+* broad `CONTROL_CHARS` class does NOT apply here.
+*/
+const NUL = /\u0000/u;
+/**
+* Validate a STORED, already-classified css blob (ADR 0022 cutover). The trust
+* model differs from a pre-classify `decls[]` array: a `StoredPlate.css` is the
+* WHOLE plate's content-addressed CSS — a string of selectors, `{ ... }` rule
+* blocks, and `@media`/`@container` at-rules — so the per-declaration
+* `isValidDeclaration` allowlist (which forbids `{}` and re-checks `isLayoutProp`)
+* cannot apply: it would reject every real plate. Braces, newlines, and bare
+* `<`/`>` (Media Queries Level 4 range syntax, `@media (width >= 600px)`) are all
+* legitimate here. The css was produced by `filterLayoutDecls`-filtered decls at
+* capture time in the browser; on disk we guard only the security boundary the
+* render path also enforces: no `<style>` raw-text breakout. Reject the raw-text /
+* markup terminators (`</style`, `<!--`, `-->`, `<![CDATA[`) and a NUL byte, and
+* bound the length. The render path independently escapes these (`escapeStyleText`,
+* css-escape.ts) — that stays as the belt; this is the braces. A `StoredPlate` is
+* untrusted exactly as a `PlateFile` was (hand-edited / arriving via git).
+*/
+function isValidPlateCss(css) {
+	if (typeof css !== "string") return false;
+	if (css.length > MAX_PLATE_CSS_LENGTH) return false;
+	if (NUL.test(css)) return false;
+	if (RAW_TEXT_TERMINATORS.test(css)) return false;
+	return true;
+}
+/**
+* Recursive `RenderNode` — the POST-classify tree shape (plate.ts): no `id` (ids
+* are stripped at classify), an optional content-class string `cls`, and the same
+* `leaf`/`ref`/`count`/`kids` the renderer reads. Mirrors `plateNodeSchema` minus
+* `id`, plus a bounded `cls`. Depth/breadth bounded by the shared `treeWithinLimits`.
+*/
+const renderNodeSchema = v.pipe(v.object({
+	leaf: v.optional(leafSchema),
+	ref: v.optional(v.pipe(v.string(), v.check(isValidPlateName, "invalid stitch ref"))),
+	cls: v.optional(v.pipe(v.string(), v.maxLength(MAX_DECL_LENGTH))),
+	count: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(MAX_TEMPLATE_COUNT))),
+	kids: v.optional(v.pipe(v.array(v.lazy(() => renderNodeSchema)), v.maxLength(MAX_TREE_NODES)))
+}), v.check((node) => treeWithinLimits(node), "tree exceeds size or depth limits"));
+/**
+* The committed/posted `StoredPlate` shape AFTER the ADR 0022 cutover (plate.ts):
+* the whole plate already projected in the browser. Validated to the SAME trust
+* boundary a `PlateFile` was — a `StoredPlate` on disk is untrusted (hand-edited
+* or arriving via git). `tree` is a `RenderNode` (post-classify, nullable for a
+* capture-less plate); `css` is the already-classified blob, guarded for
+* `<style>`-breakout only (`isValidPlateCss`, above). `breakpoints` are finite
+* non-negative numbers, bounded but NOT renormalized (the file is the source of
+* truth). `v` must be the current `PLATE_VERSION`.
+*/
+const storedPlateSchema = v.object({
+	v: v.literal(2),
+	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)),
+	tree: v.nullable(renderNodeSchema),
+	css: v.pipe(v.string(), v.check(isValidPlateCss, "invalid plate css"))
+});
+/**
+* Parse a committed/posted `StoredPlate` against its schema (the ADR 0022 cutover
+* shape). Returns the typed `StoredPlate` on success or `null` on any structural
+* failure (corrupt object, wrong shape, version mismatch, an injected `<style>`
+* terminator in the css, an oversized/over-deep tree). The disk readers and the
+* POST handler map `null` to an empty plate / a generic 400 and never echo the
+* payload — a malformed or hostile stored plate degrades to empty rather than
+* breaking the build or smuggling a `<style>`-escaping css blob through render.
+*/
+function parseStoredPlate(value) {
+	const result = v.safeParse(storedPlateSchema, value);
+	return result.success ? result.output : null;
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -432,8 +507,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) {
@@ -446,7 +524,7 @@ function xrayVitePlugin(options = {}) {
 			if (!id.startsWith(RESOLVED_PREFIX)) return void 0;
 			const name = id.slice(RESOLVED_PREFIX.length);
 			if (!isValidPlateName(name)) return renderPlateModule(emptyPlate(name));
-			return renderPlateModule(readPlate(platePath(name), name));
+			return renderPlateModule(readStoredPlate(platePath(name)) ?? emptyPlate(name), name);
 		}
 	}, {
 		name: "xray:dev",
@@ -460,7 +538,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 +554,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);
@@ -485,7 +563,7 @@ function xrayVitePlugin(options = {}) {
 				if (!file.startsWith(dir()) || !file.endsWith(".json")) return;
 				const name = relative(dir(), file).slice(0, -5);
 				if (!isValidPlateName(name)) return;
-				announcePlate(server.ws, name, readPlateFile(file));
+				announcePlate(server.ws, name, readStoredPlate(file));
 			};
 			server.watcher.on("add", onPlateFile);
 			server.watcher.on("change", onPlateFile);
@@ -495,6 +573,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 +591,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 +635,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,58 +648,90 @@ 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. The posted StoredPlate is the
+* whole projected Plate the `MAX_PLATE_BYTES` cap guards, so this sits above the
+* plate cap with headroom (the JSON envelope + diagnostics add a little) 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));
+/**
+* Derive the HUD coverage bands from a StoredPlate's `breakpoints` (ADR 0022
+* cutover). Per-View spans no longer exist on disk — a post-cutover StoredPlate
+* sweeps ALL widths in one session, so coverage is complete per-Plate and the
+* bands are just the breakpoint partition: each adjacent breakpoint pair is a
+* covered band, the first band open-min, the last open-max. `breakpoints=[b1,b2]`
+* → `[{max:b1},{min:b1,max:b2},{min:b2}]`; `breakpoints=[]` → one open band `[{}]`.
+* Keeps the `xray:plate`/coverage `spans` shape (`{min?, max?}[]`) identical — only
+* the SOURCE changes (derived from breakpoints, not read off per-View captures).
+*/
+function spansFromBreakpoints(breakpoints) {
+	const sorted = [...breakpoints].toSorted((a, b) => a - b);
+	if (sorted.length === 0) return [{}];
+	const spans = [{ max: sorted[0] }];
+	for (let i = 0; i < sorted.length - 1; i++) spans.push({
+		min: sorted[i],
+		max: sorted[i + 1]
+	});
+	spans.push({ min: sorted.at(-1) });
+	return spans;
 }
-/** 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) {
-	const merged = plateFile ? mergeViews({
-		...plateFile,
-		name
-	}) : emptyPlate(name);
+/** Send the stored plate (lowered to chunks) and its derived coverage bands over
+* the HMR event so the client hot-swaps it in place and the HUD updates its band
+* display. The gen-side runs `serializePlate(stored)` (the Bundle seam) here; the
+* `spans` derive from the stored breakpoints (the per-View list is gone). */
+function announcePlate(ws, name, stored) {
+	const breakpoints = stored?.breakpoints ?? [];
+	const plate = stored ? serializePlate({
+		v: stored.v,
+		name,
+		tree: stored.tree,
+		css: stored.css
+	}) : serializePlate(emptyPlate(name));
 	ws.send({
 		type: "custom",
 		event: "xray:plate",
 		data: {
 			name,
-			plate: serializePlate(merged),
-			breakpoints: plateFile?.breakpoints ?? [],
-			spans: (plateFile?.views ?? []).map((view) => ({
-				min: view.min,
-				max: view.max
-			}))
+			plate,
+			breakpoints,
+			spans: spansFromBreakpoints(breakpoints)
 		}
 	});
 }
 /**
-* Per-plate breakpoints + captured spans, read from the committed plate files.
+* Per-plate breakpoints + derived coverage bands, read from the committed
+* StoredPlate files. The `spans` derive from each plate's `breakpoints` (ADR 0022
+* cutover — per-View spans no longer exist on disk; a StoredPlate sweeps all
+* widths in one session, so its coverage is complete).
 *
 * @internal
 */
@@ -608,20 +751,140 @@ function readCoverage(dir) {
 		if (!rel.endsWith(".json")) continue;
 		const name = rel.slice(0, -5);
 		if (!isValidPlateName(name)) continue;
-		const plateFile = readPlateFile(resolve(dir, rel));
-		if (!plateFile) continue;
+		const stored = readStoredPlate(resolve(dir, rel));
+		if (!stored) continue;
+		const breakpoints = stored.breakpoints ?? [];
 		out[name] = {
-			breakpoints: plateFile.breakpoints ?? [],
-			spans: plateFile.views.map((view) => ({
-				min: view.min,
-				max: view.max
-			}))
+			breakpoints,
+			spans: spansFromBreakpoints(breakpoints)
 		};
 	}
 	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;
+}
 /**
-* Fold a posted capture into its plate file and hot-swap the plate in place.
+* 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");
+		}
+	});
+}
+/**
+* Validate a posted `StoredPlate` envelope, write it AS-IS, and hot-swap the
+* plate in place. After the ADR 0022 cutover the dev client posts a finished
+* StoredPlate (the whole Plate already projected in the browser) inside a
+* `{ plate, diagnostics? }` envelope — there is NO server-side accumulation/merge
+* anymore. `diagnostics` is a SIBLING field the server logs and then drops; it
+* never reaches the stored artifact (ADR 0008).
 *
 * @internal
 */
@@ -631,79 +894,129 @@ 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 raw = JSON.parse(body);
+			const envelope = isRecord(raw) ? raw : void 0;
+			const stored = parseStoredPlate(envelope?.plate);
+			if (!stored) {
 				res.statusCode = 400;
 				res.end("invalid capture payload");
 				return;
 			}
-			const file = platePath(payload.name);
-			const existing = readPlateFile(file);
-			const next = addCapture(existing, payload.name, payload.capture, payload.breakpoints ?? []);
-			const serialized = `${JSON.stringify(next, null, 1)}\n`;
+			reportServerDiagnostics(server, stored.name, validEnvelopeDiagnostics(envelope?.diagnostics));
+			const file = platePath(stored.name);
+			const { stored: existing, invalid } = loadStoredPlate(file);
+			if (invalid) reportServerDiagnostics(server, stored.name, [makeDiagnostic("invalid-plate-file", { detail: `${stored.name}.json` })]);
+			const serialized = `${JSON.stringify(stored, null, 1)}\n`;
 			if (existing !== null && `${JSON.stringify(existing, null, 1)}\n` === serialized) {
 				res.statusCode = 204;
 				res.end();
 				return;
 			}
 			if (serialized.length > MAX_PLATE_BYTES) {
-				console.warn(`[xray] not writing "${payload.name}": ${Math.round(serialized.length / 1e3)}KB exceeds the cap.`, "The <Skeleton> likely sits too high in the tree.");
+				console.warn(`[xray] not writing "${stored.name}": ${Math.round(serialized.length / 1e3)}KB exceeds the cap.`, "The <Skeleton> likely sits too high in the tree.");
 				res.statusCode = 413;
 				res.end("plate too large");
 				return;
 			}
 			mkdirSync(dirname(file), { recursive: true });
 			writeFileSync(file, serialized);
-			announcePlate(server.ws, payload.name, next);
+			announcePlate(server.ws, stored.name, stored);
 			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");
 		}
 	});
 }
 /**
-* Names come from import specifiers and POST bodies — keep them inside the plates dir.
-*
-* @internal
+* Loosely validate the envelope's SIBLING `diagnostics` (never stored, just
+* logged). The StoredPlate validator does not carry diagnostics — they are a
+* transient dev-only field on the POST envelope — so this filters the array to
+* the known-code shape `reportServerDiagnostics` formats, dropping anything that
+* is not a `{ code, message, ... }` record. A malformed diagnostics field never
+* fails the post (the plate already validated); it just logs nothing.
 */
-function isValidPlateName(name) {
-	return /^[\w-]+(\/[\w-]+)*$/.test(name);
+function validEnvelopeDiagnostics(value) {
+	if (!Array.isArray(value)) return void 0;
+	const out = [];
+	for (const item of value) {
+		if (!isRecord(item) || typeof item.code !== "string" || typeof item.message !== "string") continue;
+		out.push({
+			code: item.code,
+			message: item.message,
+			...typeof item.count === "number" ? { count: item.count } : {},
+			...typeof item.detail === "string" ? { detail: item.detail } : {}
+		});
+	}
+	return out.length > 0 ? out : void 0;
 }
-function readPlateFile(file) {
+/**
+* Read and validate a committed StoredPlate, 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 loadStoredPlate(file) {
 	let raw;
 	try {
 		raw = readFileSync(file, "utf8");
 	} catch {
-		return null;
+		return {
+			stored: null,
+			invalid: false
+		};
 	}
 	try {
-		const plateFile = JSON.parse(raw);
-		if (!isPlateFile(plateFile) || plateFile.v !== 1) return null;
-		return plateFile;
+		const stored = parseStoredPlate(JSON.parse(raw));
+		if (!stored) return {
+			stored: null,
+			invalid: true
+		};
+		return {
+			stored,
+			invalid: false
+		};
 	} catch {
-		return null;
+		return {
+			stored: null,
+			invalid: true
+		};
 	}
 }
-/**
-* Read a plate file and merge its views down to the plate the import
-* resolves to. Missing, unreadable, or version-mismatched files resolve to an
-* empty plate, so imports never break.
-*/
-function readPlate(file, name) {
-	const plateFile = readPlateFile(file);
-	if (!plateFile) return emptyPlate(name);
-	return mergeViews({
-		...plateFile,
-		name
-	});
+function readStoredPlate(file) {
+	return loadStoredPlate(file).stored;
 }
 /**
 * Render a plate as the virtual module's source. Each stitch (`ref` node) becomes
@@ -714,13 +1027,21 @@ function readPlate(file, name) {
 * import itself); an unknown child resolves to its own empty plate, never a
 * build break.
 *
+* `name` defaults to the plate's own `name`, but the loader passes the
+* PATH-derived name so a hand-edited StoredPlate whose `name` field drifted from
+* its filename still serializes and self-references under the canonical name
+* (`collectRefs` reads `stored.tree`, a RenderNode, unchanged by the cutover).
+*
 * @internal
 */
-function renderPlateModule(merged) {
-	const refs = collectRefs(merged.tree).filter((name) => name !== merged.name && isValidPlateName(name));
-	const json = JSON.stringify(serializePlate(merged));
+function renderPlateModule(merged, name = merged.name) {
+	const refs = collectRefs(merged.tree).filter((ref) => ref !== name && isValidPlateName(ref));
+	const json = JSON.stringify(serializePlate({
+		...merged,
+		name
+	}));
 	if (refs.length === 0) return `export default ${json}`;
-	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(", ")} } })`;
+	return `${refs.map((ref, i) => `import __xr${i} from ${JSON.stringify(VIRTUAL_PREFIX + ref)}`).join("\n")}\nexport default Object.assign(${json}, { refs: { ${refs.map((ref, i) => `${JSON.stringify(ref)}: __xr${i}`).join(", ")} } })`;
 }
 //#endregion
-export { addCapture, collectRefs, handleCapturePost, isValidPlateName, mergeViews, readCoverage, renderPlateModule, xrayVitePlugin };
+export { collectRefs, handleCapturePost, handleFixturePost, isValidPlateName, readCoverage, readFixtures, renderPlateModule, xrayVitePlugin };