@vectoriox/iox-ui 5.53.0 → 5.55.0

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;
+}