@domandigital/craft 0.18.2 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @domandigital/craft
 
+## 0.19.1
+
+### Patch Changes
+
+- 5056c6a: STANDARD.md: a new section 10, "The phone is the base layout" (DOM-774): base styles are the phone and wider layouts use `min-width` only, 375px is the floor every surface is designed and measured at, touch targets are at least 44 x 44 CSS px, form fields at least 16px, reviews start from the phone capture, and performance is judged on the mobile Lighthouse profile. What is not a rule is now section 11 and says layout stays free at every width; the numbers are section 12. The older sections lose their em dashes to the house copy check, with the wording unchanged. Docs only.
+- 00d79a0: `craft copy` reads `title` and `description` in Markdown front matter. A dash or a stock phrase in an agent description or a page title is reported on that line, and `copy-ok` on the line or the line above still suppresses it. Other front matter keys stay unread, and fenced code stays unread.
+
+## 0.19.0
+
+### Minor Changes
+
+- 09b49ac: Fingerprint version 3: the estate comparison now measures ground temperature and section structure (DOM-637). A warm cream and a cool porcelain page used to score as the same "grey ground" because hue barely counts at a ground's chroma; `groundDistance` adds a temperature gap (warm, neutral, cool from hue, scaled by chroma) on top of ΔE, and shared grounds are named with it ("cream ground", "cool grey ground", "warm dark ground"). Two new distance parts, `rhythm` (the page's bands of light and dark in running order, the opening counted twice) and `hero` (text placement and width, headline class and size, which side the picture sits), give structure a quarter of the weight; `DISTANCE_WEIGHTS` is now accent 0.2, type 0.2, ground 0.1, shape 0.1, motion 0.05, effects 0.1, layout 0.1, rhythm 0.1, hero 0.05, and a part only one side measures is left out rather than counted as different, so version 1 and 2 fingerprints in a register or null model compare without being re-snapshotted. Shared traits name the structure too: "light hero then dark band", "left-aligned serif hero, photo right", "same running order". `craft snapshot` and `craft audit` take `--scheme light|dark` to ask the page for one colour scheme, and a snapshot's images record `left`. New exports: `groundDistance`, `groundTemperature`, `temperatureName`, `groundLabel`, `rhythmOf`, `rhythmDistance`, `heroDistance`, `bandOf`, `TEMPERATURE_FULL`, `TEMPERATURE_NAMED`, `TEMPERATURE_WEIGHT`, `OPENING_BANDS` and the `FingerprintHero`, `HeroImage`, `LightnessBand` and `Temperature` types. Calibrated on RMP Electrical against Bellerose Plumbing's stone and porcelain light modes (`calibration/estate/2026-10-09-temperature/`); the existing register's pair ordering keeps a Kendall tau of 0.83 and no pair crosses the sibling line.
+
 ## 0.18.2
 
 ### Patch Changes

package/CHARACTER.md

@@ -327,6 +327,7 @@ craft copy app content     # the prose a visitor reads
 craft tells list           # the catalogue this build judges against
 craft audit https://example.co.uk --repo .   # the rendered page and its source, one report
 craft snapshot https://example.co.uk --out home.json
+craft snapshot https://example.co.uk --scheme dark --out home-dark.json   # a site's dark mode
 ```
 
 `--json` gives the full report. Exit code is 0 on warnings, 1 on a block (or
@@ -369,11 +370,59 @@ anywhere with `craft audit home.json`. `HTTPS_PROXY` is honoured, and a
 `localhost` or `NO_PROXY` host is reached directly.
 
 Every audit also prints a **fingerprint**: accent and ground in OKLCh, the
-display and body faces, button roundness, reveal density, the effects and the
-running order. `fingerprintDistance` compares two of them, 0 to 1, weighted
-towards accent and type. Signals 2 and 3 are both this distance, measured
+display and body faces, button roundness, reveal density, the effects, the
+running order, the rhythm of light and dark bands, and the hero's
+composition. `fingerprintDistance` compares two of them, 0 to 1, as a
+weighted mean of nine parts. Signals 2 and 3 are both this distance, measured
 against different sets.
 
+| Part | Weight | What it measures |
+|---|---|---|
+| accent | 0.20 | ΔE_OK between the accents over 0.3; 1 when only one site has one |
+| type | 0.20 | display face (0.6) and body face (0.4): 0 same family, 0.5 same class, 1 |
+| ground | 0.10 | ΔE_OK over 0.15, plus 0.6 of the temperature gap (below) |
+| shape | 0.10 | button roundness, 0 square to 0.5 pill |
+| motion | 0.05 | share of below-the-fold sections that reveal on scroll |
+| effects | 0.10 | 1 minus the Jaccard overlap of the second-look effects |
+| layout | 0.10 | edit distance over section roles and geometry (kinds before snapshot v2) |
+| rhythm | 0.10 | edit distance over the bands of light, mid and dark, opening counted twice |
+| hero | 0.05 | text centred or left, its width, headline class and size, picture side |
+
+Accent and type carry the most because that is where a model's defaults show
+first and where a real business has something of its own. Structure (layout,
+rhythm and hero) carries a quarter between its three parts, because two sites
+that open the same way read as the same site before any colour is compared;
+before 0.19 structure was `layout` alone at a tenth and barely moved a score.
+A part only one side measures (rhythm and hero on a version 1 fingerprint,
+the picture side on a snapshot without image positions) is left out and the
+rest are weighed over what remains, so older registers and null models
+compare without being re-snapshotted.
+
+**Ground temperature.** ΔE alone files every light neutral page as one
+paper: RMP's cream (`oklch(0.96 0.010 82)`) and Bellerose's porcelain
+(`#F1F3F4`, `oklch(0.96 0.003 229)`) are ΔE 0.013 apart, a tenth of the
+ground scale, and nobody takes them for the same page. A page ground is the
+largest area on the page and the eye adapts to it, so a tint far below what
+separates two buttons still reads as warm or cool paper. `groundTemperature`
+is the chroma over 0.006 (where a tint is unmistakable: cream sits at 0.010,
+stone at 0.007), signed by hue: red through yellow is warm, teal through
+violet is cool, the greens and magentas between are neither. Warm against
+cool adds 0.6 to the ground part, warm against a neutral white 0.3, two warm
+papers nothing. Shared grounds are named with it: "cream ground", "cool grey
+ground", "warm dark ground", or "warm ground" when one is cream and the other
+a warm grey.
+
+**Rhythm** is the page's sequence of light (L 0.75 and over), mid and dark
+(under 0.4) bands, each run of same-lightness sections merged: a cream hero,
+a white logo strip and a near-black band are light then dark, which is what
+a visitor sees. The first three bands are scored once on their own and once
+as part of the whole, so the opening counts double. **Hero** compares the
+hero section's centring and width, the h1's class and size (an octave, 48px
+against 96px, is the whole size distance) and which side of the centre line
+its largest picture sits, when the snapshot records image positions (craft
+0.19 and later). Shared, they are named "light hero then dark band" and
+"left-aligned serif hero, photo right".
+
 Known limit: a computed font family is the family the stylesheet asked for.
 A face that failed to load is still reported under its name.
 
@@ -539,9 +588,15 @@ the same brief usually are: the median of that distance over the null models,
 0.31 on 2026-09-23 (`--null` measures it again from any null models given).
 If a barber and an electrician look more alike than two drafts of one barber,
 neither look was chosen. The report says what the pair shares in plain words
-("Fraunces headline", "no accent", "pill buttons"), which is where to start
-pulling them apart. A sibling is a warning; `--strict` exits 1 on one, for a
-pipeline that has decided to hold the line.
+("Fraunces headline", "no accent", "pill buttons", "cream ground", "light hero
+then dark band", "left-aligned serif hero, photo right"), which is where to
+start pulling them apart. A sibling is a warning; `--strict` exits 1 on one,
+for a pipeline that has decided to hold the line.
+
+A site with a light and a dark mode is two pages to a visitor. `craft
+snapshot <url> --scheme light|dark` asks the browser for one scheme
+(`prefers-color-scheme`); a site that stores a choice in `localStorage` or on
+`<html data-theme>` needs that set instead. Compare each.
 
 `craft direction propose --estate estate.json` reads the register too, so a
 proposed accent steers away from one a sibling already uses.
@@ -928,6 +983,22 @@ Rules for a direction board, recorded so the next one starts here:
 
 The board in question is the DD redesign's Stage 05 artefact (DOM-397, CRO-21); v1.1 applied all five.
 
+### Ground temperature and structure, 2026-10-09
+
+Bellerose Plumbing's light mode looked, to the founder, too much like RMP Electrical, and craft gave the pair 0.59 sharing only "grey ground". Bellerose then moved its light page from warm stone (`#EEEDE8`) to cool porcelain (`#F1F3F4`, bellerose-plumbing#32), and craft scored the two Bellerose pages 0.01 apart. Two things were missing: hue barely counts at a ground's chroma, and structure moved the score by a tenth at most. Fingerprint version 3 (DOM-637) adds ground temperature to the ground part, a rhythm part and a hero part, with the weights in *The rendered page* above. Measured on RMP live (2026-10-09) and Bellerose built locally at `c62590c` (stone, before #32) and `47f9d79` (porcelain), each snapshotted with `--scheme light` and `--scheme dark`; snapshots, a copy of the redesign workstream's register and the full tables are in `calibration/estate/2026-10-09-temperature/`. "Before" is craft 0.18.1's distance on the same snapshots.
+
+| Pair | Before | After | Shares after |
+|---|---|---|---|
+| RMP + Bellerose light on stone | 0.59 (cream ground) | **0.54** | warm ground, left-aligned serif hero, photo right, light hero then dark band |
+| RMP + Bellerose light on porcelain | 0.59 (cream ground) | 0.58 | left-aligned serif hero, photo right, light hero then dark band |
+| RMP + Bellerose dark (either) | 0.77 | 0.72 | left-aligned serif hero, photo right |
+| Bellerose stone light + porcelain light | 0.01 | 0.06 | everything but the ground |
+| RMP + RMP | 0.00 | 0.00 | |
+
+Against the register as it stands (stored version 2 fingerprints, not re-added), the stone page's nearest site is RMP (0.54) and the porcelain page's is Harrison James (0.52) with RMP second (0.58): the move away from RMP that the founder made by eye now shows in the numbers, and both Bellerose light pages still share the opening with RMP, which is the next thing to pull apart. Neither pair is a sibling; the faces, the accent and the button shape are their own.
+
+The seven register pairs reshuffle little: Kendall tau 0.83 between the before and after orderings over 21 pairs, the closest pair is still DD + RMP (0.48 to 0.52, now "warm ground" rather than "grey ground"), and no pair crosses the sibling line. Pairs that shared "white ground" and little else move apart by 0.02 to 0.06 as the temperature counts (MMM + Sensphere keep "cool white ground"); Chair and Blade + HJ Beauty move closer (0.74 to 0.66) because both open dark then light. The sibling line measured again on the seven v2 null models is 0.337 with the old distance and 0.339 with the new, so the weights do not move it; `SIBLING_AT` stays at the 0.31 measured on the v1 models in September, and moving it to the v2 line is a separate decision.
+
 ## The catalogue
 
 Generated from the package. Run `pnpm --filter @domandigital/craft run docs`

package/README.md

@@ -67,7 +67,7 @@ module.exports = { presets: [tailwindV3Preset()] };
 
 ## The standard itself
 
-[STANDARD.md](./STANDARD.md) is the eleven-section house standard, every numeric
+[STANDARD.md](./STANDARD.md) is the twelve-section house standard, every numeric
 rule cited, including a section on what is deliberately *not* a rule. Its
 canonical numbers are compared against the code on every test run, so the
 document cannot drift from what ships.

package/STANDARD.md

@@ -1,17 +1,18 @@
 # The Doman Digital craft standard
 
-Eleven sections. Every numeric rule is cited, and section 10 says what is
+Twelve sections. Every numeric rule is cited, and section 11 says what is
 deliberately *not* a rule.
 
 This document and the package are bound together by a test: the machine-readable
-block in section 11 is compared against `HOUSE_BUDGET`, `EASE` and
+block in section 12 is compared against `HOUSE_BUDGET`, `EASE` and
 `DURATION_MS` on every run, so the standard cannot drift from what ships.
 
 ---
 
+<!-- copy-ok: the standard names the practice each rule replaces -->
 ## 1. Colour is derived, not picked
 
-Anchors — colours a surface already ships — are sacred and come back byte-identical.
+Anchors, the colours a surface already ships, are sacred and come back byte-identical.
 Everything else is generated in OKLCh from those anchors.
 
 - Ramps have **11 steps** (50–950).
@@ -19,7 +20,7 @@ Everything else is generated in OKLCh from those anchors.
   (CSS Color 4 §13.2). RGB clipping is rejected: it walks a saturated violet
   toward magenta.
 - Derived values standing in for a hand-picked one must be within
-  **ΔE_OK ≤ 0.02** — the just-noticeable difference — or be declared an
+  **ΔE_OK ≤ 0.02** (the just-noticeable difference) or be declared an
   intentional change.
 
 *Source: Ottosson, "A perceptual color space for image processing" (2020); CSS Color 4 §13.2.*
@@ -40,9 +41,9 @@ Everything else is generated in OKLCh from those anchors.
 ## 3. Type is fluid, and always has a rem term
 
 - Steps **−2 to 5**, `clamp()` interpolated between a small and a large viewport.
-- The interpolation term is **`rem + vw`, never bare `vw`** — a bare-`vw` size
+- The interpolation term is **`rem + vw`, never bare `vw`**. A bare-`vw` size
   ignores the browser text-size setting and fails WCAG 1.4.4 at 200% zoom.
-- Existing sizes are **pinned**, not regenerated, so adopting the scale moves
+- Existing sizes are **pinned**, not regenerated, so adopting the scale moves <!-- copy-ok -->
   nothing.
 
 *Source: Utopia (utopia.fyi); WCAG 2.2 SC 1.4.4.*
@@ -58,7 +59,7 @@ Everything else is generated in OKLCh from those anchors.
 - Clipped display text gets a **descender mask** (`padding-bottom: .16em;
   margin-bottom: -.16em`), or it loses the tails of g, j, p, q, y.
 
-*Source: house habit — the −0.01em display tracking and the ch measure were arrived at independently in two client repos.*
+*Source: house habit. The −0.01em display tracking and the ch measure were arrived at independently in two client repos.*
 
 ## 5. Space is fluid and proportional to type
 
@@ -66,7 +67,7 @@ Everything else is generated in OKLCh from those anchors.
 - Section rhythm has **three** sizes, not five. Five shipped with zero consumers,
   which is the signature of a scale invented ahead of a need.
 
-*Source: Utopia; measured — `--space-section-xs..xl` had no consumers in the monorepo.*
+*Source: Utopia; measured: `--space-section-xs..xl` had no consumers in the monorepo.*
 
 ## 6. Density is a property of the surface
 
@@ -89,7 +90,7 @@ needs. Set once on a shell via `[data-density]`, inherited below.
   meaning it covers more ground per unit time arriving than it averaged.
 - **UI durations ≤ 300ms.** Drawers and one gated reveal may exceed it.
 - **Don't animate what fires 100×/day**, and never animate a keyboard-triggered
-  interaction — the user is moving faster than the animation.
+  interaction: the user is moving faster than the animation.
 - **One signature moment per page**, gated, never the LCP element.
 
 *Source: Emil Kowalski, "Animations on the Web"; Core Web Vitals (LCP).*
@@ -101,12 +102,12 @@ needs. Set once on a shell via `[data-density]`, inherited below.
 
 **Never `animation: none` inside the block.** That drops the `forwards` fill along with the
 animation, so a forwards-filled entrance never applies its end state and the
-element keeps `opacity: 0` from its base rule — permanently invisible, for
+element keeps `opacity: 0` from its base rule, permanently invisible, for
 exactly the users who asked for less motion. This shipped.
 
 Images: AVIF and WebP, in that order.
 
-*Source: WCAG 2.2 SC 2.3.3; measured — a live site was stranded at opacity 0 by this exact defect.*
+*Source: WCAG 2.2 SC 2.3.3; measured: a live site was stranded at opacity 0 by this exact defect.*
 
 ## 9. Restraint is the budget
 
@@ -118,11 +119,11 @@ step: `code { font-size: 0.875em }` states one relationship and applies it
 wherever code appears, rather than adding a rung to the ladder. Counting it
 against the scale is the same category error as counting the framework's theme.
 It is still counted, because eight competing ratios is as unreadable as eight
-competing steps — split, not dropped. A value that stops being reported is a
+competing steps: split, not dropped. A value that stops being reported is a
 value that grows.
 
 Differentiation guards pass anything that differs from its siblings, however
-ugly. What they cannot see is accumulation — eighteen font sizes, six shadows,
+ugly. What they cannot see is accumulation: eighteen font sizes, six shadows,
 four competing accents, each added reasonably, together reading as noise.
 
 The budget counts the vocabulary a surface **chose**, and the whole difficulty
@@ -141,7 +142,7 @@ second reports a pass.
 
 The line is **used versus unused**, which is not a property of the layer:
 
-- References are **resolved**, not skipped — through the token chain, to the
+- References are **resolved**, not skipped: through the token chain, to the <!-- copy-ok -->
   value that renders.
 - A definition is only ever reached from a declaration in a kept layer, so a
   framework default nothing uses still counts for nothing.
@@ -154,7 +155,34 @@ The line is **used versus unused**, which is not a property of the layer:
 
 *Source: measured against the estate. The budget is the observed ceiling of the surfaces that read as designed; the resolution rule is what it took to measure them at all.*
 
-## 10. What is deliberately not a rule
+## 10. The phone is the base layout
+
+Mobile first is a rule about **order and floor**, not about a layout. The phone
+is designed, built and measured first, and every wider layout is derived from
+it. A desktop layout squeezed onto a phone keeps the desktop's priorities and
+drops whatever did not fit; a phone layout widened keeps what matters and adds.
+
+- **The phone is the base.** Base styles are the phone layout. Wider layouts
+  are added with `min-width` queries only (Tailwind: unprefixed is the phone,
+  `sm:` `md:` `lg:` add). A `max-width` query, a `width <` range or a Tailwind
+  `max-*:` variant needs a recorded exception with its reason.
+- **375px is the floor.** Every surface is designed and measured at **375 CSS
+  px** first, the narrowest iPhone width in common use (SE, mini, X to 11 Pro).
+  Nothing scrolls sideways at 375. 390 is still measured: it is the width the
+  design is accepted at.
+- **Touch targets at least 44 × 44 CSS px.** A link inside a sentence is exempt,
+  as in WCAG's own inline exception. 24px (SC 2.5.8, AA) is what an audit asks
+  for; 44 is the house bar.
+- **Form inputs at least 16px.** Safari on iOS zooms the page when a field set
+  smaller gets focus, and the visitor has to pinch back out. Fix the size, never
+  the viewport: `maximum-scale=1` takes zoom away from people who need it.
+- **Reviews look at the phone capture first**, then the desktop one.
+- **Performance is judged on the mobile Lighthouse profile.** A desktop score
+  is not evidence: the phone is the slower device and the one Google indexes.
+
+*Source: WCAG 2.2 SC 2.5.5 (Target Size, Enhanced), SC 2.5.8 and SC 1.4.4; Apple Human Interface Guidelines, "Accessibility" (44 × 44 pt hit targets); WebKit's focus zoom on fields under 16px; Lighthouse's default mobile emulation; Google Search Central, "Mobile-first indexing"; Luke Wroblewski, "Mobile First" (2011).*
+
+## 11. What is deliberately not a rule
 
 The package emits **plain CSS custom properties** precisely so these stay free:
 
@@ -162,9 +190,11 @@ The package emits **plain CSS custom properties** precisely so these stay free:
   two; the third needs nothing.
 - **The motion library.** `EASE_TUPLE` carries the same control points as `EASE`,
   so Framer Motion, GSAP and CSS agree without the package choosing one.
-- **Where tokens live.** A `:root` block, a generated file, a Tailwind theme —
+- **Where tokens live.** A `:root` block, a generated file, a Tailwind theme:
   the package does not care.
-- **Layout, grid and component structure.** Not a rule. Layout *defaults*
+- **Layout, grid and component structure.** Not a rule, at any width. Section
+  10 fixes the order the widths are designed in and the floor they are
+  measured at; what the phone layout looks like stays free. Layout *defaults*
   (hero straight into a trust strip, three icon cards, a reveal on every
   section) are measured as character in [CHARACTER.md](./CHARACTER.md), as
   warnings with a declared-exception path, never as rules here.
@@ -172,7 +202,7 @@ The package emits **plain CSS custom properties** precisely so these stay free:
 
 A rule here has to be one that is wrong to break. Everything else is a default.
 
-## 11. The numbers
+## 12. The numbers
 
 <!-- craft:canonical -->
 ```json

package/dist/{audit-4SFSLCKY.js → audit-43PC4LMS.js}

@@ -9,10 +9,10 @@ import {
   snapshotPage,
   snapshotUrl,
   snapshotUrls
-} from "./chunk-SL5VZJ2J.js";
+} from "./chunk-VDUIIWG7.js";
 import "./chunk-JYNXGCYZ.js";
-import "./chunk-WFB6F3BN.js";
-import "./chunk-4QWEAL4G.js";
+import "./chunk-WK2WMWTH.js";
+import "./chunk-CZ7KT452.js";
 import "./chunk-QYBAVU3P.js";
 export {
   PROVENANCE_BUDGET_MS,

package/dist/audit.cjs

@@ -3292,7 +3292,7 @@ var RENDERED_PATHS = {
 };
 
 // src/fingerprint/index.ts
-var FINGERPRINT_VERSION = 2;
+var FINGERPRINT_VERSION = 3;
 var CHROMATIC = 0.03;
 var MIN_ACCENT_AREA = 2e4;
 var oklch = (value) => {
@@ -3328,6 +3328,24 @@ function median(values) {
   const mid = Math.floor(sorted.length / 2);
   return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
 }
+var FULL_WIDTH_IMAGE = 0.8;
+function heroOf(s) {
+  const h1 = s.headings.find((h) => h.level === 1);
+  const inside = (top, x) => top >= x.top && top < x.top + x.height;
+  const index = (() => {
+    const withH1 = h1 ? s.sections.findIndex((x) => x.kind === "hero" && inside(h1.top, x)) : -1;
+    return withH1 >= 0 ? withH1 : s.sections.findIndex((x) => x.kind === "hero");
+  })();
+  if (index < 0) return void 0;
+  const section = s.sections[index];
+  const headline = h1 && inside(h1.top, section) ? { sizePx: h1.sizePx, weight: h1.weight, class: fontClass(normaliseFamily(h1.family)), italic: h1.italic || h1.italicPart } : null;
+  if (!s.images) return { headline };
+  const picture2 = s.images.filter((i) => (i.role === "photo" || i.role === "illustration") && (i.section === index || i.section === null && inside(i.top, section))).sort((a, b) => b.width * b.height - a.width * a.height)[0];
+  if (!picture2) return { headline, image: "none" };
+  if (picture2.left === void 0) return { headline };
+  const image = picture2.width >= FULL_WIDTH_IMAGE * s.viewport.width ? "full" : picture2.left + picture2.width / 2 < s.viewport.width / 2 ? "left" : "right";
+  return { headline, image };
+}
 function fingerprint(s) {
   const effects = [];
   if (s.effects.glass > 0) effects.push("glass-panel");
@@ -3339,6 +3357,7 @@ function fingerprint(s) {
   if (s.effects.eyebrowChip) effects.push("hero-eyebrow-chip");
   if (s.motion.introOverlay) effects.push("intro-cinematic");
   const below = s.sections.filter((x) => x.top > s.viewport.height).length;
+  const hero = heroOf(s);
   return {
     version: FINGERPRINT_VERSION,
     accent: accentOf(s),
@@ -3362,7 +3381,8 @@ function fingerprint(s) {
         carousel: x.carousel ?? false,
         figures: x.figures ?? 0
       }))
-    } : {}
+    } : {},
+    ...hero ? { hero } : {}
   };
 }
 var ACCENT_SCALE = 0.3;
@@ -4314,6 +4334,7 @@ function collectInPage() {
       width: Math.round(b.width),
       height: Math.round(b.height),
       top: Math.round(b.top),
+      left: Math.round(b.left),
       role: roleOfImage(el, src, b.width, b.height, alt),
       alt,
       decorative,
@@ -4633,7 +4654,7 @@ async function snapshotUrls(urls, options = {}) {
   const out = [];
   try {
     for (const url of urls) {
-      const page = await browser.newPage({ viewport: options.viewport ?? { width: 1440, height: 900 } });
+      const page = await browser.newPage({ viewport: options.viewport ?? { width: 1440, height: 900 }, ...options.colorScheme ? { colorScheme: options.colorScheme } : {} });
       try {
         const response = await page.goto(url, { waitUntil: "domcontentloaded", timeout: options.timeoutMs ?? 45e3 });
         const status = typeof response?.status === "function" ? response.status() : 200;

package/dist/audit.d.cts

@@ -134,6 +134,8 @@ interface SnapshotImage {
     width: number;
     height: number;
     top: number;
+    /** Version 2, craft 0.19 and later: distance from the viewport's left edge, so a hero can say which side its picture sits. */
+    left?: number;
     role: ImageRole;
     alt: string | null;
     /** Empty alt, `aria-hidden` or `role="presentation"`. */
@@ -412,8 +414,26 @@ interface FingerprintSection {
     /** Large standalone figures. */
     figures?: number;
 }
+/** Where the hero's largest picture sits, relative to the headline. */
+type HeroImage = "left" | "right" | "full" | "none";
+/** The hero's composition: the first thing two sites are compared on by eye. */
+interface FingerprintHero {
+    /** The headline (the first h1 inside the hero), or null when the hero has none. */
+    headline: {
+        sizePx: number;
+        weight: number;
+        class: FontClass;
+        italic: boolean;
+    } | null;
+    /**
+     * The largest photo or illustration in the hero: beside the text (left or
+     * right of the viewport's centre line), `full` when it spans the width,
+     * `none` without one. Absent when the snapshot predates image positions.
+     */
+    image?: HeroImage;
+}
 interface Fingerprint {
-    version: 1 | 2;
+    version: 1 | 2 | 3;
     /** The most prominent chromatic colour: button fills first, then painted area, then text. */
     accent: Oklch | null;
     ground: Oklch;
@@ -435,6 +455,8 @@ interface Fingerprint {
     layout: SectionKind[];
     /** Version 2: present when every section carries a role and geometry. */
     sections?: FingerprintSection[];
+    /** Version 3: present when the page has a hero section. */
+    hero?: FingerprintHero;
 }
 
 /**
@@ -480,6 +502,12 @@ interface SnapshotOptions {
     visual?: boolean;
     /** Read the first bytes of the page's larger images for AI provenance markers. Default true. */
     provenance?: boolean;
+    /**
+     * The colour scheme the page is asked for (`prefers-color-scheme`). A site
+     * with a light and a dark mode is two pages to the visitor; snapshot each.
+     * Default: the browser's own, which is light in headless Chromium.
+     */
+    colorScheme?: "light" | "dark";
 }
 interface MinimalPage {
     close?(): Promise<void>;
@@ -523,6 +551,7 @@ interface MinimalBrowser {
             width: number;
             height: number;
         };
+        colorScheme?: "light" | "dark";
     }): Promise<MinimalPage>;
     close(): Promise<void>;
 }

package/dist/audit.d.ts

@@ -134,6 +134,8 @@ interface SnapshotImage {
     width: number;
     height: number;
     top: number;
+    /** Version 2, craft 0.19 and later: distance from the viewport's left edge, so a hero can say which side its picture sits. */
+    left?: number;
     role: ImageRole;
     alt: string | null;
     /** Empty alt, `aria-hidden` or `role="presentation"`. */
@@ -412,8 +414,26 @@ interface FingerprintSection {
     /** Large standalone figures. */
     figures?: number;
 }
+/** Where the hero's largest picture sits, relative to the headline. */
+type HeroImage = "left" | "right" | "full" | "none";
+/** The hero's composition: the first thing two sites are compared on by eye. */
+interface FingerprintHero {
+    /** The headline (the first h1 inside the hero), or null when the hero has none. */
+    headline: {
+        sizePx: number;
+        weight: number;
+        class: FontClass;
+        italic: boolean;
+    } | null;
+    /**
+     * The largest photo or illustration in the hero: beside the text (left or
+     * right of the viewport's centre line), `full` when it spans the width,
+     * `none` without one. Absent when the snapshot predates image positions.
+     */
+    image?: HeroImage;
+}
 interface Fingerprint {
-    version: 1 | 2;
+    version: 1 | 2 | 3;
     /** The most prominent chromatic colour: button fills first, then painted area, then text. */
     accent: Oklch | null;
     ground: Oklch;
@@ -435,6 +455,8 @@ interface Fingerprint {
     layout: SectionKind[];
     /** Version 2: present when every section carries a role and geometry. */
     sections?: FingerprintSection[];
+    /** Version 3: present when the page has a hero section. */
+    hero?: FingerprintHero;
 }
 
 /**
@@ -480,6 +502,12 @@ interface SnapshotOptions {
     visual?: boolean;
     /** Read the first bytes of the page's larger images for AI provenance markers. Default true. */
     provenance?: boolean;
+    /**
+     * The colour scheme the page is asked for (`prefers-color-scheme`). A site
+     * with a light and a dark mode is two pages to the visitor; snapshot each.
+     * Default: the browser's own, which is light in headless Chromium.
+     */
+    colorScheme?: "light" | "dark";
 }
 interface MinimalPage {
     close?(): Promise<void>;
@@ -523,6 +551,7 @@ interface MinimalBrowser {
             width: number;
             height: number;
         };
+        colorScheme?: "light" | "dark";
     }): Promise<MinimalPage>;
     close(): Promise<void>;
 }

package/dist/audit.js

@@ -3257,7 +3257,7 @@ var RENDERED_PATHS = {
 };
 
 // src/fingerprint/index.ts
-var FINGERPRINT_VERSION = 2;
+var FINGERPRINT_VERSION = 3;
 var CHROMATIC = 0.03;
 var MIN_ACCENT_AREA = 2e4;
 var oklch = (value) => {
@@ -3293,6 +3293,24 @@ function median(values) {
   const mid = Math.floor(sorted.length / 2);
   return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
 }
+var FULL_WIDTH_IMAGE = 0.8;
+function heroOf(s) {
+  const h1 = s.headings.find((h) => h.level === 1);
+  const inside = (top, x) => top >= x.top && top < x.top + x.height;
+  const index = (() => {
+    const withH1 = h1 ? s.sections.findIndex((x) => x.kind === "hero" && inside(h1.top, x)) : -1;
+    return withH1 >= 0 ? withH1 : s.sections.findIndex((x) => x.kind === "hero");
+  })();
+  if (index < 0) return void 0;
+  const section = s.sections[index];
+  const headline = h1 && inside(h1.top, section) ? { sizePx: h1.sizePx, weight: h1.weight, class: fontClass(normaliseFamily(h1.family)), italic: h1.italic || h1.italicPart } : null;
+  if (!s.images) return { headline };
+  const picture2 = s.images.filter((i) => (i.role === "photo" || i.role === "illustration") && (i.section === index || i.section === null && inside(i.top, section))).sort((a, b) => b.width * b.height - a.width * a.height)[0];
+  if (!picture2) return { headline, image: "none" };
+  if (picture2.left === void 0) return { headline };
+  const image = picture2.width >= FULL_WIDTH_IMAGE * s.viewport.width ? "full" : picture2.left + picture2.width / 2 < s.viewport.width / 2 ? "left" : "right";
+  return { headline, image };
+}
 function fingerprint(s) {
   const effects = [];
   if (s.effects.glass > 0) effects.push("glass-panel");
@@ -3304,6 +3322,7 @@ function fingerprint(s) {
   if (s.effects.eyebrowChip) effects.push("hero-eyebrow-chip");
   if (s.motion.introOverlay) effects.push("intro-cinematic");
   const below = s.sections.filter((x) => x.top > s.viewport.height).length;
+  const hero = heroOf(s);
   return {
     version: FINGERPRINT_VERSION,
     accent: accentOf(s),
@@ -3327,7 +3346,8 @@ function fingerprint(s) {
         carousel: x.carousel ?? false,
         figures: x.figures ?? 0
       }))
-    } : {}
+    } : {},
+    ...hero ? { hero } : {}
   };
 }
 var ACCENT_SCALE = 0.3;
@@ -4279,6 +4299,7 @@ function collectInPage() {
       width: Math.round(b.width),
       height: Math.round(b.height),
       top: Math.round(b.top),
+      left: Math.round(b.left),
       role: roleOfImage(el, src, b.width, b.height, alt),
       alt,
       decorative,
@@ -4598,7 +4619,7 @@ async function snapshotUrls(urls, options = {}) {
   const out = [];
   try {
     for (const url of urls) {
-      const page = await browser.newPage({ viewport: options.viewport ?? { width: 1440, height: 900 } });
+      const page = await browser.newPage({ viewport: options.viewport ?? { width: 1440, height: 900 }, ...options.colorScheme ? { colorScheme: options.colorScheme } : {} });
       try {
         const response = await page.goto(url, { waitUntil: "domcontentloaded", timeout: options.timeoutMs ?? 45e3 });
         const status = typeof response?.status === "function" ? response.status() : 200;