@hueest/xray 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,7 +1,55 @@
 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.
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * 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' | 'dropped-subset' | 'dropped-cropped' | 'too-large' | 'invalid-plate-file';
+//#endregion
 //#region src/plate.d.ts
-type LeafKind = 'text' | 'media' | 'box';
+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
@@ -35,21 +83,27 @@ interface 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 }`),
- * or a stitch-bearing element kept real so its inner stitches can mount
- * (`{ c: className, k: chunk[] }`). The framework-neutral render contract: an
- * adapter injects the strings and mounts a child plate at each stitch (ADR 0008).
+ * 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).
  */
 type Chunk = string | {
   r: string;
 } | {
   c: string;
   k: Chunk[];
+} | {
+  t: string;
+  n: number;
 };
 /**
- * A plate after view-merge + classify but before chunk serialization: the
- * build-time RenderNode tree plus its scoped CSS. Produced by `mergeViews` and
- * `capture`, then serialized into the shipped `Plate` (chunks) at load
- * (`serializePlate`). Never shipped to the client.
+ * 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.
  */
 interface MergedPlate {
   v: number;
@@ -68,6 +122,12 @@ interface PlateNode {
    * 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.
+   */
+  count?: number;
   kids?: PlateNode[];
 }
 /**
@@ -80,6 +140,8 @@ interface RenderNode {
   leaf?: LeafKind;
   ref?: string;
   cls?: string;
+  /** A templated uniform run (Phase 2): serialize this subtree once + a count the adapter repeats. */
+  count?: number;
   kids?: RenderNode[];
 }
 /**
@@ -100,8 +162,11 @@ interface PlateRule {
 }
 /**
  * One capture of a component within one viewport view — `[min, max)` in px,
- * either side open-ended when undefined. What the dev client ships to the
- * plugin, and what the plate file accumulates (ADR 0004).
+ * 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.
  */
 interface ViewCapture {
   /** Viewport width at capture time. */
@@ -110,14 +175,33 @@ interface ViewCapture {
   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`: per-view captures, merged at load. */
-interface PlateFile {
-  v: number;
-  name: string;
-  /** Width thresholds (view boundaries) derived so far. */
+/**
+ * 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.
+ */
+interface StoredPlate extends MergedPlate {
+  /** Width thresholds (view boundaries); the HUD coverage derives its bands from these. */
   breakpoints: number[];
-  views: ViewCapture[];
 }
 /**
  * A dev-only sticky boolean toggle (get/set/subscribe), persisted per tab.
@@ -151,6 +235,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 +321,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;
@@ -182,40 +330,76 @@ interface CaptureHook {
   capture?: ToggleStore;
   /** Read side for `<Skeleton>`. */
   plates?: PlateStore;
-  /** Write side for the dev client's HMR-event handler. */
-  updatePlate?: (name: string, plate: Plate) => void;
+  /** 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/merge.d.ts
+//#region src/chunk.d.ts
 /**
- * Turn the per-view captures in a plate file into the one plate a Skeleton
- * renders.
+ * 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).
+ */
+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`).
  *
- * Each view is kept whole — its own subtree, its own ids, its own rules —
- * and shown only across the viewport range it owns, via `@media display:none`
- * gates. We do NOT merge the views' trees into one. An earlier design (ADR
- * 0004) did, sharing common structure and forking the rest, but aligning two
- * genuinely-different DOM trees (mobile stacked vs desktop two-column) without
- * stable keys proved unreliable: every heuristic mis-paired some nodes and
- * remapped one view's rules onto another's elements, corrupting both. A lone
- * capture is pixel-faithful; keeping each view lone preserves that. The cost
- * is a larger plate (roughly the sum of the views) — bounded by the plate
- * size cap — in exchange for correctness.
+ * 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.
  *
- * Pure data-in/data-out — runs in node (plugin load) and in tests.
+ * @module
  */
-declare function mergeViews(file: PlateFile): MergedPlate;
-/** Distinct plate names referenced by the tree's stitches, in first-seen order. */
-declare function collectRefs(tree: RenderNode | null): string[];
-/** Fold a fresh capture into the plate file: union breakpoints, one capture per view. */
-declare function addCapture(file: PlateFile | null, name: string, capture: ViewCapture, breakpoints: readonly number[]): PlateFile;
+/**
+ * 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`).
+ *
+ * @internal
+ */
+declare function isValidPlateName(name: string): boolean;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -243,6 +427,29 @@ interface XrayOptions {
   settleCap?: number;
   /** Refuse captures larger than this many nodes (Skeleton too high in the tree). Default: `4000`. */
   maxNodes?: number;
+  /**
+   * 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.
+   */
+  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'`.
+     */
+    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`.
+     */
+    replay?: false | 'prefer' | 'missing-only';
+  };
 }
 /**
  * Create the Vite plugins that resolve committed Plates and, during dev,
@@ -265,7 +472,10 @@ interface XrayOptions {
 declare function xrayVitePlugin(options?: XrayOptions): Plugin[];
 interface CaptureRequest {
   method?: string;
+  headers?: Record<string, string | string[] | undefined>;
   on(event: 'data' | 'end', listener: (chunk?: Buffer | string) => void): unknown;
+  /** Stop buffering the request body once the byte cap is exceeded. */
+  destroy?: () => void;
 }
 interface CaptureResponse {
   statusCode: number;
@@ -274,33 +484,67 @@ interface CaptureResponse {
 interface PlateBroadcaster {
   send(payload: unknown): void;
 }
+/** The subset of Vite's logger we use; 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.
+   */
+  config?: {
+    logger?: ServerLogger;
+  };
 }
 /**
- * Per-plate breakpoints + captured spans, read from the committed plate files.
+ * 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).
  *
  * @internal
  */
 declare function readCoverage(dir: string): Record<string, {
   breakpoints: number[];
-  spans: {
-    min?: number;
-    max?: number;
-  }[];
+  spans: Span[];
 }>;
 /**
- * Fold a posted capture into its plate file and hot-swap the plate in place.
+ * 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 handleCapturePost(req: CaptureRequest, res: CaptureResponse, server: CaptureServer, platePath: (name: string) => string): void;
+declare function readFixtures(dir: string): Record<string, string>;
 /**
- * Names come from import specifiers and POST bodies — keep them inside the plates dir.
+ * 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 isValidPlateName(name: string): boolean;
+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).
+ *
+ * @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
@@ -310,8 +554,13 @@ declare function isValidPlateName(name: string): boolean;
  * 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, unchanged by the cutover).
+ *
  * @internal
  */
-declare function renderPlateModule(merged: MergedPlate): string;
+declare function renderPlateModule(merged: MergedPlate, name?: string): string;
 //#endregion
-export { type LeafKind, type Plate, type PlateFile, type PlateNode, type PlateRule, type ViewCapture, XrayOptions, addCapture, collectRefs, handleCapturePost, isValidPlateName, mergeViews, readCoverage, renderPlateModule, xrayVitePlugin };
+export { type LeafKind, type Plate, type PlateNode, type PlateRule, type StoredPlate, type ViewCapture, XrayOptions, collectRefs, handleCapturePost, handleFixturePost, isValidPlateName, readCoverage, readFixtures, renderPlateModule, xrayVitePlugin };