@domandigital/craft 0.5.0 → 0.7.0

package/dist/audit.d.cts

@@ -0,0 +1,389 @@
+/**
+ * A snapshot: what a page looks like once it has rendered, as plain data.
+ *
+ * Source tells read what a site writes. A snapshot reads what a visitor gets:
+ * the font that actually loaded, the colour that actually covers the page,
+ * the sections that actually fade in. The two disagree often enough to need
+ * both. A Tailwind class list can name indigo and a CMS can override it; a
+ * source can name Fraunces and the font can fail to load.
+ *
+ * Everything here is plain JSON so a snapshot can be saved, diffed, attached
+ * 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;
+interface SnapshotColour {
+    /** `rgb(r, g, b)` or `rgba(r, g, b, a)`, as the browser computed it. */
+    value: string;
+    /** Painted area in CSS px², summed over every element using it. */
+    area: number;
+    /** Characters of text drawn in it, for text colours. */
+    chars: number;
+}
+interface SnapshotFont {
+    /** The first family in the computed stack, unquoted. */
+    family: string;
+    /** Characters of visible text set in it. */
+    chars: number;
+    /** Characters of it in headings (h1 to h3 and elements at 28px or more). */
+    displayChars: number;
+    italicChars: number;
+    weights: number[];
+}
+interface SnapshotHeading {
+    level: number;
+    family: string;
+    sizePx: number;
+    weight: number;
+    italic: boolean;
+    /** An `<em>`, `<i>` or italic span inside a non-italic heading: "Beauty, *reimagined*". */
+    italicPart: boolean;
+    text: string;
+    top: number;
+}
+interface SnapshotControl {
+    /** `button` for a <button> or submit, `link` for an anchor styled as a button. */
+    kind: "button" | "link";
+    radiusPx: number;
+    heightPx: number;
+    background: string;
+    text: string;
+}
+type SectionKind = "hero" | "logos" | "stats" | "cards" | "marquee" | "text" | "other";
+interface SnapshotSection {
+    top: number;
+    height: number;
+    kind: SectionKind;
+    /** The first heading's text, or the first words, so a report can name it. */
+    label: string;
+    /** Cards laid out side by side: siblings of similar size in one row. */
+    cards: number;
+    /** Of those cards, how many open with an icon (an <svg> or small image). */
+    iconCards: number;
+    /** Hidden at load, waiting for a scroll to reveal it. */
+    hiddenAtLoad: boolean;
+}
+interface SnapshotGradient {
+    /** Colour stops, as computed. */
+    stops: string[];
+    area: number;
+    radial: boolean;
+}
+interface SnapshotEffects {
+    /** Elements with backdrop-filter blur and a translucent background. */
+    glass: number;
+    /** Text painted with a gradient (background-clip: text). */
+    gradientText: number;
+    gradients: SnapshotGradient[];
+    /** Large blurred shapes or radial gradients behind content with no content of their own. */
+    glows: number;
+    /** Repeating 1px line or dot backgrounds. */
+    gridBackgrounds: number;
+    /** Infinite horizontal translate animations. */
+    marquees: number;
+    /** Cards with a near-invisible border and a wide soft shadow. */
+    hairlineShadowCards: number;
+    /** A small bordered pill directly above the first h1. */
+    eyebrowChip: boolean;
+}
+interface SnapshotMotion {
+    /** Sections hidden at load (opacity near 0 or translated) that appear on scroll. */
+    hiddenSections: number;
+    sections: number;
+    /** Running CSS or Web Animations at capture time. */
+    animations: number;
+    /** A full-screen layer over the page at load that is gone a few seconds later. */
+    introOverlay: boolean;
+}
+interface Snapshot {
+    version: typeof SNAPSHOT_VERSION;
+    url: string;
+    capturedAt: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    pageHeight: number;
+    /** The page ground: the body's computed background, or the html's. */
+    ground: string;
+    colours: {
+        backgrounds: SnapshotColour[];
+        text: SnapshotColour[];
+    };
+    fonts: SnapshotFont[];
+    headings: SnapshotHeading[];
+    controls: SnapshotControl[];
+    sections: SnapshotSection[];
+    effects: SnapshotEffects;
+    motion: SnapshotMotion;
+    /** The design-system measures trawl has collected since v7, kept so it can switch to this. */
+    metrics: {
+        fontSizes: number[];
+        fontWeights: number[];
+        radii: string[];
+        shadows: string[];
+        spacingOnScalePct: number | null;
+        bodyLineLengthCh: number | null;
+        bodyFontSizePx: number | null;
+    };
+}
+
+/**
+ * The shapes shared by the tell catalogue, the source scanner and the copy
+ * engine.
+ *
+ * A tell is a choice an AI model makes when nobody told it otherwise. It is not
+ * a mistake. Every tell here would be fine as a decision; it is flagged because
+ * it is the answer the model reaches for first, so a site full of them reads as
+ * nobody having decided anything.
+ */
+/**
+ * Which wave of model defaults a tell belongs to.
+ *
+ * 1: the first wave (indigo, blue-to-purple gradients, Inter, glass cards).
+ * 2: what models moved to once the first wave was named and banned (cream and
+ *    italic serif, eyebrow chips, bento grids, the marquee).
+ * 3: reserved for what the harvester finds next.
+ *
+ * The tag exists because any fixed list goes stale. Knowing which wave a tell
+ * came from is what lets a report say "this site was built in 2024" rather
+ * than only "this site has tells".
+ */
+type Generation = 1 | 2 | 3;
+/**
+ * `warn` is reported and never fails a run unless `--strict` is passed.
+ * `block` fails a run.
+ *
+ * Every entry ships as `warn`. A rule blocks only after its hits across the
+ * estate have been read by a person and the rule tuned against them. A rule
+ * that blocks on day one gets switched off by day three.
+ */
+type Severity = "warn" | "block";
+interface Finding {
+    tell: string;
+    name: string;
+    generation: Generation;
+    severity: Severity;
+    path: string;
+    /** 1-indexed. 0 for a finding on a rendered page, where `path` is the URL. */
+    line: number;
+    excerpt: string;
+    message: string;
+    fix: string;
+}
+/**
+ * A declared reason to keep a tell. Lives in the site's `art-direction.json`.
+ *
+ * DD's own brand is violet. A hue rule with no way to say so flags the agency's
+ * own site on every commit, and gets switched off. An exception without a
+ * `because` is not applied: the reason is the point.
+ */
+interface TellException {
+    tell: string;
+    because: string;
+    /** Where the reason comes from: the shopfront, the van, the trade's own look. */
+    evidence?: string;
+    /** Limit the exception to paths containing this string. */
+    path?: string;
+}
+interface CheckOptions {
+    exceptions?: TellException[];
+    /** Run only these tell ids. */
+    only?: string[];
+}
+interface CheckReport {
+    catalogueVersion: string;
+    findings: Finding[];
+    /** Exceptions that were declared but not applied, and why. */
+    rejectedExceptions: {
+        exception: TellException;
+        reason: string;
+    }[];
+    /** Findings each applied exception silenced, so an exception stays visible. */
+    excepted: {
+        tell: string;
+        because: string;
+        count: number;
+    }[];
+    /**
+     * Findings silenced by a `copy-ok` or `craft-ok` marker on the line or the
+     * line above. Listed, never hidden: a marker nobody can see is a hole.
+     */
+    suppressed: {
+        tell: string;
+        path: string;
+        line: number;
+    }[];
+    summary: {
+        files: number;
+        findings: number;
+        byGeneration: Record<Generation, number>;
+        byTell: Record<string, number>;
+        blocking: number;
+    };
+}
+
+/**
+ * OKLab / OKLCh conversions, after Björn Ottosson's published M1/M2 matrices.
+ * https://bottosson.github.io/posts/oklab/
+ *
+ * Zero dependencies is a hard constraint for every dd-packages package, so the
+ * colour maths is implemented here rather than pulled from culori/colorjs.
+ */
+interface Oklch {
+    /** Perceptual lightness, 0..1. */
+    l: number;
+    /** Chroma, 0..~0.4 in practice. */
+    c: number;
+    /** Hue angle in degrees, 0..360. */
+    h: number;
+}
+
+/**
+ * Font family names as a browser reports them, turned back into the names a
+ * person would use.
+ *
+ * `next/font` renames every family it loads: Inter arrives as
+ * `__Inter_d65c78` and its metric-matched fallback as `__Inter_Fallback_d65c78`.
+ * A rendered check that compared raw names would never see a single reflex
+ * font on a Next.js site, which is most of the estate.
+ */
+type FontClass = "serif" | "sans" | "mono" | "script" | "system";
+
+/**
+ * A fingerprint: the handful of choices that make a site look like itself,
+ * reduced to something two sites can be compared on.
+ *
+ * Signals 2 and 3 of CHARACTER.md both need a distance. "Would a model have
+ * built this anyway" is a distance from what the model builds; "does this
+ * look like the agency's other sites" is a distance from the estate. Neither
+ * cares about the exact pixels. They care whether the accent, the type, the
+ * ground, the shape language, the motion and the running order were chosen
+ * or defaulted, so that is what a fingerprint records.
+ *
+ * Pure. Built from a Snapshot, so it describes what a visitor gets.
+ */
+
+declare const FINGERPRINT_VERSION = 1;
+interface Fingerprint {
+    version: typeof FINGERPRINT_VERSION;
+    /** The most prominent chromatic colour: button fills first, then painted area, then text. */
+    accent: Oklch | null;
+    ground: Oklch;
+    display: {
+        family: string;
+        class: FontClass;
+    };
+    body: {
+        family: string;
+        class: FontClass;
+    };
+    /** Median button corner radius over its height, 0 (square) to 0.5 (pill). */
+    roundness: number | null;
+    /** Share of below-the-fold sections that wait for a scroll to appear. */
+    motion: number;
+    /** Which second-look effects are present, as tell ids. */
+    effects: string[];
+    /** Section kinds in running order, hero first. */
+    layout: SectionKind[];
+}
+
+/**
+ * The in-page half of a snapshot.
+ *
+ * `collectInPage` runs inside the browser through `page.evaluate`, so it must
+ * be self-contained: no imports, no references to anything outside its own
+ * body. Anything that drives a browser can call it: craft's own `snapshotUrl`,
+ * trawl, a Playwright test in a client repo.
+ *
+ * It measures, it does not judge. Every threshold that decides whether
+ * something is a tell lives in the pure detectors, where it can be tested
+ * against a fixture without a browser.
+ */
+
+type InPageSnapshot = Omit<Snapshot, "version" | "url" | "capturedAt" | "motion"> & {
+    motion: Omit<Snapshot["motion"], "introOverlay">;
+};
+declare function collectInPage(): InPageSnapshot;
+/** True while something covers the viewport: the first frame of an intro cinematic. */
+declare function overlayInPage(): boolean;
+
+/**
+ * `@domandigital/craft/audit`: capture a snapshot of a live page and judge it.
+ *
+ * The only part of craft that needs a browser, so the only part that imports
+ * one, and only when called. `playwright` (or `playwright-core`) is an
+ * optional peer dependency: the core import stays pure, and a machine without
+ * a browser can still judge a snapshot someone else captured.
+ */
+
+interface SnapshotOptions {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** How long an intro may run before it counts as one. Default 5000 ms. */
+    introWindowMs?: number;
+    /** A Chromium to launch instead of Playwright's own. Also read from CRAFT_CHROMIUM. */
+    executablePath?: string;
+    timeoutMs?: number;
+}
+interface MinimalPage {
+    close?(): Promise<void>;
+    goto(url: string, options?: {
+        waitUntil?: string;
+        timeout?: number;
+    }): Promise<unknown>;
+    evaluate<R>(fn: () => R): Promise<R>;
+    waitForTimeout(ms: number): Promise<void>;
+}
+interface MinimalBrowser {
+    newPage(options?: {
+        viewport?: {
+            width: number;
+            height: number;
+        };
+    }): Promise<MinimalPage>;
+    close(): Promise<void>;
+}
+type Launcher = {
+    chromium: {
+        launch(options?: {
+            executablePath?: string;
+            headless?: boolean;
+            proxy?: {
+                server: string;
+            };
+        }): Promise<MinimalBrowser>;
+    };
+};
+/** Playwright, whichever flavour is installed, or a clear error saying how to get it. */
+declare function loadPlaywright(): Promise<Launcher>;
+/**
+ * Capture a snapshot from a page someone else is already driving. The caller
+ * owns the browser; craft only measures.
+ */
+declare function snapshotPage(page: MinimalPage, url: string, options?: SnapshotOptions): Promise<Snapshot>;
+/** Launch a browser, open `url`, and capture a snapshot. */
+declare function snapshotUrl(url: string, options?: SnapshotOptions): Promise<Snapshot>;
+interface SnapshotResult {
+    url: string;
+    snapshot?: Snapshot;
+    /** Why this page has no snapshot. The others are still taken. */
+    error?: string;
+}
+/**
+ * Several pages through one browser, in order. A null model is twenty pages;
+ * launching Chromium twenty times is most of the wait. One page that will not
+ * load costs that page, not the batch.
+ */
+declare function snapshotUrls(urls: string[], options?: SnapshotOptions): Promise<SnapshotResult[]>;
+interface AuditResult {
+    snapshot: Snapshot;
+    report: CheckReport;
+    fingerprint: Fingerprint;
+}
+/** 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 };