@hueest/xray 0.5.0 → 0.7.0

package/dist/measure-CUQxB-Ic.d.ts

@@ -0,0 +1,524 @@
+//#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, off-screen bones dropped at the fold, an
+ * over-the-limit subtree). Without these records, "why does this skeleton look wrong?" has no
+ * answer short of reading the serializer source. Diagnostics surface those omissions as data the
+ * capture returns, so a caller can log them; the core performs no console side effects.
+ *
+ * Strictly DEV-ONLY (ADR 0024, ADR 0008): this type is NOT a public package export and MUST NEVER
+ * reach the persisted Plate JSON, the `GatedPlate`, or the production adapter. It rides on the
+ * TRANSIENT `ViewIR.diagnostics` field only, which `captureView` populates and the dev client
+ * strips before posting (so committed `plates/<name>.json` stays byte-identical to a capture that
+ * produced no diagnostics).
+ *
+ * Centralized on purpose: invalid posted/committed plates (ADR 0023) reuse the same messaging, so
+ * the code table and formatter stay 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' | 'dropped-subset' | 'dropped-cropped' | 'too-large' | 'invalid-plate-file';
+//#endregion
+//#region src/plate.d.ts
+/**
+ * `hidden` is EXPLICIT-ONLY (a `data-xr-bone-kind` hint or a walker `ctx.bone({ kind: 'hidden'
+ * })`), never inferred: a bone that holds its measured box in the layout but paints nothing — the
+ * space-preserving complement to `data-xr-ignore`, which drops the box entirely.
+ */
+type LeafKind = 'text-line' | 'text-block' | 'media' | 'box' | 'hidden';
+/**
+ * The shipped structural capture of a component's rendered DOM — the TREE artifact a Skeleton
+ * renders from (see the glossary: xray-js.dev/glossary). A Plate carries structure ONLY (ADR 0026):
+ * its scoped CSS is an INDEPENDENT sibling artifact — the plugin serves it through Vite's own CSS
+ * pipeline (`virtual:xray/plates/<name>.css`, plus the shared `virtual:xray/base.css`, and an
+ * `export const css` on the virtual JS module for dev/programmatic reads), and the
+ * framework-neutral `core.ts` path hands it back separately (`captureElement` → `{ plate, css }`;
+ * `renderPlateHtml(plate, css)` receives it explicitly). Consumers decide how to render either
+ * part. Still self-contained in ADR 0003's sense: both artifacts originate from the capture and
+ * depend on nothing in the consumer's build. Built from the RenderNode tree at plugin load (see
+ * chunk.ts), so the adapter injects strings instead of walking a tree on the latency-critical first
+ * paint — and no per-framework serializer ships to the client (ADR 0008).
+ */
+interface Plate {
+  v: number;
+  /** Capture name; comes from the virtual-module specifier, never typed at a call site. */
+  name: string;
+  /**
+   * The root's children, pre-serialized (ADR 0008): a stitch-free run is one HTML `string`; a
+   * stitch is `{ r: name }`; a stitch-bearing element is `{ c: className, k: chunk[] }`. Null until
+   * first capture.
+   */
+  chunks: Chunk[] | null;
+  /** The root node's own content classes (its inherited font context), if any. */
+  rootCls?: string;
+  /**
+   * Child plates named by the chunks' `{ r }` stitches, resolved through the import graph (ADR
+   * 0006). Populated by the loader's generated imports, never serialized into the plates JSON;
+   * absent in production when there are no stitches. In dev the live store takes precedence, so
+   * this need not be present.
+   */
+  refs?: Record<string, Plate>;
+}
+/**
+ * One serialized child of a plate root (or of a stitch-bearing node): a stitch-free HTML run
+ * (`string`), a stitch to a child plate (`{ r: name }`), a stitch-bearing element kept real so its
+ * inner stitches can mount (`{ c: className, k: chunk[] }`), or a templated uniform run (`{ t:
+ * html, n }`): the cell's HTML once plus a repeat count the adapter expands to N copies (Template,
+ * ADR 0022). The framework-neutral render contract: an adapter injects the strings, mounts a child
+ * plate at each stitch, and repeats each template (ADR 0008).
+ */
+type Chunk = string | {
+  r: string;
+} | {
+  c: string;
+  k: Chunk[];
+} | {
+  t: string;
+  n: number;
+};
+/**
+ * A plate after the in-browser Serialize (emit + gate + classify) but before chunk serialization:
+ * the build-time RenderNode tree plus its scoped CSS. Produced by `serializePlateIR` (the
+ * structural part of `StoredPlate`) and the single-View `capture`, then serialized into the shipped
+ * `Plate` (chunks) at load (`serializePlate`). Never shipped to the client.
+ */
+interface GatedPlate {
+  v: number;
+  name: string;
+  tree: RenderNode | null;
+  css: string;
+}
+interface PlateNode {
+  /** Plate-local id; rules reference it pre-classify. Stripped from the shipped tree. */
+  id: number;
+  /** Present on paint leaves; absent on layout containers. */
+  leaf?: LeafKind;
+  /**
+   * A stitch: render the named child plate's skeleton here instead of own structure (ADR 0006).
+   * Mutually exclusive with `leaf`/`kids`. Resolved against `Plate.refs` (prod) or the live store
+   * (dev).
+   */
+  ref?: string;
+  /**
+   * A templated uniform run (Template, ADR 0022): render this node's subtree `count` times. The
+   * serializer emits the subtree's HTML once plus the count; the adapter expands it to N copies at
+   * render. Absent on ordinary nodes.
+   */
+  count?: number;
+  kids?: PlateNode[];
+}
+/**
+ * A node in the shipped tree, after classify (ADR 0007). Carries the content-addressed style
+ * classes it needs instead of an id — the CSS targets those classes, not a per-node `data-xr`
+ * value, so no per-node scoping key is needed. `cls` is a space-joined class-token list.
+ */
+interface RenderNode {
+  leaf?: LeafKind;
+  ref?: string;
+  cls?: string;
+  /**
+   * A templated uniform run (Template, ADR 0022): serialize this subtree once + a count the adapter
+   * repeats.
+   */
+  count?: number;
+  kids?: RenderNode[];
+}
+/**
+ * A captured style rule in id form — selectors are generated downstream, so Serialize can remap
+ * node ids without string surgery. `ids: []` targets the plate root.
+ */
+interface PlateRule {
+  ids: number[];
+  decls: string[];
+  /** Media-condition stack, outermost first; conditions AND together. */
+  media?: string[];
+  /** `@container`-condition stack, outermost first; conditions AND together. Absent when none. */
+  container?: string[];
+  layered?: boolean;
+  spec: number;
+  order: number;
+}
+/**
+ * One capture of a component within one viewport view — `[min, max)` in px, either side open-ended
+ * when undefined. The id-form `{ tree, rules }` shape `emit` projects a measured View into (ADR
+ * 0004). The disk/wire shape is `StoredPlate` (below); this is the framework-neutral per-View
+ * capture shape, exported for consumers reading the id-form projection directly.
+ */
+interface ViewCapture {
+  /** Viewport width at capture time. */
+  width: number;
+  min?: number;
+  max?: number;
+  tree: PlateNode;
+  rules: PlateRule[];
+  /**
+   * TRANSIENT, dev-only capture diagnostics (why this view may be lower fidelity). Captured in the
+   * browser (mirrored onto `ViewIR.diagnostics`); the dev client logs it and posts it alongside the
+   * `StoredPlate` (so the Vite server can print the same text). It MUST NEVER be persisted: it is
+   * not part of the committed `StoredPlate` disk shape, the validator does not carry it, and the
+   * POST envelope keeps it in a SIBLING field that never reaches the stored artifact (ADR 0008).
+   * Absent in production (the prod adapter ships no capture). See diagnostics.ts and ADR 0008.
+   */
+  diagnostics?: CaptureDiagnostic[];
+}
+/**
+ * The committed `plates/<name>.json` shape (ADR 0022): the whole Plate already projected in the
+ * browser (the in-browser Serialize folds emit + the multi-View gating + classify in one session),
+ * so disk holds ONE gated, content-addressed tree + css rather than per-View captures assembled at
+ * load. It is a `GatedPlate` (the structural `{tree, css}` `serializePlate` consumes) PLUS the
+ * `breakpoints` the HUD coverage reads — the analysis-only geometry never crosses the wire (ADR
+ * 0021). The gen-side runs `serializePlate(stored) → Plate` (chunks) at module-load, leaving the
+ * Tailwind/Bundle passthrough a clean gen-side seam.
+ */
+interface StoredPlate extends GatedPlate {
+  /** Width thresholds (view boundaries); the HUD coverage derives its bands from these. */
+  breakpoints: number[];
+}
+/**
+ * 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-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 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.
+ */
+declare const BASE_CSS = "/* One timeline per skeleton, not per leaf: the root animates one inherited\n   opacity property and every leaf reads it. Hundreds of independent infinite\n   opacity animations would pin the compositor and cook the CPU. */\n@property --xr-o { syntax: \"<number>\"; inherits: true; initial-value: 1 }\n/* The reveal channel (ADR 0016): a second inherited opacity factor the leaf\n   multiplies into --xr-o. Transitioning THIS (not opacity directly) sidesteps\n   the animation-vs-transition collision ADR 0012 flagged. initial-value 1 (NOT\n   0) is the degradation floor: without @starting-style the reveal can never be\n   driven 0->1, so it must REST at 1 (fully visible). The delay-hide below is\n   pure progressive enhancement layered on top. */\n@property --xr-reveal { syntax: \"<number>\"; inherits: true; initial-value: 1 }\n.xr-root {\n  --xr-bone-highlight-color: #f4f4f5;\n  display: contents;\n  animation: var(--xr-bone-animation, xr-pulse) var(--xr-bone-animation-duration, 1.2s) ease-in-out infinite alternate;\n}\n/* No pointer-events:none — it blocks inspecting bones in devtools and buys\n   nothing (no real content to click). border-color: a node may capture\n   border-width for layout; its paint stays out. list-style: suppress a ::marker\n   a captured display:list-item would otherwise paint. */\n.xr-node { border-color: transparent; list-style: none }\n.xr-leaf {\n  background: var(--xr-bone-fill, var(--xr-bone-color, #e4e4e7));\n  border-radius: var(--xr-bone-border-radius, 4px);\n  /* Composed opacity (ADR 0016): the pulse channel times the reveal channel.\n     Never transition opacity directly (the pulse animation owns it). */\n  opacity: calc(var(--xr-o) * var(--xr-reveal));\n}\n/* Per-kind defaults: a single text LINE reads as a rounded bar; a multi-line\n   text BLOCK as a soft rect (a tall pill misreads as a button); media carries\n   the author radius, defaulting to the same soft rect. Re-theme any kind via\n   [data-xr-root] .xr-leaf-text-line { ... }. */\n.xr-leaf-text-line { border-radius: var(--xr-bone-text-line-border-radius, 999px) }\n.xr-leaf-text-block { border-radius: var(--xr-bone-text-block-border-radius, var(--xr-bone-border-radius, 4px)) }\n.xr-leaf-media { border-radius: var(--xr-bone-media-border-radius, var(--xr-bone-border-radius, 4px)) }\n/* A hidden bone holds its measured box in the flow but paints nothing: the\n   space-preserving complement to data-xr-ignore. visibility (not display) so\n   the captured size rules still lay the box out. */\n.xr-leaf-hidden { visibility: hidden }\n@keyframes xr-pulse {\n  from { --xr-o: var(--xr-bone-pulse-opacity-max, 1) }\n  to { --xr-o: var(--xr-bone-pulse-opacity-min, 0.5) }\n}\n/* Reveal delay-hide (ADR 0016), a progressive enhancement guarded so it can NEVER\n   strand a skeleton invisible (open Q3). @starting-style is the trigger: only a\n   browser that supports it enters this block at all, and such a browser also\n   honors @property + transitions, so the 0->1 reveal completes. The @supports\n   selector(...) probe is the broadest cross-engine @starting-style feature test\n   available. Without support the block is skipped entirely and --xr-reveal stays\n   at its initial-value 1 = fully visible instant skeleton. INSIDE the block we\n   start at 0 and transition to 1 after the delay: invisible for\n   --xr-skeleton-delay, then a --xr-skeleton-transition-duration fade-in; a fast\n   load unmounts before the delay elapses and the skeleton is never seen. */\n@supports (selector(:has(*))) {\n  /* The delay-hide applies to every root EXCEPT a stitch continuation (ADR 0020).\n     Scoping with :not([data-xr-instant]) keeps an ordinary top-level skeleton\n     byte-identical to before: it still mounts at --xr-reveal 0 and fades in after\n     the delay. The transition/initial-1 rest state matches the original. */\n  .xr-root:not([data-xr-instant]) {\n    --xr-reveal: 1;\n    transition: --xr-reveal var(--xr-skeleton-transition-duration, 150ms) linear var(--xr-skeleton-delay, 250ms);\n  }\n  @starting-style { .xr-root:not([data-xr-instant]) { --xr-reveal: 0 } }\n  /* A stitch continuation (ADR 0020) reveals INSTANTLY: it was already visible as a\n     stitch under a still-showing parent, so re-paying the delay would flash it away\n     and back. No @starting-style and no transition — it rests at fully visible from\n     its first frame, matching how the stitch inherited the parent's reveal. */\n  .xr-root[data-xr-instant] { --xr-reveal: 1 }\n}\n/* Reduced motion (open Q2): keep the anti-flash delay + min-duration (they are\n   not motion), drop only the FADE — collapse the reveal transition to instant and\n   kill the pulse animation (as before). */\n@media (prefers-reduced-motion: reduce) {\n  .xr-root { animation: none; --xr-skeleton-transition-duration: 0s }\n}\n/* Dark + high-contrast bone defaults. Guarded: light-dark() is an invalid value\n   without support and would drop the declaration — see the note above; remove\n   this @supports once widely available (2026-11-13). */\n@supports (color: light-dark(#000, #fff)) {\n  .xr-root { --xr-bone-highlight-color: light-dark(#f4f4f5, #52525b) }\n  .xr-leaf { background: var(--xr-bone-fill, var(--xr-bone-color, light-dark(#e4e4e7, #3f3f46))) }\n  @media (prefers-contrast: more) {\n    .xr-leaf { background: var(--xr-bone-fill, var(--xr-bone-color, light-dark(#d4d4d8, #52525b))) }\n  }\n}\n/* Derive the sheen highlight from --xr-bone-color so re-theming one token updates\n   both. Relative color isn't widely available yet; the static highlight above is\n   the fallback (sheen just looks flatter), so no hard guard is needed. */\n@supports (color: oklch(from red l c h)) {\n  .xr-root { --xr-bone-highlight-color: oklch(from var(--xr-bone-color, #e4e4e7) calc(l + 0.08) c h) }\n}";
+/**
+ * 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.
+ */
+declare function composeCss(css: string): string;
+/** The (unserialized) plate an import resolves to before anything has been captured. */
+declare function emptyPlate(name: string): GatedPlate;
+/**
+ * A dev-only sticky boolean toggle (get/set/subscribe), persisted per tab. Used for both "light
+ * box" (render every `<Skeleton>` regardless of readiness) and "capture" (whether browsing
+ * re-captures plates).
+ */
+interface ToggleStore {
+  get: () => boolean;
+  set: (value: boolean) => void;
+  subscribe: (onChange: () => void) => () => void;
+}
+/**
+ * Dev-only store of the freshest plate per name, updated in place when a capture lands.
+ * `<Skeleton>` reads through it so a new plate re-renders the site rather than reloading the module
+ * — which would remount the capture boundary and re-fire the capture, a feedback loop.
+ */
+interface PlateStore {
+  get: (name: string) => Plate | undefined;
+  subscribe: (name: string, onChange: () => void) => () => void;
+  /**
+   * Register a plate imported via the ref graph if the store has none yet — so a stitch resolves
+   * even before its child is re-captured, and survives a parent hot-swap (whose pushed plate
+   * carries no resolved `refs`). Never overwrites a live capture.
+   */
+  seed: (name: string, plate: Plate) => void;
+}
+/** A view interval `[min, max)`; an open end is undefined (ADR 0004). */
+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[];
+  spans: Span[];
+}
+/**
+ * Dev-only per-plate coverage, sourced from the committed plate files (not the session): the
+ * breakpoints detected so far and which view spans are captured. The HUD renders every band —
+ * covered ones lit, the rest dim — and the capture-all sweep derives its target widths from the
+ * breakpoints.
+ */
+interface CoverageStore {
+  get: () => ReadonlyMap<string, PlateCoverage>;
+  set: (name: string, coverage: PlateCoverage) => void;
+  subscribe: (onChange: () => void) => () => void;
+}
+/**
+ * Dev-only capture hook, installed by the dev client before the app boots. Absent in production
+ * builds, so `<Skeleton>` carries zero capture weight. `captured` returns a dispose callback (stop
+ * observing this site).
+ */
+interface CaptureHook {
+  captured: (name: string, el: Element, opts?: {
+    delay?: number;
+    walker?: unknown;
+    mode?: 'auto' | 'manual';
+    collect?: {
+      maxNodes?: number;
+      maxBreadth?: number;
+      maxDepth?: number;
+    };
+  }) => (() => void) | undefined;
+  /** Light Box toggle: force every `<Skeleton>` to its skeleton, read by `<Skeleton>`. */
+  lightbox?: ToggleStore;
+  /** Capture toggle: whether browsing re-captures plates, flipped from the HUD. */
+  capture?: ToggleStore;
+  /** Read side for `<Skeleton>`. */
+  plates?: PlateStore;
+  /** Write side for the dev client's HMR-event handler. Returns whether the plate changed. */
+  updatePlate?: (name: string, plate: Plate) => boolean;
+  /** Dev-only: run the HUD-triggered capture-all-views sweep via the extension (ADR 0010). */
+  captureAllViews?: () => Promise<void>;
+  /** Dev-only per-plate breakpoints + captured spans, from disk; fed by the bootstrap. */
+  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;
+}
+//#endregion
+//#region src/measure.d.ts
+/**
+ * Browser-side capture: walk a live rendered subtree into a Plate — one node tree plus one
+ * self-contained, scoped CSS string (ADR 0003). The CSS is lifted from the author rules that
+ * matched each node, rewritten to plate-local selectors — it carries `@media` for free and keeps
+ * layout live (the bake-off winner; ADR 0005).
+ */
+interface CaptureOptions {
+  /** Plate name; comes from the virtual-module specifier. */
+  name: string;
+  /** Collect limits (ADR 0022): refuse a capture whose measured tree exceeds any axis. */
+  collect?: CollectLimits;
+  /**
+   * Optional programmable capture walker (ADR 0018). The declarative `data-xr-*` hints cover the
+   * 90%; this is the escape hatch for the 10% a markup attribute cannot express. Capture-only: it
+   * shapes the resulting `PlateNode` tree but is never persisted into the Plate, and the production
+   * adapter never captures so it ignores this entirely.
+   */
+  walker?: XrayCaptureWalker;
+  /**
+   * Whether the top-level capture roots ARE this plate's own boundary, so the stitch guard must be
+   * SKIPPED for them (ADR 0006/0014). True ONLY for a MANUAL root: there `site.el` is the
+   * consumer's own element and its `data-xr-boundary` marks the boundary of THIS plate, so the root
+   * must be serialized as a real Entry (its box/classes/padding/border) rather than a
+   * stitch-to-itself. Defaults to `false` — the auto path, where the top-level roots are the
+   * wrapper's CHILDREN and any boundary marker on a direct-child root is a NESTED `<Skeleton>` that
+   * MUST stitch (the capture-leak guard).
+   */
+  captureRootIsBoundary?: boolean;
+}
+/**
+ * What a capture walker decides for one element (ADR 0018; ADR 0022 §5). The `applyWalker` PASS
+ * reads the decision and applies it to the measured IR node — a walker NEVER hand-builds a
+ * `PlateNode`, so xray keeps ownership of the Plate format. `ignore` drops the element + its
+ * subtree; `bone` collapses it to one Bone leaf (inferring the kind when omitted); `keep` defers to
+ * the default classifier (`markInk`).
+ */
+type WalkerDecision = {
+  type: 'ignore';
+} | {
+  type: 'bone';
+  kind?: LeafKind;
+} | {
+  type: 'keep';
+};
+/**
+ * The context handed to a capture walker's `element` hook (ADR 0018). The helpers are PURE — each
+ * returns a `WalkerDecision` the `applyWalker` pass applies; they do NOT mutate. `el` is the
+ * element under consideration.
+ */
+interface CaptureWalkerContext {
+  /** The element currently being classified. */
+  el: Element;
+  /** Drop this element AND its whole subtree (no bone). */
+  ignore(): WalkerDecision;
+  /**
+   * Collapse this element's subtree into ONE Bone leaf. `kind` omitted shares the default
+   * classifier's kind-inference heuristic (`inferLeafKind`; ADR 0018, Q4 — ONE code path).
+   */
+  bone(opts?: {
+    kind?: LeafKind;
+  }): WalkerDecision;
+  /** Defer to the default classifier (`markInk`) — recurse into the subtree. */
+  keep(): WalkerDecision;
+}
+/**
+ * The programmable capture walker (ADR 0018; ADR 0022 §5). `element` is offered each non-boundary
+ * element TOP-DOWN over the measured IR (the `applyWalker` pass, NOT the DOM walk) and returns a
+ * `WalkerDecision` the pass applies. The declarative `data-xr-*` hints cover the 90%; this is the
+ * 10% escape hatch for what a markup attribute cannot express.
+ */
+interface XrayCaptureWalker {
+  /**
+   * Called for every non-boundary element node (a stitch carries no element and is skipped — ADR
+   * 0006 — so a boundary never reaches here). Return one of `ctx.ignore()`, `ctx.bone()`, or
+   * `ctx.keep()`. An `ignore`/`bone` decision stops the descent (the subtree lowers); `keep`
+   * recurses.
+   */
+  element?(ctx: CaptureWalkerContext): WalkerDecision;
+}
+/**
+ * Typed identity wrapper for authoring a capture walker (ADR 0018) — the `defineConfig` pattern. It
+ * returns its argument unchanged at runtime; its only job is to infer and check the
+ * `XrayCaptureWalker` shape at the call site so an author gets completion and a typo in a hook name
+ * is caught.
+ */
+declare function defineXrayCaptureWalker(walker: XrayCaptureWalker): XrayCaptureWalker;
+/** The measured size of a capture's surviving tree, one number per Collect axis (ADR 0022). */
+type CaptureSize = {
+  nodes: number;
+  breadth: number;
+  depth: number;
+};
+/** Which Collect axis a too-large capture tripped. */
+type CollectAxis = 'nodes' | 'breadth' | 'depth';
+/**
+ * Thrown when a capture's measured tree exceeds a Collect limit — almost always a `<Skeleton>`
+ * sitting too high in the tree. Raised after the cheap walk and before the O(rules × nodes) CSS
+ * extraction, so an oversized capture is refused without freezing the main thread on it.
+ */
+declare class CaptureTooLargeError extends Error {
+  /** The full measured size of the surviving tree that tripped the gate. */
+  readonly size: CaptureSize;
+  /** Which axis exceeded its cap, and the cap it exceeded. */
+  readonly axis: CollectAxis;
+  readonly max: number;
+  /** Back-compat alias for `size.nodes` (the sole axis before breadth/depth). */
+  readonly nodeCount: number;
+  /** Folds the oversized-capture warning into the shared diagnostics vocabulary (diagnostics.ts). */
+  readonly code: "too-large";
+  constructor(size: CaptureSize, axis: CollectAxis, max: number);
+}
+/**
+ * Collect-stage size limits (ADR 0022): refuse to capture a boundary whose measured tree exceeds
+ * any axis. `maxNodes` caps the total surviving-node count; `maxBreadth` the widest level (most
+ * nodes at any one depth); `maxDepth` the nesting depth. Each axis is enforced only when its cap is
+ * defined. The defaults and the `maxNodes = round(maxBreadth × maxDepth / 4)` derivation live in
+ * the client (where the other defaults live); this core only enforces what it is handed.
+ */
+type CollectLimits = {
+  maxNodes?: number;
+  maxBreadth?: number;
+  maxDepth?: number;
+};
+//#endregion
+export { ViewCapture as _, CollectAxis as a, CaptureDiagnostic as b, XrayCaptureWalker as c, GatedPlate as d, LeafKind as f, StoredPlate as g, RenderNode as h, CaptureWalkerContext as i, defineXrayCaptureWalker as l, PlateNode as m, CaptureSize as n, CollectLimits as o, Plate as p, CaptureTooLargeError as r, WalkerDecision as s, CaptureOptions as t, BASE_CSS as u, composeCss as v, emptyPlate as y };