@vectoriox/iox-ui 5.55.0 → 5.56.0

package/src/generation-core/audit-site.ts

@@ -0,0 +1,386 @@
+import { ELEMENT_ACTION_DESCRIPTORS, resolveActionAvailability } from '@vectoriox/iox-ui/actions-core';
+import { auditDesignContrast, DesignTokenLike } from '@vectoriox/iox-ui/design-core';
+import { collectFormSpec, ControlType, FIELD_NODE_TYPE, FORM_NODE_TYPE } from '@vectoriox/iox-ui/forms-core';
+
+import { blocksPublish, ComposedPlaceholder, PlaceholderKind } from './compose-site';
+import { navShapeOf } from './nav-shape';
+import { PatternGlobalPosition } from './patterns';
+import { SerializedNode, walkSerialized } from './serialized-node';
+
+/**
+ * THE Publishable gate (AI plan §3e, M1-7): ONE pure function over a snapshot of a site — its pages, globals, the
+ * connectors' health, the look's token rows, what a build left to fill — run by the Publish dialog, the builder's
+ * Needs attention and the server on publish (iox-cms refuses with the same findings). Works on any site, generated
+ * or hand-built. Severity is decision D8: an unfilled fact, a policy placeholder or an action that points at nothing
+ * BLOCKS; samples, copy placeholders and stock photos ASK ("Publish anyway"); the rest WARN. Design advice
+ * (harness-core `lintDesign`) is not one of the eight — the caller adds it, and it never blocks.
+ */
+
+export enum SiteCheckId {
+    Navigation = 'navigation',
+    Forms = 'forms',
+    Consent = 'consent',
+    Seo = 'seo',
+    Facts = 'facts',
+    Accessibility = 'accessibility',
+    Tokens = 'tokens',
+    Actions = 'actions',
+}
+
+/** The eight, in §3e's order. */
+export const SITE_CHECKS: ReadonlyArray<SiteCheckId> = Object.values(SiteCheckId);
+
+export enum CheckSeverity {
+    Block = 'block',
+    Ask = 'ask',
+    Warn = 'warn',
+}
+
+export enum SiteFindingCode {
+    NoHeader = 'no-header',
+    NoPhoneMenu = 'no-phone-menu',
+    FormWithoutId = 'form-without-id',
+    EmailNeedsMailer = 'email-needs-mailer',
+    TrackerWithoutBanner = 'tracker-without-banner',
+    NoTitle = 'no-title',
+    NoDescription = 'no-description',
+    UnfilledFact = 'unfilled-fact',
+    CopyPlaceholder = 'copy-placeholder',
+    SampleItems = 'sample-items',
+    StockPhoto = 'stock-photo',
+    NoPrivacyPage = 'no-privacy-page',
+    PrivacyPagePlaceholder = 'privacy-page-placeholder',
+    LowContrast = 'low-contrast',
+    HeadingOrder = 'heading-order',
+    ImageWithoutAlt = 'image-without-alt',
+    LiteralColour = 'literal-colour',
+    DeadLink = 'dead-link',
+    DeadDialogTarget = 'dead-dialog-target',
+    ActionNeedsConnector = 'action-needs-connector',
+}
+
+/** Each finding's severity — one table (D8), never decided at a call site. */
+export const FINDING_SEVERITY: Readonly<Record<SiteFindingCode, CheckSeverity>> = {
+    [SiteFindingCode.NoHeader]: CheckSeverity.Warn,
+    [SiteFindingCode.NoPhoneMenu]: CheckSeverity.Warn,
+    [SiteFindingCode.FormWithoutId]: CheckSeverity.Block,
+    [SiteFindingCode.EmailNeedsMailer]: CheckSeverity.Warn,
+    [SiteFindingCode.TrackerWithoutBanner]: CheckSeverity.Warn,
+    [SiteFindingCode.NoTitle]: CheckSeverity.Warn,
+    [SiteFindingCode.NoDescription]: CheckSeverity.Warn,
+    [SiteFindingCode.UnfilledFact]: CheckSeverity.Block,
+    [SiteFindingCode.CopyPlaceholder]: CheckSeverity.Ask,
+    [SiteFindingCode.SampleItems]: CheckSeverity.Ask,
+    [SiteFindingCode.StockPhoto]: CheckSeverity.Ask,
+    [SiteFindingCode.NoPrivacyPage]: CheckSeverity.Ask,
+    [SiteFindingCode.PrivacyPagePlaceholder]: CheckSeverity.Block,
+    [SiteFindingCode.LowContrast]: CheckSeverity.Warn,
+    [SiteFindingCode.HeadingOrder]: CheckSeverity.Warn,
+    [SiteFindingCode.ImageWithoutAlt]: CheckSeverity.Warn,
+    [SiteFindingCode.LiteralColour]: CheckSeverity.Warn,
+    [SiteFindingCode.DeadLink]: CheckSeverity.Block,
+    [SiteFindingCode.DeadDialogTarget]: CheckSeverity.Block,
+    [SiteFindingCode.ActionNeedsConnector]: CheckSeverity.Block,
+};
+
+const CHECK_OF: Readonly<Record<SiteFindingCode, SiteCheckId>> = {
+    [SiteFindingCode.NoHeader]: SiteCheckId.Navigation,
+    [SiteFindingCode.NoPhoneMenu]: SiteCheckId.Navigation,
+    [SiteFindingCode.FormWithoutId]: SiteCheckId.Forms,
+    [SiteFindingCode.EmailNeedsMailer]: SiteCheckId.Forms,
+    [SiteFindingCode.TrackerWithoutBanner]: SiteCheckId.Consent,
+    [SiteFindingCode.NoTitle]: SiteCheckId.Seo,
+    [SiteFindingCode.NoDescription]: SiteCheckId.Seo,
+    [SiteFindingCode.UnfilledFact]: SiteCheckId.Facts,
+    [SiteFindingCode.CopyPlaceholder]: SiteCheckId.Facts,
+    [SiteFindingCode.SampleItems]: SiteCheckId.Facts,
+    [SiteFindingCode.StockPhoto]: SiteCheckId.Facts,
+    [SiteFindingCode.NoPrivacyPage]: SiteCheckId.Facts,
+    [SiteFindingCode.PrivacyPagePlaceholder]: SiteCheckId.Facts,
+    [SiteFindingCode.LowContrast]: SiteCheckId.Accessibility,
+    [SiteFindingCode.HeadingOrder]: SiteCheckId.Accessibility,
+    [SiteFindingCode.ImageWithoutAlt]: SiteCheckId.Accessibility,
+    [SiteFindingCode.LiteralColour]: SiteCheckId.Tokens,
+    [SiteFindingCode.DeadLink]: SiteCheckId.Actions,
+    [SiteFindingCode.DeadDialogTarget]: SiteCheckId.Actions,
+    [SiteFindingCode.ActionNeedsConnector]: SiteCheckId.Actions,
+};
+
+export interface SiteFinding {
+    check: SiteCheckId;
+    severity: CheckSeverity;
+    code: SiteFindingCode;
+    /** In plain words, for the screen. */
+    message: string;
+    pageId?: string;
+    nodeId?: string;
+    /** The global slot (`header` / `footer`) when it is in a global. */
+    owner?: string;
+}
+
+export interface SiteCheck {
+    id: SiteCheckId;
+    passed: boolean;
+    findings: SiteFinding[];
+}
+
+export interface SiteAudit {
+    checks: SiteCheck[];
+    blocking: number;
+    asking: number;
+}
+
+/** A page as the gate reads it. */
+export interface AuditPage {
+    id: string;
+    name: string;
+    route: string;
+    layout: ReadonlyArray<SerializedNode>;
+    seo?: unknown;
+}
+
+/** A placeholder a build left, and whether the node still shows it (the caller compares the node's text). */
+export interface AuditPlaceholder extends ComposedPlaceholder {
+    pageId?: string;
+    filled: boolean;
+}
+
+export interface SiteAuditSnapshot {
+    pages: ReadonlyArray<AuditPage>;
+    globals: ReadonlyArray<SerializedNode>;
+    /** Connector type → usable (configured or provided, and healthy). */
+    connectors: Readonly<Record<string, boolean>>;
+    /** Connector types that set a tracker (a consent category) and are configured. */
+    trackers?: ReadonlyArray<string>;
+    /** The look's token rows and the mode(s) the site wears. */
+    design?: { rows: ReadonlyArray<DesignTokenLike>; modes: ReadonlyArray<'light' | 'dark'> } | null;
+    placeholders?: ReadonlyArray<AuditPlaceholder>;
+    /** Sample items still in the site (`isSample`). */
+    samples?: ReadonlyArray<{ contentType: string; id: string; label?: string }>;
+    /** Stock photos a build placed that are still on the page. */
+    stock?: ReadonlyArray<{ nodeId: string; pageId?: string; owner?: string }>;
+}
+
+export interface SiteAuditOptions {
+    /** Audit as if only this page were being published (its own page checks + every site-wide one). */
+    pageId?: string;
+}
+
+const LINKING_TYPES = new Set(['Link', 'Heading', 'Button', 'ButtonBlock', 'LinkedContainer', 'Image']);
+const PAGE_LINK = 'page';
+const PERSONAL_CONTROLS: ReadonlySet<string> = new Set([ControlType.Email, ControlType.Tel, ControlType.Text, ControlType.Textarea]);
+const PRIVACY_PAGE = /privacy|פרטיות|מדיניות/i;
+const MAILER = 'mailer';
+const EMAIL_DELIVERY = 'email';
+const LITERAL_COLOUR = /#[0-9a-f]{3,8}\b|rgba?\(|hsla?\(/i;
+const COLOUR_TRAITS = /color|Color|^background$|boxShadow|textShadow/;
+const HEADING_LEVEL = /^h([1-6])$/;
+const DIALOG_TYPE = 'Dialog';
+const SELF = 'self';
+
+/** A route pattern (`/work/:slug`) matches a concrete path (`/work/blue-bowl`). */
+export function routeMatches(pattern: string, path: string): boolean {
+    const a = pattern.split('/').filter(Boolean);
+    const b = String(path ?? '').split(/[?#]/)[0].split('/').filter(Boolean);
+    return a.length === b.length && a.every((seg, i) => seg.startsWith(':') || seg === b[i]);
+}
+
+const nonEmpty = (v: unknown) => typeof v === 'string' && v.trim() !== '';
+
+/** A stored SEO field (a string, or `{ override, binding, auto }`) has a value, or may be derived. */
+function seoField(raw: unknown, derivable: boolean): boolean {
+    if (nonEmpty(raw)) return true;
+    if (raw && typeof raw === 'object') {
+        const v = raw as { override?: unknown; binding?: unknown; auto?: unknown };
+        if (nonEmpty(v.override) || v.binding) return true;
+        if (v.auto === false) return false;
+    }
+    return derivable;
+}
+
+function hasContent(layout: ReadonlyArray<SerializedNode>, type: string): boolean {
+    let found = false;
+    walkSerialized(layout, n => {
+        if (n.type !== type || found) return;
+        found = nonEmpty(n.props['content']) || n.bindings.some(b => b.prop === 'content');
+    });
+    return found;
+}
+
+interface Ctx {
+    out: SiteFinding[];
+    routes: string[];
+    nodeIds: Map<string, string>;
+}
+
+function add(ctx: Ctx, code: SiteFindingCode, message: string, where: { pageId?: string; nodeId?: string; owner?: string } = {}): void {
+    ctx.out.push({ check: CHECK_OF[code], severity: FINDING_SEVERITY[code], code, message, ...where });
+}
+
+/** Every node of a page or a global, with where it lives. */
+function eachNode(snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>, visit: (n: SerializedNode, where: { pageId?: string; owner?: string }) => void): void {
+    for (const page of pages) walkSerialized(page.layout, n => visit(n, { pageId: page.id }));
+    for (const global of snapshot.globals) {
+        const owner = global.globalPosition === PatternGlobalPosition.Before ? 'header' : 'footer';
+        walkSerialized([global], n => visit(n, { owner }));
+    }
+}
+
+function checkNavigation(ctx: Ctx, snapshot: SiteAuditSnapshot): void {
+    const header = snapshot.globals.find(g => g.globalPosition === PatternGlobalPosition.Before);
+    if (!header) return add(ctx, SiteFindingCode.NoHeader, 'The site has no header, so visitors have no menu to move around with.');
+    if (!navShapeOf(snapshot.globals)) add(ctx, SiteFindingCode.NoPhoneMenu, 'The header has no phone menu — on a phone its links are hard to reach.', { owner: 'header', nodeId: header.id });
+}
+
+function checkForms(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>): boolean {
+    let personal = false;
+    eachNode(snapshot, pages, (n, where) => {
+        if (n.type !== FORM_NODE_TYPE) return;
+        const spec = collectFormSpec(n as never);
+        if (!spec || !nonEmpty(spec.formId)) add(ctx, SiteFindingCode.FormWithoutId, 'A form has no id, so what visitors send is never stored.', { ...where, nodeId: n.id });
+        if (spec?.actions.some(a => a.type === EMAIL_DELIVERY) && snapshot.connectors[MAILER] !== true) {
+            add(ctx, SiteFindingCode.EmailNeedsMailer, 'A form emails what visitors send, but Email is not connected — it is stored and never sent.', { ...where, nodeId: n.id });
+        }
+        walkSerialized(n.children ?? [], f => {
+            if (f.type === FIELD_NODE_TYPE && PERSONAL_CONTROLS.has(String(f.props['control'] ?? ControlType.Text))) personal = true;
+        });
+    });
+    return personal;
+}
+
+function checkConsent(ctx: Ctx, snapshot: SiteAuditSnapshot): void {
+    if (!snapshot.trackers?.length) return;
+    let banner = false;
+    for (const g of snapshot.globals) walkSerialized([g], n => { if (n.type === DIALOG_TYPE && n.props['consentRole'] === true) banner = true; });
+    if (!banner) add(ctx, SiteFindingCode.TrackerWithoutBanner, `${snapshot.trackers.join(', ')} is connected, but the site has no cookie banner — it stays off for every visitor.`);
+}
+
+function checkSeo(ctx: Ctx, pages: ReadonlyArray<AuditPage>): void {
+    for (const page of pages) {
+        const seo = (page.seo ?? {}) as Record<string, unknown>;
+        if (!seoField(seo['title'], hasContent(page.layout, 'Heading'))) add(ctx, SiteFindingCode.NoTitle, `"${page.name}" has no title for search results.`, { pageId: page.id });
+        if (!seoField(seo['description'], hasContent(page.layout, 'Text'))) add(ctx, SiteFindingCode.NoDescription, `"${page.name}" has no description for search results.`, { pageId: page.id });
+    }
+}
+
+function checkFacts(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>, personal: boolean): void {
+    const inScope = (p: { pageId?: string }) => !p.pageId || pages.some(page => page.id === p.pageId);
+    for (const p of (snapshot.placeholders ?? []).filter(p => !p.filled && inScope(p))) {
+        const where = { pageId: p.pageId, nodeId: p.nodeId, ...(p.pageId ? {} : { owner: p.owner }) };
+        if (blocksPublish(p.kind)) add(ctx, SiteFindingCode.UnfilledFact, `"${p.text || p.fact || p.kind}" is still blank — fill it in before the site goes live.`, where);
+        else if (p.kind === PlaceholderKind.Copy) add(ctx, SiteFindingCode.CopyPlaceholder, 'Some words are still the template\'s.', where);
+    }
+    for (const s of snapshot.samples ?? []) add(ctx, SiteFindingCode.SampleItems, `"${s.label ?? s.id}" is a sample — replace or remove it.`, { nodeId: s.id });
+    for (const s of (snapshot.stock ?? []).filter(inScope)) add(ctx, SiteFindingCode.StockPhoto, 'A stock photo stands in for one of yours.', { pageId: s.pageId, nodeId: s.nodeId, owner: s.owner });
+    if (!personal) return;
+    const privacy = snapshot.pages.find(p => PRIVACY_PAGE.test(p.route) || PRIVACY_PAGE.test(p.name));
+    if (!privacy) return add(ctx, SiteFindingCode.NoPrivacyPage, 'A form asks for personal details, and the site has no privacy page saying what you do with them.');
+    if ((snapshot.placeholders ?? []).some(p => p.pageId === privacy.id && !p.filled)) {
+        add(ctx, SiteFindingCode.PrivacyPagePlaceholder, 'The privacy page still holds template words — only you can write it.', { pageId: privacy.id });
+    }
+}
+
+function checkAccessibility(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>): void {
+    for (const mode of snapshot.design?.modes ?? []) {
+        const failing = auditDesignContrast(snapshot.design!.rows, mode).filter(f => !f.pass);
+        if (failing.length) add(ctx, SiteFindingCode.LowContrast, `${failing.length} text and background pair(s) are hard to read in ${mode} mode.`);
+    }
+    for (const page of pages) {
+        let last = 0;
+        let h1 = 0;
+        walkSerialized(page.layout, n => {
+            const level = n.type === 'Heading' ? HEADING_LEVEL.exec(String(n.props['level'] ?? ''))?.[1] : undefined;
+            if (!level) return;
+            const l = Number(level);
+            if (l === 1) h1++;
+            if (last && l > last + 1) add(ctx, SiteFindingCode.HeadingOrder, `A heading on "${page.name}" skips a level (h${last} → h${l}).`, { pageId: page.id, nodeId: n.id });
+            last = l;
+        });
+        if (h1 > 1) add(ctx, SiteFindingCode.HeadingOrder, `"${page.name}" has ${h1} main headings (h1); one is clearer.`, { pageId: page.id });
+    }
+    eachNode(snapshot, pages, (n, where) => {
+        if (n.type !== 'Image') return;
+        const decorative = n.props['alt'] === '' && n.props['decorative'] === true;
+        const bound = n.bindings.some(b => b.prop === 'alt');
+        if (!decorative && !bound && !nonEmpty(n.props['alt'])) add(ctx, SiteFindingCode.ImageWithoutAlt, 'A picture has no description for people who cannot see it.', { ...where, nodeId: n.id });
+    });
+}
+
+function checkTokens(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>): void {
+    eachNode(snapshot, pages, (n, where) => {
+        if (!n.elementStyle) return;
+        const maps: Array<Record<string, unknown> | undefined> = [n.styleProps, ...Object.values(n.stateStyles ?? {}), ...Object.values(n.responsive ?? {}).map(l => l?.styleProps)];
+        const literal = maps.some(map => Object.entries(map ?? {}).some(([k, v]) =>
+            COLOUR_TRAITS.test(k) && LITERAL_COLOUR.test(String(v)) && !(k === 'borderColor' && n.styleProps['borderWidth'] === '0px')));
+        if (literal) add(ctx, SiteFindingCode.LiteralColour, 'An element paints a fixed colour, so a new look will not reach it.', { ...where, nodeId: n.id });
+    });
+}
+
+function checkActions(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>): void {
+    const routeExists = (route: unknown) => typeof route === 'string' && ctx.routes.some(r => routeMatches(r, route));
+    eachNode(snapshot, pages, (n, where) => {
+        if (LINKING_TYPES.has(n.type) && n.props['linkType'] === PAGE_LINK && !routeExists(n.props['pageRoute'])) {
+            add(ctx, SiteFindingCode.DeadLink, `"${String(n.props['label'] ?? n.props['content'] ?? n.label ?? n.type)}" links to ${String(n.props['pageRoute'] || 'no page')}, which is not a page of the site.`, { ...where, nodeId: n.id });
+        }
+        for (const ix of (n.interactions ?? []) as Array<{ actions?: Array<{ type?: string; target?: string; params?: Record<string, unknown>; disabled?: boolean }> }>) {
+            for (const action of ix?.actions ?? []) {
+                if (!action || action.disabled) continue;
+                const descriptor = ELEMENT_ACTION_DESCRIPTORS.find(d => d.type === action.type);
+                if (!descriptor) continue;
+                const types = descriptor.target?.types;
+                if (descriptor.target?.required && action.target !== SELF) {
+                    const targetType = action.target ? ctx.nodeIds.get(action.target) : undefined;
+                    if (!targetType || (types && !types.includes(targetType))) {
+                        add(ctx, SiteFindingCode.DeadDialogTarget, `"${n.label ?? n.type}" opens something that is no longer on the site.`, { ...where, nodeId: n.id });
+                    }
+                }
+                if (action.type === 'navigate' && action.params?.['navigateTo'] === PAGE_LINK && !routeExists(action.params?.['page'])) {
+                    add(ctx, SiteFindingCode.DeadLink, `"${n.label ?? n.type}" goes to a page the site does not have.`, { ...where, nodeId: n.id });
+                }
+                // A connector the snapshot does not say is usable is not: unknown is never "fine".
+                const connectors = descriptor.connector ? { [descriptor.connector]: snapshot.connectors[descriptor.connector] === true } : {};
+                const availability = resolveActionAvailability(descriptor, { connectors });
+                if (availability.state === 'connector-missing') {
+                    add(ctx, SiteFindingCode.ActionNeedsConnector, `"${n.label ?? n.type}" needs ${availability.connector} connected.`, { ...where, nodeId: n.id });
+                }
+            }
+        }
+    });
+}
+
+/** Run the eight checks. `pageId` narrows the page checks to the page being published; site-wide ones always run. */
+export function auditSite(snapshot: SiteAuditSnapshot, options: SiteAuditOptions = {}): SiteAudit {
+    const pages = options.pageId ? snapshot.pages.filter(p => p.id === options.pageId) : snapshot.pages;
+    const nodeIds = new Map<string, string>();
+    eachNode(snapshot, snapshot.pages, n => nodeIds.set(n.id, n.type));
+    const ctx: Ctx = { out: [], routes: snapshot.pages.map(p => p.route), nodeIds };
+    checkNavigation(ctx, snapshot);
+    const personal = checkForms(ctx, snapshot, pages);
+    checkConsent(ctx, snapshot);
+    checkSeo(ctx, pages);
+    checkFacts(ctx, snapshot, pages, personal);
+    checkAccessibility(ctx, snapshot, pages);
+    checkTokens(ctx, snapshot, pages);
+    checkActions(ctx, snapshot, pages);
+    const checks = SITE_CHECKS.map(id => {
+        const findings = ctx.out.filter(f => f.check === id);
+        return { id, passed: !findings.some(f => f.severity !== CheckSeverity.Warn), findings };
+    });
+    return {
+        checks,
+        blocking: ctx.out.filter(f => f.severity === CheckSeverity.Block).length,
+        asking: ctx.out.filter(f => f.severity === CheckSeverity.Ask).length,
+    };
+}
+
+/** What a publish request must acknowledge: every ASK finding's code (a BLOCK cannot be acknowledged). */
+export function requiredAcknowledgements(audit: SiteAudit): SiteFindingCode[] {
+    return [...new Set(audit.checks.flatMap(c => c.findings).filter(f => f.severity === CheckSeverity.Ask).map(f => f.code))];
+}
+
+/** The publish verdict: blocked (never acknowledgeable), needs these acknowledgements, or free to go. */
+export function publishVerdict(audit: SiteAudit, acknowledged: ReadonlyArray<string> = []): { ok: boolean; blocked: boolean; missing: SiteFindingCode[] } {
+    const missing = requiredAcknowledgements(audit).filter(code => !acknowledged.includes(code));
+    const blocked = audit.blocking > 0;
+    return { ok: !blocked && missing.length === 0, blocked, missing };
+}

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

@@ -29,3 +29,5 @@ export * from './ai-run';
 export * from './site-plan-schema';
 export * from './plan-edits';
 export * from './plan-words';
+export * from './audit-site';
+export * from './stock-photos';

package/src/generation-core/site-build-run.ts

@@ -29,6 +29,8 @@ export enum BuildStep {
     Preflight = 'preflight',
     ContentTypes = 'content-types',
     SampleImages = 'sample-images',
+    /** I2: the curated stock photos the plan's empty picture slots take, copied into the studio (never hot-linked). */
+    StockPhotos = 'stock-photos',
     Items = 'items',
     DataSources = 'data-sources',
     Pages = 'pages',
@@ -51,6 +53,8 @@ export enum CreatedKind {
     /** Fields the build added to a content type it found (types are shared by every organization of a studio). */
     ContentTypeFields = 'content-type-fields',
     SampleImage = 'sample-image',
+    /** A stock photo copied into the studio's storage (`media/stock/…`), with its assets row. */
+    StockPhoto = 'stock-photo',
     Item = 'item',
     DataSource = 'data-source',
     Page = 'page',
@@ -120,6 +124,8 @@ export enum BuildNoticeCode {
     NoStorage = 'no-storage',
     /** A content type the build reuses is not public in this studio: the site will not show its items. */
     ContentTypeNotPublic = 'content-type-not-public',
+    /** The stock library could not be read: the picture slots keep the empty box, and the run says so. */
+    StockUnavailable = 'stock-unavailable',
 }
 
 export interface BuildNotice {
@@ -195,6 +201,7 @@ export const buildKeys = {
     contentTypeFields: (name: string) => `schema-fields:${name}`,
     item: (contentType: string, n: number) => `item:${contentType}:${n}`,
     sampleImage: (n: number) => `sample-image:${n}`,
+    stockPhoto: (libraryKey: string) => `stock-photo:${libraryKey}`,
     dataSource: (alias: string) => `data-source:${alias}`,
     page: (key: string) => `page:${key}`,
     global: (nodeId: string) => `global:${nodeId}`,

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

@@ -0,0 +1,137 @@
+import { ComposedSite, PlaceholderKind } from './compose-site';
+import { patternById } from './patterns';
+import { createSerializedNode, SerializedNode, walkSerialized } from './serialized-node';
+import { SitePlan } from './site-plan.model';
+
+/**
+ * Stock photos in a built site (AI plan §3g / §3m, I2): a FREE picture from the platform's curated library, copied
+ * 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.
+ */
+
+/** Where a stock photo comes from (the library's provider). */
+export enum StockProviderId {
+    Magnific = 'magnific',
+}
+
+/** What a picture's licence asks of the site that shows it. */
+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. */
+    title: string;
+    author: string;
+    /** `freemium` — the free licence (premium pictures never enter the library). */
+    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. */
+export interface StockPhoto {
+    /** The library key (`spa/12345.jpg`) — the copy's file name is derived from it. */
+    key: string;
+    /** Where the build downloads it from (the platform bucket). */
+    url: string;
+    /** What it shows, in the provider's words — the alt text. Never a claim. */
+    alt: string;
+    width?: number;
+    height?: number;
+    credit: StockCredit;
+}
+
+/** The section families a stock photo may stand in for a picture in. */
+export const STOCK_FAMILIES: ReadonlySet<string> = new Set(['hero', 'feature', 'content', 'story', 'cta', 'contact', 'header']);
+
+export interface StockSlot {
+    /** The Image node the photo goes into. */
+    nodeId: string;
+    /** The page key it lives on. */
+    owner: string;
+    pattern: string;
+}
+
+/** The empty picture slots of a composed site a stock photo may fill, in page and section order. */
+export function stockSlots(plan: SitePlan, composed: Pick<ComposedSite, 'pages' | 'placeholders'>): StockSlot[] {
+    const empty = new Set(composed.placeholders.filter(p => p.kind === PlaceholderKind.Image).map(p => p.nodeId));
+    const out: StockSlot[] = [];
+    composed.pages.forEach((page, p) => {
+        page.layout.forEach((root, s) => {
+            const pattern = plan.pages[p]?.sections[s]?.pattern;
+            const family = patternById(pattern)?.family;
+            if (!pattern || !family || !STOCK_FAMILIES.has(family)) return;
+            walkSerialized([root], n => {
+                if (n.type === 'Image' && empty.has(n.id) && !n.bindings.length) out.push({ nodeId: n.id, owner: page.key, pattern });
+            });
+        });
+    });
+    return out;
+}
+
+export interface StockPlacement extends StockSlot {
+    photo: StockPhoto;
+}
+
+/** Which photo goes where: the library's photos in order, one per slot, never twice; none when the type says no stock. */
+export function planStockPhotos(slots: ReadonlyArray<StockSlot>, photos: ReadonlyArray<StockPhoto>, stockAllowed: boolean): StockPlacement[] {
+    if (!stockAllowed) return [];
+    return slots.slice(0, photos.length).map((slot, i) => ({ ...slot, photo: photos[i] }));
+}
+
+/** A placed photo's copy in the studio's storage: the key the build writes it under. */
+export function stockCopyKey(photo: Pick<StockPhoto, 'key'>): string {
+    return `media/stock/${photo.key.replace(/[^a-zA-Z0-9._-]+/g, '-')}`;
+}
+
+/** Put the studio's copy of each photo into its slot (src + the provider's alt). Returns the nodes changed. */
+export function applyStockPhotos(trees: ReadonlyArray<SerializedNode>, placed: ReadonlyArray<{ nodeId: string; url: string; alt: string }>): number {
+    const byId = new Map(placed.map(p => [p.nodeId, p]));
+    let changed = 0;
+    walkSerialized(trees, n => {
+        const p = byId.get(n.id);
+        if (!p || n.type !== 'Image') return;
+        n.props['src'] = p.url;
+        n.props['alt'] = p.alt;
+        changed++;
+    });
+    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 }> {
+    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);
+    return [...seen.entries()].map(([line, url]) => ({ line, url }));
+}
+
+/** The footer node id of a credit line (stable — a build that runs twice finds it). */
+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 {
+    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 {
+    footer.children ??= [];
+    let added = 0;
+    credits.forEach((credit, i) => {
+        const id = stockCreditNodeId(i);
+        if (footer.children!.some(c => c.id === id)) return;
+        footer.children!.push(stockCreditNode(i, credit));
+        added++;
+    });
+    return added;
+}

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

@@ -22,3 +22,4 @@ export * from './palette';
 export * from './reference-colour';
 export * from './site-reading';
 export * from './generation-view';
+export * from './starting-design';

package/src/harness-core/starting-design.ts

@@ -0,0 +1,44 @@
+import { DesignChoices, presetChoices } from '@vectoriox/iox-ui/design-core';
+
+import { motionFor, MotionInput } from './motion';
+import { RankInput, rankWithReferences, StyleRead } from './rank';
+import { referenceSeed } from './reference-colour';
+
+/**
+ * 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. */
+export function presetDesign(
+    presetId: string,
+    input: MotionInput | string | null,
+    kept: Partial<Pick<DesignChoices, 'scroll' | 'animate' | 'between' | 'motion'>> = {},
+    read: StyleRead | null = null,
+): DesignChoices | null {
+    const base = presetChoices(presetId);
+    if (!base) return null;
+    const motionInput: MotionInput = typeof input === 'string' || input === null ? { businessType: input } : input;
+    const start = motionFor(motionInput, presetId, read);
+    return { ...base, scroll: start.scroll, animate: start.animate, between: start.between, ...kept };
+}
+
+export 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. */
+export function startingDesign(input: (RankInput & MotionInput) | string | null, read: StyleRead | null = null): StartingDesign | null {
+    const rankInput: RankInput & MotionInput = typeof input === 'string' || input === null ? { businessType: input } : input;
+    const top = rankWithReferences(rankInput, read)[0];
+    const design = top ? presetDesign(top.id, rankInput, {}, read) : null;
+    if (!top || !design) return null;
+    const seed = referenceSeed(read, top.id);
+    return seed?.used ? { presetId: top.id, design: { ...design, seed: seed.seed }, referenceColour: true } : { presetId: top.id, design, referenceColour: false };
+}