@hueest/xray 0.6.0 → 0.7.0

package/dist/{plate-BwJUgHDc.js → plate-CXIh5_OB.js}

@@ -1,18 +1,18 @@
 /** Marks the rendered skeleton root; carries the plate name. Also a dev capture marker. */
 const ROOT_ATTR = "data-xr-root";
 /**
-* Marks an OUTERMOST skeleton root that is a stitch continuation (ADR 0020): a
-* standalone `<Skeleton>` replacing a stitch a still-showing parent skeleton was
-* just rendering. BASE_CSS reveals such a root instantly (no `--xr-skeleton-delay`,
-* no fade) so the bones do not flash away and back. Never present on a nested
-* stitch (which inherits the parent's reveal and has no `@starting-style` of its
-* own) nor on an ordinary top-level skeleton (which keeps the normal delay).
+* Marks an OUTERMOST skeleton root that is a stitch continuation (ADR 0020): a standalone
+* `<Skeleton>` replacing a stitch a still-showing parent skeleton was just rendering. BASE_CSS
+* reveals such a root instantly (no `--xr-skeleton-delay`, no fade) so the bones do not flash away
+* and back. Never present on a nested stitch (which inherits the parent's reveal and has no
+* `@starting-style` of its own) nor on an ordinary top-level skeleton (which keeps the normal
+* delay).
 */
 const ROOT_INSTANT_ATTR = "data-xr-instant";
 /**
-* Marks a `<Content>` capture boundary in dev; carries the plate name. A parent
-* capture treats it as a stitch — it references the child plate by name instead of
-* re-serializing the child's subtree (ADR 0006).
+* Marks a `<Content>` capture boundary in dev; carries the plate name. A parent capture treats it
+* as a stitch — it references the child plate by name instead of re-serializing the child's subtree
+* (ADR 0006).
 */
 const BOUNDARY_ATTR = "data-xr-boundary";
 const SPEC_LEAF = 9e6;
@@ -23,46 +23,37 @@ const ROOT_CLASS = "xr-root";
 const NODE_CLASS = "xr-node";
 const LEAF_CLASS = "xr-leaf";
 /**
-* Renderer-owned base styles, emitted once by the outermost view (ADR 0007),
-* before a plate's node rules so a node's captured class wins by source order.
-* Everything visual is driven by inheritable custom properties, so consumers
-* theme by setting `--xr-*` in `:root` or on any ancestor — and per-plate via
-* `[data-xr-root="name"]` (the root carries its plate name). See ADR 0011 and
-* docs/architecture.md. Class-based and unlayered — `@layer` was rejected
-* (unlayered app CSS would beat layered skeleton rules, and it inverts
-* `!important`).
+* Renderer-owned base styles, emitted once by the outermost view (ADR 0007), before a plate's node
+* rules so a node's captured class wins by source order. Everything visual is driven by inheritable
+* custom properties, so consumers theme by setting `--xr-*` in `:root` or on any ancestor — and
+* per-plate via `[data-xr-root="name"]` (the root carries its plate name). See ADR 0011 and
+* docs/architecture.md. Class-based and unlayered — `@layer` was rejected (unlayered app CSS would
+* beat layered skeleton rules, and it inverts `!important`).
 *
-* Progressive enhancement (ADR 0011): the plain bone fill + opacity pulse use
-* only universally-supported CSS and are the floor. `light-dark()` is guarded
-* by `@supports` because an unsupported VALUE drops the whole declaration (an
-* invisible bone), and it is not Baseline-widely-available until 2026-11-13 —
-* drop the guard then. Features that merely no-op when absent (`@property`,
-* `prefers-contrast`, relative-color-as-fallback) carry no hard guard.
+* Progressive enhancement (ADR 0011): the plain bone fill + opacity pulse use only
+* universally-supported CSS and are the floor. `light-dark()` is guarded by `@supports` because an
+* unsupported VALUE drops the whole declaration (an invisible bone), and it is not
+* Baseline-widely-available until 2026-11-13 — drop the guard then. Features that merely no-op when
+* absent (`@property`, `prefers-contrast`, relative-color-as-fallback) carry no hard guard.
 *
-* Tokens (ADR 0017 taxonomy). The `--xr-bone-*` family styles an individual
-* Bone: `--xr-bone-color` (fill), `--xr-bone-highlight-color` (sheen),
-* `--xr-bone-border-radius` (+ `--xr-bone-text-border-radius` /
-* `--xr-bone-text-block-border-radius` / `--xr-bone-media-border-radius`),
-* `--xr-bone-animation-duration`, the pulse
-* range `--xr-bone-pulse-opacity-min`/`--xr-bone-pulse-opacity-max`,
-* `--xr-bone-animation` (mode: `xr-pulse` | `none` | a custom keyframe), and
-* `--xr-bone-fill` (override the leaf paint, e.g. a sheen gradient built from the
-* two bone color tokens). The `--xr-skeleton-*` family governs whole-skeleton
-* display timing (ADR 0016): `--xr-skeleton-delay` (grace before the skeleton
-* becomes visible), `--xr-skeleton-min-duration` (minimum visible time once
-* shown; read by the `useSkeletonTiming` hook, not used in CSS), and
-* `--xr-skeleton-transition-duration` (the reveal/swap fade). The private
-* channels `--xr-o` (pulse) and `--xr-reveal` (reveal) stay undocumented
-* `@property` plumbing, not a theming surface.
+* Tokens (ADR 0017 taxonomy). The `--xr-bone-*` family styles an individual Bone: `--xr-bone-color`
+* (fill), `--xr-bone-highlight-color` (sheen), `--xr-bone-border-radius` (+
+* `--xr-bone-text-line-border-radius` / `--xr-bone-text-block-border-radius` /
+* `--xr-bone-media-border-radius`), `--xr-bone-animation-duration`, the pulse range
+* `--xr-bone-pulse-opacity-min`/`--xr-bone-pulse-opacity-max`, `--xr-bone-animation` (mode:
+* `xr-pulse` | `none` | a custom keyframe), and `--xr-bone-fill` (override the leaf paint, e.g. a
+* sheen gradient built from the two bone color tokens). The `--xr-skeleton-*` family governs
+* whole-skeleton display timing (ADR 0016): `--xr-skeleton-delay` (grace before the skeleton
+* becomes visible), `--xr-skeleton-min-duration` (minimum visible time once shown; read by the
+* `useSkeletonTiming` hook, not used in CSS), and `--xr-skeleton-transition-duration` (the
+* reveal/swap fade). The private channels `--xr-o` (pulse) and `--xr-reveal` (reveal) stay
+* undocumented `@property` plumbing, not a theming surface.
 *
-* Declared as a PLAIN template literal — no `.trim()` (or any other call) on
-* the initializer. A method call is not provably pure to a conservative
-* tree-shaker (rolldown/Rollup), and it single-handedly pinned this ~5 KB
-* string into every consumer chunk importing the React adapter even after the
-* adapter stopped referencing it (plan 005 round 2 finding). The template
-* therefore starts immediately after the backtick (the old leading newline
-* `.trim()` used to strip simply isn't there), keeping the string value
-* byte-identical to the trimmed original.
+* Declared as a PLAIN template literal — no `.trim()` (or any other call) on the initializer. A
+* method call is not provably pure to a conservative tree-shaker (rolldown/Rollup) and would pin
+* this ~5 KB string into every consumer chunk that imports the React adapter, referenced or not
+* (ADR 0026). The template starts immediately after the backtick, so there is no leading newline to
+* strip.
 */
 const BASE_CSS = `/* One timeline per skeleton, not per leaf: the root animates one inherited
    opacity property and every leaf reads it. Hundreds of independent infinite
@@ -95,10 +86,14 @@ const BASE_CSS = `/* One timeline per skeleton, not per leaf: the root animates
 /* Per-kind defaults: a single text LINE reads as a rounded bar; a multi-line
    text BLOCK as a soft rect (a tall pill misreads as a button); media carries
    the author radius, defaulting to the same soft rect. Re-theme any kind via
-   [data-xr-root] .${LEAF_CLASS}-text { ... }. */
-.${LEAF_CLASS}-text { border-radius: var(--xr-bone-text-border-radius, 999px) }
+   [data-xr-root] .${LEAF_CLASS}-text-line { ... }. */
+.${LEAF_CLASS}-text-line { border-radius: var(--xr-bone-text-line-border-radius, 999px) }
 .${LEAF_CLASS}-text-block { border-radius: var(--xr-bone-text-block-border-radius, var(--xr-bone-border-radius, 4px)) }
 .${LEAF_CLASS}-media { border-radius: var(--xr-bone-media-border-radius, var(--xr-bone-border-radius, 4px)) }
+/* A hidden bone holds its measured box in the flow but paints nothing: the
+   space-preserving complement to data-xr-ignore. visibility (not display) so
+   the captured size rules still lay the box out. */
+.${LEAF_CLASS}-hidden { visibility: hidden }
 @keyframes xr-pulse {
   from { --xr-o: var(--xr-bone-pulse-opacity-max, 1) }
   to { --xr-o: var(--xr-bone-pulse-opacity-min, 0.5) }
@@ -152,16 +147,14 @@ const BASE_CSS = `/* One timeline per skeleton, not per leaf: the root animates
   .${ROOT_CLASS} { --xr-bone-highlight-color: oklch(from var(--xr-bone-color, #e4e4e7) calc(l + 0.08) c h) }
 }`;
 /**
-* Compose a plate's scoped css with the renderer-owned BASE_CSS, base first so
-* a plate rule beats a base rule at equal specificity by source order — the
-* standard composition for rendering a skeleton outside the Vite plugin
-* (where `virtual:xray/base.css` + `virtual:xray/plates/<name>.css` do this
-* through the CSS pipeline instead). Since the two-artifact cutover (plan 005
-* round 2) css is the CALLER's input: `renderPlateHtml(plate,
-* composeCss(css))`, or `<Skeleton plate={plate} css={composeCss(css)}>` for
-* a runtime-captured plate. Rendering a NESTED stitch under an
-* already-composed parent needs the raw css only (base is already on the
-* page) — pass the string uncomposed there.
+* Compose a plate's scoped css with the renderer-owned BASE_CSS, base first so a plate rule beats a
+* base rule at equal specificity by source order — the standard composition for rendering a
+* skeleton outside the Vite plugin (where `virtual:xray/base.css` +
+* `virtual:xray/plates/<name>.css` do this through the CSS pipeline instead). css is the CALLER's
+* input (ADR 0026): `renderPlateHtml(plate, composeCss(css))`, or `<Skeleton plate={plate}
+* css={composeCss(css)}>` for a runtime-captured plate. Rendering a NESTED stitch under an
+* already-composed parent needs the raw css only (base is already on the page) — pass the string
+* uncomposed there.
 */
 function composeCss(css) {
 	return `${BASE_CSS}\n${css}`;
@@ -169,7 +162,7 @@ function composeCss(css) {
 /** The (unserialized) plate an import resolves to before anything has been captured. */
 function emptyPlate(name) {
 	return {
-		v: 2,
+		v: 1,
 		name,
 		tree: null,
 		css: ""

package/dist/react.core-BS2yvqeh.js

@@ -0,0 +1,301 @@
+import { a as ROOT_ATTR, o as ROOT_CLASS, s as ROOT_INSTANT_ATTR } from "./plate-CXIh5_OB.js";
+import { t as escapeStyleText } from "./css-escape-DJ-BsrNm.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`. Three cases skip the hold entirely (swap synchronously, no timer): min-duration
+* resolves to 0; `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; or `loading` resolved inside the grace
+* delay — the skeleton is still in its invisible window (BASE_CSS reveals at `t0 + delay`), so no
+* visible-time floor is owed and the fast load never sees a skeleton (ADR 0016).
+*
+* Reading computed custom props off the skeleton root: 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;
+		}
+		if (Date.now() < start + delay) {
+			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. Returns null when the plate has no capture yet; the caller renders the
+* fallback.
+*
+* Two-artifact contract (ADR 0026): a `Plate` is tree-only, and this renderer neither reads css off
+* it nor references `BASE_CSS` (keeping the constant out of consumer bundles — Vite-path styling is
+* entirely the CSS pipeline's job: `virtual:xray/base.css` + `virtual:xray/plates/<name>.css`).
+* `css` is the one optional styling input: the consumer-composed inline css for a runtime-captured
+* (`@hueest/xray/core`) plate, threaded from the `<Skeleton css>` prop and injected as a `<style>`
+* on this root. It rides the OUTERMOST root only — the adapters never pass it for a nested stitch
+* (the page-level/base styles are already in scope there, ADR 0007's once-per-page rule by
+* construction).
+*
+* `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, css) {
+	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 chunks = plate.chunks;
+	if (chunks.length === 1 && typeof chunks[0] === "string") {
+		if (css === void 0) return /* @__PURE__ */ jsx("div", {
+			...rootAttrs,
+			dangerouslySetInnerHTML: { __html: chunks[0] }
+		});
+		const html = `<style>${escapeStyleText(css)}</style>${chunks[0]}`;
+		return /* @__PURE__ */ jsx("div", {
+			...rootAttrs,
+			dangerouslySetInnerHTML: { __html: html }
+		});
+	}
+	return /* @__PURE__ */ jsxs("div", {
+		...rootAttrs,
+		children: [css === void 0 ? null : /* @__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);
+	});
+}
+/**
+* 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 would sit at different tree positions and 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 { 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-BkJoCgWJ.d.ts

@@ -0,0 +1,115 @@
+import { c as XrayCaptureWalker, p as Plate } from "./measure-CUQxB-Ic.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;
+  /**
+   * Inline skeleton css for a plate whose styling does NOT flow through the Vite plugin's CSS
+   * pipeline — i.e. a runtime-captured plate from `@hueest/xray/core`'s `captureElement` (ADR 0003:
+   * the no-Vite path). Pass the composed string (`composeCss(css)` for the standard BASE_CSS +
+   * plate rules); it is injected as a `<style>` on the skeleton root. OMIT for plugin-imported
+   * plates — their css (base included) is already on the page via `virtual:xray/base.css` +
+   * `virtual:xray/plates/<name>.css`, and an inline copy would double-apply and re-fight the
+   * cascade. Applies to THIS plate's root only; stitched child plates resolve through refs/the dev
+   * store and carry no inline css.
+   */
+  css?: string;
+  /**
+   * 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-*` hints: 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;
+  /**
+   * 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 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.d.ts

@@ -1,22 +1,20 @@
-import { t as SkeletonProps } from "./react.core-sJfIcaXX.js";
-
+import { t as SkeletonProps } from "./react.core-BkJoCgWJ.js";
 //#region src/react.d.ts
 /**
  * Render a committed Plate while content is loading.
  *
- * Use `loading` when your data source exposes an explicit pending state. Use
- * `suspense` when the child suspends; in that mode `<Skeleton>` is the Suspense
- * boundary and the Plate is the fallback. You can also render a bare Skeleton
- * with no children when another framework or router owns the loading boundary.
+ * Use `loading` when your data source exposes an explicit pending state. Use `suspense` when the
+ * child suspends; in that mode `<Skeleton>` is the Suspense boundary and the Plate is the fallback.
+ * You can also render a bare Skeleton with no children when another framework or router owns the
+ * loading boundary.
  *
- * In dev, the plugin aliases this component to the dev adapter. When children
- * are ready, that adapter marks the capture boundary, waits for the subtree to
- * settle, and sends the rendered DOM to the xray client. Nested `<Skeleton>`
- * boundaries become Stitches so a parent Plate records a child Plate reference
- * instead of serializing the child subtree again.
+ * In dev, the plugin aliases this component to the dev adapter. When children are ready, that
+ * adapter marks the capture boundary, waits for the subtree to settle, and sends the rendered DOM
+ * to the xray client. Nested `<Skeleton>` boundaries become Stitches so a parent Plate records a
+ * child Plate reference instead of serializing the child subtree again.
  *
- * In production this component ships no capture client, HUD, Light Box, store,
- * or subscriptions. Stitches resolve from the statically imported `refs` graph.
+ * 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<T = undefined>(props: SkeletonProps<T>): import("react").JSX.Element;
 //#endregion

package/dist/react.dev.d.ts

@@ -1,11 +1,9 @@
-import { t as SkeletonProps } from "./react.core-sJfIcaXX.js";
-
+import { t as SkeletonProps } from "./react.core-BkJoCgWJ.js";
 //#region src/react.dev.d.ts
 /**
- * Dev `<Skeleton>`: production behavior plus the Light Box override, the
- * live-store hot-swap, and browse-time capture. The xray plugin aliases
- * `@hueest/xray/react` to this module in `serve`; production gets the hook-free
- * `react.tsx`.
+ * Dev `<Skeleton>`: production behavior plus the Light Box override, the live-store hot-swap, and
+ * browse-time capture. The xray plugin aliases `@hueest/xray/react` to this module in `serve`;
+ * production gets the lean `react.tsx`.
  */
 declare function Skeleton<T = undefined>(props: SkeletonProps<T>): import("react").JSX.Element;
 //#endregion