@aglyn/plugins-ai 1.0.0-beta.237 → 1.0.0-beta.239

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

@@ -27,51 +27,75 @@ import { type AiLayoutPictureSlot, type AiLayoutPictureSource } from '../layout-
  * server door (`core.media-ingest`), and builds no source at all when either
  * is missing, so a deployment without a key behaves exactly as before.
  *
- * For each slot, in document order:
+ * What the live starts of 2026-10-10 taught (Juniper Clay Works, a ceramic
+ * artist's portfolio, and Willow Wick Candles, a candle store), each photo
+ * traced through the library's cached answers:
  *
- * 1. **Search.** Plain words. The hero asks for the kind of business (the
- *    head of the site's business type, "yoga studio" from "a family-owned
- *    yoga studio in Austin"). Any other picture asks for its SUBJECT: the
- *    noun phrase that opens the alt text the model wrote, its filler
- *    adjectives dropped ("serving bowl" from "A beautiful hand-thrown serving
- *    bowl on a linen cloth"), qualified by the site's craft where the phrase
- *    does not already say it ("serving bowl ceramic" for a ceramics studio).
- *    An about picture asks for people. The orientation and a minimum size
- *    come from the slot's frame. The provider caches every search for a day
- *    and keeps its own rate limit; one page never asks the same words twice.
- * 2. **Rank.** A picture of a thing must show the thing: every hit is scored
- *    by how many of the subject's words its tags, its description and its
- *    page's address name (singular and plural alike, the head noun counting
- *    double), and a hit naming none of them never fills a picture of a
- *    thing. The live Juniper Clay start put crackers under "Serving bowl"
- *    and plants under "Espresso cup". Among the best-scored hits the job's
- *    seed picks, so two sites built from the same words rarely open with the
- *    same photo while one job always picks the same.
- * 3. **Never twice.** A photo is placed once per job: not twice on a page,
+ * - The site's words were read as "portfolio" and "online" — the kind of
+ *   SITE, not the craft — so every search said "serving bowl portfolio" and
+ *   the hero asked for "portfolio": a wallet, fashion models, and a blank
+ *   paper mockup that read as an empty panel beside the brushes.
+ * - A hit naming the object anywhere won: a robin tagged "food bowl" filled
+ *   "Speckled serving bowl", a lilac branch tagged "bud, vase" filled "Tall
+ *   bud vase", letterpress type tagged "set" filled "Nesting bowl set" (its
+ *   head noun was read as "set"), and an antique tea set tagged "brown
+ *   candle" filled "Candle Gift Set".
+ * - The page's 20 seconds ran out after four photos (each copy took ~5s, one
+ *   after another), and the slots left took the starter photos: the laptop
+ *   desk with pink roses under "Candle Wick Trimmer" and a work card, and the
+ *   windowsill plants under another.
+ *
+ * So, for each slot:
+ *
+ * 1. **The site's terms** ({@link aiStockSiteTerms}): the business is the
+ *    first clause of its type that says more than what kind of site it is
+ *    ("ceramic artist" from "a portfolio for a ceramic artist who makes
+ *    stoneware bowls"), its craft one word ("ceramic"), and its DOMAIN the
+ *    words a photo of its world names: the craft, the business type's own
+ *    nouns ("stoneware", "soy") and, for common crafts, their kin ("pottery",
+ *    "clay", "wax"). Its broad searches ask for the world itself ("handmade
+ *    ceramics", "pottery").
+ * 2. **Search.** A picture of a thing asks for its subject — the noun phrase
+ *    of the caption, filler dropped — qualified by the craft where it does
+ *    not already name the domain ("ceramic serving bowl"), then the craft and
+ *    the object alone ("ceramic bowl"), then the broad searches. A hero asks
+ *    for the business, then broad; an about picture for the business's
+ *    people, then broad. The orientation and a minimum size come from the
+ *    slot's frame.
+ * 3. **Accept, or reject.** A hit tagged as a mockup, a blank or a template
+ *    never fills anything. A picture of a thing takes only a hit naming its
+ *    OBJECT (the head noun, past "set", "gift", "kit": "bowl" in "nesting
+ *    bowl set", "candle" in "candle gift set") AND either the site's domain
+ *    or the subject's own two-word phrase ("bud vase"). A broad, hero or
+ *    about search takes only a hit naming the domain. The accepted are
+ *    ranked: the object in the hit's first tags (what the photo is OF) over
+ *    a mention in its last, the subject's other words, the domain. Among
+ *    equals the job's seed picks, so two sites differ and one job repeats.
+ * 4. **Never twice.** A photo is placed once per job: not twice on a page,
  *    and not on a page when another page (or another pass, in this process)
- *    of the same job already placed it — the maker's portrait in About is
- *    never a vase in Selected work. The caller hands in what the job's other
- *    pages hold (`avoid`); a pass repeated over its own page keeps its own.
- * 4. **Fall back.** A picture of a thing nothing relevant answered asks once
- *    more for the place itself ("ceramics studio interior"), a neutral photo
- *    any caption sits under, before it is left to a starter photo.
- * 5. **Keep.** A photo the site's library already holds (by its source key)
- *    is reused; otherwise its bytes are downloaded from the library and
- *    stored in the site's own media library as the member who started the
- *    job, credited to its photographer. The page names the site's asset,
- *    never the library's address.
+ *    of the same job already placed it. The caller hands in what the job's
+ *    other pages hold (`avoid`); a pass repeated over its own page keeps its
+ *    own.
+ * 5. **Keep, all at once.** The choosing is done first, slot by slot; the
+ *    copies then run side by side, a few at a time, so a page of eight
+ *    pictures takes about as long as two. A photo the site's library already
+ *    holds (by its source key) is reused; otherwise its bytes are copied
+ *    into the site's own library as the member who started the job, credited
+ *    to its photographer. A copy that fails tries the slot's next accepted
+ *    hit.
  *
- * A slot that finds nothing, any error, a refusal from the library (its
- * storage band, say) or the time running out leaves the slot to a starter
- * photo. Nothing here throws, and none of it is an AI model call: photos cost
- * no AI credits.
+ * 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
+ * given one while the library answers anything of the site's world: the
+ * broad searches come first. Nothing here throws, and none of it is an AI
+ * model call: photos cost no AI credits.
  */
 /** Wall clock the whole page's photos may take, inside the step's own signal. */
-export declare const AI_LAYOUT_STOCK_PHOTOS_BUDGET_MS = 20000;
+export declare const AI_LAYOUT_STOCK_PHOTOS_BUDGET_MS = 30000;
 /** Searches one page may send to the provider; a repeated query is answered from the page's own memory. */
-export declare const AI_LAYOUT_STOCK_SEARCHES_PER_PAGE = 12;
+export declare const AI_LAYOUT_STOCK_SEARCHES_PER_PAGE = 18;
 /** The hits a pick is made among. */
-export declare const AI_LAYOUT_STOCK_PICK_WINDOW = 8;
+export declare const AI_LAYOUT_STOCK_PICK_WINDOW = 40;
 /** The largest photo copied: inside one direct upload. */
 export declare const AI_LAYOUT_STOCK_MAX_BYTES: number;
 /**
@@ -87,17 +111,38 @@ export declare const AI_STOCK_PHOTO_PAGES_INPUT = "stockPhotoPages";
 export declare function aiStockStem(word: string): string;
 /**
  * The kind of business in a few words: the first clause of the business
- * type, before a place or an audience, its last three content words (the
- * head of an English noun phrase is at its end).
+ * type that says more than what kind of site it is, before a place, an
+ * audience or what it makes, filler dropped, its last three words (the head
+ * of an English noun phrase is at its end). "ceramic artist" from "a
+ * portfolio for a ceramic artist who makes stoneware bowls"; "candle shop"
+ * from "a small-batch candle shop selling hand-poured soy candles online".
  */
 export declare function aiStockBusinessWords(businessType: string): string;
 /**
  * The business's craft in one word: the last of its words that is not the
- * place it is done in, singular — "ceramic" from "small-batch ceramics
- * studio", "yoga" from "yoga studio". Empty when the business is only a
- * place ("a shop").
+ * place it is done in nor the person doing it, singular — "ceramic" from
+ * "ceramics studio" or "ceramic artist", "yoga" from "yoga studio". Empty
+ * when the business is only a place ("a shop").
  */
 export declare function aiStockCraftWords(business: string): string;
+/** What a site's photos are searched and judged by (AGL-3660). */
+export interface AiStockSiteTerms {
+    /** The kind of business, in a few words: "ceramic artist". */
+    business: string;
+    /** Its craft, one singular word: "ceramic". */
+    craft: string;
+    /**
+     * The stems a photo of the site's world names: the business's own words,
+     * what the things it makes are made of, and the craft's kin. Empty for a
+     * site whose words name no world (a type left blank), and then no hit is
+     * held to it.
+     */
+    domain: string[];
+    /** The searches for the site's world itself, broadest last. */
+    broad: string[];
+}
+/** The site's terms, read from its business type. */
+export declare function aiStockSiteTerms(businessType: string): AiStockSiteTerms;
 /**
  * A picture's subject in a few words (AGL-3660): the noun phrase its alt
  * text opens with — its first clause holding more than filler, cut where a
@@ -105,47 +150,73 @@ export declare function aiStockCraftWords(business: string): string;
  * head noun is the last) — else its section's name.
  */
 export declare function aiStockSubjectWords(alt: string, sectionName: string): string;
+/**
+ * The thing a subject shows, one singular word: its last word that is not
+ * a set or a wrapper of it — "bowl" from "nesting bowl set", "candle" from
+ * "candle gift set", "vase" from "bud vase". Its last word when every word
+ * is one ("gift set").
+ */
+export declare function aiStockObjectWord(subject: string): string;
 /** The frame's orientation: a wide frame wants a landscape photo, a tall one a portrait. */
 export declare function aiStockOrientation(aspect: number): StockPhotoOrientation;
 /**
- * One search a slot tries. A gallery picture's searches must find a hit
- * naming its subject; a `neutral` one asks for the place itself, which any
- * caption sits under.
+ * One search a slot tries. A `broad` one asks for the site's world and
+ * takes any hit of it; any other picture of a thing takes only a hit naming
+ * the thing.
  */
 export interface AiStockSearch extends StockPhotoSearchRequest {
-    neutral?: boolean;
+    broad?: boolean;
+    /** The words its hits are scored by, where they are not the slot's own subject (a product's searches, AGL-3676). */
+    subject?: string;
+    /** A word every hit must name: a product's photo names the shop's category (AGL-3676). */
+    requires?: string;
 }
-/** The searches a slot tries, in order, most specific first, each distinct. */
-export declare function aiStockSearchesFor(slot: Pick<AiLayoutPictureSlot, 'role' | 'alt' | 'aspect'>, words: {
-    business: string;
-    subject: string;
-    craft?: string;
-}): AiStockSearch[];
 /**
- * How well a hit names a subject (AGL-3660): each subject word its tags, its
- * description or its page's address names counts once, the head noun (the
- * subject's last word) twice, and a craft word a quarter, as a tiebreak.
- * Zero when it names none of the subject.
+ * A product's searches (AGL-3676), most specific first: each of its subjects
+ * — its name's noun phrase, then its photo's — with the shop's category
+ * where the phrase does not already say it ("candle gift box"), then the
+ * category alone, a plain photo of what the shop sells. Every one must find a
+ * hit naming the category, so no product is ever filled with a lifestyle shot
+ * of something else: the beta.237 Willow Wick start put a laptop and roses
+ * under "Candle Wick Trimmer" and an antique tea set under "Candle Gift Set".
  */
-export declare function aiStockRelevance(photo: Pick<StockPhoto, 'tags' | 'alt' | 'pageUrl'>, terms: {
-    subject: string;
-    craft?: string;
-}): number;
-export interface AiStockRankOptions {
-    /** The words a hit is scored by; none, and every hit scores alike. */
+export declare function aiStockProductSearches(slot: Pick<AiLayoutPictureSlot, 'aspect' | 'product'>, craft: string): AiStockSearch[];
+/** The searches a slot tries, in order, most specific first, each distinct. */
+export declare function aiStockSearchesFor(slot: Pick<AiLayoutPictureSlot, 'role' | 'alt' | 'aspect'>, terms: Pick<AiStockSiteTerms, 'business' | 'craft' | 'domain' | 'broad'>, subject: string): AiStockSearch[];
+/** What a hit is judged by. */
+export interface AiStockJudgement {
+    /** The words the picture is of; empty for a picture of the site's world. */
     subject?: string;
-    craft?: string;
-    /** A hit naming none of the subject is no candidate at all. */
+    /** The site's domain stems ({@link AiStockSiteTerms.domain}). */
+    domain?: readonly string[];
+    /**
+     * Whether a hit must name the subject's object. A broad search, a hero
+     * and an about picture need only name the domain.
+     */
     strict?: boolean;
+    /** A word every hit must name: a product's photo names the shop's category (AGL-3676). */
+    requires?: string;
 }
 /**
- * A search's hits in the order they are tried (AGL-3660): those not placed
- * yet, among the first few, best-scored first; the seed turns the hits that
- * score alike, so two jobs differ and one job repeats itself.
+ * How well a hit shows what a slot needs (AGL-3660), or 0 when it must not
+ * fill it: a mockup or a blank never; a picture of a thing only when the hit
+ * names its object AND either the site's world or the subject's own
+ * two-word phrase ("bud vase", "wick trimmer"); anything else only when it
+ * names the site's world (when the site names one). Among the accepted, the
+ * object among the hit's first tags counts 4 (a mention among its last, 2),
+ * the subject's two-word phrase 3, each of its other words 1, and the
+ * site's world 1, plus a quarter when it is among the first tags.
+ */
+export declare function aiStockRelevance(photo: Pick<StockPhoto, 'tags' | 'alt' | 'pageUrl'>, judgement: AiStockJudgement): number;
+/**
+ * A search's acceptable hits in the order they are tried (AGL-3660): those
+ * not placed yet, among the first few the library returned, those it must
+ * not take dropped ({@link aiStockRelevance}), best first; the seed turns
+ * the hits that score alike, so two jobs differ and one job repeats itself.
  */
-export declare function aiStockRank(photos: readonly StockPhoto[], used: ReadonlySet<string>, seed: string, options?: AiStockRankOptions): StockPhoto[];
+export declare function aiStockRank(photos: readonly StockPhoto[], used: ReadonlySet<string>, seed: string, judgement?: AiStockJudgement): StockPhoto[];
 /** The pick among a search's hits: the first {@link aiStockRank} would try, or `null`. */
-export declare function aiStockPick(photos: readonly StockPhoto[], used: ReadonlySet<string>, seed: string, options?: AiStockRankOptions): StockPhoto | null;
+export declare function aiStockPick(photos: readonly StockPhoto[], used: ReadonlySet<string>, seed: string, judgement?: AiStockJudgement): StockPhoto | null;
 /**
  * The library photos a stored page already shows: every `image` whose
  * source is the site's media reference. Starter photos are the platform's,
@@ -171,6 +242,8 @@ export interface AiLayoutStockPhotoSourceInput {
     jobId?: string;
     /** Asset srcs or source keys the job's other pages already show. */
     avoid?: readonly string[];
+    /** The most searches this source sends; a page's own bound where absent. A store's products search more (AGL-3676). */
+    searches?: number;
     signal?: AbortSignal;
 }
 export interface AiLayoutStockPhotoDeps {