@vectoriox/iox-ui 5.54.0 → 5.56.0

package/src/harness-core/palette.ts

@@ -0,0 +1,198 @@
+import { parseHexColor, rgbToOklab, toHexColor } from '@vectoriox/iox-ui/design-core';
+
+import { StyleReadGround } from './rank';
+
+/**
+ * The palette MEASURE (AI plan §3k, R-D2: a colour is measured, never asked of a model) — ONE function for every
+ * reader: the browser measures a picture at upload (canvas pixels → `pixelSamples`), the server measures a picture it
+ * reads and a website's CSS (declared colours, weighted by where they paint). Weighted samples in, ≤ 6 colours out,
+ * by a deterministic median cut: the same input gives the same hexes on every run, in every runtime. Pure.
+ */
+
+/** One colour seen, and how much of the reference it covers (pixels, or a CSS colour's weight). */
+export interface ColourSample {
+    /** 0–255 each. */
+    r: number;
+    g: number;
+    b: number;
+    weight: number;
+}
+
+export interface PaletteColour {
+    hex: string;
+    /** Its part of the whole, 0–1; the palette's shares add up to 1. */
+    share: number;
+}
+
+export interface PaletteReading {
+    palette: PaletteColour[];
+    ground: `${StyleReadGround}`;
+    /** The most frequent saturated colour — a CANDIDATE seed (the AA audit decides, `referenceSeed`). */
+    brand?: string;
+}
+
+/** At most this many colours (the StyleRead's palette). */
+export const PALETTE_SIZE = 6;
+/** Channels are bucketed to this many bits before the cut, so noise never decides a colour. */
+const BUCKET_BITS = 5;
+const BUCKET_SHIFT = 8 - BUCKET_BITS;
+/** The sampling ceiling for a picture — every n-th pixel, so a 12 MP photo costs what a thumbnail does. */
+export const MAX_PIXEL_SAMPLES = 20_000;
+/** A pixel under this alpha is not part of the picture. */
+const MIN_ALPHA = 128;
+
+/** OKLab lightness / chroma thresholds the reading speaks in. */
+export const PALETTE_THRESHOLDS = {
+    /** Above: a light colour. */
+    light: 0.72,
+    /** Below: a dark colour. */
+    dark: 0.38,
+    /** At least this share of light (or dark) makes the ground light (or dark); otherwise mixed. */
+    groundShare: 0.55,
+    /** A brand candidate is at least this colourful… */
+    brandChroma: 0.08,
+    /** …and neither near-white nor near-black. */
+    brandMinL: 0.25,
+    brandMaxL: 0.92,
+    /** Two palette colours closer than this (OKLab distance) are one colour. */
+    mergeDistance: 0.035,
+} as const;
+
+/** Every n-th opaque pixel of an RGBA buffer (canvas `ImageData.data`, a decoder's pixels), weight 1 each. */
+export function pixelSamples(rgba: ArrayLike<number>, width: number, height: number, max = MAX_PIXEL_SAMPLES): ColourSample[] {
+    const pixels = Math.max(0, Math.floor(width) * Math.floor(height));
+    const step = Math.max(1, Math.ceil(pixels / max));
+    const out: ColourSample[] = [];
+    for (let p = 0; p < pixels; p += step) {
+        const i = p * 4;
+        if (rgba[i + 3] < MIN_ALPHA) continue;
+        out.push({ r: rgba[i], g: rgba[i + 1], b: rgba[i + 2], weight: 1 });
+    }
+    return out;
+}
+
+/** A palette (hex + share) back to samples — what merging two readings measures. */
+export function paletteSamples(palette: ReadonlyArray<PaletteColour>, weight = 1): ColourSample[] {
+    return palette.flatMap(c => {
+        const rgb = parseHexColor(c.hex);
+        return rgb ? [{ r: Math.round(rgb.r * 255), g: Math.round(rgb.g * 255), b: Math.round(rgb.b * 255), weight: c.share * weight }] : [];
+    });
+}
+
+type Channel = 'r' | 'g' | 'b';
+const CHANNELS: ReadonlyArray<Channel> = ['r', 'g', 'b'];
+
+interface Box { colours: ColourSample[]; weight: number; }
+
+const boxOf = (colours: ColourSample[]): Box => ({ colours, weight: colours.reduce((s, c) => s + c.weight, 0) });
+
+function range(box: Box, ch: Channel): number {
+    let lo = 255;
+    let hi = 0;
+    for (const c of box.colours) { lo = Math.min(lo, c[ch]); hi = Math.max(hi, c[ch]); }
+    return hi - lo;
+}
+
+/** The channel a box is widest in (ties: r, then g, then b). */
+function widest(box: Box): { ch: Channel; span: number } {
+    return CHANNELS.reduce<{ ch: Channel; span: number }>((best, ch) => {
+        const span = range(box, ch);
+        return span > best.span ? { ch, span } : best;
+    }, { ch: 'r', span: -1 });
+}
+
+/** Split at the weighted median of its widest channel (a stable sort, so ties never depend on the runtime). */
+function split(box: Box): [Box, Box] | null {
+    const { ch, span } = widest(box);
+    if (span <= 0 || box.colours.length < 2) return null;
+    const sorted = [...box.colours].sort((a, b) => a[ch] - b[ch] || a.r - b.r || a.g - b.g || a.b - b.b);
+    let acc = 0;
+    let cut = 1;
+    for (let i = 0; i < sorted.length - 1; i++) {
+        acc += sorted[i].weight;
+        cut = i + 1;
+        if (acc >= box.weight / 2) break;
+    }
+    return [boxOf(sorted.slice(0, cut)), boxOf(sorted.slice(cut))];
+}
+
+/** Samples bucketed (BUCKET_BITS per channel), each bucket's weighted mean colour kept. */
+function bucket(samples: ReadonlyArray<ColourSample>): ColourSample[] {
+    const buckets = new Map<number, { r: number; g: number; b: number; weight: number }>();
+    for (const s of samples) {
+        if (!(s.weight > 0)) continue;
+        const key = ((s.r >> BUCKET_SHIFT) << (2 * BUCKET_BITS)) | ((s.g >> BUCKET_SHIFT) << BUCKET_BITS) | (s.b >> BUCKET_SHIFT);
+        const b = buckets.get(key) ?? { r: 0, g: 0, b: 0, weight: 0 };
+        b.r += s.r * s.weight; b.g += s.g * s.weight; b.b += s.b * s.weight; b.weight += s.weight;
+        buckets.set(key, b);
+    }
+    return [...buckets.entries()].sort(([a], [b]) => a - b).map(([, b]) => ({ r: b.r / b.weight, g: b.g / b.weight, b: b.b / b.weight, weight: b.weight }));
+}
+
+function meanHex(box: Box): string {
+    const sum = box.colours.reduce((s, c) => ({ r: s.r + c.r * c.weight, g: s.g + c.g * c.weight, b: s.b + c.b * c.weight }), { r: 0, g: 0, b: 0 });
+    return toHexColor({ r: sum.r / box.weight / 255, g: sum.g / box.weight / 255, b: sum.b / box.weight / 255 }).toUpperCase();
+}
+
+const oklabOf = (hex: string) => rgbToOklab(parseHexColor(hex)!);
+const distance = (a: string, b: string) => { const x = oklabOf(a); const y = oklabOf(b); return Math.hypot(x.L - y.L, x.a - y.a, x.b - y.b); };
+const SHARE_PRECISION = 1e4;
+
+/** Weighted samples → ≤ 6 colours, largest share first (ties by hex), shares adding up to 1. */
+export function measurePalette(samples: ReadonlyArray<ColourSample>, size = PALETTE_SIZE): PaletteColour[] {
+    const colours = bucket(samples);
+    if (!colours.length) return [];
+    let boxes: Box[] = [boxOf(colours)];
+    while (boxes.length < size) {
+        // The box to cut: the most weight × span (ties: the earlier box).
+        let best = -1;
+        let bestScore = 0;
+        boxes.forEach((box, i) => {
+            const score = box.weight * widest(box).span;
+            if (score > bestScore) { best = i; bestScore = score; }
+        });
+        const halves = best >= 0 ? split(boxes[best]) : null;
+        if (!halves) break;
+        boxes = [...boxes.slice(0, best), ...halves, ...boxes.slice(best + 1)];
+    }
+    const total = boxes.reduce((s, b) => s + b.weight, 0);
+    const merged: Array<{ hex: string; weight: number }> = [];
+    for (const box of [...boxes].sort((a, b) => b.weight - a.weight)) {
+        const hex = meanHex(box);
+        const near = merged.find(m => distance(m.hex, hex) < PALETTE_THRESHOLDS.mergeDistance);
+        if (near) near.weight += box.weight;
+        else merged.push({ hex, weight: box.weight });
+    }
+    return merged
+        .map(m => ({ hex: m.hex, share: Math.round((m.weight / total) * SHARE_PRECISION) / SHARE_PRECISION }))
+        .sort((a, b) => b.share - a.share || a.hex.localeCompare(b.hex));
+}
+
+/** Light, dark or mixed: the share of the palette that is light (or dark). */
+export function paletteGround(palette: ReadonlyArray<PaletteColour>): `${StyleReadGround}` {
+    let light = 0;
+    let dark = 0;
+    for (const c of palette) {
+        const { L } = oklabOf(c.hex);
+        if (L >= PALETTE_THRESHOLDS.light) light += c.share;
+        else if (L <= PALETTE_THRESHOLDS.dark) dark += c.share;
+    }
+    if (light >= PALETTE_THRESHOLDS.groundShare) return StyleReadGround.Light;
+    if (dark >= PALETTE_THRESHOLDS.groundShare) return StyleReadGround.Dark;
+    return StyleReadGround.Mixed;
+}
+
+/** The most frequent saturated colour that is neither near-white nor near-black, or undefined. */
+export function paletteBrand(palette: ReadonlyArray<PaletteColour>): string | undefined {
+    return palette.find(c => {
+        const { L, a, b } = oklabOf(c.hex);
+        return Math.hypot(a, b) >= PALETTE_THRESHOLDS.brandChroma && L >= PALETTE_THRESHOLDS.brandMinL && L <= PALETTE_THRESHOLDS.brandMaxL;
+    })?.hex;
+}
+
+/** The whole reading of a set of samples: the palette, its ground, its brand candidate. */
+export function readPalette(samples: ReadonlyArray<ColourSample>): PaletteReading {
+    const palette = measurePalette(samples);
+    const brand = paletteBrand(palette);
+    return { palette, ground: paletteGround(palette), ...(brand ? { brand } : {}) };
+}

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

@@ -18,3 +18,8 @@ export * from './site-analysis';
 export * from './prompt-context';
 export * from './intake';
 export * from './structure';
+export * from './palette';
+export * from './reference-colour';
+export * from './site-reading';
+export * from './generation-view';
+export * from './starting-design';

package/src/harness-core/reference-colour.ts

@@ -0,0 +1,45 @@
+import { auditDesignContrast, designTokenRows, parseHexColor, presetChoices, stylePresetById } from '@vectoriox/iox-ui/design-core';
+import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+
+import { StyleRead } from './rank';
+
+/**
+ * Which brand colour a style starts from when the owner gave references (AI plan §3k, R4 "the AA gate decides the
+ * colour"): the reading's measured `brand` — ONLY when the preset, worn in EVERY mode it offers with that colour as its
+ * seed, passes the same contrast audit the contract gates every preset with (`auditDesignContrast`: every element
+ * style in every section scheme, form parts, focus rings). Otherwise the preset's own seed stays and the reference
+ * colour is a swatch the Colour tab marks "doesn't pass contrast here". The model never sees, picks or changes a hex.
+ * Pure; the wizard (Design ▸ Colour) and the server ("Build with these") ask the same question.
+ */
+
+export interface ReferenceSeed {
+    /** The seed to start from: the reference's when it passed, else the preset's. */
+    seed: string;
+    /** The reference colour measured, or null when there is none (no reading, nothing saturated). */
+    reference: string | null;
+    /** True when `seed` is the reference colour. */
+    used: boolean;
+    /** The modes the reference colour failed in (empty when used, or when there is no reference). */
+    failsIn: Array<'light' | 'dark'>;
+}
+
+/** Every mode `presetId` offers passes the audit with `seed`. */
+export function seedPassesPreset(presetId: string, seed: string): { passes: boolean; failsIn: Array<'light' | 'dark'> } {
+    const preset = stylePresetById(presetId);
+    if (!preset || !parseHexColor(seed)) return { passes: false, failsIn: [] };
+    const failsIn = preset.modes.filter(mode => {
+        const choices = presetChoices(preset.id, mode) as DesignChoices;
+        return auditDesignContrast(designTokenRows({ ...choices, seed }), mode).some(f => !f.pass);
+    });
+    return { passes: failsIn.length === 0, failsIn: [...failsIn] };
+}
+
+/** The seed a preset starts from, given a reading (or none). Unknown preset → null. */
+export function referenceSeed(read: Pick<StyleRead, 'brand'> | null | undefined, presetId: string): ReferenceSeed | null {
+    const preset = stylePresetById(presetId);
+    if (!preset) return null;
+    const reference = read?.brand && parseHexColor(read.brand) ? read.brand : null;
+    if (!reference) return { seed: preset.seed, reference: null, used: false, failsIn: [] };
+    const { passes, failsIn } = seedPassesPreset(preset.id, reference);
+    return passes ? { seed: reference, reference, used: true, failsIn: [] } : { seed: preset.seed, reference, used: false, failsIn };
+}

package/src/harness-core/site-analysis.ts

@@ -1,7 +1,7 @@
 import { MOOD_IDS, MoodId } from '@vectoriox/iox-ui/design-core';
 import {
-    FACT_KEYS, FactKey, isPlainObject, PathIssue, PathIssueCollector, pathAt, PlainObject, requiredShapeKeys, ShapeEntry,
-    shapeKeys,
+    describeShapeKey, FACT_KEYS, FactKey, isPlainObject, jsonClosedObject, jsonListOf, jsonOneOf, JsonSchema, jsonShapedObject, jsonText,
+    PathIssue, PathIssueCollector, pathAt, PlainObject, requiredShapeKeys, ShapeEntry, shapeKeys,
 } from '@vectoriox/iox-ui/generation-core';
 
 import { BUSINESS_TYPE_IDS, NEED_IDS, USER_AVOID_IDS, UserAvoidId } from './business-types';
@@ -189,42 +189,21 @@ export function validateSiteAnalysis(value: unknown, ctx: AnalysisContext): Anal
  * schema is a hint the provider enforces; `validateSiteAnalysis` stays the gate.
  */
 
-export type JsonSchema = { [key: string]: unknown };
+export type { JsonSchema } from '@vectoriox/iox-ui/generation-core';
 
 /** The name a provider shows the format under (`json_schema.name`). */
 export const SITE_ANALYSIS_SCHEMA_NAME = 'site_analysis';
 
-const OPTIONAL_MARK = '?';
-
-const text = (): JsonSchema => ({ type: 'string' });
-const oneOf = (values: ReadonlyArray<string>): JsonSchema => ({ type: 'string', enum: [...values] });
-const listOf = (items: JsonSchema): JsonSchema => ({ type: 'array', items });
-
-/** The shape table's own words for a key — the description the model reads. */
-function describe(shape: string, key: string): string {
-    const entry = SHAPE[shape];
-    return String(entry[key] ?? entry[`${key}${OPTIONAL_MARK}`] ?? '');
-}
+const text = jsonText;
+const oneOf = jsonOneOf;
+const listOf = jsonListOf;
 
 /** An object of `shape`: exactly its keys, its required ones required, each described by the table. */
-function shaped(shape: string, properties: Record<string, JsonSchema>): JsonSchema {
-    return {
-        type: 'object',
-        properties: Object.fromEntries(Object.entries(properties).map(([key, schema]) => [key, { ...schema, description: describe(shape, key) }])),
-        required: requiredShapeKeys(SHAPE[shape]),
-        additionalProperties: false,
-    };
-}
+const shaped = (shape: string, properties: Record<string, JsonSchema>): JsonSchema => jsonShapedObject(SHAPE[shape], properties, shape);
 
 /** `{ [fact]: factRead }`: the closed fact keys, each optional — a fact the prompt does not state is left out. */
 function factsSchema(factRead: JsonSchema): JsonSchema {
-    return {
-        type: 'object',
-        properties: Object.fromEntries(FACT_KEYS.map(key => [key, factRead])),
-        required: [],
-        additionalProperties: false,
-        description: describe('analysis', 'facts'),
-    };
+    return jsonClosedObject(Object.fromEntries(FACT_KEYS.map(key => [key, factRead])), [], describeShapeKey(SHAPE['analysis'], 'facts'));
 }
 
 export function siteAnalysisJsonSchema(): JsonSchema {

package/src/harness-core/site-reading.ts

@@ -0,0 +1,214 @@
+import { DensityId, MOOD_IDS, MoodId, ShapeId, SPEC_AXES } from '@vectoriox/iox-ui/design-core';
+import {
+    isPlainObject, jsonListOf, jsonOneOf, JsonSchema, jsonShapedObject, jsonInteger, PathIssue, PathIssueCollector, pathAt, PlainObject, ShapeEntry,
+    shapeKeys, requiredShapeKeys,
+} from '@vectoriox/iox-ui/generation-core';
+
+import { paletteSamples, readPalette } from './palette';
+import { StyleRead, StyleReadGround, StyleReadHeadings, StyleReadSourceKind } from './rank';
+import { AnalysisIssue, MAX_ANALYSIS_MOODS, SiteAnalysis, siteAnalysisJsonSchema, validateSiteAnalysis } from './site-analysis';
+
+/**
+ * The READING call (AI plan §3d step 1, §3k R2, M1-1): ONE `text.fast` call reads the owner's words AND the pictures
+ * they attached (image input) and answers with the SiteAnalysis and — when there are pictures — which ones are the
+ * owner's own (Your photos) and which are pictures they like (references, style only), plus what the liked pictures
+ * FEEL like: moods, the lettering, corners, spacing. Never a colour: the palette is MEASURED (`palette.ts`, R-D2).
+ * The format is built from `READING_SHAPE` (keys + their explanations), the gate reads the same table. Pure.
+ */
+
+/** Which group a picture belongs to (R-D3: from the words; own when the words don't say). */
+export enum PictureRole {
+    Own = 'own',
+    Reference = 'reference',
+}
+
+/** At most this many pictures go to the reading call as image input (§3d: "up to 6 pictures"). */
+export const MAX_READ_PICTURES = 6;
+
+export const READING_SHAPE: Readonly<Record<string, ShapeEntry>> = {
+    reading: {
+        analysis: 'analysis — the reading of the words',
+        pictures: 'pictures — the pictures attached, in order',
+    },
+    pictures: {
+        files: 'fileRole[] — one per attached picture, in the order given',
+        style: 'pictureStyle — what the pictures the owner LIKES (role reference) feel like; empty moods when there are none',
+    },
+    fileRole: {
+        index: 'integer — the picture, 0-based, in the order given',
+        role: "'own' | 'reference' — own: the owner's work, place, products or people, for the site; reference: a picture they like, for style only (\"a site like these\"); own when the words don't say",
+    },
+    pictureStyle: {
+        moods: 'string[] — ≤ 3 moods the liked pictures feel like',
+        'headings?': "'serif' | 'sans' | 'display' | 'mono' — the lettering they show, when they show some",
+        'shape?': 'string — design axes.shapes: their corners',
+        'density?': 'string — design axes.densities: how much room things have',
+    },
+};
+
+export interface PictureStyle {
+    moods: MoodId[];
+    headings?: `${StyleReadHeadings}`;
+    shape?: ShapeId;
+    density?: DensityId;
+}
+
+export interface SiteReading {
+    analysis: SiteAnalysis;
+    /** Present when pictures were attached. */
+    pictures?: { files: Array<{ index: number; role: `${PictureRole}` }>; style: PictureStyle };
+}
+
+export const SITE_READING_SCHEMA_NAME = 'site_reading';
+
+/** The reading's format: the analysis alone when no picture was attached, else the analysis + the pictures. */
+export function siteReadingJsonSchema(pictureCount: number): JsonSchema {
+    if (pictureCount <= 0) return siteAnalysisJsonSchema();
+    const fileRole = jsonShapedObject(READING_SHAPE['fileRole'], { index: jsonInteger(), role: jsonOneOf(Object.values(PictureRole)) }, 'fileRole');
+    const style = jsonShapedObject(READING_SHAPE['pictureStyle'], {
+        moods: jsonListOf(jsonOneOf(MOOD_IDS)),
+        headings: jsonOneOf(Object.values(StyleReadHeadings)),
+        shape: jsonOneOf(Object.keys(SPEC_AXES.shapes)),
+        density: jsonOneOf(Object.keys(SPEC_AXES.densities)),
+    }, 'pictureStyle');
+    const pictures = jsonShapedObject(READING_SHAPE['pictures'], { files: jsonListOf(fileRole), style }, 'pictures');
+    return jsonShapedObject(READING_SHAPE['reading'], { analysis: siteAnalysisJsonSchema(), pictures }, 'reading');
+}
+
+export enum ReadingIssueCode {
+    Shape = 'shape',
+    UnknownKey = 'unknown-key',
+    Duplicate = 'duplicate',
+    InvalidValue = 'invalid-value',
+    /** A picture named twice, or one left out. */
+    Pictures = 'pictures',
+}
+
+export type ReadingIssue = PathIssue<ReadingIssueCode> | AnalysisIssue;
+
+class Collector extends PathIssueCollector<ReadingIssueCode> {
+    constructor() {
+        super('reading', { shape: ReadingIssueCode.Shape, unknownKey: ReadingIssueCode.UnknownKey, duplicate: ReadingIssueCode.Duplicate });
+    }
+    object(value: unknown, shape: string, path: string): PlainObject | null {
+        if (!isPlainObject(value)) { this.add(ReadingIssueCode.Shape, path, 'must be an object'); return null; }
+        this.keys(value, shapeKeys(READING_SHAPE[shape]), path);
+        for (const key of requiredShapeKeys(READING_SHAPE[shape])) if (value[key] === undefined) this.add(ReadingIssueCode.Shape, pathAt(path, key), 'is required');
+        return value;
+    }
+    oneOf(obj: PlainObject, key: string, allowed: ReadonlyArray<string>, path: string): void {
+        const v = obj[key];
+        if (v !== undefined && (typeof v !== 'string' || !allowed.includes(v))) this.add(ReadingIssueCode.InvalidValue, pathAt(path, key), `must be one of ${allowed.join(', ')}`);
+    }
+}
+
+/** The pictures' part: every picture named once, a role each, moods from the closed list. */
+function validatePictures(c: Collector, raw: unknown, count: number): void {
+    const pictures = c.object(raw, 'pictures', 'pictures');
+    if (!pictures) return;
+    const files = c.array(pictures, 'files', 'pictures');
+    const seen = new Set<number>();
+    files.forEach((f, i) => {
+        const path = `pictures.files[${i}]`;
+        const file = c.object(f, 'fileRole', path);
+        if (!file) return;
+        c.oneOf(file, 'role', Object.values(PictureRole), path);
+        const index = file['index'];
+        if (!Number.isInteger(index) || (index as number) < 0 || (index as number) >= count) c.add(ReadingIssueCode.Pictures, `${path}.index`, `must be a picture 0–${count - 1}`);
+        else if (seen.has(index as number)) c.add(ReadingIssueCode.Pictures, `${path}.index`, `picture ${index} is named twice`);
+        else seen.add(index as number);
+    });
+    if (Array.isArray(pictures['files']) && seen.size !== count) c.add(ReadingIssueCode.Pictures, 'pictures.files', `name each of the ${count} pictures once`);
+    const style = c.object(pictures['style'], 'pictureStyle', 'pictures.style');
+    if (!style) return;
+    const moods = c.array(style, 'moods', 'pictures.style');
+    if (moods.length > MAX_ANALYSIS_MOODS) c.add(ReadingIssueCode.InvalidValue, 'pictures.style.moods', `at most ${MAX_ANALYSIS_MOODS}`);
+    moods.forEach((m, i) => { if (!(MOOD_IDS as ReadonlyArray<unknown>).includes(m)) c.add(ReadingIssueCode.InvalidValue, `pictures.style.moods[${i}]`, `"${String(m)}" is not a mood`); });
+    c.oneOf(style, 'headings', Object.values(StyleReadHeadings), 'pictures.style');
+    c.oneOf(style, 'shape', Object.keys(SPEC_AXES.shapes), 'pictures.style');
+    c.oneOf(style, 'density', Object.keys(SPEC_AXES.densities), 'pictures.style');
+}
+
+/** The reading's gate: the analysis by `validateSiteAnalysis` (paths under `analysis.` when pictures came too), the pictures by `READING_SHAPE`. */
+export function validateSiteReading(value: unknown, ctx: { prompt: string; pictureCount: number }): { valid: boolean; issues: ReadingIssue[] } {
+    if (ctx.pictureCount <= 0) return validateSiteAnalysis(value, { prompt: ctx.prompt });
+    const c = new Collector();
+    const reading = c.object(value, 'reading', '');
+    if (!reading) return { valid: false, issues: c.issues };
+    const analysis = validateSiteAnalysis(reading['analysis'], { prompt: ctx.prompt });
+    const issues: ReadingIssue[] = analysis.issues.map(i => ({ ...i, path: pathAt('analysis', i.path) }));
+    validatePictures(c, reading['pictures'], ctx.pictureCount);
+    issues.push(...c.issues);
+    return { valid: issues.length === 0, issues };
+}
+
+/** A valid reading's answer → `SiteReading` (the analysis alone answers `{ analysis }`). */
+export function decodeSiteReading(value: unknown, pictureCount: number): SiteReading {
+    if (pictureCount <= 0) return { analysis: value as SiteAnalysis };
+    return value as SiteReading;
+}
+
+// ── Readings → ONE StyleRead ───────────────────────────────────────────────────────────────────────────
+
+/** A reference picture as the server read it: its measured palette (and where it is). */
+export interface MeasuredPicture {
+    ref: string;
+    palette: StyleRead['palette'];
+}
+
+/** The liked pictures as a StyleRead: their palettes measured together, what the model saw of them. */
+export function pictureStyleRead(pictures: ReadonlyArray<MeasuredPicture>, style: PictureStyle | null | undefined): StyleRead | null {
+    if (!pictures.length) return null;
+    const reading = readPalette(pictures.flatMap(p => paletteSamples(p.palette)));
+    return {
+        sources: pictures.map(p => ({ kind: StyleReadSourceKind.Image, ref: p.ref })),
+        palette: reading.palette,
+        ...(reading.brand ? { brand: reading.brand } : {}),
+        ground: reading.ground,
+        moods: [...(style?.moods ?? [])].slice(0, MAX_ANALYSIS_MOODS),
+        ...(style?.headings ? { headings: style.headings } : {}),
+        ...(style?.shape ? { shape: style.shape } : {}),
+        ...(style?.density ? { density: style.density } : {}),
+    };
+}
+
+/** The most frequent defined value (ties: the first reading's). */
+function mostCommon<T>(values: ReadonlyArray<T | undefined>): T | undefined {
+    const counts = new Map<T, number>();
+    for (const v of values) if (v !== undefined) counts.set(v, (counts.get(v) ?? 0) + 1);
+    let best: T | undefined;
+    let n = 0;
+    for (const [v, k] of counts) if (k > n) { best = v; n = k; }
+    return best;
+}
+
+/**
+ * Every reading of one generation (the pictures', each site's) → ONE StyleRead: palettes measured together (each
+ * reading weighs the same), the ground re-read from that palette, moods by how often they were seen (≤ 3), the rest the
+ * most common answer. Null when nothing was read.
+ */
+export function mergeStyleReads(reads: ReadonlyArray<StyleRead | null | undefined>): StyleRead | null {
+    const all = reads.filter((r): r is StyleRead => !!r);
+    if (!all.length) return null;
+    if (all.length === 1) return all[0];
+    const reading = readPalette(all.flatMap(r => paletteSamples(r.palette)));
+    const moodCount = new Map<MoodId, number>();
+    all.forEach(r => r.moods.forEach(m => moodCount.set(m, (moodCount.get(m) ?? 0) + 1)));
+    const moods = [...moodCount.entries()].sort((a, b) => b[1] - a[1]).map(([m]) => m).slice(0, MAX_ANALYSIS_MOODS);
+    const pick = <K extends keyof StyleRead>(key: K) => mostCommon(all.map(r => r[key]));
+    const headings = pick('headings');
+    const shape = pick('shape');
+    const density = pick('density');
+    const motion = pick('motion');
+    return {
+        sources: all.flatMap(r => r.sources),
+        palette: reading.palette,
+        ...(reading.brand ? { brand: reading.brand } : {}),
+        ground: reading.palette.length ? reading.ground : StyleReadGround.Mixed,
+        moods,
+        ...(headings ? { headings } : {}),
+        ...(shape ? { shape } : {}),
+        ...(density ? { density } : {}),
+        ...(motion ? { motion } : {}),
+    } as StyleRead;
+}

package/src/harness-core/starting-design.ts

@@ -0,0 +1,44 @@
+import { DesignChoices, presetChoices } from '@vectoriox/iox-ui/design-core';
+
+import { motionFor, MotionInput } from './motion';
+import { RankInput, rankWithReferences, StyleRead } from './rank';
+import { referenceSeed } from './reference-colour';
+
+/**
+ * The look a business STARTS from (AI plan §3d "Build with these", §3o, MO-D3) — ONE rule for the wizard's Design step
+ * (a Look pick) and the server's "Build with these": the preset at its defaults, Scrolling · How animated · Between
+ * pages started from the kind of business (and the references), the owner's own Motion choices kept, and — given
+ * references — the best-ranked style with the reference colour as its seed when that colour passes AA in every mode
+ * the style offers (`referenceSeed`). Pure.
+ */
+
+/** A preset for this business: its choices, Motion from the business (`motionFor`), what the owner already set kept. */
+export function presetDesign(
+    presetId: string,
+    input: MotionInput | string | null,
+    kept: Partial<Pick<DesignChoices, 'scroll' | 'animate' | 'between' | 'motion'>> = {},
+    read: StyleRead | null = null,
+): DesignChoices | null {
+    const base = presetChoices(presetId);
+    if (!base) return null;
+    const motionInput: MotionInput = typeof input === 'string' || input === null ? { businessType: input } : input;
+    const start = motionFor(motionInput, presetId, read);
+    return { ...base, scroll: start.scroll, animate: start.animate, between: start.between, ...kept };
+}
+
+export interface StartingDesign {
+    presetId: string;
+    design: DesignChoices;
+    /** The reference colour was used as the seed (it passed AA in every mode the style offers). */
+    referenceColour: boolean;
+}
+
+/** The look a business starts from: its best-ranked style (with the references' boost), at its defaults. */
+export function startingDesign(input: (RankInput & MotionInput) | string | null, read: StyleRead | null = null): StartingDesign | null {
+    const rankInput: RankInput & MotionInput = typeof input === 'string' || input === null ? { businessType: input } : input;
+    const top = rankWithReferences(rankInput, read)[0];
+    const design = top ? presetDesign(top.id, rankInput, {}, read) : null;
+    if (!top || !design) return null;
+    const seed = referenceSeed(read, top.id);
+    return seed?.used ? { presetId: top.id, design: { ...design, seed: seed.seed }, referenceColour: true } : { presetId: top.id, design, referenceColour: false };
+}