@hueest/xray 0.1.0 → 0.2.0

package/dist/client.js

@@ -1,5 +1,531 @@
-import { i as captureRegime, t as CaptureTooLargeError } from "./serialize-Bq6yJnNV.js";
-import { n as regimeFor, t as deriveBreakpoints } from "./breakpoints-CBNlh7lQ.js";
+import { a as captureRegime, c as formatDiagnostic, l as makeDiagnostic, n as regimeFor, r as CaptureTooLargeError, s as diagnosticsHeader, t as deriveBreakpoints } from "./breakpoints-CMoFUUOv.js";
+//#region ../../node_modules/.pnpm/devalue@5.8.1/node_modules/devalue/src/base64.js
+/**	@type {(array_buffer: ArrayBuffer) => string} */
+function encode_native(array_buffer) {
+	return new Uint8Array(array_buffer).toBase64();
+}
+/**	@type {(base64: string) => ArrayBuffer} */
+function decode_native(base64) {
+	return Uint8Array.fromBase64(base64).buffer;
+}
+/** @type {(array_buffer: ArrayBuffer) => string} */
+function encode_buffer(array_buffer) {
+	return Buffer.from(array_buffer).toString("base64");
+}
+/**	@type {(base64: string) => ArrayBuffer} */
+function decode_buffer(base64) {
+	return Uint8Array.from(Buffer.from(base64, "base64")).buffer;
+}
+/** @type {(array_buffer: ArrayBuffer) => string} */
+function encode_legacy(array_buffer) {
+	const array = new Uint8Array(array_buffer);
+	let binary = "";
+	const chunk_size = 32768;
+	for (let i = 0; i < array.length; i += chunk_size) {
+		const chunk = array.subarray(i, i + chunk_size);
+		binary += String.fromCharCode.apply(null, chunk);
+	}
+	return btoa(binary);
+}
+/**	@type {(base64: string) => ArrayBuffer} */
+function decode_legacy(base64) {
+	const binary_string = atob(base64);
+	const len = binary_string.length;
+	const array = new Uint8Array(len);
+	for (let i = 0; i < len; i++) array[i] = binary_string.charCodeAt(i);
+	return array.buffer;
+}
+const native = typeof Uint8Array.fromBase64 === "function";
+const buffer = typeof process === "object" && process.versions?.node !== void 0;
+const encode64 = native ? encode_native : buffer ? encode_buffer : encode_legacy;
+const decode64 = native ? decode_native : buffer ? decode_buffer : decode_legacy;
+//#endregion
+//#region ../../node_modules/.pnpm/devalue@5.8.1/node_modules/devalue/src/constants.js
+const MAX_ARRAY_LEN = 2 ** 32 - 1;
+const MAX_ARRAY_INDEX = MAX_ARRAY_LEN - 1;
+//#endregion
+//#region ../../node_modules/.pnpm/devalue@5.8.1/node_modules/devalue/src/utils.js
+var DevalueError = class extends Error {
+	/**
+	* @param {string} message
+	* @param {string[]} keys
+	* @param {any} [value] - The value that failed to be serialized
+	* @param {any} [root] - The root value being serialized
+	*/
+	constructor(message, keys, value, root) {
+		super(message);
+		this.name = "DevalueError";
+		this.path = keys.join("");
+		this.value = value;
+		this.root = root;
+	}
+};
+/** @param {any} thing */
+function is_primitive(thing) {
+	return thing === null || typeof thing !== "object" && typeof thing !== "function";
+}
+const object_proto_names = /* @__PURE__ */ Object.getOwnPropertyNames(Object.prototype).sort().join("\0");
+/** @param {any} thing */
+function is_plain_object(thing) {
+	const proto = Object.getPrototypeOf(thing);
+	return proto === Object.prototype || proto === null || Object.getPrototypeOf(proto) === null || Object.getOwnPropertyNames(proto).sort().join("\0") === object_proto_names;
+}
+/** @param {any} thing */
+function get_type(thing) {
+	return Object.prototype.toString.call(thing).slice(8, -1);
+}
+/** @param {string} char */
+function get_escaped_char(char) {
+	switch (char) {
+		case "\"": return "\\\"";
+		case "<": return "\\u003C";
+		case "\\": return "\\\\";
+		case "\n": return "\\n";
+		case "\r": return "\\r";
+		case "	": return "\\t";
+		case "\b": return "\\b";
+		case "\f": return "\\f";
+		case "\u2028": return "\\u2028";
+		case "\u2029": return "\\u2029";
+		default: return char < " " ? `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}` : "";
+	}
+}
+/** @param {string} str */
+function stringify_string(str) {
+	let result = "";
+	let last_pos = 0;
+	const len = str.length;
+	for (let i = 0; i < len; i += 1) {
+		const char = str[i];
+		const replacement = get_escaped_char(char);
+		if (replacement) {
+			result += str.slice(last_pos, i) + replacement;
+			last_pos = i + 1;
+		}
+	}
+	return `"${last_pos === 0 ? str : result + str.slice(last_pos)}"`;
+}
+/** @param {Record<string | symbol, any>} object */
+function enumerable_symbols(object) {
+	return Object.getOwnPropertySymbols(object).filter((symbol) => Object.getOwnPropertyDescriptor(object, symbol).enumerable);
+}
+const is_identifier = /^[a-zA-Z_$][a-zA-Z_$0-9]*$/;
+/** @param {string} key */
+function stringify_key(key) {
+	return is_identifier.test(key) ? "." + key : "[" + JSON.stringify(key) + "]";
+}
+/** @param {number} n */
+function is_valid_array_index(n) {
+	if (!Number.isInteger(n)) return false;
+	if (n < 0) return false;
+	if (n > MAX_ARRAY_INDEX) return false;
+	return true;
+}
+/** @param {number} n */
+function is_valid_array_len(n) {
+	if (!Number.isInteger(n)) return false;
+	if (n < 0) return false;
+	if (n > MAX_ARRAY_LEN) return false;
+	return true;
+}
+/** @param {string} s */
+function is_valid_array_index_string(s) {
+	if (s.length === 0) return false;
+	if (s.length > 1 && s.charCodeAt(0) === 48) return false;
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c < 48 || c > 57) return false;
+	}
+	return is_valid_array_index(+s);
+}
+/**
+* Finds the populated indices of an array.
+* @param {unknown[]} array
+*/
+function valid_array_indices(array) {
+	const keys = Object.keys(array);
+	for (var i = keys.length - 1; i >= 0; i--) if (is_valid_array_index_string(keys[i])) break;
+	keys.length = i + 1;
+	return keys;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/devalue@5.8.1/node_modules/devalue/src/parse.js
+/**
+* Revive a value serialized with `devalue.stringify`
+* @param {string} serialized
+* @param {Record<string, (value: any) => any>} [revivers]
+*/
+function parse(serialized, revivers) {
+	return unflatten(JSON.parse(serialized), revivers);
+}
+/**
+* Revive a value flattened with `devalue.stringify`
+* @param {number | any[]} parsed
+* @param {Record<string, (value: any) => any>} [revivers]
+*/
+function unflatten(parsed, revivers) {
+	if (typeof parsed === "number") return hydrate(parsed, true);
+	if (!Array.isArray(parsed) || parsed.length === 0) throw new Error("Invalid input");
+	const values = parsed;
+	const hydrated = Array(values.length);
+	/**
+	* A set of values currently being hydrated with custom revivers,
+	* used to detect invalid cyclical dependencies
+	* @type {Set<number> | null}
+	*/
+	let hydrating = null;
+	/**
+	* @param {number} index
+	* @returns {any}
+	*/
+	function hydrate(index, standalone = false) {
+		if (index === -1) return void 0;
+		if (index === -3) return NaN;
+		if (index === -4) return Infinity;
+		if (index === -5) return -Infinity;
+		if (index === -6) return -0;
+		if (standalone || typeof index !== "number") throw new Error(`Invalid input`);
+		if (index in hydrated) return hydrated[index];
+		const value = values[index];
+		if (!value || typeof value !== "object") hydrated[index] = value;
+		else if (Array.isArray(value)) if (typeof value[0] === "string") {
+			const type = value[0];
+			const reviver = revivers && Object.hasOwn(revivers, type) ? revivers[type] : void 0;
+			if (reviver) {
+				let i = value[1];
+				if (typeof i !== "number") i = values.push(value[1]) - 1;
+				hydrating ??= /* @__PURE__ */ new Set();
+				if (hydrating.has(i)) throw new Error("Invalid circular reference");
+				hydrating.add(i);
+				hydrated[index] = reviver(hydrate(i));
+				hydrating.delete(i);
+				return hydrated[index];
+			}
+			switch (type) {
+				case "Date":
+					hydrated[index] = new Date(value[1]);
+					break;
+				case "Set":
+					const set = /* @__PURE__ */ new Set();
+					hydrated[index] = set;
+					for (let i = 1; i < value.length; i += 1) set.add(hydrate(value[i]));
+					break;
+				case "Map":
+					const map = /* @__PURE__ */ new Map();
+					hydrated[index] = map;
+					for (let i = 1; i < value.length; i += 2) map.set(hydrate(value[i]), hydrate(value[i + 1]));
+					break;
+				case "RegExp":
+					hydrated[index] = new RegExp(value[1], value[2]);
+					break;
+				case "Object": {
+					const wrapped_index = value[1];
+					if (typeof values[wrapped_index] === "object" && values[wrapped_index][0] !== "BigInt") throw new Error("Invalid input");
+					hydrated[index] = Object(hydrate(wrapped_index));
+					break;
+				}
+				case "BigInt":
+					hydrated[index] = BigInt(value[1]);
+					break;
+				case "null":
+					const obj = Object.create(null);
+					hydrated[index] = obj;
+					for (let i = 1; i < value.length; i += 2) {
+						if (value[i] === "__proto__") throw new Error("Cannot parse an object with a `__proto__` property");
+						obj[value[i]] = hydrate(value[i + 1]);
+					}
+					break;
+				case "Int8Array":
+				case "Uint8Array":
+				case "Uint8ClampedArray":
+				case "Int16Array":
+				case "Uint16Array":
+				case "Float16Array":
+				case "Int32Array":
+				case "Uint32Array":
+				case "Float32Array":
+				case "Float64Array":
+				case "BigInt64Array":
+				case "BigUint64Array":
+				case "DataView": {
+					if (values[value[1]][0] !== "ArrayBuffer") throw new Error("Invalid data");
+					const TypedArrayConstructor = globalThis[type];
+					const buffer = hydrate(value[1]);
+					hydrated[index] = value[2] !== void 0 ? new TypedArrayConstructor(buffer, value[2], value[3]) : new TypedArrayConstructor(buffer);
+					break;
+				}
+				case "ArrayBuffer": {
+					const base64 = value[1];
+					if (typeof base64 !== "string") throw new Error("Invalid ArrayBuffer encoding");
+					hydrated[index] = decode64(base64);
+					break;
+				}
+				case "Temporal.Duration":
+				case "Temporal.Instant":
+				case "Temporal.PlainDate":
+				case "Temporal.PlainTime":
+				case "Temporal.PlainDateTime":
+				case "Temporal.PlainMonthDay":
+				case "Temporal.PlainYearMonth":
+				case "Temporal.ZonedDateTime": {
+					const temporalName = type.slice(9);
+					hydrated[index] = Temporal[temporalName].from(value[1]);
+					break;
+				}
+				case "URL":
+					hydrated[index] = new URL(value[1]);
+					break;
+				case "URLSearchParams":
+					hydrated[index] = new URLSearchParams(value[1]);
+					break;
+				default: throw new Error(`Unknown type ${type}`);
+			}
+		} else if (value[0] === -7) {
+			const len = value[1];
+			if (!is_valid_array_len(len)) throw new Error("Invalid input");
+			/** @type {any[]} */
+			const array = [];
+			hydrated[index] = array;
+			array[MAX_ARRAY_INDEX] = void 0;
+			delete array[MAX_ARRAY_INDEX];
+			for (let i = 2; i < value.length; i += 2) {
+				const idx = value[i];
+				if (!is_valid_array_index(idx) || idx >= len) throw new Error("Invalid input");
+				array[idx] = hydrate(value[i + 1]);
+			}
+			array.length = len;
+		} else {
+			const array = new Array(value.length);
+			hydrated[index] = array;
+			for (let i = 0; i < value.length; i += 1) {
+				const n = value[i];
+				if (n === -2) continue;
+				array[i] = hydrate(n);
+			}
+		}
+		else {
+			/** @type {Record<string, any>} */
+			const object = {};
+			hydrated[index] = object;
+			for (const key of Object.keys(value)) {
+				if (key === "__proto__") throw new Error("Cannot parse an object with a `__proto__` property");
+				const n = value[key];
+				object[key] = hydrate(n);
+			}
+		}
+		return hydrated[index];
+	}
+	return hydrate(0);
+}
+//#endregion
+//#region ../../node_modules/.pnpm/devalue@5.8.1/node_modules/devalue/src/stringify.js
+/**
+* Turn a value into a JSON string that can be parsed with `devalue.parse`
+* @param {any} value
+* @param {Record<string, (value: any) => any>} [reducers]
+*/
+function stringify(value, reducers) {
+	const stringified = run(false, value, reducers);
+	return typeof stringified === "string" ? stringified : `[${stringified.join(",")}]`;
+}
+/**
+* @param {boolean} async
+* @param {any} value
+* @param {Record<string, (value: any) => any>} [reducers]
+*/
+function run(async, value, reducers) {
+	/** @type {any[]} */
+	const stringified = [];
+	/** @type {Map<any, number>} */
+	const indexes = /* @__PURE__ */ new Map();
+	/** @type {Array<{ key: string, fn: (value: any) => any }>} */
+	const custom = [];
+	if (reducers) for (const key of Object.getOwnPropertyNames(reducers)) custom.push({
+		key,
+		fn: reducers[key]
+	});
+	/** @type {string[]} */
+	const keys = [];
+	let p = 0;
+	/**
+	* @param {any} thing
+	* @param {number} [index]
+	*/
+	function flatten(thing, index) {
+		if (thing === void 0) return -1;
+		if (Number.isNaN(thing)) return -3;
+		if (thing === Infinity) return -4;
+		if (thing === -Infinity) return -5;
+		if (thing === 0 && 1 / thing < 0) return -6;
+		if (indexes.has(thing)) return indexes.get(thing);
+		index ??= p++;
+		indexes.set(thing, index);
+		for (const { key, fn } of custom) {
+			const value = fn(thing);
+			if (value) {
+				stringified[index] = `["${key}",${flatten(value)}]`;
+				return index;
+			}
+		}
+		if (typeof thing === "function") throw new DevalueError(`Cannot stringify a function`, keys, thing, value);
+		else if (typeof thing === "symbol") throw new DevalueError(`Cannot stringify a Symbol primitive`, keys, thing, value);
+		/** @type {string | Promise<any>} */
+		let str = "";
+		if (is_primitive(thing)) str = stringify_primitive(thing);
+		else if (typeof thing.then === "function") {
+			if (!async) throw new DevalueError(`Cannot stringify a Promise or thenable — use stringifyAsync instead`, keys, thing, value);
+			str = Promise.resolve(thing).then((value) => {
+				const i = flatten(value, index);
+				if (i < 0) stringified[index] = i;
+			});
+		} else {
+			const type = get_type(thing);
+			switch (type) {
+				case "Number":
+				case "String":
+				case "Boolean":
+				case "BigInt":
+					str = `["Object",${flatten(thing.valueOf())}]`;
+					break;
+				case "Date":
+					str = `["Date","${!isNaN(thing.getDate()) ? thing.toISOString() : ""}"]`;
+					break;
+				case "URL":
+					str = `["URL",${stringify_string(thing.toString())}]`;
+					break;
+				case "URLSearchParams":
+					str = `["URLSearchParams",${stringify_string(thing.toString())}]`;
+					break;
+				case "RegExp":
+					const { source, flags } = thing;
+					str = flags ? `["RegExp",${stringify_string(source)},"${flags}"]` : `["RegExp",${stringify_string(source)}]`;
+					break;
+				case "Array": {
+					let mostly_dense = false;
+					str = "[";
+					for (let i = 0; i < thing.length; i += 1) {
+						if (i > 0) str += ",";
+						if (Object.hasOwn(thing, i)) {
+							keys.push(`[${i}]`);
+							str += flatten(thing[i]);
+							keys.pop();
+						} else if (mostly_dense) str += -2;
+						else {
+							const populated_keys = valid_array_indices(thing);
+							const population = populated_keys.length;
+							const d = String(thing.length).length;
+							if ((thing.length - population) * 3 > 4 + d + population * (d + 1)) {
+								str = "[-7," + thing.length;
+								for (let j = 0; j < populated_keys.length; j++) {
+									const key = populated_keys[j];
+									keys.push(`[${key}]`);
+									str += "," + key + "," + flatten(thing[key]);
+									keys.pop();
+								}
+								break;
+							} else {
+								mostly_dense = true;
+								str += -2;
+							}
+						}
+					}
+					str += "]";
+					break;
+				}
+				case "Set":
+					str = "[\"Set\"";
+					for (const value of thing) str += `,${flatten(value)}`;
+					str += "]";
+					break;
+				case "Map":
+					str = "[\"Map\"";
+					for (const [key, value] of thing) {
+						keys.push(`.get(${is_primitive(key) ? stringify_primitive(key) : "..."})`);
+						str += `,${flatten(key)},${flatten(value)}`;
+						keys.pop();
+					}
+					str += "]";
+					break;
+				case "Int8Array":
+				case "Uint8Array":
+				case "Uint8ClampedArray":
+				case "Int16Array":
+				case "Uint16Array":
+				case "Float16Array":
+				case "Int32Array":
+				case "Uint32Array":
+				case "Float32Array":
+				case "Float64Array":
+				case "BigInt64Array":
+				case "BigUint64Array":
+				case "DataView": {
+					/** @type {import("./types.js").TypedArray} */
+					const typedArray = thing;
+					str = "[\"" + type + "\"," + flatten(typedArray.buffer);
+					if (typedArray.byteLength !== typedArray.buffer.byteLength) str += `,${typedArray.byteOffset},${typedArray.length}`;
+					str += "]";
+					break;
+				}
+				case "ArrayBuffer":
+					str = `["ArrayBuffer","${encode64(thing)}"]`;
+					break;
+				case "Temporal.Duration":
+				case "Temporal.Instant":
+				case "Temporal.PlainDate":
+				case "Temporal.PlainTime":
+				case "Temporal.PlainDateTime":
+				case "Temporal.PlainMonthDay":
+				case "Temporal.PlainYearMonth":
+				case "Temporal.ZonedDateTime":
+					str = `["${type}",${stringify_string(thing.toString())}]`;
+					break;
+				default:
+					if (!is_plain_object(thing)) throw new DevalueError(`Cannot stringify arbitrary non-POJOs`, keys, thing, value);
+					if (enumerable_symbols(thing).length > 0) throw new DevalueError(`Cannot stringify POJOs with symbolic keys`, keys, thing, value);
+					if (Object.getPrototypeOf(thing) === null) {
+						str = "[\"null\"";
+						for (const key of Object.keys(thing)) {
+							if (key === "__proto__") throw new DevalueError(`Cannot stringify objects with __proto__ keys`, keys, thing, value);
+							keys.push(stringify_key(key));
+							str += `,${stringify_string(key)},${flatten(thing[key])}`;
+							keys.pop();
+						}
+						str += "]";
+					} else {
+						str = "{";
+						let started = false;
+						for (const key of Object.keys(thing)) {
+							if (key === "__proto__") throw new DevalueError(`Cannot stringify objects with __proto__ keys`, keys, thing, value);
+							if (started) str += ",";
+							started = true;
+							keys.push(stringify_key(key));
+							str += `${stringify_string(key)}:${flatten(thing[key])}`;
+							keys.pop();
+						}
+						str += "}";
+					}
+			}
+		}
+		stringified[index] = str;
+		return index;
+	}
+	const index = flatten(value);
+	if (index < 0) return `${index}`;
+	return stringified;
+}
+/**
+* @param {any} thing
+* @returns {string}
+*/
+function stringify_primitive(thing) {
+	const type = typeof thing;
+	if (type === "string") return stringify_string(thing);
+	if (thing === void 0) return (-1).toString();
+	if (thing === 0 && 1 / thing < 0) return (-6).toString();
+	if (type === "bigint") return `["BigInt","${thing}"]`;
+	return String(thing);
+}
+//#endregion
 //#region src/flash.ts
 /**
 * Dev-only radiographic capture effect — pure delight. When a capture lands we
@@ -88,6 +614,23 @@ function isExtensionAck(value) {
 const DEFAULT_SETTLE_CAP = 5e3;
 const DEFAULT_MAX_NODES = 4e3;
 const RESIZE_DEBOUNCE = 300;
+/**
+* The capture roots for a site, the ONE place the auto/manual root models
+* diverge (ADR 0014, finding #6).
+*
+* - AUTO: `site.el` is the `display:contents` wrapper, a layout-neutral box, so
+*   the content is its CHILDREN — the synthetic root (id 0) stands in for the
+*   wrapper and the children become the plate's top level (today's behavior).
+*   `<STYLE>` children are dropped (a stitched-in scoped sheet, never content).
+* - MANUAL: `site.el` is the consumer's OWN styled element, so the element
+*   ITSELF is the root. Capturing its children would drop its box, classes,
+*   padding, border, background, and radius — the exact bug this fixes — so the
+*   element is the single root and its own box is serialized.
+*/
+function rootsFor(site) {
+	if (site.mode === "manual") return [site.el];
+	return Array.from(site.el.children).filter((child) => child.tagName !== "STYLE");
+}
 function installXrayClient(options) {
 	const win = window;
 	const defaultDelay = options.delay ?? 200;
@@ -95,6 +638,7 @@ function installXrayClient(options) {
 	const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
 	const sites = /* @__PURE__ */ new Set();
 	const matchMediaQueries = /* @__PURE__ */ new Set();
+	let captureGeneration = 0;
 	const livePlates = /* @__PURE__ */ new Map();
 	const plateSerialized = /* @__PURE__ */ new Map();
 	const plateListeners = /* @__PURE__ */ new Map();
@@ -129,6 +673,9 @@ function installXrayClient(options) {
 	};
 	const lightbox = createToggleStore(win, LIGHTBOX_KEY, LIGHTBOX_PARAM, false);
 	const captureEnabled = createToggleStore(win, CAPTURE_KEY, CAPTURE_PARAM, options.capture ?? true);
+	const replayEnabled = createToggleStore(win, REPLAY_KEY, REPLAY_PARAM, options.replay === "prefer" || options.replay === "missing-only");
+	const replayMode = options.replay === "missing-only" ? "missing-only" : "prefer";
+	const recordMode = options.record ?? "manual";
 	const isPrimaryForName = (site) => {
 		for (const other of sites) {
 			if (other === site || other.disposed || other.name !== site.name || !other.el.isConnected) continue;
@@ -136,17 +683,25 @@ function installXrayClient(options) {
 		}
 		return true;
 	};
-	const captureSite = async (site, force = false) => {
+	const runCapture = async (site, force, awaitSink) => {
 		if (!force && !captureEnabled.get() || site.tooLarge || !isPrimaryForName(site)) return;
-		await settle(site.el, site.delay, settleCap);
-		if (site.disposed || site.tooLarge || !site.el.isConnected || !isPrimaryForName(site)) return;
-		const roots = Array.from(site.el.children).filter((child) => child.tagName !== "STYLE");
+		const generation = captureGeneration;
+		await settle(site.el, site.delay, settleCap, site.mode);
+		if (generation !== captureGeneration || site.disposed || site.tooLarge || !site.el.isConnected || !isPrimaryForName(site)) return;
+		const roots = rootsFor(site);
 		if (roots.length === 0) return;
+		let payload;
+		let key;
 		try {
-			const capture = captureRegime(roots, { maxNodes });
+			const capture = captureRegime(roots, {
+				maxNodes,
+				walker: site.walker,
+				captureRootIsBoundary: site.mode === "manual"
+			});
+			reportDiagnostics(site.name, capture.diagnostics);
 			const breakpoints = deriveBreakpoints(capture.rules, [...matchMediaQueries]);
 			const span = regimeFor(capture.width, breakpoints);
-			const payload = {
+			payload = {
 				name: site.name,
 				capture: {
 					...capture,
@@ -154,31 +709,69 @@ function installXrayClient(options) {
 				},
 				breakpoints
 			};
-			const key = JSON.stringify(span);
+			key = JSON.stringify(span);
 			const body = JSON.stringify(payload);
 			if (site.sent.get(key) === body) return;
 			site.sent.set(key, body);
-			options.sink(payload);
-			flashCapture(site.el);
 		} catch (error) {
 			if (error instanceof CaptureTooLargeError) {
 				site.tooLarge = true;
-				console.warn(`[xray] skipping capture of "${site.name}": ${error.nodeCount} nodes (max ${maxNodes}).`, "A skeleton this big usually means the <Skeleton> sits too high in the tree.");
+				reportDiagnostics(site.name, [makeDiagnostic(error.code, { detail: `${error.nodeCount} nodes (max ${maxNodes})` })]);
 				return;
 			}
 			console.warn("[xray] capture failed for", site.name, error);
+			return;
+		}
+		if (generation !== captureGeneration || site.disposed) {
+			site.sent.delete(key);
+			return;
+		}
+		await sendCapture(site, payload, key, awaitSink);
+	};
+	const sendCapture = async (site, payload, key, awaitSink) => {
+		try {
+			await options.sink(payload);
+		} catch (error) {
+			site.sent.delete(key);
+			if (awaitSink) throw error;
+			console.warn("[xray] capture send failed for", site.name, error);
+			return;
+		}
+		flashCapture(site.el);
+	};
+	const scheduleCapture = (site, force = false, awaitSink = false) => {
+		if (site.inflight) {
+			site.dirty = true;
+			site.dirtyForce = site.dirtyForce || force;
+			site.dirtyAwaitSink = site.dirtyAwaitSink || awaitSink;
+			return site.inflight;
 		}
+		const loop = async (f, a) => {
+			await runCapture(site, f, a);
+			if (!site.dirty) return;
+			site.dirty = false;
+			const nextForce = site.dirtyForce;
+			const nextAwaitSink = site.dirtyAwaitSink;
+			site.dirtyForce = false;
+			site.dirtyAwaitSink = false;
+			await loop(nextForce, nextAwaitSink);
+		};
+		const promise = loop(force, awaitSink).finally(() => {
+			site.inflight = void 0;
+		});
+		site.inflight = promise;
+		return promise;
 	};
 	let resizeTimer;
 	const onResize = () => {
 		clearTimeout(resizeTimer);
 		resizeTimer = setTimeout(() => {
-			for (const site of sites) captureSite(site);
+			for (const site of sites) scheduleCapture(site);
 		}, RESIZE_DEBOUNCE);
 	};
 	win.addEventListener("resize", onResize);
 	const unsubscribeCapture = captureEnabled.subscribe(() => {
-		if (captureEnabled.get()) for (const site of sites) captureSite(site);
+		if (captureEnabled.get()) for (const site of sites) scheduleCapture(site);
 	});
 	const extAcks = /* @__PURE__ */ new Map();
 	let nextExtReqId = 1;
@@ -222,6 +815,58 @@ function installXrayClient(options) {
 			return () => coverageListeners.delete(cb);
 		}
 	};
+	const liveData = /* @__PURE__ */ new Map();
+	const recorded = /* @__PURE__ */ new Map();
+	const fixtureListeners = /* @__PURE__ */ new Set();
+	const notifyFixtures = () => {
+		for (const cb of fixtureListeners) cb();
+	};
+	const fixtures = {
+		register: (name, data) => {
+			const entry = { data };
+			const stack = liveData.get(name);
+			if (stack) stack.push(entry);
+			else liveData.set(name, [entry]);
+			return () => {
+				const current = liveData.get(name);
+				if (!current) return;
+				const i = current.indexOf(entry);
+				if (i !== -1) current.splice(i, 1);
+				if (current.length === 0) liveData.delete(name);
+			};
+		},
+		has: (name) => recorded.has(name),
+		read: (name) => recorded.get(name),
+		record: async (name) => {
+			const live = liveData.get(name)?.at(-1);
+			if (!live) throw new Error(`[xray] cannot record fixture for "${name}": no render-prop \`data\` is in scope. Only render-prop <Skeleton data={…}> sites participate in fixtures.`);
+			const encoded = stringify(live.data);
+			await options.recordFixtureSink?.({
+				name,
+				data: encoded
+			});
+			recorded.set(name, { data: parse(encoded) });
+			notifyFixtures();
+		},
+		recordAll: async () => {
+			await Promise.all([...liveData.keys()].map((name) => fixtures.record(name)));
+		},
+		seed: (encoded) => {
+			let changed = false;
+			for (const [name, str] of Object.entries(encoded)) {
+				if (recorded.has(name)) continue;
+				try {
+					recorded.set(name, { data: parse(str) });
+					changed = true;
+				} catch {}
+			}
+			if (changed) notifyFixtures();
+		},
+		subscribe: (cb) => {
+			fixtureListeners.add(cb);
+			return () => fixtureListeners.delete(cb);
+		}
+	};
 	const sweepWidths = () => {
 		const set = new Set(deriveBreakpoints([], [...matchMediaQueries]));
 		for (const site of sites) for (const bp of coverageMap.get(site.name)?.breakpoints ?? []) set.add(bp);
@@ -230,16 +875,25 @@ function installXrayClient(options) {
 		const first = min === void 0 ? 390 : Math.max(1, Math.min(390, min - 1));
 		return [...new Set([first, ...breakpoints])].toSorted((a, b) => a - b);
 	};
+	const MAX_SWEEP_PASSES = 8;
 	const captureAllViews = async () => {
-		const widths = sweepWidths();
+		const visited = /* @__PURE__ */ new Set();
 		try {
-			for (const width of widths) {
-				await extCommand("emulate", {
-					width,
-					height: 2400,
-					mobile: width < 600
-				});
-				await Promise.all([...sites].map((site) => captureSite(site, true)));
+			for (let pass = 0;; pass++) {
+				const pending = sweepWidths().filter((width) => !visited.has(width));
+				if (pending.length === 0) break;
+				if (pass >= MAX_SWEEP_PASSES) throw new Error(`xray capture-all did not converge after ${MAX_SWEEP_PASSES} passes (still discovering widths: ${pending.join(", ")})`);
+				for (const width of pending) {
+					visited.add(width);
+					captureGeneration++;
+					await extCommand("emulate", {
+						width,
+						height: 2400,
+						mobile: width < 600
+					});
+					await Promise.all([...sites].map((site) => scheduleCapture(site, true, true)));
+				}
+				await options.refreshCoverage?.();
 			}
 		} finally {
 			await extCommand("reset").catch(() => void 0);
@@ -252,21 +906,31 @@ function installXrayClient(options) {
 		updatePlate,
 		captureAllViews,
 		coverage,
+		replay: replayEnabled,
+		replayMode,
+		recordMode,
+		fixtures,
 		captured: (name, el, opts) => {
 			const site = {
 				name,
 				el,
 				delay: opts?.delay ?? defaultDelay,
+				mode: opts?.mode ?? "auto",
+				walker: opts?.walker,
 				sent: /* @__PURE__ */ new Map(),
 				disposed: false,
-				tooLarge: false
+				tooLarge: false,
+				dirty: false,
+				dirtyForce: false,
+				dirtyAwaitSink: false
 			};
 			sites.add(site);
-			captureSite(site);
+			scheduleCapture(site);
 			return () => {
 				site.disposed = true;
 				sites.delete(site);
-				for (const other of sites) if (other.name === site.name) captureSite(other);
+				captureGeneration++;
+				for (const other of sites) if (other.name === site.name) scheduleCapture(other);
 			};
 		}
 	};
@@ -277,13 +941,37 @@ function installXrayClient(options) {
 		clearTimeout(resizeTimer);
 		unsubscribeCapture();
 		globalThis.__XRAY__ = void 0;
+		captureGeneration++;
+		for (const site of sites) site.disposed = true;
 		sites.clear();
 	};
 }
+/**
+* Surface a capture's dev-only diagnostics as ONE grouped `console.warn` keyed
+* by plate name: a header line, then one formatted line per diagnostic via the
+* shared formatter (diagnostics.ts) — the same text the Vite server prints, so
+* the two never drift. `console.group` collapses the lines under the header;
+* we fall back to a single multi-line warn where it's unavailable. No-op when
+* there are no diagnostics, so a clean capture is silent.
+*/
+function reportDiagnostics(name, diagnostics) {
+	if (!diagnostics || diagnostics.length === 0) return;
+	const header = diagnosticsHeader(name);
+	const lines = diagnostics.map((d) => formatDiagnostic(d));
+	if (typeof console.group === "function" && typeof console.groupEnd === "function") {
+		console.group(header);
+		for (const line of lines) console.warn(line);
+		console.groupEnd();
+		return;
+	}
+	console.warn([header, ...lines].join("\n"));
+}
 const LIGHTBOX_KEY = "xray:lightbox";
 const LIGHTBOX_PARAM = "xray-lightbox";
 const CAPTURE_KEY = "xray:capture";
 const CAPTURE_PARAM = "xray-capture";
+const REPLAY_KEY = "xray:replay";
+const REPLAY_PARAM = "xray-replay";
 /**
 * A sticky boolean toggle: per-tab in sessionStorage, seedable to `true` via
 * `?<param>` in the URL, flipped from the HUD or the console
@@ -322,7 +1010,7 @@ function createToggleStore(win, key, param, initial) {
 * made single-shot capture non-deterministic in the M1 harness; this is the
 * cure. Hard-capped so a perpetually-animating subtree still captures.
 */
-function settle(el, delay, cap) {
+function settle(el, delay, cap, mode = "auto") {
 	const doc = el.ownerDocument;
 	return (doc.fonts ? doc.fonts.ready : Promise.resolve()).then(() => new Promise((resolve) => {
 		let timer;
@@ -345,7 +1033,8 @@ function settle(el, delay, cap) {
 			childList: true,
 			characterData: true
 		});
-		if (resizeObserver) for (const child of Array.from(el.children)) resizeObserver.observe(child);
+		if (resizeObserver) if (mode === "manual") resizeObserver.observe(el);
+		else for (const child of Array.from(el.children)) resizeObserver.observe(child);
 		timer = setTimeout(done, delay);
 		capTimer = setTimeout(done, cap);
 	}));