@hueest/xray 0.1.0

package/dist/index.js

@@ -0,0 +1,726 @@
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+/** 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;
+/** Fixed renderer-owned classes every rendered node carries. */
+const ROOT_CLASS = "xr-root";
+const NODE_CLASS = "xr-node";
+const LEAF_CLASS = "xr-leaf";
+`
+/* One timeline per skeleton, not per leaf: the root animates one inherited
+   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 }
+.${ROOT_CLASS} {
+  --xr-bone-highlight: #f4f4f5;
+  display: contents;
+  animation: var(--xr-anim, xr-pulse) var(--xr-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
+   border-width for layout; its paint stays out. list-style: suppress a ::marker
+   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)) }
+@keyframes xr-pulse {
+  from { --xr-o: var(--xr-pulse-max, 1) }
+  to { --xr-o: var(--xr-pulse-min, 0.5) }
+}
+@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))) }
+  @media (prefers-contrast: more) {
+    .${LEAF_CLASS} { background: var(--xr-fill, var(--xr-bone, 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. */
+@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) }
+}`.trim();
+/** The (unserialized) plate an import resolves to before anything has been captured. */
+function emptyPlate(name) {
+	return {
+		v: 1,
+		name,
+		tree: null,
+		css: ""
+	};
+}
+//#endregion
+//#region src/chunk.ts
+/**
+* Serialize a merged plate's RenderNode tree into the shipped `Plate` (ADR
+* 0008). This is the framework-neutral half of rendering: a skeleton is static,
+* text-free DOM, so the structure is flattened to HTML strings here, at build,
+* once — instead of every adapter walking a tree on the latency-critical first
+* paint. The adapter only injects the strings and mounts a child plate at each
+* stitch (see the React adapters). No escaping risk: bones carry only the
+* content-addressed class tokens (ADR 0007), never user content.
+*/
+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.
+*/
+function hasStitch(node) {
+	return node.ref !== void 0 || (node.kids?.some(hasStitch) ?? false);
+}
+/** Serialize a stitch-free subtree to one HTML string (caller guarantees no `ref` below). */
+function toHtml(node) {
+	const kids = node.kids ? node.kids.map(toHtml).join("") : "";
+	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.
+*/
+function toChunks(nodes) {
+	const out = [];
+	let buf = "";
+	const flush = () => {
+		if (buf) {
+			out.push(buf);
+			buf = "";
+		}
+	};
+	for (const node of nodes) {
+		if (!hasStitch(node)) {
+			buf += toHtml(node);
+			continue;
+		}
+		flush();
+		if (node.ref !== void 0) out.push({ r: node.ref });
+		else out.push({
+			c: nodeClass(node),
+			k: toChunks(node.kids ?? [])
+		});
+	}
+	flush();
+	return out;
+}
+/**
+* Turn a merged plate (RenderNode tree) into the shipped plate (chunks). The
+* root's own content classes travel as `rootCls` (the adapter puts them on the
+* root element); its children become `chunks`. A capture-less plate has null
+* chunks and renders the fallback.
+*/
+function serializePlate(merged) {
+	const { v, name, tree, css } = merged;
+	if (!tree) return {
+		v,
+		name,
+		chunks: null,
+		css
+	};
+	const chunks = toChunks(tree.kids ?? []);
+	return tree.cls ? {
+		v,
+		name,
+		chunks,
+		rootCls: tree.cls,
+		css
+	} : {
+		v,
+		name,
+		chunks,
+		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. */
+function collectRefs(tree) {
+	const names = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (node.ref !== void 0 && !seen.has(node.ref)) {
+			seen.add(node.ref);
+			names.push(node.ref);
+		}
+		for (const kid of node.kids ?? []) visit(kid);
+	};
+	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);
+	return {
+		v: 1,
+		name,
+		breakpoints: allBreakpoints,
+		views: [...byView.values()].toSorted((a, b) => a.width - b.width)
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* Vite plugin entry point for xray.
+*
+* Add `xrayVitePlugin()` to a Vite config to resolve committed Plate imports in
+* dev and build. The dev capture client is injected only during `vite serve`,
+* and only when `capture` or the HUD needs it.
+*
+* @module @hueest/xray
+*/
+const RESOLVED_PREFIX = `\0${VIRTUAL_PREFIX}`;
+const BOOT_ID = "virtual:xray/client";
+const RESOLVED_BOOT_ID = `\0${BOOT_ID}`;
+const ENDPOINT = "/__xray";
+/**
+* Create the Vite plugins that resolve committed Plates and, during dev,
+* capture new Plates from rendered `<Skeleton>` boundaries.
+*
+* Typical setup:
+*
+* ```ts
+* import { xrayVitePlugin } from '@hueest/xray'
+*
+* export default {
+*   plugins: [xrayVitePlugin({ hud: true })],
+* }
+* ```
+*
+* Returns two plugins:
+* - `xray:data` resolves `virtual:xray/plates/<name>` from committed Plate files in dev and build.
+* - `xray:dev` runs only during `vite serve`; it injects the capture client, receives Captures, writes Plate files, and hot-updates the page.
+*/
+function xrayVitePlugin(options = {}) {
+	const platesDir = options.platesDir ?? "plates";
+	const capture = options.capture ?? false;
+	const delay = options.delay ?? 200;
+	const settleCap = options.settleCap ?? 5e3;
+	const maxNodes = options.maxNodes ?? 4e3;
+	const hud = options.hud ?? false;
+	let root = process.cwd();
+	const platePath = (name) => resolve(root, platesDir, `${name}.json`);
+	return [{
+		name: "xray:data",
+		configResolved(config) {
+			root = config.root;
+		},
+		resolveId(id) {
+			if (id.startsWith("virtual:xray/plates/")) return `\0${id}`;
+		},
+		load(id) {
+			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));
+		}
+	}, {
+		name: "xray:dev",
+		apply: "serve",
+		config() {
+			return { resolve: { alias: [{
+				find: /^@hueest\/xray\/react$/,
+				replacement: "@hueest/xray/react/dev"
+			}] } };
+		},
+		transformIndexHtml: {
+			order: "pre",
+			handler() {
+				if (!capture && !hud) return void 0;
+				return [{
+					tag: "script",
+					attrs: {
+						type: "module",
+						src: `/@id/${BOOT_ID}`
+					},
+					injectTo: "head-prepend"
+				}];
+			}
+		},
+		resolveId(id) {
+			if (id === BOOT_ID) return RESOLVED_BOOT_ID;
+		},
+		load(id) {
+			if (id !== RESOLVED_BOOT_ID) return void 0;
+			return bootstrapCode(delay, settleCap, maxNodes, hud, capture);
+		},
+		configureServer(server) {
+			const dir = () => resolve(root, platesDir);
+			server.watcher.add(dir());
+			const onPlateFile = (file) => {
+				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));
+			};
+			server.watcher.on("add", onPlateFile);
+			server.watcher.on("change", onPlateFile);
+			server.middlewares.use(ENDPOINT, (req, res) => {
+				if (req.method === "GET" && req.url === "/coverage") {
+					res.setHeader("content-type", "application/json");
+					res.end(JSON.stringify(readCoverage(dir())));
+					return;
+				}
+				handleCapturePost(req, res, server, platePath);
+			});
+		}
+	}];
+}
+/**
+* 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) {
+	return [
+		`import { installXrayClient } from '@hueest/xray/client'`,
+		...hud ? [`import { installXrayHud } from '@hueest/xray/hud'`] : [],
+		"installXrayClient({",
+		`  delay: ${delay},`,
+		`  settleCap: ${settleCap},`,
+		`  maxNodes: ${maxNodes},`,
+		`  capture: ${capture},`,
+		"  sink(payload) {",
+		`    void fetch('${ENDPOINT}', {`,
+		"      method: 'POST',",
+		"      headers: { 'content-type': 'application/json' },",
+		"      body: JSON.stringify(payload),",
+		"    })",
+		"  },",
+		"})",
+		...hud ? ["installXrayHud()"] : [],
+		`void fetch('${ENDPOINT}/coverage')`,
+		"  .then((response) => response.json())",
+		"  .then((coverage) => {",
+		"    for (const [name, c] of Object.entries(coverage)) globalThis.__XRAY__?.coverage?.set(name, c)",
+		"  })",
+		"  .catch(() => {})",
+		"if (import.meta.hot) {",
+		"  import.meta.hot.on('xray:plate', (data) => {",
+		"    globalThis.__XRAY__?.updatePlate?.(data.name, data.plate)",
+		"    globalThis.__XRAY__?.coverage?.set(data.name, { breakpoints: data.breakpoints, spans: data.spans })",
+		"  })",
+		"}",
+		""
+	].join("\n");
+}
+/** A committed plate file past this is almost always a `<Skeleton>` set too high. */
+const MAX_PLATE_BYTES = 2e6;
+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) {
+	const merged = plateFile ? mergeViews({
+		...plateFile,
+		name
+	}) : 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
+			}))
+		}
+	});
+}
+/**
+* Per-plate breakpoints + captured spans, read from the committed plate files.
+*
+* @internal
+*/
+function readCoverage(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(".json")) continue;
+		const name = rel.slice(0, -5);
+		if (!isValidPlateName(name)) continue;
+		const plateFile = readPlateFile(resolve(dir, rel));
+		if (!plateFile) continue;
+		out[name] = {
+			breakpoints: plateFile.breakpoints ?? [],
+			spans: plateFile.views.map((view) => ({
+				min: view.min,
+				max: view.max
+			}))
+		};
+	}
+	return out;
+}
+/**
+* Fold a posted capture into its plate file and hot-swap the plate in place.
+*
+* @internal
+*/
+function handleCapturePost(req, res, server, platePath) {
+	if (req.method !== "POST") {
+		res.statusCode = 405;
+		res.end();
+		return;
+	}
+	let body = "";
+	req.on("data", (chunk) => {
+		body += typeof chunk === "string" ? chunk : chunk?.toString() ?? "";
+	});
+	req.on("end", () => {
+		try {
+			const payload = JSON.parse(body);
+			if (!isIncomingCapture(payload) || !isValidPlateName(payload.name)) {
+				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`;
+			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.");
+				res.statusCode = 413;
+				res.end("plate too large");
+				return;
+			}
+			mkdirSync(dirname(file), { recursive: true });
+			writeFileSync(file, serialized);
+			announcePlate(server.ws, payload.name, next);
+			res.statusCode = 204;
+			res.end();
+		} catch (error) {
+			res.statusCode = 400;
+			res.end(error instanceof Error ? error.message : "invalid capture payload");
+		}
+	});
+}
+/**
+* Names come from import specifiers and POST bodies — keep them inside the plates dir.
+*
+* @internal
+*/
+function isValidPlateName(name) {
+	return /^[\w-]+(\/[\w-]+)*$/.test(name);
+}
+function readPlateFile(file) {
+	let raw;
+	try {
+		raw = readFileSync(file, "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const plateFile = JSON.parse(raw);
+		if (!isPlateFile(plateFile) || plateFile.v !== 1) return null;
+		return plateFile;
+	} catch {
+		return null;
+	}
+}
+/**
+* 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
+	});
+}
+/**
+* Render a plate as the virtual module's source. Each stitch (`ref` node) becomes
+* a real import of that child's virtual module, wired into a `refs` map on the
+* default export — so the bundler builds the actual reference graph and chunks
+* the transitive closure a page uses, with no runtime registry (ADR 0006). A
+* stitchless plate is just its JSON. Self-references are dropped (a module can't
+* import itself); an unknown child resolves to its own empty plate, never a
+* build break.
+*
+* @internal
+*/
+function renderPlateModule(merged) {
+	const refs = collectRefs(merged.tree).filter((name) => name !== merged.name && isValidPlateName(name));
+	const json = JSON.stringify(serializePlate(merged));
+	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(", ")} } })`;
+}
+//#endregion
+export { addCapture, collectRefs, handleCapturePost, isValidPlateName, mergeViews, readCoverage, renderPlateModule, xrayVitePlugin };