@domandigital/craft 0.11.0 → 0.13.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,70 @@ interface SnapshotSection {
     iconCards: number;
     /** Hidden at load, waiting for a scroll to reveal it. */
     hiddenAtLoad: boolean;
+    /** Version 2. */
+    role?: SectionRole;
+    /** Version 2. */
+    geometry?: SectionGeometry;
+    /** Version 2: short pill or label texts in the section ("Most popular", "New"), at most 5. */
+    badges?: string[];
+    /** Version 2: small round portraits (at most 96px, roughly square, radius 40% or more). */
+    avatars?: number;
+    /** Version 2: a horizontal scroller, snap track or prev/next control holds the content. */
+    carousel?: boolean;
+    /** Version 2: large standalone figures ("500+", "98%", "4.9/5") at 24px or more. */
+    figures?: number;
+}
+type ImageRole = "photo" | "illustration" | "icon" | "avatar" | "logo";
+/**
+ * What the image's own bytes say about where it came from. Only a positive
+ * is evidence: most images carry no metadata at all, and a re-encode strips
+ * it, so no marker proves nothing.
+ */
+interface ImageProvenance {
+    /** The IPTC digital source type found, if any: "trainedAlgorithmicMedia" or "compositeWithTrainedAlgorithmicMedia". */
+    digitalSourceType: string | null;
+    /** Where the marker sat: an XMP packet, a C2PA manifest, or somewhere else in the file. */
+    source: "xmp" | "c2pa" | "other" | null;
+    /** The file carries a C2PA manifest (Content Credentials), whatever it says. */
+    c2pa: boolean;
+    /** Bytes read, from the start of the file. */
+    bytes: number;
+}
+/** One image as the visitor sees it: an `img`, or a CSS background large enough to be a picture. */
+interface SnapshotImage {
+    /** The URL the browser loaded, unwrapped from an image optimiser (`/_next/image?url=`), or a `data:` URI cut to 64 characters. */
+    src: string;
+    /** Host of `src`, or null for a `data:` URI. */
+    host: string | null;
+    width: number;
+    height: number;
+    top: number;
+    role: ImageRole;
+    alt: string | null;
+    /** Empty alt, `aria-hidden` or `role="presentation"`. */
+    decorative: boolean;
+    /** Index into `sections`, or null when the image sits outside them. */
+    section: number | null;
+    /** A CSS `background-image`, not an `img`. */
+    background: boolean;
+    /** Present when the bytes were read. */
+    provenance?: ImageProvenance;
+}
+/**
+ * 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 +207,17 @@ 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;
+    /**
+     * Version 2, craft 0.14 and later: every image on the page, largest first, at
+     * most 60. Absent in older snapshots, which the imagery tells never judge.
+     */
+    images?: SnapshotImage[];
+    /** 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 +368,31 @@ 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;
+    /** Left-right balance of the content, 0 to 1. Component comparison only. */
+    symmetry?: number;
+    /** Buttons in the section. */
+    controls?: number;
+    /** Cards side by side. */
+    cards?: number;
+    /** The section's own background, or null when it is the page ground. */
+    background?: Oklch | null;
+    /** Badge texts ("Most popular"), lower-cased. */
+    badges?: string[];
+    /** Small round portraits. */
+    avatars?: number;
+    carousel?: boolean;
+    /** Large standalone figures. */
+    figures?: 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 +412,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 +455,10 @@ 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;
+    /** Read the first bytes of the page's larger images for AI provenance markers. Default true. */
+    provenance?: boolean;
 }
 interface MinimalPage {
     close?(): Promise<void>;
@@ -338,7 +468,34 @@ 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>;
+    /** Optional: Playwright's request context, which fetches outside the page's CORS rules. Without it, no image gets `provenance`. */
+    request?: {
+        get(url: string, options?: {
+            headers?: Record<string, string>;
+            timeout?: number;
+        }): Promise<{
+            ok(): boolean;
+            body(): Promise<Uint8Array>;
+        }>;
+    };
 }
+/** At most this many images are read for provenance, largest first. */
+declare const PROVENANCE_MAX_IMAGES = 24;
+/** The most time the reads may take for one page, in ms, so a machine offline waits seconds, not minutes. */
+declare const PROVENANCE_BUDGET_MS = 20000;
+/** 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 +545,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, PROVENANCE_BUDGET_MS, PROVENANCE_MAX_IMAGES, 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,70 @@ interface SnapshotSection {
     iconCards: number;
     /** Hidden at load, waiting for a scroll to reveal it. */
     hiddenAtLoad: boolean;
+    /** Version 2. */
+    role?: SectionRole;
+    /** Version 2. */
+    geometry?: SectionGeometry;
+    /** Version 2: short pill or label texts in the section ("Most popular", "New"), at most 5. */
+    badges?: string[];
+    /** Version 2: small round portraits (at most 96px, roughly square, radius 40% or more). */
+    avatars?: number;
+    /** Version 2: a horizontal scroller, snap track or prev/next control holds the content. */
+    carousel?: boolean;
+    /** Version 2: large standalone figures ("500+", "98%", "4.9/5") at 24px or more. */
+    figures?: number;
+}
+type ImageRole = "photo" | "illustration" | "icon" | "avatar" | "logo";
+/**
+ * What the image's own bytes say about where it came from. Only a positive
+ * is evidence: most images carry no metadata at all, and a re-encode strips
+ * it, so no marker proves nothing.
+ */
+interface ImageProvenance {
+    /** The IPTC digital source type found, if any: "trainedAlgorithmicMedia" or "compositeWithTrainedAlgorithmicMedia". */
+    digitalSourceType: string | null;
+    /** Where the marker sat: an XMP packet, a C2PA manifest, or somewhere else in the file. */
+    source: "xmp" | "c2pa" | "other" | null;
+    /** The file carries a C2PA manifest (Content Credentials), whatever it says. */
+    c2pa: boolean;
+    /** Bytes read, from the start of the file. */
+    bytes: number;
+}
+/** One image as the visitor sees it: an `img`, or a CSS background large enough to be a picture. */
+interface SnapshotImage {
+    /** The URL the browser loaded, unwrapped from an image optimiser (`/_next/image?url=`), or a `data:` URI cut to 64 characters. */
+    src: string;
+    /** Host of `src`, or null for a `data:` URI. */
+    host: string | null;
+    width: number;
+    height: number;
+    top: number;
+    role: ImageRole;
+    alt: string | null;
+    /** Empty alt, `aria-hidden` or `role="presentation"`. */
+    decorative: boolean;
+    /** Index into `sections`, or null when the image sits outside them. */
+    section: number | null;
+    /** A CSS `background-image`, not an `img`. */
+    background: boolean;
+    /** Present when the bytes were read. */
+    provenance?: ImageProvenance;
+}
+/**
+ * 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 +207,17 @@ 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;
+    /**
+     * Version 2, craft 0.14 and later: every image on the page, largest first, at
+     * most 60. Absent in older snapshots, which the imagery tells never judge.
+     */
+    images?: SnapshotImage[];
+    /** 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 +368,31 @@ 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;
+    /** Left-right balance of the content, 0 to 1. Component comparison only. */
+    symmetry?: number;
+    /** Buttons in the section. */
+    controls?: number;
+    /** Cards side by side. */
+    cards?: number;
+    /** The section's own background, or null when it is the page ground. */
+    background?: Oklch | null;
+    /** Badge texts ("Most popular"), lower-cased. */
+    badges?: string[];
+    /** Small round portraits. */
+    avatars?: number;
+    carousel?: boolean;
+    /** Large standalone figures. */
+    figures?: 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 +412,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 +455,10 @@ 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;
+    /** Read the first bytes of the page's larger images for AI provenance markers. Default true. */
+    provenance?: boolean;
 }
 interface MinimalPage {
     close?(): Promise<void>;
@@ -338,7 +468,34 @@ 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>;
+    /** Optional: Playwright's request context, which fetches outside the page's CORS rules. Without it, no image gets `provenance`. */
+    request?: {
+        get(url: string, options?: {
+            headers?: Record<string, string>;
+            timeout?: number;
+        }): Promise<{
+            ok(): boolean;
+            body(): Promise<Uint8Array>;
+        }>;
+    };
 }
+/** At most this many images are read for provenance, largest first. */
+declare const PROVENANCE_MAX_IMAGES = 24;
+/** The most time the reads may take for one page, in ms, so a machine offline waits seconds, not minutes. */
+declare const PROVENANCE_BUDGET_MS = 20000;
+/** 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 +545,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, PROVENANCE_BUDGET_MS, PROVENANCE_MAX_IMAGES, type SnapshotOptions, type SnapshotResult, VISUAL_MAX_HEIGHT, audit, collectInPage, loadPlaywright, overlayInPage, snapshotPage, snapshotUrl, snapshotUrls };