@hueest/xray 0.3.0 → 0.5.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { l as CaptureDiagnostic, o as StoredPlate } from "./plate-BIr62u7l.js";
+import { h as StoredPlate, o as CollectLimits, v as CaptureDiagnostic } from "./serialize-BgdGt34A.js";
 
 //#region src/client.d.ts
 /**
@@ -34,10 +34,13 @@ interface ClientOptions {
    */
   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.
+   * Collect limits (ADR 0022): refuse a capture whose measured tree exceeds any
+   * axis — that big means the Skeleton sits too high in the component tree.
+   * `maxNodes` caps total surviving nodes (default 4096), `maxBreadth` the widest
+   * level (default 512), `maxDepth` the nesting depth (default 32). When `maxNodes`
+   * is omitted it derives as `round(maxBreadth × maxDepth / 4)`.
    */
-  maxNodes?: number;
+  collect?: CollectLimits;
   /**
    * Initial state of the capture toggle: whether the recording session is active
    * at boot. A per-tab override (sessionStorage / `?xray-capture`) wins over it.

package/dist/client.js

@@ -1,4 +1,4 @@
-import { a as serializePlate, d as formatDiagnostic, f as makeDiagnostic, l as runPlatePasses, n as deriveBreakpoints, o as CaptureTooLargeError, p as emit, r as regimeFor, s as captureView, t as serializePlateIR, u as diagnosticsHeader } from "./project-DORoPAo7.js";
+import { a as serializePlate, d as formatDiagnostic, f as makeDiagnostic, l as runPlatePasses, n as deriveBreakpoints, o as CaptureTooLargeError, p as emit, r as regimeFor, s as captureView, t as serializePlateIR, u as diagnosticsHeader } from "./project-BZosujs9.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) {
@@ -607,7 +607,9 @@ 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 DEFAULT_MAX_DEPTH = 32;
+const DEFAULT_MAX_BREADTH = 512;
+const deriveMaxNodes = (maxBreadth, maxDepth) => Math.round(maxBreadth * maxDepth / 4);
 const RESIZE_DEBOUNCE = 300;
 /**
 * The capture roots for a site, the ONE place the auto/manual root models
@@ -630,7 +632,16 @@ 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 baseCollect = options.collect ?? {};
+	const resolveCollect = (site) => {
+		const maxDepth = site?.maxDepth ?? baseCollect.maxDepth ?? DEFAULT_MAX_DEPTH;
+		const maxBreadth = site?.maxBreadth ?? baseCollect.maxBreadth ?? DEFAULT_MAX_BREADTH;
+		return {
+			maxNodes: site?.maxNodes ?? baseCollect.maxNodes ?? deriveMaxNodes(maxBreadth, maxDepth),
+			maxBreadth,
+			maxDepth
+		};
+	};
 	const sites = /* @__PURE__ */ new Set();
 	const matchMediaQueries = /* @__PURE__ */ new Set();
 	let captureGeneration = 0;
@@ -706,14 +717,14 @@ function installXrayClient(options) {
 		let local;
 		try {
 			local = captureView(roots, {
-				maxNodes,
+				collect: resolveCollect(site.collect),
 				walker: site.walker,
 				captureRootIsBoundary: site.mode === "manual"
 			});
 		} catch (error) {
 			if (error instanceof CaptureTooLargeError) {
 				site.tooLarge = true;
-				reportDiagnostics(site.name, [makeDiagnostic(error.code, { detail: `${error.nodeCount} nodes (max ${maxNodes})` })]);
+				reportDiagnostics(site.name, [makeDiagnostic(error.code, { detail: `${error.axis} ${error.size[error.axis]} over the ${error.axis} limit ${error.max} (nodes ${error.size.nodes}, breadth ${error.size.breadth}, depth ${error.size.depth})` })]);
 				return;
 			}
 			console.warn("[xray] capture failed for", site.name, error);
@@ -1041,6 +1052,7 @@ function installXrayClient(options) {
 				delay: opts?.delay ?? defaultDelay,
 				mode: opts?.mode ?? "auto",
 				walker: opts?.walker,
+				collect: opts?.collect,
 				disposed: false,
 				tooLarge: false,
 				dirty: false,

package/dist/core.d.ts

@@ -1,5 +1,4 @@
-import { a as RenderNode, c as emptyPlate, i as PlateNode, n as MergedPlate, r as Plate, s as ViewCapture, t as LeafKind } from "./plate-BIr62u7l.js";
-import { a as XrayCaptureWalker, i as WalkerDecision, n as CaptureTooLargeError, o as defineXrayCaptureWalker, r as CaptureWalkerContext, t as CaptureOptions } from "./serialize-Cs7hUxmK.js";
+import { _ as emptyPlate, a as CollectAxis, c as XrayCaptureWalker, d as MergedPlate, f as Plate, g as ViewCapture, i as CaptureWalkerContext, l as defineXrayCaptureWalker, m as RenderNode, n as CaptureSize, o as CollectLimits, p as PlateNode, r as CaptureTooLargeError, s as WalkerDecision, t as CaptureOptions, u as LeafKind } from "./serialize-BgdGt34A.js";
 
 //#region src/chunk.d.ts
 /**
@@ -46,4 +45,4 @@ declare function captureElement(roots: readonly Element[], options: CaptureOptio
  */
 declare function renderPlateHtml(plate: Plate): string;
 //#endregion
-export { type CaptureOptions, CaptureTooLargeError, type CaptureWalkerContext, type LeafKind, type MergedPlate, type Plate, type PlateNode, type ViewCapture, type WalkerDecision, type XrayCaptureWalker, captureElement, collectRefs, defineXrayCaptureWalker, emptyPlate, renderPlateHtml, serializePlate };
+export { type CaptureOptions, type CaptureSize, CaptureTooLargeError, type CaptureWalkerContext, type CollectAxis, type CollectLimits, type LeafKind, type MergedPlate, type Plate, type PlateNode, type ViewCapture, type WalkerDecision, type XrayCaptureWalker, captureElement, collectRefs, defineXrayCaptureWalker, emptyPlate, renderPlateHtml, serializePlate };

package/dist/core.js

@@ -1,5 +1,5 @@
 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-DORoPAo7.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/core.ts
 /**
@@ -17,6 +17,7 @@ import { t as escapeStyleText } from "./css-escape-N7bOusGW.js";
 */
 function captureElement(roots, options) {
 	const plate = captureView(roots, {
+		collect: options.collect,
 		walker: options.walker,
 		captureRootIsBoundary: options.captureRootIsBoundary
 	});

package/dist/index.d.ts

@@ -323,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;
@@ -425,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

package/dist/index.js

@@ -260,7 +260,7 @@ const DIAGNOSTIC_MESSAGES = {
 	"dropped-tag": "dropped hidden or non-visual elements (display:none, visibility:hidden, opacity:0, script/style/etc.)",
 	"dropped-subset": "dropped bones wholly inside a larger solid bone — the superset renders the same area (overlapping bones collapse to their union)",
 	"dropped-cropped": "dropped bones below the fold (off-screen at capture, in the viewport or a scroll container); real content fills in below without shifting the visible skeleton",
-	"too-large": "capture exceeded the node limit and was skipped; the <Skeleton> likely sits too high in the tree",
+	"too-large": "capture exceeded a Collect limit and was skipped; the <Skeleton> likely sits too high in the tree",
 	"invalid-plate-file": "a committed plate file could not be read (corrupt JSON, wrong shape, or a version mismatch) and was ignored"
 };
 /**
@@ -505,7 +505,7 @@ function xrayVitePlugin(options = {}) {
 	const capture = options.capture ?? false;
 	const delay = options.delay ?? 200;
 	const settleCap = options.settleCap ?? 5e3;
-	const maxNodes = options.maxNodes ?? 4e3;
+	const collect = options.collect;
 	const hud = options.hud ?? false;
 	const recordMode = options.fixtures?.record ?? "manual";
 	const replayMode = options.fixtures?.replay ?? false;
@@ -554,7 +554,7 @@ function xrayVitePlugin(options = {}) {
 		},
 		load(id) {
 			if (id !== RESOLVED_BOOT_ID) return void 0;
-			return bootstrapCode(delay, settleCap, maxNodes, hud, capture, recordMode, replayMode);
+			return bootstrapCode(delay, settleCap, collect, hud, capture, recordMode, replayMode);
 		},
 		configureServer(server) {
 			const dir = () => resolve(root, platesDir);
@@ -591,14 +591,14 @@ function xrayVitePlugin(options = {}) {
 * The injected dev module: boot the client, POST captures back, optionally
 * mount the HUD. The client installs first so the HUD finds the light box store.
 */
-function bootstrapCode(delay, settleCap, maxNodes, hud, capture, recordMode, replayMode) {
+function bootstrapCode(delay, settleCap, collect, hud, capture, recordMode, replayMode) {
 	return [
 		`import { installXrayClient } from '@hueest/xray/internal/client'`,
 		...hud ? [`import { installXrayHud } from '@hueest/xray/internal/hud'`] : [],
 		"installXrayClient({",
 		`  delay: ${delay},`,
 		`  settleCap: ${settleCap},`,
-		`  maxNodes: ${maxNodes},`,
+		`  collect: ${JSON.stringify(collect ?? {})},`,
 		`  capture: ${capture},`,
 		`  record: ${JSON.stringify(recordMode)},`,
 		`  replay: ${JSON.stringify(replayMode)},`,

package/dist/{project-DORoPAo7.js → project-BZosujs9.js}

@@ -837,7 +837,7 @@ const DIAGNOSTIC_MESSAGES = {
 	"dropped-tag": "dropped hidden or non-visual elements (display:none, visibility:hidden, opacity:0, script/style/etc.)",
 	"dropped-subset": "dropped bones wholly inside a larger solid bone — the superset renders the same area (overlapping bones collapse to their union)",
 	"dropped-cropped": "dropped bones below the fold (off-screen at capture, in the viewport or a scroll container); real content fills in below without shifting the visible skeleton",
-	"too-large": "capture exceeded the node limit and was skipped; the <Skeleton> likely sits too high in the tree",
+	"too-large": "capture exceeded a Collect limit and was skipped; the <Skeleton> likely sits too high in the tree",
 	"invalid-plate-file": "a committed plate file could not be read (corrupt JSON, wrong shape, or a version mismatch) and was ignored"
 };
 /**
@@ -9281,20 +9281,23 @@ function resolvePaintAndSalience(el, cs, rect, state) {
 		salience: nodeSalience(el, cs, rect, state.rootArea, state.win, state.styles)
 	};
 }
-/**
-* Thrown when a subtree has more nodes than the capture limit — almost always
-* a `<Skeleton>` sitting too high in the tree. Raised after the cheap walk and
-* before the O(rules × nodes) CSS extraction, so an oversized capture is
-* refused without freezing the main thread on it.
-*/
 var CaptureTooLargeError = class extends Error {
+	/** The full measured size of the surviving tree that tripped the gate. */
+	size;
+	/** Which axis exceeded its cap, and the cap it exceeded. */
+	axis;
+	max;
+	/** Back-compat alias for `size.nodes` (the sole axis before breadth/depth). */
 	nodeCount;
 	/** Folds the oversized-capture warning into the shared diagnostics vocabulary (diagnostics.ts). */
 	code = "too-large";
-	constructor(nodeCount) {
-		super(`xray: capture has ${nodeCount} nodes, over the limit`);
+	constructor(size, axis, max) {
+		super(`xray: capture ${axis} ${size[axis]} over the limit ${max} (nodes ${size.nodes}, breadth ${size.breadth}, depth ${size.depth})`);
 		this.name = "CaptureTooLargeError";
-		this.nodeCount = nodeCount;
+		this.size = size;
+		this.axis = axis;
+		this.max = max;
+		this.nodeCount = size.nodes;
 	}
 };
 /**
@@ -9313,7 +9316,7 @@ var CaptureTooLargeError = class extends Error {
 * (`ids: []`, the inherited parent font `baseRules` derives), lifted onto the
 * bundle for `emit` to fold back in.
 */
-function build(walked, doc, win, styles, diagnostics, maxNodes, walker) {
+function build(walked, doc, win, styles, diagnostics, collect, walker) {
 	const bundle = {
 		root: walked.root,
 		nodes: walked.nodes,
@@ -9321,8 +9324,12 @@ function build(walked, doc, win, styles, diagnostics, maxNodes, walker) {
 	};
 	if (walker?.element) applyWalker(bundle.root, walker);
 	markInk(bundle.root);
-	const surviving = maxNodes !== void 0 ? countSurviving(bundle.root) : 0;
-	if (maxNodes !== void 0 && surviving > maxNodes) throw new CaptureTooLargeError(surviving);
+	if (collect?.maxNodes !== void 0 || collect?.maxBreadth !== void 0 || collect?.maxDepth !== void 0) {
+		const size = measureTree(bundle.root);
+		if (collect?.maxNodes !== void 0 && size.nodes > collect.maxNodes) throw new CaptureTooLargeError(size, "nodes", collect.maxNodes);
+		if (collect?.maxBreadth !== void 0 && size.breadth > collect.maxBreadth) throw new CaptureTooLargeError(size, "breadth", collect.maxBreadth);
+		if (collect?.maxDepth !== void 0 && size.depth > collect.maxDepth) throw new CaptureTooLargeError(size, "depth", collect.maxDepth);
+	}
 	const contextRule = copyRules(walked.nodes, doc, win, styles, diagnostics, walked.extraRules, indexById(bundle.root)).find((rule) => rule.spec === -2 && rule.ids.length === 0);
 	if (contextRule) bundle.contextRule = contextRule;
 	return bundle;
@@ -9380,22 +9387,41 @@ function runPlatePasses(plate) {
 	});
 }
 /**
-* Count the SURVIVING (non-dropped) measured nodes under the synthetic root — the
-* gate's units. Walks via `effectiveKids`, so a `dropped` node (and its non-re-shown
-* subtree) and a `flattened` wrapper are handled exactly as `emit` will lower them;
-* the gate then measures the real post-mark output rather than every measured
-* element (which now includes the hidden subtrees Measure descends). The synthetic
-* root (id 0, el null) is NOT a measured entry, so it is excluded — keeping the
-* count in the same units as the legacy `entries.length` gate.
+* Measure the SURVIVING (non-dropped) tree in one DFS pass: total `nodes`, max
+* nesting `depth`, and `breadth` — the widest level (most nodes at any one depth).
+*
+* Walks via `effectiveKids`, so a `dropped` node (and its non-re-shown subtree) and
+* a `flattened` wrapper are handled exactly as `emit` will lower them — the gate
+* measures the real post-mark output, not every element Measure descended. The
+* synthetic root (id 0, el null) is NOT a measured entry, so it is excluded,
+* keeping `nodes` in the same units as the legacy `entries.length` gate.
+*
+* Widest-level `breadth` is the realistic "how wide does this tree get" signal: a
+* DOM tree's total tracks its widest level (~5×), not `breadth × depth` (which
+* assumes every level is maximally wide — a fractal that never occurs). Feeds the
+* Collect gate.
 */
-function countSurviving(root) {
-	let count = 0;
-	const visit = (node) => {
-		count += 1;
-		for (const kid of effectiveKids(node)) visit(kid);
+function measureTree(root) {
+	let nodes = 0;
+	let depth = 0;
+	const perLevel = [];
+	const visit = (node, d) => {
+		nodes += 1;
+		if (d > depth) depth = d;
+		perLevel[d] = (perLevel[d] ?? 0) + 1;
+		for (const kid of effectiveKids(node)) visit(kid, d + 1);
+	};
+	for (const kid of effectiveKids(root)) visit(kid, 1);
+	let breadth = 0;
+	for (let d = 1; d <= depth; d += 1) {
+		const w = perLevel[d] ?? 0;
+		if (w > breadth) breadth = w;
+	}
+	return {
+		nodes,
+		depth,
+		breadth
 	};
-	for (const kid of effectiveKids(root)) visit(kid);
-	return count;
 }
 /**
 * Measure one View's subtree into an `IRBundle` — the Measure stage (ADR 0022
@@ -9417,7 +9443,7 @@ function measureBundle(roots, options = {}) {
 	const diagnostics = createDiagnostics();
 	const styles = new StyleCache(win);
 	return {
-		bundle: build(walkAll(roots, win, styles, diagnostics, options.captureRootIsBoundary ?? false), doc, win, styles, diagnostics, options.maxNodes, options.walker),
+		bundle: build(walkAll(roots, win, styles, diagnostics, options.captureRootIsBoundary ?? false), doc, win, styles, diagnostics, options.collect, options.walker),
 		win,
 		diagnostics
 	};

package/dist/{react.core-DMIhXHZF.js → react.core-BC02ukac.js}

@@ -268,5 +268,27 @@ function renderChunks(chunks, resolveStitch) {
 		}, i);
 	});
 }
+/**
+* A never-settling promise for the loading suspender below. It never needs to
+* resolve: React retries a suspended boundary when its parent re-renders with new
+* props (here, `loading` flipping to false), so the prop change — not the promise —
+* drives recovery.
+*/
+const SUSPEND_UNTIL_READY = new Promise(() => {});
+/**
+* Suspends while `loading` is true. It exists so a `suspense`-mode `<Skeleton>` can
+* show its plate through the ONE Suspense fallback across BOTH readiness phases — the
+* data-loading phase (this suspender) AND the lazy code-chunk phase (the content
+* itself suspending). Because the plate is the SAME fallback DOM node the whole time,
+* there is no unmount/remount between the two phases and thus no flicker (a top-level
+* `return skeleton` for the data phase followed by a Suspense-fallback skeleton for
+* the chunk phase are different tree positions, so they DID remount). While this
+* throws, the content sibling is never committed, preserving "children never render
+* without data" (ADR 0002).
+*/
+function SuspendWhileLoading({ loading }) {
+	if (loading) throw SUSPEND_UNTIL_READY;
+	return null;
+}
 //#endregion
-export { renderPlate as a, markStitchesLive as i, isRenderProp as n, resolveContent as o, isStitchLive as r, useSkeletonTiming as s, collectStitchNames as t };
+export { markStitchesLive as a, useSkeletonTiming as c, isStitchLive as i, collectStitchNames as n, renderPlate as o, isRenderProp as r, resolveContent as s, SuspendWhileLoading as t };

package/dist/{react.core-BUj8ziwh.d.ts → react.core-NhWc9qan.d.ts}

@@ -1,5 +1,4 @@
-import { r as Plate } from "./plate-BIr62u7l.js";
-import { a as XrayCaptureWalker } from "./serialize-Cs7hUxmK.js";
+import { c as XrayCaptureWalker, f as Plate } from "./serialize-BgdGt34A.js";
 import { ReactNode } from "react";
 
 //#region src/react.core.d.ts
@@ -48,6 +47,17 @@ interface SkeletonBase {
    * `root` variants of the union, so a manual root may carry one too.
    */
   captureWalker?: XrayCaptureWalker;
+  /**
+   * Per-Skeleton Collect limits (ADR 0022, dev only): override the plugin's
+   * `collect` defaults for THIS boundary's capture. Flat primitives — not a nested
+   * object — so they stay referentially stable across renders and never churn the
+   * dev capture effect's deps. `maxNodes` caps total surviving nodes, `maxBreadth`
+   * the widest level, `maxDepth` the nesting depth; an omitted `maxNodes` derives
+   * from the resolved breadth × depth. PRODUCTION ignores them (it never captures).
+   */
+  maxNodes?: number;
+  maxBreadth?: number;
+  maxDepth?: number;
 }
 /**
  * Props accepted by the React `<Skeleton>` component, generic over the optional

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { t as SkeletonProps } from "./react.core-BUj8ziwh.js";
+import { t as SkeletonProps } from "./react.core-NhWc9qan.js";
 
 //#region src/react.d.ts
 /**

package/dist/react.dev.d.ts

@@ -1,4 +1,4 @@
-import { t as SkeletonProps } from "./react.core-BUj8ziwh.js";
+import { t as SkeletonProps } from "./react.core-NhWc9qan.js";
 
 //#region src/react.dev.d.ts
 /**

package/dist/react.dev.js

@@ -1,7 +1,7 @@
 import { n as BOUNDARY_ATTR } from "./plate-BRR6d8Se.js";
-import { a as renderPlate, i as markStitchesLive, n as isRenderProp, o as resolveContent, r as isStitchLive, s as useSkeletonTiming, t as collectStitchNames } from "./react.core-DMIhXHZF.js";
+import { a as markStitchesLive, c as useSkeletonTiming, i as isStitchLive, n as collectStitchNames, o as renderPlate, r as isRenderProp, s as resolveContent, t as SuspendWhileLoading } from "./react.core-BC02ukac.js";
 import { Suspense, useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
-import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react.dev.tsx
 const noSubscribe = () => () => {};
 const alwaysFalse = () => false;
@@ -88,7 +88,7 @@ function useLivePlate(plate) {
 * `react.tsx`.
 */
 function Skeleton(props) {
-	const { plate, loading = false, suspense = false, fallback, delay, children, data, captureWalker } = props;
+	const { plate, loading = false, suspense = false, fallback, delay, children, data, captureWalker, maxNodes, maxBreadth, maxDepth } = props;
 	const manual = props.root === "manual";
 	const lightBoxOn = useLightBox();
 	const livePlate = useLivePlate(plate);
@@ -112,11 +112,14 @@ function Skeleton(props) {
 		manual,
 		data,
 		captureWalker,
+		maxNodes,
+		maxBreadth,
+		maxDepth,
 		children
 	});
-	if (suspense) return /* @__PURE__ */ jsx(Suspense, {
+	if (suspense) return /* @__PURE__ */ jsxs(Suspense, {
 		fallback: skeleton,
-		children: content
+		children: [/* @__PURE__ */ jsx(SuspendWhileLoading, { loading: showSkeleton }), content]
 	});
 	if (showSkeleton) return skeleton;
 	return content;
@@ -128,6 +131,20 @@ function Content(props) {
 	return /* @__PURE__ */ jsx(CaptureBoundary, { ...props });
 }
 /**
+* Assemble the per-site Collect limits (ADR 0022) from the flat `<Skeleton>` props
+* into the nested shape `captured` expects, or `undefined` when none are set (so
+* the client's plugin defaults apply). Called inside the capture effect, keyed on
+* the flat primitives, so it never builds an object during render.
+*/
+function collectLimits(maxNodes, maxBreadth, maxDepth) {
+	if (maxNodes === void 0 && maxBreadth === void 0 && maxDepth === void 0) return void 0;
+	return {
+		maxNodes,
+		maxBreadth,
+		maxDepth
+	};
+}
+/**
 * `root="auto"` (default): the existing `display:contents` boundary wrapper marks
 * the capture seam so a parent capture stops here and references this plate by
 * name rather than re-serializing the content (ADR 0006). A render prop is called
@@ -135,7 +152,7 @@ function Content(props) {
 * element, carries the marker); its result renders inside the wrapper exactly as
 * plain children do.
 */
-function CaptureBoundary({ plate, delay, children, data, captureWalker }) {
+function CaptureBoundary({ plate, delay, children, data, captureWalker, maxNodes, maxBreadth, maxDepth }) {
 	const ref = useRef(null);
 	useEffect(() => {
 		const el = ref.current;
@@ -143,12 +160,16 @@ function CaptureBoundary({ plate, delay, children, data, captureWalker }) {
 		return globalThis.__XRAY__?.captured(plate.name, el, {
 			delay,
 			walker: captureWalker,
-			mode: "auto"
+			mode: "auto",
+			collect: collectLimits(maxNodes, maxBreadth, maxDepth)
 		});
 	}, [
 		plate.name,
 		delay,
-		captureWalker
+		captureWalker,
+		maxNodes,
+		maxBreadth,
+		maxDepth
 	]);
 	const effective = useFixtureData(plate.name, data, isRenderProp(children));
 	return /* @__PURE__ */ jsx("div", {
@@ -171,7 +192,7 @@ function CaptureBoundary({ plate, delay, children, data, captureWalker }) {
 * can produce. A dev-time effect asserts the ref fired and loudly `console.error`s
 * when it did not.
 */
-function ManualBoundary({ plate, delay, children, data, captureWalker }) {
+function ManualBoundary({ plate, delay, children, data, captureWalker, maxNodes, maxBreadth, maxDepth }) {
 	const disposeRef = useRef(void 0);
 	const attachedRef = useRef(false);
 	const ref = useCallback((el) => {
@@ -183,12 +204,16 @@ function ManualBoundary({ plate, delay, children, data, captureWalker }) {
 		disposeRef.current = globalThis.__XRAY__?.captured(plate.name, el, {
 			delay,
 			walker: captureWalker,
-			mode: "manual"
+			mode: "manual",
+			collect: collectLimits(maxNodes, maxBreadth, maxDepth)
 		});
 	}, [
 		plate.name,
 		delay,
-		captureWalker
+		captureWalker,
+		maxNodes,
+		maxBreadth,
+		maxDepth
 	]);
 	useEffect(() => () => disposeRef.current?.(), []);
 	useEffect(() => {

package/dist/react.js

@@ -1,6 +1,6 @@
-import { a as renderPlate, i as markStitchesLive, o as resolveContent, r as isStitchLive, s as useSkeletonTiming, t as collectStitchNames } from "./react.core-DMIhXHZF.js";
+import { a as markStitchesLive, c as useSkeletonTiming, i as isStitchLive, n as collectStitchNames, o as renderPlate, s as resolveContent, t as SuspendWhileLoading } from "./react.core-BC02ukac.js";
 import { Suspense, useEffect, useRef, useState } from "react";
-import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react.tsx
 /**
 * React adapter for rendering committed Plates through `<Skeleton>`.
@@ -44,9 +44,9 @@ function Skeleton(props) {
 		rootRef,
 		instant
 	});
-	if (suspense) return /* @__PURE__ */ jsx(Suspense, {
+	if (suspense) return /* @__PURE__ */ jsxs(Suspense, {
 		fallback: skeleton,
-		children: resolveContent(children, data)
+		children: [/* @__PURE__ */ jsx(SuspendWhileLoading, { loading: showSkeleton }), resolveContent(children, data)]
 	});
 	if (showSkeleton) return skeleton;
 	return /* @__PURE__ */ jsx(Fragment$1, { children: resolveContent(children, data) });

package/dist/{plate-BIr62u7l.d.ts → serialize-BgdGt34A.d.ts}

@@ -323,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;
@@ -360,4 +365,137 @@ declare global {
   var __XRAY__: CaptureHook | undefined;
 }
 //#endregion
-export { RenderNode as a, emptyPlate as c, PlateNode as i, CaptureDiagnostic as l, MergedPlate as n, StoredPlate as o, Plate as r, ViewCapture as s, LeafKind as t };
+//#region src/serialize.d.ts
+/**
+ * Browser-side capture: walk a live rendered subtree into a Plate — one node
+ * tree plus one self-contained, scoped CSS string (ADR 0003). The CSS is
+ * lifted from the author rules that matched each node, rewritten to
+ * plate-local selectors — it carries `@media` for free and keeps layout live
+ * (the M1 bake-off winner; ADR 0005).
+ */
+interface CaptureOptions {
+  /** Plate name; comes from the virtual-module specifier. */
+  name: string;
+  /** Collect limits (ADR 0022): refuse a capture whose measured tree exceeds any axis. */
+  collect?: CollectLimits;
+  /**
+   * Optional programmable capture walker (ADR 0018). The declarative `data-xr-*`
+   * annotations cover the 90%; this is the escape hatch for the 10% a markup
+   * attribute cannot express. Capture-only: it shapes the resulting `PlateNode`
+   * tree but is never persisted into the Plate, and the production adapter never
+   * captures so it ignores this entirely.
+   */
+  walker?: XrayCaptureWalker;
+  /**
+   * Whether the top-level capture roots ARE this plate's own boundary, so the
+   * stitch guard must be SKIPPED for them (ADR 0006/0014, finding #6). True ONLY
+   * for a MANUAL root: there `site.el` is the consumer's own element and its
+   * `data-xr-boundary` marks the boundary of THIS plate, so the root must be
+   * serialized as a real Entry (its box/classes/padding/border) rather than a
+   * stitch-to-itself. Defaults to `false` — the auto path, where the top-level
+   * roots are the wrapper's CHILDREN and any boundary marker on a direct-child
+   * root is a NESTED `<Skeleton>` that MUST stitch (the capture-leak guard).
+   */
+  captureRootIsBoundary?: boolean;
+}
+/**
+ * What a capture walker decides for one element (ADR 0018; ADR 0022 §5). The
+ * `applyWalker` PASS reads the decision and applies it to the measured IR node —
+ * a walker NEVER hand-builds a `PlateNode`, so xray keeps ownership of the Plate
+ * format. `ignore` drops the element + its subtree; `bone` collapses it to one
+ * Bone leaf (inferring the kind when omitted); `keep` defers to the default
+ * classifier (`markInk`).
+ */
+type WalkerDecision = {
+  type: 'ignore';
+} | {
+  type: 'bone';
+  kind?: LeafKind;
+} | {
+  type: 'keep';
+};
+/**
+ * The context handed to a capture walker's `element` hook (ADR 0018). The
+ * helpers are PURE — each returns a `WalkerDecision` the `applyWalker` pass
+ * applies; they do NOT mutate. `el` is the element under consideration.
+ */
+interface CaptureWalkerContext {
+  /** The element currently being classified. */
+  el: Element;
+  /** Drop this element AND its whole subtree (no bone). */
+  ignore(): WalkerDecision;
+  /**
+   * Collapse this element's subtree into ONE Bone leaf. `kind` omitted shares
+   * the default classifier's kind-inference heuristic (`inferLeafKind`; ADR 0018,
+   * Q4 — ONE code path).
+   */
+  bone(opts?: {
+    kind?: LeafKind;
+  }): WalkerDecision;
+  /** Defer to the default classifier (`markInk`) — recurse into the subtree. */
+  keep(): WalkerDecision;
+}
+/**
+ * The programmable capture walker (ADR 0018; ADR 0022 §5). `element` is offered
+ * each non-boundary element TOP-DOWN over the measured IR (the `applyWalker`
+ * pass, NOT the DOM walk) and returns a `WalkerDecision` the pass applies. The
+ * declarative `data-xr-*` annotations cover the 90%; this is the 10% escape
+ * hatch for what a markup attribute cannot express.
+ */
+interface XrayCaptureWalker {
+  /**
+   * Called for every non-boundary element node (a stitch carries no element and
+   * is skipped — ADR 0006 — so a boundary never reaches here). Return one of
+   * `ctx.ignore()`, `ctx.bone()`, or `ctx.keep()`. An `ignore`/`bone` decision
+   * stops the descent (the subtree lowers); `keep` recurses.
+   */
+  element?(ctx: CaptureWalkerContext): WalkerDecision;
+}
+/**
+ * Typed identity wrapper for authoring a capture walker (ADR 0018) — the
+ * `defineConfig` pattern. It returns its argument unchanged at runtime; its only
+ * job is to infer and check the `XrayCaptureWalker` shape at the call site so an
+ * author gets completion and a typo in a hook name is caught.
+ */
+declare function defineXrayCaptureWalker(walker: XrayCaptureWalker): XrayCaptureWalker;
+/**
+ * Thrown when a subtree has more nodes than the capture limit — almost always
+ * a `<Skeleton>` sitting too high in the tree. Raised after the cheap walk and
+ * before the O(rules × nodes) CSS extraction, so an oversized capture is
+ * refused without freezing the main thread on it.
+ */
+/** The measured size of a capture's surviving tree, one number per Collect axis (ADR 0022). */
+type CaptureSize = {
+  nodes: number;
+  breadth: number;
+  depth: number;
+};
+/** Which Collect axis a too-large capture tripped. */
+type CollectAxis = 'nodes' | 'breadth' | 'depth';
+declare class CaptureTooLargeError extends Error {
+  /** The full measured size of the surviving tree that tripped the gate. */
+  readonly size: CaptureSize;
+  /** Which axis exceeded its cap, and the cap it exceeded. */
+  readonly axis: CollectAxis;
+  readonly max: number;
+  /** Back-compat alias for `size.nodes` (the sole axis before breadth/depth). */
+  readonly nodeCount: number;
+  /** Folds the oversized-capture warning into the shared diagnostics vocabulary (diagnostics.ts). */
+  readonly code: "too-large";
+  constructor(size: CaptureSize, axis: CollectAxis, max: number);
+}
+/**
+ * Collect-stage size limits (ADR 0022): refuse to capture a boundary whose
+ * measured tree exceeds any axis. `maxNodes` caps the total surviving-node count;
+ * `maxBreadth` the widest level (most nodes at any one depth); `maxDepth` the
+ * nesting depth. Each axis is enforced only when its cap is defined. The defaults
+ * and the `maxNodes = round(maxBreadth × maxDepth / 4)` derivation live in the
+ * client (where the other defaults live); this core only enforces what it is handed.
+ */
+type CollectLimits = {
+  maxNodes?: number;
+  maxBreadth?: number;
+  maxDepth?: number;
+};
+//#endregion
+export { emptyPlate as _, CollectAxis as a, XrayCaptureWalker as c, MergedPlate as d, Plate as f, ViewCapture as g, StoredPlate as h, CaptureWalkerContext as i, defineXrayCaptureWalker as l, RenderNode as m, CaptureSize as n, CollectLimits as o, PlateNode as p, CaptureTooLargeError as r, WalkerDecision as s, CaptureOptions as t, LeafKind as u, CaptureDiagnostic as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueest/xray",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Auto-captured skeleton loading screens for Vite — capture the structure, ship the plate.",
   "keywords": [
     "loading",

package/dist/serialize-Cs7hUxmK.d.ts

@@ -1,107 +0,0 @@
-import { t as LeafKind } from "./plate-BIr62u7l.js";
-
-//#region src/serialize.d.ts
-/**
- * Browser-side capture: walk a live rendered subtree into a Plate — one node
- * tree plus one self-contained, scoped CSS string (ADR 0003). The CSS is
- * lifted from the author rules that matched each node, rewritten to
- * plate-local selectors — it carries `@media` for free and keeps layout live
- * (the M1 bake-off winner; ADR 0005).
- */
-interface CaptureOptions {
-  /** Plate name; comes from the virtual-module specifier. */
-  name: string;
-  /**
-   * Optional programmable capture walker (ADR 0018). The declarative `data-xr-*`
-   * annotations cover the 90%; this is the escape hatch for the 10% a markup
-   * attribute cannot express. Capture-only: it shapes the resulting `PlateNode`
-   * tree but is never persisted into the Plate, and the production adapter never
-   * captures so it ignores this entirely.
-   */
-  walker?: XrayCaptureWalker;
-  /**
-   * Whether the top-level capture roots ARE this plate's own boundary, so the
-   * stitch guard must be SKIPPED for them (ADR 0006/0014, finding #6). True ONLY
-   * for a MANUAL root: there `site.el` is the consumer's own element and its
-   * `data-xr-boundary` marks the boundary of THIS plate, so the root must be
-   * serialized as a real Entry (its box/classes/padding/border) rather than a
-   * stitch-to-itself. Defaults to `false` — the auto path, where the top-level
-   * roots are the wrapper's CHILDREN and any boundary marker on a direct-child
-   * root is a NESTED `<Skeleton>` that MUST stitch (the capture-leak guard).
-   */
-  captureRootIsBoundary?: boolean;
-}
-/**
- * What a capture walker decides for one element (ADR 0018; ADR 0022 §5). The
- * `applyWalker` PASS reads the decision and applies it to the measured IR node —
- * a walker NEVER hand-builds a `PlateNode`, so xray keeps ownership of the Plate
- * format. `ignore` drops the element + its subtree; `bone` collapses it to one
- * Bone leaf (inferring the kind when omitted); `keep` defers to the default
- * classifier (`markInk`).
- */
-type WalkerDecision = {
-  type: 'ignore';
-} | {
-  type: 'bone';
-  kind?: LeafKind;
-} | {
-  type: 'keep';
-};
-/**
- * The context handed to a capture walker's `element` hook (ADR 0018). The
- * helpers are PURE — each returns a `WalkerDecision` the `applyWalker` pass
- * applies; they do NOT mutate. `el` is the element under consideration.
- */
-interface CaptureWalkerContext {
-  /** The element currently being classified. */
-  el: Element;
-  /** Drop this element AND its whole subtree (no bone). */
-  ignore(): WalkerDecision;
-  /**
-   * Collapse this element's subtree into ONE Bone leaf. `kind` omitted shares
-   * the default classifier's kind-inference heuristic (`inferLeafKind`; ADR 0018,
-   * Q4 — ONE code path).
-   */
-  bone(opts?: {
-    kind?: LeafKind;
-  }): WalkerDecision;
-  /** Defer to the default classifier (`markInk`) — recurse into the subtree. */
-  keep(): WalkerDecision;
-}
-/**
- * The programmable capture walker (ADR 0018; ADR 0022 §5). `element` is offered
- * each non-boundary element TOP-DOWN over the measured IR (the `applyWalker`
- * pass, NOT the DOM walk) and returns a `WalkerDecision` the pass applies. The
- * declarative `data-xr-*` annotations cover the 90%; this is the 10% escape
- * hatch for what a markup attribute cannot express.
- */
-interface XrayCaptureWalker {
-  /**
-   * Called for every non-boundary element node (a stitch carries no element and
-   * is skipped — ADR 0006 — so a boundary never reaches here). Return one of
-   * `ctx.ignore()`, `ctx.bone()`, or `ctx.keep()`. An `ignore`/`bone` decision
-   * stops the descent (the subtree lowers); `keep` recurses.
-   */
-  element?(ctx: CaptureWalkerContext): WalkerDecision;
-}
-/**
- * Typed identity wrapper for authoring a capture walker (ADR 0018) — the
- * `defineConfig` pattern. It returns its argument unchanged at runtime; its only
- * job is to infer and check the `XrayCaptureWalker` shape at the call site so an
- * author gets completion and a typo in a hook name is caught.
- */
-declare function defineXrayCaptureWalker(walker: XrayCaptureWalker): XrayCaptureWalker;
-/**
- * Thrown when a subtree has more nodes than the capture limit — almost always
- * a `<Skeleton>` sitting too high in the tree. Raised after the cheap walk and
- * before the O(rules × nodes) CSS extraction, so an oversized capture is
- * refused without freezing the main thread on it.
- */
-declare class CaptureTooLargeError extends Error {
-  readonly nodeCount: number;
-  /** Folds the oversized-capture warning into the shared diagnostics vocabulary (diagnostics.ts). */
-  readonly code: "too-large";
-  constructor(nodeCount: number);
-}
-//#endregion
-export { XrayCaptureWalker as a, WalkerDecision as i, CaptureTooLargeError as n, defineXrayCaptureWalker as o, CaptureWalkerContext as r, CaptureOptions as t };