@vectoriox/iox-ui 5.51.0 → 5.53.0

package/src/harness-core/rank.ts

@@ -5,6 +5,7 @@ import type { AnimateId } from '@vectoriox/iox-ui/design-core';
 
 import { AvoidRule, BUSINESS_TYPES, BusinessType, isLookRule, LookRule, userAvoidRule } from './business-types';
 import { lookMatches, presetLook } from './look';
+import { AnalysisLocale } from './site-analysis';
 
 /**
  * Which styles suit a business, best first (AI plan rev 3 §3f, H3) — Design ▸ Look's order. Pure and
@@ -45,6 +46,8 @@ export interface RankedPreset {
     reasonKind: RankReason;
     /** In English, from the contract (the UI may localise `reasonKind` + `sharedMoods` instead). */
     reason: string;
+    /** A good fit's reason in Hebrew (the contract has Hebrew for good fits; `presetReason` picks). */
+    reasonHe?: string;
     sharedMoods: MoodId[];
     /** Catalogue position — ties keep it. */
     order: number;
@@ -113,10 +116,23 @@ export function rankStylePresets(
             : goodAt >= 0 && type ? [RankReason.GoodFit, type.good[goodAt].reason]
             : sharedMoods.length ? [RankReason.SharedMoods, moodsLine(sharedMoods)]
             : [RankReason.None, ''];
-        return { id: preset.id, fit, score, reasonKind, reason, sharedMoods, order };
+        const reasonHe = reasonKind === RankReason.GoodFit && type ? type.good[goodAt].reasonHe : undefined;
+        return { id: preset.id, fit, score, reasonKind, reason, ...(reasonHe ? { reasonHe } : {}), sharedMoods, order };
     }).sort((a, b) => b.score - a.score || a.order - b.order);
 }
 
+/**
+ * The line a style's card shows (its title): why it sits where it does, else what the style is — in the studio's
+ * language where the contract has it. Decided 2026-10-25: good fits and descriptions have Hebrew (the name stays a
+ * proper name); a type's or the owner's advice and the shared-moods line are English in the contract yet.
+ */
+export function presetReason(ranked: RankedPreset, preset: StylePreset | undefined, locale: string | null | undefined): string {
+    const hebrew = locale === AnalysisLocale.He;
+    if (hebrew && ranked.reasonKind === RankReason.GoodFit && ranked.reasonHe) return ranked.reasonHe;
+    if (ranked.reason) return ranked.reason;
+    return (hebrew ? preset?.blurbHe : preset?.blurb) ?? '';
+}
+
 // ── References: a reading of pictures or a site, as style (plan §3k, R4) ─────────────────────────────────
 export enum StyleReadSourceKind {
     Image = 'image',

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

@@ -178,3 +178,73 @@ export function validateSiteAnalysis(value: unknown, ctx: AnalysisContext): Anal
 
     return { valid: c.issues.length === 0, issues: c.issues };
 }
+
+/**
+ * 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.
+ */
+
+export type JsonSchema = { [key: string]: unknown };
+
+/** 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}`] ?? '');
+}
+
+/** 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,
+    };
+}
+
+/** `{ [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'),
+    };
+}
+
+export function siteAnalysisJsonSchema(): JsonSchema {
+    const factRead = shaped('factRead', { value: text(), quote: text() });
+    return shaped('analysis', {
+        businessType: oneOf(BUSINESS_TYPE_IDS),
+        alternatives: listOf(oneOf(BUSINESS_TYPE_IDS)),
+        business: shaped('business', { name: text(), audience: text() }),
+        needs: listOf(shaped('need', { id: oneOf(NEED_IDS), from: oneOf(Object.values(NeedSource)), name: text() })),
+        facts: factsSchema(factRead),
+        missingFacts: listOf(oneOf(FACT_KEYS)),
+        voice: shaped('voice', {
+            tone: text(),
+            person: oneOf(Object.values(VoicePerson)),
+            formality: oneOf(Object.values(VoiceFormality)),
+            avoidWords: listOf(text()),
+        }),
+        moods: listOf(oneOf(MOOD_IDS)),
+        avoid: listOf(oneOf(USER_AVOID_IDS)),
+        hero: shaped('hero', { headline: text(), lead: text() }),
+        locale: oneOf(Object.values(AnalysisLocale)),
+    });
+}