@nodaro/prompts 1.38.0 → 1.40.0

package/src/color-names.ts

@@ -0,0 +1,192 @@
+/**
+ * Plain colour names for a hex value — what a saved colour palette reads as
+ * in a prompt ("deep teal #0F4C5C"). A model follows a named colour more
+ * reliably than a bare hex code, and the hex keeps the exact value.
+ *
+ * NEAREST NAME, NOT A CLASSIFIER: a fixed table of everyday colour names, each
+ * with a representative value, and the one closest to the input in CIE Lab
+ * (ΔE 1976 — Euclidean distance in Lab, which tracks perceived difference far
+ * better than RGB). Deterministic, dependency-free, and a name is always one a
+ * person would say. Ties go to the earlier row.
+ */
+
+/** Everyday colour names and a representative sRGB value for each. */
+const NAMED: ReadonlyArray<readonly [name: string, hex: string]> = [
+  // Neutrals
+  ["black", "#000000"],
+  ["charcoal", "#36454F"],
+  ["dark gray", "#555555"],
+  ["slate gray", "#708090"],
+  ["gray", "#808080"],
+  ["warm gray", "#9A9088"],
+  ["silver", "#C0C0C0"],
+  ["light gray", "#D3D3D3"],
+  ["off-white", "#F2F0EB"],
+  ["white", "#FFFFFF"],
+  ["ivory", "#FFFFF0"],
+  ["cream", "#FFFDD0"],
+  ["eggshell", "#F0EAD6"],
+  ["linen", "#FAF0E6"],
+  ["champagne", "#F7E7CE"],
+  ["wheat", "#F5DEB3"],
+  // Earth tones and browns
+  ["sand", "#C2B280"],
+  ["tan", "#D2B48C"],
+  ["khaki", "#C3B091"],
+  ["taupe", "#8B8589"],
+  ["camel", "#C19A6B"],
+  ["caramel", "#C68E17"],
+  ["brown", "#964B00"],
+  ["chocolate", "#7B3F00"],
+  ["coffee", "#6F4E37"],
+  ["espresso", "#4E312D"],
+  ["walnut", "#773F1A"],
+  ["chestnut", "#954535"],
+  ["mahogany", "#C04000"],
+  ["rust", "#B7410E"],
+  ["terracotta", "#E2725B"],
+  ["copper", "#B87333"],
+  ["bronze", "#CD7F32"],
+  ["ochre", "#CC7722"],
+  // Oranges
+  ["burnt orange", "#CC5500"],
+  ["orange", "#FFA500"],
+  ["tangerine", "#F28500"],
+  ["apricot", "#FBCEB1"],
+  ["peach", "#FFCBA4"],
+  ["coral", "#FF7F50"],
+  ["salmon", "#FA8072"],
+  // Reds
+  ["red", "#FF0000"],
+  ["scarlet", "#FF2400"],
+  ["crimson", "#DC143C"],
+  ["cherry red", "#D2042D"],
+  ["brick red", "#CB4154"],
+  ["burgundy", "#800020"],
+  ["maroon", "#800000"],
+  ["wine red", "#722F37"],
+  ["oxblood", "#4A0000"],
+  // Pinks
+  ["raspberry", "#E30B5C"],
+  ["rose", "#FF007F"],
+  ["hot pink", "#FF69B4"],
+  ["pink", "#FFC0CB"],
+  ["blush pink", "#E8B4B8"],
+  ["dusty rose", "#C08081"],
+  ["mauve", "#B784A7"],
+  // Purples
+  ["magenta", "#FF00FF"],
+  ["orchid", "#DA70D6"],
+  ["plum", "#8E4585"],
+  ["eggplant", "#614051"],
+  ["dusty purple", "#6E5A7E"],
+  ["lilac", "#C8A2C8"],
+  ["lavender", "#B57EDC"],
+  ["pale lavender", "#E6E6FA"],
+  ["amethyst", "#9966CC"],
+  ["violet", "#8F00FF"],
+  ["purple", "#800080"],
+  ["indigo", "#4B0082"],
+  // Blues
+  ["navy blue", "#000080"],
+  ["midnight blue", "#191970"],
+  ["prussian blue", "#003153"],
+  ["dusky blue", "#4B5E7D"],
+  ["royal blue", "#4169E1"],
+  ["cobalt blue", "#0047AB"],
+  ["blue", "#0000FF"],
+  ["cornflower blue", "#6495ED"],
+  ["denim blue", "#1560BD"],
+  ["steel blue", "#4682B4"],
+  ["slate blue", "#6A5ACD"],
+  ["periwinkle", "#CCCCFF"],
+  ["sky blue", "#87CEEB"],
+  ["baby blue", "#89CFF0"],
+  ["powder blue", "#B0E0E6"],
+  ["ice blue", "#D6ECEF"],
+  ["azure", "#007FFF"],
+  ["cerulean", "#007BA7"],
+  ["petrol blue", "#005F6A"],
+  // Cyans and teals
+  ["cyan", "#00FFFF"],
+  ["turquoise", "#40E0D0"],
+  ["aquamarine", "#7FFFD4"],
+  ["teal", "#008080"],
+  ["dark teal", "#014D4E"],
+  ["dark slate gray", "#2F4F4F"],
+  // Greens
+  ["sea green", "#2E8B57"],
+  ["emerald green", "#50C878"],
+  ["jade green", "#00A86B"],
+  ["mint green", "#98FF98"],
+  ["seafoam green", "#93E9BE"],
+  ["sage green", "#9CAF88"],
+  ["olive green", "#708238"],
+  ["olive", "#808000"],
+  ["moss green", "#8A9A5B"],
+  ["forest green", "#228B22"],
+  ["hunter green", "#355E3B"],
+  ["bottle green", "#006A4E"],
+  ["dark green", "#013220"],
+  ["green", "#008000"],
+  ["kelly green", "#4CBB17"],
+  ["lime green", "#32CD32"],
+  ["chartreuse", "#7FFF00"],
+  ["pistachio", "#93C572"],
+  // Yellows and golds
+  ["yellow", "#FFFF00"],
+  ["lemon yellow", "#FFF44F"],
+  ["pale yellow", "#FDFD96"],
+  ["canary yellow", "#FFEF00"],
+  ["mustard yellow", "#E1AD01"],
+  ["gold", "#FFD700"],
+  ["amber", "#FFBF00"],
+  ["honey", "#F0A830"],
+  ["saffron", "#F4C430"],
+]
+
+const HEX_RE = /^#[0-9a-f]{6}$/i
+
+type Lab = readonly [l: number, a: number, b: number]
+
+function channel(v: number): number {
+  const c = v / 255
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+}
+
+function labPivot(t: number): number {
+  return t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 * t + 16) / 116
+}
+
+/** sRGB hex → CIE Lab (D65). Only called with a value that passed `HEX_RE`. */
+function toLab(hex: string): Lab {
+  const r = channel(parseInt(hex.slice(1, 3), 16))
+  const g = channel(parseInt(hex.slice(3, 5), 16))
+  const b = channel(parseInt(hex.slice(5, 7), 16))
+  const x = labPivot((0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / 0.95047)
+  const y = labPivot(0.2126729 * r + 0.7151522 * g + 0.072175 * b)
+  const z = labPivot((0.0193339 * r + 0.119192 * g + 0.9503041 * b) / 1.08883)
+  return [116 * y - 16, 500 * (x - y), 200 * (y - z)]
+}
+
+let namedLab: ReadonlyArray<readonly [string, Lab]> | null = null
+
+/**
+ * The everyday name nearest to `hex` (`#RRGGBB`, any case), or `""` when the
+ * value is not a `#RRGGBB` colour.
+ */
+export function nearestColorName(hex: string): string {
+  if (!HEX_RE.test(hex)) return ""
+  namedLab ??= NAMED.map(([name, value]) => [name, toLab(value)] as const)
+  const [l, a, b] = toLab(hex)
+  let best = ""
+  let bestDistance = Infinity
+  for (const [name, [nl, na, nb]] of namedLab) {
+    const d = (l - nl) ** 2 + (a - na) ** 2 + (b - nb) ** 2
+    if (d < bestDistance) {
+      bestDistance = d
+      best = name
+    }
+  }
+  return best
+}

package/src/direction-registry.ts

@@ -69,6 +69,7 @@ import { buildActionFxHints } from "./action-fx.js"
 import { getTemporalPromptHint, getTemporalTerm } from "./temporal.js"
 import { renderTransitionBases } from "./transitions.js"
 import { getLoopSubjectPromptHint, getLoopSubjectTerm } from "./loop-subject.js"
+import { parseUserDirectionRef, type UserDirectionRefKind } from "./user-direction-refs.js"
 
 /** Which generation stages fold a dimension. */
 export type DirectionSurface = "image" | "video" | "both"
@@ -112,6 +113,14 @@ export interface DirectionFieldSpec {
   readonly styleGroup?: DirectionStyleGroup
   /** Ids honored per dimension. Extras are SLICED at render, never a 400. */
   readonly maxPicks: number
+  /**
+   * The kind of the caller's OWN saved resource this row also takes, as
+   * `<kind>:<uuid>` (`user-direction-refs.ts`) — a palette on `colorLook`, a
+   * moodboard on `style`. Only single-pick rows carry one, so a pick budget can
+   * never slice a reference away. The platform resolves the reference before
+   * the fold and hands the rendered clause in as `refs`.
+   */
+  readonly userRef?: UserDirectionRefKind
   /**
    * Render selected ids in this catalog's own doctrine: per-id for independent
    * catalogs, ONE blended clause for Mood / Aesthetic / Photographer, the
@@ -228,12 +237,12 @@ export const DIRECTION_FIELDS = [
   { key: "lightingDirection", surface: "both", family: "look", maxPicks: 1, render: lighting },
   { key: "lightingRatio", surface: "both", family: "look", maxPicks: 1, render: lighting },
   { key: "colorTemperature", surface: "both", family: "look", maxPicks: 1, render: lighting },
-  { key: "colorLook", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getColorLookPromptHint, getColorLookTerm) },
+  { key: "colorLook", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, userRef: "palette", render: perId(getColorLookPromptHint, getColorLookTerm) },
   { key: "atmosphere", surface: "both", family: "look", maxPicks: 2, render: viaListBuilder(buildAtmosphereHints) },
   { key: "postProcess", surface: "image", family: "look", maxPicks: 2, render: viaListBuilder(buildPostProcessHints) },
 
   // Style.
-  { key: "style", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getStylePromptHint, getStyleTerm) },
+  { key: "style", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, userRef: "moodboard", render: perId(getStylePromptHint, getStyleTerm) },
   { key: "mood", surface: "both", family: "look", maxPicks: 2, render: viaMood },
   { key: "aesthetic", surface: "both", family: "look", maxPicks: 2, render: viaStringBuilder(buildAestheticHints) },
   { key: "photoGenre", surface: "image", family: "look", maxPicks: 1, render: perId(getPhotoGenrePromptHint, getPhotoGenreTerm) },
@@ -303,11 +312,39 @@ export const FILM_STYLE_KEYS: ReadonlyArray<DirectionKey> = DIRECTION_SPECS.filt
   (f) => f.styleGroup === "film",
 ).map((f) => f.key as DirectionKey)
 
+/**
+ * The direction key that takes a reference of this kind — `colorLook` for a
+ * palette, `style` for a moodboard. Derived from the table's `userRef` column.
+ */
+export function directionKeyForUserRef(kind: UserDirectionRefKind): DirectionKey {
+  const row = DIRECTION_SPECS.find((f) => f.userRef === kind)
+  if (!row) throw new Error(`no direction row takes a ${kind} reference`)
+  return row.key as DirectionKey
+}
+
+/** The kind of saved resource a direction key takes, or undefined (most keys). */
+export function userRefKindOfDirectionKey(key: string): UserDirectionRefKind | undefined {
+  return DIRECTION_SPECS.find((f) => f.key === key)?.userRef
+}
+
 /** Verbosity for a whole fold, or split per family. */
 export type DirectionHintMode =
   | PickerHintMode
   | { readonly look: PickerHintMode; readonly motion: PickerHintMode }
 
+/** How a direction bag is folded. */
+export interface DirectionRenderOptions {
+  readonly surface: "image" | "video"
+  readonly mode?: DirectionHintMode
+  /**
+   * Rendered clauses for the caller's OWN saved resources, keyed by the
+   * direction value (`palette:<id>` → `color palette: …`), resolved by the
+   * platform before the fold. A reference absent from the map renders nothing,
+   * exactly like an unknown catalog id. Absent = no reference resolves.
+   */
+  readonly refs?: ReadonlyMap<string, string>
+}
+
 /** Image policy: full clause for every dimension (today's behavior). */
 export const IMAGE_HINT_MODE_DEFAULT: DirectionHintMode = "full"
 
@@ -360,6 +397,30 @@ function normalizeDirectionIds(value: unknown, maxPicks: number): string[] {
   return ids.slice(0, maxPicks)
 }
 
+/**
+ * One row's clauses. A row with no user-owned reference among its ids renders
+ * through its catalog doctrine exactly as before (byte parity). On a row that
+ * takes a reference (`userRef`), each id renders on its own, in order: a
+ * reference of the row's kind becomes its resolved clause from `refs` (nothing
+ * when unresolved), any other value goes through the catalog.
+ */
+function renderRow(
+  spec: DirectionFieldSpec,
+  ids: readonly string[],
+  mode: PickerHintMode,
+  refs: ReadonlyMap<string, string> | undefined,
+): string[] {
+  if (spec.userRef === undefined || !ids.some((id) => parseUserDirectionRef(id) !== null)) {
+    return spec.render(ids, mode)
+  }
+  return ids.flatMap((id) => {
+    const ref = parseUserDirectionRef(id)
+    if (ref === null) return spec.render([id], mode)
+    const clause = ref.kind === spec.userRef ? refs?.get(id) : undefined
+    return clause ? [clause] : []
+  })
+}
+
 /** The rows a given generation stage folds, in table order. */
 export function directionFieldsForSurface(
   surface: "image" | "video",
@@ -383,7 +444,7 @@ export interface DirectionHintClause {
  */
 export function renderDirectionHintClauses(
   direction: DirectionFields | undefined,
-  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+  opts: DirectionRenderOptions,
 ): DirectionHintClause[] {
   if (!direction) return []
   const mode = opts.mode ?? "full"
@@ -396,7 +457,7 @@ export function renderDirectionHintClauses(
       spec.maxPicks,
     )
     if (ids.length === 0) continue
-    for (const hint of spec.render(ids, modeForFamily(mode, spec.family))) {
+    for (const hint of renderRow(spec, ids, modeForFamily(mode, spec.family), opts.refs)) {
       if (hint.length > 0 && !seen.has(hint)) {
         seen.add(hint)
         out.push({
@@ -436,7 +497,7 @@ export function renderDirectionHintClauses(
  */
 export function renderDirectionHints(
   direction: DirectionFields | undefined,
-  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+  opts: DirectionRenderOptions,
 ): string[] {
   return renderDirectionHintClauses(direction, opts).map((c) => c.text)
 }

package/src/entries/assembly.ts

@@ -20,6 +20,7 @@ export * from "../assemble-video-input.js"
 export * from "../seedance-2-inputs.js"
 export * from "../gemini-omni-inputs.js"
 export * from "../veo-i2v-inputs.js"
+export * from "../frame-reference-slots.js"
 export * from "../surround-fill.js"
 // --- Start/end frame delivery: one plan for the dispatch and the editor ---
 export * from "../frame-delivery.js"

package/src/entries/prompt-builder.ts

@@ -16,6 +16,8 @@ export * from "../described-references.js"
 export * from "../prompt-builder.js"
 export * from "../prompt-builder-structured-fields.js"
 export * from "../direction-registry.js"
+export * from "../user-direction-refs.js"
+export * from "../color-names.js"
 export * from "../subject-registry.js"
 export * from "../prompt-style-section.js"
 export * from "../read-node-direction.js"

package/src/factory-presets/generate-image.ts

@@ -10,12 +10,17 @@ const REALISM_MODEL = { provider: "gpt-image-2", resolution: "2K" } as const
 const SKIN_STUDY_MODEL = { provider: "seedream-5-pro", quality: "high" } as const
 
 export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
+  // `minReferences` marks a preset that works from connected photos its prompt
+  // describes in words ("the attached photo"); `{image:N}` tokens count on their
+  // own, so a tokenized preset declares nothing. The groups stay all-or-nothing
+  // (factory-preset-references.test.ts), so a new preset copies the line along.
   // ── Reference Sheet ──────────────────────────────────────────────────────
   {
     id: "generate-image/character-board",
     name: "Character Board",
     description: "Connect a sharp, well-lit photo → dense character sheet; reuse it as a reference for consistent shots.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -31,6 +36,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Pose Board",
     description: "Connect a sharp photo → animation-ready pose & expression sheet; reuse it as a reference for consistent action.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -46,6 +52,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Location Board",
     description: "Connect a photo → dense location sheet; reuse it as a reference for consistent scenes.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -61,6 +68,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Product Board",
     description: "Connect a photo → dense product sheet; reuse it as a reference for consistent shots.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -76,6 +84,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Outfit Board",
     description: "Connect a photo → dense wardrobe sheet; reuse it as a reference for consistent looks.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -91,6 +100,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Scene Board",
     description: "Connect a photo → set-dressing & props study; reuse it as a reference for consistent sets.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -106,6 +116,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Creature Board",
     description: "Connect a sharp photo → dense creature sheet; reuse it as a reference for consistent shots.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -121,6 +132,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Vehicle Board",
     description: "Connect a photo → dense vehicle sheet; reuse it as a reference for consistent shots.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -136,6 +148,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Food Board",
     description: "Connect a photo → dense dish sheet; reuse it as a reference for consistent food shots.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -151,6 +164,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Mascot Board",
     description: "Connect a mascot image → brand-character sheet with brand applications; reuse it for a consistent mascot.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -166,6 +180,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Pet Board",
     description: "Connect a sharp photo → dense pet sheet; reuse it as a reference for consistent shots.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -181,6 +196,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Skin Detail Sheet",
     description: "Connect a sharp face photo → a six-panel skin reference.",
     group: "Reference Sheet",
+    minReferences: 1,
     data: {
       ...SKIN_STUDY_MODEL,
       aspectRatio: "3:2",
@@ -203,6 +219,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Character Reference Grid",
     description: "Connect a photo → clean 4-angle identity grid (no decorations) — the strongest consistency anchor.",
     group: "Cast & Consistency",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "3:4",
@@ -218,6 +235,8 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Cast Mega Grid",
     description: "Connect 2–4 character refs → one labeled cast sheet; then reference cast members by name in scenes.",
     group: "Cast & Consistency",
+    // A cast sheet is two characters or more ("Connect 2–4 character refs").
+    minReferences: 2,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "3:4",
@@ -232,6 +251,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Cast Scene (by name)",
     description: "Connect a cast grid → stage a scene naming the characters; never re-describe their looks.",
     group: "Cast & Consistency",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "16:9",
@@ -247,6 +267,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Label Elements",
     description: "Step 1 · connect a photo → the same image with a numbered label on each changeable element.",
     group: "Edit by Name",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       quality: "high",
@@ -260,6 +281,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Apply Named Edit",
     description: "Step 2 · connect the labeled sheet → type your change in the prompt (e.g. change \"drink 1\" to blue); the labels are removed from the result.",
     group: "Edit by Name",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       quality: "high",
@@ -1628,6 +1650,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Five Ages (Timeless Soul)",
     description: "One person at 5 ages, studio line-up. Needs a reference photo.",
     group: "Portrait Transformations",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "3:4",
@@ -1642,6 +1665,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Three-Age Triptych",
     description: "Same person at 3 ages (~10 / 40 / 75). Needs a reference photo.",
     group: "Portrait Transformations",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "3:4",
@@ -1656,6 +1680,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Five Ages — B&W",
     description: "Monochrome age line-up. Needs a reference photo.",
     group: "Portrait Transformations",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "3:4",
@@ -1670,6 +1695,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Decade Timeline",
     description: "Same person across the '80s–2020s. Needs a reference photo.",
     group: "Portrait Transformations",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "3:4",
@@ -1684,6 +1710,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Four Seasons",
     description: "Same person in spring / summer / autumn / winter. Needs a reference photo.",
     group: "Portrait Transformations",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "3:4",
@@ -1698,6 +1725,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Times of Day",
     description: "Same person at dawn / midday / golden hour / night. Needs a reference photo.",
     group: "Portrait Transformations",
+    minReferences: 1,
     data: {
       provider: "gpt-image-2",
       aspectRatio: "3:4",
@@ -1712,6 +1740,7 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
     name: "Sports Jersey Portrait",
     description: "You in an oversized team jersey, studio editorial. Needs a reference photo.",
     group: "Portrait Transformations",
+    minReferences: 1,
     data: {
       provider: "nano-banana-2-1",
       aspectRatio: "4:5",

package/src/factory-presets/index.ts

@@ -1,4 +1,5 @@
 import { T2I_TO_I2I_VARIANT } from "@nodaro/shared/models"
+import { ownEntry } from "../own-entry.js"
 import type { FactoryPreset } from "./types.js"
 import { stylizedSubjectFor, editsFor } from "./shared-image.js"
 import { GENERATE_IMAGE_PRESETS } from "./generate-image.js"
@@ -14,6 +15,8 @@ import { LOTTIE_OVERLAY_PRESETS } from "./lottie-overlay.js"
 
 export type { FactoryPreset, FactoryPresetGroup } from "./types.js"
 export { groupFactoryPresets } from "./types.js"
+export { MAX_PRESET_REFERENCES, presetMinReferences } from "./references.js"
+export { FACTORY_PRESET_PREVIEW_FILES, PRESET_PREVIEW_PATH, factoryPresetPreviewUrl } from "./previews.js"
 
 /**
  * A shared preset as Modify Image takes it. Modify Image always works from a source photo, so its
@@ -55,6 +58,8 @@ export const FACTORY_PRESETS: Readonly<Record<string, readonly FactoryPreset[]>>
   "lottie-overlay": LOTTIE_OVERLAY_PRESETS,
 }
 
+/** The catalog for `nodeType`, or an empty one — also for a name that is an
+ *  Object.prototype member (`constructor`), which is no catalog of ours. */
 export function getFactoryPresets(nodeType: string): readonly FactoryPreset[] {
-  return FACTORY_PRESETS[nodeType] ?? []
+  return ownEntry(FACTORY_PRESETS, nodeType) ?? []
 }

package/src/factory-presets/preview-files.generated.ts

@@ -0,0 +1,4 @@
+// GENERATED by tools/preset-previews/build.mts — do not edit. Factory preset id →
+// content-hashed file under frontend/public/preset-previews/ (`<nodeType>/<slug>.<hash8>.webp`).
+export const FACTORY_PRESET_PREVIEW_FILES: Readonly<Record<string, string>> = {
+}

package/src/factory-presets/previews.ts

@@ -0,0 +1,40 @@
+import { FACTORY_PRESET_PREVIEW_FILES } from "./preview-files.generated.js"
+
+export { FACTORY_PRESET_PREVIEW_FILES }
+
+/**
+ * Where the factory preset previews live, relative to the app's origin:
+ * `frontend/public/preset-previews/` is served at `/preset-previews/` in every
+ * edition. Each name carries its content hash (`<slug>.<hash8>.webp`), so the
+ * server caches them as immutable and a regenerated picture is a new URL.
+ */
+export const PRESET_PREVIEW_PATH = "/preset-previews/"
+
+function originOf(baseUrl: string): string | undefined {
+  try {
+    const url = new URL(baseUrl)
+    if (url.protocol !== "https:" && url.protocol !== "http:") return undefined
+    return url.origin + url.pathname.replace(/\/+$/, "")
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The absolute URL of a factory preset's example picture on the installation
+ * at `baseUrl` (its public origin, e.g. "https://app.nodaro.ai"), or null when
+ * the preset has none. Only a preset whose file is in the committed map gets a
+ * URL, so it never points at a file that does not exist.
+ *
+ * @param files the preset id → file map; defaults to the committed one
+ */
+export function factoryPresetPreviewUrl(
+  presetId: string,
+  baseUrl: string,
+  files: Readonly<Record<string, string>> = FACTORY_PRESET_PREVIEW_FILES,
+): string | null {
+  const file = Object.prototype.hasOwnProperty.call(files, presetId) ? files[presetId] : undefined
+  if (!file) return null
+  const origin = originOf(baseUrl)
+  return origin ? `${origin}${PRESET_PREVIEW_PATH}${file}` : null
+}