@hueest/xray 0.1.0

package/dist/breakpoints-CBNlh7lQ.js

@@ -0,0 +1,47 @@
+//#region src/breakpoints.ts
+/**
+* Per-plate breakpoint derivation (ADR 0004): the width thresholds that could
+* change this plate come from the `@media` conditions on its own copied rules
+* plus the queries the app evaluated through `matchMedia` during capture.
+* Thresholds partition the width axis into views; identical captures in
+* adjacent views collapse at merge time.
+*/
+const FONT_SIZE_PX = 16;
+/** A breakpoint is the first integer px width of the view ABOVE the boundary. */
+function thresholdsOf(condition) {
+	const out = [];
+	const toPx = (value, unit) => Number.parseFloat(value) * (unit === "px" ? 1 : FONT_SIZE_PX);
+	const push = (raw, exclusiveBelow) => {
+		const bp = exclusiveBelow ? Number.isInteger(raw) ? raw + 1 : Math.ceil(raw) : Math.ceil(raw);
+		if (Number.isFinite(bp) && bp > 0) out.push(bp);
+	};
+	for (const m of condition.matchAll(/min-width:\s*([\d.]+)(px|em|rem)/g)) push(toPx(m[1] ?? "", m[2] ?? "px"), false);
+	for (const m of condition.matchAll(/max-width:\s*([\d.]+)(px|em|rem)/g)) push(toPx(m[1] ?? "", m[2] ?? "px"), true);
+	for (const m of condition.matchAll(/width\s*>=?\s*([\d.]+)(px|em|rem)/g)) push(toPx(m[1] ?? "", m[2] ?? "px"), false);
+	for (const m of condition.matchAll(/width\s*<=?\s*([\d.]+)(px|em|rem)/g)) push(toPx(m[1] ?? "", m[2] ?? "px"), true);
+	for (const m of condition.matchAll(/([\d.]+)(px|em|rem)\s*<=?\s*width/g)) push(toPx(m[1] ?? "", m[2] ?? "px"), false);
+	return out;
+}
+/** Width thresholds for this plate: its rules' media conditions + the app's matchMedia queries. */
+function deriveBreakpoints(rules, matchMediaQueries = []) {
+	const set = /* @__PURE__ */ new Set();
+	for (const rule of rules) for (const condition of rule.media ?? []) for (const bp of thresholdsOf(condition)) set.add(bp);
+	for (const query of matchMediaQueries) for (const bp of thresholdsOf(query)) set.add(bp);
+	return [...set].toSorted((a, b) => a - b);
+}
+/** 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
+export { regimeFor as n, deriveBreakpoints as t };

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import { s as ViewCapture } from "./plate-DboxMKg-.js";
+
+//#region src/client.d.ts
+/**
+ * The dev capture client (M2). Runs in the browser during dev only: installs
+ * the `__XRAY__` hook `<Skeleton>` calls when content becomes ready,
+ * settles, serializes the subtree into a view capture, and hands it to the
+ * sink (the plugin's POST endpoint in M3). Re-captures when the viewport
+ * crosses into another view while a site is still mounted.
+ */
+interface CapturePayload {
+  name: string;
+  /** This capture, view interval already derived. */
+  capture: ViewCapture;
+  /** Width thresholds derived for this plate (rules' @media + matchMedia queries). */
+  breakpoints: number[];
+}
+interface ClientOptions {
+  /** Settle delay (ms) once the subtree goes quiet. Default 200. */
+  delay?: number;
+  /**
+   * Upper bound (ms) on waiting for quiet before capturing anyway. Raise it
+   * for pages that stream content for a long time. Default 5000.
+   */
+  settleCap?: number;
+  /**
+   * Refuse captures larger than this many nodes — a skeleton that big means
+   * the Skeleton sits too high in the component tree. Default 4000.
+   */
+  maxNodes?: number;
+  /**
+   * Initial state of the capture toggle: whether browsing re-captures plates.
+   * A per-tab override (sessionStorage / `?xray-capture`) wins over it.
+   * Defaults to `true` — the plugin passes its own (off-by-default) policy.
+   */
+  capture?: boolean;
+  /** Where finished captures go. */
+  sink: (payload: CapturePayload) => void;
+}
+declare function installXrayClient(options: ClientOptions): () => void;
+//#endregion
+export { CapturePayload, ClientOptions, installXrayClient };

package/dist/client.js

@@ -0,0 +1,354 @@
+import { i as captureRegime, t as CaptureTooLargeError } from "./serialize-Bq6yJnNV.js";
+import { n as regimeFor, t as deriveBreakpoints } from "./breakpoints-CBNlh7lQ.js";
+//#region src/flash.ts
+/**
+* Dev-only radiographic capture effect — pure delight. When a capture lands we
+* briefly "expose" the captured element: a cyan bloom, a negative blink (an
+* x-ray IS a negative — `backdrop-filter: invert`), and a scan-line sweep down
+* the box. Honors `prefers-reduced-motion` (then just a soft bloom). It's a
+* transient `position: fixed`, `pointer-events: none` overlay sitting just under
+* the HUD; it never touches the capture pipeline or the captured DOM.
+*/
+const STYLE_ID = "xr-flash-style";
+function ensureStyle() {
+	if (document.getElementById(STYLE_ID)) return;
+	const style = document.createElement("style");
+	style.id = STYLE_ID;
+	style.textContent = `
+    .xr-flash {
+      position: fixed; pointer-events: none; z-index: 2147483646;
+      overflow: hidden; border-radius: 4px;
+      animation: xr-expose 480ms ease-out forwards;
+    }
+    .xr-flash::after {
+      content: ''; position: absolute; left: 0; right: 0; height: 18%;
+      background: linear-gradient(180deg, transparent, rgba(186, 230, 253, 0.9), transparent);
+      filter: blur(1px);
+      animation: xr-scan 480ms ease-in-out forwards;
+    }
+    @keyframes xr-expose {
+      0% { background: rgba(186, 230, 253, 0); backdrop-filter: invert(0); opacity: 1 }
+      18% { background: rgba(186, 230, 253, 0.28); backdrop-filter: invert(1) }
+      100% { background: rgba(186, 230, 253, 0); backdrop-filter: invert(0); opacity: 0 }
+    }
+    @keyframes xr-scan {
+      from { transform: translateY(-100%) }
+      to { transform: translateY(560%) }
+    }
+    @keyframes xr-expose-soft {
+      0% { background: rgba(186, 230, 253, 0.25); opacity: 1 }
+      100% { background: rgba(186, 230, 253, 0); opacity: 0 }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      .xr-flash { animation: xr-expose-soft 320ms ease-out forwards }
+      .xr-flash::after { display: none }
+    }
+  `;
+	(document.head ?? document.documentElement).append(style);
+}
+/** The element's box, or the union of its children's (a display:contents wrapper has none). */
+function boxOf(el) {
+	const own = el.getBoundingClientRect();
+	if (own.width > 0 && own.height > 0) return own;
+	let left = Infinity;
+	let top = Infinity;
+	let right = -Infinity;
+	let bottom = -Infinity;
+	for (const child of el.children) {
+		const rect = child.getBoundingClientRect();
+		if (rect.width === 0 && rect.height === 0) continue;
+		left = Math.min(left, rect.left);
+		top = Math.min(top, rect.top);
+		right = Math.max(right, rect.right);
+		bottom = Math.max(bottom, rect.bottom);
+	}
+	return Number.isFinite(left) ? new DOMRect(left, top, right - left, bottom - top) : null;
+}
+/** Flash the radiographic effect over `el`'s box. No-op outside a laid-out DOM. */
+function flashCapture(el) {
+	if (typeof document === "undefined") return;
+	const box = boxOf(el);
+	if (!box) return;
+	ensureStyle();
+	const flash = document.createElement("div");
+	flash.className = "xr-flash";
+	flash.style.left = `${box.left}px`;
+	flash.style.top = `${box.top}px`;
+	flash.style.width = `${box.width}px`;
+	flash.style.height = `${box.height}px`;
+	flash.addEventListener("animationend", () => flash.remove(), { once: true });
+	(document.body ?? document.documentElement).append(flash);
+	setTimeout(() => flash.remove(), 1e3);
+}
+//#endregion
+//#region src/client.ts
+function isExtensionAck(value) {
+	return typeof value === "object" && value !== null && "source" in value && value.source === "xray-ext" && "kind" in value && value.kind === "ack" && "id" in value && typeof value.id === "number" && (!("ok" in value) || typeof value.ok === "boolean") && (!("error" in value) || typeof value.error === "string");
+}
+const DEFAULT_SETTLE_CAP = 5e3;
+const DEFAULT_MAX_NODES = 4e3;
+const RESIZE_DEBOUNCE = 300;
+function installXrayClient(options) {
+	const win = window;
+	const defaultDelay = options.delay ?? 200;
+	const settleCap = options.settleCap ?? DEFAULT_SETTLE_CAP;
+	const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+	const sites = /* @__PURE__ */ new Set();
+	const matchMediaQueries = /* @__PURE__ */ new Set();
+	const livePlates = /* @__PURE__ */ new Map();
+	const plateSerialized = /* @__PURE__ */ new Map();
+	const plateListeners = /* @__PURE__ */ new Map();
+	const plates = {
+		get: (name) => livePlates.get(name),
+		subscribe: (name, onChange) => {
+			let set = plateListeners.get(name);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				plateListeners.set(name, set);
+			}
+			set.add(onChange);
+			return () => set.delete(onChange);
+		},
+		seed: (name, plate) => {
+			if (livePlates.has(name)) return;
+			livePlates.set(name, plate);
+			plateSerialized.set(name, JSON.stringify(plate));
+		}
+	};
+	const updatePlate = (name, plate) => {
+		const json = JSON.stringify(plate);
+		if (plateSerialized.get(name) === json) return;
+		plateSerialized.set(name, json);
+		livePlates.set(name, plate);
+		for (const cb of plateListeners.get(name) ?? []) cb();
+	};
+	const nativeMatchMedia = win.matchMedia.bind(win);
+	win.matchMedia = (query) => {
+		matchMediaQueries.add(query);
+		return nativeMatchMedia(query);
+	};
+	const lightbox = createToggleStore(win, LIGHTBOX_KEY, LIGHTBOX_PARAM, false);
+	const captureEnabled = createToggleStore(win, CAPTURE_KEY, CAPTURE_PARAM, options.capture ?? true);
+	const isPrimaryForName = (site) => {
+		for (const other of sites) {
+			if (other === site || other.disposed || other.name !== site.name || !other.el.isConnected) continue;
+			if ((site.el.compareDocumentPosition(other.el) & Node.DOCUMENT_POSITION_PRECEDING) !== 0) return false;
+		}
+		return true;
+	};
+	const captureSite = async (site, force = false) => {
+		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");
+		if (roots.length === 0) return;
+		try {
+			const capture = captureRegime(roots, { maxNodes });
+			const breakpoints = deriveBreakpoints(capture.rules, [...matchMediaQueries]);
+			const span = regimeFor(capture.width, breakpoints);
+			const payload = {
+				name: site.name,
+				capture: {
+					...capture,
+					...span
+				},
+				breakpoints
+			};
+			const 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.");
+				return;
+			}
+			console.warn("[xray] capture failed for", site.name, error);
+		}
+	};
+	let resizeTimer;
+	const onResize = () => {
+		clearTimeout(resizeTimer);
+		resizeTimer = setTimeout(() => {
+			for (const site of sites) captureSite(site);
+		}, RESIZE_DEBOUNCE);
+	};
+	win.addEventListener("resize", onResize);
+	const unsubscribeCapture = captureEnabled.subscribe(() => {
+		if (captureEnabled.get()) for (const site of sites) captureSite(site);
+	});
+	const extAcks = /* @__PURE__ */ new Map();
+	let nextExtReqId = 1;
+	const onExtMessage = (event) => {
+		if (event.source !== win) return;
+		const data = event.data;
+		if (isExtensionAck(data)) {
+			extAcks.get(data.id)?.({
+				ok: data.ok ?? false,
+				error: data.error
+			});
+			extAcks.delete(data.id);
+		}
+	};
+	win.addEventListener("message", onExtMessage);
+	const extCommand = (kind, extra = {}) => {
+		const id = nextExtReqId++;
+		return new Promise((resolve, reject) => {
+			extAcks.set(id, (res) => res.ok ? resolve() : reject(new Error(res.error ?? "xray extension error")));
+			win.postMessage({
+				source: "xray",
+				kind,
+				id,
+				...extra
+			}, "*");
+			setTimeout(() => {
+				if (extAcks.delete(id)) reject(/* @__PURE__ */ new Error("xray extension did not respond (installed? DevTools closed on this tab?)"));
+			}, 1e4);
+		});
+	};
+	const coverageMap = /* @__PURE__ */ new Map();
+	const coverageListeners = /* @__PURE__ */ new Set();
+	const coverage = {
+		get: () => coverageMap,
+		set: (name, plateCoverage) => {
+			coverageMap.set(name, plateCoverage);
+			for (const cb of coverageListeners) cb();
+		},
+		subscribe: (cb) => {
+			coverageListeners.add(cb);
+			return () => coverageListeners.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);
+		const breakpoints = [...set].toSorted((a, b) => a - b);
+		const min = breakpoints[0];
+		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 captureAllViews = async () => {
+		const widths = sweepWidths();
+		try {
+			for (const width of widths) {
+				await extCommand("emulate", {
+					width,
+					height: 2400,
+					mobile: width < 600
+				});
+				await Promise.all([...sites].map((site) => captureSite(site, true)));
+			}
+		} finally {
+			await extCommand("reset").catch(() => void 0);
+		}
+	};
+	globalThis.__XRAY__ = {
+		lightbox,
+		capture: captureEnabled,
+		plates,
+		updatePlate,
+		captureAllViews,
+		coverage,
+		captured: (name, el, opts) => {
+			const site = {
+				name,
+				el,
+				delay: opts?.delay ?? defaultDelay,
+				sent: /* @__PURE__ */ new Map(),
+				disposed: false,
+				tooLarge: false
+			};
+			sites.add(site);
+			captureSite(site);
+			return () => {
+				site.disposed = true;
+				sites.delete(site);
+				for (const other of sites) if (other.name === site.name) captureSite(other);
+			};
+		}
+	};
+	return () => {
+		win.matchMedia = nativeMatchMedia;
+		win.removeEventListener("resize", onResize);
+		win.removeEventListener("message", onExtMessage);
+		clearTimeout(resizeTimer);
+		unsubscribeCapture();
+		globalThis.__XRAY__ = void 0;
+		sites.clear();
+	};
+}
+const LIGHTBOX_KEY = "xray:lightbox";
+const LIGHTBOX_PARAM = "xray-lightbox";
+const CAPTURE_KEY = "xray:capture";
+const CAPTURE_PARAM = "xray-capture";
+/**
+* A sticky boolean toggle: per-tab in sessionStorage, seedable to `true` via
+* `?<param>` in the URL, flipped from the HUD or the console
+* (`__XRAY__.lightbox.set(true)`). A stored value wins over `initial`; the
+* URL param forces `true`.
+*/
+function createToggleStore(win, key, param, initial) {
+	let value = initial;
+	try {
+		const stored = win.sessionStorage.getItem(key);
+		if (stored !== null) value = stored === "1";
+	} catch {}
+	if (new URL(win.location.href).searchParams.has(param)) value = true;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		get: () => value,
+		set(next) {
+			if (next === value) return;
+			value = next;
+			try {
+				win.sessionStorage.setItem(key, next ? "1" : "0");
+			} catch {}
+			for (const listener of listeners) listener();
+		},
+		subscribe(onChange) {
+			listeners.add(onChange);
+			return () => {
+				listeners.delete(onChange);
+			};
+		}
+	};
+}
+/**
+* Resolve once the subtree has been quiet (no mutations, no child resizes)
+* for `delay` ms — fonts loaded first. Charts, lazy images and late embeds
+* 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) {
+	const doc = el.ownerDocument;
+	return (doc.fonts ? doc.fonts.ready : Promise.resolve()).then(() => new Promise((resolve) => {
+		let timer;
+		let capTimer;
+		const observer = new MutationObserver(bump);
+		const resizeObserver = typeof ResizeObserver === "undefined" ? void 0 : new ResizeObserver(bump);
+		function done() {
+			observer.disconnect();
+			resizeObserver?.disconnect();
+			clearTimeout(timer);
+			clearTimeout(capTimer);
+			resolve();
+		}
+		function bump() {
+			clearTimeout(timer);
+			timer = setTimeout(done, delay);
+		}
+		observer.observe(el, {
+			subtree: true,
+			childList: true,
+			characterData: true
+		});
+		if (resizeObserver) for (const child of Array.from(el.children)) resizeObserver.observe(child);
+		timer = setTimeout(done, delay);
+		capTimer = setTimeout(done, cap);
+	}));
+}
+//#endregion
+export { installXrayClient };

package/dist/core.d.ts

@@ -0,0 +1,55 @@
+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";
+
+//#region src/chunk.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+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>`.
+ */
+declare function captureElement(roots: readonly Element[], options: CaptureOptions): Plate;
+/**
+ * Render a stitch-free Plate to a self-contained HTML string — the
+ * framework-neutral equivalent of `<Skeleton plate loading />`, for when you
+ * don't want to pull a framework adapter (demos, plain DOM, server strings).
+ * Drop it in with `el.innerHTML = renderPlateHtml(plate)` or React's
+ * `dangerouslySetInnerHTML`. The string is self-contained: it carries BASE_CSS
+ * + the plate's scoped rules in its own `<style>`. Stitched plates (a nested
+ * `<Skeleton>`) need an adapter to mount their child plates, so they throw here.
+ */
+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 };