@hueest/xray 0.2.0 → 0.4.0

package/dist/core.js

@@ -1,212 +1,14 @@
-import { a as ROOT_ATTR, c as SPEC_GATE, d as emptyPlate, i as NODE_CLASS, o as ROOT_CLASS, r as LEAF_CLASS, t as BASE_CSS } from "./plate-DoE1HEXp.js";
-import { a as captureRegime, i as capture, n as regimeFor, o as defineXrayCaptureWalker, r as CaptureTooLargeError, u as classify } from "./breakpoints-CMoFUUOv.js";
+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";
-//#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 { diagnostics: _diagnostics, ...persisted } = capture;
-	const views = [...file?.views ?? [], persisted];
-	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>`.
+* 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
@@ -214,7 +16,14 @@ function addCapture(file, name, capture, breakpoints) {
 * capture-only and never persisted into the returned Plate.
 */
 function captureElement(roots, options) {
-	return serializePlate(capture(roots, options));
+	const plate = captureView(roots, {
+		collect: options.collect,
+		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
@@ -228,9 +37,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${escapeStyleText(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, defineXrayCaptureWalker, emptyPlate, mergeViews, renderPlateHtml, serializePlate };
+export { CaptureTooLargeError, captureElement, collectRefs, defineXrayCaptureWalker, emptyPlate, renderPlateHtml, serializePlate };

package/dist/index.d.ts

@@ -7,8 +7,8 @@ import { Plugin } from "vite";
  * browser console (`client.ts`) and the Vite server output (`index.ts`) print.
  *
  * Motivation: the serializer silently swallows a handful of capture omissions
- * (an unreadable cross-origin stylesheet, skipped pseudo-elements, a collapsed
- * list run, an over-the-limit subtree). Early adopters asking "why does this
+ * (an unreadable cross-origin stylesheet, skipped pseudo-elements, off-screen
+ * bones dropped at the fold, an over-the-limit subtree). Early adopters asking "why does this
  * skeleton look wrong?" had to read the serializer source to find out. These
  * diagnostics surface those omissions as data the capture process returns, so a
  * caller can log them — without the core performing any console side effects.
@@ -16,7 +16,7 @@ import { Plugin } from "vite";
  * Strictly DEV-ONLY (see the plan's decisions and ADR 0008): this type is NOT a
  * public package export and MUST NEVER reach the persisted Plate JSON, the
  * `MergedPlate`, or the production adapter. It rides on the TRANSIENT
- * `ViewCapture.diagnostics` field only, which `captureRegime` populates and the
+ * `ViewIR.diagnostics` field only, which `captureView` populates and the
  * dev client strips before posting (so committed `plates/<name>.json` stays
  * byte-identical to a capture that produced no diagnostics).
  *
@@ -46,10 +46,10 @@ interface CaptureDiagnostic {
  * serializer (or an existing oversized-capture warning folded into the same
  * vocabulary). Kept as a const union so the message table is exhaustive.
  */
-type DiagnosticCode = 'unreadable-stylesheet' | 'unreadable-import' | 'skipped-dynamic-pseudo' | 'skipped-pseudo-element' | 'unsupported-rule' | 'dropped-tag' | 'pruned-run' | 'too-large' | 'invalid-plate-file';
+type DiagnosticCode = 'unreadable-stylesheet' | 'unreadable-import' | 'skipped-dynamic-pseudo' | 'skipped-pseudo-element' | 'unsupported-rule' | 'dropped-tag' | 'dropped-subset' | 'dropped-cropped' | 'too-large' | 'invalid-plate-file';
 //#endregion
 //#region src/plate.d.ts
-type LeafKind = 'text' | 'media' | 'box';
+type LeafKind = 'text' | 'text-block' | 'media' | 'box';
 /**
  * The shipped structural capture of a component's rendered DOM — the data a
  * Skeleton renders from (see CONTEXT.md). Self-contained: pre-serialized chunks
@@ -83,21 +83,27 @@ interface Plate {
 /**
  * One serialized child of a plate root (or of a stitch-bearing node): a
  * stitch-free HTML run (`string`), a stitch to a child plate (`{ r: name }`),
- * or a stitch-bearing element kept real so its inner stitches can mount
- * (`{ c: className, k: chunk[] }`). The framework-neutral render contract: an
- * adapter injects the strings and mounts a child plate at each stitch (ADR 0008).
+ * a stitch-bearing element kept real so its inner stitches can mount
+ * (`{ c: className, k: chunk[] }`), or a templated uniform run (`{ t: html, n }`):
+ * the cell's HTML once plus a repeat count the adapter expands to N copies (Phase
+ * 2). The framework-neutral render contract: an adapter injects the strings,
+ * mounts a child plate at each stitch, and repeats each template (ADR 0008).
  */
 type Chunk = string | {
   r: string;
 } | {
   c: string;
   k: Chunk[];
+} | {
+  t: string;
+  n: number;
 };
 /**
- * A plate after view-merge + classify but before chunk serialization: the
- * build-time RenderNode tree plus its scoped CSS. Produced by `mergeViews` and
- * `capture`, then serialized into the shipped `Plate` (chunks) at load
- * (`serializePlate`). Never shipped to the client.
+ * A plate after the in-browser Serialize (emit + merge/gate + classify) but
+ * before chunk serialization: the build-time RenderNode tree plus its scoped
+ * CSS. Produced by `serializePlateIR` (the structural part of `StoredPlate`) and
+ * the single-View `capture`, then serialized into the shipped `Plate` (chunks) at
+ * load (`serializePlate`). Never shipped to the client.
  */
 interface MergedPlate {
   v: number;
@@ -116,6 +122,12 @@ interface PlateNode {
    * against `Plate.refs` (prod) or the live store (dev).
    */
   ref?: string;
+  /**
+   * A templated uniform run (Phase 2): render this node's subtree `count` times.
+   * The serializer emits the subtree's HTML once plus the count; the adapter
+   * expands it to N copies at render. Absent on ordinary nodes.
+   */
+  count?: number;
   kids?: PlateNode[];
 }
 /**
@@ -128,6 +140,8 @@ interface RenderNode {
   leaf?: LeafKind;
   ref?: string;
   cls?: string;
+  /** A templated uniform run (Phase 2): serialize this subtree once + a count the adapter repeats. */
+  count?: number;
   kids?: RenderNode[];
 }
 /**
@@ -148,8 +162,11 @@ interface PlateRule {
 }
 /**
  * One capture of a component within one viewport view — `[min, max)` in px,
- * either side open-ended when undefined. What the dev client ships to the
- * plugin, and what the plate file accumulates (ADR 0004).
+ * either side open-ended when undefined. The id-form `{ tree, rules }` shape
+ * `emit` projects a measured View into (ADR 0004). NO LONGER the disk/wire shape
+ * after the ADR 0022 cutover — `StoredPlate` (below) is. Kept as the
+ * framework-neutral per-View capture shape, exported for consumers reading the
+ * id-form projection directly.
  */
 interface ViewCapture {
   /** Viewport width at capture time. */
@@ -160,23 +177,31 @@ interface ViewCapture {
   rules: PlateRule[];
   /**
    * TRANSIENT, dev-only capture diagnostics (why this view may be lower
-   * fidelity). Populated by `captureRegime` in the browser; the dev client logs
-   * it and posts it (so the Vite server can print the same text), then it is
-   * STRIPPED at the merge layer (`addCapture`) before persisting. It MUST NEVER
-   * be persisted: it is not part of the committed `plates/<name>.json` shape,
-   * the `isViewCapture` validator does not require it, and `addCapture` drops it
-   * so neither it nor `mergeViews` ever writes it. Absent in production (the
-   * prod adapter ships no capture). See diagnostics.ts and ADR 0008.
+   * fidelity). Captured in the browser (mirrored onto `ViewIR.diagnostics`); the
+   * dev client logs it and posts it alongside the `StoredPlate` (so the Vite
+   * server can print the same text). It MUST NEVER be persisted: it is not part
+   * of the committed
+   * `StoredPlate` disk shape, the validator does not carry it, and the POST
+   * envelope keeps it in a SIBLING field that never reaches the stored artifact
+   * (ADR 0008). Absent in production (the prod adapter ships no capture). See
+   * diagnostics.ts and ADR 0008.
    */
   diagnostics?: CaptureDiagnostic[];
 }
-/** The committed `plates/<name>.json`: per-view captures, merged at load. */
-interface PlateFile {
-  v: number;
-  name: string;
-  /** Width thresholds (view boundaries) derived so far. */
+/**
+ * The committed `plates/<name>.json` shape AFTER the ADR 0022 cutover: the whole
+ * Plate already projected in the browser (the in-browser Serialize folds emit +
+ * the multi-View merge/gate + classify in one session), so disk holds ONE gated,
+ * content-addressed tree + css instead of per-View captures merged at load. It is
+ * a `MergedPlate` (the structural `{tree, css}` `serializePlate` consumes) PLUS the
+ * `breakpoints` the HUD coverage reads — the analysis-only geometry never crosses
+ * the wire (ADR 0021). The gen-side runs `serializePlate(stored) → Plate` (chunks)
+ * at module-load, leaving the Tailwind/Bundle passthrough a clean gen-side seam.
+ * Replaces `PlateFile` (+ `ViewCapture`) on disk and on the `/__xray` wire.
+ */
+interface StoredPlate extends MergedPlate {
+  /** Width thresholds (view boundaries); the HUD coverage derives its bands from these. */
   breakpoints: number[];
-  views: ViewCapture[];
 }
 /**
  * A dev-only sticky boolean toggle (get/set/subscribe), persisted per tab.
@@ -298,6 +323,11 @@ interface CaptureHook {
     delay?: number;
     walker?: unknown;
     mode?: 'auto' | 'manual';
+    collect?: {
+      maxNodes?: number;
+      maxBreadth?: number;
+      maxDepth?: number;
+    };
   }) => (() => void) | undefined;
   /** Light Box toggle: force every `<Skeleton>` to its skeleton, read by `<Skeleton>`. */
   lightbox?: ToggleStore;
@@ -305,8 +335,8 @@ interface CaptureHook {
   capture?: ToggleStore;
   /** Read side for `<Skeleton>`. */
   plates?: PlateStore;
-  /** Write side for the dev client's HMR-event handler. */
-  updatePlate?: (name: string, plate: Plate) => void;
+  /** Write side for the dev client's HMR-event handler. Returns whether the plate changed. */
+  updatePlate?: (name: string, plate: Plate) => boolean;
   /** Dev-only: run the HUD-triggered capture-all-views sweep via the extension (ADR 0010). */
   captureAllViews?: () => Promise<void>;
   /** Dev-only per-plate breakpoints + captured spans, from disk; fed by the bootstrap. */
@@ -335,29 +365,17 @@ declare global {
   var __XRAY__: CaptureHook | undefined;
 }
 //#endregion
-//#region src/merge.d.ts
+//#region src/chunk.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/name.d.ts
 /**
@@ -412,8 +430,19 @@ interface XrayOptions {
   delay?: number;
   /** Upper bound in milliseconds on waiting for a busy subtree to go quiet before capturing anyway. Default: `5000`. */
   settleCap?: number;
-  /** Refuse captures larger than this many nodes (Skeleton too high in the tree). Default: `4000`. */
-  maxNodes?: number;
+  /**
+   * Collect-stage limits (ADR 0022): refuse to capture a boundary whose measured
+   * tree exceeds any axis — too big means the Skeleton sits too high in the tree.
+   * `maxNodes` caps total surviving nodes (default `4096`), `maxBreadth` the widest
+   * level (default `512`), `maxDepth` the nesting depth (default `32`). Omit
+   * `maxNodes` and it derives as `round(maxBreadth × maxDepth / 4)`. Override one
+   * boundary with the flat `maxNodes`/`maxBreadth`/`maxDepth` `<Skeleton>` props.
+   */
+  collect?: {
+    maxNodes?: number;
+    maxBreadth?: number;
+    maxDepth?: number;
+  };
   /**
    * Dev-only Fixtures (ADR 0015): record a `<Skeleton>`'s render-input `data` to a
    * `plates/<name>.fixture.json` sidecar and replay it in place of live data so
@@ -488,16 +517,16 @@ interface CaptureServer {
   };
 }
 /**
- * Per-plate breakpoints + captured spans, read from the committed plate files.
+ * Per-plate breakpoints + derived coverage bands, read from the committed
+ * StoredPlate files. The `spans` derive from each plate's `breakpoints` (ADR 0022
+ * cutover — per-View spans no longer exist on disk; a StoredPlate sweeps all
+ * widths in one session, so its coverage is complete).
  *
  * @internal
  */
 declare function readCoverage(dir: string): Record<string, {
   breakpoints: number[];
-  spans: {
-    min?: number;
-    max?: number;
-  }[];
+  spans: Span[];
 }>;
 /**
  * All recorded Fixtures as `{ <name>: <devalueString> }`, read from the
@@ -522,7 +551,12 @@ declare function readFixtures(dir: string): Record<string, string>;
  */
 declare function handleFixturePost(req: CaptureRequest, res: CaptureResponse, fixturePath: (name: string) => string): void;
 /**
- * Fold a posted capture into its plate file and hot-swap the plate in place.
+ * Validate a posted `StoredPlate` envelope, write it AS-IS, and hot-swap the
+ * plate in place. After the ADR 0022 cutover the dev client posts a finished
+ * StoredPlate (the whole Plate already projected in the browser) inside a
+ * `{ plate, diagnostics? }` envelope — there is NO server-side accumulation/merge
+ * anymore. `diagnostics` is a SIBLING field the server logs and then drops; it
+ * never reaches the stored artifact (ADR 0008).
  *
  * @internal
  */
@@ -536,8 +570,13 @@ declare function handleCapturePost(req: CaptureRequest, res: CaptureResponse, se
  * import itself); an unknown child resolves to its own empty plate, never a
  * build break.
  *
+ * `name` defaults to the plate's own `name`, but the loader passes the
+ * PATH-derived name so a hand-edited StoredPlate whose `name` field drifted from
+ * its filename still serializes and self-references under the canonical name
+ * (`collectRefs` reads `stored.tree`, a RenderNode, unchanged by the cutover).
+ *
  * @internal
  */
-declare function renderPlateModule(merged: MergedPlate): string;
+declare function renderPlateModule(merged: MergedPlate, name?: string): string;
 //#endregion
-export { type LeafKind, type Plate, type PlateFile, type PlateNode, type PlateRule, type ViewCapture, XrayOptions, addCapture, collectRefs, handleCapturePost, handleFixturePost, isValidPlateName, mergeViews, readCoverage, readFixtures, renderPlateModule, xrayVitePlugin };
+export { type LeafKind, type Plate, type PlateNode, type PlateRule, type StoredPlate, type ViewCapture, XrayOptions, collectRefs, handleCapturePost, handleFixturePost, isValidPlateName, readCoverage, readFixtures, renderPlateModule, xrayVitePlugin };