domflax 0.1.0

package/dist/verify.d.cts

@@ -0,0 +1,245 @@
+import { H as Diagnostic } from './types-BQ7l6dVe.cjs';
+
+/**
+ * @domflax/verify — public type contract (TYPED STUB)
+ *
+ * Equivalence verifier: renders the `before` and `after` source of a single-file
+ * transform in a real browser and proves they are visually + structurally
+ * equivalent across a set of viewports. The heavy rendering/diffing engine
+ * (playwright + pixelmatch + pngjs) lands in a later stage; this module defines
+ * the FULL result/option surface and a NotImplemented entry point so downstream
+ * packages can typecheck against the contract today.
+ *
+ * Future runtime deps (NOT in package.json by design — see SKILL build rules):
+ *   - playwright   (headless render of before/after)
+ *   - pixelmatch   (per-pixel image delta)
+ *   - pngjs        (PNG decode for pixelmatch)
+ */
+
+/** A rendered surface to compare. */
+interface RenderTarget {
+    /** Stable label, e.g. 'before' | 'after'. */
+    readonly label: string;
+    /** Source code (JSX/TSX/HTML) to mount and render. */
+    readonly code: string;
+    /** Virtual module id / path, used for diagnostics + module resolution. */
+    readonly id: string;
+}
+/** Logical viewport the page is rendered at. */
+interface Viewport {
+    readonly name: string;
+    readonly width: number;
+    readonly height: number;
+    readonly deviceScaleFactor?: number;
+}
+/** Browser engine to drive (playwright channel). */
+type BrowserEngine = 'chromium' | 'firefox' | 'webkit';
+interface VerifyOptions {
+    readonly viewports?: readonly Viewport[];
+    readonly engine?: BrowserEngine;
+    /** Per-channel 0–255 tolerance before a pixel counts as different. */
+    readonly pixelThreshold?: number;
+    /** Max fraction (0–1) of differing pixels still considered equivalent. */
+    readonly maxPixelRatio?: number;
+    /** Max bounding-box drift in CSS px before flagging a layout shift. */
+    readonly maxBoxDeltaPx?: number;
+    /** Computed-style properties to compare; omit to use the verifier default set. */
+    readonly styleProperties?: readonly string[];
+    /** Wall-clock budget per target render, in ms. */
+    readonly timeoutMs?: number;
+    /** When true, retain rendered PNGs/diffs in the result for debugging. */
+    readonly captureArtifacts?: boolean;
+}
+interface BoundingBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Per-pixel comparison for one viewport. */
+interface PixelDiff {
+    readonly width: number;
+    readonly height: number;
+    readonly totalPixels: number;
+    readonly changedPixels: number;
+    readonly changedRatio: number;
+    /** Encoded PNG of the diff overlay; present only when captureArtifacts. */
+    readonly diffPng?: Uint8Array;
+}
+/** Layout drift for a single matched element between before/after. */
+interface BBoxDiff {
+    /** Best-effort selector / index path identifying the element. */
+    readonly path: string;
+    readonly before: BoundingBox | null;
+    readonly after: BoundingBox | null;
+    readonly deltaX: number;
+    readonly deltaY: number;
+    readonly deltaWidth: number;
+    readonly deltaHeight: number;
+    /** Max absolute component of the delta, in CSS px. */
+    readonly maxDelta: number;
+}
+/** Computed-style mismatch for one property on one element. */
+interface StyleDiff {
+    readonly path: string;
+    readonly property: string;
+    readonly before: string | null;
+    readonly after: string | null;
+}
+type Equivalence = 'equivalent' | 'divergent' | 'inconclusive';
+interface ViewportResult {
+    readonly viewport: Viewport;
+    readonly equivalence: Equivalence;
+    readonly pixel: PixelDiff;
+    readonly boxes: readonly BBoxDiff[];
+    readonly styles: readonly StyleDiff[];
+    /** Present only when captureArtifacts. */
+    readonly beforePng?: Uint8Array;
+    readonly afterPng?: Uint8Array;
+}
+interface VerifyResult {
+    readonly equivalence: Equivalence;
+    readonly engine: BrowserEngine;
+    readonly viewports: readonly ViewportResult[];
+    readonly diagnostics: readonly Diagnostic[];
+    readonly durationMs: number;
+}
+declare const DEFAULT_VIEWPORTS: readonly Viewport[];
+declare const DEFAULT_VERIFY_OPTIONS: {
+    readonly engine: "chromium";
+    readonly pixelThreshold: 2;
+    readonly maxPixelRatio: 0;
+    readonly maxBoxDeltaPx: 0.5;
+    readonly timeoutMs: 30000;
+    readonly captureArtifacts: false;
+};
+
+/**
+ * @domflax/verify — deterministic headless render + artifact capture.
+ *
+ * Accepts an HTML-string fragment (or a full document) and produces, for a
+ * single viewport:
+ *   - a viewport-clipped PNG screenshot (equal dimensions for before/after, so
+ *     pixelmatch never sees a size mismatch), and
+ *   - the list of VISUAL LEAVES with their bounding boxes + computed styles.
+ *
+ * Determinism is pinned hard: animations/transitions/caret disabled, reduced
+ * motion forced, fonts awaited, and layout settled across two animation frames
+ * before anything is measured.
+ */
+
+/** A measured visual leaf — see {@link extractLeaves}. */
+interface LeafSnapshot {
+    /** Lower-cased tag name. */
+    readonly tag: string;
+    /** ARIA role if set, else the tag — the structure-independent identity. */
+    readonly role: string;
+    /** Trimmed direct text content (own text nodes only). */
+    readonly text: string;
+    /** Layout geometry in CSS pixels, viewport-relative. */
+    readonly box: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Requested computed-style properties, raw (normalization happens in diff). */
+    readonly styles: Record<string, string>;
+}
+interface RenderArtifacts {
+    readonly png: Uint8Array;
+    readonly leaves: readonly LeafSnapshot[];
+}
+
+/**
+ * @domflax/verify — pure diff engine (no browser, fully unit-testable)
+ *
+ * Three independent comparison passes operate on the artifacts captured from a
+ * rendered page (see {@link ./render}):
+ *
+ *   1. {@link pixelDiff}   — per-pixel delta of the two screenshots (pixelmatch + pngjs).
+ *   2. {@link diffBoxes}   — per-visual-leaf bounding-box drift.
+ *   3. {@link diffStyles}  — per-visual-leaf computed-style mismatch, NORMALIZED.
+ *
+ * Passes 2 and 3 are STRUCTURE-INDEPENDENT: leaves are matched by (role, text)
+ * and visual position order, never by DOM index — node counts legitimately
+ * differ once a transform flattens wrappers, so DOM-order matching would be
+ * meaningless.
+ */
+
+declare const DEFAULT_STYLE_PROPERTIES: readonly string[];
+
+/**
+ * @domflax/verify — headless browser lifecycle.
+ *
+ * One shared {@link Browser} is launched and reused across every viewport and
+ * every fixture in a run (see {@link ./index}'s `createVerifier`), which is the
+ * batching primitive the maintainer-side oracle needs when validating many
+ * fixtures at once.
+ *
+ * Critically, a launch failure (no downloaded browser binary on a bare CI box)
+ * is reported as a value, never thrown past the public API — the verifier then
+ * returns an `inconclusive` verdict instead of hard-failing.
+ */
+
+/**
+ * Probe whether the engine can actually launch on this machine. Used by tests
+ * to `skipIf` cleanly when no browser is present, keeping browserless CI green.
+ */
+declare function isBrowserAvailable(engine?: BrowserEngine): Promise<boolean>;
+
+/**
+ * @domflax/verify — the maintainer-side Tier-2 equivalence oracle.
+ *
+ * Renders the `before` and `after` source of a single-file transform in a real
+ * headless browser and proves they are visually + structurally equivalent
+ * across a matrix of viewports. For each viewport it runs three independent
+ * passes (pixel, bounding-box, computed-style) and folds them into one verdict.
+ *
+ * The comparison is STRUCTURE-INDEPENDENT by design: node counts legitimately
+ * change once a transform flattens wrappers, so leaves are matched by visual
+ * role/text/position, never by DOM index (see {@link ./diff}).
+ *
+ * If no browser binary is available the verifier returns an `inconclusive`
+ * verdict (never throws), so browserless CI stays green.
+ */
+
+/** Fully-resolved options used by the render+diff engine. */
+interface ResolvedVerifyOptions {
+    readonly viewports: readonly Viewport[];
+    readonly engine: BrowserEngine;
+    readonly pixelThreshold: number;
+    readonly maxPixelRatio: number;
+    readonly maxBoxDeltaPx: number;
+    readonly styleProperties: readonly string[];
+    readonly timeoutMs: number;
+    readonly captureArtifacts: boolean;
+}
+/**
+ * Merge caller options over the verifier defaults. Pure and total — safe to use
+ * for config validation / dry-run planning.
+ */
+declare function resolveVerifyOptions(opts?: VerifyOptions): ResolvedVerifyOptions;
+interface Verifier {
+    /** Verify one before/after pair. Per-call options override the verifier defaults. */
+    verify(before: RenderTarget, after: RenderTarget, opts?: VerifyOptions): Promise<VerifyResult>;
+    /** Close the shared browser. Safe to call multiple times. */
+    close(): Promise<void>;
+}
+/**
+ * Create a verifier that holds ONE browser open across many {@link Verifier.verify}
+ * calls — the efficient path for validating a corpus of fixtures. The browser is
+ * launched lazily on first use; if launch fails (no binary), every `verify` call
+ * returns an `inconclusive` verdict rather than throwing.
+ */
+declare function createVerifier(): Verifier;
+/**
+ * One-shot equivalence check: render `before` and `after` and prove visual +
+ * structural equivalence across every viewport. Launches a single browser for
+ * the call and closes it afterwards.
+ *
+ * Returns an `inconclusive` verdict (never throws) when no browser is available.
+ */
+declare function verifyEquivalence(before: RenderTarget, after: RenderTarget, opts?: VerifyOptions): Promise<VerifyResult>;
+
+export { type BBoxDiff, type BoundingBox, type BrowserEngine, DEFAULT_STYLE_PROPERTIES, DEFAULT_VERIFY_OPTIONS, DEFAULT_VIEWPORTS, type Equivalence, type LeafSnapshot, type PixelDiff, type RenderArtifacts, type RenderTarget, type ResolvedVerifyOptions, type StyleDiff, type Verifier, type VerifyOptions, type VerifyResult, type Viewport, type ViewportResult, createVerifier, isBrowserAvailable, resolveVerifyOptions, verifyEquivalence };

package/dist/verify.d.ts

@@ -0,0 +1,245 @@
+import { H as Diagnostic } from './types-BQ7l6dVe.js';
+
+/**
+ * @domflax/verify — public type contract (TYPED STUB)
+ *
+ * Equivalence verifier: renders the `before` and `after` source of a single-file
+ * transform in a real browser and proves they are visually + structurally
+ * equivalent across a set of viewports. The heavy rendering/diffing engine
+ * (playwright + pixelmatch + pngjs) lands in a later stage; this module defines
+ * the FULL result/option surface and a NotImplemented entry point so downstream
+ * packages can typecheck against the contract today.
+ *
+ * Future runtime deps (NOT in package.json by design — see SKILL build rules):
+ *   - playwright   (headless render of before/after)
+ *   - pixelmatch   (per-pixel image delta)
+ *   - pngjs        (PNG decode for pixelmatch)
+ */
+
+/** A rendered surface to compare. */
+interface RenderTarget {
+    /** Stable label, e.g. 'before' | 'after'. */
+    readonly label: string;
+    /** Source code (JSX/TSX/HTML) to mount and render. */
+    readonly code: string;
+    /** Virtual module id / path, used for diagnostics + module resolution. */
+    readonly id: string;
+}
+/** Logical viewport the page is rendered at. */
+interface Viewport {
+    readonly name: string;
+    readonly width: number;
+    readonly height: number;
+    readonly deviceScaleFactor?: number;
+}
+/** Browser engine to drive (playwright channel). */
+type BrowserEngine = 'chromium' | 'firefox' | 'webkit';
+interface VerifyOptions {
+    readonly viewports?: readonly Viewport[];
+    readonly engine?: BrowserEngine;
+    /** Per-channel 0–255 tolerance before a pixel counts as different. */
+    readonly pixelThreshold?: number;
+    /** Max fraction (0–1) of differing pixels still considered equivalent. */
+    readonly maxPixelRatio?: number;
+    /** Max bounding-box drift in CSS px before flagging a layout shift. */
+    readonly maxBoxDeltaPx?: number;
+    /** Computed-style properties to compare; omit to use the verifier default set. */
+    readonly styleProperties?: readonly string[];
+    /** Wall-clock budget per target render, in ms. */
+    readonly timeoutMs?: number;
+    /** When true, retain rendered PNGs/diffs in the result for debugging. */
+    readonly captureArtifacts?: boolean;
+}
+interface BoundingBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Per-pixel comparison for one viewport. */
+interface PixelDiff {
+    readonly width: number;
+    readonly height: number;
+    readonly totalPixels: number;
+    readonly changedPixels: number;
+    readonly changedRatio: number;
+    /** Encoded PNG of the diff overlay; present only when captureArtifacts. */
+    readonly diffPng?: Uint8Array;
+}
+/** Layout drift for a single matched element between before/after. */
+interface BBoxDiff {
+    /** Best-effort selector / index path identifying the element. */
+    readonly path: string;
+    readonly before: BoundingBox | null;
+    readonly after: BoundingBox | null;
+    readonly deltaX: number;
+    readonly deltaY: number;
+    readonly deltaWidth: number;
+    readonly deltaHeight: number;
+    /** Max absolute component of the delta, in CSS px. */
+    readonly maxDelta: number;
+}
+/** Computed-style mismatch for one property on one element. */
+interface StyleDiff {
+    readonly path: string;
+    readonly property: string;
+    readonly before: string | null;
+    readonly after: string | null;
+}
+type Equivalence = 'equivalent' | 'divergent' | 'inconclusive';
+interface ViewportResult {
+    readonly viewport: Viewport;
+    readonly equivalence: Equivalence;
+    readonly pixel: PixelDiff;
+    readonly boxes: readonly BBoxDiff[];
+    readonly styles: readonly StyleDiff[];
+    /** Present only when captureArtifacts. */
+    readonly beforePng?: Uint8Array;
+    readonly afterPng?: Uint8Array;
+}
+interface VerifyResult {
+    readonly equivalence: Equivalence;
+    readonly engine: BrowserEngine;
+    readonly viewports: readonly ViewportResult[];
+    readonly diagnostics: readonly Diagnostic[];
+    readonly durationMs: number;
+}
+declare const DEFAULT_VIEWPORTS: readonly Viewport[];
+declare const DEFAULT_VERIFY_OPTIONS: {
+    readonly engine: "chromium";
+    readonly pixelThreshold: 2;
+    readonly maxPixelRatio: 0;
+    readonly maxBoxDeltaPx: 0.5;
+    readonly timeoutMs: 30000;
+    readonly captureArtifacts: false;
+};
+
+/**
+ * @domflax/verify — deterministic headless render + artifact capture.
+ *
+ * Accepts an HTML-string fragment (or a full document) and produces, for a
+ * single viewport:
+ *   - a viewport-clipped PNG screenshot (equal dimensions for before/after, so
+ *     pixelmatch never sees a size mismatch), and
+ *   - the list of VISUAL LEAVES with their bounding boxes + computed styles.
+ *
+ * Determinism is pinned hard: animations/transitions/caret disabled, reduced
+ * motion forced, fonts awaited, and layout settled across two animation frames
+ * before anything is measured.
+ */
+
+/** A measured visual leaf — see {@link extractLeaves}. */
+interface LeafSnapshot {
+    /** Lower-cased tag name. */
+    readonly tag: string;
+    /** ARIA role if set, else the tag — the structure-independent identity. */
+    readonly role: string;
+    /** Trimmed direct text content (own text nodes only). */
+    readonly text: string;
+    /** Layout geometry in CSS pixels, viewport-relative. */
+    readonly box: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Requested computed-style properties, raw (normalization happens in diff). */
+    readonly styles: Record<string, string>;
+}
+interface RenderArtifacts {
+    readonly png: Uint8Array;
+    readonly leaves: readonly LeafSnapshot[];
+}
+
+/**
+ * @domflax/verify — pure diff engine (no browser, fully unit-testable)
+ *
+ * Three independent comparison passes operate on the artifacts captured from a
+ * rendered page (see {@link ./render}):
+ *
+ *   1. {@link pixelDiff}   — per-pixel delta of the two screenshots (pixelmatch + pngjs).
+ *   2. {@link diffBoxes}   — per-visual-leaf bounding-box drift.
+ *   3. {@link diffStyles}  — per-visual-leaf computed-style mismatch, NORMALIZED.
+ *
+ * Passes 2 and 3 are STRUCTURE-INDEPENDENT: leaves are matched by (role, text)
+ * and visual position order, never by DOM index — node counts legitimately
+ * differ once a transform flattens wrappers, so DOM-order matching would be
+ * meaningless.
+ */
+
+declare const DEFAULT_STYLE_PROPERTIES: readonly string[];
+
+/**
+ * @domflax/verify — headless browser lifecycle.
+ *
+ * One shared {@link Browser} is launched and reused across every viewport and
+ * every fixture in a run (see {@link ./index}'s `createVerifier`), which is the
+ * batching primitive the maintainer-side oracle needs when validating many
+ * fixtures at once.
+ *
+ * Critically, a launch failure (no downloaded browser binary on a bare CI box)
+ * is reported as a value, never thrown past the public API — the verifier then
+ * returns an `inconclusive` verdict instead of hard-failing.
+ */
+
+/**
+ * Probe whether the engine can actually launch on this machine. Used by tests
+ * to `skipIf` cleanly when no browser is present, keeping browserless CI green.
+ */
+declare function isBrowserAvailable(engine?: BrowserEngine): Promise<boolean>;
+
+/**
+ * @domflax/verify — the maintainer-side Tier-2 equivalence oracle.
+ *
+ * Renders the `before` and `after` source of a single-file transform in a real
+ * headless browser and proves they are visually + structurally equivalent
+ * across a matrix of viewports. For each viewport it runs three independent
+ * passes (pixel, bounding-box, computed-style) and folds them into one verdict.
+ *
+ * The comparison is STRUCTURE-INDEPENDENT by design: node counts legitimately
+ * change once a transform flattens wrappers, so leaves are matched by visual
+ * role/text/position, never by DOM index (see {@link ./diff}).
+ *
+ * If no browser binary is available the verifier returns an `inconclusive`
+ * verdict (never throws), so browserless CI stays green.
+ */
+
+/** Fully-resolved options used by the render+diff engine. */
+interface ResolvedVerifyOptions {
+    readonly viewports: readonly Viewport[];
+    readonly engine: BrowserEngine;
+    readonly pixelThreshold: number;
+    readonly maxPixelRatio: number;
+    readonly maxBoxDeltaPx: number;
+    readonly styleProperties: readonly string[];
+    readonly timeoutMs: number;
+    readonly captureArtifacts: boolean;
+}
+/**
+ * Merge caller options over the verifier defaults. Pure and total — safe to use
+ * for config validation / dry-run planning.
+ */
+declare function resolveVerifyOptions(opts?: VerifyOptions): ResolvedVerifyOptions;
+interface Verifier {
+    /** Verify one before/after pair. Per-call options override the verifier defaults. */
+    verify(before: RenderTarget, after: RenderTarget, opts?: VerifyOptions): Promise<VerifyResult>;
+    /** Close the shared browser. Safe to call multiple times. */
+    close(): Promise<void>;
+}
+/**
+ * Create a verifier that holds ONE browser open across many {@link Verifier.verify}
+ * calls — the efficient path for validating a corpus of fixtures. The browser is
+ * launched lazily on first use; if launch fails (no binary), every `verify` call
+ * returns an `inconclusive` verdict rather than throwing.
+ */
+declare function createVerifier(): Verifier;
+/**
+ * One-shot equivalence check: render `before` and `after` and prove visual +
+ * structural equivalence across every viewport. Launches a single browser for
+ * the call and closes it afterwards.
+ *
+ * Returns an `inconclusive` verdict (never throws) when no browser is available.
+ */
+declare function verifyEquivalence(before: RenderTarget, after: RenderTarget, opts?: VerifyOptions): Promise<VerifyResult>;
+
+export { type BBoxDiff, type BoundingBox, type BrowserEngine, DEFAULT_STYLE_PROPERTIES, DEFAULT_VERIFY_OPTIONS, DEFAULT_VIEWPORTS, type Equivalence, type LeafSnapshot, type PixelDiff, type RenderArtifacts, type RenderTarget, type ResolvedVerifyOptions, type StyleDiff, type Verifier, type VerifyOptions, type VerifyResult, type Viewport, type ViewportResult, createVerifier, isBrowserAvailable, resolveVerifyOptions, verifyEquivalence };