@hueest/xray 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+import { Plugin } from "vite";
+
+//#region src/plate.d.ts
+type LeafKind = 'text' | '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 }`),
+ * 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).
+ */
+type Chunk = string | {
+  r: string;
+} | {
+  c: string;
+  k: Chunk[];
+};
+/**
+ * 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.
+ */
+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;
+  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;
+  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. What the dev client ships to the
+ * plugin, and what the plate file accumulates (ADR 0004).
+ */
+interface ViewCapture {
+  /** Viewport width at capture time. */
+  width: number;
+  min?: number;
+  max?: number;
+  tree: PlateNode;
+  rules: PlateRule[];
+}
+/** The committed `plates/<name>.json`: per-view captures, merged at load. */
+interface PlateFile {
+  v: number;
+  name: string;
+  /** Width thresholds (view boundaries) derived so far. */
+  breakpoints: number[];
+  views: ViewCapture[];
+}
+/**
+ * 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;
+}
+/** 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;
+  }) => (() => 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. */
+  updatePlate?: (name: string, plate: Plate) => void;
+  /** 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;
+}
+declare global {
+  var __XRAY__: CaptureHook | undefined;
+}
+//#endregion
+//#region src/merge.d.ts
+/**
+ * Turn the per-view captures in a plate file into the one plate a Skeleton
+ * renders.
+ *
+ * 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.
+ *
+ * Pure data-in/data-out — runs in node (plugin load) and in tests.
+ */
+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;
+//#endregion
+//#region src/index.d.ts
+/**
+ * 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.
+ */
+interface XrayOptions {
+  /** 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`.
+   */
+  capture?: boolean;
+  /** 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`. */
+  settleCap?: number;
+  /** Refuse captures larger than this many nodes (Skeleton too high in the tree). Default: `4000`. */
+  maxNodes?: number;
+}
+/**
+ * Create the Vite plugins that resolve committed Plates and, during dev,
+ * capture new Plates from rendered `<Skeleton>` boundaries.
+ *
+ * Typical setup:
+ *
+ * ```ts
+ * import { xrayVitePlugin } from '@hueest/xray'
+ *
+ * export default {
+ *   plugins: [xrayVitePlugin({ hud: true })],
+ * }
+ * ```
+ *
+ * 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.
+ */
+declare function xrayVitePlugin(options?: XrayOptions): Plugin[];
+interface CaptureRequest {
+  method?: string;
+  on(event: 'data' | 'end', listener: (chunk?: Buffer | string) => void): unknown;
+}
+interface CaptureResponse {
+  statusCode: number;
+  end(chunk?: string): unknown;
+}
+interface PlateBroadcaster {
+  send(payload: unknown): void;
+}
+interface CaptureServer {
+  ws: PlateBroadcaster;
+}
+/**
+ * Per-plate breakpoints + captured spans, read from the committed plate files.
+ *
+ * @internal
+ */
+declare function readCoverage(dir: string): Record<string, {
+  breakpoints: number[];
+  spans: {
+    min?: number;
+    max?: number;
+  }[];
+}>;
+/**
+ * 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;
+/**
+ * Names come from import specifiers and POST bodies — keep them inside the plates dir.
+ *
+ * @internal
+ */
+declare function isValidPlateName(name: string): boolean;
+/**
+ * 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.
+ *
+ * @internal
+ */
+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 };