@vectoriox/iox-ui 5.54.0 → 5.56.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,314 @@ 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;
+};
+
+/**
+ * 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. */
+declare function presetDesign(presetId: string, input: MotionInput | string | null, kept?: Partial<Pick<DesignChoices, 'scroll' | 'animate' | 'between' | 'motion'>>, read?: StyleRead | null): DesignChoices | null;
+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. */
+declare function startingDesign(input: (RankInput & MotionInput) | string | null, read?: StyleRead | null): StartingDesign | null;
+
+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, presetDesign, presetHasSerifHeadings, presetLook, presetReason, rankStylePresets, rankWithReferences, readPalette, referenceSeed, seedPassesPreset, siteAnalysisJsonSchema, siteReadingJsonSchema, startingDesign, 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, StartingDesign, StructureChoice, StructureId, StyleHints, StyleRead, UserAvoidId };

package/package.json

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

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

@@ -30,6 +30,15 @@ export enum AiStep {
 
 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 = 'structuredOutputs',
@@ -50,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 },
 };
 
@@ -62,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. */
@@ -70,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. */
@@ -103,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). */