@nodaro/prompts 1.38.0 → 1.39.0

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/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

@@ -14,6 +14,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

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
+}

package/src/factory-presets/references.ts

@@ -0,0 +1,80 @@
+import { IMAGE_TOKEN_PATTERN } from "../image-token-pattern.js"
+import { getPromptFields, nodeSupportsPromptAffixes, promptAffixCoreField } from "../node-prompt-fields.js"
+import { NODE_PROMPT_CANDIDATE_FIELDS } from "../resolve-prompt.js"
+import { MODELS_WITH_REFERENCE_IMAGE_SUPPORT, imageReferenceLimit } from "@nodaro/shared/models"
+
+/**
+ * The most reference images any image model takes. A preset can never need
+ * more than some model could be sent, so a count is clamped to it — a typo
+ * like `{image:99999}` must not tell a client to ask for 99,999 photos.
+ */
+export const MAX_PRESET_REFERENCES: number = Math.max(
+  1,
+  ...[...MODELS_WITH_REFERENCE_IMAGE_SUPPORT].map((provider) => imageReferenceLimit(provider)),
+)
+
+/**
+ * The data fields of `nodeType` a reference token can sit in — every field the
+ * run reads its prompt from: the candidate fields `computeNodePrompt` joins
+ * (`NODE_PROMPT_CANDIDATE_FIELDS` — how a preset's prompt is resolved when it
+ * runs, on the canvas and through `presetId` alike), the prompt-field
+ * registry's own prompt and negative fields, the field the run wraps with
+ * pre/post text, and the pre/post text itself where the node takes it. A node
+ * whose prompt lives elsewhere (`llm-chat` → `userInput`) is read where its
+ * prompt really is; a type with no prompt (an app namespace) has none.
+ */
+function promptFieldsOf(nodeType: string): string[] {
+  const spec = getPromptFields(nodeType)
+  const candidates = NODE_PROMPT_CANDIDATE_FIELDS[nodeType] ?? []
+  if (!spec && candidates.length === 0) return []
+  const fields = new Set<string>(candidates)
+  if (spec) {
+    fields.add(spec.prompt)
+    if (spec.negative) fields.add(spec.negative)
+  }
+  const core = promptAffixCoreField(nodeType)
+  if (core) fields.add(core)
+  if (nodeSupportsPromptAffixes(nodeType)) {
+    fields.add("promptPrefix")
+    fields.add("promptSuffix")
+  }
+  return [...fields]
+}
+
+/** The highest `{image:N}` / `{image:N:label}` position in `text`, or 0. */
+function highestImageToken(text: string): number {
+  let highest = 0
+  for (const match of text.matchAll(IMAGE_TOKEN_PATTERN)) {
+    const n = Number.parseInt(match[1] ?? "", 10)
+    if (Number.isInteger(n) && n > highest) highest = n
+  }
+  return highest
+}
+
+/**
+ * How many connected reference images a preset works from — 0 for a preset
+ * that needs none. A client shows a preset with a non-zero count as "needs a
+ * photo" (`needsImage`) and asks for that many before running it.
+ *
+ * Two sources, and the larger wins:
+ *   - the `{image:N}` / `{image:N:label}` tokens in the preset's prompt fields
+ *     (the highest N): a template that names its references always reports them;
+ *   - `declared` — the factory preset's own `minReferences`, for presets whose
+ *     prompt refers to "the attached photo" in words, which no data field marks.
+ *     A user preset has no declaration, so its count comes from its tokens.
+ *
+ * Pure; never throws. A declaration that is not a positive whole number is
+ * ignored, and the result is at most {@link MAX_PRESET_REFERENCES}.
+ */
+export function presetMinReferences(
+  nodeType: string,
+  data: Readonly<Record<string, unknown>>,
+  declared?: number,
+): number {
+  let count = typeof declared === "number" && Number.isInteger(declared) && declared > 0 ? declared : 0
+  for (const field of promptFieldsOf(nodeType)) {
+    const value = data[field]
+    if (typeof value === "string") count = Math.max(count, highestImageToken(value))
+  }
+  return Math.min(count, MAX_PRESET_REFERENCES)
+}

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

@@ -89,6 +89,8 @@ export function stylizedSubjectFor(nodeType: string): FactoryPreset[] {
     description: p.description,
     group: "Stylized Subject",
     data: { provider: editProviderFor(nodeType), ...p.data },
+    // Restyles the person in the connected photo ("the reference image").
+    minReferences: 1,
   }))
 }
 
@@ -242,5 +244,7 @@ export function editsFor(nodeType: string): FactoryPreset[] {
     description: p.description,
     group: "Edits",
     data: { provider: editProviderFor(nodeType), ...p.data },
+    // Every edit operates on the connected photo.
+    minReferences: 1,
   }))
 }

package/src/factory-presets/types.ts

@@ -12,6 +12,14 @@ export interface FactoryPreset {
   readonly groupKind?: "folder" | "section"
   /** Capture-shaped config (no label / fieldMappings / runtime keys). */
   readonly data: Readonly<Record<string, unknown>>
+  /**
+   * How many connected reference images the preset works from, stated for a
+   * preset whose prompt refers to "the attached photo" in words (Reference
+   * Sheet, Portrait Transformations, Stylized Subject, Edits, …). Leave it out
+   * otherwise: `{image:N}` tokens in the prompt are counted on their own, and
+   * the count a client sees is the larger of the two (`presetMinReferences`).
+   */
+  readonly minReferences?: number
 }
 
 /** A render-ready bucket of factory presets sharing one `group` (or the leading

package/src/image-reference-doctrine.ts

@@ -6,9 +6,9 @@
  * the video node skills.
  *
  * Unlike the per-provider video doctrines, this is a PLATFORM mechanism: the
- * token grammar and expansion are Nodaro's own (`prompt-builder.ts` —
- * `IMAGE_TOKEN_PATTERN`, `expandImageRefTokens`), so there is one doctrine,
- * not one per model family.
+ * token grammar and expansion are Nodaro's own (`image-token-pattern.ts` —
+ * `IMAGE_TOKEN_PATTERN`; `prompt-builder.ts` — `expandImageRefTokens`), so
+ * there is one doctrine, not one per model family.
  *
  * Source of truth for the semantics documented here (verified 2026-08-25):
  * - `IMAGE_TOKEN_PATTERN` = `/\{image:(\d+)(?::([^}\n]+))?\}/gi`

package/src/image-token-pattern.ts

@@ -0,0 +1,13 @@
+/**
+ * The `{image:N}` / `{image:N:label}` reference-token grammar — one pattern for
+ * the image prompt assembly (`prompt-builder.ts`) and for the preset metadata
+ * that reads which references a template names (`factory-presets/references.ts`).
+ *
+ * Group 1 = position (1-based), group 2 = optional label. The label allows
+ * spaces (multi-word labels like "clothes and shoes") but never a newline or
+ * `}`, so a match can't run away across lines or token boundaries.
+ *
+ * Global on purpose (callers use `.replace` / `.matchAll`, which never leave a
+ * `lastIndex` behind); never call `.test` / `.exec` on it.
+ */
+export const IMAGE_TOKEN_PATTERN = /\{image:(\d+)(?::([^}\n]+))?\}/gi

package/src/prompt-builder.ts

@@ -5,6 +5,7 @@
  */
 
 import { joinSentences } from "./hint-join.js"
+import { IMAGE_TOKEN_PATTERN } from "./image-token-pattern.js"
 import { resolveTemplate, applyTemplate } from "./prompt-templates.js"
 import { NATIVE_NEGATIVE_PROMPT_MODELS, MODELS_WITH_REFERENCE_IMAGE_SUPPORT, imageReferenceLimit, getMaxImagePromptChars, getMaxNegativePromptChars } from "@nodaro/shared/models"
 import { getStylePromptHint, isDeniedStyleId } from "./style.js"
@@ -3276,11 +3277,9 @@ const STRICT_DEFAULT_SOURCES: ReadonlySet<ReferenceSource> = new Set([
   "wired-location",
 ])
 
-/** Matches `{image:N}` and `{image:N:label}` tokens.
- *  Group 1 = position, group 2 = optional label. */
-// Label allows spaces (multi-word labels like "clothes and shoes") but never a
-// newline or `}` so the match can't run away across lines / token boundaries.
-const IMAGE_TOKEN_PATTERN = /\{image:(\d+)(?::([^}\n]+))?\}/gi
+// `IMAGE_TOKEN_PATTERN` (`{image:N}` / `{image:N:label}`) lives in
+// image-token-pattern.ts, shared with the preset metadata that reads which
+// references a template names.
 
 /**
  * The final 1-based slot an `{image:N}` token binds to on the connected-reference

package/src/prompt-style-section.ts

@@ -51,7 +51,7 @@ import {
   renderDirectionHintClauses,
   type DirectionFamily,
   type DirectionFields,
-  type DirectionHintMode,
+  type DirectionRenderOptions,
   type DirectionStyleGroup,
 } from "./direction-registry.js"
 
@@ -159,7 +159,7 @@ export function asBodyClauses(texts: readonly string[]): SlottedPromptClause[] {
  */
 export function partitionStyleClauses(
   direction: DirectionFields | undefined,
-  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+  opts: DirectionRenderOptions,
 ): SlottedPromptClause[] {
   return renderDirectionHintClauses(direction, opts).map((clause) => ({
     text: clause.text,
@@ -185,7 +185,7 @@ export function styleSectionFromClauses(clauses: readonly SlottedPromptClause[])
  */
 export function renderStyleSection(
   direction: DirectionFields | undefined,
-  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+  opts: DirectionRenderOptions,
 ): string {
   return styleSectionFromClauses(partitionStyleClauses(direction, opts))
 }