@hueest/xray 0.1.0 → 0.3.0

package/dist/react.core-BUj8ziwh.d.ts

@@ -0,0 +1,79 @@
+import { r as Plate } from "./plate-BIr62u7l.js";
+import { a as XrayCaptureWalker } from "./serialize-Cs7hUxmK.js";
+import { ReactNode } from "react";
+
+//#region src/react.core.d.ts
+/**
+ * The additive render-prop children form (ADR 0014). Called only at
+ * `loading=false` (null included — `loading` stays the sole readiness axis, ADR
+ * 0002), it hands back the typed `data` verbatim plus a `ref` for the manual
+ * capture root.
+ *
+ * `ref` is a CALLBACK ref by contract: in `root="manual"` (dev) it imperatively
+ * writes the `data-xr-boundary` marker onto the consumer's own element and
+ * registers it as the capture root, so it must run on the real DOM node. In
+ * `root="auto"` and in production it is a no-op (omitted), and the existing
+ * `display:contents` boundary wrapper does the marking instead.
+ *
+ * It is typed as a callback ref over the base `Element` rather than a `Ref<T>`.
+ * A callback that accepts `Element | null` is, by parameter contravariance,
+ * assignable to a more specific `ref` slot (`<section ref={ref}>` wants
+ * `(el: HTMLElement | null) => void`), so the consumer spreads it onto any host
+ * element without a cast. A `RefObject` would NOT compose this way and is not
+ * offered: writing the boundary attribute needs the imperative callback anyway.
+ */
+type SkeletonRef = (el: Element | null) => void;
+type SkeletonRenderProp<T> = (ctx: {
+  data: T;
+  ref?: SkeletonRef;
+}) => ReactNode;
+/** Fields shared by both `root` variants of `<Skeleton>`. */
+interface SkeletonBase {
+  /** The plate to render while loading, imported from `virtual:xray/plates/<name>`. */
+  plate: Plate;
+  /** Explicit readiness mode: render the Skeleton while true, then render children and capture them in dev when false. */
+  loading?: boolean;
+  /** Suspense mode: make `<Skeleton>` the Suspense boundary and use the Plate as the fallback until children resolve. */
+  suspense?: boolean;
+  /** Shown while loading when the plate has no capture yet. */
+  fallback?: ReactNode;
+  /** Override the plugin's settle delay before this site is captured (dev only). */
+  delay?: number;
+  /**
+   * Programmable capture walker for this Skeleton's subtree (ADR 0018, dev only).
+   * The escape hatch beyond the declarative `data-xr-*` annotations: a closure
+   * that decides, per element, whether to ignore it, collapse it to one Bone, or
+   * defer to the built-in walk. Threaded through the dev adapter into
+   * `captureView`; PRODUCTION ignores it entirely (it never captures). On both
+   * `root` variants of the union, so a manual root may carry one too.
+   */
+  captureWalker?: XrayCaptureWalker;
+}
+/**
+ * Props accepted by the React `<Skeleton>` component, generic over the optional
+ * render-prop `data` payload `T` (ADR 0014). The generic defaults to `undefined`
+ * so existing call sites — `<Skeleton plate loading />`, plain children — keep
+ * working with zero type arguments; passing `data` infers `T` into the render
+ * prop. `data` is a pure pass-through (the consumer owns nullability), never
+ * `NonNullable<T>`.
+ *
+ * The two members discriminate on `root`:
+ * - `root="auto"` (default): the existing `display:contents` boundary wrapper
+ *   marks the capture seam (ADR 0006); children may be plain `ReactNode` OR a
+ *   render prop, and the surfaced `ref` is a no-op.
+ * - `root="manual"`: no wrapper; the consumer owns the capture root element. This
+ *   REQUIRES render-prop children (the only way to hand back the `ref` that
+ *   writes the boundary marker), so plain children + `root="manual"` is a type
+ *   error.
+ */
+type SkeletonProps<T = undefined> = SkeletonBase & ({
+  /** Auto capture root (default): xray inserts a `display:contents` boundary wrapper. */root?: 'auto'; /** Render-prop payload, passed back to the children function verbatim as `T`. */
+  data?: T; /** Real content. In dev, these children are also the capture source once ready. Either plain `ReactNode` or a render prop. */
+  children?: ReactNode | SkeletonRenderProp<T>;
+} | {
+  /** Manual capture root: the consumer's element owns the boundary marker; no wrapper (ADR 0014). */root: 'manual'; /** Render-prop payload, passed back to the children function verbatim as `T`. */
+  data?: T; /** Render prop required: spread the supplied `ref` onto your root element so capture does not leak into the parent plate. */
+  children: SkeletonRenderProp<T>;
+});
+//#endregion
+export { SkeletonProps as t };

package/dist/react.core-DMIhXHZF.js

@@ -0,0 +1,272 @@
+import { a as ROOT_ATTR, o as ROOT_CLASS, s as ROOT_INSTANT_ATTR, t as BASE_CSS } from "./plate-BRR6d8Se.js";
+import { t as escapeStyleText } from "./css-escape-N7bOusGW.js";
+import { Fragment, useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react.core.tsx
+/**
+* The live-stitch registry (ADR 0020): a module-level ref-counted set of stitch
+* names that are CURRENTLY rendered as a stitch inside a still-SHOWING parent
+* skeleton. It exists to kill the "stitch flash": when a parent skeleton resolves
+* and its real content mounts a descendant's OWN standalone `<Skeleton>` for the
+* same plate, that standalone is a NEW outermost skeleton — it would re-pay the
+* full `--xr-skeleton-delay` (ADR 0016) from zero and visually disappear for
+* ~250ms even though the child was continuously visible as a stitch. A standalone
+* skeleton replacing such a live stitch must reveal INSTANTLY (no delay, no fade),
+* matching how the stitch inherited its parent's already-revealed channel.
+*
+* Why a loading-keyed registry and not wall-clock time: the parent marks its
+* direct stitch names live in an effect WHILE it shows its skeleton (an earlier
+* commit). When the parent resolves, React renders the content tree — the child's
+* standalone Skeleton first-renders and reads `isStitchLive(child)` BEFORE the
+* parent's unmark cleanup runs (render happens before that commit's effects), so
+* the read deterministically sees `child` still live. The unmark then clears it.
+* "Recently" is defined by React's render-before-effect ordering, not a timer, so
+* it is race-free AND does not over-apply to independent nested skeletons (a
+* tab-hidden skeleton was never marked live by a currently-showing parent → not
+* live → normal delay). It is portal-correct for free: only genuine stitches
+* (names in a parent plate's stitch set) are ever registered, so a portaled child
+* is never a stitch, never live, and reveals on the normal delay (ADR 0020).
+*
+* This ships to PROD: the flash is a production issue too, and the cost is a Map
+* plus a register effect and a read-once `useState` per `<Skeleton>` — a few
+* bytes, consistent with the prod-hooks relaxation ADR 0016 opened.
+*/
+const liveStitches = /* @__PURE__ */ new Map();
+/**
+* Mark a parent skeleton's direct stitch names live (ref-counted, so concurrent
+* showing parents that stitch the same child stack), returning a disposer that
+* decrements each. The adapter calls this in an effect while `showSkeleton` is
+* true and runs the disposer when it stops showing (resolve/unmount). Several
+* marks of the same name increment the count; the count drops to 0 (entry
+* removed) only when every showing parent has unmarked it (ADR 0020).
+*/
+function markStitchesLive(names) {
+	for (const name of names) liveStitches.set(name, (liveStitches.get(name) ?? 0) + 1);
+	return () => {
+		queueMicrotask(() => {
+			for (const name of names) {
+				const next = (liveStitches.get(name) ?? 0) - 1;
+				if (next <= 0) liveStitches.delete(name);
+				else liveStitches.set(name, next);
+			}
+		});
+	};
+}
+/** True while `name` is rendered as a stitch inside a still-showing parent
+* skeleton — i.e. a standalone `<Skeleton>` for it is a continuation, not a fresh
+* skeleton, and must reveal instantly (ADR 0020). */
+function isStitchLive(name) {
+	return (liveStitches.get(name) ?? 0) > 0;
+}
+/**
+* The direct stitch names a plate's chunks reference (ADR 0020): a `{ r: name }`
+* chunk IS a stitch; a `{ c, k }` chunk is a stitch-bearing element kept real, so
+* recurse its `k`. Walks the SHIPPED `chunks` (the render contract), not
+* `plate.refs` (empty in dev, where the live store resolves stitches) nor
+* `collectRefs` (which walks the build-time RenderNode tree, not the shipped
+* chunks). One level of direct stitch names per Skeleton is enough: each level
+* self-registers as it becomes a real `<Skeleton>` (the cascade), so arbitrary
+* nesting is covered without recursing into child plates here.
+*/
+function collectStitchNames(chunks) {
+	if (!chunks) return [];
+	const names = [];
+	const walk = (cs) => {
+		for (const chunk of cs) {
+			if (typeof chunk === "string") continue;
+			if ("t" in chunk) continue;
+			if ("r" in chunk) names.push(chunk.r);
+			else walk(chunk.k);
+		}
+	};
+	walk(chunks);
+	return names;
+}
+/** Narrow unknown children to the render-prop form. */
+function isRenderProp(children) {
+	return typeof children === "function";
+}
+/**
+* Resolve `<Skeleton>` content at the ready (`loading=false`) path: invoke the
+* render prop with the verbatim `data` and the adapter's `ref` (a no-op in prod
+* and in `root="auto"`, the boundary-writing callback in dev `root="manual"`), or
+* pass plain children through untouched. Centralizes the single `data as T` step:
+* `data` is declared `data?: T`, so it reads back as `T | undefined`, but it is
+* the exact value the consumer passed for the render prop's `T` (ADR 0014 keeps it
+* a pass-through, not `NonNullable<T>`).
+*/
+function resolveContent(children, data, ref) {
+	if (!isRenderProp(children)) return children;
+	return children({
+		data,
+		ref
+	});
+}
+/**
+* The token defaults that mirror the BASE_CSS `var(--xr-skeleton-*, …)` fallbacks
+* (ADR 0016). The hook reads the COMPUTED token off the boundary element, but a
+* consumer who never sets it leaves the computed value empty (the tokens are not
+* declared on `.xr-root`, only referenced with these inline fallbacks). So when a
+* read comes back empty/unparseable the hook falls back to these same numbers,
+* keeping the JS hold and the CSS reveal in lockstep on identical defaults.
+*/
+const DEFAULT_SKELETON_DELAY_MS = 250;
+const DEFAULT_SKELETON_MIN_DURATION_MS = 600;
+/**
+* Parse a CSS time token (`getPropertyValue` returns a trimmed string like
+* `"250ms"`, `"0.6s"`, or `""`) to milliseconds, falling back to `fallback` when
+* empty or unparseable. Supports `ms` and `s`; a bare number is treated as ms.
+*/
+function parseMs(value, fallback) {
+	const text = value.trim();
+	if (text === "") return fallback;
+	const match = /^(-?[\d.]+)(ms|s)?$/.exec(text);
+	if (!match?.[1]) return fallback;
+	const n = Number.parseFloat(match[1]);
+	if (!Number.isFinite(n)) return fallback;
+	return match[2] === "s" ? n * 1e3 : n;
+}
+/**
+* The min-duration hold (ADR 0016), shared by the production (`react.tsx`) and dev
+* (`react.dev.tsx`) adapters so both keep identical timing. Returns whether the
+* skeleton should render RIGHT NOW.
+*
+* The reveal DELAY is pure CSS (BASE_CSS `--xr-reveal`, zero JS); this hook is
+* ONLY the part CSS cannot express: keeping the skeleton mounted past
+* `loading=false` for a minimum visible window. The hook returns `loading ||
+* holding`: the `loading` term is SYNCHRONOUS, so the skeleton shows on the very
+* render `loading` flips true (no content frame at a false→true restart, and no
+* stale-state lag), and `holding` is state used SOLELY for the post-ready hold.
+*
+* While loading, an effect anchors `t0` (loading start) and pre-arms `holding`
+* true, so that pre-armed value carries into the first `loading=false` render with
+* no content flash at the true→false transition. When `loading` flips false the
+* effect reads the COMPUTED `--xr-skeleton-delay` + `--xr-skeleton-min-duration`
+* off `ref` and holds until `t0 + delay + min-duration`. Two cases skip the hold
+* entirely (swap synchronously, no timer): min-duration resolves to 0, or `ref` is
+* null / no `t0` was recorded — meaning no skeleton root was ever shown (e.g. a
+* plate with no capture, just a fallback), so there is nothing to hold and a hold
+* would only keep blank/fallback UI on screen after data is ready.
+*
+* Reading computed custom props off the skeleton root (open Q4): the root carries
+* `display:contents`, but custom-property inheritance and resolution are
+* unaffected by `display` — `getComputedStyle(el).getPropertyValue('--xr-…')`
+* returns the inherited token value on a `display:contents` element just as on any
+* other. The tokens are not declared on `.xr-root` (only referenced with inline
+* fallbacks), so a consumer who never themes them yields an empty read; `parseMs`
+* then applies the same defaults the CSS uses, so the hold matches the reveal.
+*/
+function useSkeletonTiming(loading, ref) {
+	const [holding, setHolding] = useState(loading);
+	const startRef = useRef(null);
+	const timerRef = useRef(void 0);
+	useEffect(() => {
+		const clear = () => {
+			if (timerRef.current !== void 0) {
+				clearTimeout(timerRef.current);
+				timerRef.current = void 0;
+			}
+		};
+		if (loading) {
+			clear();
+			if (startRef.current === null) startRef.current = Date.now();
+			setHolding(true);
+			return clear;
+		}
+		const start = startRef.current;
+		startRef.current = null;
+		const el = ref.current;
+		if (el === null || start === null) {
+			clear();
+			setHolding(false);
+			return clear;
+		}
+		const style = getComputedStyle(el);
+		const delay = parseMs(style.getPropertyValue("--xr-skeleton-delay"), DEFAULT_SKELETON_DELAY_MS);
+		const minDuration = parseMs(style.getPropertyValue("--xr-skeleton-min-duration"), DEFAULT_SKELETON_MIN_DURATION_MS);
+		if (minDuration <= 0) {
+			clear();
+			setHolding(false);
+			return clear;
+		}
+		const remaining = start + delay + minDuration - Date.now();
+		if (remaining <= 0) {
+			clear();
+			setHolding(false);
+			return clear;
+		}
+		clear();
+		timerRef.current = setTimeout(() => {
+			timerRef.current = void 0;
+			setHolding(false);
+		}, remaining);
+		return clear;
+	}, [loading, ref]);
+	return loading || holding;
+}
+/** Layout-neutral wrapper for an HTML island sitting beside React stitch nodes —
+* its children participate in the grandparent's flow, so grid/flex item counts
+* are unchanged. */
+const DISPLAY_CONTENTS = { display: "contents" };
+/**
+* Render a shipped plate's skeleton. `resolveStitch` turns a child plate name
+* into the node that mounts it (static `refs` in prod, a store-subscribed
+* component in dev). `nested` is true for a stitch-mounted child, which skips
+* BASE_CSS — the outermost view already emitted it (ADR 0007). Returns null
+* when the plate has no capture yet; the caller renders the fallback.
+*
+* `instant` (ADR 0020) marks this root a stitch continuation: a standalone
+* `<Skeleton>` replacing a stitch a still-showing parent was just rendering. It
+* lands as `data-xr-instant` on the OUTERMOST root only (`instant && !nested`) so
+* BASE_CSS reveals it without the `--xr-skeleton-delay` fade.
+*/
+function renderPlate(plate, resolveStitch, nested, rootRef, instant) {
+	if (!plate.chunks) return null;
+	const className = plate.rootCls ? `${ROOT_CLASS} ${plate.rootCls}` : ROOT_CLASS;
+	const rootAttrs = {
+		[ROOT_ATTR]: plate.name,
+		className,
+		"aria-hidden": true,
+		"aria-busy": true,
+		...rootRef ? { ref: rootRef } : {},
+		...instant && !nested ? { [ROOT_INSTANT_ATTR]: "" } : {}
+	};
+	const css = nested ? plate.css : `${BASE_CSS}\n${plate.css}`;
+	const chunks = plate.chunks;
+	if (chunks.length === 1 && typeof chunks[0] === "string") {
+		const html = `<style>${escapeStyleText(css)}</style>${chunks[0]}`;
+		return /* @__PURE__ */ jsx("div", {
+			...rootAttrs,
+			dangerouslySetInnerHTML: { __html: html }
+		});
+	}
+	return /* @__PURE__ */ jsxs("div", {
+		...rootAttrs,
+		children: [/* @__PURE__ */ jsx("style", { children: css }), renderChunks(chunks, resolveStitch)]
+	});
+}
+/**
+* Each `string` chunk is injected as a display:contents innerHTML island; each
+* `{ r }` stitch resolves through `resolveStitch`; a `{ c, k }` node stays a
+* real element and recurses (it holds a stitch deeper). No per-node tree walk —
+* the strings are already serialized.
+*/
+function renderChunks(chunks, resolveStitch) {
+	return chunks.map((chunk, i) => {
+		if (typeof chunk === "string") return /* @__PURE__ */ jsx("div", {
+			style: DISPLAY_CONTENTS,
+			dangerouslySetInnerHTML: { __html: chunk }
+		}, i);
+		if ("t" in chunk) return /* @__PURE__ */ jsx("div", {
+			style: DISPLAY_CONTENTS,
+			dangerouslySetInnerHTML: { __html: chunk.t.repeat(chunk.n) }
+		}, i);
+		if ("r" in chunk) return /* @__PURE__ */ jsx(Fragment, { children: resolveStitch(chunk.r) }, i);
+		return /* @__PURE__ */ jsx("div", {
+			className: chunk.c,
+			children: renderChunks(chunk.k, resolveStitch)
+		}, i);
+	});
+}
+//#endregion
+export { renderPlate as a, markStitchesLive as i, isRenderProp as n, resolveContent as o, isStitchLive as r, useSkeletonTiming as s, collectStitchNames as t };

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { t as SkeletonProps } from "./react.core-fgWG_svU.js";
+import { t as SkeletonProps } from "./react.core-BUj8ziwh.js";
 
 //#region src/react.d.ts
 /**
@@ -18,12 +18,6 @@ import { t as SkeletonProps } from "./react.core-fgWG_svU.js";
  * In production this component ships no capture client, HUD, Light Box, store,
  * or subscriptions. Stitches resolve from the statically imported `refs` graph.
  */
-declare function Skeleton({
-  plate,
-  loading,
-  suspense,
-  fallback,
-  children
-}: SkeletonProps): import("react").JSX.Element;
+declare function Skeleton<T = undefined>(props: SkeletonProps<T>): import("react").JSX.Element;
 //#endregion
 export { Skeleton, type SkeletonProps };

package/dist/react.dev.d.ts

@@ -1,4 +1,4 @@
-import { t as SkeletonProps } from "./react.core-fgWG_svU.js";
+import { t as SkeletonProps } from "./react.core-BUj8ziwh.js";
 
 //#region src/react.dev.d.ts
 /**
@@ -7,13 +7,6 @@ import { t as SkeletonProps } from "./react.core-fgWG_svU.js";
  * `@hueest/xray/react` to this module in `serve`; production gets the hook-free
  * `react.tsx`.
  */
-declare function Skeleton({
-  plate,
-  loading,
-  suspense,
-  fallback,
-  delay,
-  children
-}: SkeletonProps): import("react").JSX.Element;
+declare function Skeleton<T = undefined>(props: SkeletonProps<T>): import("react").JSX.Element;
 //#endregion
 export { Skeleton, type SkeletonProps };

package/dist/react.dev.js

@@ -1,6 +1,6 @@
-import { n as BOUNDARY_ATTR } from "./plate-BuzRMPx4.js";
-import { t as renderPlate } from "./react.core-CqnDjfAJ.js";
-import { Suspense, useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+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 { Suspense, useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 //#region src/react.dev.tsx
 const noSubscribe = () => () => {};
@@ -10,6 +10,67 @@ function useLightBox() {
 	const lightbox = globalThis.__XRAY__?.lightbox;
 	return useSyncExternalStore(lightbox?.subscribe ?? noSubscribe, lightbox?.get ?? alwaysFalse, alwaysFalse);
 }
+/** True while the HUD/console "Replay" toggle is on (ADR 0015). */
+function useReplayOn() {
+	const replay = globalThis.__XRAY__?.replay;
+	return useSyncExternalStore(replay?.subscribe ?? noSubscribe, replay?.get ?? alwaysFalse, alwaysFalse);
+}
+/**
+* The Fixtures (ADR 0015) seam, applied at the ready (`loading=false`) path right
+* before `resolveContent`. It is the ONE place Record reads `data` and Replay
+* substitutes it — the render-prop `data` argument is in scope here (open Q1,
+* confirmed).
+*
+* Replay: when the toggle is on and a Fixture exists, the recorded `data` is
+* substituted for the live `data` according to `replayMode` — `'prefer'` always
+* uses the Fixture; `'missing-only'` uses it only when live `data` is NULLISH
+* (`missing ≡ nullish`, so an empty array/object is present and stays
+* capturable). The substituted value is returned synchronously so it feeds
+* `resolveContent` for THIS render; the capture-all sweep only re-renders at each
+* width and reads the SAME Fixture from the store (which the sweep never changes
+* per width), so every View is captured from one width-independent Fixture with
+* no new capture trigger (open Q2, confirmed — capture follows whatever renders,
+* ADR 0002).
+*
+* Record: the live `data` is registered (in an effect, so render stays pure) so
+* the HUD button and the auto modes always have the current input in scope. The
+* auto modes (`'first-ready'`, `'always'`) fire from the same effect; `'manual'`
+* (the default) records nothing automatically. We register and auto-record the
+* LIVE `data`, never the replayed value, so Replay and Record never feed each
+* other.
+*
+* Only the render-prop children form is the `data` seam (ADR 0014/0015), so
+* Fixtures apply to it alone: `renderProp` gates participation. A plain-children
+* Skeleton has no `data` input, so it must NOT register, auto-record, or replay —
+* the hook is a pass-through for it, which keeps a never-registered plain name out
+* of `recordAll` and lets `record(name)` throw loudly (no render-prop data) as the
+* store contract documents. A render-prop Skeleton passed `data={undefined}` is
+* still a render prop and participates exactly as any other.
+*/
+function useFixtureData(name, data, renderProp) {
+	const replayOn = useReplayOn();
+	const fixturesStore = globalThis.__XRAY__?.fixtures;
+	const recordedFixture = useSyncExternalStore(useCallback((onChange) => fixturesStore?.subscribe(onChange) ?? noSubscribe(), [fixturesStore]), () => fixturesStore?.read(name), () => void 0);
+	useEffect(() => {
+		if (!renderProp) return void 0;
+		const fx = globalThis.__XRAY__?.fixtures;
+		if (!fx) return void 0;
+		const dispose = fx.register(name, data);
+		const mode = globalThis.__XRAY__?.recordMode ?? "manual";
+		if (mode === "always" || mode === "first-ready" && !fx.has(name)) fx.record(name).catch((error) => {
+			console.error(`[xray] fixture record failed for "${name}":`, error);
+		});
+		return dispose;
+	}, [
+		name,
+		data,
+		renderProp
+	]);
+	if (!renderProp) return data;
+	if (!replayOn || !recordedFixture) return data;
+	if ((globalThis.__XRAY__?.replayMode ?? "prefer") === "missing-only" && data != null) return data;
+	return recordedFixture.data;
+}
 /**
 * The plate to render: the freshest capture from the client store (hot-swapped
 * in place, no remount) when present, else the imported prop.
@@ -26,50 +87,119 @@ function useLivePlate(plate) {
 * `@hueest/xray/react` to this module in `serve`; production gets the hook-free
 * `react.tsx`.
 */
-function Skeleton({ plate, loading = false, suspense = false, fallback, delay, children }) {
+function Skeleton(props) {
+	const { plate, loading = false, suspense = false, fallback, delay, children, data, captureWalker } = props;
+	const manual = props.root === "manual";
 	const lightBoxOn = useLightBox();
+	const livePlate = useLivePlate(plate);
+	const rootRef = useRef(null);
+	const showSkeleton = useSkeletonTiming(loading, rootRef);
+	const [instant] = useState(() => isStitchLive(plate.name));
+	useEffect(() => {
+		if (!showSkeleton) return void 0;
+		return markStitchesLive(collectStitchNames(livePlate.chunks));
+	}, [showSkeleton, livePlate.chunks]);
 	const skeleton = /* @__PURE__ */ jsx(PlateView, {
-		plate: useLivePlate(plate),
-		fallback
+		plate: livePlate,
+		fallback,
+		rootRef,
+		instant
 	});
 	if (lightBoxOn) return skeleton;
-	if (suspense) return /* @__PURE__ */ jsx(Suspense, {
-		fallback: skeleton,
-		children: /* @__PURE__ */ jsx(Content, {
-			plate,
-			delay,
-			children
-		})
-	});
-	if (loading) return skeleton;
-	return /* @__PURE__ */ jsx(Content, {
+	const content = /* @__PURE__ */ jsx(Content, {
 		plate,
 		delay,
+		manual,
+		data,
+		captureWalker,
 		children
 	});
+	if (suspense) return /* @__PURE__ */ jsx(Suspense, {
+		fallback: skeleton,
+		children: content
+	});
+	if (showSkeleton) return skeleton;
+	return content;
 }
 function Content(props) {
-	if (globalThis.__XRAY__ === void 0) return /* @__PURE__ */ jsx(Fragment$1, { children: props.children });
+	const { children, data } = props;
+	if (globalThis.__XRAY__ === void 0) return /* @__PURE__ */ jsx(Fragment$1, { children: resolveContent(children, data) });
+	if (props.manual) return /* @__PURE__ */ jsx(ManualBoundary, { ...props });
 	return /* @__PURE__ */ jsx(CaptureBoundary, { ...props });
 }
-function CaptureBoundary({ plate, delay, children }) {
+/**
+* `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
+* with the verbatim `data` and a no-op `ref` (the wrapper, not the consumer's
+* element, carries the marker); its result renders inside the wrapper exactly as
+* plain children do.
+*/
+function CaptureBoundary({ plate, delay, children, data, captureWalker }) {
 	const ref = useRef(null);
 	useEffect(() => {
 		const el = ref.current;
 		if (!el) return void 0;
-		return globalThis.__XRAY__?.captured(plate.name, el, { delay });
-	}, [plate.name, delay]);
+		return globalThis.__XRAY__?.captured(plate.name, el, {
+			delay,
+			walker: captureWalker,
+			mode: "auto"
+		});
+	}, [
+		plate.name,
+		delay,
+		captureWalker
+	]);
+	const effective = useFixtureData(plate.name, data, isRenderProp(children));
 	return /* @__PURE__ */ jsx("div", {
 		[BOUNDARY_ATTR]: plate.name,
 		style: { display: "contents" },
 		ref,
-		children
+		children: resolveContent(children, effective)
 	});
 }
+/**
+* `root="manual"` (ADR 0014): no wrapper. The render prop is handed a CALLBACK
+* ref that, when spread onto the consumer's root element, writes the existing
+* `data-xr-boundary` marker onto it and registers it as the capture root, so a
+* parent capture reads the identical marker (`serialize.ts` does
+* `BOUNDARY_ATTR ?? ROOT_ATTR`) and cannot tell a manual root from an auto one.
+*
+* If the consumer forgets to spread the ref, the marker never lands and the
+* parent capture descends into and silently swallows this subtree's DOM: the
+* exact stitch-isolation breakage ADR 0006 prevents, and the worst failure xray
+* 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 }) {
+	const disposeRef = useRef(void 0);
+	const attachedRef = useRef(false);
+	const ref = useCallback((el) => {
+		disposeRef.current?.();
+		disposeRef.current = void 0;
+		if (!el) return;
+		el.setAttribute(BOUNDARY_ATTR, plate.name);
+		attachedRef.current = true;
+		disposeRef.current = globalThis.__XRAY__?.captured(plate.name, el, {
+			delay,
+			walker: captureWalker,
+			mode: "manual"
+		});
+	}, [
+		plate.name,
+		delay,
+		captureWalker
+	]);
+	useEffect(() => () => disposeRef.current?.(), []);
+	useEffect(() => {
+		if (!attachedRef.current) console.error(`[xray] <Skeleton root="manual" plate="${plate.name}"> never received its \`ref\`: spread it onto your root element, or capture leaks into the parent plate (ADR 0006).`);
+	}, [plate.name]);
+	return /* @__PURE__ */ jsx(Fragment$1, { children: resolveContent(children, useFixtureData(plate.name, data, isRenderProp(children)), ref) });
+}
 /** Render a plate's skeleton, seeding the live store from its resolved refs so a
 * stitch resolves before its child is re-captured and survives a parent
 * hot-swap (which pushes a refs-less plate). Never overwrites a live capture. */
-function PlateView({ plate, fallback, nested = false }) {
+function PlateView({ plate, fallback, nested = false, rootRef, instant }) {
 	useEffect(() => {
 		const store = globalThis.__XRAY__?.plates;
 		if (!store || !plate.refs) return;
@@ -79,7 +209,7 @@ function PlateView({ plate, fallback, nested = false }) {
 	return renderPlate(plate, (name) => /* @__PURE__ */ jsx(RefNode, {
 		name,
 		staticRefs: plate.refs
-	}), nested);
+	}), nested, rootRef, instant);
 }
 /**
 * A stitch in dev: resolve the child plate from the live store (so re-capturing

package/dist/react.js

@@ -1,5 +1,5 @@
-import { t as renderPlate } from "./react.core-CqnDjfAJ.js";
-import { Suspense } from "react";
+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 { Suspense, useEffect, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 //#region src/react.tsx
 /**
@@ -29,30 +29,42 @@ import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 * In production this component ships no capture client, HUD, Light Box, store,
 * or subscriptions. Stitches resolve from the statically imported `refs` graph.
 */
-function Skeleton({ plate, loading = false, suspense = false, fallback, children }) {
+function Skeleton(props) {
+	const { plate, loading = false, suspense = false, fallback, children, data } = props;
+	const rootRef = useRef(null);
+	const showSkeleton = useSkeletonTiming(loading, rootRef);
+	const [instant] = useState(() => isStitchLive(plate.name));
+	useEffect(() => {
+		if (!showSkeleton) return void 0;
+		return markStitchesLive(collectStitchNames(plate.chunks));
+	}, [showSkeleton, plate.chunks]);
 	const skeleton = /* @__PURE__ */ jsx(PlateView, {
 		plate,
-		fallback
+		fallback,
+		rootRef,
+		instant
 	});
 	if (suspense) return /* @__PURE__ */ jsx(Suspense, {
 		fallback: skeleton,
-		children
+		children: resolveContent(children, data)
 	});
-	if (loading) return skeleton;
-	return /* @__PURE__ */ jsx(Fragment$1, { children });
+	if (showSkeleton) return skeleton;
+	return /* @__PURE__ */ jsx(Fragment$1, { children: resolveContent(children, data) });
 }
 /** Render a plate's skeleton, mounting each stitch's child plate from `refs`. */
-function PlateView({ plate, fallback }) {
+function PlateView({ plate, fallback, rootRef, instant }) {
 	if (!plate.chunks) return /* @__PURE__ */ jsx(Fragment$1, { children: fallback ?? null });
-	return renderStatic(plate, false);
+	return renderStatic(plate, false, rootRef, instant);
 }
 /** Resolve stitches statically through the import graph (ADR 0006) — pure
-* recursion, no store, no subscription. An unknown child renders nothing. */
-function renderStatic(plate, nested) {
+* recursion, no store, no subscription. An unknown child renders nothing. The
+* `instant` flag (ADR 0020) rides the outermost root only; nested stitches pass
+* none, so `renderPlate` never marks a nested root. */
+function renderStatic(plate, nested, rootRef, instant) {
 	return renderPlate(plate, (name) => {
 		const child = plate.refs?.[name];
 		return child ? renderStatic(child, true) : null;
-	}, nested);
+	}, nested, rootRef, instant);
 }
 //#endregion
 export { Skeleton };