@domandigital/craft 0.10.0 → 0.12.0

package/dist/audit.d.cts

@@ -11,7 +11,13 @@
  * to a report and judged again later without a browser. Capturing one needs a
  * browser (see `@domandigital/craft/audit`); judging one does not.
  */
-declare const SNAPSHOT_VERSION = 1;
+/**
+ * 2 adds `role` and `geometry` per section, `rhythmVariance` for the page and
+ * the screenshot measures in `visual`. All four are optional: a version 1
+ * snapshot reads as version 2 without them (see `readSnapshot`), and nothing
+ * that judged a v1 snapshot judges it differently.
+ */
+declare const SNAPSHOT_VERSION = 2;
 interface SnapshotColour {
     /** `rgb(r, g, b)` or `rgba(r, g, b, a)`, as the browser computed it. */
     value: string;
@@ -50,6 +56,27 @@ interface SnapshotControl {
     text: string;
 }
 type SectionKind = "hero" | "logos" | "stats" | "cards" | "marquee" | "text" | "other";
+/**
+ * What a section is for, finer than `kind`. `kind` keeps its version 1
+ * meaning because the rendered tells, the null models and the estate were
+ * calibrated on it; `role` is what component-level comparison reads.
+ */
+type SectionRole = SectionKind | "cta-band" | "footer-cta" | "pricing" | "testimonials" | "faq" | "process" | "features" | "team" | "contact";
+/** How a section is laid out, measured, not judged. */
+interface SectionGeometry {
+    /** Share of the section's text blocks that are centred, 0 to 1. */
+    centredShare: number;
+    /** Content area balance about the vertical centre line: 1 mirror-even, 0 all on one side. */
+    mirrorSymmetry: number;
+    /** Share of the section's area with no text, image or control in it, 0 to 1. */
+    whitespaceRatio: number;
+    /** Width the content spans, over the viewport width. */
+    contentWidthRatio: number;
+    /** The painted background behind the section, as computed. */
+    background: string;
+    /** Buttons and button-styled links in the section. */
+    controls: number;
+}
 interface SnapshotSection {
     top: number;
     height: number;
@@ -62,6 +89,26 @@ interface SnapshotSection {
     iconCards: number;
     /** Hidden at load, waiting for a scroll to reveal it. */
     hiddenAtLoad: boolean;
+    /** Version 2. */
+    role?: SectionRole;
+    /** Version 2. */
+    geometry?: SectionGeometry;
+}
+/**
+ * Measures of the rendered pixels, from a full-page screenshot (capped at
+ * `height`). None of them passes or fails anything: they describe.
+ */
+interface SnapshotVisual {
+    /** Hasler and Süsstrunk (2003) colourfulness, M = σ_rgyb + 0.3 μ_rgyb, on 0-255 channels. Grey is 0. */
+    colourfulness: number;
+    /** Share of sampled pixels on a luminance edge: a complexity proxy, 0 to 1. */
+    edgeDensity: number;
+    /** 1 minus the mean luminance difference between each pixel and its left-right mirror, 0 to 1. */
+    symmetry: number;
+    width: number;
+    height: number;
+    /** Pixels actually read: large pages are sampled on a grid. */
+    sampled: number;
 }
 interface SnapshotGradient {
     /** Colour stops, as computed. */
@@ -116,6 +163,12 @@ interface Snapshot {
     sections: SnapshotSection[];
     effects: SnapshotEffects;
     motion: SnapshotMotion;
+    /** Version 2: coefficient of variation of the section heights. Null with fewer than two sections. */
+    rhythmVariance?: number | null;
+    /** Version 2: absent when the page could not be screenshotted. */
+    visual?: SnapshotVisual;
+    /** Set when a version 1 snapshot was read and upgraded in memory. */
+    migratedFrom?: 1;
     /** The design-system measures trawl has collected since v7, kept so it can switch to this. */
     metrics: {
         fontSizes: number[];
@@ -266,9 +319,16 @@ type FontClass = "serif" | "sans" | "mono" | "script" | "system";
  * Pure. Built from a Snapshot, so it describes what a visitor gets.
  */
 
-declare const FINGERPRINT_VERSION = 1;
+/** One section as layout comparison sees it. */
+interface FingerprintSection {
+    role: SectionRole;
+    /** Share of centred text, 0 to 1. */
+    centred: number;
+    /** Content width over viewport width, 0 to 1. */
+    width: number;
+}
 interface Fingerprint {
-    version: typeof FINGERPRINT_VERSION;
+    version: 1 | 2;
     /** The most prominent chromatic colour: button fills first, then painted area, then text. */
     accent: Oklch | null;
     ground: Oklch;
@@ -288,6 +348,8 @@ interface Fingerprint {
     effects: string[];
     /** Section kinds in running order, hero first. */
     layout: SectionKind[];
+    /** Version 2: present when every section carries a role and geometry. */
+    sections?: FingerprintSection[];
 }
 
 /**
@@ -329,6 +391,8 @@ interface SnapshotOptions {
     /** A Chromium to launch instead of Playwright's own. Also read from CRAFT_CHROMIUM. */
     executablePath?: string;
     timeoutMs?: number;
+    /** Take a screenshot and measure its pixels (`visual`). Default true. */
+    visual?: boolean;
 }
 interface MinimalPage {
     close?(): Promise<void>;
@@ -338,7 +402,20 @@ interface MinimalPage {
     }): Promise<unknown>;
     evaluate<R>(fn: () => R): Promise<R>;
     waitForTimeout(ms: number): Promise<void>;
+    /** Optional: a driver without it gets a snapshot with no `visual` measures. */
+    screenshot?(options: {
+        fullPage?: boolean;
+        type?: "png";
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }): Promise<Uint8Array>;
 }
+/** The most of a page the screenshot measures read, in CSS px. A long page is judged on its opening. */
+declare const VISUAL_MAX_HEIGHT = 6000;
 interface MinimalBrowser {
     newPage(options?: {
         viewport?: {
@@ -388,4 +465,4 @@ interface AuditResult {
 /** Snapshot a URL, judge it against the rendered tells, and fingerprint it. */
 declare function audit(url: string, options?: SnapshotOptions & CheckOptions): Promise<AuditResult>;
 
-export { type AuditResult, type SnapshotOptions, type SnapshotResult, audit, collectInPage, loadPlaywright, overlayInPage, snapshotPage, snapshotUrl, snapshotUrls };
+export { type AuditResult, type SnapshotOptions, type SnapshotResult, VISUAL_MAX_HEIGHT, audit, collectInPage, loadPlaywright, overlayInPage, snapshotPage, snapshotUrl, snapshotUrls };

package/dist/audit.d.ts

@@ -11,7 +11,13 @@
  * to a report and judged again later without a browser. Capturing one needs a
  * browser (see `@domandigital/craft/audit`); judging one does not.
  */
-declare const SNAPSHOT_VERSION = 1;
+/**
+ * 2 adds `role` and `geometry` per section, `rhythmVariance` for the page and
+ * the screenshot measures in `visual`. All four are optional: a version 1
+ * snapshot reads as version 2 without them (see `readSnapshot`), and nothing
+ * that judged a v1 snapshot judges it differently.
+ */
+declare const SNAPSHOT_VERSION = 2;
 interface SnapshotColour {
     /** `rgb(r, g, b)` or `rgba(r, g, b, a)`, as the browser computed it. */
     value: string;
@@ -50,6 +56,27 @@ interface SnapshotControl {
     text: string;
 }
 type SectionKind = "hero" | "logos" | "stats" | "cards" | "marquee" | "text" | "other";
+/**
+ * What a section is for, finer than `kind`. `kind` keeps its version 1
+ * meaning because the rendered tells, the null models and the estate were
+ * calibrated on it; `role` is what component-level comparison reads.
+ */
+type SectionRole = SectionKind | "cta-band" | "footer-cta" | "pricing" | "testimonials" | "faq" | "process" | "features" | "team" | "contact";
+/** How a section is laid out, measured, not judged. */
+interface SectionGeometry {
+    /** Share of the section's text blocks that are centred, 0 to 1. */
+    centredShare: number;
+    /** Content area balance about the vertical centre line: 1 mirror-even, 0 all on one side. */
+    mirrorSymmetry: number;
+    /** Share of the section's area with no text, image or control in it, 0 to 1. */
+    whitespaceRatio: number;
+    /** Width the content spans, over the viewport width. */
+    contentWidthRatio: number;
+    /** The painted background behind the section, as computed. */
+    background: string;
+    /** Buttons and button-styled links in the section. */
+    controls: number;
+}
 interface SnapshotSection {
     top: number;
     height: number;
@@ -62,6 +89,26 @@ interface SnapshotSection {
     iconCards: number;
     /** Hidden at load, waiting for a scroll to reveal it. */
     hiddenAtLoad: boolean;
+    /** Version 2. */
+    role?: SectionRole;
+    /** Version 2. */
+    geometry?: SectionGeometry;
+}
+/**
+ * Measures of the rendered pixels, from a full-page screenshot (capped at
+ * `height`). None of them passes or fails anything: they describe.
+ */
+interface SnapshotVisual {
+    /** Hasler and Süsstrunk (2003) colourfulness, M = σ_rgyb + 0.3 μ_rgyb, on 0-255 channels. Grey is 0. */
+    colourfulness: number;
+    /** Share of sampled pixels on a luminance edge: a complexity proxy, 0 to 1. */
+    edgeDensity: number;
+    /** 1 minus the mean luminance difference between each pixel and its left-right mirror, 0 to 1. */
+    symmetry: number;
+    width: number;
+    height: number;
+    /** Pixels actually read: large pages are sampled on a grid. */
+    sampled: number;
 }
 interface SnapshotGradient {
     /** Colour stops, as computed. */
@@ -116,6 +163,12 @@ interface Snapshot {
     sections: SnapshotSection[];
     effects: SnapshotEffects;
     motion: SnapshotMotion;
+    /** Version 2: coefficient of variation of the section heights. Null with fewer than two sections. */
+    rhythmVariance?: number | null;
+    /** Version 2: absent when the page could not be screenshotted. */
+    visual?: SnapshotVisual;
+    /** Set when a version 1 snapshot was read and upgraded in memory. */
+    migratedFrom?: 1;
     /** The design-system measures trawl has collected since v7, kept so it can switch to this. */
     metrics: {
         fontSizes: number[];
@@ -266,9 +319,16 @@ type FontClass = "serif" | "sans" | "mono" | "script" | "system";
  * Pure. Built from a Snapshot, so it describes what a visitor gets.
  */
 
-declare const FINGERPRINT_VERSION = 1;
+/** One section as layout comparison sees it. */
+interface FingerprintSection {
+    role: SectionRole;
+    /** Share of centred text, 0 to 1. */
+    centred: number;
+    /** Content width over viewport width, 0 to 1. */
+    width: number;
+}
 interface Fingerprint {
-    version: typeof FINGERPRINT_VERSION;
+    version: 1 | 2;
     /** The most prominent chromatic colour: button fills first, then painted area, then text. */
     accent: Oklch | null;
     ground: Oklch;
@@ -288,6 +348,8 @@ interface Fingerprint {
     effects: string[];
     /** Section kinds in running order, hero first. */
     layout: SectionKind[];
+    /** Version 2: present when every section carries a role and geometry. */
+    sections?: FingerprintSection[];
 }
 
 /**
@@ -329,6 +391,8 @@ interface SnapshotOptions {
     /** A Chromium to launch instead of Playwright's own. Also read from CRAFT_CHROMIUM. */
     executablePath?: string;
     timeoutMs?: number;
+    /** Take a screenshot and measure its pixels (`visual`). Default true. */
+    visual?: boolean;
 }
 interface MinimalPage {
     close?(): Promise<void>;
@@ -338,7 +402,20 @@ interface MinimalPage {
     }): Promise<unknown>;
     evaluate<R>(fn: () => R): Promise<R>;
     waitForTimeout(ms: number): Promise<void>;
+    /** Optional: a driver without it gets a snapshot with no `visual` measures. */
+    screenshot?(options: {
+        fullPage?: boolean;
+        type?: "png";
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }): Promise<Uint8Array>;
 }
+/** The most of a page the screenshot measures read, in CSS px. A long page is judged on its opening. */
+declare const VISUAL_MAX_HEIGHT = 6000;
 interface MinimalBrowser {
     newPage(options?: {
         viewport?: {
@@ -388,4 +465,4 @@ interface AuditResult {
 /** Snapshot a URL, judge it against the rendered tells, and fingerprint it. */
 declare function audit(url: string, options?: SnapshotOptions & CheckOptions): Promise<AuditResult>;
 
-export { type AuditResult, type SnapshotOptions, type SnapshotResult, audit, collectInPage, loadPlaywright, overlayInPage, snapshotPage, snapshotUrl, snapshotUrls };
+export { type AuditResult, type SnapshotOptions, type SnapshotResult, VISUAL_MAX_HEIGHT, audit, collectInPage, loadPlaywright, overlayInPage, snapshotPage, snapshotUrl, snapshotUrls };