@vectoriox/iox-ui 5.59.1 → 5.61.0

package/src/generation-core/plan-wire.ts

@@ -0,0 +1,458 @@
+import { ANIMATE_IDS, DesignChoices } from '@vectoriox/iox-ui/design-core';
+import { FORM_PRESETS } from '@vectoriox/iox-ui/forms-core';
+
+import { describeShapeKey, jsonAnyOf, jsonBoolean, jsonInteger, jsonListOf, jsonOneOf, JsonSchema, jsonShapedObject, jsonText } from './json-schema';
+import { patternLinkSlots, patternOptionalParts, patternSlots, PatternGlobalPosition, SITE_PATTERNS } from './patterns';
+import {
+    ContentFieldPlan, ContentTypePlan, DataSourcePlan, FactKey, GlobalSlot, PAGE_ARCHETYPES, PagePlan, PageSectionPlan, PlanDataSourceMode, PlanDataSourceType,
+    RelativeOp, SITE_NEED_IDS, SITE_PLAN_VERSION, SitePlan, SitePlanSource, SiteLocale,
+} from './site-plan.model';
+import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
+import { isPlainObject, PlainObject, ShapeEntry, shapeKeys } from './shape-check';
+
+/**
+ * The plan WIRE (AI plan M1-3, vectoriox/iox-cms#45): what a model writes when it plans a site — a compact format inside
+ * the Claude API's structured-output limits (≤ 24 optional parameters and ≤ 16 unions per request; `strict-schema.ts`).
+ * The Site Plan itself (`SPEC_SITE_PLAN_SHAPE`) has 213 optional keys once every pattern is a branch, so the model never
+ * writes it: it writes this, and ONE pure `expandPlanWire` turns it into the Site Plan that `validateSitePlan` and the
+ * stage's gate judge exactly as before.
+ *
+ * - **Every key required.** A plan key that may be absent is written with its stated "none" — `''`, `0`, `false`, `[]`.
+ * - **Closed lists as enums** (patterns, page types, needs, slots, parts, forms, entrances, header/footer), from the
+ *   contract — never per-pattern branches: the gate refuses a slot or a part the chosen pattern does not have, with its path.
+ * - **Maps as lists:** slots `[{ slot, text }]`, links `[{ slot, route }]`, seed values `[{ field, value }]`, roles fixed.
+ * - **One data source object** for both kinds; `type` says which keys are read (the other kind's hold their none).
+ * - **What the model does not decide is not on the wire** (`PLAN_WIRE_DERIVED`): the look (the owner's pick), the run,
+ *   the language (the reading's), the facts (the owner's own, verbatim), the version, the home page (the page at `/`).
+ *   So the format is the same for every studio and every run — one compiled grammar, cached by the provider.
+ *
+ * ONE source: every wire key names the plan keys it carries (`refs`) and is described in the plan table's own words, and
+ * every plan key is either carried or derived (`planWireGaps()`); a key the plan shape gains breaks the builder until it
+ * is placed. The expanders translate, never repair: a value the model got wrong stays wrong, for the gate to refuse.
+ */
+
+export const PLAN_WIRE_SCHEMA_NAME = 'site_plan';
+
+export enum PlanWireEntry {
+    Plan = 'plan',
+    Business = 'business',
+    ContentType = 'contentType',
+    Roles = 'roles',
+    Field = 'field',
+    Seed = 'seed',
+    SeedValue = 'seedValue',
+    DataSource = 'dataSource',
+    Page = 'page',
+    PageSeo = 'pageSeo',
+    Section = 'section',
+    SlotText = 'slotText',
+    SlotLink = 'slotLink',
+    Globals = 'globals',
+}
+
+type PlanShapeName = keyof typeof SPEC_SITE_PLAN_SHAPE;
+
+interface WireKey {
+    /** The plan keys it carries (`entry.key`, `[field]` for a dynamic key). */
+    refs: ReadonlyArray<string>;
+    /** Its own words, when the first ref's do not fit the wire. */
+    text?: string;
+    /** What stands for "absent" (an optional plan key). */
+    none?: string;
+}
+
+const PLAN_SHAPE = SPEC_SITE_PLAN_SHAPE as unknown as Readonly<Record<string, ShapeEntry>>;
+const key = (ref: string, none?: string): WireKey => ({ refs: [ref], ...(none !== undefined ? { none } : {}) });
+
+const WIRE_KEYS: Readonly<Record<`${PlanWireEntry}`, Readonly<Record<string, WireKey>>>> = {
+    plan: {
+        business: key('plan.business'),
+        contentTypes: key('plan.contentTypes'),
+        dataSources: { refs: ['plan.dataSources'], text: 'dataSource[] — merged by alias into the org library' },
+        pages: key('plan.pages'),
+        globals: key('plan.globals'),
+    },
+    business: {
+        name: key('business.name'),
+        tagline: key('business.tagline', "''"),
+    },
+    contentType: {
+        name: key('contentType.name'),
+        label: key('contentType.label'),
+        roles: key('contentType.roles'),
+        fields: key('contentType.fields'),
+        seed: { refs: ['contentType.seed'], text: 'seed — the sample items', none: 'count 0 and no values' },
+    },
+    roles: {
+        title: key('roles.title'),
+        summary: key('roles.summary', "''"),
+        image: key('roles.image', "''"),
+        meta: key('roles.meta', "''"),
+        date: key('roles.date', "''"),
+        gallery: key('roles.gallery', "''"),
+    },
+    field: {
+        name: key('field.name'),
+        type: key('field.type'),
+        controller: key('field.controller'),
+        required: { refs: ['field.required'], text: 'boolean — the field must be filled', none: 'false' },
+        note: key('field.note', "''"),
+    },
+    seed: {
+        count: key('seed.count'),
+        sample: key('seed.sample'),
+        isPublished: key('seed.isPublished'),
+        values: { refs: ['seed.[field]'], text: "seedValue[] — one per field: the samples' value for it" },
+    },
+    seedValue: {
+        field: { refs: ['seed.[field]'], text: 'string — a field of the type' },
+        value: { refs: ['seed.[field]'], text: `string | string[] — ${describeShapeKey(PLAN_SHAPE['seed'], '[field]')} (a list for an array field)` },
+    },
+    dataSource: {
+        alias: { refs: ['cmsDataSource.alias', 'relativeDataSource.alias'] },
+        type: { refs: ['cmsDataSource.type', 'relativeDataSource.type'], text: "'cms' | 'relative' — which of the keys below are read" },
+        mode: key('cmsDataSource.mode', "'' (relative)"),
+        contentType: key('cmsDataSource.contentType', "'' (relative)"),
+        limit: key('cmsDataSource.limit', '0 (all, or relative)'),
+        filterField: { refs: ['cmsDataSource.filterByRouteParam'], text: "string — single only: the field that holds the route param's value (e.g. slug)", none: "''" },
+        routeParam: { refs: ['cmsDataSource.filterByRouteParam'], text: 'string — single only: the route param that picks the item (the :param of its page route)', none: "''" },
+        of: key('relativeDataSource.of', "'' (cms)"),
+        op: key('relativeDataSource.op', "'' (cms)"),
+        within: key('relativeDataSource.within', "'' (cms)"),
+    },
+    page: {
+        key: key('page.key'),
+        name: key('page.name'),
+        route: { refs: ['page.route'], text: `${describeShapeKey(PLAN_SHAPE['page'], 'route')}; the page at "/" is the home page` },
+        inNav: key('page.inNav', 'false'),
+        archetype: key('page.archetype', "''"),
+        need: key('page.need', "''"),
+        template: key('page.template', "''"),
+        routeSource: key('page.routeSource', "''"),
+        seo: key('page.seo'),
+        sections: key('page.sections'),
+    },
+    pageSeo: {
+        title: key('pageSeo.title', "''"),
+        description: key('pageSeo.description', "''"),
+    },
+    section: {
+        pattern: key('section.pattern'),
+        slots: { refs: ['section.slots'], text: "slotText[] — the pattern's declared slots it fills, each within its budget (site.patterns … max × site.copyLengths)", none: '[]' },
+        links: { refs: ['section.links'], text: 'slotLink[] — re-points a linked slot (a button, a link) to another page route of the plan', none: '[]' },
+        binding: key('section.binding', "''"),
+        without: key('section.without', '[]'),
+        form: key('section.form', "''"),
+        enter: key('section.enter', "'' (the look's)"),
+    },
+    slotText: {
+        slot: { refs: ['section.slots'], text: "string — one of the pattern's slots" },
+        text: { refs: ['section.slots'], text: "string — the words, in the owner's language and voice" },
+    },
+    slotLink: {
+        slot: { refs: ['section.links'], text: "string — one of the pattern's linked slots" },
+        route: { refs: ['section.links'], text: 'string — a page route of the plan (no :param)' },
+    },
+    globals: {
+        header: key('globals.header'),
+        footer: key('globals.footer'),
+    },
+};
+
+/** The plan keys the model does not write, and where the expander takes each from. */
+export const PLAN_WIRE_DERIVED: Readonly<Record<string, string>> = {
+    'plan.version': `always '${SITE_PLAN_VERSION}'`,
+    'plan.source': 'this run (the context)',
+    'plan.locale': "the reading's language (the context)",
+    'plan.design': "the owner's pick (the context)",
+    'business.facts': "the owner's own facts, verbatim (the context)",
+    'page.isHome': 'the page at "/"',
+    'page.required': "a template page's (the wizard's Pages step), never the AI's",
+    sourceTemplate: 'the AI never writes a template plan',
+    sourceAi: 'this run (the context)',
+    design: "the owner's pick (the context)",
+};
+
+const wireText = (spec: WireKey): string => {
+    const [entry, planKey] = spec.refs[0].split('.');
+    const base = spec.text ?? describeShapeKey(PLAN_SHAPE[entry], planKey);
+    return spec.none === undefined ? base : `${base} — ${spec.none} = none`;
+};
+
+/** The wire's shape table, in the plan table's words — what the model reads, and what the format is built from. */
+export const PLAN_WIRE_SHAPE: Readonly<Record<`${PlanWireEntry}`, ShapeEntry>> = Object.fromEntries(
+    Object.entries(WIRE_KEYS).map(([entry, keys]) => [entry, Object.fromEntries(Object.entries(keys).map(([k, spec]) => [k, wireText(spec)]))]),
+) as Record<`${PlanWireEntry}`, ShapeEntry>;
+
+/** Plan keys neither carried by a wire key nor derived — always empty (a spec and the builder hold it). */
+export function planWireGaps(): string[] {
+    const carried = new Set(Object.values(WIRE_KEYS).flatMap(keys => Object.values(keys).flatMap(spec => spec.refs)));
+    const gaps: string[] = [];
+    for (const [entry, shape] of Object.entries(PLAN_SHAPE)) {
+        if (PLAN_WIRE_DERIVED[entry]) continue;
+        for (const raw of Object.keys(shape)) {
+            const ref = `${entry}.${raw.replace(/\?$/, '')}`;
+            if (!carried.has(ref) && !PLAN_WIRE_DERIVED[ref]) gaps.push(ref);
+        }
+    }
+    return gaps;
+}
+
+export class PlanWireShapeError extends Error {}
+
+// ── The format ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+const unique = (values: ReadonlyArray<string>) => [...new Set(values)];
+const NONE = '';
+const orNone = (values: ReadonlyArray<string>): JsonSchema => jsonOneOf([NONE, ...values]);
+const closedOrText = (values: ReadonlyArray<string>): JsonSchema => (values.length ? jsonOneOf(values) : jsonText());
+const shaped = (entry: `${PlanWireEntry}`, properties: Record<string, JsonSchema>) => jsonShapedObject(PLAN_WIRE_SHAPE[entry], properties, `wire ${entry}`);
+
+/** 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);
+}
+
+const sectionPatterns = () => sectionPatternIds().map(id => SITE_PATTERNS[id]);
+const globalIds = (position: `${PatternGlobalPosition}`) => Object.entries(SITE_PATTERNS).filter(([, p]) => p.global === position).map(([id]) => id);
+
+export function wireFieldJsonSchema(): JsonSchema {
+    return shaped(PlanWireEntry.Field, { name: jsonText(), type: jsonText(), controller: jsonText(), required: jsonBoolean(), note: jsonText() });
+}
+
+export function wireContentTypeJsonSchema(): JsonSchema {
+    const roleKeys = shapeKeys(PLAN_WIRE_SHAPE.roles);
+    const value = shaped(PlanWireEntry.SeedValue, { field: jsonText(), value: jsonAnyOf([jsonText(), jsonListOf(jsonText())]) });
+    return shaped(PlanWireEntry.ContentType, {
+        name: jsonText(),
+        label: jsonText(),
+        roles: shaped(PlanWireEntry.Roles, Object.fromEntries(roleKeys.map(k => [k, jsonText()]))),
+        fields: jsonListOf(wireFieldJsonSchema()),
+        seed: shaped(PlanWireEntry.Seed, { count: jsonInteger(), sample: jsonBoolean(), isPublished: jsonBoolean(), values: jsonListOf(value) }),
+    });
+}
+
+export function wireDataSourceJsonSchema(): JsonSchema {
+    return shaped(PlanWireEntry.DataSource, {
+        alias: jsonText(),
+        type: jsonOneOf(Object.values(PlanDataSourceType)),
+        mode: orNone(Object.values(PlanDataSourceMode)),
+        contentType: jsonText(),
+        limit: jsonInteger(),
+        filterField: jsonText(),
+        routeParam: jsonText(),
+        of: jsonText(),
+        op: orNone(Object.values(RelativeOp)),
+        within: jsonText(),
+    });
+}
+
+export function wireSectionJsonSchema(): JsonSchema {
+    const patterns = sectionPatterns();
+    return shaped(PlanWireEntry.Section, {
+        pattern: jsonOneOf(sectionPatternIds()),
+        slots: jsonListOf(shaped(PlanWireEntry.SlotText, { slot: closedOrText(unique(patterns.flatMap(patternSlots))), text: jsonText() })),
+        links: jsonListOf(shaped(PlanWireEntry.SlotLink, { slot: closedOrText(unique(patterns.flatMap(patternLinkSlots))), route: jsonText() })),
+        binding: jsonText(),
+        without: jsonListOf(closedOrText(unique(patterns.flatMap(patternOptionalParts)))),
+        form: orNone(FORM_PRESETS.map(p => p.id)),
+        enter: orNone(ANIMATE_IDS),
+    });
+}
+
+export function wirePageJsonSchema(): JsonSchema {
+    return shaped(PlanWireEntry.Page, {
+        key: jsonText(),
+        name: jsonText(),
+        route: jsonText(),
+        inNav: jsonBoolean(),
+        archetype: orNone(Object.keys(PAGE_ARCHETYPES)),
+        need: orNone(SITE_NEED_IDS),
+        template: jsonText(),
+        routeSource: jsonText(),
+        seo: shaped(PlanWireEntry.PageSeo, { title: jsonText(), description: jsonText() }),
+        sections: jsonListOf(wireSectionJsonSchema()),
+    });
+}
+
+/** The format a model writes a plan in. The same for every studio and run: nothing in it is pinned. */
+export function planWireJsonSchema(): JsonSchema {
+    const gaps = planWireGaps();
+    if (gaps.length) throw new PlanWireShapeError(`the plan wire neither carries nor derives ${gaps.join(', ')}`);
+    return shaped(PlanWireEntry.Plan, {
+        business: shaped(PlanWireEntry.Business, { name: jsonText(), tagline: jsonText() }),
+        contentTypes: jsonListOf(wireContentTypeJsonSchema()),
+        dataSources: jsonListOf(wireDataSourceJsonSchema()),
+        pages: jsonListOf(wirePageJsonSchema()),
+        globals: shaped(PlanWireEntry.Globals, {
+            [GlobalSlot.Header]: jsonOneOf(globalIds(PatternGlobalPosition.Before)),
+            [GlobalSlot.Footer]: jsonOneOf(globalIds(PatternGlobalPosition.After)),
+        }),
+    });
+}
+
+// ── The wire → the plan ────────────────────────────────────────────────────────────────────────────────────────────
+
+/** What the plan takes from the generation, not from the model. */
+export interface PlanWireContext {
+    design: DesignChoices;
+    source: SitePlanSource;
+    /** The owner's own facts (the analysis's, as corrected), verbatim. */
+    facts?: Readonly<Partial<Record<FactKey, string>>>;
+    locale?: `${SiteLocale}`;
+}
+
+/** A value standing for "absent": `''` (or nothing at all). */
+const isNone = (v: unknown) => v === undefined || v === NONE;
+const optional = (name: string, v: unknown, none: (v: unknown) => boolean = isNone): PlainObject => (none(v) ? {} : { [name]: v });
+const emptyList = (v: unknown) => v === undefined || (Array.isArray(v) && v.length === 0);
+
+/** `[{ <keyName>, <valueName> }]` → `{ key: value }`; anything else is left for the gate to refuse. */
+function listToMap(list: unknown, keyName: string, valueName: string): unknown {
+    if (!Array.isArray(list)) return list;
+    const out: PlainObject = {};
+    for (const entry of list) {
+        if (!isPlainObject(entry) || typeof entry[keyName] !== 'string') return list;
+        out[entry[keyName] as string] = entry[valueName];
+    }
+    return out;
+}
+
+const mapToList = (map: Readonly<Record<string, unknown>> | undefined, keyName: string, valueName: string) =>
+    Object.entries(map ?? {}).map(([k, v]) => ({ [keyName]: k, [valueName]: v }));
+
+const each = (list: unknown, expand: (v: unknown) => unknown) => (Array.isArray(list) ? list.map(expand) : list);
+
+export function expandWireField(wire: unknown): ContentFieldPlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { required, note, ...rest } = wire;
+    return { ...rest, ...optional('required', required, v => v === undefined || v === false), ...optional('note', note) };
+}
+
+export function expandWireContentType(wire: unknown): ContentTypePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { roles, fields, seed, ...rest } = wire;
+    const out: PlainObject = { ...rest, roles: isPlainObject(roles) ? Object.fromEntries(Object.entries(roles).filter(([, v]) => !isNone(v))) : roles, fields: each(fields, expandWireField) };
+    if (!isPlainObject(seed)) return seed === undefined ? out : { ...out, seed };
+    const { values, ...fixed } = seed;
+    if (fixed['count'] === 0 && emptyList(values)) return out;
+    const map = listToMap(values ?? [], 'field', 'value');
+    return { ...out, seed: isPlainObject(map) ? { ...fixed, ...map } : { ...fixed, values } };
+}
+
+export function expandWireDataSource(wire: unknown): DataSourcePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { alias, type, mode, contentType, limit, filterField, routeParam, of, op, within, ...rest } = wire;
+    if (type === PlanDataSourceType.Cms) {
+        const filter = isNone(filterField) && isNone(routeParam) ? {} : { filterByRouteParam: { field: filterField, routeParam } };
+        return { ...rest, alias, type, mode, contentType, ...optional('limit', limit, v => v === undefined || v === 0), ...filter };
+    }
+    if (type === PlanDataSourceType.Relative) return { ...rest, alias, type, of, op, within };
+    return wire;
+}
+
+export function expandWireSection(wire: unknown): PageSectionPlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { slots, links, binding, without, form, enter, ...rest } = wire;
+    return {
+        ...rest,
+        ...optional('slots', listToMap(slots, 'slot', 'text'), v => emptyList(slots) || v === undefined),
+        ...optional('links', listToMap(links, 'slot', 'route'), v => emptyList(links) || v === undefined),
+        ...optional('binding', binding),
+        ...optional('without', without, emptyList),
+        ...optional('form', form),
+        ...optional('enter', enter),
+    };
+}
+
+export function expandWirePage(wire: unknown): PagePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { archetype, need, template, routeSource, seo, sections, ...rest } = wire;
+    const words = isPlainObject(seo) ? { ...optional('title', seo['title']), ...optional('description', seo['description']) } : seo;
+    return {
+        ...rest,
+        ...(wire['route'] === '/' ? { isHome: true } : {}),
+        ...optional('archetype', archetype),
+        ...optional('need', need),
+        ...optional('template', template),
+        ...optional('routeSource', routeSource),
+        ...optional('seo', words, v => v === undefined || (isPlainObject(v) && Object.keys(v).length === 0)),
+        sections: each(sections, expandWireSection),
+    };
+}
+
+function expandWireBusiness(wire: unknown, facts: PlanWireContext['facts']): unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { tagline, ...rest } = wire;
+    return { ...rest, ...optional('tagline', tagline), ...(facts && Object.keys(facts).length ? { facts: { ...facts } } : {}) };
+}
+
+/**
+ * A model's plan (the wire) + what the generation decides (the look, the run, the language, the owner's facts) → the
+ * Site Plan. Pure. Translates, never repairs: whatever the answer got wrong is still wrong, for `validateSitePlan`.
+ */
+export function expandPlanWire(wire: unknown, context: PlanWireContext): SitePlan | unknown {
+    if (!isPlainObject(wire)) return wire;
+    const { business, contentTypes, dataSources, pages, ...rest } = wire;
+    return {
+        ...rest,
+        version: SITE_PLAN_VERSION,
+        source: { ...context.source },
+        business: expandWireBusiness(business, context.facts),
+        ...(context.locale ? { locale: context.locale } : {}),
+        design: { ...context.design },
+        contentTypes: each(contentTypes, expandWireContentType),
+        dataSources: each(dataSources, expandWireDataSource),
+        pages: each(pages, expandWirePage),
+    };
+}
+
+// ── The plan → the wire ────────────────────────────────────────────────────────────────────────────────────────────
+
+export function fieldToWire(field: ContentFieldPlan): PlainObject {
+    return { name: field.name, type: field.type, controller: field.controller, required: field.required ?? false, note: field.note ?? NONE };
+}
+
+export function contentTypeToWire(type: ContentTypePlan): PlainObject {
+    const roles = Object.fromEntries(shapeKeys(PLAN_WIRE_SHAPE.roles).map(role => [role, (type.roles as Readonly<Record<string, string>>)[role] ?? NONE]));
+    const { count = 0, sample = false, isPublished = false, ...values } = type.seed ?? {};
+    return {
+        name: type.name, label: type.label, roles, fields: type.fields.map(fieldToWire),
+        seed: { count, sample, isPublished, values: mapToList(values, 'field', 'value') },
+    };
+}
+
+export function dataSourceToWire(source: DataSourcePlan): PlainObject {
+    const blank = { alias: source.alias, type: source.type, mode: NONE, contentType: NONE, limit: 0, filterField: NONE, routeParam: NONE, of: NONE, op: NONE, within: NONE };
+    if (source.type === PlanDataSourceType.Relative) return { ...blank, of: source.of, op: source.op, within: source.within };
+    return {
+        ...blank, mode: source.mode, contentType: source.contentType, limit: source.limit ?? 0,
+        filterField: source.filterByRouteParam?.field ?? NONE, routeParam: source.filterByRouteParam?.routeParam ?? NONE,
+    };
+}
+
+export function sectionToWire(section: PageSectionPlan): PlainObject {
+    return {
+        pattern: section.pattern, slots: mapToList(section.slots, 'slot', 'text'), links: mapToList(section.links, 'slot', 'route'),
+        binding: section.binding ?? NONE, without: [...(section.without ?? [])], form: section.form ?? NONE, enter: section.enter ?? NONE,
+    };
+}
+
+export function pageToWire(page: PagePlan): PlainObject {
+    return {
+        key: page.key, name: page.name, route: page.route, inNav: page.inNav ?? false, archetype: page.archetype ?? NONE, need: page.need ?? NONE,
+        template: page.template ?? NONE, routeSource: page.routeSource ?? NONE,
+        seo: { title: page.seo?.title ?? NONE, description: page.seo?.description ?? NONE }, sections: page.sections.map(sectionToWire),
+    };
+}
+
+/** The plan → the wire: what a model would have written (the plan edits' prompt shows it; fakes and evals write it). */
+export function planToWire(plan: SitePlan): PlainObject {
+    return {
+        business: { name: plan.business.name, tagline: plan.business.tagline ?? NONE },
+        contentTypes: plan.contentTypes.map(contentTypeToWire),
+        dataSources: plan.dataSources.map(dataSourceToWire),
+        pages: plan.pages.map(pageToWire),
+        globals: { ...plan.globals },
+    };
+}

package/src/generation-core/public-api.ts

@@ -27,7 +27,8 @@ export * from './plan-data';
 export * from './showcase';
 export * from './site-build-run';
 export * from './ai-run';
-export * from './site-plan-schema';
+export * from './plan-wire';
+export * from './strict-schema';
 export * from './plan-edits';
 export * from './plan-words';
 export * from './audit-site';

package/src/generation-core/stock-photos.ts

@@ -8,31 +8,63 @@ import { SitePlan } from './site-plan.model';
  * into the studio's own storage (never hot-linked), placed only in an EMPTY picture slot of a section that may show
  * one — never the owner's work (a collection, a detail page, a gallery: what the nine portfolio types sell is theirs),
  * never a person (testimonials, the team), never anywhere when the business type says `stock: false`. Its alt text is
- * the provider's description of what it shows (never a claim), and the credit line its licence requires is placed in
- * the footer. Pure: the build step does the copying.
+ * the provider's description of what it shows (never a claim), and the credit line its licence requires — when it
+ * requires one — is placed in the footer. Pure: the build step does the copying.
  */
 
 /** Where a stock photo comes from (the library's provider). */
 export enum StockProviderId {
     Magnific = 'magnific',
+    Pixabay = 'pixabay',
 }
 
-/** What a picture's licence asks of the site that shows it. */
+/** Words and the address they link to. */
+export interface StockLink {
+    line: string;
+    url: string;
+}
+
+/** What a provider's terms ask of IOX, per provider — the ONE place a credit line is decided. */
+export interface StockProviderTerms {
+    name: string;
+    /** The line a site showing one of its pictures must carry (in the footer), or null when its licence asks none. */
+    credit: StockLink | null;
+    /** What to show wherever its SEARCH RESULTS are displayed — the operator's review of the library, never a site. */
+    sourceNotice: StockLink;
+}
+
+/**
+ * The providers' terms (AI plan §3g, I2; read 2026-10-25 / 2026-10-27). Magnific's free licence requires "Designed by
+ * Magnific", linked, next to the resource or in the site's footer. Pixabay's Content License: "You do not need to credit
+ * Pixabay or the contributor" — but its API asks to "show your users where the images and videos are from, whenever
+ * search results are displayed", which only the operator's review does.
+ */
+export const STOCK_PROVIDER_TERMS: Readonly<Record<StockProviderId, StockProviderTerms>> = {
+    [StockProviderId.Magnific]: {
+        name: 'Magnific',
+        credit: { line: 'Designed by Magnific', url: 'https://www.magnific.com' },
+        sourceNotice: { line: 'Designed by Magnific', url: 'https://www.magnific.com' },
+    },
+    [StockProviderId.Pixabay]: {
+        name: 'Pixabay',
+        credit: null,
+        sourceNotice: { line: 'Images from Pixabay', url: 'https://pixabay.com/' },
+    },
+};
+
+/** Where a picture came from and under which licence — recorded with every library photo and every studio copy. */
 export interface StockCredit {
     provider: `${StockProviderId}`;
     /** The provider's id of the picture. */
     resourceId: string;
     /** The provider's page for it. */
     sourceUrl: string;
-    /** The provider's own title — what the picture shows. */
+    /** The provider's own words for what the picture shows (Magnific's title, Pixabay's tags). */
     title: string;
     author: string;
-    /** `freemium` — the free licence (premium pictures never enter the library). */
+    /** The licence it is used under, as the provider names it (Magnific `freemium`, Pixabay `content-license`). */
     licence: string;
     licenceUrl: string;
-    /** The words the licence requires, and where they link. */
-    line: string;
-    lineUrl: string;
 }
 
 /** One picture of the platform library (`iox-stock/<type>/`), as its manifest lists it. */
@@ -105,10 +137,18 @@ export function applyStockPhotos(trees: ReadonlyArray<SerializedNode>, placed: R
     return changed;
 }
 
-/** The credit lines a set of photos needs — one per distinct line (a free Magnific photo: "Designed by Magnific"). */
-export function stockCreditLines(photos: ReadonlyArray<Pick<StockPhoto, 'credit'>>): Array<{ line: string; url: string }> {
+/** The line a picture's licence requires on the site, or null when it requires none (`STOCK_PROVIDER_TERMS`). */
+export function stockCreditLine(credit: Pick<StockCredit, 'provider'>): StockLink | null {
+    return STOCK_PROVIDER_TERMS[credit.provider as StockProviderId]?.credit ?? null;
+}
+
+/** The credit lines a set of photos needs — one per distinct line, none for a provider whose licence asks none. */
+export function stockCreditLines(photos: ReadonlyArray<Pick<StockPhoto, 'credit'>>): StockLink[] {
     const seen = new Map<string, string>();
-    for (const p of photos) if (!seen.has(p.credit.line)) seen.set(p.credit.line, p.credit.lineUrl);
+    for (const p of photos) {
+        const credit = stockCreditLine(p.credit);
+        if (credit && !seen.has(credit.line)) seen.set(credit.line, credit.url);
+    }
     return [...seen.entries()].map(([line, url]) => ({ line, url }));
 }
 
@@ -119,12 +159,12 @@ export const stockCreditNodeId = (index: number) => `stock-credit-${index + 1}`;
  * The credit line, as the builder would create a Link (a plain node the owner may move or restyle): the licence's words,
  * linking where it asks, opening in a new tab. Placed at the end of the footer — the place the licence names for a site.
  */
-export function stockCreditNode(index: number, credit: { line: string; url: string }): SerializedNode {
+export function stockCreditNode(index: number, credit: StockLink): SerializedNode {
     return createSerializedNode(stockCreditNodeId(index), 'Link', { label: credit.line, linkType: 'external', url: credit.url, target: '_blank' }, 'link');
 }
 
 /** Append the credit lines to the footer root (once each). Returns how many it added. */
-export function addStockCredits(footer: SerializedNode, credits: ReadonlyArray<{ line: string; url: string }>): number {
+export function addStockCredits(footer: SerializedNode, credits: ReadonlyArray<StockLink>): number {
     footer.children ??= [];
     let added = 0;
     credits.forEach((credit, i) => {