@hueest/xray 0.5.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Maric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @hueest/xray
+
+Auto-captured skeleton loading screens for [Vite](https://vite.dev). Capture the structure, ship the plate.
+
+xray captures the **real rendered DOM** of your components as you browse your dev server, then renders faithful skeleton loading states from those captures. Placeholders are captured rather than hand-drawn, with no separate headless browser and no fixed-height hacks.
+
+> Beta: APIs may move before 1.0. Docs, guides, and the API reference live at
+> **[xray-js.dev](https://xray-js.dev)**; source and issues at
+> [github.com/hueest/xray](https://github.com/hueest/xray).
+
+## Install
+
+```sh
+pnpm add @hueest/xray
+```
+
+## Use
+
+```ts
+// vite.config.ts
+import { xrayVitePlugin } from '@hueest/xray'
+
+export default defineConfig({
+  plugins: [xrayVitePlugin({ hud: true })],
+})
+```
+
+```tsx
+import { Skeleton } from '@hueest/xray/react'
+import plate from 'virtual:xray/plates/my-banner'
+
+// skeleton while loading; content + (dev) capture when ready
+;<Skeleton plate={plate} loading={loading} fallback={<Spinner />}>
+  <RealBanner data={data} />
+</Skeleton>
+```
+
+To inspect skeletons without waiting on loading states, tick **Light Box**
+in the HUD (or open the page with `?xray-lightbox`); every mounted
+`<Skeleton>` flips to its skeleton until unticked.
+
+Capture starts off. Tick **Capture** in the HUD (or pass `capture: true` to
+`xrayVitePlugin`) to start writing Plates as you browse. With Capture on,
+captures land in `plates/` (commit them). Resize to capture other views: each
+width lands as its own View, carried whole in the one plate and gated by
+`@media display:none` (JS-driven structure differences become Projections).
+Add `"@hueest/xray/virtual"` to the tsconfig `types` for the
+`virtual:xray/plates/*` imports.
+
+## Learn more
+
+- **[xray-js.dev](https://xray-js.dev)** — the docs site: how it works, the
+  radiographic mental model (Plate / Capture / Stitch / View / Projection / Light
+  Box), and guides for responsive Views, the HUD & Light Box, capture-all-views,
+  and theming.
+- **[xray-js.dev/reference/api/xray](https://xray-js.dev/reference/api/xray)** —
+  full API reference, generated from source.
+- **[GitHub](https://github.com/hueest/xray)** — source, issues, and the
+  architecture/decision-record trail.

package/dist/client.d.ts

@@ -1,25 +1,22 @@
-import { h as StoredPlate, o as CollectLimits, v as CaptureDiagnostic } from "./serialize-BgdGt34A.js";
-
+import { b as CaptureDiagnostic, g as StoredPlate, o as CollectLimits } from "./measure-CUQxB-Ic.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,
- * 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.
+ * The dev capture client. Runs in the browser during dev only: installs 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.
+ * Two paths produce a Plate. BROWSE-TIME is a CAPTURE 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.
  */
 /**
- * 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).
+ * The `/__xray` POST envelope (ADR 0022). `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;
@@ -29,59 +26,53 @@ interface ClientOptions {
   /** Settle delay (ms) once the subtree goes quiet. Default 200. */
   delay?: number;
   /**
-   * Upper bound (ms) on waiting for quiet before capturing anyway. Raise it
-   * for pages that stream content for a long time. Default 5000.
+   * Upper bound (ms) on waiting for quiet before capturing anyway. Raise it for pages that stream
+   * content for a long time. Default 5000.
    */
   settleCap?: number;
   /**
-   * Collect limits (ADR 0022): refuse a capture whose measured tree exceeds any
-   * axis — that big means the Skeleton sits too high in the component tree.
-   * `maxNodes` caps total surviving nodes (default 4096), `maxBreadth` the widest
-   * level (default 512), `maxDepth` the nesting depth (default 32). When `maxNodes`
-   * is omitted it derives as `round(maxBreadth × maxDepth / 4)`.
+   * Collect limits (ADR 0022): refuse a capture whose measured tree exceeds any axis — that big
+   * means the Skeleton sits too high in the component tree. `maxNodes` caps total surviving nodes
+   * (default 4096), `maxBreadth` the widest level (default 512), `maxDepth` the nesting depth
+   * (default 32). When `maxNodes` is omitted it derives as `round(maxBreadth × maxDepth / 4)`.
    */
   collect?: CollectLimits;
   /**
-   * 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.
+   * Initial state of the capture toggle: whether the capture session is active at boot. A per-tab
+   * override (sessionStorage / `?xray-capture`) wins over it. Defaults to `false` — capturing 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 session. 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. 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).
+   * 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).
    */
   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.
+   * 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. 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`).
+   * 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).
+   * 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;