@hueest/xray 0.1.0

package/dist/serialize.d.ts

@@ -0,0 +1,88 @@
+import { n as MergedPlate, s as ViewCapture, t as LeafKind } from "./plate-DboxMKg-.js";
+
+//#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;
+}
+/**
+ * Capture the rendered subtree(s) under a Skeleton into a Plate. `roots` are
+ * the component's top-level elements (the children of the layout-neutral
+ * wrapper); the synthetic root node (id 0) stands in for the wrapper itself.
+ */
+declare function capture(roots: readonly Element[], options: CaptureOptions): MergedPlate;
+/**
+ * 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.
+ */
+declare class CaptureTooLargeError extends Error {
+  readonly nodeCount: number;
+  constructor(nodeCount: number);
+}
+interface CaptureRegimeOptions {
+  /** Refuse (throw `CaptureTooLargeError`) before CSS extraction if the walk exceeds this. */
+  maxNodes?: number;
+}
+/**
+ * Capture one view's worth of a component: the tree plus id-form rules,
+ * with the viewport width it was taken at. The caller (the dev client)
+ * derives the view interval and ships it off; `capture` is the
+ * single-view convenience on top.
+ */
+declare function captureRegime(roots: readonly Element[], options?: CaptureRegimeOptions): ViewCapture;
+/** One measurement per walked node, ids matching what `capture` assigns. */
+interface AuditEntry {
+  id: number;
+  tag: string;
+  leaf?: LeafKind;
+  w: number;
+  h: number;
+}
+/**
+ * Walk a live subtree exactly like `capture` does, but return per-node
+ * geometry instead of a plate. Rendering the captured plate and auditing both
+ * sides gives an id-aligned fidelity diff (used by the M1 bake-off).
+ */
+declare function audit(roots: readonly Element[]): AuditEntry[];
+/**
+ * Shrink a text run's measured box to what's actually painted. A `Range`'s
+ * rect is the text's full geometry and ignores ancestor clipping, so a
+ * `-webkit-line-clamp` box (fewer lines than the text fills) or a single-line
+ * `text-overflow: ellipsis` (`white-space: nowrap; overflow: hidden`) makes the
+ * bar over-measure — a 2-line title bone rendered at its unclamped 5-line
+ * height. Painted text can't exceed any clipping ancestor's content box, so we
+ * intersect with each: per axis the ancestor clips (`overflow !== visible`),
+ * clamp to its content box. A non-clipping or larger ancestor leaves it be, so
+ * unclamped text is untouched. Walks to the root since the clamp may sit a few
+ * inline wrappers up from the text node.
+ */
+interface ClippingStyle {
+  overflowX: string;
+  overflowY: string;
+  paddingTop: string;
+  paddingBottom: string;
+  paddingLeft: string;
+  paddingRight: string;
+  borderTopWidth: string;
+  borderBottomWidth: string;
+  borderLeftWidth: string;
+  borderRightWidth: string;
+}
+interface ClippingWindow {
+  getComputedStyle(element: Element): ClippingStyle;
+}
+declare function clampToClipping(width: number, height: number, fromParent: Element | null, win: ClippingWindow): {
+  width: number;
+  height: number;
+};
+//#endregion
+export { AuditEntry, CaptureOptions, CaptureRegimeOptions, CaptureTooLargeError, audit, capture, captureRegime, clampToClipping };

package/dist/serialize.js

@@ -0,0 +1,2 @@
+import { a as clampToClipping, i as captureRegime, n as audit, r as capture, t as CaptureTooLargeError } from "./serialize-Bq6yJnNV.js";
+export { CaptureTooLargeError, audit, capture, captureRegime, clampToClipping };

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@hueest/xray",
+  "version": "0.1.0",
+  "description": "Auto-captured skeleton loading screens for Vite — capture the structure, ship the plate.",
+  "keywords": [
+    "loading",
+    "placeholder",
+    "skeleton",
+    "skeleton-screen",
+    "vite",
+    "vite-plugin"
+  ],
+  "homepage": "https://xray-js.dev",
+  "bugs": "https://github.com/hueest/xray/issues",
+  "license": "MIT",
+  "author": "Stefan Maric",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hueest/xray.git"
+  },
+  "files": [
+    "dist",
+    "virtual.d.ts"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./react/dev": {
+      "types": "./dist/react.dev.d.ts",
+      "import": "./dist/react.dev.js"
+    },
+    "./serialize": {
+      "types": "./dist/serialize.d.ts",
+      "import": "./dist/serialize.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./hud": {
+      "types": "./dist/hud.d.ts",
+      "import": "./dist/hud.js"
+    },
+    "./virtual": {
+      "types": "./virtual.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "25.9.3",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@typescript/native-preview": "7.0.0-dev.20260619.1",
+    "happy-dom": "20.10.6",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "tsdown": "0.22.3",
+    "typescript": "6.0.3",
+    "vite": "8.0.16",
+    "vitest": "4.1.9"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "vite": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/virtual.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Type declarations for xray virtual modules.
+ *
+ * Reference from the consuming app, e.g. in tsconfig:
+ * `"types": ["@hueest/xray/virtual"]`, or per file:
+ * `/// <reference types="@hueest/xray/virtual" />`.
+ *
+ * @module @hueest/xray/virtual
+ */
+
+/**
+ * Import a committed or not-yet-captured Plate by name.
+ *
+ * The import specifier is the Plate identity: `virtual:xray/plates/my-banner`
+ * reads and writes `plates/my-banner.json`, and that name travels with the
+ * imported Plate. Pass the imported Plate to `<Skeleton>`; do not repeat the
+ * name in props.
+ *
+ * If the file does not exist yet, the Vite plugin resolves an empty Plate with
+ * the same name so `<Skeleton fallback={...}>` can render until the first
+ * Capture writes the file. Nested `<Skeleton>` boundaries become Stitches; the
+ * generated virtual module wires child Plates into `Plate.refs`, so production
+ * rendering follows the static import graph with no global registry.
+ *
+ * Captured Plate files are source artifacts. Commit files under `plates/` with
+ * the component change they describe.
+ */
+declare module 'virtual:xray/plates/*' {
+  import type { Plate } from '@hueest/xray'
+
+  /**
+   * The captured Plate named by the `virtual:xray/plates/<name>` import specifier.
+   *
+   * Enable this import in a consuming app with
+   * `"types": ["@hueest/xray/virtual"]` in tsconfig, or with a per-file
+   * `/// <reference types="@hueest/xray/virtual" />` directive.
+   *
+   * The specifier maps to a file under `plates/`; for example,
+   * `virtual:xray/plates/my-banner` maps to `plates/my-banner.json`. If that
+   * file does not exist yet, the plugin returns an empty Plate with the same
+   * name so a `<Skeleton fallback={...}>` can render until the first Capture.
+   * Pass the imported Plate to `<Skeleton>`; do not repeat the name in props.
+   *
+   * Child Plates referenced by Stitches are wired into `Plate.refs` by the
+   * generated virtual module. Production rendering follows that static import
+   * graph with no global Plate registry or runtime name lookup.
+   *
+   * Captured Plate files are source artifacts. Commit them with the component
+   * change they describe.
+   */
+  const plate: Plate
+  export default plate
+}