@hueest/xray 0.1.0 → 0.2.0

package/dist/{plate-DboxMKg-.d.ts → plate-Bv6W-GkA.d.ts}

@@ -1,3 +1,51 @@
+//#region src/diagnostics.d.ts
+/**
+ * Dev-only capture diagnostics: a small, serializable record of why a Plate may
+ * be incomplete or lower-fidelity, plus the one shared formatter both the
+ * browser console (`client.ts`) and the Vite server output (`index.ts`) print.
+ *
+ * Motivation: the serializer silently swallows a handful of capture omissions
+ * (an unreadable cross-origin stylesheet, skipped pseudo-elements, a collapsed
+ * list run, an over-the-limit subtree). Early adopters asking "why does this
+ * skeleton look wrong?" had to read the serializer source to find out. These
+ * diagnostics surface those omissions as data the capture process returns, so a
+ * caller can log them — without the core performing any console side effects.
+ *
+ * Strictly DEV-ONLY (see the plan's decisions and ADR 0008): this type is NOT a
+ * public package export and MUST NEVER reach the persisted Plate JSON, the
+ * `MergedPlate`, or the production adapter. It rides on the TRANSIENT
+ * `ViewCapture.diagnostics` field only, which `captureRegime` populates and the
+ * dev client strips before posting (so committed `plates/<name>.json` stays
+ * byte-identical to a capture that produced no diagnostics).
+ *
+ * Centralized on purpose: a follow-up plan (capture-input-validation) reuses
+ * this same messaging for invalid posted/committed plates, so the code table
+ * and formatter are kept reusable. Browser and server share `formatDiagnostic`
+ * so their warning text cannot drift.
+ *
+ * @module
+ */
+/**
+ * One aggregated capture omission. Serializable on purpose: NO DOM nodes, NO
+ * CSS bodies, NO captured text — only a stable `code`, a human message, an
+ * optional aggregate `count`, and an optional short `detail` (e.g. a plate name
+ * or a node count, never user content). `count` aggregates occurrences: there
+ * is at most one record per code per capture, never one per skipped selector or
+ * node.
+ */
+interface CaptureDiagnostic {
+  code: DiagnosticCode;
+  message: string;
+  count?: number;
+  detail?: string;
+}
+/**
+ * The closed set of capture-omission codes. Each maps to one silent site in the
+ * serializer (or an existing oversized-capture warning folded into the same
+ * vocabulary). Kept as a const union so the message table is exhaustive.
+ */
+type DiagnosticCode = 'unreadable-stylesheet' | 'unreadable-import' | 'skipped-dynamic-pseudo' | 'skipped-pseudo-element' | 'unsupported-rule' | 'dropped-tag' | 'pruned-run' | 'too-large' | 'invalid-plate-file';
+//#endregion
 //#region src/plate.d.ts
 type LeafKind = 'text' | 'media' | 'box';
 /**
@@ -108,6 +156,17 @@ interface ViewCapture {
   max?: number;
   tree: PlateNode;
   rules: PlateRule[];
+  /**
+   * TRANSIENT, dev-only capture diagnostics (why this view may be lower
+   * fidelity). Populated by `captureRegime` in the browser; the dev client logs
+   * it and posts it (so the Vite server can print the same text), then it is
+   * STRIPPED at the merge layer (`addCapture`) before persisting. It MUST NEVER
+   * be persisted: it is not part of the committed `plates/<name>.json` shape,
+   * the `isViewCapture` validator does not require it, and `addCapture` drops it
+   * so neither it nor `mergeViews` ever writes it. Absent in production (the
+   * prod adapter ships no capture). See diagnostics.ts and ADR 0008.
+   */
+  diagnostics?: CaptureDiagnostic[];
 }
 /** The committed `plates/<name>.json`: per-view captures, merged at load. */
 interface PlateFile {
@@ -151,6 +210,68 @@ interface Span {
   min?: number;
   max?: number;
 }
+/**
+ * Dev-only Fixture store (ADR 0015): stored render-INPUT `data` per Plate,
+ * recorded to and replayed from a `plates/<name>.fixture.json` sidecar. Entirely
+ * dev-only — devalue and this store never reach the production bundle.
+ *
+ * Two cooperating halves, both flowing through the render-prop `data` seam (ADR
+ * 0014):
+ * - The dev adapter (`react.dev.tsx`) calls `register(name, data)` at
+ *   `loading=false` with the live `data` it is about to render, so the latest
+ *   recordable input for each mounted Plate is always in scope for Record.
+ * - `record(name)` serializes that registered live `data` with devalue and POSTs
+ *   it to the sidecar (the HUD button and the `first-ready`/`always` modes call
+ *   it). `has(name)` reports whether a Fixture exists (HUD coverage marker), and
+ *   `read(name)` returns the parsed Fixture `data` for Replay to substitute in
+ *   front of the render prop.
+ *
+ * The store holds DECODED values (the dev client owns the devalue parse, since it
+ * has the live runtime); only the on-disk sidecar and the wire carry the opaque
+ * devalue string.
+ */
+interface FixtureStore {
+  /**
+   * Record the latest live `data` the dev adapter is about to render for `name`,
+   * so Record always has the current recordable input in scope. A `register` with
+   * the same value is cheap; the adapter calls it on every ready render. Returns a
+   * disposer the adapter runs on unmount so an unmounted Skeleton's `data` never
+   * lingers in the store: an unmounted instance must never be recorded or shadow a
+   * still-mounted one (ADR 0015). With several Skeletons of the same plate name
+   * mounted, the live value is the most-recently-registered still-mounted instance.
+   */
+  register: (name: string, data: unknown) => () => void;
+  /** True once a recorded Fixture exists for `name` (drives the HUD coverage marker). */
+  has: (name: string) => boolean;
+  /** The parsed Fixture `data` for `name`, or `undefined` when none is recorded. */
+  read: (name: string) => {
+    data: unknown;
+  } | undefined;
+  /**
+   * Serialize the registered live `data` for `name` with devalue and POST it to
+   * the sidecar. Returns a promise that resolves once the write is
+   * server-confirmed (so the HUD can surface a failed Record). Throws loudly when
+   * the live `data` is unrecordable (devalue's contract) or no live `data` was
+   * registered (a plain-children `<Skeleton>` has none).
+   */
+  record: (name: string) => Promise<void>;
+  /**
+   * Record every Skeleton that currently has live `data` registered (the HUD's
+   * single "Record fixture" button — one click captures the inputs of all mounted
+   * render-prop Skeletons). Resolves once all writes are server-confirmed; a
+   * rejected write surfaces to the HUD.
+   */
+  recordAll: () => Promise<void>;
+  /**
+   * Seed the store from the on-disk sidecars on boot: a `{ <name>: devalueString }`
+   * map (the opaque strings the server serves). The client decodes each with
+   * devalue. Existing entries are not clobbered, so a Fixture recorded this
+   * session survives a re-seed.
+   */
+  seed: (encoded: Record<string, string>) => void;
+  /** React subscription so the HUD re-renders when a Fixture is recorded or seeded. */
+  subscribe: (onChange: () => void) => () => void;
+}
 /** A plate's detected width thresholds and the spans actually captured, from disk. */
 interface PlateCoverage {
   breakpoints: number[];
@@ -175,6 +296,8 @@ interface CoverageStore {
 interface CaptureHook {
   captured: (name: string, el: Element, opts?: {
     delay?: number;
+    walker?: unknown;
+    mode?: 'auto' | 'manual';
   }) => (() => void) | undefined;
   /** Light Box toggle: force every `<Skeleton>` to its skeleton, read by `<Skeleton>`. */
   lightbox?: ToggleStore;
@@ -188,6 +311,25 @@ interface CaptureHook {
   captureAllViews?: () => Promise<void>;
   /** Dev-only per-plate breakpoints + captured spans, from disk; fed by the bootstrap. */
   coverage?: CoverageStore;
+  /**
+   * Replay toggle (ADR 0015): when active, the dev adapter substitutes a recorded
+   * Fixture's `data` for the live `data` at `loading=false`. The boolean is the
+   * coarse on/off the HUD owns per tab; the per-mode policy (`prefer` vs
+   * `missing-only`) is carried alongside in `replayMode`.
+   */
+  replay?: ToggleStore;
+  /** Dev-only Replay policy: how a Fixture substitutes for live `data` (ADR 0015). */
+  replayMode?: 'prefer' | 'missing-only';
+  /**
+   * Dev-only Record policy (ADR 0015): when the dev adapter records the live
+   * `data` it is about to render. `'manual'` (the default) records nothing
+   * automatically — only the HUD button does; `'first-ready'` records once when a
+   * Skeleton goes ready and has no Fixture yet; `'always'` records on every ready
+   * render.
+   */
+  recordMode?: 'manual' | 'first-ready' | 'always';
+  /** Dev-only Fixture record/replay store (ADR 0015); never present in production. */
+  fixtures?: FixtureStore;
 }
 declare global {
   var __XRAY__: CaptureHook | undefined;

package/dist/plate-DoE1HEXp.js

@@ -0,0 +1,152 @@
+/** 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).
+*/
+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).
+*/
+const BOUNDARY_ATTR = "data-xr-boundary";
+const SPEC_LEAF = 9e6;
+const SPEC_INLINE = 1e7;
+const SPEC_GATE = 2e7;
+/** Fixed renderer-owned classes every rendered node carries. */
+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`).
+*
+* 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-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.
+*/
+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
+   opacity animations would pin the compositor and cook the CPU. */
+@property --xr-o { syntax: "<number>"; inherits: true; initial-value: 1 }
+/* The reveal channel (ADR 0016): a second inherited opacity factor the leaf
+   multiplies into --xr-o. Transitioning THIS (not opacity directly) sidesteps
+   the animation-vs-transition collision ADR 0012 flagged. initial-value 1 (NOT
+   0) is the degradation floor: without @starting-style the reveal can never be
+   driven 0->1, so it must REST at 1 (fully visible). The delay-hide below is
+   pure progressive enhancement layered on top. */
+@property --xr-reveal { syntax: "<number>"; inherits: true; initial-value: 1 }
+.${ROOT_CLASS} {
+  --xr-bone-highlight-color: #f4f4f5;
+  display: contents;
+  animation: var(--xr-bone-animation, xr-pulse) var(--xr-bone-animation-duration, 1.2s) ease-in-out infinite alternate;
+}
+/* No pointer-events:none — it blocks inspecting bones in devtools and buys
+   nothing (no real content to click). border-color: a node may capture
+   border-width for layout; its paint stays out. list-style: suppress a ::marker
+   a captured display:list-item would otherwise paint. */
+.${NODE_CLASS} { border-color: transparent; list-style: none }
+.${LEAF_CLASS} {
+  background: var(--xr-bone-fill, var(--xr-bone-color, #e4e4e7));
+  border-radius: var(--xr-bone-border-radius, 4px);
+  /* Composed opacity (ADR 0016): the pulse channel times the reveal channel.
+     Never transition opacity directly (the pulse animation owns it). */
+  opacity: calc(var(--xr-o) * var(--xr-reveal));
+}
+/* Per-kind defaults: text reads as rounded bars, media as blocks. Re-theme any
+   kind via [data-xr-root] .${LEAF_CLASS}-text { ... }. */
+.${LEAF_CLASS}-text { border-radius: var(--xr-bone-text-border-radius, 999px) }
+.${LEAF_CLASS}-media { border-radius: var(--xr-bone-media-border-radius, var(--xr-bone-border-radius, 4px)) }
+@keyframes xr-pulse {
+  from { --xr-o: var(--xr-bone-pulse-opacity-max, 1) }
+  to { --xr-o: var(--xr-bone-pulse-opacity-min, 0.5) }
+}
+/* Reveal delay-hide (ADR 0016), a progressive enhancement guarded so it can NEVER
+   strand a skeleton invisible (open Q3). @starting-style is the trigger: only a
+   browser that supports it enters this block at all, and such a browser also
+   honors @property + transitions, so the 0->1 reveal completes. The @supports
+   selector(...) probe is the broadest cross-engine @starting-style feature test
+   available. Without support the block is skipped entirely and --xr-reveal stays
+   at its initial-value 1 = fully visible instant skeleton. INSIDE the block we
+   start at 0 and transition to 1 after the delay: invisible for
+   --xr-skeleton-delay, then a --xr-skeleton-transition-duration fade-in; a fast
+   load unmounts before the delay elapses and the skeleton is never seen. */
+@supports (selector(:has(*))) {
+  /* The delay-hide applies to every root EXCEPT a stitch continuation (ADR 0020).
+     Scoping with :not([data-xr-instant]) keeps an ordinary top-level skeleton
+     byte-identical to before: it still mounts at --xr-reveal 0 and fades in after
+     the delay. The transition/initial-1 rest state matches the original. */
+  .${ROOT_CLASS}:not([${ROOT_INSTANT_ATTR}]) {
+    --xr-reveal: 1;
+    transition: --xr-reveal var(--xr-skeleton-transition-duration, 150ms) linear var(--xr-skeleton-delay, 250ms);
+  }
+  @starting-style { .${ROOT_CLASS}:not([${ROOT_INSTANT_ATTR}]) { --xr-reveal: 0 } }
+  /* A stitch continuation (ADR 0020) reveals INSTANTLY: it was already visible as a
+     stitch under a still-showing parent, so re-paying the delay would flash it away
+     and back. No @starting-style and no transition — it rests at fully visible from
+     its first frame, matching how the stitch inherited the parent's reveal. */
+  .${ROOT_CLASS}[${ROOT_INSTANT_ATTR}] { --xr-reveal: 1 }
+}
+/* Reduced motion (open Q2): keep the anti-flash delay + min-duration (they are
+   not motion), drop only the FADE — collapse the reveal transition to instant and
+   kill the pulse animation (as before). */
+@media (prefers-reduced-motion: reduce) {
+  .${ROOT_CLASS} { animation: none; --xr-skeleton-transition-duration: 0s }
+}
+/* Dark + high-contrast bone defaults. Guarded: light-dark() is an invalid value
+   without support and would drop the declaration — see the note above; remove
+   this @supports once widely available (2026-11-13). */
+@supports (color: light-dark(#000, #fff)) {
+  .${ROOT_CLASS} { --xr-bone-highlight-color: light-dark(#f4f4f5, #52525b) }
+  .${LEAF_CLASS} { background: var(--xr-bone-fill, var(--xr-bone-color, light-dark(#e4e4e7, #3f3f46))) }
+  @media (prefers-contrast: more) {
+    .${LEAF_CLASS} { background: var(--xr-bone-fill, var(--xr-bone-color, light-dark(#d4d4d8, #52525b))) }
+  }
+}
+/* Derive the sheen highlight from --xr-bone-color so re-theming one token updates
+   both. Relative color isn't widely available yet; the static highlight above is
+   the fallback (sheen just looks flatter), so no hard guard is needed. */
+@supports (color: oklch(from red l c h)) {
+  .${ROOT_CLASS} { --xr-bone-highlight-color: oklch(from var(--xr-bone-color, #e4e4e7) calc(l + 0.08) c h) }
+}`.trim();
+/** The (unserialized) plate an import resolves to before anything has been captured. */
+function emptyPlate(name) {
+	return {
+		v: 1,
+		name,
+		tree: null,
+		css: ""
+	};
+}
+//#endregion
+export { ROOT_ATTR as a, SPEC_GATE as c, emptyPlate as d, NODE_CLASS as i, SPEC_INLINE as l, BOUNDARY_ATTR as n, ROOT_CLASS as o, LEAF_CLASS as r, ROOT_INSTANT_ATTR as s, BASE_CSS as t, SPEC_LEAF as u };

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

@@ -0,0 +1,79 @@
+import { r as Plate } from "./plate-Bv6W-GkA.js";
+import { o as XrayCaptureWalker } from "./serialize-B--oY2bV.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
+   * `captureRegime`; 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-IyFy2b_8.js

@@ -0,0 +1,267 @@
+import { a as ROOT_ATTR, o as ROOT_CLASS, s as ROOT_INSTANT_ATTR, t as BASE_CSS } from "./plate-DoE1HEXp.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 ("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 ("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 };