@hueest/xray 0.1.0 → 0.3.0

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { a as PlateNode, c as emptyPlate, i as PlateFile, n as MergedPlate, o as RenderNode, r as Plate, s as ViewCapture, t as LeafKind } from "./plate-DboxMKg-.js";
-import { CaptureOptions, CaptureRegimeOptions, CaptureTooLargeError, capture, captureRegime } from "./serialize.js";
+import { a as RenderNode, c as emptyPlate, i as PlateNode, n as MergedPlate, r as Plate, s as ViewCapture, t as LeafKind } from "./plate-BIr62u7l.js";
+import { a as XrayCaptureWalker, i as WalkerDecision, n as CaptureTooLargeError, o as defineXrayCaptureWalker, r as CaptureWalkerContext, t as CaptureOptions } from "./serialize-Cs7hUxmK.js";
 
 //#region src/chunk.d.ts
 /**
@@ -9,36 +9,30 @@ import { CaptureOptions, CaptureRegimeOptions, CaptureTooLargeError, capture, ca
  * chunks and renders the fallback.
  */
 declare function serializePlate(merged: MergedPlate): Plate;
-//#endregion
-//#region src/merge.d.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.
+ * 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).
  */
-declare function mergeViews(file: PlateFile): MergedPlate;
-/** Distinct plate names referenced by the tree's stitches, in first-seen order. */
 declare function collectRefs(tree: RenderNode | null): string[];
-/** Fold a fresh capture into the plate file: union breakpoints, one capture per view. */
-declare function addCapture(file: PlateFile | null, name: string, capture: ViewCapture, breakpoints: readonly number[]): PlateFile;
 //#endregion
 //#region src/core.d.ts
 /**
- * Capture a live DOM subtree straight to a renderable Plate — `capture` followed
- * by `serializePlate` in one call. `roots` are the top-level elements to capture
- * (a component's rendered roots). Pass the result to a `<Skeleton plate>`.
+ * Capture a live DOM subtree straight to a renderable Plate. Runs the same
+ * uniform pipeline the dev client does for a single View — measure (`captureView`),
+ * reduce (`runPlatePasses`), project (`serializePlateIR` → the structured
+ * `StoredPlate`), then lower to chunks (`serializePlate`) — in one call. `roots`
+ * are the top-level elements to capture (a component's rendered roots). Pass the
+ * result to a `<Skeleton plate>`.
+ *
+ * `options.walker` is the public programmable capture walker (ADR 0018, Q2 —
+ * yes, public): the same `XrayCaptureWalker` the `<Skeleton captureWalker>` prop
+ * threads through in dev, available here for driving capture directly. It is
+ * capture-only and never persisted into the returned Plate.
  */
 declare function captureElement(roots: readonly Element[], options: CaptureOptions): Plate;
 /**
@@ -52,4 +46,4 @@ declare function captureElement(roots: readonly Element[], options: CaptureOptio
  */
 declare function renderPlateHtml(plate: Plate): string;
 //#endregion
-export { type CaptureOptions, type CaptureRegimeOptions, CaptureTooLargeError, type LeafKind, type MergedPlate, type Plate, type PlateFile, type PlateNode, type ViewCapture, addCapture, capture, captureElement, captureRegime, collectRefs, emptyPlate, mergeViews, renderPlateHtml, serializePlate };
+export { type CaptureOptions, CaptureTooLargeError, type CaptureWalkerContext, type LeafKind, type MergedPlate, type Plate, type PlateNode, type ViewCapture, type WalkerDecision, type XrayCaptureWalker, captureElement, collectRefs, defineXrayCaptureWalker, emptyPlate, renderPlateHtml, serializePlate };

package/dist/core.js

@@ -1,214 +1,28 @@
-import { a as ROOT_ATTR, i as NODE_CLASS, o as ROOT_CLASS, r as LEAF_CLASS, s as SPEC_GATE, t as BASE_CSS, u as emptyPlate } from "./plate-BuzRMPx4.js";
-import { i as captureRegime, o as classify, r as capture, t as CaptureTooLargeError } from "./serialize-Bq6yJnNV.js";
-import { n as regimeFor } from "./breakpoints-CBNlh7lQ.js";
-//#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/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
+import { a as ROOT_ATTR, d as emptyPlate, o as ROOT_CLASS, t as BASE_CSS } from "./plate-BRR6d8Se.js";
+import { a as serializePlate, c as defineXrayCaptureWalker, i as collectRefs, l as runPlatePasses, o as CaptureTooLargeError, s as captureView, t as serializePlateIR } from "./project-DORoPAo7.js";
+import { t as escapeStyleText } from "./css-escape-N7bOusGW.js";
 //#region src/core.ts
 /**
-* Capture a live DOM subtree straight to a renderable Plate — `capture` followed
-* by `serializePlate` in one call. `roots` are the top-level elements to capture
-* (a component's rendered roots). Pass the result to a `<Skeleton plate>`.
+* Capture a live DOM subtree straight to a renderable Plate. Runs the same
+* uniform pipeline the dev client does for a single View — measure (`captureView`),
+* reduce (`runPlatePasses`), project (`serializePlateIR` → the structured
+* `StoredPlate`), then lower to chunks (`serializePlate`) — in one call. `roots`
+* are the top-level elements to capture (a component's rendered roots). Pass the
+* result to a `<Skeleton plate>`.
+*
+* `options.walker` is the public programmable capture walker (ADR 0018, Q2 —
+* yes, public): the same `XrayCaptureWalker` the `<Skeleton captureWalker>` prop
+* threads through in dev, available here for driving capture directly. It is
+* capture-only and never persisted into the returned Plate.
 */
 function captureElement(roots, options) {
-	return serializePlate(capture(roots, options));
+	const plate = captureView(roots, {
+		walker: options.walker,
+		captureRootIsBoundary: options.captureRootIsBoundary
+	});
+	plate.name = options.name;
+	runPlatePasses(plate);
+	return serializePlate(serializePlateIR(plate));
 }
 /**
 * Render a stitch-free Plate to a self-contained HTML string — the
@@ -222,9 +36,24 @@ function captureElement(roots, options) {
 function renderPlateHtml(plate) {
 	const chunks = plate.chunks;
 	if (!chunks) return "";
-	if (chunks.length !== 1 || typeof chunks[0] !== "string") throw new Error("xray: renderPlateHtml renders stitch-free plates only — use a framework adapter for stitched plates");
 	const className = plate.rootCls ? `${ROOT_CLASS} ${plate.rootCls}` : ROOT_CLASS;
-	return `<div ${ROOT_ATTR}="${plate.name}" class="${className}" aria-hidden="true" aria-busy="true"><style>${BASE_CSS}\n${plate.css}</style>${chunks[0]}</div>`;
+	return `<div ${ROOT_ATTR}="${plate.name}" class="${className}" aria-hidden="true" aria-busy="true"><style>${BASE_CSS}\n${escapeStyleText(plate.css)}</style>${chunksToHtml(chunks)}</div>`;
+}
+/**
+* Flatten chunks to one HTML string. A `string` concatenates; a template chunk
+* (`{ t, n }`) expands to its cell repeated `n` times (the cell is stitch-free by
+* construction); a stitch-free wrapper (`{ c, k }`) recurses inside a real `<div>`.
+* A stitch (`{ r }`) resolves to a child plate at render and needs a framework
+* adapter to mount, so a stitched plate throws here. Chunk HTML is xray-generated
+* and interpolated raw, exactly as the single-string path was before.
+*/
+function chunksToHtml(chunks) {
+	let html = "";
+	for (const chunk of chunks) if (typeof chunk === "string") html += chunk;
+	else if ("t" in chunk) html += chunk.t.repeat(chunk.n);
+	else if ("r" in chunk) throw new Error("xray: renderPlateHtml renders stitch-free plates only — use a framework adapter for stitched plates");
+	else html += `<div class="${chunk.c}">${chunksToHtml(chunk.k)}</div>`;
+	return html;
 }
 //#endregion
-export { CaptureTooLargeError, addCapture, capture, captureElement, captureRegime, collectRefs, emptyPlate, mergeViews, renderPlateHtml, serializePlate };
+export { CaptureTooLargeError, captureElement, collectRefs, defineXrayCaptureWalker, emptyPlate, renderPlateHtml, serializePlate };

package/dist/css-escape-N7bOusGW.js

@@ -0,0 +1,52 @@
+//#region src/css-escape.ts
+/**
+* Dependency-free raw-text safety for the one place a Plate's CSS string is
+* interpolated into `<style>…</style>` markup.
+*
+* A plate's `css` is normally produced by the capture path (`filterLayoutDecls`
+* + `classify`), which only ever emits well-formed `selector { prop: value }`
+* rules — never a raw-text terminator. But a committed `plates/<name>.json` is
+* UNTRUSTED at render time (it can be hand-edited or arrive over git, see the
+* capture-input-validation plan's decisions), and a corrupt/malicious `css`
+* could carry a `</style>` or an HTML comment delimiter. `<style>` is a
+* raw-text element: the parser ends the element at the first `</style` it sees
+* and resumes parsing the rest as ordinary HTML, so an unescaped terminator in
+* the CSS body turns the tail of the plate into live markup.
+*
+* The React text-child path (`<style>{css}</style>`) is already safe — React
+* escapes the child — but the two STRING paths interpolate `css` directly into
+* a markup string (`renderPlateHtml` builds an HTML string; `react.core.tsx`
+* feeds one to `dangerouslySetInnerHTML`). Those must run the body through this
+* helper first.
+*
+* This lives in its own dependency-free module ON PURPOSE: it is imported by
+* render/browser paths, so it must NOT pull in the Node-only validation code
+* (valibot). It neutralizes only the sequences that can escape a raw-text
+* `<style>` context — a `<` that begins `</style`, and the HTML comment / CDATA
+* delimiters the tokenizer treats specially inside raw text — by inserting a
+* CSS-comment break (`/​**​/`) that the CSS parser ignores. It does not, and is
+* not meant to, sanitize CSS semantically; POST-time validation
+* (`validate.ts`) is what rejects junk declarations.
+*
+* @module
+*/
+/**
+* Make a CSS body safe to interpolate into a `<style>…</style>` STRING. Breaks
+* up the only sequences the HTML tokenizer acts on inside a raw-text `<style>`
+* element, so none can terminate the element early or open a comment/CDATA run:
+*
+*  - `</style` (the end-tag open, case-insensitive) — inserts the break between
+*    `<` and `/style` so the parser never matches the end tag.
+*  - `<!--`, `-->`, `<![CDATA[` — the comment/CDATA delimiters; split so neither
+*    a comment nor a CDATA section can open.
+*
+* The inserted `/​**​/` is an empty CSS comment: inert to the CSS parser (it
+* cannot appear mid-token in a value we emit, and a stray one only ends a
+* token early), so a well-formed plate is rendered byte-for-byte equivalently
+* while a corrupt one can no longer break out of the style element.
+*/
+function escapeStyleText(css) {
+	return css.replace(/<(\/style)/gi, "</**/$1").replace(/<!--/g, "<!/**/--").replace(/-->/g, "--/**/>").replace(/<!\[CDATA\[/g, "<![/**/CDATA[");
+}
+//#endregion
+export { escapeStyleText as t };

package/dist/hud.js

@@ -52,6 +52,7 @@ function installXrayHud() {
     .bands { text-align: right }
     .band.covered { color: #4ade80 }
     .band.missing { color: #52525b }
+    .fixture { color: #fbbf24; margin-left: 6px }
     .toggle { display: flex; gap: 6px; align-items: center; cursor: pointer; user-select: none }
     .toggle input { accent-color: #4ade80; margin: 0 }
     .action {
@@ -70,6 +71,8 @@ function installXrayHud() {
 	let extensionPresent = false;
 	let sweeping = false;
 	let sweepStatus = "";
+	let recording = false;
+	let recordStatus = "";
 	const render = () => {
 		panel.textContent = "";
 		const coverage = globalThis.__XRAY__?.coverage?.get();
@@ -82,6 +85,26 @@ function installXrayHud() {
 		if (capture) panel.append(toggleRow(capture, "Capture"));
 		const lightbox = globalThis.__XRAY__?.lightbox;
 		if (lightbox) panel.append(toggleRow(lightbox, "Light Box"));
+		const replay = globalThis.__XRAY__?.replay;
+		if (replay) panel.append(toggleRow(replay, "Replay"));
+		const fixtures = globalThis.__XRAY__?.fixtures;
+		if (fixtures) {
+			const button = document.createElement("button");
+			button.className = "action";
+			button.type = "button";
+			button.disabled = recording;
+			button.textContent = recording ? "Recording fixture…" : "Record fixture";
+			button.addEventListener("click", () => {
+				recordFixtures(fixtures);
+			});
+			panel.append(button);
+			if (recordStatus) {
+				const status = document.createElement("div");
+				status.className = "status";
+				status.textContent = recordStatus;
+				panel.append(status);
+			}
+		}
 		if (globalThis.__XRAY__?.captureAllViews) if (extensionPresent) {
 			const button = document.createElement("button");
 			button.className = "action";
@@ -109,6 +132,12 @@ function installXrayHud() {
 			row.className = "plate";
 			const label = document.createElement("span");
 			label.textContent = name;
+			if (globalThis.__XRAY__?.fixtures?.has(name)) {
+				const tag = document.createElement("span");
+				tag.className = "fixture";
+				tag.textContent = "◆ fixture";
+				label.append(tag);
+			}
 			const bands = document.createElement("span");
 			bands.className = "bands";
 			for (const band of bandsOf(plateCoverage)) {
@@ -136,6 +165,21 @@ function installXrayHud() {
 			render();
 		}
 	}
+	async function recordFixtures(fixtures) {
+		if (recording || !fixtures) return;
+		recording = true;
+		recordStatus = "";
+		render();
+		try {
+			await fixtures.recordAll();
+			recordStatus = "Fixture recorded.";
+		} catch (error) {
+			recordStatus = `Failed: ${error instanceof Error ? error.message : String(error)}`;
+		} finally {
+			recording = false;
+			render();
+		}
+	}
 	const onHudMessage = (event) => {
 		if (event.source !== window) return;
 		if (isExtensionHello(event.data) && !extensionPresent) {
@@ -149,6 +193,7 @@ function installXrayHud() {
 		kind: "whois"
 	}, "*");
 	const unsubscribeCoverage = globalThis.__XRAY__?.coverage?.subscribe(render);
+	const unsubscribeFixtures = globalThis.__XRAY__?.fixtures?.subscribe(render);
 	render();
 	const mount = () => {
 		if (document.body) document.body.append(host);
@@ -158,6 +203,7 @@ function installXrayHud() {
 	return { dispose() {
 		window.removeEventListener("message", onHudMessage);
 		unsubscribeCoverage?.();
+		unsubscribeFixtures?.();
 		host.remove();
 	} };
 }