@hueest/xray 0.5.0 → 0.7.0

package/dist/serialize-BgdGt34A.d.ts

@@ -1,501 +0,0 @@
-//#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' | '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).
- */
-interface Plate {
-  v: number;
-  /** Capture name; comes from the virtual-module specifier, never typed at a call site. */
-  name: string;
-  /**
-   * The root's children, pre-serialized (ADR 0008): a stitch-free run is one
-   * HTML `string`; a stitch is `{ r: name }`; a stitch-bearing element is
-   * `{ c: className, k: chunk[] }`. Null until first capture.
-   */
-  chunks: Chunk[] | null;
-  /** The root node's own content classes (its inherited font context), if any. */
-  rootCls?: string;
-  /** 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.
-   */
-  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).
- */
-type Chunk = string | {
-  r: string;
-} | {
-  c: string;
-  k: Chunk[];
-} | {
-  t: 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.
- */
-interface MergedPlate {
-  v: number;
-  name: string;
-  tree: RenderNode | null;
-  css: string;
-}
-interface PlateNode {
-  /** Plate-local id; rules reference it pre-classify. Stripped from the shipped tree. */
-  id: number;
-  /** Present on paint leaves; absent on layout containers. */
-  leaf?: LeafKind;
-  /**
-   * A stitch: render the named child plate's skeleton here instead of own
-   * structure (ADR 0006). Mutually exclusive with `leaf`/`kids`. Resolved
-   * against `Plate.refs` (prod) or the live store (dev).
-   */
-  ref?: string;
-  /**
-   * A templated uniform run (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[];
-}
-/**
- * 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.
- */
-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[];
-}
-/**
- * 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.
- */
-interface PlateRule {
-  ids: number[];
-  decls: string[];
-  /** Media-condition stack, outermost first; conditions AND together. */
-  media?: string[];
-  /** `@container`-condition stack, outermost first; conditions AND together. Absent when none. */
-  container?: string[];
-  layered?: boolean;
-  spec: number;
-  order: number;
-}
-/**
- * One capture of a component within one viewport view — `[min, max)` in px,
- * either side open-ended when undefined. The id-form `{ tree, rules }` shape
- * `emit` projects a measured View into (ADR 0004). 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. */
-  width: number;
-  min?: number;
-  max?: number;
-  tree: PlateNode;
-  rules: PlateRule[];
-  /**
-   * TRANSIENT, dev-only capture diagnostics (why this view may be lower
-   * fidelity). Captured in the browser (mirrored onto `ViewIR.diagnostics`); the
-   * dev client logs it and posts it alongside the `StoredPlate` (so the Vite
-   * server can print the same text). It MUST NEVER be persisted: it is not part
-   * of the committed
-   * `StoredPlate` disk shape, the validator does not carry it, and the POST
-   * envelope keeps it in a SIBLING field that never reaches the stored artifact
-   * (ADR 0008). Absent in production (the prod adapter ships no capture). See
-   * diagnostics.ts and ADR 0008.
-   */
-  diagnostics?: CaptureDiagnostic[];
-}
-/**
- * The committed `plates/<name>.json` shape 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[];
-}
-/** The (unserialized) plate an import resolves to before anything has been captured. */
-declare function emptyPlate(name: string): MergedPlate;
-/**
- * A dev-only sticky boolean toggle (get/set/subscribe), persisted per tab.
- * Used for both "light box" (render every `<Skeleton>` regardless of readiness)
- * and "capture" (whether browsing re-captures plates).
- */
-interface ToggleStore {
-  get: () => boolean;
-  set: (value: boolean) => void;
-  subscribe: (onChange: () => void) => () => void;
-}
-/**
- * Dev-only store of the freshest plate per name, updated in place when a
- * capture lands. `<Skeleton>` reads through it so a new plate re-renders the
- * site rather than reloading the module — which would remount the capture
- * boundary and re-fire the capture, a feedback loop.
- */
-interface PlateStore {
-  get: (name: string) => Plate | undefined;
-  subscribe: (name: string, onChange: () => void) => () => void;
-  /**
-   * Register a plate imported via the ref graph if the store has none yet — so a
-   * stitch resolves even before its child is re-captured, and survives a parent
-   * hot-swap (whose pushed plate carries no resolved `refs`). Never overwrites a
-   * live capture.
-   */
-  seed: (name: string, plate: Plate) => void;
-}
-/** A view interval `[min, max)`; an open end is undefined (ADR 0004). */
-interface Span {
-  min?: number;
-  max?: number;
-}
-/**
- * Dev-only Fixture store (ADR 0015): stored render-INPUT `data` per Plate,
- * recorded to and replayed from a `plates/<name>.fixture.json` sidecar. Entirely
- * dev-only — devalue and this store never reach the production bundle.
- *
- * Two cooperating halves, both flowing through the render-prop `data` seam (ADR
- * 0014):
- * - The dev adapter (`react.dev.tsx`) calls `register(name, data)` at
- *   `loading=false` with the live `data` it is about to render, so the latest
- *   recordable input for each mounted Plate is always in scope for Record.
- * - `record(name)` serializes that registered live `data` with devalue and POSTs
- *   it to the sidecar (the HUD button and the `first-ready`/`always` modes call
- *   it). `has(name)` reports whether a Fixture exists (HUD coverage marker), and
- *   `read(name)` returns the parsed Fixture `data` for Replay to substitute in
- *   front of the render prop.
- *
- * The store holds DECODED values (the dev client owns the devalue parse, since it
- * has the live runtime); only the on-disk sidecar and the wire carry the opaque
- * devalue string.
- */
-interface FixtureStore {
-  /**
-   * Record the latest live `data` the dev adapter is about to render for `name`,
-   * so Record always has the current recordable input in scope. A `register` with
-   * the same value is cheap; the adapter calls it on every ready render. Returns a
-   * disposer the adapter runs on unmount so an unmounted Skeleton's `data` never
-   * lingers in the store: an unmounted instance must never be recorded or shadow a
-   * still-mounted one (ADR 0015). With several Skeletons of the same plate name
-   * mounted, the live value is the most-recently-registered still-mounted instance.
-   */
-  register: (name: string, data: unknown) => () => void;
-  /** True once a recorded Fixture exists for `name` (drives the HUD coverage marker). */
-  has: (name: string) => boolean;
-  /** The parsed Fixture `data` for `name`, or `undefined` when none is recorded. */
-  read: (name: string) => {
-    data: unknown;
-  } | undefined;
-  /**
-   * Serialize the registered live `data` for `name` with devalue and POST it to
-   * the sidecar. Returns a promise that resolves once the write is
-   * server-confirmed (so the HUD can surface a failed Record). Throws loudly when
-   * the live `data` is unrecordable (devalue's contract) or no live `data` was
-   * registered (a plain-children `<Skeleton>` has none).
-   */
-  record: (name: string) => Promise<void>;
-  /**
-   * Record every Skeleton that currently has live `data` registered (the HUD's
-   * single "Record fixture" button — one click captures the inputs of all mounted
-   * render-prop Skeletons). Resolves once all writes are server-confirmed; a
-   * rejected write surfaces to the HUD.
-   */
-  recordAll: () => Promise<void>;
-  /**
-   * Seed the store from the on-disk sidecars on boot: a `{ <name>: devalueString }`
-   * map (the opaque strings the server serves). The client decodes each with
-   * devalue. Existing entries are not clobbered, so a Fixture recorded this
-   * session survives a re-seed.
-   */
-  seed: (encoded: Record<string, string>) => void;
-  /** React subscription so the HUD re-renders when a Fixture is recorded or seeded. */
-  subscribe: (onChange: () => void) => () => void;
-}
-/** A plate's detected width thresholds and the spans actually captured, from disk. */
-interface PlateCoverage {
-  breakpoints: number[];
-  spans: Span[];
-}
-/**
- * Dev-only per-plate coverage, sourced from the committed plate files (not the
- * session): the breakpoints detected so far and which view spans are captured.
- * The HUD renders every band — covered ones lit, the rest dim — and the
- * capture-all sweep derives its target widths from the breakpoints.
- */
-interface CoverageStore {
-  get: () => ReadonlyMap<string, PlateCoverage>;
-  set: (name: string, coverage: PlateCoverage) => void;
-  subscribe: (onChange: () => void) => () => void;
-}
-/**
- * Dev-only capture hook, installed by the dev client before the app boots.
- * Absent in production builds, so `<Skeleton>` carries zero capture weight.
- * `captured` returns a dispose callback (stop observing this site).
- */
-interface CaptureHook {
-  captured: (name: string, el: Element, opts?: {
-    delay?: number;
-    walker?: unknown;
-    mode?: 'auto' | 'manual';
-    collect?: {
-      maxNodes?: number;
-      maxBreadth?: number;
-      maxDepth?: number;
-    };
-  }) => (() => void) | undefined;
-  /** Light Box toggle: force every `<Skeleton>` to its skeleton, read by `<Skeleton>`. */
-  lightbox?: ToggleStore;
-  /** Capture toggle: whether browsing re-captures plates, flipped from the HUD. */
-  capture?: ToggleStore;
-  /** Read side for `<Skeleton>`. */
-  plates?: PlateStore;
-  /** Write side for the dev client's HMR-event handler. Returns whether the plate changed. */
-  updatePlate?: (name: string, plate: Plate) => boolean;
-  /** Dev-only: run the HUD-triggered capture-all-views sweep via the extension (ADR 0010). */
-  captureAllViews?: () => Promise<void>;
-  /** Dev-only per-plate breakpoints + captured spans, from disk; fed by the bootstrap. */
-  coverage?: CoverageStore;
-  /**
-   * Replay toggle (ADR 0015): when active, the dev adapter substitutes a recorded
-   * Fixture's `data` for the live `data` at `loading=false`. The boolean is the
-   * coarse on/off the HUD owns per tab; the per-mode policy (`prefer` vs
-   * `missing-only`) is carried alongside in `replayMode`.
-   */
-  replay?: ToggleStore;
-  /** Dev-only Replay policy: how a Fixture substitutes for live `data` (ADR 0015). */
-  replayMode?: 'prefer' | 'missing-only';
-  /**
-   * Dev-only Record policy (ADR 0015): when the dev adapter records the live
-   * `data` it is about to render. `'manual'` (the default) records nothing
-   * automatically — only the HUD button does; `'first-ready'` records once when a
-   * Skeleton goes ready and has no Fixture yet; `'always'` records on every ready
-   * render.
-   */
-  recordMode?: 'manual' | 'first-ready' | 'always';
-  /** Dev-only Fixture record/replay store (ADR 0015); never present in production. */
-  fixtures?: FixtureStore;
-}
-declare global {
-  var __XRAY__: CaptureHook | undefined;
-}
-//#endregion
-//#region src/serialize.d.ts
-/**
- * Browser-side capture: walk a live rendered subtree into a Plate — one node
- * tree plus one self-contained, scoped CSS string (ADR 0003). The CSS is
- * lifted from the author rules that matched each node, rewritten to
- * plate-local selectors — it carries `@media` for free and keeps layout live
- * (the M1 bake-off winner; ADR 0005).
- */
-interface CaptureOptions {
-  /** Plate name; comes from the virtual-module specifier. */
-  name: string;
-  /** Collect limits (ADR 0022): refuse a capture whose measured tree exceeds any axis. */
-  collect?: CollectLimits;
-  /**
-   * Optional programmable capture walker (ADR 0018). The declarative `data-xr-*`
-   * annotations cover the 90%; this is the escape hatch for the 10% a markup
-   * attribute cannot express. Capture-only: it shapes the resulting `PlateNode`
-   * tree but is never persisted into the Plate, and the production adapter never
-   * captures so it ignores this entirely.
-   */
-  walker?: XrayCaptureWalker;
-  /**
-   * Whether the top-level capture roots ARE this plate's own boundary, so the
-   * stitch guard must be SKIPPED for them (ADR 0006/0014, finding #6). True ONLY
-   * for a MANUAL root: there `site.el` is the consumer's own element and its
-   * `data-xr-boundary` marks the boundary of THIS plate, so the root must be
-   * serialized as a real Entry (its box/classes/padding/border) rather than a
-   * stitch-to-itself. Defaults to `false` — the auto path, where the top-level
-   * roots are the wrapper's CHILDREN and any boundary marker on a direct-child
-   * root is a NESTED `<Skeleton>` that MUST stitch (the capture-leak guard).
-   */
-  captureRootIsBoundary?: boolean;
-}
-/**
- * What a capture walker decides for one element (ADR 0018; ADR 0022 §5). The
- * `applyWalker` PASS reads the decision and applies it to the measured IR node —
- * a walker NEVER hand-builds a `PlateNode`, so xray keeps ownership of the Plate
- * format. `ignore` drops the element + its subtree; `bone` collapses it to one
- * Bone leaf (inferring the kind when omitted); `keep` defers to the default
- * classifier (`markInk`).
- */
-type WalkerDecision = {
-  type: 'ignore';
-} | {
-  type: 'bone';
-  kind?: LeafKind;
-} | {
-  type: 'keep';
-};
-/**
- * The context handed to a capture walker's `element` hook (ADR 0018). The
- * helpers are PURE — each returns a `WalkerDecision` the `applyWalker` pass
- * applies; they do NOT mutate. `el` is the element under consideration.
- */
-interface CaptureWalkerContext {
-  /** The element currently being classified. */
-  el: Element;
-  /** Drop this element AND its whole subtree (no bone). */
-  ignore(): WalkerDecision;
-  /**
-   * Collapse this element's subtree into ONE Bone leaf. `kind` omitted shares
-   * the default classifier's kind-inference heuristic (`inferLeafKind`; ADR 0018,
-   * Q4 — ONE code path).
-   */
-  bone(opts?: {
-    kind?: LeafKind;
-  }): WalkerDecision;
-  /** Defer to the default classifier (`markInk`) — recurse into the subtree. */
-  keep(): WalkerDecision;
-}
-/**
- * The programmable capture walker (ADR 0018; ADR 0022 §5). `element` is offered
- * each non-boundary element TOP-DOWN over the measured IR (the `applyWalker`
- * pass, NOT the DOM walk) and returns a `WalkerDecision` the pass applies. The
- * declarative `data-xr-*` annotations cover the 90%; this is the 10% escape
- * hatch for what a markup attribute cannot express.
- */
-interface XrayCaptureWalker {
-  /**
-   * Called for every non-boundary element node (a stitch carries no element and
-   * is skipped — ADR 0006 — so a boundary never reaches here). Return one of
-   * `ctx.ignore()`, `ctx.bone()`, or `ctx.keep()`. An `ignore`/`bone` decision
-   * stops the descent (the subtree lowers); `keep` recurses.
-   */
-  element?(ctx: CaptureWalkerContext): WalkerDecision;
-}
-/**
- * Typed identity wrapper for authoring a capture walker (ADR 0018) — the
- * `defineConfig` pattern. It returns its argument unchanged at runtime; its only
- * job is to infer and check the `XrayCaptureWalker` shape at the call site so an
- * author gets completion and a typo in a hook name is caught.
- */
-declare function defineXrayCaptureWalker(walker: XrayCaptureWalker): XrayCaptureWalker;
-/**
- * Thrown when a subtree has more nodes than the capture limit — almost always
- * a `<Skeleton>` sitting too high in the tree. Raised after the cheap walk and
- * before the O(rules × nodes) CSS extraction, so an oversized capture is
- * refused without freezing the main thread on it.
- */
-/** The measured size of a capture's surviving tree, one number per Collect axis (ADR 0022). */
-type CaptureSize = {
-  nodes: number;
-  breadth: number;
-  depth: number;
-};
-/** Which Collect axis a too-large capture tripped. */
-type CollectAxis = 'nodes' | 'breadth' | 'depth';
-declare class CaptureTooLargeError extends Error {
-  /** The full measured size of the surviving tree that tripped the gate. */
-  readonly size: CaptureSize;
-  /** Which axis exceeded its cap, and the cap it exceeded. */
-  readonly axis: CollectAxis;
-  readonly max: number;
-  /** Back-compat alias for `size.nodes` (the sole axis before breadth/depth). */
-  readonly nodeCount: number;
-  /** Folds the oversized-capture warning into the shared diagnostics vocabulary (diagnostics.ts). */
-  readonly code: "too-large";
-  constructor(size: CaptureSize, axis: CollectAxis, max: number);
-}
-/**
- * Collect-stage size limits (ADR 0022): refuse to capture a boundary whose
- * measured tree exceeds any axis. `maxNodes` caps the total surviving-node count;
- * `maxBreadth` the widest level (most nodes at any one depth); `maxDepth` the
- * nesting depth. Each axis is enforced only when its cap is defined. The defaults
- * and the `maxNodes = round(maxBreadth × maxDepth / 4)` derivation live in the
- * client (where the other defaults live); this core only enforces what it is handed.
- */
-type CollectLimits = {
-  maxNodes?: number;
-  maxBreadth?: number;
-  maxDepth?: number;
-};
-//#endregion
-export { emptyPlate as _, CollectAxis as a, XrayCaptureWalker as c, MergedPlate as d, Plate as f, ViewCapture as g, StoredPlate as h, CaptureWalkerContext as i, defineXrayCaptureWalker as l, RenderNode as m, CaptureSize as n, CollectLimits as o, PlateNode as p, CaptureTooLargeError as r, WalkerDecision as s, CaptureOptions as t, LeafKind as u, CaptureDiagnostic as v };