@vectoriox/iox-ui 5.83.1 → 5.84.0

package/src/generation-core/pictures.ts

@@ -0,0 +1,464 @@
+import { compositeOver, parseCssColour, relativeLuminance, Rgb, wcagContrastRatio } from '@vectoriox/iox-ui/design-core';
+
+import { AiStep, AiTokenPrice, creditsOfUsd, estimateStepCredits } from './ai-run';
+import { ArtDirection, artDirectionPreamble } from './art-direction';
+import { ComposedSite } from './compose-site';
+import { jsonBoolean, jsonClosedObject, JsonSchema, jsonText } from './json-schema';
+import { patternById } from './patterns';
+import { SerializedNode, walkSerialized } from './serialized-node';
+import { SitePlan } from './site-plan.model';
+import { STOCK_INTENT_ORDER, StockIntent } from './stock-match';
+import { OwnPhotoPlacement, planOwnPhotos, stockItemSlots, StockSlotKind, stockSlots, StockTarget } from './stock-photos';
+
+/**
+ * Pictures MADE for a site (premium-components M7, AI plan I3, premium sites PS4) — pure and deterministic: which picture
+ * slots of a composed site get a made picture, the prompt each is asked with (the site's ONE art direction first,
+ * verbatim, then what the slot is about, its frame and — where words sit over it — the part of the frame left calm for
+ * them), what the whole set costs before anything is asked, how a vision model's look at each picture is judged, and how
+ * dark the scrim under the words must be for the picture actually made. iox-cms makes, reviews and stores the pictures;
+ * the wizard shows the count and the cost from the same functions.
+ *
+ * The order of who fills a slot never changes: the OWNER's photos first (`planOwnPhotos`), then — only when the owner
+ * opted in — a made picture where one may stand, then stock where the business type allows it, else the empty box.
+ */
+
+/** Why a slot never gets a made picture — said to the owner, never silently skipped. */
+export enum PictureRefusal {
+    /** The business sells its own work (a photographer, a maker): a made picture would pass as it. */
+    OwnWork = 'own-work',
+    /** A product, a dish, a piece the business offers: a made one would show a thing it does not sell. */
+    Product = 'product',
+    /** Where to find the business: a made picture would fake a real place. */
+    RealPlace = 'real-place',
+    /** More slots than one site makes pictures for (`MAX_SITE_PICTURES`): the rest keep stock or the empty box. */
+    Limit = 'limit',
+}
+
+/** The section families whose picture is a real place (the contact / visit section). */
+export const PICTURE_REAL_PLACE_FAMILIES: ReadonlySet<string> = new Set(['contact']);
+
+/** The most pictures one site is made — a ceiling on what one build may spend on pictures. */
+export const MAX_SITE_PICTURES = 12;
+
+/** Which edge of the frame the words sit at. */
+export enum WordsEdge {
+    Top = 'top',
+    Bottom = 'bottom',
+}
+
+/** The part of the frame words sit over — left calm in the picture, measured once it is made. */
+export interface WordsArea {
+    edge: `${WordsEdge}`;
+    /** The share of the frame's height (0–1). */
+    share: number;
+}
+
+/** A scrim with no height of its own (it wraps its words) covers about this much of the frame. */
+export const WORDS_AREA_DEFAULT_SHARE = 0.45;
+const MEDIA_SCRIM_STYLE = 'media-scrim';
+const ABSOLUTE = 'absolute';
+const ZERO = /^0(px|%)?$/;
+const PERCENT = /^(\d+(?:\.\d+)?)%$/;
+
+/** The frames an image model is asked for (`image_config.aspect_ratio`), as width / height. */
+export const PICTURE_ASPECTS: Readonly<Record<string, number>> = {
+    '1:1': 1, '2:3': 2 / 3, '3:2': 3 / 2, '3:4': 3 / 4, '4:3': 4 / 3, '4:5': 4 / 5, '5:4': 5 / 4, '9:16': 9 / 16, '16:9': 16 / 9, '21:9': 21 / 9,
+};
+/** A slot that fills its box (a Scene's picture, a full-bleed band) is made wide: a phone crops its middle. */
+export const FILL_ASPECT = '16:9';
+
+/** One picture a site may be made: the slot it fills and everything its prompt and review read. */
+export interface PictureSlot {
+    /** Stable across runs: `page:<owner>:<nodeId>` (a section's picture) or `item:<type>:<index>:<field>`. */
+    key: string;
+    target: StockTarget;
+    intent: `${StockIntent}`;
+    /** The frame asked of the model (`PICTURE_ASPECTS`). */
+    ratio: string;
+    /** The section family it is in (`hero`, `story`…) — empty for an item. */
+    family: string;
+    /** What the section says, in the plan's own words (its slots) — what the picture is about. */
+    text: string;
+    /** Where the words sit over it, when they do. */
+    wordsArea?: WordsArea;
+    /** The node holding those words (a `media-scrim` box) — its scrim is chosen for the picture made. */
+    scrimNodeId?: string;
+}
+
+/** What a site's pictures will be. */
+export interface PicturePlan {
+    /** The owner's photos and where each goes — always first. */
+    own: OwnPhotoPlacement[];
+    /** The slots a picture is made for, the hero first. */
+    make: PictureSlot[];
+    /** The slots no picture is made for, and why (stock or the empty box fills them). */
+    refused: Array<{ key: string; reason: PictureRefusal }>;
+}
+
+export interface PicturePlanOptions {
+    /** The owner's own photos (urls), in order. */
+    ownPhotos?: ReadonlyArray<string>;
+    /** The business type's rule (harness-core `BusinessType.stock`): where stock may not stand in for the work, no made
+     *  picture may either. */
+    stockAllowed: boolean;
+    max?: number;
+}
+
+/** The ONE list of picture slots a build fills — its composed sections' empty pictures, then its sample items'. */
+export function pictureTargets(plan: SitePlan, composed: Pick<ComposedSite, 'pages' | 'placeholders' | 'items'>): StockTarget[] {
+    return [...stockSlots(plan, composed), ...stockItemSlots(plan, composed)];
+}
+
+/** A slot's stable key. */
+export function pictureSlotKey(target: StockTarget): string {
+    return target.kind === StockSlotKind.Section ? `page:${target.owner}:${target.nodeId}` : `item:${target.contentType}:${target.index}:${target.field}`;
+}
+
+/** The nearest frame a model is asked for (by the ratio of ratios); a slot with no shape fills its box. */
+export function pictureAspect(aspect: number | undefined): string {
+    if (!aspect || !Number.isFinite(aspect) || aspect <= 0) return FILL_ASPECT;
+    let best = FILL_ASPECT;
+    let distance = Infinity;
+    for (const [ratio, value] of Object.entries(PICTURE_ASPECTS)) {
+        const d = Math.abs(Math.log(value / aspect));
+        if (d < distance) { best = ratio; distance = d; }
+    }
+    return best;
+}
+
+interface NodeAt { node: SerializedNode; parent?: SerializedNode; section: number; page: number }
+
+function indexNodes(composed: Pick<ComposedSite, 'pages'>): Map<string, NodeAt> {
+    const at = new Map<string, NodeAt>();
+    composed.pages.forEach((page, p) => page.layout.forEach((root, s) => {
+        walkSerialized([root], (node, ancestors) => at.set(node.id, { node, parent: ancestors[ancestors.length - 1], section: s, page: p }));
+    }));
+    return at;
+}
+
+/**
+ * The words over a picture: a picture laid ABSOLUTE in its box whose sibling wears `media-scrim` (a Scene's stage, a
+ * full-bleed band) carries the words that box holds. The area is the scrim's: its height when it says one, else
+ * `WORDS_AREA_DEFAULT_SHARE`, at the edge it is pinned to.
+ */
+export function wordsOverPicture(node: SerializedNode, parent: SerializedNode | undefined): { area: WordsArea; scrimNodeId: string } | null {
+    if (!parent || node.styleProps['position'] !== ABSOLUTE) return null;
+    const scrim = parent.children?.find(c => c !== node && c.elementStyle === MEDIA_SCRIM_STYLE);
+    if (!scrim) return null;
+    const top = String(scrim.styleProps['top'] ?? '');
+    const bottom = String(scrim.styleProps['bottom'] ?? '');
+    const edge = ZERO.test(top) && !ZERO.test(bottom) ? WordsEdge.Top : WordsEdge.Bottom;
+    const height = PERCENT.exec(String(scrim.styleProps['height'] ?? ''));
+    const share = height ? Math.min(1, Number(height[1]) / 100) : WORDS_AREA_DEFAULT_SHARE;
+    return { area: { edge, share }, scrimNodeId: scrim.id };
+}
+
+const SECTION_TEXT_MAX = 160;
+
+/** What a section says (its slots, in the plan's words), cut to a prompt's length. */
+function sectionText(plan: SitePlan, page: number, section: number): string {
+    const slots = plan.pages[page]?.sections[section]?.slots ?? {};
+    const text = Object.values(slots).filter((v): v is string => typeof v === 'string' && !!v.trim()).join(' — ').replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
+    return text.length > SECTION_TEXT_MAX ? `${text.slice(0, SECTION_TEXT_MAX - 1).trimEnd()}…` : text;
+}
+
+/** Why `target` never gets a made picture, or null. */
+export function pictureRefusalOf(target: StockTarget, stockAllowed: boolean): PictureRefusal | null {
+    if (!stockAllowed) return PictureRefusal.OwnWork;
+    if (target.kind === StockSlotKind.Item) return PictureRefusal.Product;
+    const family = patternById(target.pattern)?.family ?? '';
+    return PICTURE_REAL_PLACE_FAMILIES.has(family) ? PictureRefusal.RealPlace : null;
+}
+
+const intentRank = (intent: string) => STOCK_INTENT_ORDER.indexOf(intent as StockIntent);
+
+/**
+ * Which slots get a made picture: the owner's photos take theirs first (the same `planOwnPhotos` the build places them
+ * with), then each slot left — the hero first, page order within — gets one unless it is refused (the work, a product,
+ * a real place) or the site already has `max`. Pure: the wizard's count, the generation's run and the build agree.
+ */
+export function planPictures(plan: SitePlan, composed: Pick<ComposedSite, 'pages' | 'placeholders' | 'items'>, opts: PicturePlanOptions): PicturePlan {
+    const { placements: own, rest } = planOwnPhotos(pictureTargets(plan, composed), opts.ownPhotos ?? []);
+    const nodes = indexNodes(composed);
+    const max = opts.max ?? MAX_SITE_PICTURES;
+    const ordered = rest.map((t, i) => ({ t, i })).sort((a, b) => intentRank(a.t.intent) - intentRank(b.t.intent) || a.i - b.i).map(x => x.t);
+    const make: PictureSlot[] = [];
+    const refused: PicturePlan['refused'] = [];
+    for (const target of ordered) {
+        const key = pictureSlotKey(target);
+        const reason = pictureRefusalOf(target, opts.stockAllowed) ?? (make.length >= max ? PictureRefusal.Limit : null);
+        if (reason) { refused.push({ key, reason }); continue; }
+        make.push(pictureSlotOf(plan, target, key, nodes));
+    }
+    return { own, make, refused };
+}
+
+function pictureSlotOf(plan: SitePlan, target: StockTarget, key: string, nodes: Map<string, NodeAt>): PictureSlot {
+    const base = { key, target, intent: target.intent, ratio: pictureAspect(target.aspect) };
+    if (target.kind !== StockSlotKind.Section) return { ...base, family: '', text: '' };
+    const at = nodes.get(target.nodeId);
+    const over = at ? wordsOverPicture(at.node, at.parent) : null;
+    return {
+        ...base,
+        family: patternById(target.pattern)?.family ?? '',
+        text: at ? sectionText(plan, at.page, at.section) : '',
+        ...(over ? { wordsArea: over.area, scrimNodeId: over.scrimNodeId } : {}),
+    };
+}
+
+// ── The prompt ──────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** What each kind of slot asks to see (`business` = the kind of business, "a café or bakery"). */
+const INTENT_SUBJECT: Readonly<Record<StockIntent, (business: string) => string>> = {
+    [StockIntent.Atmosphere]: b => `A wide, atmospheric picture that sets the mood of ${b}: depth, a sense of the place, nothing staged.`,
+    [StockIntent.Place]: b => `The kind of place ${b} is: the room or the setting at eye level, quiet and inviting.`,
+    [StockIntent.Detail]: b => `A close detail of the work of ${b}: its materials, its tools, a moment of making.`,
+    [StockIntent.Product]: b => `One thing ${b} offers, alone on a plain ground.`,
+};
+
+const EDGE_WORD: Readonly<Record<WordsEdge, string>> = { [WordsEdge.Top]: 'upper', [WordsEdge.Bottom]: 'lower' };
+
+/** The empty part a slot's words sit over, said to the model: where, how much, and what it must look like. */
+export function emptyAreaPhrase(area: WordsArea): string {
+    const share = Math.round(area.share * 100);
+    return `Leave the ${EDGE_WORD[area.edge as WordsEdge]} ${share}% of the frame calm and uncluttered — soft focus, even tone, nothing important there — because the site's words sit over it.`;
+}
+
+/** The frame, said plainly. */
+export function frameWords(ratio: string): string {
+    const value = PICTURE_ASPECTS[ratio] ?? 1;
+    const shape = value > 1.05 ? 'landscape' : value < 0.95 ? 'portrait' : 'square';
+    return `Frame: ${shape}, ${ratio}.`;
+}
+
+export interface PicturePromptContext {
+    /** The kind of business, in words a prompt can carry ("a café or bakery") — never its name (it would be drawn). */
+    business: string;
+}
+
+/**
+ * The prompt a picture is asked with: the site's preamble VERBATIM, what the slot is about (its intent, then the
+ * section's own words), its frame, the empty part the words need — and nothing else. The same slot of the same plan
+ * is always asked the same words.
+ */
+export function picturePrompt(slot: PictureSlot, direction: ArtDirection, context: PicturePromptContext): string {
+    return [
+        artDirectionPreamble(direction),
+        INTENT_SUBJECT[slot.intent as StockIntent](context.business),
+        ...(slot.text ? [`It goes beside these words of the site: “${slot.text}”.`] : []),
+        frameWords(slot.ratio),
+        ...(slot.wordsArea ? [emptyAreaPhrase(slot.wordsArea)] : []),
+    ].join('\n');
+}
+
+// ── The cost, shown before ──────────────────────────────────────────────────────────────────────────────────────────
+
+/** One picture in this many may be made a second time (a review said no) — paid for in the estimate shown. */
+export const PICTURE_REROLL_EVERY = 6;
+
+/** How many second tries a set of `count` pictures has, shown and paid for up front. */
+export function pictureRerolls(count: number): number {
+    return count > 0 ? Math.ceil(count / PICTURE_REROLL_EVERY) : 0;
+}
+
+export interface PicturesEstimate {
+    count: number;
+    /** Second tries included in the total. */
+    rerolls: number;
+    /** One picture, in credits. */
+    picture: number;
+    /** One review of a picture, in credits. */
+    review: number;
+    /** What the owner is shown and the most the run may spend: every picture and its review, plus the second tries. */
+    total: number;
+}
+
+/**
+ * The cost shown before the owner says yes (I-D4): each picture and its review at the vetted list's prices, plus one
+ * second try (a picture and its review) for every `PICTURE_REROLL_EVERY` pictures. The run never spends past `total` —
+ * a second try that would cross it is not made — so the shown cost is a ceiling met exactly when every try is used.
+ */
+export function estimatePictures(count: number, prices: { image: AiTokenPrice; review: AiTokenPrice }): PicturesEstimate {
+    const picture = estimateStepCredits(AiStep.MakePictures, prices.image);
+    const review = estimateStepCredits(AiStep.CheckPictures, prices.review);
+    const rerolls = pictureRerolls(count);
+    return { count, rerolls, picture, review, total: creditsOfUsd(((count + rerolls) * (picture + review)) / 100) };
+}
+
+// ── The review ──────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** The structured answer's name (`output.name`). */
+export const PICTURE_REVIEW_FORMAT = 'picture_review';
+
+/** What a vision model says of one picture against its slot. */
+export interface PictureReview {
+    subject: boolean;
+    calmArea: boolean;
+    clean: boolean;
+    anatomy: boolean;
+    alt: string;
+    note: string;
+}
+
+/** The review's shape, each key in the words the model reads (every key required: no optional parameter). */
+export const PICTURE_REVIEW_SHAPE: Readonly<Record<keyof PictureReview, string>> = {
+    subject: 'boolean — it shows what the slot asked for, in the art direction asked',
+    calmArea: 'boolean — the part of the frame named for words is calm enough to read words over (true when none was named)',
+    clean: 'boolean — no text, letters, numbers, logo, watermark, signage or frame anywhere',
+    anatomy: 'boolean — no distorted hands, faces, bodies or objects; nothing melted or duplicated',
+    alt: 'string — what the picture shows, in at most 12 plain words, in the language asked (the alt text)',
+    note: 'string — why, when any answer is false; else empty',
+};
+
+const BOOLEAN_KEYS: ReadonlyArray<keyof PictureReview> = ['subject', 'calmArea', 'clean', 'anatomy'];
+const TEXT_KEYS: ReadonlyArray<keyof PictureReview> = ['alt', 'note'];
+
+/** The review's strict format: 6 properties, all required, closed — well inside every structured-output limit. */
+export function pictureReviewJsonSchema(): JsonSchema {
+    const properties: Record<string, JsonSchema> = {};
+    for (const key of BOOLEAN_KEYS) properties[key] = { ...jsonBoolean(), description: PICTURE_REVIEW_SHAPE[key] };
+    for (const key of TEXT_KEYS) properties[key] = { ...jsonText(), description: PICTURE_REVIEW_SHAPE[key] };
+    return jsonClosedObject(properties, [...BOOLEAN_KEYS, ...TEXT_KEYS], 'A look at one picture made for a website, against what its slot asked for.');
+}
+
+/** What is wrong with an answer as a review — the gate the call service holds it to. */
+export function pictureReviewIssues(value: unknown): Array<{ code: string; path: string; message: string }> {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return [{ code: 'shape', path: '', message: 'must be an object' }];
+    const v = value as Record<string, unknown>;
+    const issues: Array<{ code: string; path: string; message: string }> = [];
+    for (const key of BOOLEAN_KEYS) if (typeof v[key] !== 'boolean') issues.push({ code: 'shape', path: key, message: 'must be true or false' });
+    for (const key of TEXT_KEYS) if (typeof v[key] !== 'string') issues.push({ code: 'shape', path: key, message: 'must be text' });
+    for (const key of Object.keys(v)) if (!(key in PICTURE_REVIEW_SHAPE)) issues.push({ code: 'shape', path: key, message: 'is not a key of the review' });
+    return issues;
+}
+
+/** A picture is used when it shows the subject, is clean and whole — and, where words sit over it, leaves them room. */
+export function pictureReviewPasses(review: PictureReview, slot: Pick<PictureSlot, 'wordsArea'>): boolean {
+    return review.subject && review.clean && review.anatomy && (!slot.wordsArea || review.calmArea);
+}
+
+// ── Words over the picture made ─────────────────────────────────────────────────────────────────────────────────────
+
+/** How strong the scrim under a picture's words is, weakest first. `Soft` is the element style's own gradient. */
+export enum ScrimLevel {
+    Soft = 'soft',
+    Firm = 'firm',
+    Full = 'full',
+}
+
+export const SCRIM_LEVELS: ReadonlyArray<ScrimLevel> = [ScrimLevel.Soft, ScrimLevel.Firm, ScrimLevel.Full];
+
+/** What each level writes on the scrim node (`backgroundColor`, token references only) — `null`: the style's own. */
+export const SCRIM_BACKGROUND: Readonly<Record<ScrimLevel, string | null>> = {
+    [ScrimLevel.Soft]: null,
+    [ScrimLevel.Firm]: 'linear-gradient(180deg, transparent 0%, var(--iox-media-scrim) 18%)',
+    [ScrimLevel.Full]: 'var(--iox-media-scrim)',
+};
+
+/** The least share of the scrim's own strength under the first line of words, at each level (the gradient's ramp). */
+export const SCRIM_COVER: Readonly<Record<ScrimLevel, number>> = {
+    [ScrimLevel.Soft]: 0.5,
+    [ScrimLevel.Firm]: 0.85,
+    [ScrimLevel.Full]: 1,
+};
+
+/** WCAG AA for body text — the words over a picture include a lead and a button label, never only a headline. */
+export const PICTURE_TEXT_CONTRAST = 4.5;
+
+/** The light of a picture's words area: its darkest and lightest few percent (relative luminance, 0–1), and its mean. */
+export interface AreaLuminance {
+    low: number;
+    high: number;
+    mean: number;
+}
+
+/** The share of pixels left out at each end, so a single sparkle does not decide the scrim. */
+const AREA_PERCENTILE = 0.05;
+/** The area is read a little past its edge: a Scene scales its picture in from the middle. */
+const AREA_MARGIN = 0.1;
+/** A phone shows the middle of a wide picture: read that column too. */
+const PHONE_COLUMN: readonly [number, number] = [1 / 3, 2 / 3];
+
+const srgbToLinear = (v: number) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+const linearToSrgb = (v: number) => (v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055);
+const BYTE = 255;
+const RGBA = 4;
+
+function windowLuminance(rgba: ArrayLike<number>, width: number, height: number, rows: readonly [number, number], columns: readonly [number, number]): AreaLuminance {
+    const values: number[] = [];
+    const [y0, y1] = rows.map(r => Math.round(r * height));
+    const [x0, x1] = columns.map(c => Math.round(c * width));
+    for (let y = Math.max(0, y0); y < Math.min(height, y1); y++) {
+        for (let x = Math.max(0, x0); x < Math.min(width, x1); x++) {
+            const i = (y * width + x) * RGBA;
+            values.push(0.2126 * srgbToLinear(rgba[i] / BYTE) + 0.7152 * srgbToLinear(rgba[i + 1] / BYTE) + 0.0722 * srgbToLinear(rgba[i + 2] / BYTE));
+        }
+    }
+    if (!values.length) return { low: 0, high: 0, mean: 0 };
+    values.sort((a, b) => a - b);
+    const at = (q: number) => values[Math.min(values.length - 1, Math.max(0, Math.round(q * (values.length - 1))))];
+    return { low: at(AREA_PERCENTILE), high: at(1 - AREA_PERCENTILE), mean: values.reduce((a, b) => a + b, 0) / values.length };
+}
+
+/**
+ * The light of the part of a picture its words sit over (RGBA bytes, row by row) — read across the whole width (a laptop)
+ * and in the middle third (a phone's crop of a wide picture); the darker low and the lighter high of the two.
+ */
+export function areaLuminance(rgba: ArrayLike<number>, width: number, height: number, area: WordsArea): AreaLuminance {
+    const reach = Math.min(1, area.share + AREA_MARGIN);
+    const rows: readonly [number, number] = area.edge === WordsEdge.Top ? [0, reach] : [1 - reach, 1];
+    const laptop = windowLuminance(rgba, width, height, rows, [0, 1]);
+    const phone = windowLuminance(rgba, width, height, rows, PHONE_COLUMN);
+    return { low: Math.min(laptop.low, phone.low), high: Math.max(laptop.high, phone.high), mean: laptop.mean };
+}
+
+/** A grey of this relative luminance. */
+function greyOf(luminance: number): Rgb {
+    const v = linearToSrgb(Math.min(1, Math.max(0, luminance)));
+    return { r: v, g: v, b: v };
+}
+
+export interface ScrimChoice {
+    level: ScrimLevel;
+    /** The worst contrast the words have over the picture at that level. */
+    contrast: number;
+}
+
+/**
+ * The weakest scrim under which the words reach AA over the picture made: the scrim's own colour (`--iox-media-scrim`,
+ * as the look writes it) at its least strength under the words, over the area's darkest and lightest, against the ink
+ * (`--iox-media-scrim-ink`). `Full` when nothing weaker does — the contract already holds a full scrim over white to AA.
+ */
+export function chooseScrim(area: AreaLuminance, colours: { scrim: string; ink: string }, minContrast = PICTURE_TEXT_CONTRAST): ScrimChoice {
+    const scrim = parseCssColour(colours.scrim);
+    const ink = parseCssColour(colours.ink);
+    if (!scrim || !ink) return { level: ScrimLevel.Full, contrast: 0 };
+    const worstAt = (level: ScrimLevel) => Math.min(...[area.low, area.high].map(y => {
+        const under = compositeOver({ ...scrim, a: scrim.a * SCRIM_COVER[level] }, greyOf(y));
+        return wcagContrastRatio(ink, under);
+    }));
+    for (const level of SCRIM_LEVELS) {
+        const contrast = worstAt(level);
+        if (contrast >= minContrast) return { level, contrast };
+    }
+    return { level: ScrimLevel.Full, contrast: worstAt(ScrimLevel.Full) };
+}
+
+/** Set each chosen scrim on its node (`Soft` leaves the element style's own). Returns the nodes changed. */
+export function applyPictureScrims(trees: ReadonlyArray<SerializedNode>, chosen: ReadonlyArray<{ nodeId: string; level: `${ScrimLevel}` }>): number {
+    const byId = new Map(chosen.map(c => [c.nodeId, SCRIM_BACKGROUND[c.level as ScrimLevel]]));
+    let changed = 0;
+    walkSerialized(trees, node => {
+        const background = byId.get(node.id);
+        if (!background) return;
+        node.styleProps['backgroundColor'] = background;
+        changed++;
+    });
+    return changed;
+}
+
+/** The relative luminance of a CSS colour (for a review sheet or a log), or null. */
+export function luminanceOf(colour: string): number | null {
+    const c = parseCssColour(colour);
+    return c ? relativeLuminance(c) : null;
+}

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

@@ -198,6 +198,8 @@ export const PLAN_WIRE_DERIVED: Readonly<Record<string, string>> = {
     design: "the owner's pick (the context)",
     'plan.film': "the owner's film, set by the build (SC6b)",
     film: "the owner's film, set by the build (SC6b)",
+    'plan.artDirection': 'the generation, from the business type and the look (M7 — artDirectionFor)',
+    artDirection: 'the generation, from the business type and the look (M7 — artDirectionFor)',
 };
 
 const wireText = (spec: WireKey): string => {

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

@@ -37,3 +37,5 @@ export * from './audit-site';
 export * from './stock-match';
 export * from './stock-photos';
 export * from './film';
+export * from './art-direction';
+export * from './pictures';

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

@@ -129,6 +129,9 @@ export enum BuildNoticeCode {
     /** The stock library was read but holds no photo for this kind of business (never built, or reviewed down to
      *  none): the picture slots keep the empty box, and the run says so (I2.1 — never silently). */
     StockMissing = 'stock-missing',
+    /** M7: a picture made for the site was refused by its review twice (or its second try did not fit the cost shown):
+     *  stock or the empty box stands in, and the run says so. */
+    PictureFallback = 'picture-fallback',
 }
 
 export interface BuildNotice {

package/src/generation-core/site-plan.model.ts

@@ -1,5 +1,6 @@
 import type { FrameSequence } from '@vectoriox/iox-ui/media-core';
 import type { AnimateId, DesignChoices } from '@vectoriox/iox-ui/design-core';
+import type { ArtDirection } from './art-direction';
 
 import { SPEC_SITE_ARCHETYPES, SPEC_SITE_FACTS, SPEC_SITE_LOCALES, SPEC_SITE_NEED_IDS, SPEC_SITE_REQUIRED_ROLES, SPEC_SITE_ROLES } from './site-spec.generated';
 
@@ -249,6 +250,9 @@ export interface SitePlan {
     readonly globals: Readonly<Record<`${GlobalSlot}`, string>>;
     /** SC6b: the owner's film as pictures, set by the build and placed by `placeFilm` — never a model's. */
     readonly film?: PlanFilm;
+    /** M7: what every picture made for the site shares (a world and its five parts) — set by the generation from the
+     *  business type and the look (`artDirectionFor`), never a model's. */
+    readonly artDirection?: ArtDirection;
 }
 
 /** SC6b: the owner's film — the numbered pictures the wizard's browser made of their video (media-core). */

package/src/generation-core/site-spec.generated.ts

@@ -13,11 +13,20 @@ export const SPEC_SITE_PLAN_SHAPE = {
     "dataSources": "(cmsDataSource | relativeDataSource)[] — merged by alias into the org library",
     "pages": "page[]",
     "globals": "globals",
-    "film?": "film — the owner's film as pictures (SC6b), set by the build and placed by placeFilm; never a model's"
+    "film?": "film — the owner's film as pictures (SC6b), set by the build and placed by placeFilm; never a model's",
+    "artDirection?": "artDirection — what every picture made for the site shares (M7): set by the generation from the business type and the look (generation-core artDirectionFor); never a model's"
   },
   "film": {
     "sequence": "object — a media-core FrameSequence: where the numbered pictures live, how many, their size"
   },
+  "artDirection": {
+    "world": "string — a site.pictureWorlds id",
+    "medium": "string — the picture's medium and lens",
+    "light": "string — its light",
+    "grade": "string — its colour grade",
+    "texture": "string — its texture",
+    "negative": "string[] — what no picture of the site may show (site.pictureNever, then the world's own)"
+  },
   "sourceTemplate": {
     "kind": "'template'",
     "templateId": "string",
@@ -5782,3 +5791,111 @@ export const SPEC_SITE_LIBRARY = [
     "composed": true
   }
 ] as const;
+
+export const SPEC_SITE_PICTURE_WORLDS = {
+  "documentary": {
+    "label": "Documentary",
+    "medium": "an unposed documentary photograph, 35mm lens, natural eye-level framing",
+    "light": "available natural light, soft and directional",
+    "grade": "true-to-life colour with gentle contrast",
+    "texture": "fine natural grain and real, lived-in surfaces",
+    "negative": [
+      "staged poses",
+      "a studio backdrop"
+    ],
+    "dark": "low-key"
+  },
+  "high-key": {
+    "label": "High-key",
+    "medium": "a bright editorial photograph, 50mm lens, a clean composition with generous air",
+    "light": "soft, even daylight from a large window; few, pale shadows",
+    "grade": "a light, airy palette with lifted whites and low contrast",
+    "texture": "smooth surfaces and crisp, gentle detail",
+    "negative": [
+      "harsh shadows",
+      "dark corners"
+    ],
+    "dark": "low-key"
+  },
+  "low-key": {
+    "label": "Low-key",
+    "medium": "a moody photograph, 50mm lens at a wide aperture, shallow depth of field",
+    "light": "one warm, low light source; most of the frame falls into deep shadow",
+    "grade": "rich blacks with warm, glowing highlights",
+    "texture": "a soft haze in the air and a gentle film grain",
+    "negative": [
+      "flat lighting",
+      "a bright background"
+    ],
+    "dark": "low-key"
+  },
+  "hard-light": {
+    "label": "Hard light",
+    "medium": "a graphic photograph, 35mm lens, bold and simple shapes",
+    "light": "hard, direct sunlight with crisp, long cast shadows",
+    "grade": "saturated colour and punchy contrast",
+    "texture": "sharp edges and clean planes",
+    "negative": [
+      "haze",
+      "muddy colour"
+    ],
+    "dark": "low-key"
+  },
+  "macro": {
+    "label": "Macro",
+    "medium": "a close-up macro photograph, 100mm macro lens, a very shallow plane of focus",
+    "light": "soft side light raking across the surface",
+    "grade": "natural colour with rich mid-tones",
+    "texture": "tactile surface detail — grain, fibre, glaze, crumb",
+    "negative": [
+      "a wide view",
+      "clutter in focus"
+    ],
+    "dark": "low-key"
+  },
+  "architectural": {
+    "label": "Architectural",
+    "medium": "an architectural photograph, 24mm tilt-shift lens, straight verticals and a calm composition",
+    "light": "calm, diffuse daylight",
+    "grade": "neutral, precise colour with balanced contrast",
+    "texture": "clean lines and crisp materials — stone, wood, glass, plaster",
+    "negative": [
+      "converging verticals",
+      "wide-angle distortion"
+    ],
+    "dark": "nocturne"
+  },
+  "nocturne": {
+    "label": "Nocturne",
+    "medium": "a night photograph, 35mm lens",
+    "light": "practical lights only — lamps, candles, a warm window — against the dark",
+    "grade": "deep blue-black shadows with warm pools of light",
+    "texture": "soft bokeh and a light haze",
+    "negative": [
+      "daylight",
+      "flash"
+    ],
+    "dark": "nocturne"
+  },
+  "drawing": {
+    "label": "Drawing",
+    "medium": "a hand-made illustration, ink and watercolour wash on paper",
+    "light": "flat and even, never photographic",
+    "grade": "a limited palette of two or three colours",
+    "texture": "visible paper grain and brush strokes",
+    "negative": [
+      "photographic realism",
+      "a 3D rendering"
+    ],
+    "dark": "drawing"
+  }
+} as const;
+
+export const SPEC_SITE_PICTURE_NEVER = [
+  "text, letters or numbers",
+  "logos, brand names or signage",
+  "a watermark",
+  "a recognisable face",
+  "borders or frames",
+  "distorted hands or objects"
+] as const;