@hueest/xray 0.1.0 → 0.2.0

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { a as PlateNode, c as emptyPlate, i as PlateFile, n as MergedPlate, o as RenderNode, r as Plate, s as ViewCapture, t as LeafKind } from "./plate-DboxMKg-.js";
-import { CaptureOptions, CaptureRegimeOptions, CaptureTooLargeError, capture, captureRegime } from "./serialize.js";
+import { a as PlateNode, c as emptyPlate, i as PlateFile, n as MergedPlate, o as RenderNode, r as Plate, s as ViewCapture, t as LeafKind } from "./plate-Bv6W-GkA.js";
+import { a as WalkerResult, c as captureRegime, i as CaptureWalkerContext, l as defineXrayCaptureWalker, n as CaptureRegimeOptions, o as XrayCaptureWalker, r as CaptureTooLargeError, s as capture, t as CaptureOptions } from "./serialize-B--oY2bV.js";
 
 //#region src/chunk.d.ts
 /**
@@ -39,6 +39,11 @@ declare function addCapture(file: PlateFile | null, name: string, capture: ViewC
  * Capture a live DOM subtree straight to a renderable Plate — `capture` followed
  * by `serializePlate` in one call. `roots` are the top-level elements to capture
  * (a component's rendered roots). Pass the result to a `<Skeleton plate>`.
+ *
+ * `options.walker` is the public programmable capture walker (ADR 0018, Q2 —
+ * yes, public): the same `XrayCaptureWalker` the `<Skeleton captureWalker>` prop
+ * threads through in dev, available here for driving capture directly. It is
+ * capture-only and never persisted into the returned Plate.
  */
 declare function captureElement(roots: readonly Element[], options: CaptureOptions): Plate;
 /**
@@ -52,4 +57,4 @@ declare function captureElement(roots: readonly Element[], options: CaptureOptio
  */
 declare function renderPlateHtml(plate: Plate): string;
 //#endregion
-export { type CaptureOptions, type CaptureRegimeOptions, CaptureTooLargeError, type LeafKind, type MergedPlate, type Plate, type PlateFile, type PlateNode, type ViewCapture, addCapture, capture, captureElement, captureRegime, collectRefs, emptyPlate, mergeViews, renderPlateHtml, serializePlate };
+export { type CaptureOptions, type CaptureRegimeOptions, CaptureTooLargeError, type CaptureWalkerContext, type LeafKind, type MergedPlate, type Plate, type PlateFile, type PlateNode, type ViewCapture, type WalkerResult, type XrayCaptureWalker, addCapture, capture, captureElement, captureRegime, collectRefs, defineXrayCaptureWalker, emptyPlate, mergeViews, renderPlateHtml, serializePlate };

package/dist/core.js

@@ -1,6 +1,6 @@
-import { a as ROOT_ATTR, i as NODE_CLASS, o as ROOT_CLASS, r as LEAF_CLASS, s as SPEC_GATE, t as BASE_CSS, u as emptyPlate } from "./plate-BuzRMPx4.js";
-import { i as captureRegime, o as classify, r as capture, t as CaptureTooLargeError } from "./serialize-Bq6yJnNV.js";
-import { n as regimeFor } from "./breakpoints-CBNlh7lQ.js";
+import { a as ROOT_ATTR, c as SPEC_GATE, d as emptyPlate, i as NODE_CLASS, o as ROOT_CLASS, r as LEAF_CLASS, t as BASE_CSS } from "./plate-DoE1HEXp.js";
+import { a as captureRegime, i as capture, n as regimeFor, o as defineXrayCaptureWalker, r as CaptureTooLargeError, u as classify } from "./breakpoints-CMoFUUOv.js";
+import { t as escapeStyleText } from "./css-escape-N7bOusGW.js";
 //#region src/chunk.ts
 /**
 * Serialize a merged plate's RenderNode tree into the shipped `Plate` (ADR
@@ -190,7 +190,8 @@ function remapRules(rules, idMap) {
 function addCapture(file, name, capture, breakpoints) {
 	const allBreakpoints = [...new Set([...file?.breakpoints ?? [], ...breakpoints])].toSorted((a, b) => a - b);
 	const spanKey = (width) => JSON.stringify(regimeFor(width, allBreakpoints));
-	const views = [...file?.views ?? [], capture];
+	const { diagnostics: _diagnostics, ...persisted } = capture;
+	const views = [...file?.views ?? [], persisted];
 	const byView = /* @__PURE__ */ new Map();
 	for (const view of views) byView.set(spanKey(view.width), view);
 	return {
@@ -206,6 +207,11 @@ function addCapture(file, name, capture, breakpoints) {
 * Capture a live DOM subtree straight to a renderable Plate — `capture` followed
 * by `serializePlate` in one call. `roots` are the top-level elements to capture
 * (a component's rendered roots). Pass the result to a `<Skeleton plate>`.
+*
+* `options.walker` is the public programmable capture walker (ADR 0018, Q2 —
+* yes, public): the same `XrayCaptureWalker` the `<Skeleton captureWalker>` prop
+* threads through in dev, available here for driving capture directly. It is
+* capture-only and never persisted into the returned Plate.
 */
 function captureElement(roots, options) {
 	return serializePlate(capture(roots, options));
@@ -224,7 +230,7 @@ function renderPlateHtml(plate) {
 	if (!chunks) return "";
 	if (chunks.length !== 1 || typeof chunks[0] !== "string") throw new Error("xray: renderPlateHtml renders stitch-free plates only — use a framework adapter for stitched plates");
 	const className = plate.rootCls ? `${ROOT_CLASS} ${plate.rootCls}` : ROOT_CLASS;
-	return `<div ${ROOT_ATTR}="${plate.name}" class="${className}" aria-hidden="true" aria-busy="true"><style>${BASE_CSS}\n${plate.css}</style>${chunks[0]}</div>`;
+	return `<div ${ROOT_ATTR}="${plate.name}" class="${className}" aria-hidden="true" aria-busy="true"><style>${BASE_CSS}\n${escapeStyleText(plate.css)}</style>${chunks[0]}</div>`;
 }
 //#endregion
-export { CaptureTooLargeError, addCapture, capture, captureElement, captureRegime, collectRefs, emptyPlate, mergeViews, renderPlateHtml, serializePlate };
+export { CaptureTooLargeError, addCapture, capture, captureElement, captureRegime, collectRefs, defineXrayCaptureWalker, emptyPlate, mergeViews, renderPlateHtml, serializePlate };

package/dist/css-escape-N7bOusGW.js

@@ -0,0 +1,52 @@
+//#region src/css-escape.ts
+/**
+* Dependency-free raw-text safety for the one place a Plate's CSS string is
+* interpolated into `<style>…</style>` markup.
+*
+* A plate's `css` is normally produced by the capture path (`filterLayoutDecls`
+* + `classify`), which only ever emits well-formed `selector { prop: value }`
+* rules — never a raw-text terminator. But a committed `plates/<name>.json` is
+* UNTRUSTED at render time (it can be hand-edited or arrive over git, see the
+* capture-input-validation plan's decisions), and a corrupt/malicious `css`
+* could carry a `</style>` or an HTML comment delimiter. `<style>` is a
+* raw-text element: the parser ends the element at the first `</style` it sees
+* and resumes parsing the rest as ordinary HTML, so an unescaped terminator in
+* the CSS body turns the tail of the plate into live markup.
+*
+* The React text-child path (`<style>{css}</style>`) is already safe — React
+* escapes the child — but the two STRING paths interpolate `css` directly into
+* a markup string (`renderPlateHtml` builds an HTML string; `react.core.tsx`
+* feeds one to `dangerouslySetInnerHTML`). Those must run the body through this
+* helper first.
+*
+* This lives in its own dependency-free module ON PURPOSE: it is imported by
+* render/browser paths, so it must NOT pull in the Node-only validation code
+* (valibot). It neutralizes only the sequences that can escape a raw-text
+* `<style>` context — a `<` that begins `</style`, and the HTML comment / CDATA
+* delimiters the tokenizer treats specially inside raw text — by inserting a
+* CSS-comment break (`/​**​/`) that the CSS parser ignores. It does not, and is
+* not meant to, sanitize CSS semantically; POST-time validation
+* (`validate.ts`) is what rejects junk declarations.
+*
+* @module
+*/
+/**
+* Make a CSS body safe to interpolate into a `<style>…</style>` STRING. Breaks
+* up the only sequences the HTML tokenizer acts on inside a raw-text `<style>`
+* element, so none can terminate the element early or open a comment/CDATA run:
+*
+*  - `</style` (the end-tag open, case-insensitive) — inserts the break between
+*    `<` and `/style` so the parser never matches the end tag.
+*  - `<!--`, `-->`, `<![CDATA[` — the comment/CDATA delimiters; split so neither
+*    a comment nor a CDATA section can open.
+*
+* The inserted `/​**​/` is an empty CSS comment: inert to the CSS parser (it
+* cannot appear mid-token in a value we emit, and a stray one only ends a
+* token early), so a well-formed plate is rendered byte-for-byte equivalently
+* while a corrupt one can no longer break out of the style element.
+*/
+function escapeStyleText(css) {
+	return css.replace(/<(\/style)/gi, "</**/$1").replace(/<!--/g, "<!/**/--").replace(/-->/g, "--/**/>").replace(/<!\[CDATA\[/g, "<![/**/CDATA[");
+}
+//#endregion
+export { escapeStyleText as t };

package/dist/hud.js

@@ -52,6 +52,7 @@ function installXrayHud() {
     .bands { text-align: right }
     .band.covered { color: #4ade80 }
     .band.missing { color: #52525b }
+    .fixture { color: #fbbf24; margin-left: 6px }
     .toggle { display: flex; gap: 6px; align-items: center; cursor: pointer; user-select: none }
     .toggle input { accent-color: #4ade80; margin: 0 }
     .action {
@@ -70,6 +71,8 @@ function installXrayHud() {
 	let extensionPresent = false;
 	let sweeping = false;
 	let sweepStatus = "";
+	let recording = false;
+	let recordStatus = "";
 	const render = () => {
 		panel.textContent = "";
 		const coverage = globalThis.__XRAY__?.coverage?.get();
@@ -82,6 +85,26 @@ function installXrayHud() {
 		if (capture) panel.append(toggleRow(capture, "Capture"));
 		const lightbox = globalThis.__XRAY__?.lightbox;
 		if (lightbox) panel.append(toggleRow(lightbox, "Light Box"));
+		const replay = globalThis.__XRAY__?.replay;
+		if (replay) panel.append(toggleRow(replay, "Replay"));
+		const fixtures = globalThis.__XRAY__?.fixtures;
+		if (fixtures) {
+			const button = document.createElement("button");
+			button.className = "action";
+			button.type = "button";
+			button.disabled = recording;
+			button.textContent = recording ? "Recording fixture…" : "Record fixture";
+			button.addEventListener("click", () => {
+				recordFixtures(fixtures);
+			});
+			panel.append(button);
+			if (recordStatus) {
+				const status = document.createElement("div");
+				status.className = "status";
+				status.textContent = recordStatus;
+				panel.append(status);
+			}
+		}
 		if (globalThis.__XRAY__?.captureAllViews) if (extensionPresent) {
 			const button = document.createElement("button");
 			button.className = "action";
@@ -109,6 +132,12 @@ function installXrayHud() {
 			row.className = "plate";
 			const label = document.createElement("span");
 			label.textContent = name;
+			if (globalThis.__XRAY__?.fixtures?.has(name)) {
+				const tag = document.createElement("span");
+				tag.className = "fixture";
+				tag.textContent = "◆ fixture";
+				label.append(tag);
+			}
 			const bands = document.createElement("span");
 			bands.className = "bands";
 			for (const band of bandsOf(plateCoverage)) {
@@ -136,6 +165,21 @@ function installXrayHud() {
 			render();
 		}
 	}
+	async function recordFixtures(fixtures) {
+		if (recording || !fixtures) return;
+		recording = true;
+		recordStatus = "";
+		render();
+		try {
+			await fixtures.recordAll();
+			recordStatus = "Fixture recorded.";
+		} catch (error) {
+			recordStatus = `Failed: ${error instanceof Error ? error.message : String(error)}`;
+		} finally {
+			recording = false;
+			render();
+		}
+	}
 	const onHudMessage = (event) => {
 		if (event.source !== window) return;
 		if (isExtensionHello(event.data) && !extensionPresent) {
@@ -149,6 +193,7 @@ function installXrayHud() {
 		kind: "whois"
 	}, "*");
 	const unsubscribeCoverage = globalThis.__XRAY__?.coverage?.subscribe(render);
+	const unsubscribeFixtures = globalThis.__XRAY__?.fixtures?.subscribe(render);
 	render();
 	const mount = () => {
 		if (document.body) document.body.append(host);
@@ -158,6 +203,7 @@ function installXrayHud() {
 	return { dispose() {
 		window.removeEventListener("message", onHudMessage);
 		unsubscribeCoverage?.();
+		unsubscribeFixtures?.();
 		host.remove();
 	} };
 }

package/dist/index.d.ts

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