@vectoriox/iox-ui 5.66.1 → 5.67.0

package/generation-core/index.d.ts

@@ -5617,7 +5617,10 @@ declare enum BuildNoticeCode {
     /** 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"
+    StockUnavailable = "stock-unavailable",
+    /** 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"
 }
 interface BuildNotice {
     code: string;
@@ -6482,10 +6485,114 @@ declare function publishVerdict(audit: SiteAudit, acknowledged?: ReadonlyArray<s
 };
 
 /**
- * Stock photos in a built site (AI plan §3g / §3m, I2): a FREE picture from the platform's curated library, copied
+ * How a stock photo is judged against a picture slot (AI plan §3g, I2.1) — pure and deterministic, so the same plan and
+ * the same library always place the same photos. A photo is described by what the library's manifest carries (the
+ * provider's tags, its orientation, the reviewer's subject and notes — each optional, derived when absent); a slot by
+ * its INTENT (what kind of picture its section wants), its aspect ratio and the plan's words around it.
+ */
+declare enum StockOrientation {
+    Horizontal = "horizontal",
+    Vertical = "vertical",
+    Square = "square"
+}
+/** What a photo mainly shows — the reviewer may set it; otherwise it is read from the provider's tags. */
+declare enum StockSubject {
+    /** A room, a shop front, a garden — somewhere. */
+    Place = "place",
+    /** A close-up: a texture, a tool, an ingredient. */
+    Detail = "detail",
+    /** A thing a business sells or serves: a cake, a bottle, a bouquet. */
+    Product = "product"
+}
+/** What a slot wants to show. */
+declare enum StockIntent {
+    /** The hero / a page header / a call to action: wide and atmospheric. */
+    Atmosphere = "atmosphere",
+    /** A story or a visit section: the place. */
+    Place = "place",
+    /** A feature row: a detail of the work or the service. */
+    Detail = "detail",
+    /** A list item's picture (a product, a service, a dish). */
+    Product = "product"
+}
+declare enum StockReviewVerdict {
+    Approved = "approved",
+    Rejected = "rejected"
+}
+/** What the review found in a photo that keeps it out of every site (the licence: no person, no logo or brand). */
+declare enum StockReviewFlag {
+    Person = "person",
+    Logo = "logo"
+}
+/** The operator's one review of a photo, as the manifest records it. */
+interface StockReview {
+    verdict: `${StockReviewVerdict}`;
+    flags?: Array<`${StockReviewFlag}`>;
+    /** The reviewer's own words for it — they count as tags when placing it. */
+    notes?: string;
+}
+/** The section families a stock photo may stand in for a picture in, and what each wants. */
+declare const STOCK_FAMILY_INTENTS: Readonly<Record<string, StockIntent>>;
+/** Per intent, the subjects it takes, best first. */
+declare const STOCK_INTENT_SUBJECTS: Readonly<Record<StockIntent, ReadonlyArray<StockSubject>>>;
+/** The order slots choose in: the hero picks first, a list item last. */
+declare const STOCK_INTENT_ORDER: ReadonlyArray<StockIntent>;
+/** The words that tell a photo's subject when the reviewer did not name it (singular, lower case). */
+declare const STOCK_SUBJECT_WORDS: Readonly<Record<StockSubject, ReadonlyArray<string>>>;
+/** The share of a photo a slot may crop away and still be a fit: a portrait never fills a 21 / 9 band. */
+declare const STOCK_MIN_KEPT = 0.5;
+/**
+ * A word as compared — a canonical form, never shown: lower case, a plain plural made singular, and `-ie` / `-y` one
+ * ending (English cannot tell `cookies` from `pastries` by rule, so `cookie`, `cookies`, `pastry`, `pastries` all
+ * fold to the same shape as their singular).
+ */
+declare function stockWord(raw: string): string;
+/** The meaningful words of a text, in order, each once. */
+declare function stockWords(...texts: ReadonlyArray<unknown>): string[];
+/** A CSS aspect ratio (`4 / 3`, `1.5`) as width / height, or undefined. */
+declare function aspectRatioOf(aspect: unknown): number | undefined;
+/** What the planner reads of a library photo. */
+interface StockPhotoTraits {
+    alt: string;
+    width?: number;
+    height?: number;
+    tags?: ReadonlyArray<string>;
+    orientation?: `${StockOrientation}`;
+    subject?: `${StockSubject}`;
+    review?: StockReview;
+}
+/** A photo may be placed: not rejected and nothing flagged by the review. */
+declare function stockPhotoUsable(photo: Pick<StockPhotoTraits, 'review'>): boolean;
+/** The words a photo is placed by: its tags (else its alt — the provider's own words) and the reviewer's notes. */
+declare function stockPhotoWords(photo: Pick<StockPhotoTraits, 'alt' | 'tags' | 'review'>): string[];
+/** Its width / height: the size when known, else its orientation's nominal shape, else undefined. */
+declare function stockPhotoRatio(photo: Pick<StockPhotoTraits, 'width' | 'height' | 'orientation'>): number | undefined;
+/** The orientation of a width / height ratio. */
+declare function orientationOfRatio(ratio: number): StockOrientation;
+/** The reviewer's subject, else the one its words name most (ties: the enum's order), else undefined. */
+declare function stockPhotoSubject(photo: Pick<StockPhotoTraits, 'alt' | 'tags' | 'review' | 'subject'>): StockSubject | undefined;
+/** What a slot asks of a photo. */
+interface StockNeed {
+    intent: `${StockIntent}`;
+    /** The slot's width / height (undefined: any shape). */
+    aspect?: number;
+    /** The plan's words around the slot. */
+    words: ReadonlyArray<string>;
+}
+/** The share of the photo a slot shows (1 = the same shape), or undefined when either shape is unknown. */
+declare function stockKept(photo: Pick<StockPhotoTraits, 'width' | 'height' | 'orientation'>, aspect: number | undefined): number | undefined;
+/** A photo fits a slot when the slot keeps at least half of it (an unknown shape fits). */
+declare function stockFits(photo: Pick<StockPhotoTraits, 'width' | 'height' | 'orientation'>, need: Pick<StockNeed, 'aspect'>): boolean;
+/** How well a photo answers a slot: its subject for the intent, its shape, the plan's words and the type's imagery. */
+declare function scoreStockPhoto(photo: StockPhotoTraits, need: StockNeed, imagery?: ReadonlyArray<string>): number;
+
+/**
+ * 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.
  */
@@ -6528,34 +6635,77 @@ interface StockCredit {
     licence: string;
     licenceUrl: string;
 }
-/** One picture of the platform library (`iox-stock/<type>/`), as its manifest lists it. */
-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.
+ */
+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. */
 declare const STOCK_FAMILIES: ReadonlySet<string>;
-interface StockSlot {
+/** The aspect a list item's picture is shown at (Card v2's Image top, `composite-core` card layouts). */
+declare const STOCK_ITEM_ASPECT: number;
+declare enum StockSlotKind {
+    /** An empty Image of a composed section. */
+    Section = "section",
+    /** The image field of a marked sample item. */
+    Item = "item"
+}
+/** An empty picture of a composed section a stock photo may fill. */
+interface StockSlot extends StockNeed {
+    kind: `${StockSlotKind.Section}`;
     /** 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. */
+/** The image field of a sample item (a product, a service, a dish) a stock photo may fill. */
+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;
+}
+type StockTarget = StockSlot | StockItemSlot;
+/** Where a photo may not appear twice: one page; one content type's samples (a list shows them together). */
+declare function stockGroupOf(target: StockTarget): string;
+/**
+ * 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.
+ */
 declare function stockSlots(plan: SitePlan, composed: Pick<ComposedSite, 'pages' | 'placeholders'>): StockSlot[];
-interface StockPlacement extends StockSlot {
+/**
+ * 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.
+ */
+declare function stockItemSlots(plan: Pick<SitePlan, 'contentTypes'>, composed: Pick<ComposedSite, 'items'>): StockItemSlot[];
+type StockPlacement<T extends StockTarget = StockTarget> = T & {
     photo: StockPhoto;
+};
+/** What a placement run is told besides the slots and the library. */
+interface StockPlanOptions {
+    /** The business type's imagery line (harness-core `BusinessType.imagery`) — its words count for every slot. */
+    imagery?: string;
 }
-/** Which photo goes where: the library's photos in order, one per slot, never twice; none when the type says no stock. */
-declare function planStockPhotos(slots: ReadonlyArray<StockSlot>, photos: ReadonlyArray<StockPhoto>, stockAllowed: boolean): StockPlacement[];
+/**
+ * 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.
+ */
+declare function planStockPhotos<T extends StockTarget>(slots: ReadonlyArray<T>, photos: ReadonlyArray<StockPhoto>, stockAllowed: boolean, opts?: StockPlanOptions): Array<StockPlacement<T>>;
 /** A placed photo's copy in the studio's storage: the key the build writes it under. */
 declare function stockCopyKey(photo: Pick<StockPhoto, 'key'>): string;
 /** Put the studio's copy of each photo into its slot (src + the provider's alt). Returns the nodes changed. */
@@ -6564,6 +6714,13 @@ declare function applyStockPhotos(trees: ReadonlyArray<SerializedNode>, placed:
     url: string;
     alt: string;
 }>): number;
+/** Put the studio's copy of each photo into its sample item's image field. Returns the items changed. */
+declare function applyStockItemPhotos(items: Readonly<Record<string, ReadonlyArray<Record<string, unknown>>>>, placed: ReadonlyArray<{
+    contentType: string;
+    index: number;
+    field: string;
+    url: string;
+}>): number;
 /** The line a picture's licence requires on the site, or null when it requires none (`STOCK_PROVIDER_TERMS`). */
 declare function stockCreditLine(credit: Pick<StockCredit, 'provider'>): StockLink | null;
 /** The credit lines a set of photos needs — one per distinct line, none for a provider whose licence asks none. */
@@ -6578,5 +6735,5 @@ declare function stockCreditNode(index: number, credit: StockLink): SerializedNo
 /** Append the credit lines to the footer root (once each). Returns how many it added. */
 declare function addStockCredits(footer: SerializedNode, credits: ReadonlyArray<StockLink>): number;
 
-export { ACTIVE_BUILD_STATUSES, AI_REFUSAL_NEXT, AI_REFUSAL_STATUS, AI_STEPS, AI_STEP_LABELS, AI_STEP_NEEDS, AI_STEP_PART_TOKENS, AI_STEP_TYPICAL_TOKENS, AiCallStatus, AiCapability, AiFeature, AiGenerationStage, AiKeyMode, AiLimit, AiNextKind, AiProviderId, AiRefusalCode, AiStep, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CONTENT_ROLE_MEANINGS, CREDITS_PER_USD, CardBindTarget, CheckSeverity, ComposeError, ComposeIssueCode, ContentRole, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, DEFAULT_SITE_LOCALE, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, EntranceSide, FACT_KEYS, FINAL_GENERATION_STAGES, FINDING_SEVERITY, GRAMMAR_TOO_LARGE_MESSAGE, GlobalSlot, HEBREW_PREFIXES, JSON_SCHEMA_BANNED_KEYWORDS, JsonSchemaShapeError, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NO_TOKENS, NavPagesSource, NavRole, NavShape, NavShapeError, PAGE_ARCHETYPES, PLAN_EDITS_ANSWER_SHAPES, PLAN_EDITS_PART_SCHEMA_NAMES, PLAN_EDIT_OP_PART, PLAN_EDIT_SHAPE, PLAN_EDIT_WIRE_KEYS, PLAN_PARTS, PLAN_PART_KEYS, PLAN_WIRE_DERIVED, PLAN_WIRE_PART_SCHEMA_NAMES, PLAN_WIRE_SHAPE, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanChangeAction, PlanChangeKind, PlanDataSourceMode, PlanDataSourceType, PlanEditIssueCode, PlanEditOp, PlanEditsOutcome, PlanPart, PlanWireEntry, PlanWireShapeError, PlanWordIssueCode, PreflightRefusalCode, PublishRefusalCode, REQUIRED_CONTENT_ROLES, RelativeOp, SAMPLE_IMAGE_REF, SITE_CHECKS, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_LIBRARY, SITE_LOCALES, SITE_NEED_IDS, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_ARCHETYPES, SPEC_SITE_COPY_LENGTHS, SPEC_SITE_DENSITY_COPY, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_LOCALES, SPEC_SITE_NEED_IDS, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_REQUIRED_ROLES, SPEC_SITE_ROLES, SPEC_SITE_TEMPLATES, STOCK_FAMILIES, STOCK_PROVIDER_TERMS, STRICT_SCHEMA_BUDGET, STRICT_SCHEMA_LIMITS, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SiteCheckId, SiteFindingCode, SiteLocale, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, StepState, StockProviderId, addBarItem, addStockCredits, aiStepParts, applyPlanEdits, applyStockPhotos, archetypeIssues, assertStyleSlots, assertValidSitePlan, auditSite, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, contentTypePreviewFields, contentTypeToWire, copyLengthOf, costUsd, createSerializedNode, creditsOfUsd, dataSourceToWire, derivedDataSources, describePlanData, describeShapeKey, entranceAction, entranceInteraction, estimateStepCredits, expandPlanWire, expandWireContentType, expandWireDataSource, expandWireEdit, expandWireField, expandWirePage, expandWireSection, failedBuildStep, fieldToWire, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, isRtlLocale, jsonAnyOf, jsonBoolean, jsonClosedObject, jsonInteger, jsonListOf, jsonOneOf, jsonSchemaKeywords, jsonSchemaObjects, jsonShapedObject, jsonText, modelCanDo, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, pageToWire, parsePatternPath, parseSampleImageRef, pathAt, patternById, patternHasForm, patternLinkSlots, patternListGap, patternManifest, patternNeedsBinding, patternNodes, patternOptionalParts, patternRoleNeeds, patternScopes, patternSlotBudgets, patternSlots, patternTakesBinding, phoneMenuPages, planEditOps, planEditToWire, planEditWireGaps, planEditWireKeys, planEditWireOps, planEditWireShape, planEditsFromWire, planEditsJsonSchema, planEditsToWire, planEntrances, planFromTemplate, planNavShape, planPartOfPath, planPartToWire, planStockPhotos, planToWire, planWireGaps, planWirePartJsonSchema, planWirePartShape, planWordIssues, publishRefusal, publishVerdict, recipeListBinds, releasedLayoutDefaults, removeBarItem, requiredAcknowledgements, requiredShapeKeys, roleField, routeMatches, routeParams, sampleImageRef, sectionEntrances, sectionPatternIds, sectionToWire, setStyleProps, shapeKeys, showcaseGlobals, showcasePages, showcasePlans, siteNavPages, slotBudget, stockCopyKey, stockCreditLine, stockCreditLines, stockCreditNode, stockCreditNodeId, stockSlots, strictSchemaComplexity, strictSchemaRefusal, typicalStepTokens, validatePlanEdits, validateSitePlan, walkSerialized, wireContentTypeJsonSchema, wireDataSourceJsonSchema, wireFieldJsonSchema, wirePageJsonSchema, wireSectionJsonSchema, withDerivedSources, wordPattern, writtenTexts };
-export type { AddBarItemResult, AiEntitlementsView, AiMeter, AiModelEntry, AiRefusal, AiTokenCounts, AiTokenPrice, AuditPage, AuditPlaceholder, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentRoles, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, DynamicKeysAsList, EntranceAction, EntranceActionOptions, EntranceInteraction, EntranceMark, EntranceSpec, EntranceStamp, FactKey, JsonSchema, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageArchetype, PageArchetypeId, PageArchetypeSlot, PageData, PageDataLine, PagePlan, PageSectionPlan, PageSeoPlan, PathIssue, PatternManifestEntry, PatternNode, PatternPath, PatternRoleNeed, PlainObject, PlanChange, PlanEdit, PlanEditIssue, PlanEditResult, PlanEditsAnswer, PlanEntrancesInput, PlanWireContext, PlanWireParts, PlanWordContext, PlanWordIssue, PreflightRefusal, PublishRefusal, RecipeListBinds, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, ShowcaseInput, SiteAudit, SiteAuditOptions, SiteAuditSnapshot, SiteBuildRun, SiteBusiness, SiteCheck, SiteFinding, SiteNeedId, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, StockCredit, StockLink, StockPhoto, StockPlacement, StockProviderTerms, StockSlot, StrictSchemaComplexity, StrictSchemaRefusal, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord, WireOptions, WrittenText };
+export { ACTIVE_BUILD_STATUSES, AI_REFUSAL_NEXT, AI_REFUSAL_STATUS, AI_STEPS, AI_STEP_LABELS, AI_STEP_NEEDS, AI_STEP_PART_TOKENS, AI_STEP_TYPICAL_TOKENS, AiCallStatus, AiCapability, AiFeature, AiGenerationStage, AiKeyMode, AiLimit, AiNextKind, AiProviderId, AiRefusalCode, AiStep, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CONTENT_ROLE_MEANINGS, CREDITS_PER_USD, CardBindTarget, CheckSeverity, ComposeError, ComposeIssueCode, ContentRole, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, DEFAULT_SITE_LOCALE, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, EntranceSide, FACT_KEYS, FINAL_GENERATION_STAGES, FINDING_SEVERITY, GRAMMAR_TOO_LARGE_MESSAGE, GlobalSlot, HEBREW_PREFIXES, JSON_SCHEMA_BANNED_KEYWORDS, JsonSchemaShapeError, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NO_TOKENS, NavPagesSource, NavRole, NavShape, NavShapeError, PAGE_ARCHETYPES, PLAN_EDITS_ANSWER_SHAPES, PLAN_EDITS_PART_SCHEMA_NAMES, PLAN_EDIT_OP_PART, PLAN_EDIT_SHAPE, PLAN_EDIT_WIRE_KEYS, PLAN_PARTS, PLAN_PART_KEYS, PLAN_WIRE_DERIVED, PLAN_WIRE_PART_SCHEMA_NAMES, PLAN_WIRE_SHAPE, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanChangeAction, PlanChangeKind, PlanDataSourceMode, PlanDataSourceType, PlanEditIssueCode, PlanEditOp, PlanEditsOutcome, PlanPart, PlanWireEntry, PlanWireShapeError, PlanWordIssueCode, PreflightRefusalCode, PublishRefusalCode, REQUIRED_CONTENT_ROLES, RelativeOp, SAMPLE_IMAGE_REF, SITE_CHECKS, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_LIBRARY, SITE_LOCALES, SITE_NEED_IDS, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_ARCHETYPES, SPEC_SITE_COPY_LENGTHS, SPEC_SITE_DENSITY_COPY, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_LOCALES, SPEC_SITE_NEED_IDS, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_REQUIRED_ROLES, SPEC_SITE_ROLES, SPEC_SITE_TEMPLATES, STOCK_FAMILIES, STOCK_FAMILY_INTENTS, STOCK_INTENT_ORDER, STOCK_INTENT_SUBJECTS, STOCK_ITEM_ASPECT, STOCK_MIN_KEPT, STOCK_PROVIDER_TERMS, STOCK_SUBJECT_WORDS, STRICT_SCHEMA_BUDGET, STRICT_SCHEMA_LIMITS, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SiteCheckId, SiteFindingCode, SiteLocale, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, StepState, StockIntent, StockOrientation, StockProviderId, StockReviewFlag, StockReviewVerdict, StockSlotKind, StockSubject, addBarItem, addStockCredits, aiStepParts, applyPlanEdits, applyStockItemPhotos, applyStockPhotos, archetypeIssues, aspectRatioOf, assertStyleSlots, assertValidSitePlan, auditSite, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, contentTypePreviewFields, contentTypeToWire, copyLengthOf, costUsd, createSerializedNode, creditsOfUsd, dataSourceToWire, derivedDataSources, describePlanData, describeShapeKey, entranceAction, entranceInteraction, estimateStepCredits, expandPlanWire, expandWireContentType, expandWireDataSource, expandWireEdit, expandWireField, expandWirePage, expandWireSection, failedBuildStep, fieldToWire, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, isRtlLocale, jsonAnyOf, jsonBoolean, jsonClosedObject, jsonInteger, jsonListOf, jsonOneOf, jsonSchemaKeywords, jsonSchemaObjects, jsonShapedObject, jsonText, modelCanDo, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, orientationOfRatio, pageToWire, parsePatternPath, parseSampleImageRef, pathAt, patternById, patternHasForm, patternLinkSlots, patternListGap, patternManifest, patternNeedsBinding, patternNodes, patternOptionalParts, patternRoleNeeds, patternScopes, patternSlotBudgets, patternSlots, patternTakesBinding, phoneMenuPages, planEditOps, planEditToWire, planEditWireGaps, planEditWireKeys, planEditWireOps, planEditWireShape, planEditsFromWire, planEditsJsonSchema, planEditsToWire, planEntrances, planFromTemplate, planNavShape, planPartOfPath, planPartToWire, planStockPhotos, planToWire, planWireGaps, planWirePartJsonSchema, planWirePartShape, planWordIssues, publishRefusal, publishVerdict, recipeListBinds, releasedLayoutDefaults, removeBarItem, requiredAcknowledgements, requiredShapeKeys, roleField, routeMatches, routeParams, sampleImageRef, scoreStockPhoto, sectionEntrances, sectionPatternIds, sectionToWire, setStyleProps, shapeKeys, showcaseGlobals, showcasePages, showcasePlans, siteNavPages, slotBudget, stockCopyKey, stockCreditLine, stockCreditLines, stockCreditNode, stockCreditNodeId, stockFits, stockGroupOf, stockItemSlots, stockKept, stockPhotoRatio, stockPhotoSubject, stockPhotoUsable, stockPhotoWords, stockSlots, stockWord, stockWords, strictSchemaComplexity, strictSchemaRefusal, typicalStepTokens, validatePlanEdits, validateSitePlan, walkSerialized, wireContentTypeJsonSchema, wireDataSourceJsonSchema, wireFieldJsonSchema, wirePageJsonSchema, wireSectionJsonSchema, withDerivedSources, wordPattern, writtenTexts };
+export type { AddBarItemResult, AiEntitlementsView, AiMeter, AiModelEntry, AiRefusal, AiTokenCounts, AiTokenPrice, AuditPage, AuditPlaceholder, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentRoles, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, DynamicKeysAsList, EntranceAction, EntranceActionOptions, EntranceInteraction, EntranceMark, EntranceSpec, EntranceStamp, FactKey, JsonSchema, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageArchetype, PageArchetypeId, PageArchetypeSlot, PageData, PageDataLine, PagePlan, PageSectionPlan, PageSeoPlan, PathIssue, PatternManifestEntry, PatternNode, PatternPath, PatternRoleNeed, PlainObject, PlanChange, PlanEdit, PlanEditIssue, PlanEditResult, PlanEditsAnswer, PlanEntrancesInput, PlanWireContext, PlanWireParts, PlanWordContext, PlanWordIssue, PreflightRefusal, PublishRefusal, RecipeListBinds, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, ShowcaseInput, SiteAudit, SiteAuditOptions, SiteAuditSnapshot, SiteBuildRun, SiteBusiness, SiteCheck, SiteFinding, SiteNeedId, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, StockCredit, StockItemSlot, StockLink, StockNeed, StockPhoto, StockPhotoTraits, StockPlacement, StockPlanOptions, StockProviderTerms, StockReview, StockSlot, StockTarget, StrictSchemaComplexity, StrictSchemaRefusal, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord, WireOptions, WrittenText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.66.1",
+  "version": "5.67.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

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

@@ -34,4 +34,5 @@ export * from './strict-schema';
 export * from './plan-edits';
 export * from './plan-words';
 export * from './audit-site';
+export * from './stock-match';
 export * from './stock-photos';

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

@@ -126,6 +126,9 @@ export enum BuildNoticeCode {
     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',
+    /** 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',
 }
 
 export interface BuildNotice {

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

@@ -0,0 +1,238 @@
+/**
+ * How a stock photo is judged against a picture slot (AI plan §3g, I2.1) — pure and deterministic, so the same plan and
+ * the same library always place the same photos. A photo is described by what the library's manifest carries (the
+ * provider's tags, its orientation, the reviewer's subject and notes — each optional, derived when absent); a slot by
+ * its INTENT (what kind of picture its section wants), its aspect ratio and the plan's words around it.
+ */
+
+export enum StockOrientation {
+    Horizontal = 'horizontal',
+    Vertical = 'vertical',
+    Square = 'square',
+}
+
+/** What a photo mainly shows — the reviewer may set it; otherwise it is read from the provider's tags. */
+export enum StockSubject {
+    /** A room, a shop front, a garden — somewhere. */
+    Place = 'place',
+    /** A close-up: a texture, a tool, an ingredient. */
+    Detail = 'detail',
+    /** A thing a business sells or serves: a cake, a bottle, a bouquet. */
+    Product = 'product',
+}
+
+/** What a slot wants to show. */
+export enum StockIntent {
+    /** The hero / a page header / a call to action: wide and atmospheric. */
+    Atmosphere = 'atmosphere',
+    /** A story or a visit section: the place. */
+    Place = 'place',
+    /** A feature row: a detail of the work or the service. */
+    Detail = 'detail',
+    /** A list item's picture (a product, a service, a dish). */
+    Product = 'product',
+}
+
+export enum StockReviewVerdict {
+    Approved = 'approved',
+    Rejected = 'rejected',
+}
+
+/** What the review found in a photo that keeps it out of every site (the licence: no person, no logo or brand). */
+export enum StockReviewFlag {
+    Person = 'person',
+    Logo = 'logo',
+}
+
+/** The operator's one review of a photo, as the manifest records it. */
+export interface StockReview {
+    verdict: `${StockReviewVerdict}`;
+    flags?: Array<`${StockReviewFlag}`>;
+    /** The reviewer's own words for it — they count as tags when placing it. */
+    notes?: string;
+}
+
+/** The section families a stock photo may stand in for a picture in, and what each wants. */
+export const STOCK_FAMILY_INTENTS: Readonly<Record<string, StockIntent>> = {
+    hero: StockIntent.Atmosphere,
+    header: StockIntent.Atmosphere,
+    cta: StockIntent.Atmosphere,
+    story: StockIntent.Place,
+    contact: StockIntent.Place,
+    feature: StockIntent.Detail,
+    content: StockIntent.Detail,
+};
+
+/** Per intent, the subjects it takes, best first. */
+export const STOCK_INTENT_SUBJECTS: Readonly<Record<StockIntent, ReadonlyArray<StockSubject>>> = {
+    [StockIntent.Atmosphere]: [StockSubject.Place, StockSubject.Detail, StockSubject.Product],
+    [StockIntent.Place]: [StockSubject.Place, StockSubject.Detail, StockSubject.Product],
+    [StockIntent.Detail]: [StockSubject.Detail, StockSubject.Product, StockSubject.Place],
+    [StockIntent.Product]: [StockSubject.Product, StockSubject.Detail, StockSubject.Place],
+};
+
+/** The order slots choose in: the hero picks first, a list item last. */
+export const STOCK_INTENT_ORDER: ReadonlyArray<StockIntent> = [StockIntent.Atmosphere, StockIntent.Place, StockIntent.Detail, StockIntent.Product];
+
+/** The words that tell a photo's subject when the reviewer did not name it (singular, lower case). */
+export const STOCK_SUBJECT_WORDS: Readonly<Record<StockSubject, ReadonlyArray<string>>> = {
+    [StockSubject.Place]: [
+        'room', 'interior', 'studio', 'salon', 'shop', 'store', 'boutique', 'restaurant', 'cafe', 'bar', 'bakery', 'cellar', 'kitchen',
+        'gym', 'clinic', 'office', 'lobby', 'hall', 'building', 'architecture', 'facade', 'exterior', 'street', 'garden', 'terrace',
+        'patio', 'pool', 'sauna', 'window', 'landscape', 'view', 'beach', 'forest', 'mountain', 'city', 'house', 'workshop', 'counter',
+        'shelf', 'reception', 'spa', 'hotel', 'bedroom', 'bathroom', 'living', 'courtyard', 'vineyard', 'market',
+    ],
+    [StockSubject.Detail]: [
+        'texture', 'detail', 'closeup', 'macro', 'pattern', 'fabric', 'wood', 'wooden', 'stone', 'marble', 'leaf', 'towel', 'tool',
+        'equipment', 'ingredient', 'spice', 'grain', 'bean', 'oil', 'water', 'steam', 'shadow', 'paper', 'thread', 'brush', 'ceramic',
+    ],
+    [StockSubject.Product]: [
+        'product', 'bottle', 'wine', 'beer', 'coffee', 'cup', 'mug', 'tea', 'cake', 'bread', 'pastry', 'croissant', 'cookie', 'dessert',
+        'chocolate', 'food', 'dish', 'plate', 'meal', 'pizza', 'salad', 'soup', 'burger', 'fruit', 'flower', 'bouquet', 'jewelry',
+        'jewellery', 'ring', 'necklace', 'cosmetic', 'cream', 'soap', 'perfume', 'candle', 'shoe', 'bag', 'dress', 'clothing', 'book', 'toy',
+    ],
+};
+
+/** Words that say nothing about what a picture shows (the plan's sample and placeholder words among them). */
+const STOP_WORDS: ReadonlySet<string> = new Set([
+    'the', 'and', 'with', 'for', 'your', 'our', 'you', 'from', 'into', 'this', 'that', 'here', 'there', 'about', 'page', 'section',
+    'sample', 'replace', 'image', 'photo', 'picture', 'sentence', 'words', 'own', 'how', 'what', 'who', 'are', 'all', 'one', 'two',
+    'three', 'more', 'less', 'very', 'tell', 'story', 'item', 'service', 'project',
+]);
+const MIN_WORD = 3;
+const HTML_TAG = /<[^>]*>/g;
+const WORD_SPLIT = /[^\p{L}\p{N}]+/u;
+
+/** Nominal ratios (width / height) of an orientation when the manifest gives no size. */
+const ORIENTATION_RATIO: Readonly<Record<StockOrientation, number>> = {
+    [StockOrientation.Horizontal]: 3 / 2,
+    [StockOrientation.Vertical]: 2 / 3,
+    [StockOrientation.Square]: 1,
+};
+/** The share of a photo a slot may crop away and still be a fit: a portrait never fills a 21 / 9 band. */
+export const STOCK_MIN_KEPT = 0.5;
+/** What an unknown shape keeps, for scoring only (neither rewarded nor refused). */
+const UNKNOWN_KEPT = 0.75;
+
+/** Score weights — subject, then shape, then the plan's own words, then the business type's imagery words. */
+const SUBJECT_POINTS: ReadonlyArray<number> = [4, 2, 1];
+const UNKNOWN_SUBJECT_POINTS = 1.5;
+const SHAPE_POINTS = 4;
+const WORD_POINTS = 2;
+const MAX_WORD_MATCHES = 3;
+const IMAGERY_POINTS = 1;
+const MAX_IMAGERY_MATCHES = 2;
+
+/**
+ * A word as compared — a canonical form, never shown: lower case, a plain plural made singular, and `-ie` / `-y` one
+ * ending (English cannot tell `cookies` from `pastries` by rule, so `cookie`, `cookies`, `pastry`, `pastries` all
+ * fold to the same shape as their singular).
+ */
+export function stockWord(raw: string): string {
+    let w = raw.toLowerCase();
+    if (w.length > 3 && w.endsWith('s') && !w.endsWith('ss') && !STOP_WORDS.has(w)) w = w.slice(0, -1);
+    return w.length > 3 && w.endsWith('ie') ? `${w.slice(0, -2)}y` : w;
+}
+
+/** The meaningful words of a text, in order, each once. */
+export function stockWords(...texts: ReadonlyArray<unknown>): string[] {
+    const out = new Set<string>();
+    for (const text of texts) {
+        if (typeof text !== 'string') continue;
+        for (const raw of text.replace(HTML_TAG, ' ').split(WORD_SPLIT)) {
+            const w = stockWord(raw);
+            if (w.length >= MIN_WORD && !STOP_WORDS.has(w) && !/^\d+$/.test(w)) out.add(w);
+        }
+    }
+    return [...out];
+}
+
+/** A CSS aspect ratio (`4 / 3`, `1.5`) as width / height, or undefined. */
+export function aspectRatioOf(aspect: unknown): number | undefined {
+    if (typeof aspect === 'number') return aspect > 0 ? aspect : undefined;
+    if (typeof aspect !== 'string') return undefined;
+    const [w, h] = aspect.split('/').map(s => Number(s.trim()));
+    const ratio = h === undefined ? w : w / h;
+    return Number.isFinite(ratio) && ratio > 0 ? ratio : undefined;
+}
+
+/** What the planner reads of a library photo. */
+export interface StockPhotoTraits {
+    alt: string;
+    width?: number;
+    height?: number;
+    tags?: ReadonlyArray<string>;
+    orientation?: `${StockOrientation}`;
+    subject?: `${StockSubject}`;
+    review?: StockReview;
+}
+
+/** A photo may be placed: not rejected and nothing flagged by the review. */
+export function stockPhotoUsable(photo: Pick<StockPhotoTraits, 'review'>): boolean {
+    return photo.review?.verdict !== StockReviewVerdict.Rejected && !(photo.review?.flags?.length);
+}
+
+/** The words a photo is placed by: its tags (else its alt — the provider's own words) and the reviewer's notes. */
+export function stockPhotoWords(photo: Pick<StockPhotoTraits, 'alt' | 'tags' | 'review'>): string[] {
+    const tags = photo.tags?.length ? photo.tags.join(', ') : photo.alt;
+    return stockWords(tags, photo.review?.notes);
+}
+
+/** Its width / height: the size when known, else its orientation's nominal shape, else undefined. */
+export function stockPhotoRatio(photo: Pick<StockPhotoTraits, 'width' | 'height' | 'orientation'>): number | undefined {
+    if (photo.width && photo.height && photo.width > 0 && photo.height > 0) return photo.width / photo.height;
+    return photo.orientation ? ORIENTATION_RATIO[photo.orientation as StockOrientation] : undefined;
+}
+
+/** The orientation of a width / height ratio. */
+export function orientationOfRatio(ratio: number): StockOrientation {
+    if (ratio > 1.05) return StockOrientation.Horizontal;
+    return ratio < 0.95 ? StockOrientation.Vertical : StockOrientation.Square;
+}
+
+/** The reviewer's subject, else the one its words name most (ties: the enum's order), else undefined. */
+export function stockPhotoSubject(photo: Pick<StockPhotoTraits, 'alt' | 'tags' | 'review' | 'subject'>): StockSubject | undefined {
+    if (photo.subject && (Object.values(StockSubject) as string[]).includes(photo.subject)) return photo.subject as StockSubject;
+    const words = new Set(stockPhotoWords(photo));
+    let best: StockSubject | undefined;
+    let most = 0;
+    for (const subject of Object.values(StockSubject)) {
+        const n = STOCK_SUBJECT_WORDS[subject].filter(w => words.has(stockWord(w))).length;
+        if (n > most) { most = n; best = subject; }
+    }
+    return best;
+}
+
+/** What a slot asks of a photo. */
+export interface StockNeed {
+    intent: `${StockIntent}`;
+    /** The slot's width / height (undefined: any shape). */
+    aspect?: number;
+    /** The plan's words around the slot. */
+    words: ReadonlyArray<string>;
+}
+
+/** The share of the photo a slot shows (1 = the same shape), or undefined when either shape is unknown. */
+export function stockKept(photo: Pick<StockPhotoTraits, 'width' | 'height' | 'orientation'>, aspect: number | undefined): number | undefined {
+    const ratio = stockPhotoRatio(photo);
+    if (!ratio || !aspect) return undefined;
+    return Math.min(ratio, aspect) / Math.max(ratio, aspect);
+}
+
+/** A photo fits a slot when the slot keeps at least half of it (an unknown shape fits). */
+export function stockFits(photo: Pick<StockPhotoTraits, 'width' | 'height' | 'orientation'>, need: Pick<StockNeed, 'aspect'>): boolean {
+    const kept = stockKept(photo, need.aspect);
+    return kept === undefined || kept >= STOCK_MIN_KEPT;
+}
+
+/** How well a photo answers a slot: its subject for the intent, its shape, the plan's words and the type's imagery. */
+export function scoreStockPhoto(photo: StockPhotoTraits, need: StockNeed, imagery: ReadonlyArray<string> = []): number {
+    const subject = stockPhotoSubject(photo);
+    const rank = subject ? STOCK_INTENT_SUBJECTS[need.intent as StockIntent].indexOf(subject) : -1;
+    const subjectPoints = subject ? SUBJECT_POINTS[rank] ?? 0 : UNKNOWN_SUBJECT_POINTS;
+    const shapePoints = SHAPE_POINTS * (stockKept(photo, need.aspect) ?? UNKNOWN_KEPT);
+    const words = new Set(stockPhotoWords(photo));
+    const matched = need.words.filter(w => words.has(w)).length;
+    const imageryMatched = imagery.filter(w => words.has(w)).length;
+    return subjectPoints + shapePoints + WORD_POINTS * Math.min(MAX_WORD_MATCHES, matched) + IMAGERY_POINTS * Math.min(MAX_IMAGERY_MATCHES, imageryMatched);
+}