@vectoriox/iox-ui 5.54.0 → 5.55.0

package/src/generation-core/site-plan-schema.ts

@@ -0,0 +1,239 @@
+import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+
+import {
+    jsonAnyOf, jsonBoolean, jsonClosedObject, jsonInteger, jsonListOf, jsonOneOf, JsonSchema, jsonShapedObject, jsonText,
+} from './json-schema';
+import { patternOptionalParts, patternSlots, patternTakesBinding, PatternGlobalPosition, SITE_PATTERNS, SitePattern } from './patterns';
+import {
+    FACT_KEYS, GlobalSlot, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SitePlan, SitePlanSource, SitePlanSourceKind, SITE_PLAN_VERSION,
+} from './site-plan.model';
+import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
+import { isPlainObject, PlainObject, ShapeEntry } from './shape-check';
+
+/**
+ * The structured-output format a model writes a Site Plan in (AI plan §3d step 4, M1-3) — built from the SAME shape
+ * table `validateSitePlan` reads (`SPEC_SITE_PLAN_SHAPE`) and the SAME pattern library, so the plan a model is told
+ * about is the plan the gate refuses. ONE source: a key the table gains breaks this builder until it is written here.
+ *
+ * Two maps of the shape are written as LISTS on the wire, because no strict mode can say "any key": a section's
+ * `slots` (`[{ slot, text }]`, the slot names closed per pattern) and a seed's field values (`values: [{ field,
+ * value }]`). `sitePlanFromWire` turns them back; nothing else differs. Every section is one `anyOf` branch per
+ * pattern — its id, its declared slots, its optional parts, a binding only when it takes one — and the design, the
+ * source and the version are PINNED to the owner's pick and this run (one-value enums), so the provider cannot let
+ * a model change the look. The gate still checks both (`plan.design` deep-equals the pick).
+ */
+
+export const SITE_PLAN_SCHEMA_NAME = 'site_plan';
+
+/** The wire keys of the two maps written as lists. */
+export enum SitePlanWireKey {
+    SlotName = 'slot',
+    SlotText = 'text',
+    SeedValues = 'values',
+    SeedField = 'field',
+    SeedValue = 'value',
+}
+
+const SHAPE: Readonly<Record<string, ShapeEntry>> = SPEC_SITE_PLAN_SHAPE;
+
+export interface SitePlanSchemaPin {
+    /** The owner's pick, verbatim — every design key becomes a one-value enum. */
+    design: DesignChoices;
+    /** This generation. */
+    source: SitePlanSource;
+}
+
+const one = (value: string): JsonSchema => jsonOneOf([value]);
+const oneBoolean = (value: boolean): JsonSchema => ({ type: 'boolean', enum: [value] });
+
+/** The pick, key by key, as one-value enums; an optional key the pick leaves out may only be left out (or empty). */
+function pinnedDesign(design: DesignChoices): JsonSchema {
+    const entry = SHAPE['design'];
+    const values = design as unknown as Record<string, unknown>;
+    const properties: Record<string, JsonSchema> = {};
+    for (const key of Object.keys(entry).map(k => k.replace(/\?$/, ''))) {
+        const v = values[key];
+        if (typeof v === 'string') properties[key] = one(v);
+        else if (typeof v === 'boolean') properties[key] = oneBoolean(v);
+        else if (isPlainObject(v)) properties[key] = jsonClosedObject(
+            Object.fromEntries(Object.entries(v).map(([role, family]) => [role, one(String(family))])), Object.keys(v));
+        else properties[key] = jsonClosedObject({}, []);
+    }
+    const shaped = jsonShapedObject(entry, properties, 'design');
+    // Everything the pick carries is required: a model may not leave a choice out and let a default stand in.
+    const given = Object.keys(values).filter(k => values[k] !== undefined && k in properties);
+    return { ...shaped, required: [...new Set([...(shaped['required'] as string[]), ...given])] };
+}
+
+function sourceSchema(source: SitePlanSource): JsonSchema {
+    if (source.kind === SitePlanSourceKind.Ai) return jsonShapedObject(SHAPE['sourceAi'], { kind: one(source.kind), runId: one(source.runId) }, 'sourceAi');
+    return jsonShapedObject(SHAPE['sourceTemplate'], {
+        kind: one(source.kind), templateId: one(source.templateId), templateVersion: { type: 'integer', enum: [source.templateVersion] },
+    }, 'sourceTemplate');
+}
+
+function businessSchema(): JsonSchema {
+    const facts = jsonClosedObject(Object.fromEntries(FACT_KEYS.map(key => [key, jsonText()])), []);
+    return jsonShapedObject(SHAPE['business'], { name: jsonText(), tagline: jsonText(), facts }, 'business');
+}
+
+/** A content type's field. */
+export function fieldJsonSchema(): JsonSchema {
+    return jsonShapedObject(SHAPE['field'], { name: jsonText(), type: jsonText(), controller: jsonText(), required: jsonBoolean(), note: jsonText() }, 'field');
+}
+
+/** A content type, its seed's field values as a list (`values: [{ field, value }]`). */
+export function contentTypeJsonSchema(): JsonSchema {
+    const value = jsonAnyOf([jsonText(), jsonListOf(jsonText())]);
+    const values = jsonListOf(jsonClosedObject({ [SitePlanWireKey.SeedField]: jsonText(), [SitePlanWireKey.SeedValue]: value }, [SitePlanWireKey.SeedField, SitePlanWireKey.SeedValue]));
+    const seed = jsonShapedObject(SHAPE['seed'], { count: jsonInteger(), sample: jsonBoolean(), isPublished: jsonBoolean() }, 'seed',
+        { key: SitePlanWireKey.SeedValues, schema: values });
+    return jsonShapedObject(SHAPE['contentType'], {
+        name: jsonText(), label: jsonText(), previewTextField: jsonText(), previewImageField: jsonText(), fields: jsonListOf(fieldJsonSchema()), seed,
+    }, 'contentType');
+}
+
+/** A data source: a cms list / single item, or a relative one. */
+export function dataSourceJsonSchema(): JsonSchema {
+    const byRoute = jsonClosedObject({ field: jsonText(), routeParam: jsonText() }, ['field', 'routeParam']);
+    const cms = jsonShapedObject(SHAPE['cmsDataSource'], {
+        alias: jsonText(), type: one(PlanDataSourceType.Cms), mode: jsonOneOf(Object.values(PlanDataSourceMode)),
+        contentType: jsonText(), limit: jsonInteger(), filterByRouteParam: byRoute,
+    }, 'cmsDataSource');
+    const relative = jsonShapedObject(SHAPE['relativeDataSource'], {
+        alias: jsonText(), type: one(PlanDataSourceType.Relative), of: jsonText(), op: jsonOneOf(Object.values(RelativeOp)), within: jsonText(),
+    }, 'relativeDataSource');
+    return jsonAnyOf([cms, relative]);
+}
+
+/** The patterns a page section may use (every non-global one), in library order. */
+export function sectionPatternIds(): string[] {
+    return Object.entries(SITE_PATTERNS).filter(([, p]) => !p.global).map(([id]) => id);
+}
+
+/** A key a pattern has nothing for: only `{}` (or leaving it out) — the decoder drops it. */
+const NOTHING = (): JsonSchema => jsonClosedObject({}, []);
+
+/** One section branch: this pattern's id, its declared slots (a list), its optional parts, a binding when it takes one. */
+function sectionBranch(id: string, pattern: SitePattern): JsonSchema {
+    const slots = patternSlots(pattern);
+    const parts = patternOptionalParts(pattern);
+    const slotList = slots.length
+        ? jsonListOf(jsonClosedObject({ [SitePlanWireKey.SlotName]: jsonOneOf(slots), [SitePlanWireKey.SlotText]: jsonText() }, [SitePlanWireKey.SlotName, SitePlanWireKey.SlotText]))
+        : NOTHING();
+    const branch = jsonShapedObject(SHAPE['section'], {
+        pattern: one(id),
+        slots: slotList,
+        binding: patternTakesBinding(pattern) ? jsonText() : NOTHING(),
+        without: parts.length ? jsonListOf(jsonOneOf(parts)) : NOTHING(),
+    }, 'section');
+    return { ...branch, description: `${id}: ${pattern.label}` };
+}
+
+/** A page section: one branch per pattern. */
+export function sectionJsonSchema(): JsonSchema {
+    return jsonAnyOf(sectionPatternIds().map(id => sectionBranch(id, SITE_PATTERNS[id])));
+}
+
+/** A page. */
+export function pageJsonSchema(): JsonSchema {
+    return jsonShapedObject(SHAPE['page'], {
+        key: jsonText(), name: jsonText(), route: jsonText(), isHome: jsonBoolean(), required: jsonBoolean(), inNav: jsonBoolean(),
+        template: jsonText(), routeSource: jsonText(), sections: jsonListOf(sectionJsonSchema()),
+    }, 'page');
+}
+
+const globalIds = (position: `${PatternGlobalPosition}`) => Object.entries(SITE_PATTERNS).filter(([, p]) => p.global === position).map(([id]) => id);
+
+/** The Site Plan format, pinned to the owner's pick and this run. */
+export function sitePlanJsonSchema(pin: SitePlanSchemaPin): JsonSchema {
+    const globals = jsonShapedObject(SHAPE['globals'], {
+        [GlobalSlot.Header]: jsonOneOf(globalIds(PatternGlobalPosition.Before)),
+        [GlobalSlot.Footer]: jsonOneOf(globalIds(PatternGlobalPosition.After)),
+    }, 'globals');
+    return jsonShapedObject(SHAPE['plan'], {
+        version: one(SITE_PLAN_VERSION),
+        source: sourceSchema(pin.source),
+        business: businessSchema(),
+        design: pinnedDesign(pin.design),
+        contentTypes: jsonListOf(contentTypeJsonSchema()),
+        dataSources: jsonListOf(dataSourceJsonSchema()),
+        pages: jsonListOf(pageJsonSchema()),
+        globals,
+    }, 'plan');
+}
+
+// ── The wire → the plan ─────────────────────────────────────────────────────────────────────────────
+
+const isEmptyObject = (v: unknown) => isPlainObject(v) && Object.keys(v).length === 0;
+
+/** `[{ slot, text }]` → `{ slot: text }`; anything that is not that list is left for the gate to refuse. */
+function slotsFromWire(slots: unknown): unknown {
+    if (!Array.isArray(slots)) return slots;
+    const out: PlainObject = {};
+    for (const entry of slots) {
+        if (!isPlainObject(entry) || typeof entry[SitePlanWireKey.SlotName] !== 'string') return slots;
+        out[entry[SitePlanWireKey.SlotName] as string] = entry[SitePlanWireKey.SlotText];
+    }
+    return out;
+}
+
+/** A section off the wire: its slots back to a map; a key the pattern has nothing for (`{}`) dropped. */
+export function sectionFromWire(section: unknown): unknown {
+    if (!isPlainObject(section)) return section;
+    const out: PlainObject = { ...section };
+    for (const key of ['slots', 'binding', 'without']) if (isEmptyObject(out[key])) delete out[key];
+    if ('slots' in out) out['slots'] = slotsFromWire(out['slots']);
+    return out;
+}
+
+/** A content type off the wire: its seed's `values` list back to field keys. */
+export function contentTypeFromWire(type: unknown): unknown {
+    if (!isPlainObject(type) || !isPlainObject(type['seed'])) return type;
+    const { [SitePlanWireKey.SeedValues]: values, ...seed } = type['seed'] as PlainObject;
+    if (Array.isArray(values)) {
+        for (const entry of values) {
+            if (isPlainObject(entry) && typeof entry[SitePlanWireKey.SeedField] === 'string') seed[entry[SitePlanWireKey.SeedField] as string] = entry[SitePlanWireKey.SeedValue];
+        }
+    } else if (values !== undefined) seed[SitePlanWireKey.SeedValues] = values;
+    return { ...type, seed };
+}
+
+function pageFromWire(page: unknown): unknown {
+    if (!isPlainObject(page) || !Array.isArray(page['sections'])) return page;
+    return { ...page, sections: (page['sections'] as unknown[]).map(sectionFromWire) };
+}
+
+/** The design off the wire: an empty optional object (a choice the pick does not carry) dropped. */
+function designFromWire(design: unknown): unknown {
+    if (!isPlainObject(design)) return design;
+    return Object.fromEntries(Object.entries(design).filter(([, v]) => !isEmptyObject(v)));
+}
+
+/**
+ * A model's answer → a Site Plan: the two listed maps back to maps, nothing else touched. Never repairs — whatever the
+ * answer got wrong is still wrong, for `validateSitePlan` to refuse with a path.
+ */
+export function sitePlanFromWire(wire: unknown): SitePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const out: PlainObject = { ...wire };
+    if (Array.isArray(out['contentTypes'])) out['contentTypes'] = (out['contentTypes'] as unknown[]).map(contentTypeFromWire);
+    if (Array.isArray(out['pages'])) out['pages'] = (out['pages'] as unknown[]).map(pageFromWire);
+    if ('design' in out) out['design'] = designFromWire(out['design']);
+    return out;
+}
+
+/** The plan → the wire (what a re-ask shows the model, and what the plan edits' prompt carries). */
+export function sitePlanToWire(plan: SitePlan): PlainObject {
+    const slotsToWire = (slots: Readonly<Record<string, string>> | undefined) =>
+        Object.entries(slots ?? {}).map(([slot, text]) => ({ [SitePlanWireKey.SlotName]: slot, [SitePlanWireKey.SlotText]: text }));
+    return {
+        ...plan,
+        contentTypes: plan.contentTypes.map(t => {
+            if (!t.seed) return t;
+            const { count, sample, isPublished, ...values } = t.seed;
+            return { ...t, seed: { count, sample, isPublished, [SitePlanWireKey.SeedValues]: Object.entries(values).map(([field, value]) => ({ [SitePlanWireKey.SeedField]: field, [SitePlanWireKey.SeedValue]: value })) } };
+        }),
+        pages: plan.pages.map(p => ({ ...p, sections: p.sections.map(s => (s.slots ? { ...s, slots: slotsToWire(s.slots) } : s)) })),
+    };
+}

package/src/harness-core/generation-view.ts

@@ -0,0 +1,115 @@
+import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+import type { AiGenerationStage, AiStep, PlanChange, PlanEdit, SitePlan } from '@vectoriox/iox-ui/generation-core';
+
+import type { StyleRead } from './rank';
+import type { SiteAnalysis } from './site-analysis';
+import type { PictureRole } from './site-reading';
+
+/**
+ * A generation as the screens read it (AI plan "M1 pipeline — the screens contract"): what iox-cms's
+ * `GET …/ai/generations/:id` answers and the Thinking · Analysis · Design · Plan · Build screens render. ONE
+ * definition: iox-cms builds it, cms-client types its client with it. Types and enums only — no transport.
+ */
+
+/** Where one reader is (Thinking's three lines). */
+export enum ReaderState {
+    Wait = 'wait',
+    Run = 'run',
+    Done = 'done',
+    /** Nothing to read (no pictures, no address). */
+    Skipped = 'skipped',
+    /** Refused on purpose (robots.txt, a private address…) — said in one plain line, never blocks the reading. */
+    Refused = 'refused',
+    Failed = 'failed',
+}
+
+/** Why a website address was not read (the screens' i18n `ai.siteRead.<reason>`). */
+export enum SiteReadRefusal {
+    /** robots.txt disallows our user agent (`IOX-Import`). */
+    Robots = 'robots',
+    InvalidAddress = 'invalid-address',
+    PrivateAddress = 'private-address',
+    Unreachable = 'unreachable',
+    Timeout = 'timeout',
+    TooLarge = 'too-large',
+    NotHtml = 'not-html',
+    HttpError = 'http-error',
+    TooManyRedirects = 'redirects',
+}
+
+/** What a sentence in the Plan prompt box did. */
+export enum PlanChangeOutcome {
+    Applied = 'applied',
+    /** The closed operations cannot say it — one line, the map unchanged (the call still cost). */
+    Cannot = 'cannot',
+    /** Its edits did not make a valid plan, twice — the map unchanged. */
+    Invalid = 'invalid',
+}
+
+export interface GenerationFileView {
+    key: string;
+    url: string;
+    role: `${PictureRole}`;
+}
+
+export interface SiteReaderView {
+    address: string;
+    state: `${ReaderState}`;
+    reason?: `${SiteReadRefusal}`;
+}
+
+export interface GenerationReadersView {
+    words: { state: `${ReaderState}` };
+    pictures: { state: `${ReaderState}`; count: number };
+    site: { state: `${ReaderState}`; addresses: SiteReaderView[] };
+}
+
+export interface PlanRevisionView {
+    plan: SitePlan;
+    at: string;
+    sentence?: string;
+    edits?: PlanEdit[];
+    changed?: PlanChange[];
+}
+
+export interface AiGenerationView {
+    _id: string;
+    organization: string;
+    stage: `${AiGenerationStage}`;
+    /** The model step the runner is working on; null = the owner's move. */
+    task: `${AiStep}` | null;
+    intake: { prompt: string; files: GenerationFileView[]; addresses: string[]; auto: boolean };
+    readers: GenerationReadersView;
+    reads: { analysis?: { value: SiteAnalysis; model: string; usageIds: string[] }; style?: StyleRead | null };
+    /** What Design and Plan use: the owner's edit, else the reading. */
+    analysis: SiteAnalysis | null;
+    analysisRevision: number;
+    design?: { presetId?: string; design: DesignChoices; auto?: boolean };
+    plan?: {
+        revisions: PlanRevisionView[];
+        model: string;
+        lastChange?: { sentence: string; outcome: `${PlanChangeOutcome}`; message?: string; at: string };
+    };
+    siteBuildId?: string;
+    models: Partial<Record<`${AiStep}`, string>>;
+    estimate: number;
+    cap: number;
+    /** Derived from the ledger — the running credit total. */
+    spent: number;
+    error?: { code: string; detail: string; providerMessage?: string; issues?: Array<{ code: string; path: string }> };
+}
+
+/** `POST …/ai/generations`. */
+export interface GenerationStartRequest {
+    prompt: string;
+    files?: Array<{ key: string; role?: `${PictureRole}` }>;
+    addresses?: string[];
+}
+
+/** The longest message, the most files and addresses a generation starts from (Start's limits). */
+export const GENERATION_LIMITS = {
+    promptChars: 4_000,
+    files: 12,
+    addresses: 3,
+    sentenceChars: 500,
+} as const;

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,7 @@ 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';

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 {