@aglyn/plugins-ai 1.0.0-beta.242 → 1.0.0-beta.244

package/src/lib/jobs/ai-layout-stock-photos.d.ts

@@ -106,6 +106,16 @@ import { type AiLayoutPictureSlot, type AiLayoutPictureSource } from '../layout-
  *    searches, and then — a product or a hero only — reuses an on-topic photo
  *    the job already shows rather than take a starter. Every slot of a
  *    craft's site tries the craft's broad searches last.
+ * 7. **A product takes the surest photo, even a borrowed one** (the beta.242
+ *    Tidewater Soap Works start: a sauna for "Bath Gift Set", colognes for
+ *    "Natural Body Lotion", a bathroom shelf for "Soap Bar Trio" and a soap
+ *    dispenser for its starter size, while the collection tiles beside them
+ *    were good). A product's searches are ranked by how sure they are: its
+ *    own photo (the head noun or its kin among the first tags), then a photo
+ *    OF its category, new or one the job already shows, then a weak hit of
+ *    its own. No product shows a room or a scene, a fragrance bottle, or what
+ *    its kin shuns (a pump for a bar) unless it names it; "bath" in a bath
+ *    gift set is what the set is for; a size is never the product.
  *
  * A slot nothing acceptable answered — the library down, refusing, or out
  * of time — is left `null` for the starter photos. A named object is never
@@ -185,6 +195,8 @@ export interface AiStockSiteTerms {
      * site names no craft.
      */
     core: string[];
+    /** Words no photo of the site's craft carries unless the slot or the brief names them ({@link CRAFT_KIN}). */
+    shun: string[];
 }
 /** The site's terms, read from its business type. */
 export declare function aiStockSiteTerms(businessType: string): AiStockSiteTerms;
@@ -229,6 +241,19 @@ export interface AiStockSearch extends StockPhotoSearchRequest {
     lead?: boolean;
     /** Whether the hit's first tags must name the site's world, where the object need not lead (AGL-3660). */
     leadWorld?: boolean;
+    /** Phrases (as stems) of which one must be among the hit's first tags: a borrowed photo is OF the product's category (AGL-3660). */
+    leadAny?: readonly string[];
+    /** Whether it fills a product: no room, no scene, no fragrance bottle ({@link PRODUCT_SCENES}, AGL-3660). */
+    product?: boolean;
+    /** Words its hits never carry unless the slot or the brief names them ({@link AiStockSiteTerms.shun}). */
+    shun?: readonly string[];
+    /**
+     * How sure a product's search is (AGL-3660). Absent: its own photo, the
+     * head noun among the first tags. `borrow`: a photo OF its category, which
+     * may repeat one the job already shows. `weak`: the head noun anywhere, or
+     * the category anywhere — taken only once nothing surer is left.
+     */
+    tier?: 'borrow' | 'weak';
 }
 /** A slot's part of a page, where it asks for more than its role: a collection tile or a story of the craft (AGL-3660). */
 export type AiStockSlotPart = 'collection' | 'story';
@@ -267,16 +292,29 @@ export interface AiStockProductFallback {
  * back to its own craft (AGL-3660). The Saltmarsh Soap Co start (2026-10-10)
  * found no hit naming "bar" or "box" among the first tags, and four of its
  * five products took the starter photos — a laptop and roses, a living room
- * of plants. So, in order:
+ * of plants. And the beta.242 Tidewater Soap Works start (2026-10-11) showed
+ * that the head noun anywhere is not enough: its own weak hits put a sauna
+ * under "Bath Gift Set", colognes under "Natural Body Lotion", a bathroom
+ * shelf under "Soap Bar Trio" and a soap dispenser under its starter size,
+ * while the collection tiles beside them, searched for the category, were
+ * good. So the searches are ranked by how sure they are ({@link AiStockSearch.tier}):
  *
- * 1. The same searches again, the head noun named anywhere among the tags
- *    (no extra search: the page remembers its answers), and a gift's own
- *    wrapper with the craft ("soap gift box").
- * 2. The site's broad searches ("handmade soap", "natural skincare"), any hit
- *    naming the craft itself ({@link AiStockSiteTerms.core}).
+ * 1. Its own: the head noun (or its kin) among the first tags, as above.
+ * 2. `borrow`: a photo OF its category — the category alone, then the craft's
+ *    broad searches ("handmade soap", "natural skincare"), one of the
+ *    product's kin or the craft's own names among the first tags. A product
+ *    may repeat one the job already shows, a collection tile's photo or
+ *    another product's ({@link aiLayoutStockPhotoSource}): a borrowed
+ *    on-topic photo beats a weak specific one.
+ * 3. `weak`: the same searches again, the head noun named anywhere among the
+ *    tags (no extra search: the page remembers its answers), a gift's own
+ *    wrapper with the craft ("soap gift box"), and the craft's broad searches,
+ *    any hit naming the craft itself ({@link AiStockSiteTerms.core}).
  *
- * The source then reuses an on-topic photo another slot of the job already
- * shows before it gives up ({@link aiLayoutStockPhotoSource}).
+ * Every one of them turns down a room or a scene, a fragrance bottle, and
+ * what the product's kin shuns (a pump for a bar of soap), unless the
+ * product names it. A size never names the product: "Bath Gift Set Starter
+ * Size" is a bath gift set.
  */
 export declare function aiStockProductSearches(slot: Pick<AiLayoutPictureSlot, 'aspect' | 'product'>, craft: string, domain?: readonly string[], fallback?: AiStockProductFallback): AiStockSearch[];
 /** The searches a slot tries, in order, most specific first, each distinct. */
@@ -311,6 +349,12 @@ export interface AiStockJudgement {
         words: readonly string[];
         core: readonly string[];
     }>;
+    /** Phrases of which one must be among the hit's first tags ({@link AiStockSearch.leadAny}). */
+    leadAny?: readonly string[];
+    /** Whether it judges for a product: no room, no scene, no fragrance bottle (AGL-3660). */
+    product?: boolean;
+    /** Words a hit never carries unless the subject or the brief names them ({@link AiStockSiteTerms.shun}). */
+    shun?: readonly string[];
 }
 /**
  * Whether a hit carries a topic its site never named ({@link SENSITIVE_TOPICS}):