@domandigital/craft 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -693,4 +693,1014 @@ declare function tailwindV4Theme(): string;
 /** Density names, re-exported so a consumer can type its shell prop. */
 declare const DENSITY_NAMES: DensityName[];
 
-export { type AccentFork, type AccentForkOptions, type CheckRestraintInput, type ContrastCheck, type ContrastReport, type CraftTokensInput, type CraftTokensResult, DENSITIES, DENSITY_NAMES, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DurationName, EASE, EASE_TUPLE, EXIT_RATIO, type EaseName, type EmitCssOptions, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type Gamut, HOUSE_BUDGET, HOUSE_TYPE, LIGHTNESS_CURVE, type MotionDecision, type MotionKind, type Oklch, type OklchToHexOptions, RAMP_STEPS, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, SCALE, SPACE_STEPS, SPRING, type SectionRhythmOptions, type SemanticInput, type SemanticResult, type ShouldAnimateInput, type SpaceStep, TYPE_STEPS, type TailwindPreset, type TypeStep, accentFork, apcaContrast, checkPair, checkRestraint, craftTokens, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, exitDuration, fluidClamp, fluidSpace, fluidType, formatHex, hexToOklch, inP3Gamut, inSrgbGamut, motionTokens, oklchToHex, oklchToRgb, parseHex, ramp, rampFromAnchors, sectionRhythm, semantic, shouldAnimate, tailwindV3Preset, tailwindV4Theme, toGamut, typeFeatureTokens, wcagContrast };
+/**
+ * A snapshot: what a page looks like once it has rendered, as plain data.
+ *
+ * Source tells read what a site writes. A snapshot reads what a visitor gets:
+ * the font that actually loaded, the colour that actually covers the page,
+ * the sections that actually fade in. The two disagree often enough to need
+ * both. A Tailwind class list can name indigo and a CMS can override it; a
+ * source can name Fraunces and the font can fail to load.
+ *
+ * Everything here is plain JSON so a snapshot can be saved, diffed, attached
+ * to a report and judged again later without a browser. Capturing one needs a
+ * browser (see `@domandigital/craft/audit`); judging one does not.
+ */
+declare const SNAPSHOT_VERSION = 1;
+interface SnapshotColour {
+    /** `rgb(r, g, b)` or `rgba(r, g, b, a)`, as the browser computed it. */
+    value: string;
+    /** Painted area in CSS px², summed over every element using it. */
+    area: number;
+    /** Characters of text drawn in it, for text colours. */
+    chars: number;
+}
+interface SnapshotFont {
+    /** The first family in the computed stack, unquoted. */
+    family: string;
+    /** Characters of visible text set in it. */
+    chars: number;
+    /** Characters of it in headings (h1 to h3 and elements at 28px or more). */
+    displayChars: number;
+    italicChars: number;
+    weights: number[];
+}
+interface SnapshotHeading {
+    level: number;
+    family: string;
+    sizePx: number;
+    weight: number;
+    italic: boolean;
+    /** An `<em>`, `<i>` or italic span inside a non-italic heading: "Beauty, *reimagined*". */
+    italicPart: boolean;
+    text: string;
+    top: number;
+}
+interface SnapshotControl {
+    /** `button` for a <button> or submit, `link` for an anchor styled as a button. */
+    kind: "button" | "link";
+    radiusPx: number;
+    heightPx: number;
+    background: string;
+    text: string;
+}
+type SectionKind = "hero" | "logos" | "stats" | "cards" | "marquee" | "text" | "other";
+interface SnapshotSection {
+    top: number;
+    height: number;
+    kind: SectionKind;
+    /** The first heading's text, or the first words, so a report can name it. */
+    label: string;
+    /** Cards laid out side by side: siblings of similar size in one row. */
+    cards: number;
+    /** Of those cards, how many open with an icon (an <svg> or small image). */
+    iconCards: number;
+    /** Hidden at load, waiting for a scroll to reveal it. */
+    hiddenAtLoad: boolean;
+}
+interface SnapshotGradient {
+    /** Colour stops, as computed. */
+    stops: string[];
+    area: number;
+    radial: boolean;
+}
+interface SnapshotEffects {
+    /** Elements with backdrop-filter blur and a translucent background. */
+    glass: number;
+    /** Text painted with a gradient (background-clip: text). */
+    gradientText: number;
+    gradients: SnapshotGradient[];
+    /** Large blurred shapes or radial gradients behind content with no content of their own. */
+    glows: number;
+    /** Repeating 1px line or dot backgrounds. */
+    gridBackgrounds: number;
+    /** Infinite horizontal translate animations. */
+    marquees: number;
+    /** Cards with a near-invisible border and a wide soft shadow. */
+    hairlineShadowCards: number;
+    /** A small bordered pill directly above the first h1. */
+    eyebrowChip: boolean;
+}
+interface SnapshotMotion {
+    /** Sections hidden at load (opacity near 0 or translated) that appear on scroll. */
+    hiddenSections: number;
+    sections: number;
+    /** Running CSS or Web Animations at capture time. */
+    animations: number;
+    /** A full-screen layer over the page at load that is gone a few seconds later. */
+    introOverlay: boolean;
+}
+interface Snapshot {
+    version: typeof SNAPSHOT_VERSION;
+    url: string;
+    capturedAt: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    pageHeight: number;
+    /** The page ground: the body's computed background, or the html's. */
+    ground: string;
+    colours: {
+        backgrounds: SnapshotColour[];
+        text: SnapshotColour[];
+    };
+    fonts: SnapshotFont[];
+    headings: SnapshotHeading[];
+    controls: SnapshotControl[];
+    sections: SnapshotSection[];
+    effects: SnapshotEffects;
+    motion: SnapshotMotion;
+    /** The design-system measures trawl has collected since v7, kept so it can switch to this. */
+    metrics: {
+        fontSizes: number[];
+        fontWeights: number[];
+        radii: string[];
+        shadows: string[];
+        spacingOnScalePct: number | null;
+        bodyLineLengthCh: number | null;
+        bodyFontSizePx: number | null;
+    };
+}
+
+/**
+ * The shapes shared by the tell catalogue, the source scanner and the copy
+ * engine.
+ *
+ * A tell is a choice an AI model makes when nobody told it otherwise. It is not
+ * a mistake. Every tell here would be fine as a decision; it is flagged because
+ * it is the answer the model reaches for first, so a site full of them reads as
+ * nobody having decided anything.
+ */
+/**
+ * Which wave of model defaults a tell belongs to.
+ *
+ * 1: the first wave (indigo, blue-to-purple gradients, Inter, glass cards).
+ * 2: what models moved to once the first wave was named and banned (cream and
+ *    italic serif, eyebrow chips, bento grids, the marquee).
+ * 3: reserved for what the harvester finds next.
+ *
+ * The tag exists because any fixed list goes stale. Knowing which wave a tell
+ * came from is what lets a report say "this site was built in 2024" rather
+ * than only "this site has tells".
+ */
+type Generation = 1 | 2 | 3;
+/** Where a tell is detected first. A source tell may also carry a rendered path. */
+type Surface = "source" | "copy";
+/**
+ * `warn` is reported and never fails a run unless `--strict` is passed.
+ * `block` fails a run.
+ *
+ * Every entry ships as `warn`. A rule blocks only after its hits across the
+ * estate have been read by a person and the rule tuned against them. A rule
+ * that blocks on day one gets switched off by day three.
+ */
+type Severity = "warn" | "block";
+interface SourceFile {
+    /** Repo-relative path. The extension decides how the file is read. */
+    path: string;
+    text: string;
+}
+type FixtureCase = SourceFile | SourceFile[];
+/** A detector's raw result, before it is placed on a line. */
+interface Hit {
+    path: string;
+    /** Character offset into the file's text. */
+    offset: number;
+    message: string;
+    /** Overrides the excerpt taken from the offset's line. */
+    excerpt?: string;
+}
+interface Finding {
+    tell: string;
+    name: string;
+    generation: Generation;
+    severity: Severity;
+    path: string;
+    /** 1-indexed. 0 for a finding on a rendered page, where `path` is the URL. */
+    line: number;
+    excerpt: string;
+    message: string;
+    fix: string;
+}
+/** A class list as it applies to one element, with where it starts. */
+interface ClassUnit {
+    classes: string[];
+    offset: number;
+}
+interface CssDeclaration {
+    property: string;
+    value: string;
+    /** The innermost rule's prelude: a selector, `@theme`, `@font-face`. */
+    selector: string;
+    offset: number;
+}
+/** A file read once, so every detector works from the same parse. */
+interface ParsedFile extends SourceFile {
+    kind: "markup" | "script" | "css" | "prose" | "other";
+    classUnits: ClassUnit[];
+    declarations: CssDeclaration[];
+}
+interface ScanContext {
+    files: ParsedFile[];
+}
+interface CopyBlock {
+    path: string;
+    text: string;
+    /** Offset of `text[0]` in the original file, so hits land on real lines. */
+    offset: number;
+    /** A quoted string in code, as opposed to text a reader sees in place. */
+    literal?: boolean;
+}
+interface CopyContext {
+    files: SourceFile[];
+    /** Sentences: what word and phrase tells read. */
+    blocks: CopyBlock[];
+    /** Every visible string on its own, however short: what badge, dash and emoji tells read. */
+    strings: CopyBlock[];
+}
+interface TellBase {
+    /** Stable kebab-case id. Exceptions, suppressions and reports refer to it. */
+    id: string;
+    name: string;
+    generation: Generation;
+    severity: Severity;
+    /** Why this is a default rather than a decision, in one or two sentences. */
+    why: string;
+    /** What to do instead. Specific enough to act on without reading anything else. */
+    fix: string;
+    /**
+     * Proof the rule can fire and can stay quiet. Each entry needs at least one
+     * of each, and the catalogue test runs both: a guard that cannot fail is not
+     * a guard.
+     *
+     * Each item is one case, run on its own: a file, or an array of files for a
+     * tell that only exists across several. One case per detection path, so a
+     * path that breaks cannot hide behind one that still works.
+     */
+    fixtures: {
+        flag: FixtureCase[];
+        pass: FixtureCase[];
+    };
+    /** Present when the tell can also be seen on a live page. */
+    rendered?: RenderedPath;
+}
+/**
+ * The same tell measured on a rendered page: pure over a Snapshot, with its
+ * own flag and pass snapshots, proved on their own like any other path.
+ */
+interface RenderedPath {
+    detect(snapshot: Snapshot): Hit[];
+    fixtures: {
+        flag: Snapshot[];
+        pass: Snapshot[];
+    };
+}
+interface SourceTell extends TellBase {
+    surface: "source";
+    detect(ctx: ScanContext): Hit[];
+}
+interface CopyTell extends TellBase {
+    surface: "copy";
+    detect(ctx: CopyContext): Hit[];
+}
+type Tell = SourceTell | CopyTell;
+/**
+ * A declared reason to keep a tell. Lives in the site's `art-direction.json`.
+ *
+ * DD's own brand is violet. A hue rule with no way to say so flags the agency's
+ * own site on every commit, and gets switched off. An exception without a
+ * `because` is not applied: the reason is the point.
+ */
+interface TellException {
+    tell: string;
+    because: string;
+    /** Where the reason comes from: the shopfront, the van, the trade's own look. */
+    evidence?: string;
+    /** Limit the exception to paths containing this string. */
+    path?: string;
+}
+interface CheckOptions {
+    exceptions?: TellException[];
+    /** Run only these tell ids. */
+    only?: string[];
+}
+interface CheckReport {
+    catalogueVersion: string;
+    findings: Finding[];
+    /** Exceptions that were declared but not applied, and why. */
+    rejectedExceptions: {
+        exception: TellException;
+        reason: string;
+    }[];
+    /** Findings each applied exception silenced, so an exception stays visible. */
+    excepted: {
+        tell: string;
+        because: string;
+        count: number;
+    }[];
+    /**
+     * Findings silenced by a `copy-ok` or `craft-ok` marker on the line or the
+     * line above. Listed, never hidden: a marker nobody can see is a hole.
+     */
+    suppressed: {
+        tell: string;
+        path: string;
+        line: number;
+    }[];
+    summary: {
+        files: number;
+        findings: number;
+        byGeneration: Record<Generation, number>;
+        byTell: Record<string, number>;
+        blocking: number;
+    };
+}
+
+/**
+ * Running the catalogue: source scan and copy check.
+ *
+ * Both are pure over `{ path, text }[]`. The CLI reads files and git; a hook,
+ * a CI job and trawl all call these with the same input and get the same
+ * answer.
+ */
+
+/**
+ * Bumped whenever an entry is added, removed or its detection changes, so a
+ * report can say which list it was judged against.
+ */
+declare const CATALOGUE_VERSION = "2026.09.3";
+declare const CATALOGUE: readonly Tell[];
+declare function tellById(id: string): Tell | undefined;
+/** Scan markup, component code and stylesheets for design tells. */
+declare function scanSource(files: SourceFile[], options?: CheckOptions): CheckReport;
+/** Check the prose in files for copy tells. */
+declare function checkCopy(files: SourceFile[], options?: CheckOptions): CheckReport;
+/**
+ * Judge a rendered page. Every tell with a rendered path runs over the
+ * snapshot; findings carry the URL as their path and line 0.
+ */
+declare function auditSnapshot(snapshot: Snapshot, options?: CheckOptions): CheckReport;
+/** Run one tell's detector over some files. What the fixture test calls. */
+declare function runTell(tell: Tell, files: SourceFile[]): Hit[];
+/**
+ * The catalogue as a Markdown table. CHARACTER.md carries this between
+ * markers, and a test fails if the two differ.
+ */
+declare function catalogueTable(): string;
+/**
+ * The copy word and phrase lists, as portable JSON.
+ *
+ * These are the only part of the copy catalogue a non-TypeScript consumer can
+ * use directly: a word list is data, a regex-shaped tell (contrastive
+ * negation, the "No X" badge, em dash, emoji) is not something worth
+ * re-deriving from a JSON export, so those stay TypeScript-only here.
+ *
+ * `claude-kit`'s `copy_check.py` is the reason this exists. It hardcoded its
+ * own copies of these same lists rather than reading this package, and the
+ * two drifted (documented in claude-kit's `house-style/copy-rules.md`, "Note
+ * the enforcement gap"). `word-lists.json` is the file that ends the drift:
+ * `install/sync-copy-wordlists.sh` on that side copies it in verbatim, same
+ * shape as `sync-craft-standard.sh` does for `STANDARD.md`. Regenerate the
+ * checked-in `word-lists.json` with `pnpm --filter @domandigital/craft run
+ * docs` after changing any list in `tells/copy.ts`.
+ */
+declare function wordListsJson(): string;
+
+/** Plain-text rendering of a report, for a terminal or a hook. */
+
+declare function formatReport(report: CheckReport, title: string): string;
+
+/**
+ * The rendered detection path for tells that can be seen on a live page.
+ *
+ * Same tells, same ids, measured on what the visitor gets rather than on what
+ * the source says. A report can then say "Inter in source and on the page",
+ * or catch the violet a CMS sets that no source file mentions.
+ *
+ * Pure over a Snapshot. Thresholds are here, next to their fixtures, and not
+ * in the in-page collector, so each one can be proved without a browser.
+ */
+
+declare const RENDERED_PATHS: Record<string, RenderedPath>;
+
+/**
+ * A plain, decided-looking page as a snapshot, for fixtures.
+ *
+ * Every rendered tell's pass case starts from this and its flag case changes
+ * one thing, so a detector is proved against the difference it claims to see.
+ * Exported so a client repo can write the same kind of test.
+ */
+
+type SnapshotPatch = {
+    [K in keyof Snapshot]?: Snapshot[K] extends object ? Partial<Snapshot[K]> | Snapshot[K] : Snapshot[K];
+};
+declare function makeSnapshot(patch?: SnapshotPatch): Snapshot;
+
+/**
+ * Font family names as a browser reports them, turned back into the names a
+ * person would use.
+ *
+ * `next/font` renames every family it loads: Inter arrives as
+ * `__Inter_d65c78` and its metric-matched fallback as `__Inter_Fallback_d65c78`.
+ * A rendered check that compared raw names would never see a single reflex
+ * font on a Next.js site, which is most of the estate.
+ */
+type FontClass = "serif" | "sans" | "mono" | "script" | "system";
+declare function normaliseFamily(raw: string): string;
+declare function fontClass(family: string): FontClass;
+
+/**
+ * A fingerprint: the handful of choices that make a site look like itself,
+ * reduced to something two sites can be compared on.
+ *
+ * Signals 2 and 3 of CHARACTER.md both need a distance. "Would a model have
+ * built this anyway" is a distance from what the model builds; "does this
+ * look like the agency's other sites" is a distance from the estate. Neither
+ * cares about the exact pixels. They care whether the accent, the type, the
+ * ground, the shape language, the motion and the running order were chosen
+ * or defaulted, so that is what a fingerprint records.
+ *
+ * Pure. Built from a Snapshot, so it describes what a visitor gets.
+ */
+
+declare const FINGERPRINT_VERSION = 1;
+interface Fingerprint {
+    version: typeof FINGERPRINT_VERSION;
+    /** The most prominent chromatic colour: button fills first, then painted area, then text. */
+    accent: Oklch | null;
+    ground: Oklch;
+    display: {
+        family: string;
+        class: FontClass;
+    };
+    body: {
+        family: string;
+        class: FontClass;
+    };
+    /** Median button corner radius over its height, 0 (square) to 0.5 (pill). */
+    roundness: number | null;
+    /** Share of below-the-fold sections that wait for a scroll to appear. */
+    motion: number;
+    /** Which second-look effects are present, as tell ids. */
+    effects: string[];
+    /** Section kinds in running order, hero first. */
+    layout: SectionKind[];
+}
+declare function fingerprint(s: Snapshot): Fingerprint;
+interface FingerprintDistance {
+    /** 0 identical, 1 nothing in common. A weighted mean of the parts. */
+    total: number;
+    parts: {
+        accent: number;
+        ground: number;
+        type: number;
+        shape: number;
+        motion: number;
+        effects: number;
+        layout: number;
+    };
+}
+/**
+ * How much each part counts. Accent and type are where a model's defaults
+ * show first and where a real business has something of its own, so they
+ * carry half the weight between them.
+ */
+declare const DISTANCE_WEIGHTS: {
+    readonly accent: 0.25;
+    readonly type: 0.25;
+    readonly ground: 0.1;
+    readonly shape: 0.1;
+    readonly motion: 0.1;
+    readonly effects: 0.1;
+    readonly layout: 0.1;
+};
+declare function fingerprintDistance(a: Fingerprint, b: Fingerprint): FingerprintDistance;
+/**
+ * The nearest neighbours of a fingerprint in a set, closest first. Typicality
+ * (phase D) and estate distance (phase E) are both this, against different sets.
+ */
+declare function nearest<T>(target: Fingerprint, set: {
+    id: T;
+    fingerprint: Fingerprint;
+}[], k?: number): {
+    id: T;
+    distance: FingerprintDistance;
+}[];
+
+/**
+ * Every colour syntax the estate actually writes, read into OKLCh.
+ *
+ * A hue rule that only knows Tailwind class names misses the site that sets its
+ * violet as `#5a35d1`, which is exactly what the old checker did. Hue is judged
+ * in OKLCh because that is where "violet" is one range of angles; in RGB and HSL
+ * the same perceived hue drifts with lightness.
+ */
+
+interface FoundColour {
+    raw: string;
+    oklch: Oklch;
+    alpha: number;
+    /** Offset of `raw` inside the searched string. */
+    index: number;
+}
+declare function parseColour(raw: string): {
+    oklch: Oklch;
+    alpha: number;
+} | null;
+declare function findColours(value: string): FoundColour[];
+/**
+ * The indigo-to-purple band models default to, in OKLCh hue degrees.
+ *
+ * Tailwind's blue-600 sits at 262, indigo-600 at 277, violet-600 at 293,
+ * purple-600 at 304 and fuchsia at 322. The band starts past blue, so a
+ * plumber's navy is left alone, and stops before fuchsia and pink, which are
+ * a different conversation. Chroma must be high enough to read as a colour
+ * choice rather than a tinted grey.
+ */
+declare const AI_VIOLET: {
+    readonly hueMin: 268;
+    readonly hueMax: 312;
+    readonly minChroma: 0.1;
+    readonly minL: 0.3;
+    readonly maxL: 0.85;
+};
+declare function isAiViolet({ l, c, h }: Oklch): boolean;
+/**
+ * The warm off-white the second wave moved to once violet was named: parchment,
+ * linen, oat. Very light, faintly saturated, yellow-orange hue.
+ */
+declare function isCream({ l, c, h }: Oklch): boolean;
+
+/**
+ * Tells found in source: markup, component code and stylesheets.
+ *
+ * Detectors are deliberately plain. Each reads the parse every other detector
+ * reads, looks for one pattern, and says where. Thresholds for the counted
+ * tells (reveals, pills) come from the estate survey: they sit below the sites
+ * that read as templated and above the ones that do not.
+ */
+
+/** The faces a model picks when the brief does not name one. */
+declare const REFLEX_FONTS_1: readonly ["Inter", "Roboto", "Open Sans", "Poppins", "Montserrat", "Lato"];
+/** What models moved to once Inter was named and banned. */
+declare const REFLEX_FONTS_2: readonly ["Inter Tight", "DM Sans", "Manrope", "Space Grotesk", "Plus Jakarta Sans", "Outfit", "Geist", "Sora", "Instrument Sans", "Instrument Serif", "Fraunces", "Playfair Display", "Cormorant Garamond", "DM Serif Display"];
+/** Above this many scroll reveals in one scan, reveal is the default, not a choice. */
+declare const REVEAL_LIMIT = 12;
+/** Above this many fully rounded shapes in one scan, the pill is the shape language by accident. */
+declare const PILL_LIMIT = 30;
+/** A components/ui folder with this many stock primitives is a generator's dump. */
+declare const SHADCN_LIMIT = 12;
+/** The stock shadcn/ui primitives, as their files are named. */
+declare const SHADCN_PRIMITIVES: readonly ["accordion", "alert", "alert-dialog", "aspect-ratio", "avatar", "badge", "breadcrumb", "button", "calendar", "card", "carousel", "chart", "checkbox", "collapsible", "command", "context-menu", "dialog", "drawer", "dropdown-menu", "form", "hover-card", "input", "input-otp", "label", "menubar", "navigation-menu", "pagination", "popover", "progress", "radio-group", "resizable", "scroll-area", "select", "separator", "sheet", "sidebar", "skeleton", "slider", "sonner", "switch", "table", "tabs", "textarea", "toast", "toaster", "toggle", "toggle-group", "tooltip"];
+
+/**
+ * Tells found in copy.
+ *
+ * The rule lists live here as data, with fixtures, rather than hardcoded in a
+ * checker in another repo where they had already drifted from the written
+ * rules. Since 2026.09.2 this is also where the house copy rules live: the
+ * blocking tier of claude-kit's `house-style/copy-rules.md` is carried by its
+ * own tells here, and `copy-check` is a wrapper that decides which of them
+ * fail a commit. craft itself ships every tell as `warn`.
+ *
+ * Word and phrase tells read sentences (`ctx.blocks`). Tells that key on a
+ * shape short enough to sit in a label, an em dash, an emoji, a "No catch."
+ * badge, read every visible string (`ctx.strings`).
+ */
+
+/**
+ * Words a model reaches for that a person writing about their own business
+ * rarely uses. The house-blocking words (seamless, empower, delve, leverage,
+ * harness) are not here: they have tells of their own, so a finding says
+ * which tier it belongs to.
+ */
+declare const AI_WORDS: readonly ["tapestry", "testament", "realm", "embark", "embarking", "unleash", "unlocks", "unlocking", "elevate", "elevates", "elevated", "elevating", "bustling", "nestled", "meticulous", "meticulously", "paramount", "furthermore", "moreover", "navigating", "ever-evolving", "unparalleled"];
+declare const STOCK_PHRASES: readonly ["in today's digital age", "to the next level", "one-stop shop", "second to none", "we pride ourselves", "passionate about", "your journey", "our journey", "curated", "crafted with care", "tailored to your", "peace of mind"];
+/**
+ * The phrase list from the blocking tier of copy-rules.md, plus the phrases
+ * the old copy-check blocked that the rules had never written down. Each is a
+ * phrase generated copy uses far more than people do.
+ */
+declare const AI_PHRASES: readonly ["let's dive in", "dive into", "let's unpack", "let's break this down", "let's break it down", "here's the thing", "it's important to note", "it's important to remember", "it is worth noting that", "at its core", "the key takeaway", "the reality is", "the truth is", "increasingly digital", "seamless", "seamlessly", "unlock your", "unlock the power", "meaningful impact", "drive meaningful", "foster collaboration", "fosters collaboration", "fostering collaboration", "comprehensive guide to", "look no further", "in the event that", "at no additional cost to you", "rest assured", "when it comes to", "we have got you covered", "we've got you covered"];
+/** Blocked because a plainer word almost always exists. */
+declare const PLAINER_WORDS: readonly ["empower", "empowers", "empowered", "empowering", "harness", "harnesses", "harnessed", "harnessing", "delve", "delves", "delved", "delving", "leverage", "leverages", "leveraged", "leveraging"];
+/** The corporate buzzwords of the house list. Older than any model; models still reach for them. */
+declare const BUZZWORDS: readonly ["synergy", "synergise", "synergize", "cutting-edge", "cutting edge", "best-in-class", "best in class", "best of breed", "game-changer", "game changer", "paradigm shift", "world-class", "state of the art", "state-of-the-art", "mission-critical", "low-hanging fruit", "move the needle", "circle back", "touch base", "reach out", "value-add", "robust", "turnkey", "holistic", "disruptive"];
+declare const NEGATIVE_REASSURANCE: readonly ["no risk", "never locked in", "nothing goes wrong", "no hidden fees", "never pay", "without the hassle", "no surprises"];
+/** Banned only when vague. Reported for review, never blocking. */
+declare const VAGUE_WORDS: readonly ["innovative", "scalable", "end-to-end", "streamline", "solutions"];
+/** The review tier of copy-rules.md: normal English once, a tell when stacked. */
+declare const REVIEW_PHRASES: readonly ["great question", "of course!", "absolutely!", "absolutely,", "truly", "genuinely", "deeply", "ultimately", "one-size-fits-all", "one size fits all", "let me know if you'd", "the single most", "by far the most", "hands down the", "arguably the best", "bar none"];
+
+/**
+ * `art-direction.json`: what a site decided about how it looks, and why.
+ *
+ * CHARACTER.md's reason rule lives here. Every expressive choice records a
+ * `because` drawn from the client's real world (the shopfront, the van, the
+ * trade's own lettering, the place, the materials) and points at a source
+ * that shows it. A choice with no reason is a default, however good it looks.
+ *
+ * The file also carries the tell exceptions craft has read since phase A, in
+ * the same shape, so an existing file stays valid.
+ */
+
+declare const DIRECTION_VERSION = 1;
+/** Where a reason comes from. Deliberately physical: a mood board is not a source. */
+declare const SOURCE_KINDS: readonly ["livery", "shopfront", "signage", "packaging", "product", "uniform", "interior", "place", "material", "trade", "print", "photo", "founder"];
+type SourceKind = (typeof SOURCE_KINDS)[number];
+interface DirectionSource {
+    /** Short id a choice refers to: "van", "fascia", "price-list". */
+    id: string;
+    kind: SourceKind;
+    /** What it is and where, in a sentence. */
+    note: string;
+    /** A photo or file in the repo, or a URL. */
+    path?: string;
+    /** Colours read off it by a person or by `craft direction propose`, as hex. */
+    colours?: string[];
+    /** Lettering seen on it: "hand-painted sign-writing", "stencilled capitals". */
+    lettering?: string;
+}
+/** The expressive choices. Layout and navigation are not here: they stay conventional. */
+declare const CHOICE_KEYS: readonly ["accent", "ground", "display", "body", "shape", "motif", "signature"];
+type ChoiceKey = (typeof CHOICE_KEYS)[number];
+interface DirectionChoice {
+    /** A colour as hex for accent and ground, a family name for display and body, words otherwise. */
+    value: string;
+    because: string;
+    /** Source ids this reason rests on. */
+    evidence: string[];
+}
+interface ArtDirection {
+    $schema?: string;
+    version: typeof DIRECTION_VERSION;
+    client: string;
+    /** Who, where, and what they do, in a sentence or two. The brief a model would have been given. */
+    brief: string;
+    sources: DirectionSource[];
+    choices: Partial<Record<ChoiceKey, DirectionChoice>>;
+    exceptions?: TellException[];
+}
+type DirectionSeverity = "error" | "warn";
+interface DirectionProblem {
+    severity: DirectionSeverity;
+    /** Where in the file: "choices.accent.because", "sources[2].kind". */
+    at: string;
+    message: string;
+}
+interface DirectionReport {
+    valid: boolean;
+    problems: DirectionProblem[];
+    /** How many of the seven choices carry an accepted reason. */
+    decided: number;
+}
+
+/**
+ * Checking an art direction: the file's shape, the reason rule, and whether
+ * the site actually does what the file says.
+ *
+ * Pure. The CLI reads the file, any snapshot and the paths it cites.
+ */
+
+interface ValidateContext {
+    /** The fingerprint of the rendered site, to check the file against what ships. */
+    fingerprint?: Fingerprint;
+    /** Which cited paths exist, when the caller can look. */
+    pathExists?: (path: string) => boolean;
+}
+declare function validateDirection(input: unknown, ctx?: ValidateContext): DirectionReport;
+
+/**
+ * A first art-direction.json for a site that exists: what it does today,
+ * written down, with every reason left empty.
+ *
+ * Empty on purpose. `validateDirection` fails the file until each choice has
+ * a source and a reason, so the first thing init produces is the list of
+ * things nobody decided.
+ */
+
+declare function initDirection(input: {
+    client?: string;
+    brief?: string;
+    current?: Fingerprint;
+    exceptions?: ArtDirection["exceptions"];
+}): ArtDirection;
+
+/**
+ * Proposing an art direction from the client's world.
+ *
+ * A proposal is a draft, never a decision. Every choice it writes carries a
+ * `because` that starts "PROPOSED:", and `validateDirection` rejects that
+ * prefix, so the file cannot pass until a person has looked at the van, agreed
+ * the green is the van's green, and said so in their own words.
+ *
+ * Pure. Pixels come in as numbers; the CLI decodes the images.
+ */
+
+declare const PROPOSED = "PROPOSED:";
+interface PaletteColour {
+    hex: string;
+    /** Share of sampled pixels, 0 to 1. */
+    share: number;
+    oklch: Oklch;
+}
+/**
+ * The dominant colours in an RGBA pixel buffer: k-means in OKLab, so colours
+ * cluster the way they look alike. Deterministic: seeded by lightness order,
+ * not at random, so the same photo always proposes the same colours.
+ */
+declare function paletteFromPixels(rgba: ArrayLike<number>, k?: number, maxSamples?: number): PaletteColour[];
+interface ProposeInput {
+    client: string;
+    brief: string;
+    sources: DirectionSource[];
+    /** What the site ships today, if it exists. */
+    current?: Fingerprint;
+    /** The rest of the estate, so a proposal does not land on a sibling. */
+    estate?: {
+        id: string;
+        fingerprint: Fingerprint;
+    }[];
+}
+interface Proposal {
+    key: ChoiceKey;
+    candidates: {
+        value: string;
+        evidence: string[];
+        note: string;
+    }[];
+}
+declare function propose(input: ProposeInput): {
+    proposals: Proposal[];
+    direction: ArtDirection;
+};
+
+/**
+ * The counterfactual: what a model builds for this brief when nobody tells it
+ * anything else. Signal 2 of CHARACTER.md.
+ *
+ * A null model is about twenty pages generated from one brief, each reduced to
+ * a fingerprint. A site is typical when it sits as close to those pages as they
+ * sit to each other. That question keeps working when model defaults move,
+ * which a fixed list of tells cannot: ban Inter and the null model moves with
+ * the model, so the comparison moves too.
+ *
+ * `harvest` reads the same pages the other way round: which choices recur
+ * across them that the catalogue does not know yet. Those are the candidates
+ * for the next generation of tells. A person decides; nothing is added here.
+ *
+ * Pure. Generating pages and snapshotting them lives in the CLI.
+ */
+
+declare const NULL_VERSION = 1;
+/**
+ * The prompt a null run gets: the brief, and nothing about how it should look.
+ * Changing this changes every null model built after it, so it is versioned
+ * by being recorded in each one.
+ */
+declare function nullPrompt(brief: string): string;
+interface NullRun {
+    /** The page's file name without extension: "01". */
+    id: string;
+    fingerprint: Fingerprint;
+    /** Catalogue tells found on the page, source and rendered, each once. */
+    tells: string[];
+    /** Every visible string on the page, for the phrase harvest. */
+    copy: string[];
+}
+interface NullModel {
+    version: typeof NULL_VERSION;
+    brief: string;
+    prompt: string;
+    /** What was asked for with --model, or "default". */
+    model: string;
+    catalogueVersion: string;
+    builtAt: string;
+    runs: NullRun[];
+}
+/** The HTML document in a model's reply, without code fences or commentary. */
+declare function extractHtml(reply: string): string | null;
+/** Fewer runs than this and the spread of the null is noise, so nothing is judged. */
+declare const MIN_RUNS = 5;
+/** Typical when at least this share of the null's own pages sit further out. */
+declare const TYPICAL_AT = 0.1;
+interface Typicality {
+    /**
+     * 0 to 1: the share of the null's own pages that sit further from the rest
+     * than this page sits from them. 1 is more typical than anything the model
+     * built; 0 is further out than every one of them.
+     */
+    score: number;
+    typical: boolean;
+    /** Mean distance to the k nearest null pages. */
+    distance: number;
+    /** The same measure for each null page against the others, median. */
+    baseline: number;
+    nearest: {
+        id: string;
+        distance: number;
+    }[];
+    /** The choices this page shares with most of the null: why it reads as typical. */
+    shared: {
+        part: string;
+        value: string;
+        runs: number;
+        of: number;
+    }[];
+}
+/**
+ * How typical a page is against one or more null models (pooled). Every null
+ * page is scored against the others the same way, leaving itself out, so the
+ * threshold comes from the model's own spread and not from a number picked
+ * here: a page drawn from the null is flagged nine times in ten by
+ * construction, and the calibration checks whether real sites are not.
+ */
+declare function typicality(target: Fingerprint, runs: NullRun[], k?: number): Typicality;
+declare function hueName(o: Oklch | null): string;
+declare function groundName(o: Oklch): string;
+declare function shapeName(roundness: number | null): string;
+/** The discrete choices a fingerprint makes, as part → value. What a person would name. */
+declare function choicesOf(fp: Fingerprint): Record<string, string[]>;
+type CandidateKind = "face" | "accent" | "ground" | "shape" | "motion" | "opening" | "tell" | "phrase";
+interface HarvestCandidate {
+    kind: CandidateKind;
+    value: string;
+    /** Null pages that make this choice, across every model given. */
+    runs: number;
+    of: number;
+    /** Distinct briefs it turned up for. A habit shows across briefs; a brief's own words do not. */
+    briefs: number;
+    /** The catalogue tell that already catches it, or null when nothing does. */
+    known: string | null;
+    /** An example, for a phrase: the string it came from. */
+    example?: string;
+}
+interface HarvestOptions {
+    /** Report a choice made by at least this share of pages. Default 0.25. */
+    minShare?: number;
+    /** Which copy tell, if any, already catches a phrase. The CLI passes the catalogue's. */
+    copyTell?: (phrase: string) => string | null;
+}
+/**
+ * Choices that recur across null pages, with the tell that already catches
+ * each, if any. The ones with `known: null` are the next generation's
+ * candidates. Nothing here decides: a person reads them, and a candidate only
+ * becomes a tell with a flag case and a pass case like every other.
+ */
+declare function harvest(models: Pick<NullModel, "brief" | "runs">[], options?: HarvestOptions): HarvestCandidate[];
+/** A representative colour for a hue family, for a report. */
+declare function hueSwatch(runs: NullRun[], hue: string): string | null;
+
+/**
+ * The estate register: every site the agency has shipped, fingerprinted, so a
+ * new one can be checked against its siblings. Signal 3 of CHARACTER.md.
+ *
+ * An agency's biggest tell is its clients looking like each other. No single
+ * site shows it; only the set does. So the register holds one fingerprint per
+ * site, and `compareToEstate` says which sites a page sits nearest and what
+ * it shares with them.
+ *
+ * The line for "siblings" is not a number picked here. Two different
+ * businesses are siblings when they sit closer together than two pages Claude
+ * builds for the same brief usually do: if a barber and an electrician look
+ * more alike than two drafts of one barber, nobody chose either look. The
+ * median comes from null models when they are given, and from the 2026-09-23
+ * calibration when they are not.
+ *
+ * Pure. The CLI reads and writes the register file.
+ */
+
+declare const ESTATE_VERSION = 1;
+/**
+ * Median fingerprint distance between two null pages built from the same
+ * brief, across seven briefs and 1,330 pairs (calibration/null, 2026-09-23).
+ */
+declare const SIBLING_AT = 0.31;
+interface EstateSite {
+    /** Short kebab-case id: "rmp", "chair-and-blade". */
+    id: string;
+    client: string;
+    url: string;
+    /** Where the site's source lives, if known: "rmp474/RMP-Electrical". */
+    repo?: string;
+    fingerprint: Fingerprint;
+    /** Rendered tells found when it was added, for the record. */
+    tells: string[];
+    addedAt: string;
+}
+interface EstateRegister {
+    version: typeof ESTATE_VERSION;
+    sites: EstateSite[];
+}
+declare function emptyEstate(): EstateRegister;
+/** Add a site, or replace the one with the same id. Sorted by id so the file diffs cleanly. */
+declare function addSite(register: EstateRegister, site: EstateSite): EstateRegister;
+/**
+ * What two fingerprints effectively share, named the way a person would see
+ * it: "Fraunces headline", "no accent", "pill buttons". A part counts when its
+ * distance is 0.2 or less.
+ */
+declare function sharedParts(a: Fingerprint, b: Fingerprint, d?: FingerprintDistance): string[];
+interface EstateMatch {
+    id: string;
+    distance: number;
+    sibling: boolean;
+    shared: string[];
+}
+/** The sites nearest a fingerprint, closest first, leaving out `exclude` (the site itself). */
+declare function compareToEstate(target: Fingerprint, register: EstateRegister, options?: {
+    exclude?: string;
+    siblingAt?: number;
+}): EstateMatch[];
+interface EstatePair {
+    a: string;
+    b: string;
+    distance: number;
+    sibling: boolean;
+    shared: string[];
+}
+/** Every pair in the register, closest first. */
+declare function estatePairs(register: EstateRegister, siblingAt?: number): EstatePair[];
+/**
+ * The sibling line from null models: the median distance between two pages
+ * built from the same brief. Each inner array is one brief's fingerprints.
+ */
+declare function siblingLine(briefs: Fingerprint[][]): number;
+
+/**
+ * The character report: the three signals and the reason rule, read together.
+ *
+ * No one signal decides. A site can carry no catalogued tell and still be what
+ * Claude builds for its brief (signal 2); it can be nothing like the null and
+ * still wear last year's reflexes (signal 1); it can pass both and be a twin of
+ * the agency's other client (signal 3). And a site that passes all three has
+ * still only avoided defaults: "decided" needs the reasons written down.
+ *
+ * So the verdict is:
+ *   default   two or more signals raised
+ *   mixed     one raised
+ *   decided   none raised, and all measured, reasons included
+ *   unproven  none raised, but something was not measured. Unverified is
+ *             never a pass.
+ *
+ * The actions change the surface: type, colour, shape, effects, motion, copy.
+ * Never the page grammar. A layout tell says what to change about how a
+ * section looks, not that it should move.
+ *
+ * Pure. The CLI gathers the inputs.
+ */
+
+/** Three or more distinct design tells: the rule fixed for the 2026-09-23 calibration. */
+declare const TELL_HEAVY = 3;
+/** Fewer choices decided than this and the reasons are not yet a direction. */
+declare const MIN_DECIDED = 5;
+type Verdict = "default" | "mixed" | "decided" | "unproven";
+type Area = "direction" | "type" | "colour" | "shape" | "effects" | "motion" | "layout" | "copy";
+interface SignalResult {
+    id: "tells" | "typicality" | "estate" | "reasons";
+    /** null when it was not measured. */
+    raised: boolean | null;
+    detail: string;
+}
+interface Action {
+    area: Area;
+    what: string;
+    why: string;
+    /** 1 first. Deciding comes before changing, so direction actions are always 1. */
+    priority: 1 | 2 | 3;
+    /** The art-direction choice that settles it, when there is one. */
+    choice?: ChoiceKey;
+}
+interface CharacterReport {
+    site: string;
+    verdict: Verdict;
+    summary: string;
+    signals: SignalResult[];
+    actions: Action[];
+}
+interface CharacterInputs {
+    site: string;
+    /** Source and rendered findings, merged. */
+    findings?: CheckReport | null;
+    typicality?: Typicality | null;
+    estate?: EstateMatch[] | null;
+    direction?: DirectionReport | null;
+}
+declare function characterReport(input: CharacterInputs, copyTells?: Set<string>): CharacterReport;
+
+/**
+ * `craft retrofit`: a character report turned into the checklist a retrofit
+ * session works through, in the order that works: decide, then change.
+ *
+ * Every change is tied to the art-direction choice that settles it, and shows
+ * the decided value and its reason when there is one. A change with no
+ * decided value waits for the decision; otherwise the retrofit swaps one
+ * default for the next.
+ *
+ * Pure. Returns Markdown.
+ */
+
+declare function retrofitPlan(report: CharacterReport, direction?: ArtDirection | null): string;
+
+export { AI_PHRASES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type Area, type ArtDirection, BUZZWORDS, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type ContrastCheck, type ContrastReport, type CopyTell, type CraftTokensInput, type CraftTokensResult, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionProblem, type DirectionReport, type DirectionSource, type DurationName, EASE, EASE_TUPLE, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, type Finding, type Fingerprint, type FingerprintDistance, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, type Gamut, type Generation, HOUSE_BUDGET, HOUSE_TYPE, type HarvestCandidate, type HarvestOptions, type Hit, LIGHTNESS_CURVE, MIN_DECIDED, MIN_RUNS, type MotionDecision, type MotionKind, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PILL_LIMIT, PLAINER_WORDS, PROPOSED, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, REFLEX_FONTS_1, REFLEX_FONTS_2, RENDERED_PATHS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, SCALE, SHADCN_LIMIT, SHADCN_PRIMITIVES, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPRING, STOCK_PHRASES, type SectionKind, type SectionRhythmOptions, type SemanticInput, type SemanticResult, type Severity, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Surface, TELL_HEAVY, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type Tell, type TellException, type TypeStep, type Typicality, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, auditSnapshot, catalogueTable, characterReport, checkCopy, checkPair, checkRestraint, choicesOf, compareToEstate, craftTokens, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, emptyEstate, estatePairs, exitDuration, extractHtml, findColours, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatHex, formatReport, groundName, harvest, hexToOklch, hueName, hueSwatch, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isCream, makeSnapshot, motionTokens, nearest, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, paletteFromPixels, parseColour, parseHex, propose, ramp, rampFromAnchors, retrofitPlan, runTell, scanSource, sectionRhythm, semantic, shapeName, sharedParts, shouldAnimate, siblingLine, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, typeFeatureTokens, typicality, validateDirection, wcagContrast, wordListsJson };