@hueest/xray 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,39 +1,34 @@
 import { Plugin } from "vite";
-
 //#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.
+ * 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). 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.
+ * 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 (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
- * `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).
+ * 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: 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.
+ * 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.
+ * 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;
@@ -42,52 +37,59 @@ interface CaptureDiagnostic {
   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.
+ * 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
-type LeafKind = 'text' | 'text-block' | 'media' | 'box';
 /**
- * The shipped structural capture of a component's rendered DOM — the data a
- * Skeleton renders from (see CONTEXT.md). Self-contained: pre-serialized chunks
- * plus one scoped CSS string; depends on nothing in the consumer's build (ADR
- * 0003). 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).
+ * `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.
+   * 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;
-  /** Layout-relevant CSS (incl. `@media`) scoped under the plate root, paint stripped. */
-  css: 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.
+   * 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 (Phase
- * 2). The framework-neutral render contract: an adapter injects the strings,
- * mounts a child plate at each stitch, and repeats each template (ADR 0008).
+ * 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;
@@ -99,13 +101,12 @@ type Chunk = string | {
   n: number;
 };
 /**
- * A plate after the in-browser Serialize (emit + merge/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.
+ * 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 MergedPlate {
+interface GatedPlate {
   v: number;
   name: string;
   tree: RenderNode | null;
@@ -117,37 +118,38 @@ interface PlateNode {
   /** 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).
+   * 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 (Phase 2): 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.
+   * 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 node scoping (the old
- * `nodeKey`) is gone. `cls` is a space-joined class-token list.
+ * 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 (Phase 2): serialize this subtree once + a count the adapter repeats. */
+  /**
+   * 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 at render time,
- * so view merging can remap node ids without string surgery. `ids: []`
- * targets the plate root.
+ * 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[];
@@ -161,12 +163,10 @@ interface PlateRule {
   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). NO LONGER the disk/wire shape
- * after the ADR 0022 cutover — `StoredPlate` (below) is. Kept as the
- * framework-neutral per-View capture shape, exported for consumers reading the
- * id-form projection directly.
+ * 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. */
@@ -176,37 +176,32 @@ interface ViewCapture {
   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.
+   * 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 AFTER the ADR 0022 cutover: the whole
- * Plate already projected in the browser (the in-browser Serialize folds emit +
- * the multi-View merge/gate + classify in one session), so disk holds ONE gated,
- * content-addressed tree + css instead of per-View captures merged at load. It is
- * a `MergedPlate` (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.
- * Replaces `PlateFile` (+ `ViewCapture`) on disk and on the `/__xray` wire.
+ * 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 MergedPlate {
+interface StoredPlate extends GatedPlate {
   /** Width thresholds (view boundaries); the HUD coverage derives its bands from these. */
   breakpoints: number[];
 }
 /**
- * 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).
+ * 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;
@@ -214,19 +209,17 @@ interface ToggleStore {
   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.
+ * 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.
+   * 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;
 }
@@ -236,34 +229,31 @@ interface Span {
   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.
+ * 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):
  *
- * 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 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.
+ * 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.
+   * 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). */
@@ -273,25 +263,22 @@ interface FixtureStore {
     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).
+   * 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.
+   * 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 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. */
@@ -303,10 +290,10 @@ interface PlateCoverage {
   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.
+ * 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>;
@@ -314,9 +301,9 @@ interface CoverageStore {
   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).
+ * 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?: {
@@ -342,20 +329,18 @@ interface CaptureHook {
   /** 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 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.
+   * 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. */
@@ -367,40 +352,36 @@ declare global {
 //#endregion
 //#region src/chunk.d.ts
 /**
- * Distinct plate names referenced by the tree's stitches, in first-seen order.
- * Walks a `RenderNode` tree (the stored, post-classify shape), so it drives the
- * gen-side stitch import graph straight off a `StoredPlate.tree`
- * (`renderPlateModule`, index.ts). Relocated here from the now-deleted `merge.ts`
- * in the ADR 0022 cutover — it is the one node-side primitive that survived the
- * `mergeViews`/`addCapture` removal (the multi-View merge/gate now lives in the
- * in-browser `serializePlateIR`, project.ts).
+ * Distinct plate names referenced by the tree's stitches, in first-seen order. Walks a `RenderNode`
+ * tree (the stored, post-classify shape), so it drives the gen-side stitch import graph straight
+ * off a `StoredPlate.tree` (`renderPlateModule`, index.ts). The one node-side primitive needed at
+ * build time; multi-View gating happens in the in-browser `serializePlateIR` (serialize.ts, ADR
+ * 0022).
  */
 declare function collectRefs(tree: RenderNode | null): string[];
 //#endregion
 //#region src/name.d.ts
 /**
- * Plate-name validation, shared by the Vite plugin (`index.ts`) and the
- * Node-only POST validator (`validate.ts`).
+ * Plate-name validation, shared by the Vite plugin (`index.ts`) and the Node-only POST validator
+ * (`validate.ts`).
  *
- * Lives in its own dependency-free module so `validate.ts` can reuse it without
- * importing the plugin entry (which would be a cycle), and so the regex stays
- * the single source of truth for what a plate name may be — the same rule the
- * loader, the file watcher, the coverage reader, the POST endpoint, and the
- * ref-graph emitter all gate on.
+ * Lives in its own dependency-free module so `validate.ts` can reuse it without importing the
+ * plugin entry (which would be a cycle), and so the regex stays the single source of truth for what
+ * a plate name may be — the same rule the loader, the file watcher, the coverage reader, the POST
+ * endpoint, and the ref-graph emitter all gate on.
  *
  * @module
  */
 /**
  * Names come from import specifiers and POST bodies — keep them inside the plates dir.
  *
- * Each path segment is `\w+(-\w+)*` — word chars with single interior hyphens,
- * never doubled and never at a segment edge — and segments are joined by `/`.
- * The class-prefix encoder (`classify.ts`) renders `/` as `--` to keep nested
- * names readable, and that prefix is the isolation boundary across stitched
- * plates (ADR 0007), so the encoding must be injective. Banning a literal `--`
- * and any edge hyphen guarantees no `-` ever abuts a `/`, so every `--` in the
- * prefix came from exactly one `/` — making distinct names always map to
- * distinct prefixes (else e.g. `a/-b` and `a-/b` would both encode to `a---b`).
+ * Each path segment is `\w+(-\w+)*` — word chars with single interior hyphens, never doubled and
+ * never at a segment edge — and segments are joined by `/`. The class-prefix encoder
+ * (`classify.ts`) renders `/` as `--` to keep nested names readable, and that prefix is the
+ * isolation boundary across stitched plates (ADR 0007), so the encoding must be injective. Banning
+ * a literal `--` and any edge hyphen guarantees no `-` ever abuts a `/`, so every `--` in the
+ * prefix came from exactly one `/` — making distinct names always map to distinct prefixes (else
+ * e.g. `a/-b` and `a-/b` would both encode to `a---b`).
  *
  * @internal
  */
@@ -411,32 +392,38 @@ declare function isValidPlateName(name: string): boolean;
  * Options for `xrayVitePlugin()`.
  *
  * Fixed conventions are intentionally not configurable: Plate names come from
- * `virtual:xray/plates/<name>`, files live under `platesDir`, and responsive
- * breakpoints are derived from captured CSS plus the `matchMedia` queries the
- * page evaluates.
+ * `virtual:xray/plates/<name>`, files live under `platesDir`, and responsive breakpoints are
+ * derived from captured CSS plus the `matchMedia` queries the page evaluates.
  */
 interface XrayOptions {
-  /** Directory where Plate JSON files are written and read, relative to the Vite root. Default: `plates`. */
+  /**
+   * Directory where Plate JSON files are written and read, relative to the Vite root. Default:
+   * `plates`.
+   */
   platesDir?: string;
   /** Mount the dev HUD for coverage, Capture, Light Box, and capture-all controls. Default: `false`. */
   hud?: boolean;
   /**
-   * Initial state of the browse-time Capture toggle in dev. Keep this off for
-   * normal browsing and let the HUD, capture-all flow, or `?xray-capture` turn
-   * Capture on per tab. Default: `false`.
+   * Initial state of the browse-time Capture toggle in dev. Keep this off for normal browsing and
+   * let the HUD, capture-all flow, or `?xray-capture` turn Capture on per tab. Default: `false`.
    */
   capture?: boolean;
-  /** Settle delay in milliseconds before capturing a ready Skeleton; override one boundary with the `delay` prop. Default: `200`. */
+  /**
+   * Settle delay in milliseconds before capturing a ready Skeleton; override one boundary with the
+   * `delay` prop. Default: `200`.
+   */
   delay?: number;
-  /** Upper bound in milliseconds on waiting for a busy subtree to go quiet before capturing anyway. Default: `5000`. */
+  /**
+   * Upper bound in milliseconds on waiting for a busy subtree to go quiet before capturing anyway.
+   * Default: `5000`.
+   */
   settleCap?: number;
   /**
-   * Collect-stage limits (ADR 0022): refuse to capture a boundary whose measured
-   * tree exceeds any axis — too big means the Skeleton sits too high in the tree.
-   * `maxNodes` caps total surviving nodes (default `4096`), `maxBreadth` the widest
-   * level (default `512`), `maxDepth` the nesting depth (default `32`). Omit
-   * `maxNodes` and it derives as `round(maxBreadth × maxDepth / 4)`. Override one
-   * boundary with the flat `maxNodes`/`maxBreadth`/`maxDepth` `<Skeleton>` props.
+   * Collect-stage limits (ADR 0022): refuse to capture a boundary whose measured tree exceeds any
+   * axis — too big means the Skeleton sits too high in the tree. `maxNodes` caps total surviving
+   * nodes (default `4096`), `maxBreadth` the widest level (default `512`), `maxDepth` the nesting
+   * depth (default `32`). Omit `maxNodes` and it derives as `round(maxBreadth × maxDepth / 4)`.
+   * Override one boundary with the flat `maxNodes`/`maxBreadth`/`maxDepth` `<Skeleton>` props.
    */
   collect?: {
     maxNodes?: number;
@@ -445,31 +432,30 @@ interface XrayOptions {
   };
   /**
    * Dev-only Fixtures (ADR 0015): record a `<Skeleton>`'s render-input `data` to a
-   * `plates/<name>.fixture.json` sidecar and replay it in place of live data so
-   * capture is deterministic. Boot state only — the HUD is per-tab authority, just
-   * like `capture`. Entirely dev-only; nothing here ships in production.
+   * `plates/<name>.fixture.json` sidecar and replay it in place of live data so capture is
+   * deterministic. Boot state only — the HUD is per-tab authority, just like `capture`. Entirely
+   * dev-only; nothing here ships in production.
    */
   fixtures?: {
     /**
-     * When to record the live `data`: `'manual'` (HUD button only — the default,
-     * so live app data is never silently committed), `'first-ready'` (record once
-     * the first time a Skeleton goes ready with no Fixture yet), or `'always'`
-     * (record on every ready render). Default: `'manual'`.
+     * When to record the live `data`: `'manual'` (HUD button only — the default, so live app data
+     * is never silently committed), `'first-ready'` (record once the first time a Skeleton goes
+     * ready with no Fixture yet), or `'always'` (record on every ready render). Default:
+     * `'manual'`.
      */
     record?: 'manual' | 'first-ready' | 'always';
     /**
-     * Whether to replay a recorded Fixture in place of live `data`: `false` (off,
-     * the default), `'prefer'` (always use the Fixture when one exists), or
-     * `'missing-only'` (use the Fixture only when live `data` is nullish —
-     * `missing ≡ nullish`, so an empty array/object is present and stays
-     * capturable). Default: `false`.
+     * Whether to replay a recorded Fixture in place of live `data`: `false` (off, the default),
+     * `'prefer'` (always use the Fixture when one exists), or `'missing-only'` (use the Fixture
+     * only when live `data` is nullish — `missing ≡ nullish`, so an empty array/object is present
+     * and stays capturable). Default: `false`.
      */
     replay?: false | 'prefer' | 'missing-only';
   };
 }
 /**
- * Create the Vite plugins that resolve committed Plates and, during dev,
- * capture new Plates from rendered `<Skeleton>` boundaries.
+ * Create the Vite plugins that resolve committed Plates and, during dev, capture new Plates from
+ * rendered `<Skeleton>` boundaries.
  *
  * Typical setup:
  *
@@ -482,8 +468,10 @@ interface XrayOptions {
  * ```
  *
  * Returns two plugins:
+ *
  * - `xray:data` resolves `virtual:xray/plates/<name>` from committed Plate files in dev and build.
- * - `xray:dev` runs only during `vite serve`; it injects the capture client, receives Captures, writes Plate files, and hot-updates the page.
+ * - `xray:dev` runs only during `vite serve`; it injects the capture client, receives Captures,
+ *   writes Plate files, and hot-updates the page.
  */
 declare function xrayVitePlugin(options?: XrayOptions): Plugin[];
 interface CaptureRequest {
@@ -500,27 +488,37 @@ interface CaptureResponse {
 interface PlateBroadcaster {
   send(payload: unknown): void;
 }
-/** The subset of Vite's logger we use; it preserves the formatted string verbatim. */
+/** The subset of Vite's logger used here; it preserves the formatted string verbatim. */
 interface ServerLogger {
   warn(message: string): void;
 }
 interface CaptureServer {
   ws: PlateBroadcaster;
   /**
-   * Vite's logger (`server.config.logger`). When present its `warn` prints the
-   * diagnostic text to the server output; otherwise we fall back to
-   * `console.warn`. Either way the SAME shared formatter (diagnostics.ts) is
-   * used, so server output matches the browser console exactly.
+   * Vite's logger (`server.config.logger`). When present its `warn` prints the diagnostic text to
+   * the server output; otherwise `console.warn` is the fallback. Either way the SAME shared
+   * formatter (diagnostics.ts) is used, so server output matches the browser console exactly.
    */
   config?: {
     logger?: ServerLogger;
   };
+  /**
+   * The subset of Vite's dev server needed to keep BOTH of a plate's virtual modules fresh after a
+   * plate file changes (capture POST, hand edit, git checkout). Optional — absent in the unit tests
+   * that stub a minimal `server`. `getModuleById`/`invalidateModule`/`reloadModule` mirror
+   * `ViteDevServer`'s real shape (a subset, so this module stays free of a hard `vite` import at
+   * the type level beyond the `Plugin` type already used elsewhere).
+   */
+  moduleGraph?: {
+    getModuleById(id: string): unknown;
+    invalidateModule(mod: unknown): void;
+  };
+  reloadModule?(mod: unknown): Promise<void>;
 }
 /**
- * Per-plate breakpoints + derived coverage bands, read from the committed
- * StoredPlate files. The `spans` derive from each plate's `breakpoints` (ADR 0022
- * cutover — per-View spans no longer exist on disk; a StoredPlate sweeps all
- * widths in one session, so its coverage is complete).
+ * Per-plate breakpoints + derived coverage bands, read from the committed StoredPlate files. The
+ * `spans` derive from each plate's `breakpoints` (ADR 0022: a StoredPlate sweeps all widths in one
+ * session, so its coverage is complete).
  *
  * @internal
  */
@@ -529,54 +527,74 @@ declare function readCoverage(dir: string): Record<string, {
   spans: Span[];
 }>;
 /**
- * All recorded Fixtures as `{ <name>: <devalueString> }`, read from the
- * `<name>.fixture.json` sidecars (ADR 0015). The map values are the OPAQUE
- * devalue strings exactly as written — the node side never parses them; the
- * browser dev client owns the devalue decode. The `.fixture.json` suffix keeps
- * these distinct from Plate files (`isValidPlateName` rejects the dotted name, so
+ * All recorded Fixtures as `{ <name>: <devalueString> }`, read from the `<name>.fixture.json`
+ * sidecars (ADR 0015). The map values are the OPAQUE devalue strings exactly as written — the node
+ * side never parses them; the browser dev client owns the devalue decode. The `.fixture.json`
+ * suffix keeps these distinct from Plate files (`isValidPlateName` rejects the dotted name, so
  * `readCoverage` never picks them up — Fixtures never leak into Plate coverage).
  *
  * @internal
  */
 declare function readFixtures(dir: string): Record<string, string>;
 /**
- * Write a recorded Fixture sidecar (ADR 0015). Reuses the capture endpoint's
- * front-door checks (method, content type, declared/streamed size cap) and the
- * `isValidPlateName` gate, but treats the devalue `data` payload as OPAQUE TEXT:
- * it is validated only as a string and written verbatim, never eval'd or parsed
- * server-side. The sidecar lives NEXT TO the Plate but is never merged into it,
- * so the persisted Plate stays purely structural.
+ * Write a recorded Fixture sidecar (ADR 0015). Reuses the capture endpoint's front-door checks
+ * (method, content type, declared/streamed size cap) and the `isValidPlateName` gate, but treats
+ * the devalue `data` payload as OPAQUE TEXT: it is validated only as a string and written verbatim,
+ * never eval'd or parsed server-side. The sidecar lives NEXT TO the Plate but is never merged into
+ * it, so the persisted Plate stays purely structural.
  *
  * @internal
  */
 declare function handleFixturePost(req: CaptureRequest, res: CaptureResponse, fixturePath: (name: string) => string): void;
 /**
- * Validate a posted `StoredPlate` envelope, write it AS-IS, and hot-swap the
- * plate in place. After the ADR 0022 cutover the dev client posts a finished
- * StoredPlate (the whole Plate already projected in the browser) inside a
- * `{ plate, diagnostics? }` envelope — there is NO server-side accumulation/merge
- * anymore. `diagnostics` is a SIBLING field the server logs and then drops; it
- * never reaches the stored artifact (ADR 0008).
+ * Validate a posted `StoredPlate` envelope, write it AS-IS, and hot-swap the plate in place. The
+ * dev client posts a finished StoredPlate (the whole Plate already projected in the browser, ADR
+ * 0022) inside a `{ plate, diagnostics? }` envelope; there is NO server-side accumulation/merge.
+ * `diagnostics` is a SIBLING field the server logs and then drops; it never reaches the stored
+ * artifact (ADR 0008).
  *
  * @internal
  */
 declare function handleCapturePost(req: CaptureRequest, res: CaptureResponse, server: CaptureServer, platePath: (name: string) => string): void;
 /**
- * Render a plate as the virtual module's source. Each stitch (`ref` node) becomes
- * a real import of that child's virtual module, wired into a `refs` map on the
- * default export — so the bundler builds the actual reference graph and chunks
- * the transitive closure a page uses, with no runtime registry (ADR 0006). A
- * stitchless plate is just its JSON. Self-references are dropped (a module can't
- * import itself); an unknown child resolves to its own empty plate, never a
- * build break.
+ * Render a plate as the virtual module's source. Each stitch (`ref` node) becomes a real import of
+ * that child's virtual module, wired into a `refs` map on the default export — so the bundler
+ * builds the actual reference graph and chunks the transitive closure a page uses, with no runtime
+ * registry (ADR 0006). A stitchless plate is just its JSON. Self-references are dropped (a module
+ * can't import itself); an unknown child resolves to its own empty plate, never a build break.
+ *
+ * `name` defaults to the plate's own `name`, but the loader passes the PATH-derived name so a
+ * hand-edited StoredPlate whose `name` field drifted from its filename still serializes and
+ * self-references under the canonical name (`collectRefs` reads `stored.tree`, a RenderNode).
+ *
+ * Two-artifact module shape (ADR 0026):
+ *
+ * ```js
+ * import "virtual:xray/base.css"
+ * import "virtual:xray/plates/<name>.css"
+ * export default { tree-only plate JSON }
+ * export const css = "<the plate's scoped css string>"
+ * ```
+ *
+ * The default export is the TREE artifact (`Plate` carries no css field); the page's styling flows
+ * through Vite's own CSS pipeline via the two side-effect imports (dev inject + HMR, build
+ * extraction into the chunk's `.css` asset). `export const css` is the plate's css as data, for dev
+ * tooling / programmatic consumers that want the string itself — production adapters import only
+ * the default, so Rollup TREE-SHAKES the unused named export out of built chunks (verified
+ * empirically; the side-effect css imports do not pin it).
  *
- * `name` defaults to the plate's own `name`, but the loader passes the
- * PATH-derived name so a hand-edited StoredPlate whose `name` field drifted from
- * its filename still serializes and self-references under the canonical name
- * (`collectRefs` reads `stored.tree`, a RenderNode, unchanged by the cutover).
+ * BASE_CSS rides as a JS-level import of the SHARED `virtual:xray/base.css` module (not an
+ * `@import` inside each plate's css): Vite dedupes JS module imports by id, so the base rules reach
+ * the page exactly once no matter how many plates (nested/stitched included — every plate module
+ * emits this import, module identity collapses them) a page mounts, and at build a multi-chunk app
+ * gets it hoisted/shared rather than copied per chunk. An `@import` inside each plate's `.css`
+ * would instead be INLINED per importer by Vite's postcss-import at build, duplicating BASE_CSS
+ * into every plate's asset — the opposite of the dedupe this design locks in. Base rides before the
+ * plate's css module so a plate rule still beats a base rule at equal specificity by source order
+ * (the `${BASE_CSS}\n${css}` composition order).
  *
  * @internal
  */
-declare function renderPlateModule(merged: MergedPlate, name?: string): string;
+declare function renderPlateModule(merged: GatedPlate, name?: string): string;
 //#endregion
 export { type LeafKind, type Plate, type PlateNode, type PlateRule, type StoredPlate, type ViewCapture, XrayOptions, collectRefs, handleCapturePost, handleFixturePost, isValidPlateName, readCoverage, readFixtures, renderPlateModule, xrayVitePlugin };