@hueest/xray 0.1.0

package/dist/core.js

@@ -0,0 +1,230 @@
+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
+//#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>`.
+*/
+function captureElement(roots, options) {
+	return serializePlate(capture(roots, options));
+}
+/**
+* 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.
+*/
+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>`;
+}
+//#endregion
+export { CaptureTooLargeError, addCapture, capture, captureElement, captureRegime, collectRefs, emptyPlate, mergeViews, renderPlateHtml, serializePlate };

package/dist/hud.d.ts

@@ -0,0 +1,18 @@
+//#region src/hud.d.ts
+/**
+ * The opt-in dev HUD (Astro-dev-toolbar-style): a small fixed badge. For each
+ * plate it shows every detected width band — captured ones lit, the rest dim —
+ * sourced from the committed plate files (via `__XRAY__.coverage`), not the
+ * session, so it reflects what's actually on disk.
+ *
+ * It is also the controller for capture-all-views (ADR 0010): it probes for the
+ * companion extension (which announces itself via its content script) and shows
+ * a "Capture all views" button when present, or a one-line promotion when not.
+ * The sweep itself lives in the dev client (`__XRAY__.captureAllViews`).
+ */
+interface HudHandle {
+  dispose: () => void;
+}
+declare function installXrayHud(): HudHandle;
+//#endregion
+export { HudHandle, installXrayHud };

package/dist/hud.js

@@ -0,0 +1,165 @@
+//#region src/hud.ts
+function isExtensionHello(value) {
+	return typeof value === "object" && value !== null && "source" in value && value.source === "xray-ext" && "kind" in value && value.kind === "hello";
+}
+/**
+* A labelled checkbox bound to a sticky toggle store; reads the store on build
+* so a console/URL flip stays in sync with the box at the next render.
+*/
+function toggleRow(store, text) {
+	const label = document.createElement("label");
+	label.className = "toggle";
+	const checkbox = document.createElement("input");
+	checkbox.type = "checkbox";
+	checkbox.checked = store.get();
+	checkbox.addEventListener("change", () => {
+		store.set(checkbox.checked);
+	});
+	label.append(checkbox, document.createTextNode(text));
+	return label;
+}
+/**
+* Expand a plate's coverage into the full set of width bands, flagging which are
+* captured. The breakpoints partition the width axis; a band is covered when a
+* captured span matches it (spans align to band boundaries, ADR 0004).
+*/
+function bandsOf({ breakpoints, spans }) {
+	const sorted = [...breakpoints].toSorted((a, b) => a - b);
+	const bands = [];
+	for (let i = 0; i <= sorted.length; i++) bands.push({
+		min: i === 0 ? void 0 : sorted[i - 1],
+		max: i === sorted.length ? void 0 : sorted[i]
+	});
+	return bands.map((band) => ({
+		label: `[${band.min ?? 0},${band.max ?? "∞"})`,
+		covered: spans.some((span) => span.min === band.min && span.max === band.max)
+	}));
+}
+function installXrayHud() {
+	const host = document.createElement("div");
+	host.setAttribute("data-xray-hud", "");
+	const shadow = host.attachShadow({ mode: "open" });
+	const style = document.createElement("style");
+	style.textContent = `
+    .hud {
+      position: fixed; bottom: 12px; right: 12px; z-index: 2147483647;
+      background: #1c1c1f; color: #e4e4e7; border: 1px solid #3f3f46;
+      border-radius: 8px; padding: 8px 10px; max-width: 340px;
+      font: 11px/1.5 ui-monospace, monospace; opacity: 0.92;
+    }
+    .title { font-weight: 700; margin-bottom: 2px; color: #a1a1aa }
+    .plate { display: flex; gap: 8px; justify-content: space-between }
+    .bands { text-align: right }
+    .band.covered { color: #4ade80 }
+    .band.missing { color: #52525b }
+    .toggle { display: flex; gap: 6px; align-items: center; cursor: pointer; user-select: none }
+    .toggle input { accent-color: #4ade80; margin: 0 }
+    .action {
+      display: block; width: 100%; margin: 6px 0 2px; padding: 5px 8px;
+      border: 0; border-radius: 5px; background: #4ade80; color: #0a0a0a;
+      font: inherit; font-weight: 700; cursor: pointer;
+    }
+    .action:disabled { opacity: 0.6; cursor: default }
+    .promo { margin: 6px 0 2px; color: #a1a1aa }
+    .promo a { color: #4ade80 }
+    .status { color: #a1a1aa }
+  `;
+	const panel = document.createElement("div");
+	panel.className = "hud";
+	shadow.append(style, panel);
+	let extensionPresent = false;
+	let sweeping = false;
+	let sweepStatus = "";
+	const render = () => {
+		panel.textContent = "";
+		const coverage = globalThis.__XRAY__?.coverage?.get();
+		const count = coverage?.size ?? 0;
+		const title = document.createElement("div");
+		title.className = "title";
+		title.textContent = count === 0 ? "xray" : `xray — ${count} plate${count > 1 ? "s" : ""}`;
+		panel.append(title);
+		const capture = globalThis.__XRAY__?.capture;
+		if (capture) panel.append(toggleRow(capture, "Capture"));
+		const lightbox = globalThis.__XRAY__?.lightbox;
+		if (lightbox) panel.append(toggleRow(lightbox, "Light Box"));
+		if (globalThis.__XRAY__?.captureAllViews) if (extensionPresent) {
+			const button = document.createElement("button");
+			button.className = "action";
+			button.type = "button";
+			button.disabled = sweeping;
+			button.textContent = sweeping ? "Capturing all views…" : "Capture all views";
+			button.addEventListener("click", () => {
+				startSweep();
+			});
+			panel.append(button);
+			if (sweepStatus) {
+				const status = document.createElement("div");
+				status.className = "status";
+				status.textContent = sweepStatus;
+				panel.append(status);
+			}
+		} else {
+			const promo = document.createElement("div");
+			promo.className = "promo";
+			promo.textContent = "Install the xray extension to capture all views in one click.";
+			panel.append(promo);
+		}
+		for (const [name, plateCoverage] of coverage ?? []) {
+			const row = document.createElement("div");
+			row.className = "plate";
+			const label = document.createElement("span");
+			label.textContent = name;
+			const bands = document.createElement("span");
+			bands.className = "bands";
+			for (const band of bandsOf(plateCoverage)) {
+				const chip = document.createElement("span");
+				chip.className = `band ${band.covered ? "covered" : "missing"}`;
+				chip.textContent = band.label;
+				bands.append(chip, document.createTextNode(" "));
+			}
+			row.append(label, bands);
+			panel.append(row);
+		}
+	};
+	async function startSweep() {
+		if (sweeping) return;
+		sweeping = true;
+		sweepStatus = "";
+		render();
+		try {
+			await globalThis.__XRAY__?.captureAllViews?.();
+			sweepStatus = "Done — coverage updated.";
+		} catch (error) {
+			sweepStatus = `Failed: ${error instanceof Error ? error.message : String(error)}`;
+		} finally {
+			sweeping = false;
+			render();
+		}
+	}
+	const onHudMessage = (event) => {
+		if (event.source !== window) return;
+		if (isExtensionHello(event.data) && !extensionPresent) {
+			extensionPresent = true;
+			render();
+		}
+	};
+	window.addEventListener("message", onHudMessage);
+	window.postMessage({
+		source: "xray",
+		kind: "whois"
+	}, "*");
+	const unsubscribeCoverage = globalThis.__XRAY__?.coverage?.subscribe(render);
+	render();
+	const mount = () => {
+		if (document.body) document.body.append(host);
+		else document.addEventListener("DOMContentLoaded", () => document.body.append(host));
+	};
+	mount();
+	return { dispose() {
+		window.removeEventListener("message", onHudMessage);
+		unsubscribeCoverage?.();
+		host.remove();
+	} };
+}
+//#endregion
+export { installXrayHud };