@hueest/xray 0.1.0 → 0.3.0

package/dist/client.d.ts

@@ -1,19 +1,29 @@
-import { s as ViewCapture } from "./plate-DboxMKg-.js";
+import { l as CaptureDiagnostic, o as StoredPlate } from "./plate-BIr62u7l.js";
 
 //#region src/client.d.ts
 /**
  * The dev capture client (M2). Runs in the browser during dev only: installs
- * the `__XRAY__` hook `<Skeleton>` calls when content becomes ready,
- * settles, serializes the subtree into a view capture, and hands it to the
- * sink (the plugin's POST endpoint in M3). Re-captures when the viewport
+ * the `__XRAY__` hook `<Skeleton>` calls when content becomes ready, settles,
+ * measures the subtree into a per-Plate `PlateIR`, projects it to the structured
+ * `StoredPlate` in the browser (the ADR 0022 in-browser Serialize), and hands the
+ * envelope to the sink (the plugin's POST endpoint). Re-captures when the viewport
  * crosses into another view while a site is still mounted.
+ *
+ * Two paths produce a Plate. BROWSE-TIME is a RECORDING SESSION (the Capture toggle):
+ * while on, each capture accumulates a View into a name-keyed `PlateIR` buffer
+ * (deduped per breakpoint band) and live-previews it in-memory; toggling off writes
+ * each accumulated Plate to the sink ONCE. The capture-all SWEEP threads ONE `PlateIR`
+ * through every emulated width (one View each) and posts the projected StoredPlate once.
  */
-interface CapturePayload {
-  name: string;
-  /** This capture, view interval already derived. */
-  capture: ViewCapture;
-  /** Width thresholds derived for this plate (rules' @media + matchMedia queries). */
-  breakpoints: number[];
+/**
+ * The `/__xray` POST envelope (ADR 0022 cutover). `plate` is the finished,
+ * in-browser-projected `StoredPlate` written to disk as-is; `diagnostics` is a
+ * SIBLING dev-only field the server logs and drops — it NEVER reaches the stored
+ * artifact (ADR 0008).
+ */
+interface CaptureEnvelope {
+  plate: StoredPlate;
+  diagnostics?: CaptureDiagnostic[];
 }
 interface ClientOptions {
   /** Settle delay (ms) once the subtree goes quiet. Default 200. */
@@ -29,14 +39,52 @@ interface ClientOptions {
    */
   maxNodes?: number;
   /**
-   * Initial state of the capture toggle: whether browsing re-captures plates.
-   * A per-tab override (sessionStorage / `?xray-capture`) wins over it.
-   * Defaults to `true` — the plugin passes its own (off-by-default) policy.
+   * Initial state of the capture toggle: whether the recording session is active
+   * at boot. A per-tab override (sessionStorage / `?xray-capture`) wins over it.
+   * Defaults to `false` — recording is explicit opt-in (turn it on, browse/resize to
+   * accumulate Views, turn it off to write), so normal browsing never accumulates and
+   * an HMR/close can't drop an unsaved recording. The plugin passes the same
+   * off-by-default policy; a direct caller can pass `true` to capture on boot.
    */
   capture?: boolean;
-  /** Where finished captures go. */
-  sink: (payload: CapturePayload) => void;
+  /**
+   * Where finished captures go. May be synchronous (fire-and-forget) or return
+   * a promise that resolves once the write is server-confirmed. Browse-time
+   * capture ignores the return value; the capture-all sweep awaits it so it
+   * does not advance to the next emulated width until the current writes have
+   * been accepted by the dev server (backpressure — capture-all-backpressure plan).
+   */
+  sink: (envelope: CaptureEnvelope) => void | Promise<void>;
+  /**
+   * Re-pull the on-disk per-plate coverage and feed it into the coverage store.
+   * The capture-all sweep calls this after each pass so the next `sweepWidths()`
+   * sees the breakpoints just written by that pass, rather than racing the
+   * async `xray:plate` HMR event (coverage freshness — capture-all-backpressure
+   * plan). Optional: browse-time capture never needs it, and the unit tests
+   * drive coverage directly through the store.
+   */
+  refreshCoverage?: () => void | Promise<void>;
+  /**
+   * Fixtures boot state (ADR 0015). `record` is when to write the live `data` to a
+   * sidecar (`'manual'` — HUD button only, the default; `'first-ready'`; or
+   * `'always'`); `replay` is whether to substitute a recorded Fixture for live
+   * `data` (`false`, `'prefer'`, or `'missing-only'`). The HUD overrides the
+   * replay toggle per tab. Absent ≡ defaults (`'manual'` / `false`).
+   */
+  record?: 'manual' | 'first-ready' | 'always';
+  replay?: false | 'prefer' | 'missing-only';
+  /**
+   * Where a recorded Fixture's OPAQUE devalue string is POSTed (the sidecar write
+   * endpoint). The client owns the devalue stringify; this only ships the bytes.
+   * Resolves once the write is server-confirmed, rejects on a non-2xx so the HUD
+   * Record button can surface a failed write. Absent ≡ Record is a no-op (the
+   * unit tests inject their own).
+   */
+  recordFixtureSink?: (payload: {
+    name: string;
+    data: string;
+  }) => void | Promise<void>;
 }
 declare function installXrayClient(options: ClientOptions): () => void;
 //#endregion
-export { CapturePayload, ClientOptions, installXrayClient };
+export { CaptureEnvelope, ClientOptions, installXrayClient };