@vectoriox/iox-ui 5.46.0 → 5.47.0

package/src/harness-core/lint.ts

@@ -0,0 +1,94 @@
+import { DesignChoices, DesignMotion, parseHexColor, rgbToOklab, SPEC_AXES } from '@vectoriox/iox-ui/design-core';
+import type { FactKey } from '@vectoriox/iox-ui/generation-core';
+
+import { AvoidCheck, BUSINESS_TYPES, BusinessType, COPY_LENGTH_ORDER, CopyLength, isLookRule } from './business-types';
+import { lookMatches } from './look';
+
+/**
+ * Design advice (AI plan rev 3 §3f, H5's core): the business type's avoid rules run against a built site's
+ * look, home sections, facts and copy length. ADVICE only — Needs attention and the Publish dialog show it,
+ * "Keep it" dismisses it, and nothing is ever refused on it (H-D9).
+ */
+
+export enum LintKind {
+    Look = 'look',
+    Content = 'content',
+    Fact = 'fact',
+}
+
+export interface LintFinding {
+    kind: LintKind;
+    say: string;
+    fact?: FactKey;
+}
+
+/** What the lint reads of a site. */
+export interface LintSite {
+    design: Pick<DesignChoices, 'flavorId' | 'seed' | 'motion' | 'density' | 'mode'> & Partial<Pick<DesignChoices, 'tint'>> & Partial<DesignMotion>;
+    moods?: ReadonlyArray<string>;
+    /** The home page's section patterns. */
+    homePatterns?: ReadonlyArray<string>;
+    /** Every page's section patterns (defaults to the home page's). */
+    allPatterns?: ReadonlyArray<string>;
+    facts?: Partial<Record<FactKey, string>>;
+    copyLength?: `${CopyLength}`;
+    heroHasImage?: boolean;
+}
+
+const DEGREES = 180 / Math.PI;
+const FULL_TURN = 360;
+/** How far a site may move above what its kind of business usually wears before the lint says so. */
+export const ANIMATE_ADVICE_STEPS = 2;
+const ANIMATE_ORDER = Object.keys(SPEC_AXES.animations);
+
+/** A colour's OKLCH hue (degrees) and chroma, through design-core's one OKLab conversion. */
+export function oklchHue(hex: string): { hue: number; chroma: number } | null {
+    const rgb = parseHexColor(hex);
+    if (!rgb) return null;
+    const { a, b } = rgbToOklab(rgb);
+    return { hue: (Math.atan2(b, a) * DEGREES + FULL_TURN) % FULL_TURN, chroma: Math.hypot(a, b) };
+}
+
+const familyOf = (patternId: string) => patternId.split('.')[0];
+
+export function lintDesign(site: LintSite, typeId: string, types: ReadonlyArray<BusinessType> = BUSINESS_TYPES): LintFinding[] {
+    const type = types.find(t => t.id === typeId);
+    if (!type) return [];
+    const out: LintFinding[] = [];
+    const home = site.homePatterns ?? [];
+    const all = site.allPatterns ?? home;
+    for (const rule of type.avoid) {
+        if (isLookRule(rule)) {
+            if (lookMatches(rule.when, site.design, site.moods ?? [])) out.push({ kind: LintKind.Look, say: rule.say });
+            continue;
+        }
+        switch (rule.check) {
+            case AvoidCheck.NeedsFamily:
+                if (!home.some(id => familyOf(id) === rule.family)) out.push({ kind: LintKind.Content, say: rule.say });
+                break;
+            case AvoidCheck.NeedsFact:
+                if (!site.facts?.[rule.fact]) out.push({ kind: LintKind.Fact, say: rule.say, fact: rule.fact });
+                break;
+            case AvoidCheck.ImageHero:
+                if (!site.heroHasImage) out.push({ kind: LintKind.Content, say: rule.say });
+                break;
+            case AvoidCheck.NoPattern:
+                if (all.includes(rule.pattern)) out.push({ kind: LintKind.Content, say: rule.say });
+                break;
+            case AvoidCheck.CopyLength:
+                if (site.copyLength && COPY_LENGTH_ORDER.indexOf(site.copyLength) > COPY_LENGTH_ORDER.indexOf(rule.max)) out.push({ kind: LintKind.Content, say: rule.say });
+                break;
+            case AvoidCheck.BrandHue: {
+                const hue = oklchHue(site.design.seed);
+                if (hue && hue.chroma >= rule.minChroma && hue.hue >= rule.from && hue.hue <= rule.to) out.push({ kind: LintKind.Look, say: rule.say });
+                break;
+            }
+        }
+    }
+    // Rev 3.1: two levels above what this kind of business usually wears (Subtle → Lively) is advice, never a block.
+    if (site.design.animate && ANIMATE_ORDER.indexOf(site.design.animate) >= ANIMATE_ORDER.indexOf(type.moves.animate) + ANIMATE_ADVICE_STEPS) {
+        const usual = (SPEC_AXES.animations as Readonly<Record<string, { label: string }>>)[type.moves.animate].label;
+        out.push({ kind: LintKind.Look, say: `${type.label} sites usually move less (${usual}); this much movement as people scroll can feel restless.` });
+    }
+    return out;
+}

package/src/harness-core/look.ts

@@ -0,0 +1,32 @@
+import type { DesignChoices, DesignMode, DesignMotion, StylePreset } from '@vectoriox/iox-ui/design-core';
+
+import { LookCondition } from './business-types';
+
+/** The parts of a look a rule can name: the design's choices (motion included) in one colour mode. */
+export type LookDesign = Pick<DesignChoices, 'flavorId' | 'motion' | 'density'> & Partial<Pick<DesignChoices, 'tint'>>
+    & Partial<DesignMotion> & { mode: DesignMode };
+
+const LIST_AXES = ['flavor', 'mode', 'motion', 'tint', 'density', 'scroll', 'animate', 'between'] as const;
+type ListAxis = (typeof LIST_AXES)[number];
+const DESIGN_KEY: Readonly<Record<ListAxis, keyof LookDesign>> = {
+    flavor: 'flavorId', mode: 'mode', motion: 'motion', tint: 'tint', density: 'density',
+    scroll: 'scroll', animate: 'animate', between: 'between',
+};
+
+/** True when `design` (worn with `moods`) is the look `when` describes — every axis it names must match. */
+export function lookMatches(when: LookCondition, design: LookDesign, moods: ReadonlyArray<string>): boolean {
+    for (const axis of LIST_AXES) {
+        const values = when[axis] as ReadonlyArray<string> | undefined;
+        if (values && !values.includes(String(design[DESIGN_KEY[axis]] ?? ''))) return false;
+    }
+    if (when.moods && !when.moods.some(m => moods.includes(m))) return false;
+    return true;
+}
+
+/** A style preset as a rule sees it, in `mode` (default: the mode it opens in). */
+export function presetLook(preset: StylePreset, mode: DesignMode = preset.modes[0]): LookDesign {
+    return {
+        flavorId: preset.flavorId, motion: preset.motion, density: preset.density, tint: preset.tint, mode,
+        ...preset.moves,
+    };
+}

package/src/harness-core/motion.ts

@@ -0,0 +1,67 @@
+import { DesignMotion, SPEC_AXES, STYLE_PRESETS, StylePreset } from '@vectoriox/iox-ui/design-core';
+
+import { BUSINESS_TYPES, BusinessType } from './business-types';
+import { READ_ANIMATE, StyleRead } from './rank';
+
+/**
+ * Where Design ▸ Motion starts (AI plan rev 3.1 §3p, MO-D3) — and what "Build with these" takes. Pure.
+ * Scrolling and Between pages are the BUSINESS's (a spa scrolls softly whatever its look); How animated is the
+ * CALMER of the business's (or what the references show) and the style's — so a quiet serif look never gets
+ * bouncing cards. The owner's "little movement" caps all three. No matching type → the style's own.
+ */
+
+export interface MotionInput {
+    businessType?: string | null;
+    avoid?: ReadonlyArray<string>;
+}
+
+export interface MotionStart extends DesignMotion {
+    /** Why, in English — one line per step the start took. */
+    why: string[];
+}
+
+/** The owner asked for little movement (`USER_AVOID_IDS`). */
+export const LITTLE_MOVEMENT_AVOID = 'lots-of-motion';
+/** What "little movement" caps each choice at. */
+export const LITTLE_MOVEMENT_CAP: Readonly<DesignMotion> = { scroll: 'smooth', animate: 'subtle', between: 'fade' };
+
+type Axis = keyof DesignMotion;
+const TABLES = { scroll: SPEC_AXES.scrolls, animate: SPEC_AXES.animations, between: SPEC_AXES.betweens } as const;
+const ORDER: Readonly<Record<Axis, ReadonlyArray<string>>> = {
+    scroll: Object.keys(SPEC_AXES.scrolls), animate: Object.keys(SPEC_AXES.animations), between: Object.keys(SPEC_AXES.betweens),
+};
+
+/** The stiller of two choices on one axis (the axes are ordered stillest first). */
+export function calmerChoice<A extends Axis>(axis: A, a: DesignMotion[A], b: DesignMotion[A]): DesignMotion[A] {
+    return ORDER[axis].indexOf(a) <= ORDER[axis].indexOf(b) ? a : b;
+}
+
+const label = (axis: Axis, id: string) => (TABLES[axis] as Readonly<Record<string, { label: string }>>)[id]?.label ?? id;
+const triple = (m: DesignMotion) => `${label('scroll', m.scroll)} · ${label('animate', m.animate)} · ${label('between', m.between)}`;
+
+export function motionFor(
+    input: MotionInput,
+    presetId: string,
+    read: StyleRead | null = null,
+    types: ReadonlyArray<BusinessType> = BUSINESS_TYPES,
+    presets: ReadonlyArray<StylePreset> = STYLE_PRESETS,
+): MotionStart {
+    const type = input.businessType ? types.find(t => t.id === input.businessType) : undefined;
+    const preset = presets.find(p => p.id === presetId) ?? presets[0];
+    const base = type ? type.moves : preset.moves;
+    const ref = read?.motion ? READ_ANIMATE[read.motion] : null;
+    const wanted = ref ?? base.animate;
+    let out: DesignMotion = { scroll: base.scroll, animate: calmerChoice('animate', wanted, preset.moves.animate), between: base.between };
+    const why = [type ? `${type.label}: ${triple(base)}` : `${preset.name}: the style's own`];
+    if (out.animate !== wanted) why.push(`${preset.name} moves less (${label('animate', preset.moves.animate)})`);
+    if (ref && type) why.push(`your references: ${label('animate', ref)}`);
+    if ((input.avoid ?? []).includes(LITTLE_MOVEMENT_AVOID)) {
+        out = {
+            scroll: calmerChoice('scroll', out.scroll, LITTLE_MOVEMENT_CAP.scroll),
+            animate: calmerChoice('animate', out.animate, LITTLE_MOVEMENT_CAP.animate),
+            between: calmerChoice('between', out.between, LITTLE_MOVEMENT_CAP.between),
+        };
+        why.push('you asked for little movement');
+    }
+    return { ...out, why };
+}

package/src/harness-core/needs.ts

@@ -0,0 +1,42 @@
+import { BookingNeed, BUSINESS_TYPES, BusinessType, NeedId } from './business-types';
+
+/** Who asked for a need: the owner named it, or the kind of business needs it ("we added"). */
+export enum NeedSource {
+    You = 'you',
+    Type = 'type',
+}
+
+export interface SiteNeed {
+    id: NeedId;
+    from: `${NeedSource}`;
+    /** The owner's own word for it ("Friday workshops"). */
+    name?: string;
+}
+
+/** The needs that already let a visitor ask for a slot. */
+const BOOKING_NEEDS: ReadonlyArray<NeedId> = ['booking-request', 'sign-up-form'];
+const BOOKING_REQUEST: NeedId = 'booking-request';
+
+/**
+ * What the site needs (AI plan rev 3 §3d, H3): what the owner named, then what this kind of business needs and
+ * they did not name — its page set, in order, and a booking request for a business that must take bookings —
+ * each marked `from: 'type'` (the Analysis step's "we added"). Pure; an unknown type adds nothing.
+ */
+export function inferNeeds(
+    typeId: string | null | undefined,
+    said: ReadonlyArray<Omit<SiteNeed, 'from'>> = [],
+    types: ReadonlyArray<BusinessType> = BUSINESS_TYPES,
+): SiteNeed[] {
+    const type = typeId ? types.find(t => t.id === typeId) : undefined;
+    const out: SiteNeed[] = said.map(n => ({ ...n, from: NeedSource.You }));
+    const have = new Set<NeedId>(said.map(n => n.id));
+    for (const id of type?.needs ?? []) {
+        if (have.has(id)) continue;
+        have.add(id);
+        out.push({ id, from: NeedSource.Type });
+    }
+    if (type?.booking === BookingNeed.Must && !BOOKING_NEEDS.some(id => have.has(id))) {
+        out.push({ id: BOOKING_REQUEST, from: NeedSource.Type });
+    }
+    return out;
+}

package/src/harness-core/prompt-context.ts

@@ -0,0 +1,91 @@
+import { DesignChoices, presetChoices } from '@vectoriox/iox-ui/design-core';
+import { FactKey, patternById, SITE_FACT_LABELS, SPEC_SITE_LIBRARY } from '@vectoriox/iox-ui/generation-core';
+
+import { BusinessType, businessTypeById, isLookRule } from './business-types';
+import { SiteNeed } from './needs';
+import { SiteAnalysis } from './site-analysis';
+
+/**
+ * What the PLAN prompt is given (AI plan rev 3 §3f "Retrieval, not the whole knowledge base"): the one matched
+ * business rule, the analysis the owner corrected, the style they picked, and the sections that rule's home
+ * uses — never the 30 rules or the 24 presets. Design ▸ Look and the prompt read the same rule. Pure; the M1
+ * caller serialises it.
+ */
+
+export interface PromptSection {
+    id: string;
+    family: string;
+    /** The composed pattern's label; null while the library has not composed it yet (track L). */
+    label: string | null;
+    composed: boolean;
+}
+
+export interface PromptContext {
+    type: {
+        id: string;
+        label: string;
+        tone: string;
+        /** Words the copy must not use — the type's and the owner's. */
+        avoidWords: string[];
+        imagery: string;
+        fonts: string;
+        colourMood: string;
+        structure: BusinessType['structure'];
+        booking: BusinessType['booking'];
+        /** What this kind of site should not look like — the look rules' lines. */
+        lookAdvice: string[];
+    } | null;
+    business: SiteAnalysis['business'];
+    voice: SiteAnalysis['voice'];
+    needs: SiteNeed[];
+    facts: Partial<Record<FactKey, string>>;
+    /** The facts the prompt did not state — placeholders, never invented. */
+    missingFacts: Array<{ key: FactKey; label: string }>;
+    moods: SiteAnalysis['moods'];
+    hero: SiteAnalysis['hero'];
+    locale: SiteAnalysis['locale'];
+    design: DesignChoices | null;
+    sections: PromptSection[];
+}
+
+export interface PromptContextOptions {
+    /** The style the owner picked on Design ▸ Look. */
+    presetId?: string | null;
+    /** …or the exact choices (after Colour / Type / Shape / Motion edits) — wins over `presetId`. */
+    design?: DesignChoices | null;
+}
+
+const FAMILY_OF: ReadonlyMap<string, string> = new Map(SPEC_SITE_LIBRARY.map(e => [e.id, e.family]));
+
+export function analysisPromptContext(analysis: SiteAnalysis, opts: PromptContextOptions = {}): PromptContext {
+    const type = businessTypeById(analysis.businessType);
+    const facts: Partial<Record<FactKey, string>> = {};
+    for (const [key, read] of Object.entries(analysis.facts) as Array<[FactKey, { value: string }]>) facts[key] = read.value;
+    return {
+        type: type ? {
+            id: type.id,
+            label: type.label,
+            tone: type.tone,
+            avoidWords: [...new Set([...type.words, ...analysis.voice.avoidWords])],
+            imagery: type.imagery,
+            fonts: type.fonts,
+            colourMood: type.colour.mood,
+            structure: type.structure,
+            booking: type.booking,
+            lookAdvice: type.avoid.filter(isLookRule).map(r => r.say),
+        } : null,
+        business: analysis.business,
+        voice: analysis.voice,
+        needs: analysis.needs,
+        facts,
+        missingFacts: analysis.missingFacts.map(key => ({ key, label: SITE_FACT_LABELS[key] })),
+        moods: analysis.moods,
+        hero: analysis.hero,
+        locale: analysis.locale,
+        design: opts.design ?? (opts.presetId ? presetChoices(opts.presetId) : null),
+        sections: (type?.home ?? []).map(id => {
+            const pattern = patternById(id);
+            return { id, family: pattern?.family ?? FAMILY_OF.get(id) ?? id.split('.')[0], label: pattern?.label ?? null, composed: !!pattern };
+        }),
+    };
+}

package/src/harness-core/public-api.ts

@@ -0,0 +1,18 @@
+/**
+ * @vectoriox/iox-ui/harness-core — the design HARNESS (AI plan rev 3 §3f, decision N18), FRAMEWORK-FREE: the 30
+ * kinds of business and their rules (generated 1:1 from iox-ai-guidance `flavor-spec.v1.json` `harness`), the
+ * `SiteAnalysis` gate, what a site needs, the style ranking (+ references), where Motion starts, the design
+ * lint and what the plan prompt is given. Pure: no transport, no clock, no randomness. Consumed by iox-cms (the
+ * AI pipeline), the wizard and the boards. Depends on design-core and generation-core; neither depends on it.
+ * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths — or
+ * `nest start` dies with ERR_REQUIRE_ESM while jest and build both pass.
+ */
+export * from './harness-spec.generated';
+export * from './business-types';
+export * from './look';
+export * from './rank';
+export * from './motion';
+export * from './needs';
+export * from './lint';
+export * from './site-analysis';
+export * from './prompt-context';

package/src/harness-core/rank.ts

@@ -0,0 +1,226 @@
+import {
+    DensityId, flavorPackById, MOOD_LABELS, MoodId, parseFontFamilies, ShapeId, STYLE_PRESETS, StylePreset, TintId,
+} from '@vectoriox/iox-ui/design-core';
+import type { AnimateId } from '@vectoriox/iox-ui/design-core';
+
+import { AvoidRule, BUSINESS_TYPES, BusinessType, isLookRule, LookRule, userAvoidRule } from './business-types';
+import { lookMatches, presetLook } from './look';
+
+/**
+ * Which styles suit a business, best first (AI plan rev 3 §3f, H3) — Design ▸ Look's order. Pure and
+ * deterministic: the browser and the server give the same order, and the eval asserts it.
+ */
+
+/** What the ranker reads of an analysis. */
+export interface RankInput {
+    businessType?: string | null;
+    moods?: ReadonlyArray<string>;
+    /** What the owner asked to avoid (`USER_AVOID_IDS`). */
+    avoid?: ReadonlyArray<string>;
+}
+
+export enum PresetFit {
+    Good = 'good',
+    Ok = 'ok',
+    Poor = 'poor',
+}
+
+/** Why a style sits where it does — the line Design ▸ Look shows. */
+export enum RankReason {
+    /** The business type names it as a good fit (`reason` = the type's line). */
+    GoodFit = 'good-fit',
+    /** A type rule advises against its look (`reason` = the rule's line). */
+    TypeAvoid = 'type-avoid',
+    /** The owner asked to avoid its look (`reason` = the rule's line). */
+    UserAvoid = 'user-avoid',
+    /** It shares the analysis's moods (`sharedMoods`). */
+    SharedMoods = 'shared-moods',
+    None = 'none',
+}
+
+export interface RankedPreset {
+    id: string;
+    fit: PresetFit;
+    score: number;
+    reasonKind: RankReason;
+    /** In English, from the contract (the UI may localise `reasonKind` + `sharedMoods` instead). */
+    reason: string;
+    sharedMoods: MoodId[];
+    /** Catalogue position — ties keep it. */
+    order: number;
+    /** With references (`rankWithReferences`): the boost the reading gave it, and whether it is the nearest. */
+    refBoost?: number;
+    nearest?: boolean;
+}
+
+/** The ranking's weights: the type's own order, then moods, then motion character, minus what is advised against. */
+export const RANK_WEIGHTS = {
+    firstGoodFit: 100,
+    goodFitStep: 10,
+    sharedMood: 6,
+    sharedMove: 2,
+    typeAvoid: 60,
+    userAvoid: 80,
+} as const;
+
+const MOVE_KEYS = ['scroll', 'animate', 'between'] as const;
+
+/**
+ * The rule among `rules` that `preset`'s look matches — in EVERY mode it offers (a preset that can switch to a
+ * mode escaping a mode-only rule is judged in that mode: Night gallery offers light). The rule reported is the
+ * one its default mode matches.
+ */
+function ruleHit(preset: StylePreset, rules: ReadonlyArray<LookRule>): LookRule | null {
+    for (const mode of preset.modes) {
+        if (!rules.some(r => lookMatches(r.when, presetLook(preset, mode), preset.moods))) return null;
+    }
+    return rules.find(r => lookMatches(r.when, presetLook(preset), preset.moods)) ?? null;
+}
+
+const lookRules = (rules: ReadonlyArray<AvoidRule>): LookRule[] => rules.filter(isLookRule);
+
+function moodsLine(moods: ReadonlyArray<MoodId>): string {
+    return `${moods.map(m => MOOD_LABELS[m]).join(' and ')}, like your description.`;
+}
+
+/**
+ * Every preset, best first: score = the type's own order (a good fit 100, 90, 80…) + 6 per mood shared with
+ * the analysis + 2 per motion choice shared with the type, − 60 for a look the type advises against, − 80 for
+ * one the owner said to avoid. Ties keep catalogue order. With no matching type, moods alone order them.
+ */
+export function rankStylePresets(
+    input: RankInput,
+    presets: ReadonlyArray<StylePreset> = STYLE_PRESETS,
+    types: ReadonlyArray<BusinessType> = BUSINESS_TYPES,
+): RankedPreset[] {
+    const type = input.businessType ? types.find(t => t.id === input.businessType) : undefined;
+    const typeRules = type ? lookRules(type.avoid) : [];
+    const userRules = (input.avoid ?? []).map(userAvoidRule).filter((r): r is LookRule => !!r);
+    const moods = input.moods ?? [];
+    return presets.map((preset, order) => {
+        const goodAt = type ? type.good.findIndex(g => g.preset === preset.id) : -1;
+        const sharedMoods = preset.moods.filter(m => moods.includes(m));
+        let score = goodAt >= 0 ? RANK_WEIGHTS.firstGoodFit - RANK_WEIGHTS.goodFitStep * goodAt : 0;
+        score += RANK_WEIGHTS.sharedMood * sharedMoods.length;
+        if (type) score += RANK_WEIGHTS.sharedMove * MOVE_KEYS.filter(k => preset.moves[k] === type.moves[k]).length;
+        const typeHit = ruleHit(preset, typeRules);
+        const userHit = ruleHit(preset, userRules);
+        if (typeHit) score -= RANK_WEIGHTS.typeAvoid;
+        if (userHit) score -= RANK_WEIGHTS.userAvoid;
+        const fit = typeHit || userHit ? PresetFit.Poor : goodAt >= 0 ? PresetFit.Good : PresetFit.Ok;
+        const [reasonKind, reason] = userHit ? [RankReason.UserAvoid, userHit.say]
+            : typeHit ? [RankReason.TypeAvoid, typeHit.say]
+            : goodAt >= 0 && type ? [RankReason.GoodFit, type.good[goodAt].reason]
+            : sharedMoods.length ? [RankReason.SharedMoods, moodsLine(sharedMoods)]
+            : [RankReason.None, ''];
+        return { id: preset.id, fit, score, reasonKind, reason, sharedMoods, order };
+    }).sort((a, b) => b.score - a.score || a.order - b.order);
+}
+
+// ── References: a reading of pictures or a site, as style (plan §3k, R4) ─────────────────────────────────
+export enum StyleReadSourceKind {
+    Image = 'image',
+    Site = 'site',
+}
+export enum StyleReadGround {
+    Light = 'light',
+    Dark = 'dark',
+    Mixed = 'mixed',
+}
+export enum StyleReadMotion {
+    None = 'none',
+    Some = 'some',
+    Lots = 'lots',
+}
+export enum StyleReadHeadings {
+    Serif = 'serif',
+    Sans = 'sans',
+    Display = 'display',
+    Mono = 'mono',
+}
+
+/** What a reader measured (palette) and saw (moods, shape…) — never their CSS, text or pictures. */
+export interface StyleRead {
+    sources: ReadonlyArray<{ kind: `${StyleReadSourceKind}`; ref: string }>;
+    /** ≤ 6, MEASURED, never asked of a model. */
+    palette: ReadonlyArray<{ hex: string; share: number }>;
+    /** The most frequent saturated colour — a CANDIDATE seed: the AA audit decides. */
+    brand?: string;
+    ground: `${StyleReadGround}`;
+    shape?: ShapeId;
+    density?: DensityId;
+    motion?: `${StyleReadMotion}`;
+    headings?: `${StyleReadHeadings}`;
+    moods: ReadonlyArray<MoodId>;
+}
+
+/** The boosts a reading gives each preset, and the defaults it suggests. */
+export interface StyleHints {
+    boost: Record<string, number>;
+    seed: string | null;
+    tint: TintId;
+    shape?: ShapeId;
+    density?: DensityId;
+    animate: AnimateId | null;
+}
+
+export const READ_WEIGHTS = {
+    sharedMood: 8,
+    ground: 10,
+    shape: 6,
+    density: 4,
+    serifHeadings: 6,
+} as const;
+
+/** How much motion a reading saw → How animated. */
+export const READ_ANIMATE: Readonly<Record<`${StyleReadMotion}`, AnimateId>> = {
+    [StyleReadMotion.None]: 'still',
+    [StyleReadMotion.Some]: 'subtle',
+    [StyleReadMotion.Lots]: 'standard',
+};
+
+const SERIF_GENERIC = 'serif';
+
+/** True when the preset's pairing sets headings in a serif (its display stack ends in the serif generic). */
+export function presetHasSerifHeadings(preset: StylePreset): boolean {
+    const pair = flavorPackById(preset.flavorId)?.pairs.find(p => p.id === preset.pairId);
+    return parseFontFamilies(pair?.tokens['font-display'] ?? '').includes(SERIF_GENERIC);
+}
+
+/** A reading → a score boost per preset and the defaults it suggests (pure, deterministic). */
+export function mapStyleRead(read: StyleRead, presets: ReadonlyArray<StylePreset> = STYLE_PRESETS): StyleHints {
+    const boost: Record<string, number> = {};
+    for (const p of presets) {
+        let b = READ_WEIGHTS.sharedMood * p.moods.filter(m => read.moods.includes(m)).length;
+        if (read.ground !== StyleReadGround.Mixed && p.modes[0] === read.ground) b += READ_WEIGHTS.ground;
+        if (read.shape && p.shape === read.shape) b += READ_WEIGHTS.shape;
+        if (read.density && p.density === read.density) b += READ_WEIGHTS.density;
+        if (read.headings === StyleReadHeadings.Serif && presetHasSerifHeadings(p)) b += READ_WEIGHTS.serifHeadings;
+        boost[p.id] = b;
+    }
+    return {
+        boost,
+        seed: read.brand ?? null,
+        tint: read.palette.length && read.ground === StyleReadGround.Light ? 'subtle' : 'neutral',
+        ...(read.shape ? { shape: read.shape } : {}),
+        ...(read.density ? { density: read.density } : {}),
+        animate: read.motion ? READ_ANIMATE[read.motion] : null,
+    };
+}
+
+/** `rankStylePresets` + the reading's boost; `nearest` = the best-boosted style that is not a poor fit. */
+export function rankWithReferences(
+    input: RankInput,
+    read: StyleRead | null | undefined,
+    presets: ReadonlyArray<StylePreset> = STYLE_PRESETS,
+    types: ReadonlyArray<BusinessType> = BUSINESS_TYPES,
+): RankedPreset[] {
+    const ranked = rankStylePresets(input, presets, types);
+    if (!read) return ranked;
+    const { boost } = mapStyleRead(read, presets);
+    const out = ranked.map(x => ({ ...x, score: x.score + (boost[x.id] ?? 0), refBoost: boost[x.id] ?? 0 }))
+        .sort((a, b) => b.score - a.score || a.order - b.order);
+    const nearest = out.filter(x => x.fit !== PresetFit.Poor)
+        .reduce<RankedPreset | null>((a, b) => (!a || (b.refBoost ?? 0) > (a.refBoost ?? 0) ? b : a), null);
+    return out.map(x => ({ ...x, nearest: !!nearest && x.id === nearest.id }));
+}