@vectoriox/iox-ui 5.66.0 → 5.67.0

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

@@ -1,13 +1,19 @@
-import { ComposedSite, PlaceholderKind } from './compose-site';
+import { ComposedSite, parseSampleImageRef, PlaceholderKind } from './compose-site';
 import { patternById } from './patterns';
 import { createSerializedNode, SerializedNode, walkSerialized } from './serialized-node';
-import { SitePlan } from './site-plan.model';
+import { ContentRole, roleField, SitePlan } from './site-plan.model';
+import {
+    aspectRatioOf, scoreStockPhoto, STOCK_FAMILY_INTENTS, STOCK_INTENT_ORDER, StockIntent, StockNeed, stockFits, StockPhotoTraits, stockPhotoUsable,
+    stockWords,
+} from './stock-match';
 
 /**
- * Stock photos in a built site (AI plan §3g / §3m, I2): a FREE picture from the platform's curated library, copied
+ * Stock photos in a built site (AI plan §3g / §3m, I2 + I2.1): 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
+ * never a person (testimonials, the team), never anywhere when the business type says `stock: false` — and, since I2.1
+ * (Doron, 2026-10-28), in the picture of a MARKED sample item (a product, a service, a dish) of a type that may show
+ * stock. Which photo goes where is chosen by what the slot is about (`stock-match.ts`). Its alt text is
  * 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.
  */
@@ -67,23 +73,36 @@ export interface StockCredit {
     licenceUrl: 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. */
+/**
+ * One picture of the platform library (`iox-stock/<type>/`), as its manifest lists it. Everything past `credit` is
+ * optional (I2.1) — a manifest written before it is read as it was, and the planner derives what is missing.
+ */
+export interface StockPhoto extends StockPhotoTraits {
+    /** The library key (`spa/12345.jpg`) — the copy's file name is derived from it, the build reads it from the library's address. */
     key: string;
-    /** Where the build downloads it from (the platform bucket). */
+    /** Where the operator's run wrote it (kept for older readers; a build resolves `key` against the library's address). */
     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 const STOCK_FAMILIES: ReadonlySet<string> = new Set(Object.keys(STOCK_FAMILY_INTENTS));
+
+/** The aspect a list item's picture is shown at (Card v2's Image top, `composite-core` card layouts). */
+export const STOCK_ITEM_ASPECT = 4 / 3;
+
+export enum StockSlotKind {
+    /** An empty Image of a composed section. */
+    Section = 'section',
+    /** The image field of a marked sample item. */
+    Item = 'item',
+}
 
-export interface StockSlot {
+/** An empty picture of a composed section a stock photo may fill. */
+export interface StockSlot extends StockNeed {
+    kind: `${StockSlotKind.Section}`;
     /** The Image node the photo goes into. */
     nodeId: string;
     /** The page key it lives on. */
@@ -91,31 +110,128 @@ export interface StockSlot {
     pattern: string;
 }
 
-/** The empty picture slots of a composed site a stock photo may fill, in page and section order. */
+/** The image field of a sample item (a product, a service, a dish) a stock photo may fill. */
+export interface StockItemSlot extends StockNeed {
+    kind: `${StockSlotKind.Item}`;
+    contentType: string;
+    /** The item's 0-based position in the content type's samples. */
+    index: number;
+    /** The field playing the type's `image` role. */
+    field: string;
+}
+
+export type StockTarget = StockSlot | StockItemSlot;
+
+/** Where a photo may not appear twice: one page; one content type's samples (a list shows them together). */
+export function stockGroupOf(target: StockTarget): string {
+    return target.kind === StockSlotKind.Section ? `page:${target.owner}` : `items:${target.contentType}`;
+}
+
+const TEXT_PROPS: ReadonlyArray<string> = ['content', 'label'];
+
+/** The words of a subtree's text (Headings, Text, Links), the given node left out. */
+function textOf(nodes: ReadonlyArray<SerializedNode>, skip: string): string[] {
+    const out: string[] = [];
+    walkSerialized(nodes, n => {
+        if (n.id === skip) return;
+        for (const prop of TEXT_PROPS) if (typeof n.props[prop] === 'string') out.push(n.props[prop] as string);
+    });
+    return out;
+}
+
+/**
+ * The empty picture slots of a composed site a stock photo may fill, in page and section order — each with its intent
+ * (the section's family), its aspect, and the words around it: the text beside it (its row), the section's slots and
+ * the page's name and search words.
+ */
 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) => {
+        const pagePlan = plan.pages[p];
         page.layout.forEach((root, s) => {
-            const pattern = plan.pages[p]?.sections[s]?.pattern;
+            const section = pagePlan?.sections[s];
+            const pattern = section?.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 });
+            const intent = family ? STOCK_FAMILY_INTENTS[family] : undefined;
+            if (!pattern || !intent) return;
+            const sectionWords = [...Object.values(section?.slots ?? {}), pagePlan?.name, pagePlan?.seo?.title, pagePlan?.seo?.description];
+            walkSerialized([root], (n, ancestors) => {
+                if (n.type !== 'Image' || !empty.has(n.id) || n.bindings.length) return;
+                const row = ancestors[ancestors.length - 1];
+                out.push({
+                    kind: StockSlotKind.Section, nodeId: n.id, owner: page.key, pattern, intent,
+                    aspect: aspectRatioOf(n.styleProps['aspectRatio']),
+                    words: stockWords(...(row ? textOf([row], n.id) : []), ...sectionWords),
+                });
             });
         });
     });
     return out;
 }
 
-export interface StockPlacement extends StockSlot {
-    photo: StockPhoto;
+/**
+ * The sample items' pictures a stock photo may fill: per content type with an `image` role, each MARKED sample whose
+ * image is still a bundled sample (`{sampleImage:k}`), with the type's and the item's own words.
+ */
+export function stockItemSlots(plan: Pick<SitePlan, 'contentTypes'>, composed: Pick<ComposedSite, 'items'>): StockItemSlot[] {
+    const out: StockItemSlot[] = [];
+    for (const type of plan.contentTypes) {
+        const field = roleField(type, ContentRole.Image);
+        if (!field) continue;
+        const words = (item: Record<string, unknown>) => [type.label, type.name, ...[ContentRole.Title, ContentRole.Summary].map(r => item[roleField(type, r) ?? ''])];
+        (composed.items[type.name] ?? []).forEach((item, index) => {
+            if (!item.isSample || parseSampleImageRef(item[field]) === null) return;
+            out.push({ kind: StockSlotKind.Item, contentType: type.name, index, field, intent: StockIntent.Product, aspect: STOCK_ITEM_ASPECT, words: stockWords(...words(item)) });
+        });
+    }
+    return out;
 }
 
-/** 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[] {
+export type StockPlacement<T extends StockTarget = StockTarget> = T & { photo: StockPhoto };
+
+/** What a placement run is told besides the slots and the library. */
+export interface StockPlanOptions {
+    /** The business type's imagery line (harness-core `BusinessType.imagery`) — its words count for every slot. */
+    imagery?: string;
+}
+
+const intentRank = (intent: string) => STOCK_INTENT_ORDER.indexOf(intent as StockIntent);
+
+/**
+ * Which photo goes where (I2.1). Slots choose in intent order (the hero first, list items last; page order within),
+ * each taking the best-scoring photo that FITS its shape (`stockFits`) and is not already on its page (or among its
+ * type's samples) — a photo no slot has taken yet always before one another page shows. Ties go to the library's
+ * order. A slot nothing fits keeps its empty box (a sample its abstract picture). None at all when the type says no
+ * stock, and never a photo the review rejected or flagged. Returned in the slots' order.
+ */
+export function planStockPhotos<T extends StockTarget>(slots: ReadonlyArray<T>, photos: ReadonlyArray<StockPhoto>, stockAllowed: boolean, opts: StockPlanOptions = {}): Array<StockPlacement<T>> {
     if (!stockAllowed) return [];
-    return slots.slice(0, photos.length).map((slot, i) => ({ ...slot, photo: photos[i] }));
+    const usable = photos.filter(stockPhotoUsable);
+    const imagery = stockWords(opts.imagery);
+    const order = slots.map((slot, i) => ({ slot, i })).sort((a, b) => intentRank(a.slot.intent) - intentRank(b.slot.intent) || a.i - b.i);
+    const used = new Set<string>();
+    const shownIn = new Map<string, Set<string>>();
+    const placed = new Map<number, StockPlacement<T>>();
+    for (const { slot, i } of order) {
+        const group = stockGroupOf(slot);
+        const here = shownIn.get(group) ?? new Set<string>();
+        const candidates = usable.filter(p => !here.has(p.key) && stockFits(p, slot));
+        const fresh = candidates.filter(p => !used.has(p.key));
+        const pool = fresh.length ? fresh : candidates;
+        let best: StockPhoto | undefined;
+        let bestScore = -Infinity;
+        for (const photo of pool) {
+            const score = scoreStockPhoto(photo, slot, imagery);
+            if (score > bestScore) { best = photo; bestScore = score; }
+        }
+        if (!best) continue;
+        used.add(best.key);
+        here.add(best.key);
+        shownIn.set(group, here);
+        placed.set(i, { ...slot, photo: best });
+    }
+    return slots.map((_, i) => placed.get(i)).filter((p): p is StockPlacement<T> => !!p);
 }
 
 /** A placed photo's copy in the studio's storage: the key the build writes it under. */
@@ -137,6 +253,21 @@ export function applyStockPhotos(trees: ReadonlyArray<SerializedNode>, placed: R
     return changed;
 }
 
+/** Put the studio's copy of each photo into its sample item's image field. Returns the items changed. */
+export function applyStockItemPhotos(
+    items: Readonly<Record<string, ReadonlyArray<Record<string, unknown>>>>,
+    placed: ReadonlyArray<{ contentType: string; index: number; field: string; url: string }>,
+): number {
+    let changed = 0;
+    for (const p of placed) {
+        const item = items[p.contentType]?.[p.index];
+        if (!item) continue;
+        item[p.field] = p.url;
+        changed++;
+    }
+    return changed;
+}
+
 /** 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;