@hueest/xray 0.5.0 → 0.7.0

package/dist/core.js

@@ -1,52 +1,58 @@
-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-BZosujs9.js";
-import { t as escapeStyleText } from "./css-escape-N7bOusGW.js";
+import { a as ROOT_ATTR, d as composeCss, f as emptyPlate, o as ROOT_CLASS, t as BASE_CSS } from "./plate-CXIh5_OB.js";
+import { a as serializePlate, c as defineXrayCaptureWalker, i as collectRefs, l as distilPlate, o as CaptureTooLargeError, s as captureView, t as serializePlateIR } from "./serialize-Cj-EHvMv.js";
+import { t as escapeStyleText } from "./css-escape-DJ-BsrNm.js";
 //#region src/core.ts
 /**
-* 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>`.
+* Capture a live DOM subtree straight to the two renderable artifacts: the structural `plate`
+* (tree, lowered to chunks) and its scoped `css` string — independent parts, per the two-artifact
+* contract. Runs the same uniform pipeline the dev client does for a single View — measure
+* (`captureView`), distil (`distilPlate`), 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). Render however suits: `renderPlateHtml(plate,
+* composeCss(css))`, or `<Skeleton plate={plate} css={composeCss(css)}>` with the React adapter.
 *
-* `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.
+* `options.walker` is the public programmable capture walker (ADR 0018): 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
+* artifacts.
 */
 function captureElement(roots, options) {
-	const plate = captureView(roots, {
+	const plateIR = captureView(roots, {
 		collect: options.collect,
 		walker: options.walker,
 		captureRootIsBoundary: options.captureRootIsBoundary
 	});
-	plate.name = options.name;
-	runPlatePasses(plate);
-	return serializePlate(serializePlateIR(plate));
+	plateIR.name = options.name;
+	distilPlate(plateIR);
+	const stored = serializePlateIR(plateIR);
+	return {
+		plate: serializePlate(stored),
+		css: stored.css
+	};
 }
 /**
-* 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.
+* Render a stitch-free Plate to an 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, composeCss(css))` or React's
+* `dangerouslySetInnerHTML`.
+*
+* `css` is the caller's explicit input (two-artifact contract): pass `composeCss(css)` for the
+* standard BASE_CSS + plate-rules composition (BASE_CSS is what makes bones paint and pulse), the
+* raw capture css if the base rules are already on the page, or your own composition. Stitched
+* plates (a nested `<Skeleton>`) need an adapter to mount their child plates, so they throw here.
 */
-function renderPlateHtml(plate) {
+function renderPlateHtml(plate, css) {
 	const chunks = plate.chunks;
 	if (!chunks) return "";
 	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${escapeStyleText(plate.css)}</style>${chunksToHtml(chunks)}</div>`;
+	return `<div ${ROOT_ATTR}="${plate.name}" class="${className}" aria-hidden="true" aria-busy="true"><style>${escapeStyleText(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.
+* 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 safe to interpolate raw.
 */
 function chunksToHtml(chunks) {
 	let html = "";
@@ -57,4 +63,4 @@ function chunksToHtml(chunks) {
 	return html;
 }
 //#endregion
-export { CaptureTooLargeError, captureElement, collectRefs, defineXrayCaptureWalker, emptyPlate, renderPlateHtml, serializePlate };
+export { BASE_CSS, CaptureTooLargeError, captureElement, collectRefs, composeCss, defineXrayCaptureWalker, emptyPlate, renderPlateHtml, serializePlate };

package/dist/css-escape-DJ-BsrNm.js

@@ -0,0 +1,47 @@
+//#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, ADR 0023), 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 the capture emits, 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.d.ts

@@ -1,14 +1,13 @@
 //#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.
+ * 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`).
+ * 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;

package/dist/hud.js

@@ -3,8 +3,8 @@ 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.
+* 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");
@@ -19,9 +19,9 @@ function toggleRow(store, 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).
+* 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);