@vectoriox/iox-ui 5.53.0 → 5.55.0

package/harness-core/index.d.ts

@@ -1,5 +1,6 @@
-import { MotionId, MoodId, TintId, DensityId, DesignMotion, DesignChoices, DesignMode, StylePreset, AnimateId, ShapeId } from '@vectoriox/iox-ui/design-core';
-import { FactKey, PathIssue, SiteTemplate } from '@vectoriox/iox-ui/generation-core';
+import { MotionId, MoodId, TintId, DensityId, DesignMotion, DesignChoices, DesignMode, StylePreset, ShapeId, AnimateId } from '@vectoriox/iox-ui/design-core';
+import { FactKey, PathIssue, JsonSchema, SiteTemplate, ShapeEntry, AiGenerationStage, AiStep, SitePlan, PlanEdit, PlanChange } from '@vectoriox/iox-ui/generation-core';
+export { JsonSchema } from '@vectoriox/iox-ui/generation-core';
 
 declare const SPEC_HARNESS_SOURCE: {
     readonly repo: "nextlevelbuilder/ui-ux-pro-max-skill";
@@ -2572,18 +2573,7 @@ interface AnalysisContext {
 /** At most this many moods (the closed list a preset carries too). */
 declare const MAX_ANALYSIS_MOODS = 3;
 declare function validateSiteAnalysis(value: unknown, ctx: AnalysisContext): AnalysisValidation;
-/**
- * The structured-output schema a model is given to write a `SiteAnalysis` (AI plan §3c/§3d, M0-5): built from the
- * SAME shape table `validateSiteAnalysis` reads (keys, which are required, each key's explanation as its
- * description) and the same closed lists (30 business types, needs, facts, moods, avoids) — so the shape the model
- * is told about is the shape the gate refuses. Written to the strictest common subset of JSON Schema the providers'
- * native strict modes accept (Anthropic `output_config.format`, OpenRouter `json_schema` + `strict`): every object
- * closes with `additionalProperties: false`; no length, count or number bounds (the gate checks those). The
- * schema is a hint the provider enforces; `validateSiteAnalysis` stays the gate.
- */
-type JsonSchema = {
-    [key: string]: unknown;
-};
+
 /** The name a provider shows the format under (`json_schema.name`). */
 declare const SITE_ANALYSIS_SCHEMA_NAME = "site_analysis";
 declare function siteAnalysisJsonSchema(): JsonSchema;
@@ -2673,5 +2663,296 @@ interface StructureChoice {
  */
 declare function structureFor(typeId: string | null | undefined): StructureChoice;
 
-export { ANIMATE_ADVICE_STEPS, AnalysisIssueCode, AnalysisLocale, AvoidCheck, BUSINESS_TYPES, BUSINESS_TYPE_IDS, BookingNeed, COPY_LENGTH_ORDER, CopyLength, HARNESS_SOURCE, LITTLE_MOVEMENT_AVOID, LITTLE_MOVEMENT_CAP, LintKind, MAX_ANALYSIS_MOODS, NEEDS, NEED_IDS, NeedSource, PresetFit, RANK_WEIGHTS, READ_ANIMATE, READ_WEIGHTS, RankReason, SITE_ANALYSIS_SCHEMA_NAME, SPEC_ANALYSIS_SHAPE, SPEC_BUSINESS_TYPES, SPEC_HARNESS_EXAMPLES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS, STRUCTURES, StyleReadGround, StyleReadHeadings, StyleReadMotion, StyleReadSourceKind, USER_AVOID_IDS, VoiceFormality, VoicePerson, addressesIn, analysisPromptContext, businessTypeById, calmerChoice, inferNeeds, isLookRule, lintDesign, lookMatches, mapStyleRead, matchBusinessType, matchBusinessTypes, motionAdvice, motionFor, normalizeAddress, oklchHue, presetHasSerifHeadings, presetLook, presetReason, rankStylePresets, rankWithReferences, siteAnalysisJsonSchema, structureFor, userAvoidRule, validateSiteAnalysis, withoutAddress };
-export type { AnalysisContext, AnalysisIssue, AnalysisValidation, AvoidRule, BusinessType, BusinessTypeMatch, CheckRule, FactRead, GoodFit, JsonSchema, LintFinding, LintSite, LookCondition, LookDesign, LookRule, MotionBasis, MotionInput, MotionStart, NeedDef, NeedId, PromptContext, PromptContextOptions, PromptSection, RankInput, RankedPreset, SiteAnalysis, SiteNeed, StructureChoice, StructureId, StyleHints, StyleRead, UserAvoidId };
+/**
+ * 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). */
+interface ColourSample {
+    /** 0–255 each. */
+    r: number;
+    g: number;
+    b: number;
+    weight: number;
+}
+interface PaletteColour {
+    hex: string;
+    /** Its part of the whole, 0–1; the palette's shares add up to 1. */
+    share: number;
+}
+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). */
+declare const PALETTE_SIZE = 6;
+/** The sampling ceiling for a picture — every n-th pixel, so a 12 MP photo costs what a thumbnail does. */
+declare const MAX_PIXEL_SAMPLES = 20000;
+/** OKLab lightness / chroma thresholds the reading speaks in. */
+declare const PALETTE_THRESHOLDS: {
+    /** Above: a light colour. */
+    readonly light: 0.72;
+    /** Below: a dark colour. */
+    readonly dark: 0.38;
+    /** At least this share of light (or dark) makes the ground light (or dark); otherwise mixed. */
+    readonly groundShare: 0.55;
+    /** A brand candidate is at least this colourful… */
+    readonly brandChroma: 0.08;
+    /** …and neither near-white nor near-black. */
+    readonly brandMinL: 0.25;
+    readonly brandMaxL: 0.92;
+    /** Two palette colours closer than this (OKLab distance) are one colour. */
+    readonly mergeDistance: 0.035;
+};
+/** Every n-th opaque pixel of an RGBA buffer (canvas `ImageData.data`, a decoder's pixels), weight 1 each. */
+declare function pixelSamples(rgba: ArrayLike<number>, width: number, height: number, max?: number): ColourSample[];
+/** A palette (hex + share) back to samples — what merging two readings measures. */
+declare function paletteSamples(palette: ReadonlyArray<PaletteColour>, weight?: number): ColourSample[];
+/** Weighted samples → ≤ 6 colours, largest share first (ties by hex), shares adding up to 1. */
+declare function measurePalette(samples: ReadonlyArray<ColourSample>, size?: number): PaletteColour[];
+/** Light, dark or mixed: the share of the palette that is light (or dark). */
+declare function paletteGround(palette: ReadonlyArray<PaletteColour>): `${StyleReadGround}`;
+/** The most frequent saturated colour that is neither near-white nor near-black, or undefined. */
+declare function paletteBrand(palette: ReadonlyArray<PaletteColour>): string | undefined;
+/** The whole reading of a set of samples: the palette, its ground, its brand candidate. */
+declare function readPalette(samples: ReadonlyArray<ColourSample>): PaletteReading;
+
+/**
+ * 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.
+ */
+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`. */
+declare function seedPassesPreset(presetId: string, seed: string): {
+    passes: boolean;
+    failsIn: Array<'light' | 'dark'>;
+};
+/** The seed a preset starts from, given a reading (or none). Unknown preset → null. */
+declare function referenceSeed(read: Pick<StyleRead, 'brand'> | null | undefined, presetId: string): ReferenceSeed | null;
+
+/**
+ * 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). */
+declare enum PictureRole {
+    Own = "own",
+    Reference = "reference"
+}
+/** At most this many pictures go to the reading call as image input (§3d: "up to 6 pictures"). */
+declare const MAX_READ_PICTURES = 6;
+declare const READING_SHAPE: Readonly<Record<string, ShapeEntry>>;
+interface PictureStyle {
+    moods: MoodId[];
+    headings?: `${StyleReadHeadings}`;
+    shape?: ShapeId;
+    density?: DensityId;
+}
+interface SiteReading {
+    analysis: SiteAnalysis;
+    /** Present when pictures were attached. */
+    pictures?: {
+        files: Array<{
+            index: number;
+            role: `${PictureRole}`;
+        }>;
+        style: PictureStyle;
+    };
+}
+declare const SITE_READING_SCHEMA_NAME = "site_reading";
+/** The reading's format: the analysis alone when no picture was attached, else the analysis + the pictures. */
+declare function siteReadingJsonSchema(pictureCount: number): JsonSchema;
+declare enum ReadingIssueCode {
+    Shape = "shape",
+    UnknownKey = "unknown-key",
+    Duplicate = "duplicate",
+    InvalidValue = "invalid-value",
+    /** A picture named twice, or one left out. */
+    Pictures = "pictures"
+}
+type ReadingIssue = PathIssue<ReadingIssueCode> | AnalysisIssue;
+/** The reading's gate: the analysis by `validateSiteAnalysis` (paths under `analysis.` when pictures came too), the pictures by `READING_SHAPE`. */
+declare function validateSiteReading(value: unknown, ctx: {
+    prompt: string;
+    pictureCount: number;
+}): {
+    valid: boolean;
+    issues: ReadingIssue[];
+};
+/** A valid reading's answer → `SiteReading` (the analysis alone answers `{ analysis }`). */
+declare function decodeSiteReading(value: unknown, pictureCount: number): SiteReading;
+/** A reference picture as the server read it: its measured palette (and where it is). */
+interface MeasuredPicture {
+    ref: string;
+    palette: StyleRead['palette'];
+}
+/** The liked pictures as a StyleRead: their palettes measured together, what the model saw of them. */
+declare function pictureStyleRead(pictures: ReadonlyArray<MeasuredPicture>, style: PictureStyle | null | undefined): StyleRead | null;
+/**
+ * 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.
+ */
+declare function mergeStyleReads(reads: ReadonlyArray<StyleRead | null | undefined>): StyleRead | null;
+
+/**
+ * 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). */
+declare 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>`). */
+declare 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. */
+declare 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"
+}
+interface GenerationFileView {
+    key: string;
+    url: string;
+    role: `${PictureRole}`;
+}
+interface SiteReaderView {
+    address: string;
+    state: `${ReaderState}`;
+    reason?: `${SiteReadRefusal}`;
+}
+interface GenerationReadersView {
+    words: {
+        state: `${ReaderState}`;
+    };
+    pictures: {
+        state: `${ReaderState}`;
+        count: number;
+    };
+    site: {
+        state: `${ReaderState}`;
+        addresses: SiteReaderView[];
+    };
+}
+interface PlanRevisionView {
+    plan: SitePlan;
+    at: string;
+    sentence?: string;
+    edits?: PlanEdit[];
+    changed?: PlanChange[];
+}
+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`. */
+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). */
+declare const GENERATION_LIMITS: {
+    readonly promptChars: 4000;
+    readonly files: 12;
+    readonly addresses: 3;
+    readonly sentenceChars: 500;
+};
+
+export { ANIMATE_ADVICE_STEPS, AnalysisIssueCode, AnalysisLocale, AvoidCheck, BUSINESS_TYPES, BUSINESS_TYPE_IDS, BookingNeed, COPY_LENGTH_ORDER, CopyLength, GENERATION_LIMITS, HARNESS_SOURCE, LITTLE_MOVEMENT_AVOID, LITTLE_MOVEMENT_CAP, LintKind, MAX_ANALYSIS_MOODS, MAX_PIXEL_SAMPLES, MAX_READ_PICTURES, NEEDS, NEED_IDS, NeedSource, PALETTE_SIZE, PALETTE_THRESHOLDS, PictureRole, PlanChangeOutcome, PresetFit, RANK_WEIGHTS, READING_SHAPE, READ_ANIMATE, READ_WEIGHTS, RankReason, ReaderState, ReadingIssueCode, SITE_ANALYSIS_SCHEMA_NAME, SITE_READING_SCHEMA_NAME, SPEC_ANALYSIS_SHAPE, SPEC_BUSINESS_TYPES, SPEC_HARNESS_EXAMPLES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS, STRUCTURES, SiteReadRefusal, StyleReadGround, StyleReadHeadings, StyleReadMotion, StyleReadSourceKind, USER_AVOID_IDS, VoiceFormality, VoicePerson, addressesIn, analysisPromptContext, businessTypeById, calmerChoice, decodeSiteReading, inferNeeds, isLookRule, lintDesign, lookMatches, mapStyleRead, matchBusinessType, matchBusinessTypes, measurePalette, mergeStyleReads, motionAdvice, motionFor, normalizeAddress, oklchHue, paletteBrand, paletteGround, paletteSamples, pictureStyleRead, pixelSamples, presetHasSerifHeadings, presetLook, presetReason, rankStylePresets, rankWithReferences, readPalette, referenceSeed, seedPassesPreset, siteAnalysisJsonSchema, siteReadingJsonSchema, structureFor, userAvoidRule, validateSiteAnalysis, validateSiteReading, withoutAddress };
+export type { AiGenerationView, AnalysisContext, AnalysisIssue, AnalysisValidation, AvoidRule, BusinessType, BusinessTypeMatch, CheckRule, ColourSample, FactRead, GenerationFileView, GenerationReadersView, GenerationStartRequest, GoodFit, LintFinding, LintSite, LookCondition, LookDesign, LookRule, MeasuredPicture, MotionBasis, MotionInput, MotionStart, NeedDef, NeedId, PaletteColour, PaletteReading, PictureStyle, PlanRevisionView, PromptContext, PromptContextOptions, PromptSection, RankInput, RankedPreset, ReadingIssue, ReferenceSeed, SiteAnalysis, SiteNeed, SiteReaderView, SiteReading, StructureChoice, StructureId, StyleHints, StyleRead, UserAvoidId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.53.0",
+  "version": "5.55.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/generation-core/ai-run.ts

@@ -4,6 +4,8 @@
  * list with its price per token class, the one cost → credits rule (1 credit = 1 US cent of what the AI cost, D4),
  * the refusals (board 11) and a generation's stages. ONE definition: iox-cms meters and refuses with it, the
  * Settings ▸ AI screen and the wizard show it. Pure types, enums and helpers; no transport, no prices typed here.
+ * The step and capability spellings are the control plane's (`GET /instances/me/entitlements`, AI plan "M0 control
+ * plane — the instance-route contract") — the platform has ONE spelling of each.
  */
 
 export enum AiProviderId {
@@ -19,20 +21,29 @@ export enum AiKeyMode {
 
 /** The steps a model works on (board 9's rows), in screen order. */
 export enum AiStep {
-    ReadMessage = 'read',
+    ReadMessage = 'analysis',
     PlanSite = 'plan',
-    ChangePlan = 'change',
-    MakePictures = 'pictures',
-    NameStructures = 'scan',
+    ChangePlan = 'planEdit',
+    MakePictures = 'image',
+    NameStructures = 'scanNaming',
 }
 
 export const AI_STEPS: ReadonlyArray<AiStep> = Object.values(AiStep);
 
+/** Each step's name on the wire (the control plane's `label`, the console) — the screens translate their own. */
+export const AI_STEP_LABELS: Readonly<Record<AiStep, string>> = {
+    [AiStep.ReadMessage]: 'Read your message',
+    [AiStep.PlanSite]: 'Plan the site',
+    [AiStep.ChangePlan]: 'Change the plan',
+    [AiStep.MakePictures]: 'Make pictures',
+    [AiStep.NameStructures]: 'Name repeated structures',
+};
+
 /** What a model must be able to do for a step to run on it. */
 export enum AiCapability {
-    StructuredOutput = 'structured-output',
-    ImageInput = 'image-input',
-    ImageOutput = 'image-output',
+    StructuredOutput = 'structuredOutputs',
+    ImageInput = 'imageInput',
+    ImageOutput = 'imageOutput',
 }
 
 export const AI_STEP_NEEDS: Readonly<Record<AiStep, ReadonlyArray<AiCapability>>> = {
@@ -48,7 +59,8 @@ export const AI_STEP_TYPICAL_TOKENS: Readonly<Record<AiStep, AiTokenCounts>> = {
     [AiStep.ReadMessage]: { input: 8_800, output: 1_500, cacheWrite: 0, cacheRead: 0 },
     [AiStep.PlanSite]: { input: 12_000, output: 7_000, cacheWrite: 0, cacheRead: 0 },
     [AiStep.ChangePlan]: { input: 6_000, output: 500, cacheWrite: 0, cacheRead: 0 },
-    [AiStep.MakePictures]: { input: 1_120, output: 0, cacheWrite: 0, cacheRead: 0 },
+    // a 1 K picture is 1,120 image tokens (Google's figure for Nano Banana 2) — I-D4
+    [AiStep.MakePictures]: { input: 0, output: 0, cacheWrite: 0, cacheRead: 0, imageOutput: 1_120 },
     [AiStep.NameStructures]: { input: 80_000, output: 10_000, cacheWrite: 0, cacheRead: 0 },
 };
 
@@ -60,6 +72,8 @@ export interface AiTokenCounts {
     cacheWrite: number;
     /** Read from the prompt cache (priced well below input). */
     cacheRead: number;
+    /** Image tokens written (a picture step) — priced at `imageOutput`. */
+    imageOutput?: number;
 }
 
 /** US dollars per million tokens, per class. A class without a price is priced as input. */
@@ -68,6 +82,8 @@ export interface AiTokenPrice {
     output: number;
     cacheWrite?: number;
     cacheRead?: number;
+    /** Image-output tokens; a model without the price is priced at `output`. */
+    imageOutput?: number;
 }
 
 /** A model of the vetted list (served by the control plane with the entitlements, §3n) — its price travels with it. */
@@ -79,6 +95,8 @@ export interface AiModelEntry {
     steps: ReadonlyArray<`${AiStep}`>;
     /** The steps it is the default for (board 9's "recommended"). */
     recommendedFor?: ReadonlyArray<`${AiStep}`>;
+    /** The steps it runs when the default is not available (the control plane's `fallbackModel`). */
+    fallbackFor?: ReadonlyArray<`${AiStep}`>;
     capabilities: ReadonlyArray<`${AiCapability}`>;
     /** Null when the provider reports each call's cost itself and the list carries no price. */
     price: AiTokenPrice | null;
@@ -99,7 +117,8 @@ export function costUsd(tokens: AiTokenCounts, price: AiTokenPrice): number {
     return tokens.input * perToken(price.input, 0)
         + tokens.output * perToken(price.output, 0)
         + tokens.cacheWrite * perToken(price.cacheWrite, price.input)
-        + tokens.cacheRead * perToken(price.cacheRead, price.input);
+        + tokens.cacheRead * perToken(price.cacheRead, price.input)
+        + (tokens.imageOutput ?? 0) * perToken(price.imageOutput, price.output);
 }
 
 /** Dollars → credits, kept to a millionth of a credit (a short read costs a fraction of one). */

package/src/generation-core/json-schema.ts

@@ -0,0 +1,97 @@
+import { requiredShapeKeys, ShapeEntry, shapeKeys } from './shape-check';
+
+/**
+ * The ONE set of builders every structured-output format is written with (AI plan §3c, M0-5 / M1-1 / M1-3 / M1-5):
+ * the SiteAnalysis, the reading, the Site Plan and the plan edits. Each object is built FROM a documented shape table
+ * (`shape-check`): its keys are the table's keys, the required ones are the table's required ones, each described in
+ * the table's own words — and a builder handed a key list that disagrees with its table THROWS, so a shape that gains
+ * a key cannot ship a format that silently lacks it. The subset is the strictest both providers' native strict modes
+ * accept (Anthropic `output_config.format`, OpenRouter `json_schema` + `strict`): every object closed
+ * (`additionalProperties: false`), unions as `anyOf`, single values as a one-entry `enum`, no length / count / number
+ * bounds, no `$ref`. The format is a hint the provider enforces; the shared validator stays the gate.
+ */
+
+export type JsonSchema = { [key: string]: unknown };
+
+const OPTIONAL_MARK = '?';
+
+export class JsonSchemaShapeError extends Error {}
+
+export const jsonText = (): JsonSchema => ({ type: 'string' });
+export const jsonBoolean = (): JsonSchema => ({ type: 'boolean' });
+export const jsonInteger = (): JsonSchema => ({ type: 'integer' });
+export const jsonOneOf = (values: ReadonlyArray<string>): JsonSchema => ({ type: 'string', enum: [...values] });
+export const jsonListOf = (items: JsonSchema): JsonSchema => ({ type: 'array', items });
+export const jsonAnyOf = (options: ReadonlyArray<JsonSchema>): JsonSchema => ({ anyOf: [...options] });
+
+/** A closed object with exactly these properties. */
+export function jsonClosedObject(properties: Record<string, JsonSchema>, required: ReadonlyArray<string>, description?: string): JsonSchema {
+    return {
+        type: 'object',
+        properties,
+        required: [...required],
+        additionalProperties: false,
+        ...(description ? { description } : {}),
+    };
+}
+
+/** The table's own words for a key (`key` or `key?`). */
+export function describeShapeKey(entry: ShapeEntry, key: string): string {
+    return String(entry[key] ?? entry[`${key}${OPTIONAL_MARK}`] ?? '');
+}
+
+/** An entry's `[name]` keys (the object's own field names) written as ONE list on the wire — no strict mode can say
+ *  "any key", so the map travels as `[{ name, value }]` under `key` and the decoder turns it back. */
+export interface DynamicKeysAsList {
+    /** The wire key holding the list. */
+    key: string;
+    /** The list's schema. */
+    schema: JsonSchema;
+}
+
+/**
+ * An object of one shape-table entry: exactly its fixed keys, its required keys required, each described by the
+ * table; an entry's `[name]` keys are not object keys — `dynamic` writes them as one list. Throws when the properties
+ * given are not the table's keys.
+ */
+export function jsonShapedObject(entry: ShapeEntry, properties: Record<string, JsonSchema>, name = 'shape', dynamic?: DynamicKeysAsList): JsonSchema {
+    const expected = [...shapeKeys(entry)].sort();
+    const given = Object.keys(properties).sort();
+    if (expected.join() !== given.join()) {
+        throw new JsonSchemaShapeError(`${name}: the format's keys (${given.join(', ')}) are not the shape table's (${expected.join(', ')})`);
+    }
+    const dynamicKey = Object.keys(entry).find(k => /^\[[^\]]+\]\??$/.test(k));
+    if (!!dynamic !== !!dynamicKey) throw new JsonSchemaShapeError(`${name}: ${dynamicKey ? `its ${dynamicKey} keys need a list on the wire` : 'it has no [name] keys to list'}`);
+    const described = Object.fromEntries(Object.entries(properties).map(([key, schema]) => [key, { ...schema, description: describeShapeKey(entry, key) }]));
+    if (dynamic && dynamicKey) described[dynamic.key] = { ...dynamic.schema, description: `${dynamicKey}: ${entry[dynamicKey]}` };
+    return jsonClosedObject(described, requiredShapeKeys(entry));
+}
+
+/** Every keyword a schema uses — what a spec checks against the strict subset. */
+export function jsonSchemaKeywords(node: unknown, out = new Set<string>()): Set<string> {
+    if (Array.isArray(node)) node.forEach(n => jsonSchemaKeywords(n, out));
+    else if (node && typeof node === 'object') {
+        for (const [k, v] of Object.entries(node)) {
+            out.add(k);
+            if (k === 'properties') Object.values(v as object).forEach(p => jsonSchemaKeywords(p, out));
+            else if (k !== 'enum' && k !== 'required' && k !== 'description') jsonSchemaKeywords(v, out);
+        }
+    }
+    return out;
+}
+
+/** The keywords the strict subset never uses. */
+export const JSON_SCHEMA_BANNED_KEYWORDS: ReadonlyArray<string> = [
+    'minLength', 'maxLength', 'minimum', 'maximum', 'minItems', 'maxItems', 'pattern', 'oneOf', '$ref', 'const', 'format',
+];
+
+/** Every object node of a schema (through properties, items and anyOf). */
+export function jsonSchemaObjects(node: unknown, out: JsonSchema[] = []): JsonSchema[] {
+    if (!node || typeof node !== 'object') return out;
+    const n = node as JsonSchema;
+    if (n['type'] === 'object') out.push(n);
+    for (const p of Object.values((n['properties'] as object | undefined) ?? {})) jsonSchemaObjects(p, out);
+    if (n['items']) jsonSchemaObjects(n['items'], out);
+    for (const option of (n['anyOf'] as unknown[] | undefined) ?? []) jsonSchemaObjects(option, out);
+    return out;
+}