@domandigital/craft 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @domandigital/craft
 
+## 0.18.1
+
+### Patch Changes
+
+- 72c3463: `gradientContrast` no longer blends across a hard stop. A gradient such as `linear-gradient(90deg, #000 50%, #fff 50%)` is painted as a jump from black to white, but 0.18.0 sampled the greys between them and could fail text that clears every colour the browser actually paints. Stop positions are now read, and a stop placed at or before an earlier position starts a hard edge that is not sampled, as in CSS. A painted blend is still sampled between its stops. Found by Codex review on Doman-Digital/dd-drift-guards#8, where the same fix landed.
+
+## 0.18.0
+
+### Minor Changes
+
+- 1c08793: Two build gates from dd-drift-guards are now part of craft, so that repo can be archived. `gradientContrast(text, gradient, beneath)` scores text on a CSS gradient, the case axe-core and Lighthouse leave unscored, against the worst point of the gradient composited over what sits beneath. It samples between the stops as well as at them: the drift-guards version checked the stops only, and passed mid-grey text on a black-to-white gradient that is about 1:1 in the middle. `checkPhotoReview(text, options)` gates a build on the report `halide review --json` wrote, failing a weak image under a passing average, a truncated report and, unless `required: false`, a missing one.
+
 ## 0.17.0
 
 ### Minor Changes

package/CHARACTER.md

@@ -894,6 +894,24 @@ same on all seven: the display face. It is the estate's common default, and
 the one choice the retrofits (phase G) should settle first. Not yet read by a
 person.
 
+### Recalibration on snapshot v2, 2026-09-30
+
+The estate and the seven null models were still on snapshot v1 (the AI set and the human set were re-snapshotted on 2026-09-29). This run moves them to v2 and changes nothing else: the same 140 null pages (each `calibration/null/<name>/pages/`, copied into `<name>-v2/`, so no model was called and the model is not a confound; the original build recorded its model as `default`) were re-snapshotted with `craft null build`, and the seven live home pages were re-snapshotted on 2026-09-30 into `calibration/estate/2026-09-30-v2/` and a new register, `estate/estate-v2.json`. The v1 folders and the 2026-09-23 snapshots are untouched. The `-v2` folders hold `null.json` and `snapshots/` only: their `pages/` are byte-for-byte the v1 pages, so to rebuild copy `<name>/pages/` across and rerun the same `craft null build`. Scoring is `calibration/null/score-v2.mjs` (the same method as `score.mjs`; the AI set is read from the v2 snapshots in `calibration/results/2026-09-29-wider/`). Outputs: `null/results-v2.json`, `null/score-v2.txt`, `null/harvest-v2.txt`, `estate/compare-2026-09-30-v2.txt`. The live sites may have changed since 2026-09-23, so the estate rows also move for that reason.
+
+| Measure | Before (v1) | After (v2) |
+|---|---|---|
+| Estate typicality against its own brief's null (own): dd, mmm, sensphere, harrison-james, hj-beauty, chair-and-blade, rmp | 0.15, 0.05, 0.00, 0.10, 0.05, 0.05, 0.05 | 0.10, 0.05, 0.00, 0.10, 0.05, 0.05, 0.05 |
+| Estate typicality against all seven pooled (same order) | 0.01, 0.00, 0.00, 0.09, 0.00, 0.01, 0.26 | 0.01, 0.00, 0.00, 0.10, 0.00, 0.01, 0.21 |
+| Distance to own null (same order) | 0.340, 0.450, 0.503, 0.277, 0.442, 0.361, 0.518 | 0.443, 0.420, 0.530, 0.304, 0.479, 0.381, 0.558 |
+| Sibling pairs in the estate (below 0.31) | 1 (dd + hjbeauty, 0.28) | 0 (dd + hjbeauty is now 0.58; closest pair is dd + rmp, 0.48) |
+| Null pages flagged when scored against the other six briefs (dd, mmm, sensphere, harrison-james, hj-beauty, chair-and-blade, rmp) | 20, 20, 19, 20, 19, 18, 15 of 20 | 20, 20, 20, 20, 20, 18, 18 of 20 |
+| Null pages typical against the other six (same order) | 13, 10, 10, 12, 10, 4, 2 | 14, 8, 9, 13, 6, 7, 3 |
+| AI set flagged against the pooled v2 null | 19 of 20 | 20 of 20 (typical 15, tell-heavy 20) |
+
+What moved: the estate is still atypical of what the model builds for its own brief (own typicality 0.10 or lower on all seven), and only RMP Electrical is close to the pooled null (0.21, down from 0.26; its shared traits are a hero eyebrow chip and pill buttons). The one sibling pair, Doman Digital and Harrisons Beauty, is no longer one; the pair that stays closest is Doman Digital and RMP Electrical (0.48). The AI set gained one flagged page (the 20 of 20 the flagged-rule decision records). Because the live sites were not frozen, the estate movement mixes the snapshot version with site changes, and this run cannot separate them.
+
+`craft tells harvest` on the v2 models gives the same three candidates as before (red accent #e77a63, 66 of 140; square shape, 47 of 140; the opening `hero > hero > cards`, 54 of 140) and 40 recurring phrases (the same count as before; the list was not diffed line by line). The only difference is in the already-caught list, which now includes `no-real-imagery` (117 of 140), `hero-eyebrow-chip` (53), `stats-row` (42) and `unproven-claim` (35): tells that came in with snapshot v2 and later phases, which the v1 harvest could not see. Nothing was added to the catalogue, and no tell or threshold changed.
+
 ## The catalogue
 
 Generated from the package. Run `pnpm --filter @domandigital/craft run docs`

package/README.md

@@ -200,13 +200,36 @@ the house APCA bar, which is the failure mode a WCAG-only check cannot see. The
 accent fork emits its measured ratios as a CSS comment, so the choice is
 checkable rather than asserted.
 
+## Build gates folded in from drift-guards
+
+Two checks that lived only in `Doman-Digital/dd-drift-guards` (pinned by git tag
+in a few client repos) are part of craft since 0.18.0. The other three guards
+there were already here: restraint (`checkRestraint`), reduced motion (a
+restraint rule) and art direction (`craft direction`, `craft estate`).
+
+- **`gradientContrast(text, gradient, beneath)`**: text on a CSS gradient, the
+  case axe-core and Lighthouse mark "incomplete" and never score. It composites
+  the gradient over what sits beneath and scores the text, WCAG and APCA,
+  against the worst point. The worst point is sampled along every segment, not
+  only at the stops: mid-grey text on a black-to-white gradient clears 4.5:1
+  against both ends and is about 1:1 in the middle, which the drift-guards
+  version passed. A hard stop (`#000 50%, #fff 50%`) is a jump the browser
+  paints without a blend, so it is not sampled across. WCAG defines no method for gradients, so this is craft's
+  rule, not a conformance claim.
+- **`checkPhotoReview(text, { minScore, required })`**: gates a build on the
+  report `halide review --json` wrote. It takes the report's text (null when
+  there is none) and never runs halide. One weak image fails the build even
+  under a passing average, and a truncated report fails rather than reading as
+  "no report".
+
 ## API
 
 | Area | Exports |
 | --- | --- |
 | Colour space | `hexToOklch`, `oklchToHex`, `toGamut`, `inSrgbGamut`, `inP3Gamut`, `deltaEOk`, `deltaEOkHex` |
 | Ramps | `ramp`, `rampFromAnchors`, `RAMP_STEPS`, `LIGHTNESS_CURVE` |
-| Contrast | `wcagContrast`, `apcaContrast`, `checkPair` |
+| Contrast | `wcagContrast`, `apcaContrast`, `checkPair`, `gradientContrast`, `gradientStops` |
+| Photography | `checkPhotoReview` |
 | Semantic | `semantic`, `accentFork` |
 | Motion | `EASE`, `EASE_TUPLE`, `DURATION_MS`, `DURATION_S`, `SPRING`, `SCALE`, `exitDuration`, `shouldAnimate` |
 | Type | `fluidType`, `fluidClamp`, `typeFeatureTokens`, `HOUSE_TYPE`, `TYPE_STEPS` |

package/dist/index.cjs

@@ -97,6 +97,7 @@ __export(index_exports, {
   RENDERED_TELLS: () => RENDERED_TELLS,
   REVEAL_LIMIT: () => REVEAL_LIMIT,
   REVIEW_PHRASES: () => REVIEW_PHRASES,
+  SAMPLES_PER_SEGMENT: () => SAMPLES_PER_SEGMENT,
   SCALE: () => SCALE,
   SECTION_ROLES: () => SECTION_ROLES,
   SHADCN_LIMIT: () => SHADCN_LIMIT,
@@ -134,6 +135,7 @@ __export(index_exports, {
   checkCopy: () => checkCopy,
   checkOrder: () => checkOrder,
   checkPair: () => checkPair,
+  checkPhotoReview: () => checkPhotoReview,
   checkReason: () => checkReason,
   checkRegister: () => checkRegister,
   checkRestraint: () => checkRestraint,
@@ -187,6 +189,8 @@ __export(index_exports, {
   formatReport: () => formatReport,
   getRegister: () => getRegister,
   globToRegExp: () => globToRegExp,
+  gradientContrast: () => gradientContrast,
+  gradientStops: () => gradientStops,
   groundName: () => groundName,
   harvest: () => harvest,
   hedgeCount: () => hedgeCount,
@@ -586,6 +590,274 @@ function checkPair(text, background) {
   };
 }
 
+// src/character/color.ts
+var COLOUR = /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3,4}\b|\b(?:rgba?|hsla?|oklch|oklab)\([^)]*\)|\bcolor\(\s*srgb\b[^)]*\)/g;
+function num(token, percentOf) {
+  const t = token.trim();
+  if (t.endsWith("%")) return parseFloat(t) / 100 * percentOf;
+  return parseFloat(t);
+}
+function parts(fn) {
+  const inner = fn.slice(fn.indexOf("(") + 1, -1).trim();
+  const [main, slashAlpha] = inner.split("/");
+  const channels = main.split(/[\s,]+/).filter(Boolean);
+  let alpha = 1;
+  if (slashAlpha !== void 0) alpha = num(slashAlpha, 1);
+  else if (channels.length === 4) alpha = num(channels.pop(), 1);
+  return { channels, alpha: Number.isFinite(alpha) ? alpha : 1 };
+}
+function hslToRgb(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f4 = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return { r: f4(0), g: f4(8), b: f4(4) };
+}
+var clamp012 = (n) => Math.min(1, Math.max(0, n));
+function parseColour(raw) {
+  try {
+    if (raw.startsWith("#")) {
+      const hex2 = raw.slice(1);
+      const alpha2 = hex2.length === 8 ? parseInt(hex2.slice(6), 16) / 255 : hex2.length === 4 ? parseInt(hex2[3] + hex2[3], 16) / 255 : 1;
+      return { oklch: hexToOklch(raw), alpha: alpha2 };
+    }
+    const fn = raw.slice(0, raw.indexOf("(")).toLowerCase();
+    if (fn === "color") {
+      const { channels: channels2, alpha: alpha2 } = parts(raw.replace(/^color\(\s*srgb\s+/i, "srgb("));
+      const [r, g, b] = channels2.map((c) => clamp012(num(c, 1)));
+      if (![r, g, b].every(Number.isFinite)) return null;
+      return { oklch: hexToOklch(formatHex({ r, g, b })), alpha: alpha2 };
+    }
+    const { channels, alpha } = parts(raw);
+    if (channels.length < 3 || channels.some((c) => c.startsWith("var"))) return null;
+    if (fn === "oklch") {
+      const l = num(channels[0], 1);
+      const c = num(channels[1], 0.4);
+      const h = parseFloat(channels[2]);
+      if (![l, c].every(Number.isFinite)) return null;
+      return { oklch: { l, c, h: Number.isFinite(h) ? h : 0 }, alpha };
+    }
+    if (fn === "oklab") {
+      const l = num(channels[0], 1);
+      const a = num(channels[1], 0.4);
+      const b = num(channels[2], 0.4);
+      if (![l, a, b].every(Number.isFinite)) return null;
+      const c = Math.sqrt(a * a + b * b);
+      const h = c < 1e-7 ? 0 : (Math.atan2(b, a) * 180 / Math.PI % 360 + 360) % 360;
+      return { oklch: { l, c, h }, alpha };
+    }
+    if (fn === "rgb" || fn === "rgba") {
+      const [r, g, b] = channels.map((c) => clamp012(num(c, 255) / 255));
+      if (![r, g, b].every(Number.isFinite)) return null;
+      return { oklch: hexToOklch(formatHex({ r, g, b })), alpha };
+    }
+    if (fn === "hsl" || fn === "hsla") {
+      const h = parseFloat(channels[0]);
+      const s = num(channels[1], 1);
+      const l = num(channels[2], 1);
+      if (![h, s, l].every(Number.isFinite)) return null;
+      const rgb = hslToRgb((h % 360 + 360) % 360, clamp012(s), clamp012(l));
+      return { oklch: hexToOklch(formatHex(rgb)), alpha };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function findColours(value) {
+  const out = [];
+  for (const m of value.matchAll(COLOUR)) {
+    const parsed = parseColour(m[0]);
+    if (parsed) out.push({ raw: m[0], ...parsed, index: m.index ?? 0 });
+  }
+  return out;
+}
+var AI_VIOLET = { hueMin: 268, hueMax: 312, minChroma: 0.1, minL: 0.3, maxL: 0.85 };
+function isAiViolet({ l, c, h }) {
+  return c >= AI_VIOLET.minChroma && h >= AI_VIOLET.hueMin && h <= AI_VIOLET.hueMax && l >= AI_VIOLET.minL && l <= AI_VIOLET.maxL;
+}
+function isCream({ l, c, h }) {
+  return l >= 0.9 && l <= 0.985 && c >= 8e-3 && c <= 0.06 && h >= 55 && h <= 105;
+}
+function isBlueToPurple({ c, h }) {
+  return c >= 0.08 && h >= 240 && h <= 330;
+}
+
+// src/color/gradient.ts
+var KEYWORDS = {
+  white: { r: 1, g: 1, b: 1, a: 1 },
+  black: { r: 0, g: 0, b: 0, a: 1 },
+  transparent: { r: 0, g: 0, b: 0, a: 0 }
+};
+var clamp013 = (n) => Math.min(1, Math.max(0, n));
+function toRgba(raw) {
+  const value = raw.trim().toLowerCase();
+  if (KEYWORDS[value]) return KEYWORDS[value];
+  if (/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(value)) {
+    const h = value.length <= 5 ? [...value.slice(1)].map((c) => c + c).join("") : value.slice(1);
+    const { r: r2, g: g2, b: b2 } = parseHex(h.slice(0, 6));
+    return { r: r2, g: g2, b: b2, a: h.length === 8 ? parseInt(h.slice(6), 16) / 255 : 1 };
+  }
+  const rgb = /^rgba?\(([^)]+)\)$/.exec(value);
+  if (rgb) {
+    const parts2 = rgb[1].split(/[\s,/]+/).filter(Boolean);
+    const channel = (p) => p.endsWith("%") ? parseFloat(p) / 100 : parseFloat(p) / 255;
+    const alpha = parts2[3] === void 0 ? 1 : parts2[3].endsWith("%") ? parseFloat(parts2[3]) / 100 : parseFloat(parts2[3]);
+    const [r2, g2, b2] = parts2.slice(0, 3).map(channel);
+    if (parts2.length >= 3 && [r2, g2, b2, alpha].every(Number.isFinite)) return { r: clamp013(r2), g: clamp013(g2), b: clamp013(b2), a: clamp013(alpha) };
+    return null;
+  }
+  const parsed = parseColour(value);
+  if (!parsed) return null;
+  const { r, g, b } = oklchToRgb(parsed.oklch);
+  return { r: clamp013(r), g: clamp013(g), b: clamp013(b), a: clamp013(parsed.alpha) };
+}
+var SAMPLES_PER_SEGMENT = 256;
+function mix(a, b, t) {
+  const alpha = a.a + (b.a - a.a) * t;
+  if (alpha === 0) return { r: 0, g: 0, b: 0, a: 0 };
+  const ch = (x, y) => (x * a.a + (y * b.a - x * a.a) * t) / alpha;
+  return { r: ch(a.r, b.r), g: ch(a.g, b.g), b: ch(a.b, b.b), a: alpha };
+}
+function composite(top, under) {
+  return {
+    r: top.r * top.a + under.r * (1 - top.a),
+    g: top.g * top.a + under.g * (1 - top.a),
+    b: top.b * top.a + under.b * (1 - top.a)
+  };
+}
+function gradientStops(gradient) {
+  return parseStops(gradient).map((s) => s.colour);
+}
+function parseStops(gradient) {
+  const inner = /gradient\(([\s\S]*)\)\s*$/.exec(gradient.trim());
+  if (!inner) throw new Error(`not a CSS gradient: ${gradient}`);
+  const parts2 = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of inner[1]) {
+    if (ch === "(") depth += 1;
+    if (ch === ")") depth -= 1;
+    if (ch === "," && depth === 0) {
+      parts2.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) parts2.push(current.trim());
+  const stops = [];
+  for (const part of parts2) {
+    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(part)) continue;
+    const positions = [];
+    let colour = part;
+    for (let i = 0; i < 2; i++) {
+      const m = /\s+(-?[\d.]+)(%|px|r?em|vw|vh|deg|turn|rad|grad)\s*$/i.exec(colour);
+      if (!m) break;
+      positions.unshift({ value: parseFloat(m[1]), unit: m[2].toLowerCase() });
+      colour = colour.slice(0, m.index);
+    }
+    colour = colour.trim();
+    if (!toRgba(colour)) throw new Error(`unreadable gradient stop "${colour}" in ${gradient}`);
+    stops.push({ colour, positions });
+  }
+  if (stops.length === 0) throw new Error(`no colour stops in ${gradient}`);
+  return stops;
+}
+function blendedSegments(stops) {
+  const entries = [];
+  for (const s of stops) {
+    const rgba = toRgba(s.colour);
+    if (s.positions.length === 0) entries.push({ rgba, pos: null });
+    for (const pos of s.positions) entries.push({ rgba, pos });
+  }
+  const furthest = {};
+  const pairs = [];
+  for (let i = 0; i + 1 < entries.length; i++) {
+    const pos = entries[i].pos;
+    if (pos) furthest[pos.unit] = Math.max(furthest[pos.unit] ?? -Infinity, pos.value);
+    const next = entries[i + 1].pos;
+    const hard = next !== null && furthest[next.unit] !== void 0 && next.value <= furthest[next.unit];
+    if (!hard) pairs.push([entries[i].rgba, entries[i + 1].rgba]);
+  }
+  return pairs;
+}
+function gradientContrast(text, gradient, beneath = "#ffffff") {
+  const under = toRgba(beneath);
+  if (!under || under.a < 1) throw new Error(`beneath must be an opaque colour, got ${beneath}`);
+  const fg = toRgba(text);
+  if (!fg || fg.a < 1) throw new Error(`text must be an opaque colour, got ${text}`);
+  const textHex = formatHex(fg);
+  const parsed = parseStops(gradient);
+  const stops = parsed.map((s) => formatHex(composite(toRgba(s.colour), under)));
+  let worst = stops[0];
+  let worstRatio = wcagContrast(textHex, worst);
+  for (const s of stops) {
+    const ratio = wcagContrast(textHex, s);
+    if (ratio < worstRatio) [worst, worstRatio] = [s, ratio];
+  }
+  for (const [a, b] of blendedSegments(parsed)) {
+    for (let k = 1; k < SAMPLES_PER_SEGMENT; k++) {
+      const point = formatHex(composite(mix(a, b, k / SAMPLES_PER_SEGMENT), under));
+      const ratio = wcagContrast(textHex, point);
+      if (ratio < worstRatio) [worst, worstRatio] = [point, ratio];
+    }
+  }
+  const wcag = wcagContrast(textHex, worst);
+  const lc = apcaContrast(textHex, worst);
+  return {
+    text,
+    gradient,
+    beneath,
+    stops,
+    worst,
+    wcag,
+    lc,
+    passesAA: wcag >= 4.5,
+    passesAALarge: wcag >= 3,
+    note: `${text} on ${gradient} over ${beneath}: worst point ${worst}, ${wcag.toFixed(2)}:1, Lc ${lc.toFixed(1)}`
+  };
+}
+
+// src/photo/review.ts
+function checkPhotoReview(text, options = {}) {
+  const minScore = options.minScore ?? 0.7;
+  const required = options.required ?? true;
+  const failures = [];
+  const report2 = [];
+  const add = (ok, message) => {
+    report2.push(`${ok ? "ok  " : "FAIL"}  ${message}`);
+    if (!ok) failures.push(message);
+  };
+  const done = () => ({ ok: failures.length === 0, failures, report: report2 });
+  if (text === null) {
+    if (required) add(false, "no photo review: run `halide review --json`");
+    else report2.push("ok    no photo review, and none required");
+    return done();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    add(false, `the photo review is not valid JSON: ${error.message}`);
+    return done();
+  }
+  const images = Array.isArray(parsed.images) ? parsed.images : [];
+  const overall = typeof parsed.score === "number" ? parsed.score : null;
+  if (overall === null && images.length === 0) {
+    add(false, "the photo review has neither a score nor an images list");
+    return done();
+  }
+  if (overall !== null) add(overall >= minScore, `overall score ${overall.toFixed(2)} against a minimum of ${minScore.toFixed(2)}`);
+  const below = images.filter((i) => typeof i.score === "number" && i.score < minScore);
+  if (below.length > 0) {
+    const named = below.slice(0, 5).map((i) => `${i.file ?? i.id ?? "?"} (${i.score.toFixed(2)})`).join(", ");
+    add(false, `${below.length} of ${images.length} image(s) below ${minScore.toFixed(2)}: ${named}`);
+  } else if (images.length > 0) {
+    add(true, `all ${images.length} image(s) at or above ${minScore.toFixed(2)}`);
+  }
+  return done();
+}
+
 // src/color/semantic.ts
 function accentFork(rampSteps, on, options = {}) {
   const minWcag = options.minWcag ?? 4.5;
@@ -2833,98 +3105,6 @@ ${filler(520, 11)}`)]
   }
 ];
 
-// src/character/color.ts
-var COLOUR = /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3,4}\b|\b(?:rgba?|hsla?|oklch|oklab)\([^)]*\)|\bcolor\(\s*srgb\b[^)]*\)/g;
-function num(token, percentOf) {
-  const t = token.trim();
-  if (t.endsWith("%")) return parseFloat(t) / 100 * percentOf;
-  return parseFloat(t);
-}
-function parts(fn) {
-  const inner = fn.slice(fn.indexOf("(") + 1, -1).trim();
-  const [main, slashAlpha] = inner.split("/");
-  const channels = main.split(/[\s,]+/).filter(Boolean);
-  let alpha = 1;
-  if (slashAlpha !== void 0) alpha = num(slashAlpha, 1);
-  else if (channels.length === 4) alpha = num(channels.pop(), 1);
-  return { channels, alpha: Number.isFinite(alpha) ? alpha : 1 };
-}
-function hslToRgb(h, s, l) {
-  const k = (n) => (n + h / 30) % 12;
-  const a = s * Math.min(l, 1 - l);
-  const f4 = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
-  return { r: f4(0), g: f4(8), b: f4(4) };
-}
-var clamp012 = (n) => Math.min(1, Math.max(0, n));
-function parseColour(raw) {
-  try {
-    if (raw.startsWith("#")) {
-      const hex2 = raw.slice(1);
-      const alpha2 = hex2.length === 8 ? parseInt(hex2.slice(6), 16) / 255 : hex2.length === 4 ? parseInt(hex2[3] + hex2[3], 16) / 255 : 1;
-      return { oklch: hexToOklch(raw), alpha: alpha2 };
-    }
-    const fn = raw.slice(0, raw.indexOf("(")).toLowerCase();
-    if (fn === "color") {
-      const { channels: channels2, alpha: alpha2 } = parts(raw.replace(/^color\(\s*srgb\s+/i, "srgb("));
-      const [r, g, b] = channels2.map((c) => clamp012(num(c, 1)));
-      if (![r, g, b].every(Number.isFinite)) return null;
-      return { oklch: hexToOklch(formatHex({ r, g, b })), alpha: alpha2 };
-    }
-    const { channels, alpha } = parts(raw);
-    if (channels.length < 3 || channels.some((c) => c.startsWith("var"))) return null;
-    if (fn === "oklch") {
-      const l = num(channels[0], 1);
-      const c = num(channels[1], 0.4);
-      const h = parseFloat(channels[2]);
-      if (![l, c].every(Number.isFinite)) return null;
-      return { oklch: { l, c, h: Number.isFinite(h) ? h : 0 }, alpha };
-    }
-    if (fn === "oklab") {
-      const l = num(channels[0], 1);
-      const a = num(channels[1], 0.4);
-      const b = num(channels[2], 0.4);
-      if (![l, a, b].every(Number.isFinite)) return null;
-      const c = Math.sqrt(a * a + b * b);
-      const h = c < 1e-7 ? 0 : (Math.atan2(b, a) * 180 / Math.PI % 360 + 360) % 360;
-      return { oklch: { l, c, h }, alpha };
-    }
-    if (fn === "rgb" || fn === "rgba") {
-      const [r, g, b] = channels.map((c) => clamp012(num(c, 255) / 255));
-      if (![r, g, b].every(Number.isFinite)) return null;
-      return { oklch: hexToOklch(formatHex({ r, g, b })), alpha };
-    }
-    if (fn === "hsl" || fn === "hsla") {
-      const h = parseFloat(channels[0]);
-      const s = num(channels[1], 1);
-      const l = num(channels[2], 1);
-      if (![h, s, l].every(Number.isFinite)) return null;
-      const rgb = hslToRgb((h % 360 + 360) % 360, clamp012(s), clamp012(l));
-      return { oklch: hexToOklch(formatHex(rgb)), alpha };
-    }
-  } catch {
-    return null;
-  }
-  return null;
-}
-function findColours(value) {
-  const out = [];
-  for (const m of value.matchAll(COLOUR)) {
-    const parsed = parseColour(m[0]);
-    if (parsed) out.push({ raw: m[0], ...parsed, index: m.index ?? 0 });
-  }
-  return out;
-}
-var AI_VIOLET = { hueMin: 268, hueMax: 312, minChroma: 0.1, minL: 0.3, maxL: 0.85 };
-function isAiViolet({ l, c, h }) {
-  return c >= AI_VIOLET.minChroma && h >= AI_VIOLET.hueMin && h <= AI_VIOLET.hueMax && l >= AI_VIOLET.minL && l <= AI_VIOLET.maxL;
-}
-function isCream({ l, c, h }) {
-  return l >= 0.9 && l <= 0.985 && c >= 8e-3 && c <= 0.06 && h >= 55 && h <= 105;
-}
-function isBlueToPurple({ c, h }) {
-  return c >= 0.08 && h >= 240 && h <= 330;
-}
-
 // src/character/tells/source.ts
 function baseClass(cls) {
   let depth = 0;
@@ -9379,6 +9559,7 @@ function retrofitPlan(report2, direction) {
   RENDERED_TELLS,
   REVEAL_LIMIT,
   REVIEW_PHRASES,
+  SAMPLES_PER_SEGMENT,
   SCALE,
   SECTION_ROLES,
   SHADCN_LIMIT,
@@ -9416,6 +9597,7 @@ function retrofitPlan(report2, direction) {
   checkCopy,
   checkOrder,
   checkPair,
+  checkPhotoReview,
   checkReason,
   checkRegister,
   checkRestraint,
@@ -9469,6 +9651,8 @@ function retrofitPlan(report2, direction) {
   formatReport,
   getRegister,
   globToRegExp,
+  gradientContrast,
+  gradientStops,
   groundName,
   harvest,
   hedgeCount,

package/dist/index.d.cts

@@ -159,6 +159,91 @@ interface ContrastCheck {
 /** Measure one text-on-background pair against both models. */
 declare function checkPair(text: string, background: string): ContrastCheck;
 
+/**
+ * Contrast against a CSS gradient: the case automated tools do not score.
+ *
+ * axe-core and Lighthouse mark text on a gradient "incomplete", and it never
+ * reaches the result, so a page can report no contrast violations while its
+ * body copy fails AA. This was first found on two client sites (4.14:1 to
+ * 4.44:1, reported clean by every tool in CI). This walks the gradient's
+ * stops, composites each over what sits beneath, and scores the text against
+ * the worst one: the backdrop the text has to clear everywhere.
+ *
+ * WCAG 2.2 defines no method for gradient or translucent backdrops, so the
+ * worst point is this package's own rule, not a conformance claim.
+ *
+ * Folded in from dd-drift-guards (guards/contrast-math.mjs) on 3 October 2026,
+ * on craft's own colour parsing and contrast models, with one fix: the guard
+ * scored the stops only. The worst point can sit between two stops, wherever
+ * the backdrop's luminance comes closest to the text's: mid-grey text on a
+ * black-to-white gradient clears 4.5:1 against both ends and about 1:1 in the
+ * middle. So each segment is sampled, interpolated as browsers paint legacy
+ * colours (sRGB, premultiplied alpha), except across a hard stop
+ * (`#000 50%, #fff 50%`), where the browser paints a jump and no blend. Pure.
+ */
+/** Samples per segment between two stops: under 1/255 of a channel apart for any pair. */
+declare const SAMPLES_PER_SEGMENT = 256;
+/**
+ * The colour stops of a CSS gradient, in order, as written. Splits on
+ * top-level commas only, so `rgba(1, 2, 3, 0.4)` survives, and drops the
+ * direction or shape argument (`to bottom`, `135deg`, `circle at top`).
+ * Throws on a stop it cannot read: a skipped stop could be the worst one.
+ */
+declare function gradientStops(gradient: string): string[];
+interface GradientContrast {
+    text: string;
+    gradient: string;
+    beneath: string;
+    /** Every stop composited over `beneath`, as hex. */
+    stops: string[];
+    /** The point of the gradient, stop or between stops, the text contrasts least with. */
+    worst: string;
+    /** WCAG 2.x ratio against the worst point. */
+    wcag: number;
+    /** APCA Lc against the worst point, signed. */
+    lc: number;
+    passesAA: boolean;
+    passesAALarge: boolean;
+    note: string;
+}
+/**
+ * Text on a gradient that sits on `beneath` (an opaque colour; default white).
+ * The text colour must be opaque: a translucent text colour depends on the
+ * backdrop at each pixel, which is a rendered measurement, not this one.
+ */
+declare function gradientContrast(text: string, gradient: string, beneath?: string): GradientContrast;
+
+/**
+ * The photo-review gate: reads the report `halide review --json` wrote and
+ * fails a build whose photography is under the bar.
+ *
+ * It takes the report's text, not a path, and never runs halide. A check that
+ * spawns a binary cannot run where the binary is absent (a CI image, a fresh
+ * clone), turns a fast check slow, and depends on a tool version nobody
+ * pinned. The pipeline writes the report; the build reads it and hands it here.
+ *
+ * Folded in from dd-drift-guards (guards/photo-review.mjs) on 3 October 2026,
+ * unchanged in what it passes and fails. Pure.
+ */
+interface PhotoReviewOptions {
+    /** Lowest acceptable score, overall and per image. Default 0.7. */
+    minScore?: number;
+    /**
+     * When false, no report is a pass: for a site with no photography at all.
+     * Default true, because a missing report on a site that has photos is the
+     * review not having run.
+     */
+    required?: boolean;
+}
+interface PhotoReviewResult {
+    ok: boolean;
+    failures: string[];
+    /** One line per thing checked, passed or not. */
+    report: string[];
+}
+/** `text` is the report's contents, or null when there is no report. */
+declare function checkPhotoReview(text: string | null, options?: PhotoReviewOptions): PhotoReviewResult;
+
 /**
  * Semantic tokens derived from a small set of anchors, with a contrast report.
  *
@@ -3260,4 +3345,4 @@ declare function characterReport(input: CharacterInputs, copyTells?: Set<string>
 
 declare function retrofitPlan(report: CharacterReport, direction?: ArtDirection | null): string;
 
-export { ACCENT_SCALE, ACCENT_SHARED, AI_PHRASES, AI_SOURCE_TYPES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type ActionPosition, type Area, type ArtDirection, BASELINE_VERSION, BUZZWORDS, type Band, type Baseline, type BaselineEntry, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, COMPONENT_ROLES, CONSIDERATION, CONTENT_FEATURES, CONVENTION, CUSTOMER_KINDS, type Calibration, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type Claim, type ClaimsReport, type CompetitorComparison, type ComponentPair, type ComponentTypicality, type Consideration, type ContrastCheck, type ContrastReport, type CopySide, type CopyTell, type CraftConfig, type CraftTokensInput, type CraftTokensResult, type CustomerKind, DEFAULT_IGNORE, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DIRECTION_VERSIONS, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionComparison, type DirectionMatch, type DirectionProblem, type DirectionReport, type DirectionSource, type DirectionSummary, type DurationName, EASE, EASE_TUPLE, EDGE_STEP, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, FLAGGED_TARGET, FUNCTION_WORDS, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FingerprintSection, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, GROUND_SCALE, GROUND_SHARED, type Gamut, type Generation, HIERARCHY_FIELDS, HOME_FILE, HOME_URL, HOUSE, HOUSE_BUDGET, HOUSE_LOCKED, HOUSE_TYPE, HUMAN_TYPICAL_TARGET, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, IMAGERY_TELLS, type ImageProvenance, type ImageRole, JSON_SCHEMA_VERSION, type JobContext, type JobMap, type JobPart, LABELS, LEXICAL_FEATURES, LICENCES, LIGHTNESS_CURVE, type Label, type LabelSummary, type LexicalFeatures, type LicenceEntry, type LicenceSubject, MIN_DECIDED, MIN_PARAGRAPHS, MIN_RUNS, MOOD, type MeasuredPage, type MotionDecision, type MotionKind, type MultiClient, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PAGE_TYPES, PILL_LIMIT, PLAINER_WORDS, PREFERENCE, PROFILE, PROFILE_MEASURED, PROFILE_PARAGRAPHS, PROMO_BADGE, PROOF_NAMES, PROPOSED, PROVENANCE_SCAN_BYTES, type PageCopy, type PageHierarchy, type PageResult, type PageType, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, READABLE_SNAPSHOT_VERSIONS, REFLEX_FONTS_1, REFLEX_FONTS_2, REGISTERS, REGISTER_BASELINE, REGISTER_FEATURES, REGISTER_IDS, RENDERED_PATHS, RENDERED_TELLS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type ReasonInput, type Register, type RegisterCheck, type RegisterFeatures, type RegisterId, type RegisterProfile, type RenderedTell, type ResearchInput, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, type RgbaImage, SCALE, SECTION_ROLES, SHADCN_LIMIT, SHADCN_PRIMITIVES, SHARED_PART, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPECIFICITY_COPY_TELLS, SPECIFICITY_RENDERED_TELLS, SPRING, STANDING_CLAIM, STOCK_AVATAR_HOSTS, STOCK_FIGURES, STOCK_PHOTO_HOSTS, STOCK_PHRASES, STUDY_WORDS, type SarifOptions, type SarifTell, type SectionGeometry, type SectionKind, type SectionRhythmOptions, type SectionRole, type SemanticInput, type SemanticResult, type Severity, type SeverityLevel, type SeverityOverride, type ShapeFeatures, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotImage, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SnapshotVisual, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Specific, type SpecificKind, type Specificity, type StudyWord, type Surface, TELL_HEAVY, TRADE_NOUNS, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type TargetCheck, type Tell, type TellException, type TellRate, type Tricolon, type TypeStep, type Typicality, type UnmeasuredPage, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, briefTerms, calibrate, catalogueTable, characterReport, checkCopy, checkOrder, checkPair, checkReason, checkRegister, checkRestraint, choicesOf, clauseDepth, closestComponents, compareCompetitor, compareDirections, compareFacts, compareToDeclared, compareToEstate, componentDistance, componentShared, componentTypicalities, componentTypicality, componentsOf, contentWords, countWords, craftTokens, createBaseline, cv, deltaEOk, deltaEOkHex, densityCss, densityTokens, designTells, documentParagraphs, emitCss, emptyEstate, estateComponentPairs, estatePairs, exitDuration, extractHtml, faceLicence, featureLabel, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatCalibration, formatClaims, formatComparison, formatCompetitor, formatDirectionMatches, formatHex, formatReport, getRegister, globToRegExp, groundName, harvest, hedgeCount, hedgedClose, hexToOklch, holdHouseBlocks, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isBlurb, isCategoryLabel, isCream, isFlagged, jobWords, layoutDistance, lexicalOf, licencesJson, makeSnapshot, motionTokens, namedSources, nearest, nominalisations, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, pageCopy, paletteFromPixels, paragraphUniformity, parseBaseline, parseColour, parseCraftConfig, parseHex, participialClauses, phrasalCoordinations, propose, protectedFacts, ramp, rampFromAnchors, readSnapshot, registerBrief, registerOf, registersDoc, renderedOrder, researchPrompt, retrofitPlan, runTell, scanProvenance, scanSource, sectionRhythm, semantic, sentencesOf, severityExceptions, shapeMoves, shapeName, shapeOf, words as shapeWords, sharedParts, shouldAnimate, siblingLine, skeleton, skeletonRepeat, specificity, specifics, splitSentences, stackedConditional, stockAvatarSource, stockSource, summariseDirection, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, tradeOf, tricolons, typeFeatureTokens, typicality, unprovenClaims, validateDirection, validateHierarchy, validateJob, visibleText, visualMeasures, vocabulary, vocabularyCounts, wcagContrast, wordListsJson };
+export { ACCENT_SCALE, ACCENT_SHARED, AI_PHRASES, AI_SOURCE_TYPES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type ActionPosition, type Area, type ArtDirection, BASELINE_VERSION, BUZZWORDS, type Band, type Baseline, type BaselineEntry, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, COMPONENT_ROLES, CONSIDERATION, CONTENT_FEATURES, CONVENTION, CUSTOMER_KINDS, type Calibration, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type Claim, type ClaimsReport, type CompetitorComparison, type ComponentPair, type ComponentTypicality, type Consideration, type ContrastCheck, type ContrastReport, type CopySide, type CopyTell, type CraftConfig, type CraftTokensInput, type CraftTokensResult, type CustomerKind, DEFAULT_IGNORE, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DIRECTION_VERSIONS, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionComparison, type DirectionMatch, type DirectionProblem, type DirectionReport, type DirectionSource, type DirectionSummary, type DurationName, EASE, EASE_TUPLE, EDGE_STEP, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, FLAGGED_TARGET, FUNCTION_WORDS, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FingerprintSection, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, GROUND_SCALE, GROUND_SHARED, type Gamut, type Generation, type GradientContrast, HIERARCHY_FIELDS, HOME_FILE, HOME_URL, HOUSE, HOUSE_BUDGET, HOUSE_LOCKED, HOUSE_TYPE, HUMAN_TYPICAL_TARGET, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, IMAGERY_TELLS, type ImageProvenance, type ImageRole, JSON_SCHEMA_VERSION, type JobContext, type JobMap, type JobPart, LABELS, LEXICAL_FEATURES, LICENCES, LIGHTNESS_CURVE, type Label, type LabelSummary, type LexicalFeatures, type LicenceEntry, type LicenceSubject, MIN_DECIDED, MIN_PARAGRAPHS, MIN_RUNS, MOOD, type MeasuredPage, type MotionDecision, type MotionKind, type MultiClient, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PAGE_TYPES, PILL_LIMIT, PLAINER_WORDS, PREFERENCE, PROFILE, PROFILE_MEASURED, PROFILE_PARAGRAPHS, PROMO_BADGE, PROOF_NAMES, PROPOSED, PROVENANCE_SCAN_BYTES, type PageCopy, type PageHierarchy, type PageResult, type PageType, type PaletteColour, type PhotoReviewOptions, type PhotoReviewResult, type Proposal, type ProposeInput, RAMP_STEPS, READABLE_SNAPSHOT_VERSIONS, REFLEX_FONTS_1, REFLEX_FONTS_2, REGISTERS, REGISTER_BASELINE, REGISTER_FEATURES, REGISTER_IDS, RENDERED_PATHS, RENDERED_TELLS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type ReasonInput, type Register, type RegisterCheck, type RegisterFeatures, type RegisterId, type RegisterProfile, type RenderedTell, type ResearchInput, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, type RgbaImage, SAMPLES_PER_SEGMENT, SCALE, SECTION_ROLES, SHADCN_LIMIT, SHADCN_PRIMITIVES, SHARED_PART, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPECIFICITY_COPY_TELLS, SPECIFICITY_RENDERED_TELLS, SPRING, STANDING_CLAIM, STOCK_AVATAR_HOSTS, STOCK_FIGURES, STOCK_PHOTO_HOSTS, STOCK_PHRASES, STUDY_WORDS, type SarifOptions, type SarifTell, type SectionGeometry, type SectionKind, type SectionRhythmOptions, type SectionRole, type SemanticInput, type SemanticResult, type Severity, type SeverityLevel, type SeverityOverride, type ShapeFeatures, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotImage, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SnapshotVisual, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Specific, type SpecificKind, type Specificity, type StudyWord, type Surface, TELL_HEAVY, TRADE_NOUNS, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type TargetCheck, type Tell, type TellException, type TellRate, type Tricolon, type TypeStep, type Typicality, type UnmeasuredPage, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, briefTerms, calibrate, catalogueTable, characterReport, checkCopy, checkOrder, checkPair, checkPhotoReview, checkReason, checkRegister, checkRestraint, choicesOf, clauseDepth, closestComponents, compareCompetitor, compareDirections, compareFacts, compareToDeclared, compareToEstate, componentDistance, componentShared, componentTypicalities, componentTypicality, componentsOf, contentWords, countWords, craftTokens, createBaseline, cv, deltaEOk, deltaEOkHex, densityCss, densityTokens, designTells, documentParagraphs, emitCss, emptyEstate, estateComponentPairs, estatePairs, exitDuration, extractHtml, faceLicence, featureLabel, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatCalibration, formatClaims, formatComparison, formatCompetitor, formatDirectionMatches, formatHex, formatReport, getRegister, globToRegExp, gradientContrast, gradientStops, groundName, harvest, hedgeCount, hedgedClose, hexToOklch, holdHouseBlocks, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isBlurb, isCategoryLabel, isCream, isFlagged, jobWords, layoutDistance, lexicalOf, licencesJson, makeSnapshot, motionTokens, namedSources, nearest, nominalisations, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, pageCopy, paletteFromPixels, paragraphUniformity, parseBaseline, parseColour, parseCraftConfig, parseHex, participialClauses, phrasalCoordinations, propose, protectedFacts, ramp, rampFromAnchors, readSnapshot, registerBrief, registerOf, registersDoc, renderedOrder, researchPrompt, retrofitPlan, runTell, scanProvenance, scanSource, sectionRhythm, semantic, sentencesOf, severityExceptions, shapeMoves, shapeName, shapeOf, words as shapeWords, sharedParts, shouldAnimate, siblingLine, skeleton, skeletonRepeat, specificity, specifics, splitSentences, stackedConditional, stockAvatarSource, stockSource, summariseDirection, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, tradeOf, tricolons, typeFeatureTokens, typicality, unprovenClaims, validateDirection, validateHierarchy, validateJob, visibleText, visualMeasures, vocabulary, vocabularyCounts, wcagContrast, wordListsJson };

package/dist/index.d.ts

@@ -159,6 +159,91 @@ interface ContrastCheck {
 /** Measure one text-on-background pair against both models. */
 declare function checkPair(text: string, background: string): ContrastCheck;
 
+/**
+ * Contrast against a CSS gradient: the case automated tools do not score.
+ *
+ * axe-core and Lighthouse mark text on a gradient "incomplete", and it never
+ * reaches the result, so a page can report no contrast violations while its
+ * body copy fails AA. This was first found on two client sites (4.14:1 to
+ * 4.44:1, reported clean by every tool in CI). This walks the gradient's
+ * stops, composites each over what sits beneath, and scores the text against
+ * the worst one: the backdrop the text has to clear everywhere.
+ *
+ * WCAG 2.2 defines no method for gradient or translucent backdrops, so the
+ * worst point is this package's own rule, not a conformance claim.
+ *
+ * Folded in from dd-drift-guards (guards/contrast-math.mjs) on 3 October 2026,
+ * on craft's own colour parsing and contrast models, with one fix: the guard
+ * scored the stops only. The worst point can sit between two stops, wherever
+ * the backdrop's luminance comes closest to the text's: mid-grey text on a
+ * black-to-white gradient clears 4.5:1 against both ends and about 1:1 in the
+ * middle. So each segment is sampled, interpolated as browsers paint legacy
+ * colours (sRGB, premultiplied alpha), except across a hard stop
+ * (`#000 50%, #fff 50%`), where the browser paints a jump and no blend. Pure.
+ */
+/** Samples per segment between two stops: under 1/255 of a channel apart for any pair. */
+declare const SAMPLES_PER_SEGMENT = 256;
+/**
+ * The colour stops of a CSS gradient, in order, as written. Splits on
+ * top-level commas only, so `rgba(1, 2, 3, 0.4)` survives, and drops the
+ * direction or shape argument (`to bottom`, `135deg`, `circle at top`).
+ * Throws on a stop it cannot read: a skipped stop could be the worst one.
+ */
+declare function gradientStops(gradient: string): string[];
+interface GradientContrast {
+    text: string;
+    gradient: string;
+    beneath: string;
+    /** Every stop composited over `beneath`, as hex. */
+    stops: string[];
+    /** The point of the gradient, stop or between stops, the text contrasts least with. */
+    worst: string;
+    /** WCAG 2.x ratio against the worst point. */
+    wcag: number;
+    /** APCA Lc against the worst point, signed. */
+    lc: number;
+    passesAA: boolean;
+    passesAALarge: boolean;
+    note: string;
+}
+/**
+ * Text on a gradient that sits on `beneath` (an opaque colour; default white).
+ * The text colour must be opaque: a translucent text colour depends on the
+ * backdrop at each pixel, which is a rendered measurement, not this one.
+ */
+declare function gradientContrast(text: string, gradient: string, beneath?: string): GradientContrast;
+
+/**
+ * The photo-review gate: reads the report `halide review --json` wrote and
+ * fails a build whose photography is under the bar.
+ *
+ * It takes the report's text, not a path, and never runs halide. A check that
+ * spawns a binary cannot run where the binary is absent (a CI image, a fresh
+ * clone), turns a fast check slow, and depends on a tool version nobody
+ * pinned. The pipeline writes the report; the build reads it and hands it here.
+ *
+ * Folded in from dd-drift-guards (guards/photo-review.mjs) on 3 October 2026,
+ * unchanged in what it passes and fails. Pure.
+ */
+interface PhotoReviewOptions {
+    /** Lowest acceptable score, overall and per image. Default 0.7. */
+    minScore?: number;
+    /**
+     * When false, no report is a pass: for a site with no photography at all.
+     * Default true, because a missing report on a site that has photos is the
+     * review not having run.
+     */
+    required?: boolean;
+}
+interface PhotoReviewResult {
+    ok: boolean;
+    failures: string[];
+    /** One line per thing checked, passed or not. */
+    report: string[];
+}
+/** `text` is the report's contents, or null when there is no report. */
+declare function checkPhotoReview(text: string | null, options?: PhotoReviewOptions): PhotoReviewResult;
+
 /**
  * Semantic tokens derived from a small set of anchors, with a contrast report.
  *
@@ -3260,4 +3345,4 @@ declare function characterReport(input: CharacterInputs, copyTells?: Set<string>
 
 declare function retrofitPlan(report: CharacterReport, direction?: ArtDirection | null): string;
 
-export { ACCENT_SCALE, ACCENT_SHARED, AI_PHRASES, AI_SOURCE_TYPES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type ActionPosition, type Area, type ArtDirection, BASELINE_VERSION, BUZZWORDS, type Band, type Baseline, type BaselineEntry, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, COMPONENT_ROLES, CONSIDERATION, CONTENT_FEATURES, CONVENTION, CUSTOMER_KINDS, type Calibration, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type Claim, type ClaimsReport, type CompetitorComparison, type ComponentPair, type ComponentTypicality, type Consideration, type ContrastCheck, type ContrastReport, type CopySide, type CopyTell, type CraftConfig, type CraftTokensInput, type CraftTokensResult, type CustomerKind, DEFAULT_IGNORE, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DIRECTION_VERSIONS, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionComparison, type DirectionMatch, type DirectionProblem, type DirectionReport, type DirectionSource, type DirectionSummary, type DurationName, EASE, EASE_TUPLE, EDGE_STEP, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, FLAGGED_TARGET, FUNCTION_WORDS, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FingerprintSection, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, GROUND_SCALE, GROUND_SHARED, type Gamut, type Generation, HIERARCHY_FIELDS, HOME_FILE, HOME_URL, HOUSE, HOUSE_BUDGET, HOUSE_LOCKED, HOUSE_TYPE, HUMAN_TYPICAL_TARGET, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, IMAGERY_TELLS, type ImageProvenance, type ImageRole, JSON_SCHEMA_VERSION, type JobContext, type JobMap, type JobPart, LABELS, LEXICAL_FEATURES, LICENCES, LIGHTNESS_CURVE, type Label, type LabelSummary, type LexicalFeatures, type LicenceEntry, type LicenceSubject, MIN_DECIDED, MIN_PARAGRAPHS, MIN_RUNS, MOOD, type MeasuredPage, type MotionDecision, type MotionKind, type MultiClient, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PAGE_TYPES, PILL_LIMIT, PLAINER_WORDS, PREFERENCE, PROFILE, PROFILE_MEASURED, PROFILE_PARAGRAPHS, PROMO_BADGE, PROOF_NAMES, PROPOSED, PROVENANCE_SCAN_BYTES, type PageCopy, type PageHierarchy, type PageResult, type PageType, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, READABLE_SNAPSHOT_VERSIONS, REFLEX_FONTS_1, REFLEX_FONTS_2, REGISTERS, REGISTER_BASELINE, REGISTER_FEATURES, REGISTER_IDS, RENDERED_PATHS, RENDERED_TELLS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type ReasonInput, type Register, type RegisterCheck, type RegisterFeatures, type RegisterId, type RegisterProfile, type RenderedTell, type ResearchInput, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, type RgbaImage, SCALE, SECTION_ROLES, SHADCN_LIMIT, SHADCN_PRIMITIVES, SHARED_PART, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPECIFICITY_COPY_TELLS, SPECIFICITY_RENDERED_TELLS, SPRING, STANDING_CLAIM, STOCK_AVATAR_HOSTS, STOCK_FIGURES, STOCK_PHOTO_HOSTS, STOCK_PHRASES, STUDY_WORDS, type SarifOptions, type SarifTell, type SectionGeometry, type SectionKind, type SectionRhythmOptions, type SectionRole, type SemanticInput, type SemanticResult, type Severity, type SeverityLevel, type SeverityOverride, type ShapeFeatures, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotImage, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SnapshotVisual, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Specific, type SpecificKind, type Specificity, type StudyWord, type Surface, TELL_HEAVY, TRADE_NOUNS, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type TargetCheck, type Tell, type TellException, type TellRate, type Tricolon, type TypeStep, type Typicality, type UnmeasuredPage, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, briefTerms, calibrate, catalogueTable, characterReport, checkCopy, checkOrder, checkPair, checkReason, checkRegister, checkRestraint, choicesOf, clauseDepth, closestComponents, compareCompetitor, compareDirections, compareFacts, compareToDeclared, compareToEstate, componentDistance, componentShared, componentTypicalities, componentTypicality, componentsOf, contentWords, countWords, craftTokens, createBaseline, cv, deltaEOk, deltaEOkHex, densityCss, densityTokens, designTells, documentParagraphs, emitCss, emptyEstate, estateComponentPairs, estatePairs, exitDuration, extractHtml, faceLicence, featureLabel, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatCalibration, formatClaims, formatComparison, formatCompetitor, formatDirectionMatches, formatHex, formatReport, getRegister, globToRegExp, groundName, harvest, hedgeCount, hedgedClose, hexToOklch, holdHouseBlocks, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isBlurb, isCategoryLabel, isCream, isFlagged, jobWords, layoutDistance, lexicalOf, licencesJson, makeSnapshot, motionTokens, namedSources, nearest, nominalisations, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, pageCopy, paletteFromPixels, paragraphUniformity, parseBaseline, parseColour, parseCraftConfig, parseHex, participialClauses, phrasalCoordinations, propose, protectedFacts, ramp, rampFromAnchors, readSnapshot, registerBrief, registerOf, registersDoc, renderedOrder, researchPrompt, retrofitPlan, runTell, scanProvenance, scanSource, sectionRhythm, semantic, sentencesOf, severityExceptions, shapeMoves, shapeName, shapeOf, words as shapeWords, sharedParts, shouldAnimate, siblingLine, skeleton, skeletonRepeat, specificity, specifics, splitSentences, stackedConditional, stockAvatarSource, stockSource, summariseDirection, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, tradeOf, tricolons, typeFeatureTokens, typicality, unprovenClaims, validateDirection, validateHierarchy, validateJob, visibleText, visualMeasures, vocabulary, vocabularyCounts, wcagContrast, wordListsJson };
+export { ACCENT_SCALE, ACCENT_SHARED, AI_PHRASES, AI_SOURCE_TYPES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type ActionPosition, type Area, type ArtDirection, BASELINE_VERSION, BUZZWORDS, type Band, type Baseline, type BaselineEntry, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, COMPONENT_ROLES, CONSIDERATION, CONTENT_FEATURES, CONVENTION, CUSTOMER_KINDS, type Calibration, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type Claim, type ClaimsReport, type CompetitorComparison, type ComponentPair, type ComponentTypicality, type Consideration, type ContrastCheck, type ContrastReport, type CopySide, type CopyTell, type CraftConfig, type CraftTokensInput, type CraftTokensResult, type CustomerKind, DEFAULT_IGNORE, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DIRECTION_VERSIONS, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionComparison, type DirectionMatch, type DirectionProblem, type DirectionReport, type DirectionSource, type DirectionSummary, type DurationName, EASE, EASE_TUPLE, EDGE_STEP, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, FLAGGED_TARGET, FUNCTION_WORDS, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FingerprintSection, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, GROUND_SCALE, GROUND_SHARED, type Gamut, type Generation, type GradientContrast, HIERARCHY_FIELDS, HOME_FILE, HOME_URL, HOUSE, HOUSE_BUDGET, HOUSE_LOCKED, HOUSE_TYPE, HUMAN_TYPICAL_TARGET, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, IMAGERY_TELLS, type ImageProvenance, type ImageRole, JSON_SCHEMA_VERSION, type JobContext, type JobMap, type JobPart, LABELS, LEXICAL_FEATURES, LICENCES, LIGHTNESS_CURVE, type Label, type LabelSummary, type LexicalFeatures, type LicenceEntry, type LicenceSubject, MIN_DECIDED, MIN_PARAGRAPHS, MIN_RUNS, MOOD, type MeasuredPage, type MotionDecision, type MotionKind, type MultiClient, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PAGE_TYPES, PILL_LIMIT, PLAINER_WORDS, PREFERENCE, PROFILE, PROFILE_MEASURED, PROFILE_PARAGRAPHS, PROMO_BADGE, PROOF_NAMES, PROPOSED, PROVENANCE_SCAN_BYTES, type PageCopy, type PageHierarchy, type PageResult, type PageType, type PaletteColour, type PhotoReviewOptions, type PhotoReviewResult, type Proposal, type ProposeInput, RAMP_STEPS, READABLE_SNAPSHOT_VERSIONS, REFLEX_FONTS_1, REFLEX_FONTS_2, REGISTERS, REGISTER_BASELINE, REGISTER_FEATURES, REGISTER_IDS, RENDERED_PATHS, RENDERED_TELLS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type ReasonInput, type Register, type RegisterCheck, type RegisterFeatures, type RegisterId, type RegisterProfile, type RenderedTell, type ResearchInput, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, type RgbaImage, SAMPLES_PER_SEGMENT, SCALE, SECTION_ROLES, SHADCN_LIMIT, SHADCN_PRIMITIVES, SHARED_PART, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPECIFICITY_COPY_TELLS, SPECIFICITY_RENDERED_TELLS, SPRING, STANDING_CLAIM, STOCK_AVATAR_HOSTS, STOCK_FIGURES, STOCK_PHOTO_HOSTS, STOCK_PHRASES, STUDY_WORDS, type SarifOptions, type SarifTell, type SectionGeometry, type SectionKind, type SectionRhythmOptions, type SectionRole, type SemanticInput, type SemanticResult, type Severity, type SeverityLevel, type SeverityOverride, type ShapeFeatures, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotImage, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SnapshotVisual, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Specific, type SpecificKind, type Specificity, type StudyWord, type Surface, TELL_HEAVY, TRADE_NOUNS, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type TargetCheck, type Tell, type TellException, type TellRate, type Tricolon, type TypeStep, type Typicality, type UnmeasuredPage, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, briefTerms, calibrate, catalogueTable, characterReport, checkCopy, checkOrder, checkPair, checkPhotoReview, checkReason, checkRegister, checkRestraint, choicesOf, clauseDepth, closestComponents, compareCompetitor, compareDirections, compareFacts, compareToDeclared, compareToEstate, componentDistance, componentShared, componentTypicalities, componentTypicality, componentsOf, contentWords, countWords, craftTokens, createBaseline, cv, deltaEOk, deltaEOkHex, densityCss, densityTokens, designTells, documentParagraphs, emitCss, emptyEstate, estateComponentPairs, estatePairs, exitDuration, extractHtml, faceLicence, featureLabel, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatCalibration, formatClaims, formatComparison, formatCompetitor, formatDirectionMatches, formatHex, formatReport, getRegister, globToRegExp, gradientContrast, gradientStops, groundName, harvest, hedgeCount, hedgedClose, hexToOklch, holdHouseBlocks, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isBlurb, isCategoryLabel, isCream, isFlagged, jobWords, layoutDistance, lexicalOf, licencesJson, makeSnapshot, motionTokens, namedSources, nearest, nominalisations, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, pageCopy, paletteFromPixels, paragraphUniformity, parseBaseline, parseColour, parseCraftConfig, parseHex, participialClauses, phrasalCoordinations, propose, protectedFacts, ramp, rampFromAnchors, readSnapshot, registerBrief, registerOf, registersDoc, renderedOrder, researchPrompt, retrofitPlan, runTell, scanProvenance, scanSource, sectionRhythm, semantic, sentencesOf, severityExceptions, shapeMoves, shapeName, shapeOf, words as shapeWords, sharedParts, shouldAnimate, siblingLine, skeleton, skeletonRepeat, specificity, specifics, splitSentences, stackedConditional, stockAvatarSource, stockSource, summariseDirection, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, tradeOf, tricolons, typeFeatureTokens, typicality, unprovenClaims, validateDirection, validateHierarchy, validateJob, visibleText, visualMeasures, vocabulary, vocabularyCounts, wcagContrast, wordListsJson };

package/dist/index.js

@@ -300,6 +300,274 @@ function checkPair(text, background) {
   };
 }
 
+// src/character/color.ts
+var COLOUR = /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3,4}\b|\b(?:rgba?|hsla?|oklch|oklab)\([^)]*\)|\bcolor\(\s*srgb\b[^)]*\)/g;
+function num(token, percentOf) {
+  const t = token.trim();
+  if (t.endsWith("%")) return parseFloat(t) / 100 * percentOf;
+  return parseFloat(t);
+}
+function parts(fn) {
+  const inner = fn.slice(fn.indexOf("(") + 1, -1).trim();
+  const [main, slashAlpha] = inner.split("/");
+  const channels = main.split(/[\s,]+/).filter(Boolean);
+  let alpha = 1;
+  if (slashAlpha !== void 0) alpha = num(slashAlpha, 1);
+  else if (channels.length === 4) alpha = num(channels.pop(), 1);
+  return { channels, alpha: Number.isFinite(alpha) ? alpha : 1 };
+}
+function hslToRgb(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f4 = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return { r: f4(0), g: f4(8), b: f4(4) };
+}
+var clamp012 = (n) => Math.min(1, Math.max(0, n));
+function parseColour(raw) {
+  try {
+    if (raw.startsWith("#")) {
+      const hex2 = raw.slice(1);
+      const alpha2 = hex2.length === 8 ? parseInt(hex2.slice(6), 16) / 255 : hex2.length === 4 ? parseInt(hex2[3] + hex2[3], 16) / 255 : 1;
+      return { oklch: hexToOklch(raw), alpha: alpha2 };
+    }
+    const fn = raw.slice(0, raw.indexOf("(")).toLowerCase();
+    if (fn === "color") {
+      const { channels: channels2, alpha: alpha2 } = parts(raw.replace(/^color\(\s*srgb\s+/i, "srgb("));
+      const [r, g, b] = channels2.map((c) => clamp012(num(c, 1)));
+      if (![r, g, b].every(Number.isFinite)) return null;
+      return { oklch: hexToOklch(formatHex({ r, g, b })), alpha: alpha2 };
+    }
+    const { channels, alpha } = parts(raw);
+    if (channels.length < 3 || channels.some((c) => c.startsWith("var"))) return null;
+    if (fn === "oklch") {
+      const l = num(channels[0], 1);
+      const c = num(channels[1], 0.4);
+      const h = parseFloat(channels[2]);
+      if (![l, c].every(Number.isFinite)) return null;
+      return { oklch: { l, c, h: Number.isFinite(h) ? h : 0 }, alpha };
+    }
+    if (fn === "oklab") {
+      const l = num(channels[0], 1);
+      const a = num(channels[1], 0.4);
+      const b = num(channels[2], 0.4);
+      if (![l, a, b].every(Number.isFinite)) return null;
+      const c = Math.sqrt(a * a + b * b);
+      const h = c < 1e-7 ? 0 : (Math.atan2(b, a) * 180 / Math.PI % 360 + 360) % 360;
+      return { oklch: { l, c, h }, alpha };
+    }
+    if (fn === "rgb" || fn === "rgba") {
+      const [r, g, b] = channels.map((c) => clamp012(num(c, 255) / 255));
+      if (![r, g, b].every(Number.isFinite)) return null;
+      return { oklch: hexToOklch(formatHex({ r, g, b })), alpha };
+    }
+    if (fn === "hsl" || fn === "hsla") {
+      const h = parseFloat(channels[0]);
+      const s = num(channels[1], 1);
+      const l = num(channels[2], 1);
+      if (![h, s, l].every(Number.isFinite)) return null;
+      const rgb = hslToRgb((h % 360 + 360) % 360, clamp012(s), clamp012(l));
+      return { oklch: hexToOklch(formatHex(rgb)), alpha };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function findColours(value) {
+  const out = [];
+  for (const m of value.matchAll(COLOUR)) {
+    const parsed = parseColour(m[0]);
+    if (parsed) out.push({ raw: m[0], ...parsed, index: m.index ?? 0 });
+  }
+  return out;
+}
+var AI_VIOLET = { hueMin: 268, hueMax: 312, minChroma: 0.1, minL: 0.3, maxL: 0.85 };
+function isAiViolet({ l, c, h }) {
+  return c >= AI_VIOLET.minChroma && h >= AI_VIOLET.hueMin && h <= AI_VIOLET.hueMax && l >= AI_VIOLET.minL && l <= AI_VIOLET.maxL;
+}
+function isCream({ l, c, h }) {
+  return l >= 0.9 && l <= 0.985 && c >= 8e-3 && c <= 0.06 && h >= 55 && h <= 105;
+}
+function isBlueToPurple({ c, h }) {
+  return c >= 0.08 && h >= 240 && h <= 330;
+}
+
+// src/color/gradient.ts
+var KEYWORDS = {
+  white: { r: 1, g: 1, b: 1, a: 1 },
+  black: { r: 0, g: 0, b: 0, a: 1 },
+  transparent: { r: 0, g: 0, b: 0, a: 0 }
+};
+var clamp013 = (n) => Math.min(1, Math.max(0, n));
+function toRgba(raw) {
+  const value = raw.trim().toLowerCase();
+  if (KEYWORDS[value]) return KEYWORDS[value];
+  if (/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(value)) {
+    const h = value.length <= 5 ? [...value.slice(1)].map((c) => c + c).join("") : value.slice(1);
+    const { r: r2, g: g2, b: b2 } = parseHex(h.slice(0, 6));
+    return { r: r2, g: g2, b: b2, a: h.length === 8 ? parseInt(h.slice(6), 16) / 255 : 1 };
+  }
+  const rgb = /^rgba?\(([^)]+)\)$/.exec(value);
+  if (rgb) {
+    const parts2 = rgb[1].split(/[\s,/]+/).filter(Boolean);
+    const channel = (p) => p.endsWith("%") ? parseFloat(p) / 100 : parseFloat(p) / 255;
+    const alpha = parts2[3] === void 0 ? 1 : parts2[3].endsWith("%") ? parseFloat(parts2[3]) / 100 : parseFloat(parts2[3]);
+    const [r2, g2, b2] = parts2.slice(0, 3).map(channel);
+    if (parts2.length >= 3 && [r2, g2, b2, alpha].every(Number.isFinite)) return { r: clamp013(r2), g: clamp013(g2), b: clamp013(b2), a: clamp013(alpha) };
+    return null;
+  }
+  const parsed = parseColour(value);
+  if (!parsed) return null;
+  const { r, g, b } = oklchToRgb(parsed.oklch);
+  return { r: clamp013(r), g: clamp013(g), b: clamp013(b), a: clamp013(parsed.alpha) };
+}
+var SAMPLES_PER_SEGMENT = 256;
+function mix(a, b, t) {
+  const alpha = a.a + (b.a - a.a) * t;
+  if (alpha === 0) return { r: 0, g: 0, b: 0, a: 0 };
+  const ch = (x, y) => (x * a.a + (y * b.a - x * a.a) * t) / alpha;
+  return { r: ch(a.r, b.r), g: ch(a.g, b.g), b: ch(a.b, b.b), a: alpha };
+}
+function composite(top, under) {
+  return {
+    r: top.r * top.a + under.r * (1 - top.a),
+    g: top.g * top.a + under.g * (1 - top.a),
+    b: top.b * top.a + under.b * (1 - top.a)
+  };
+}
+function gradientStops(gradient) {
+  return parseStops(gradient).map((s) => s.colour);
+}
+function parseStops(gradient) {
+  const inner = /gradient\(([\s\S]*)\)\s*$/.exec(gradient.trim());
+  if (!inner) throw new Error(`not a CSS gradient: ${gradient}`);
+  const parts2 = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of inner[1]) {
+    if (ch === "(") depth += 1;
+    if (ch === ")") depth -= 1;
+    if (ch === "," && depth === 0) {
+      parts2.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) parts2.push(current.trim());
+  const stops = [];
+  for (const part of parts2) {
+    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(part)) continue;
+    const positions = [];
+    let colour = part;
+    for (let i = 0; i < 2; i++) {
+      const m = /\s+(-?[\d.]+)(%|px|r?em|vw|vh|deg|turn|rad|grad)\s*$/i.exec(colour);
+      if (!m) break;
+      positions.unshift({ value: parseFloat(m[1]), unit: m[2].toLowerCase() });
+      colour = colour.slice(0, m.index);
+    }
+    colour = colour.trim();
+    if (!toRgba(colour)) throw new Error(`unreadable gradient stop "${colour}" in ${gradient}`);
+    stops.push({ colour, positions });
+  }
+  if (stops.length === 0) throw new Error(`no colour stops in ${gradient}`);
+  return stops;
+}
+function blendedSegments(stops) {
+  const entries = [];
+  for (const s of stops) {
+    const rgba = toRgba(s.colour);
+    if (s.positions.length === 0) entries.push({ rgba, pos: null });
+    for (const pos of s.positions) entries.push({ rgba, pos });
+  }
+  const furthest = {};
+  const pairs = [];
+  for (let i = 0; i + 1 < entries.length; i++) {
+    const pos = entries[i].pos;
+    if (pos) furthest[pos.unit] = Math.max(furthest[pos.unit] ?? -Infinity, pos.value);
+    const next = entries[i + 1].pos;
+    const hard = next !== null && furthest[next.unit] !== void 0 && next.value <= furthest[next.unit];
+    if (!hard) pairs.push([entries[i].rgba, entries[i + 1].rgba]);
+  }
+  return pairs;
+}
+function gradientContrast(text, gradient, beneath = "#ffffff") {
+  const under = toRgba(beneath);
+  if (!under || under.a < 1) throw new Error(`beneath must be an opaque colour, got ${beneath}`);
+  const fg = toRgba(text);
+  if (!fg || fg.a < 1) throw new Error(`text must be an opaque colour, got ${text}`);
+  const textHex = formatHex(fg);
+  const parsed = parseStops(gradient);
+  const stops = parsed.map((s) => formatHex(composite(toRgba(s.colour), under)));
+  let worst = stops[0];
+  let worstRatio = wcagContrast(textHex, worst);
+  for (const s of stops) {
+    const ratio = wcagContrast(textHex, s);
+    if (ratio < worstRatio) [worst, worstRatio] = [s, ratio];
+  }
+  for (const [a, b] of blendedSegments(parsed)) {
+    for (let k = 1; k < SAMPLES_PER_SEGMENT; k++) {
+      const point = formatHex(composite(mix(a, b, k / SAMPLES_PER_SEGMENT), under));
+      const ratio = wcagContrast(textHex, point);
+      if (ratio < worstRatio) [worst, worstRatio] = [point, ratio];
+    }
+  }
+  const wcag = wcagContrast(textHex, worst);
+  const lc = apcaContrast(textHex, worst);
+  return {
+    text,
+    gradient,
+    beneath,
+    stops,
+    worst,
+    wcag,
+    lc,
+    passesAA: wcag >= 4.5,
+    passesAALarge: wcag >= 3,
+    note: `${text} on ${gradient} over ${beneath}: worst point ${worst}, ${wcag.toFixed(2)}:1, Lc ${lc.toFixed(1)}`
+  };
+}
+
+// src/photo/review.ts
+function checkPhotoReview(text, options = {}) {
+  const minScore = options.minScore ?? 0.7;
+  const required = options.required ?? true;
+  const failures = [];
+  const report2 = [];
+  const add = (ok, message) => {
+    report2.push(`${ok ? "ok  " : "FAIL"}  ${message}`);
+    if (!ok) failures.push(message);
+  };
+  const done = () => ({ ok: failures.length === 0, failures, report: report2 });
+  if (text === null) {
+    if (required) add(false, "no photo review: run `halide review --json`");
+    else report2.push("ok    no photo review, and none required");
+    return done();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    add(false, `the photo review is not valid JSON: ${error.message}`);
+    return done();
+  }
+  const images = Array.isArray(parsed.images) ? parsed.images : [];
+  const overall = typeof parsed.score === "number" ? parsed.score : null;
+  if (overall === null && images.length === 0) {
+    add(false, "the photo review has neither a score nor an images list");
+    return done();
+  }
+  if (overall !== null) add(overall >= minScore, `overall score ${overall.toFixed(2)} against a minimum of ${minScore.toFixed(2)}`);
+  const below = images.filter((i) => typeof i.score === "number" && i.score < minScore);
+  if (below.length > 0) {
+    const named = below.slice(0, 5).map((i) => `${i.file ?? i.id ?? "?"} (${i.score.toFixed(2)})`).join(", ");
+    add(false, `${below.length} of ${images.length} image(s) below ${minScore.toFixed(2)}: ${named}`);
+  } else if (images.length > 0) {
+    add(true, `all ${images.length} image(s) at or above ${minScore.toFixed(2)}`);
+  }
+  return done();
+}
+
 // src/color/semantic.ts
 function accentFork(rampSteps, on, options = {}) {
   const minWcag = options.minWcag ?? 4.5;
@@ -2547,98 +2815,6 @@ ${filler(520, 11)}`)]
   }
 ];
 
-// src/character/color.ts
-var COLOUR = /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3,4}\b|\b(?:rgba?|hsla?|oklch|oklab)\([^)]*\)|\bcolor\(\s*srgb\b[^)]*\)/g;
-function num(token, percentOf) {
-  const t = token.trim();
-  if (t.endsWith("%")) return parseFloat(t) / 100 * percentOf;
-  return parseFloat(t);
-}
-function parts(fn) {
-  const inner = fn.slice(fn.indexOf("(") + 1, -1).trim();
-  const [main, slashAlpha] = inner.split("/");
-  const channels = main.split(/[\s,]+/).filter(Boolean);
-  let alpha = 1;
-  if (slashAlpha !== void 0) alpha = num(slashAlpha, 1);
-  else if (channels.length === 4) alpha = num(channels.pop(), 1);
-  return { channels, alpha: Number.isFinite(alpha) ? alpha : 1 };
-}
-function hslToRgb(h, s, l) {
-  const k = (n) => (n + h / 30) % 12;
-  const a = s * Math.min(l, 1 - l);
-  const f4 = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
-  return { r: f4(0), g: f4(8), b: f4(4) };
-}
-var clamp012 = (n) => Math.min(1, Math.max(0, n));
-function parseColour(raw) {
-  try {
-    if (raw.startsWith("#")) {
-      const hex2 = raw.slice(1);
-      const alpha2 = hex2.length === 8 ? parseInt(hex2.slice(6), 16) / 255 : hex2.length === 4 ? parseInt(hex2[3] + hex2[3], 16) / 255 : 1;
-      return { oklch: hexToOklch(raw), alpha: alpha2 };
-    }
-    const fn = raw.slice(0, raw.indexOf("(")).toLowerCase();
-    if (fn === "color") {
-      const { channels: channels2, alpha: alpha2 } = parts(raw.replace(/^color\(\s*srgb\s+/i, "srgb("));
-      const [r, g, b] = channels2.map((c) => clamp012(num(c, 1)));
-      if (![r, g, b].every(Number.isFinite)) return null;
-      return { oklch: hexToOklch(formatHex({ r, g, b })), alpha: alpha2 };
-    }
-    const { channels, alpha } = parts(raw);
-    if (channels.length < 3 || channels.some((c) => c.startsWith("var"))) return null;
-    if (fn === "oklch") {
-      const l = num(channels[0], 1);
-      const c = num(channels[1], 0.4);
-      const h = parseFloat(channels[2]);
-      if (![l, c].every(Number.isFinite)) return null;
-      return { oklch: { l, c, h: Number.isFinite(h) ? h : 0 }, alpha };
-    }
-    if (fn === "oklab") {
-      const l = num(channels[0], 1);
-      const a = num(channels[1], 0.4);
-      const b = num(channels[2], 0.4);
-      if (![l, a, b].every(Number.isFinite)) return null;
-      const c = Math.sqrt(a * a + b * b);
-      const h = c < 1e-7 ? 0 : (Math.atan2(b, a) * 180 / Math.PI % 360 + 360) % 360;
-      return { oklch: { l, c, h }, alpha };
-    }
-    if (fn === "rgb" || fn === "rgba") {
-      const [r, g, b] = channels.map((c) => clamp012(num(c, 255) / 255));
-      if (![r, g, b].every(Number.isFinite)) return null;
-      return { oklch: hexToOklch(formatHex({ r, g, b })), alpha };
-    }
-    if (fn === "hsl" || fn === "hsla") {
-      const h = parseFloat(channels[0]);
-      const s = num(channels[1], 1);
-      const l = num(channels[2], 1);
-      if (![h, s, l].every(Number.isFinite)) return null;
-      const rgb = hslToRgb((h % 360 + 360) % 360, clamp012(s), clamp012(l));
-      return { oklch: hexToOklch(formatHex(rgb)), alpha };
-    }
-  } catch {
-    return null;
-  }
-  return null;
-}
-function findColours(value) {
-  const out = [];
-  for (const m of value.matchAll(COLOUR)) {
-    const parsed = parseColour(m[0]);
-    if (parsed) out.push({ raw: m[0], ...parsed, index: m.index ?? 0 });
-  }
-  return out;
-}
-var AI_VIOLET = { hueMin: 268, hueMax: 312, minChroma: 0.1, minL: 0.3, maxL: 0.85 };
-function isAiViolet({ l, c, h }) {
-  return c >= AI_VIOLET.minChroma && h >= AI_VIOLET.hueMin && h <= AI_VIOLET.hueMax && l >= AI_VIOLET.minL && l <= AI_VIOLET.maxL;
-}
-function isCream({ l, c, h }) {
-  return l >= 0.9 && l <= 0.985 && c >= 8e-3 && c <= 0.06 && h >= 55 && h <= 105;
-}
-function isBlueToPurple({ c, h }) {
-  return c >= 0.08 && h >= 240 && h <= 330;
-}
-
 // src/character/tells/source.ts
 function baseClass(cls) {
   let depth = 0;
@@ -9092,6 +9268,7 @@ export {
   RENDERED_TELLS,
   REVEAL_LIMIT,
   REVIEW_PHRASES,
+  SAMPLES_PER_SEGMENT,
   SCALE,
   SECTION_ROLES,
   SHADCN_LIMIT,
@@ -9129,6 +9306,7 @@ export {
   checkCopy,
   checkOrder,
   checkPair,
+  checkPhotoReview,
   checkReason,
   checkRegister,
   checkRestraint,
@@ -9182,6 +9360,8 @@ export {
   formatReport,
   getRegister,
   globToRegExp,
+  gradientContrast,
+  gradientStops,
   groundName,
   harvest,
   hedgeCount,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/craft",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "private": false,
   "description": "The Doman Digital house craft standard as numbers: OKLCh colour ramps that snap to existing anchors, derived semantic tokens with measured WCAG and APCA contrast, one shared motion vocabulary for CSS and JS, and a base stylesheet. Zero dependencies.",
   "license": "Apache-2.0",