@nodaro/prompts 1.38.0 → 1.39.0

package/src/__tests__/assemble-image-input-style-references.test.ts

@@ -0,0 +1,173 @@
+/**
+ * `assembleImageInput` with a caller's RESOLVED palette / moodboard:
+ *
+ * - `directionRefs` — the clause each user-owned direction id resolved to,
+ *   folded in that row's slot like a catalog clause;
+ * - `styleReferences` — a moodboard's images. They only FILL the reference
+ *   seats the caller's own references leave free, after them, and never move,
+ *   renumber or evict one of the caller's own (the attach-priority cap would
+ *   otherwise let a style image push out a mentioned character variant).
+ */
+import { describe, it, expect } from "vitest"
+import { assembleImageInput } from "../assemble-image-input.js"
+import { styleReferenceDescription } from "../user-direction-refs.js"
+import { imageReferenceLimit } from "@nodaro/shared/models"
+import type { ConnectedReference } from "@nodaro/shared/types"
+
+const PALETTE = "palette:0f9e8d7c-6b5a-4c3d-9e2f-1a2b3c4d5e6f"
+const MOODBOARD = "moodboard:0f9e8d7c-6b5a-4c3d-9e2f-1a2b3c4d5e6f"
+const style = (n: number) =>
+  Array.from({ length: n }, (_, i) => ({ url: `https://cdn.test/mood-${i + 1}.png` }))
+const flat = (n: number) => Array.from({ length: n }, (_, i) => `https://cdn.test/own-${i + 1}.png`)
+
+const kira: ConnectedReference[] = [
+  { id: "k0", defaultName: "Kira", source: "wired-character", url: "https://cdn.test/kira.png", characterSlug: "kira", characterCanonicalDescription: "a red-haired woman" },
+  { id: "k1", defaultName: "Kira", source: "wired-character", url: "https://cdn.test/kira-smile.png", characterSlug: "kira", variantSlug: "smile" },
+]
+
+describe("directionRefs", () => {
+  it("folds a resolved palette onto the [style] film line", () => {
+    const result = assembleImageInput({
+      userPrompt: "a cat on a sofa",
+      provider: "nano-banana-pro",
+      direction: { colorLook: PALETTE },
+      directionRefs: new Map([[PALETTE, "color palette: deep teal #0F4C5C"]]),
+    })
+    expect(result.prompt).toBe("a cat on a sofa\n\n[style]:\ncolor palette: deep teal #0F4C5C")
+  })
+
+  it("folds nothing for an id it was not handed (the platform resolves before assembling)", () => {
+    const result = assembleImageInput({ userPrompt: "a cat", provider: "nano-banana-pro", direction: { style: MOODBOARD } })
+    expect(result.prompt).toBe("a cat")
+  })
+})
+
+describe("styleReferences — absent is byte-identical", () => {
+  it("adds no field and changes nothing when none are given", () => {
+    const input = { userPrompt: "a cat", provider: "nano-banana-pro", extraReferenceImageUrls: flat(2) }
+    const result = assembleImageInput(input)
+    expect(result).toEqual(assembleImageInput({ ...input, styleReferences: undefined }))
+    expect("styleReferencesSent" in result).toBe(false)
+  })
+})
+
+describe("styleReferences — fill the free seats, after the caller's own", () => {
+  it("appends them after the caller's references and says how many went", () => {
+    for (const referenceFormat of ["legacy", "hybrid"] as const) {
+      const base = assembleImageInput({ userPrompt: "a cat", provider: "nano-banana-pro", extraReferenceImageUrls: flat(2), referenceFormat })
+      const result = assembleImageInput({
+        userPrompt: "a cat",
+        provider: "nano-banana-pro",
+        extraReferenceImageUrls: flat(2),
+        referenceFormat,
+        styleReferences: style(3),
+      })
+      expect(result.referenceImageUrls, referenceFormat).toEqual([...base.referenceImageUrls!, ...style(3).map((s) => s.url)])
+      expect(result.styleReferencesSent, referenceFormat).toBe(3)
+      expect(result.prompt, referenceFormat).toContain(styleReferenceDescription(0))
+      expect(result.prompt, referenceFormat).toContain(styleReferenceDescription(1))
+    }
+  })
+
+  it("never sends more than the model takes: the caller's references come first", () => {
+    const cap = imageReferenceLimit("nano-banana-pro")
+    const result = assembleImageInput({
+      userPrompt: "a cat",
+      provider: "nano-banana-pro",
+      extraReferenceImageUrls: flat(cap - 2),
+      styleReferences: style(5),
+    })
+    expect(result.referenceImageUrls).toEqual([...flat(cap - 2), ...style(2).map((s) => s.url)])
+    expect(result.styleReferencesSent).toBe(2)
+  })
+
+  it("sends none when the caller already fills every seat", () => {
+    const cap = imageReferenceLimit("nano-banana-pro")
+    const result = assembleImageInput({
+      userPrompt: "a cat",
+      provider: "nano-banana-pro",
+      extraReferenceImageUrls: flat(cap),
+      styleReferences: style(2),
+    })
+    expect(result.referenceImageUrls).toEqual(flat(cap))
+    expect(result.styleReferencesSent).toBe(0)
+  })
+
+  it("never evicts a mentioned character variant to make room", () => {
+    // cap 8; the caller's two connected entries (a canonical + the mentioned
+    // variant) send ONE image, so seven seats look free — but seven style
+    // images would push the raw list past the attach-priority cap, which
+    // keeps non-variants first and would drop the mentioned variant.
+    const base = assembleImageInput({
+      userPrompt: "@kira:2:smile walking",
+      provider: "nano-banana-pro",
+      connectedReferences: kira,
+      referenceFormat: "hybrid",
+    })
+    expect(base.referenceImageUrls).toEqual(["https://cdn.test/kira-smile.png"])
+    const result = assembleImageInput({
+      userPrompt: "@kira:2:smile walking",
+      provider: "nano-banana-pro",
+      connectedReferences: kira,
+      referenceFormat: "hybrid",
+      styleReferences: style(12),
+    })
+    expect(result.referenceImageUrls![0]).toBe("https://cdn.test/kira-smile.png")
+    expect(result.styleReferencesSent).toBe(6)
+    expect(result.referenceImageUrls).toEqual(["https://cdn.test/kira-smile.png", ...style(6).map((s) => s.url)])
+  })
+
+  it("skips a style image the caller already sends, and fills with the next", () => {
+    const own = flat(1)
+    const result = assembleImageInput({
+      userPrompt: "a cat",
+      provider: "nano-banana-pro",
+      extraReferenceImageUrls: own,
+      styleReferences: [{ url: own[0] }, ...style(2)],
+    })
+    expect(result.referenceImageUrls).toEqual([own[0], ...style(2).map((s) => s.url)])
+    expect(result.styleReferencesSent).toBe(2)
+  })
+
+  it("sends none to a model that takes no reference images", () => {
+    expect(imageReferenceLimit("imagen4")).toBe(0)
+    const result = assembleImageInput({ userPrompt: "a cat", provider: "imagen4", styleReferences: style(2) })
+    expect(result.referenceImageUrls ?? []).toEqual([])
+    expect(result.styleReferencesSent).toBe(0)
+    expect(result.prompt).toBe("a cat")
+  })
+
+  it("sends none on the trained-character (LoRA) path, which takes no references", () => {
+    const result = assembleImageInput({
+      userPrompt: "@kira walking",
+      provider: "nano-banana-pro",
+      connectedReferences: kira,
+      skipCharacterMentions: true,
+      styleReferences: style(2),
+    })
+    expect(result.referenceImageUrls ?? []).toEqual([])
+    expect(result.styleReferencesSent).toBe(0)
+  })
+
+  it("carries each image's caption into its line", () => {
+    const result = assembleImageInput({
+      userPrompt: "a cat",
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+      styleReferences: [{ url: "https://cdn.test/m.png", caption: "linen and oak" }],
+    })
+    expect(result.prompt).toContain(styleReferenceDescription(0, "linen and oak"))
+  })
+
+  it("an empty prompt with style images is not an empty prompt", () => {
+    const result = assembleImageInput({
+      userPrompt: "",
+      provider: "nano-banana-pro",
+      styleReferences: style(1),
+      throwOnEmpty: true,
+    })
+    expect(result.styleReferencesSent).toBe(1)
+    expect(result.prompt.trim().length).toBeGreaterThan(0)
+    expect(() => assembleImageInput({ userPrompt: "", provider: "nano-banana-pro", throwOnEmpty: true })).toThrow(/No prompt/)
+  })
+})

package/src/__tests__/catalog-id-guard.test.ts

@@ -132,6 +132,36 @@ describe("the field contract covers the shapes the resolvers actually read", ()
   })
 })
 
+describe("a reference to the caller's own palette / moodboard is not a catalog id", () => {
+  const PALETTE = "palette:0f9e8d7c-6b5a-4c3d-9e2f-1a2b3c4d5e6f"
+  const MOODBOARD = "moodboard:0f9e8d7c-6b5a-4c3d-9e2f-1a2b3c4d5e6f"
+  const curate = () => {
+    registerCatalogPack({ id: "g-color", catalogId: "color-look", mode: "deny", denyIds: [getPickerCatalog("color-look")!.options![0].id] })
+    registerCatalogPack({ id: "g-style", catalogId: "style", mode: "deny", denyIds: [getPickerCatalog("style")!.options![0].id] })
+  }
+
+  it("a curated deployment lets one through on its own key, in a request body", () => {
+    curate()
+    expect(findForeignCatalogIdsInBody("generate-image", { direction: { colorLook: PALETTE, style: MOODBOARD } })).toEqual([])
+  })
+
+  it("and on a consumer node's stored direction (the graph lane)", () => {
+    curate()
+    expect(findForeignCatalogIds([{ id: "g", type: "generate-image", data: { direction: { colorLook: PALETTE, style: MOODBOARD } } }])).toEqual([])
+  })
+
+  it("is still refused on a key that does not take that kind — it is no id there", () => {
+    curate()
+    expect(findForeignCatalogIdsInBody("generate-image", { direction: { colorLook: MOODBOARD } })).toHaveLength(1)
+    expect(findForeignCatalogIdsInBody("generate-image", { direction: { mood: PALETTE } })).toHaveLength(1)
+  })
+
+  it("is still refused in a parameter node's own field (a picker never takes one)", () => {
+    curate()
+    expect(findForeignCatalogIds([{ id: "c", type: "color-look", data: { colorLook: PALETTE } }])).toHaveLength(1)
+  })
+})
+
 describe("the message", () => {
   it("names every offending value once, by field", () => {
     const msg = foreignCatalogIdMessage([

package/src/__tests__/factory-preset-previews.test.ts

@@ -0,0 +1,123 @@
+// @test-watches frontend/public/preset-previews/**
+/**
+ * Factory preset previews: one small example picture per preset, committed
+ * under frontend/public/preset-previews/<nodeType>/<slug>.<hash8>.webp and
+ * served by the app at /preset-previews/… (cached as immutable, so the name
+ * must carry the file's own content hash). The generated map
+ * (preview-files.generated.ts, written by tools/preset-previews/build.mts) is
+ * what the API reads to hand out `previewUrl`.
+ *
+ * The API must never point at a file that does not exist — the CDN in front
+ * keeps a 404 for a long time — so the map and the folder must agree exactly:
+ *   - every mapped file exists, is non-empty and carries its own hash;
+ *   - every mapped id is a factory preset, and the file sits under its node
+ *     type with its slug as the name;
+ *   - no file in the folder is missing from the map (a dropped-in file that
+ *     was never built, or a stale one).
+ * With no previews at all (the folder absent) every check holds and every
+ * `previewUrl` is null.
+ */
+import { createHash } from "node:crypto"
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { describe, expect, it } from "vitest"
+import {
+  FACTORY_PRESETS,
+  FACTORY_PRESET_PREVIEW_FILES,
+  PRESET_PREVIEW_PATH,
+  factoryPresetPreviewUrl,
+} from "../factory-presets.js"
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..")
+const PREVIEW_DIR = join(REPO_ROOT, "frontend", "public", "preset-previews")
+const FILE_NAME = /^([a-z0-9]+(?:-[a-z0-9]+)*)\.([0-9a-f]{8})\.webp$/
+
+/** Every file under the folder, as `<nodeType>/<name>` (dotfiles skipped). */
+function filesOnDisk(): string[] {
+  if (!existsSync(PREVIEW_DIR)) return []
+  return readdirSync(PREVIEW_DIR, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name.startsWith(".")) return []
+    if (!entry.isDirectory()) return [entry.name]
+    return readdirSync(join(PREVIEW_DIR, entry.name))
+      .filter((name) => !name.startsWith("."))
+      .map((name) => `${entry.name}/${name}`)
+  })
+}
+
+const factoryIds = new Set(Object.values(FACTORY_PRESETS).flatMap((list) => list.map((p) => p.id)))
+
+describe("factory preset previews — the map and the folder agree", () => {
+  it("every mapped id is a factory preset, filed under its node type and slug", () => {
+    const wrong: string[] = []
+    for (const [id, file] of Object.entries(FACTORY_PRESET_PREVIEW_FILES)) {
+      if (!factoryIds.has(id)) wrong.push(`${id}: not a factory preset`)
+      const [nodeType, name] = file.split("/")
+      const match = FILE_NAME.exec(name ?? "")
+      const slug = id.slice(id.indexOf("/") + 1)
+      if (`${nodeType}/${match?.[1]}` !== `${id.slice(0, id.indexOf("/"))}/${slug}`) {
+        wrong.push(`${id}: filed as ${file}`)
+      }
+    }
+    expect(wrong).toEqual([])
+  })
+
+  it("every mapped file exists, is non-empty and is named by its own content hash", () => {
+    const wrong: string[] = []
+    for (const [id, file] of Object.entries(FACTORY_PRESET_PREVIEW_FILES)) {
+      const path = join(PREVIEW_DIR, file)
+      if (!existsSync(path) || !statSync(path).isFile()) {
+        wrong.push(`${id}: ${file} is missing`)
+        continue
+      }
+      const bytes = readFileSync(path)
+      if (bytes.length === 0) wrong.push(`${id}: ${file} is empty`)
+      const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 8)
+      if (FILE_NAME.exec(file.split("/")[1] ?? "")?.[2] !== hash) wrong.push(`${id}: ${file} does not carry its hash ${hash}`)
+    }
+    expect(wrong).toEqual([])
+  })
+
+  it("no file in the folder is missing from the map (run tools/preset-previews/build.mts)", () => {
+    const mapped = new Set(Object.values(FACTORY_PRESET_PREVIEW_FILES))
+    expect(filesOnDisk().filter((f) => !mapped.has(f))).toEqual([])
+  })
+
+  it("each file is mapped from exactly one preset", () => {
+    const files = Object.values(FACTORY_PRESET_PREVIEW_FILES)
+    expect(files.length).toBe(new Set(files).size)
+  })
+})
+
+describe("factoryPresetPreviewUrl", () => {
+  const FILES = { "generate-image/character-board": "generate-image/character-board.1a2b3c4d.webp" }
+
+  it("is an absolute URL on the installation's origin for a preset that has a preview", () => {
+    expect(factoryPresetPreviewUrl("generate-image/character-board", "https://app.nodaro.ai", FILES)).toBe(
+      "https://app.nodaro.ai/preset-previews/generate-image/character-board.1a2b3c4d.webp",
+    )
+    expect(factoryPresetPreviewUrl("generate-image/character-board", "http://localhost:3000/", FILES)).toBe(
+      "http://localhost:3000/preset-previews/generate-image/character-board.1a2b3c4d.webp",
+    )
+  })
+
+  it("is null for a preset without a preview", () => {
+    expect(factoryPresetPreviewUrl("generate-image/pose-board", "https://app.nodaro.ai", FILES)).toBeNull()
+    expect(factoryPresetPreviewUrl("not-a/preset", "https://app.nodaro.ai", FILES)).toBeNull()
+  })
+
+  it("is null when the base URL is unusable, rather than a broken link", () => {
+    for (const base of ["", "not a url", "javascript:alert(1)", "ftp://host"]) {
+      expect(factoryPresetPreviewUrl("generate-image/character-board", base, FILES)).toBeNull()
+    }
+  })
+
+  it("reads the committed map by default, and every committed preview resolves under /preset-previews/", () => {
+    for (const id of Object.keys(FACTORY_PRESET_PREVIEW_FILES)) {
+      expect(factoryPresetPreviewUrl(id, "https://app.nodaro.ai")).toMatch(
+        new RegExp(`^https://app\\.nodaro\\.ai${PRESET_PREVIEW_PATH}[a-z0-9-]+/[a-z0-9-]+\\.[0-9a-f]{8}\\.webp$`),
+      )
+    }
+    expect(factoryPresetPreviewUrl("not-a/preset", "https://app.nodaro.ai")).toBeNull()
+  })
+})

package/src/__tests__/factory-preset-references.test.ts

@@ -0,0 +1,222 @@
+/**
+ * How many connected reference images a preset works from (`minReferences`,
+ * served as `needsImage` / `minReferences` by `GET /v1/node-presets/factory`
+ * and on every user preset).
+ *
+ * Two sources feed one number (`presetMinReferences`):
+ *   - the `{image:N}` / `{image:N:label}` tokens in the preset's prompt fields —
+ *     derived, so a template that names its references can never under-report;
+ *   - a DECLARATION on the factory preset, for the families whose prompt says
+ *     "the attached photo" in words (Reference Sheet, Portrait Transformations,
+ *     Stylized Subject, Edits, …): no data field marks those, so the number is
+ *     stated where the preset is written.
+ *
+ * The guards below keep the declarations honest: a declaration never states
+ * less than the preset's own tokens, a group never mixes photo and text-only
+ * presets unless it is listed with a reason, and the families the product
+ * names as photo-based all resolve to at least one reference.
+ */
+import { describe, it, expect } from "vitest"
+import { FACTORY_PRESETS, MAX_PRESET_REFERENCES, presetMinReferences, type FactoryPreset } from "../factory-presets.js"
+import { NODE_PROMPT_CANDIDATE_FIELDS, computeNodePrompt } from "../resolve-prompt.js"
+import { nodeSupportsPromptAffixes } from "../node-prompt-fields.js"
+
+const all = (): Array<[nodeType: string, preset: FactoryPreset]> =>
+  Object.entries(FACTORY_PRESETS).flatMap(([nodeType, list]) => list.map((p) => [nodeType, p] as [string, FactoryPreset]))
+
+const effective = (nodeType: string, p: FactoryPreset): number => presetMinReferences(nodeType, p.data, p.minReferences)
+const tokenFloor = (nodeType: string, p: FactoryPreset): number => presetMinReferences(nodeType, p.data)
+
+describe("presetMinReferences — derived from the prompt's reference tokens", () => {
+  it("is 0 for a prompt with no tokens, and for data with no prompt at all", () => {
+    expect(presetMinReferences("generate-image", { prompt: "a red fox in the snow" })).toBe(0)
+    expect(presetMinReferences("generate-image", {})).toBe(0)
+  })
+
+  it("reads the highest position over bare and labelled tokens", () => {
+    expect(presetMinReferences("generate-image", { prompt: "make the persons in {image:1} faceless" })).toBe(1)
+    expect(presetMinReferences("generate-image", { prompt: "{image:1:person} holds {image:2:product}" })).toBe(2)
+    expect(presetMinReferences("generate-image", { prompt: "{image:3} beside {image:1:dog}" })).toBe(3)
+    expect(presetMinReferences("generate-video", { prompt: "{IMAGE:2:product} spins" })).toBe(2)
+  })
+
+  it("reads the pre/post text and the negative prompt, where the node has them", () => {
+    expect(presetMinReferences("generate-image", { promptPrefix: "keep {image:1} unchanged" })).toBe(1)
+    expect(presetMinReferences("generate-image", { promptSuffix: "lit like {image:2:settings}" })).toBe(2)
+    expect(presetMinReferences("generate-image", { negativePrompt: "anything unlike {image:1:face}" })).toBe(1)
+  })
+
+  it("ignores fields that are not the node's prompt fields, and values that are not text", () => {
+    expect(presetMinReferences("generate-image", { style: "{image:4}", prompt: "a cat" })).toBe(0)
+    expect(presetMinReferences("generate-image", { prompt: 42 as unknown as string })).toBe(0)
+  })
+
+  it("reads a node whose prompt lives in another field (llm-chat → userInput)", () => {
+    expect(presetMinReferences("llm-chat", { userInput: "describe {image:1}" })).toBe(1)
+    expect(presetMinReferences("llm-chat", { prompt: "describe {image:1}" })).toBe(0)
+  })
+
+  it("is 0 for a node type with no prompt fields (an app namespace such as recast-render)", () => {
+    expect(presetMinReferences("recast-render", { schemaVersion: 1, prompt: "{image:2}" })).toBe(0)
+    expect(presetMinReferences("does-not-exist", { prompt: "{image:2}" })).toBe(0)
+  })
+
+  it("never counts position 0 (positions start at 1)", () => {
+    expect(presetMinReferences("generate-image", { prompt: "{image:0}" })).toBe(0)
+  })
+
+  it("takes a declaration when it is higher than the tokens, and never goes below them", () => {
+    expect(presetMinReferences("generate-image", { prompt: "the attached photo" }, 1)).toBe(1)
+    expect(presetMinReferences("generate-image", { prompt: "{image:2}" }, 1)).toBe(2)
+    expect(presetMinReferences("generate-image", { prompt: "a cat" }, 0)).toBe(0)
+  })
+
+  it("never asks for more photos than any image model takes", () => {
+    expect(MAX_PRESET_REFERENCES).toBeGreaterThanOrEqual(4)
+    expect(MAX_PRESET_REFERENCES).toBeLessThan(100)
+    expect(presetMinReferences("generate-image", { prompt: "{image:99999}" })).toBe(MAX_PRESET_REFERENCES)
+    expect(presetMinReferences("generate-image", { prompt: "a cat" }, 5000)).toBe(MAX_PRESET_REFERENCES)
+    expect(presetMinReferences("generate-image", { prompt: `{image:${MAX_PRESET_REFERENCES}}` })).toBe(MAX_PRESET_REFERENCES)
+  })
+
+  it("ignores a declaration that is not a positive whole number", () => {
+    for (const bad of [-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(presetMinReferences("generate-image", { prompt: "a cat" }, bad)).toBe(0)
+    }
+  })
+})
+
+/**
+ * One source of truth with how a preset RUNS: the run resolves a node's prompt
+ * through `computeNodePrompt` (the editor's build, and `presetId` on
+ * /v1/generate-image — lib/presets/apply-image-preset.ts), which joins the
+ * node's candidate prompt fields and its pre/post text. A token in any field
+ * the run reads must be counted, or a preset would run with fewer photos than
+ * its prompt names.
+ */
+describe("presetMinReferences reads every field the run reads", () => {
+  const cases = Object.entries(NODE_PROMPT_CANDIDATE_FIELDS).flatMap(([nodeType, fields]) => [
+    ...fields.map((f) => [nodeType, f] as const),
+    ...(nodeSupportsPromptAffixes(nodeType) ? (["promptPrefix", "promptSuffix"] as const).map((f) => [nodeType, f] as const) : []),
+  ])
+
+  it.each(cases)("%s: a token in %s counts", (nodeType, field) => {
+    expect(presetMinReferences(nodeType, { [field]: "keep {image:3:subject} as is" })).toBe(3)
+  })
+
+  it("counts the same tokens in a factory preset's raw data as in the prompt the run assembles from it", () => {
+    for (const [nodeType, p] of all()) {
+      if (!(nodeType in NODE_PROMPT_CANDIDATE_FIELDS)) continue
+      const assembled = computeNodePrompt(nodeType, { ...p.data }, { refMap: new Map() })
+      const fromRun = presetMinReferences(nodeType, {
+        prompt: assembled,
+        negativePrompt: typeof p.data.negativePrompt === "string" ? p.data.negativePrompt : undefined,
+      })
+      expect(tokenFloor(nodeType, p), p.id).toBe(fromRun)
+    }
+  })
+})
+
+describe("factory presets — declared reference counts", () => {
+  it("a declaration is a positive whole number (absence means: no photo needed beyond the tokens)", () => {
+    const bad = all()
+      .filter(([, p]) => p.minReferences !== undefined && !(Number.isInteger(p.minReferences) && p.minReferences > 0))
+      .map(([, p]) => `${p.id}: ${p.minReferences}`)
+    expect(bad).toEqual([])
+  })
+
+  it("no preset declares fewer references than its own prompt tokens name", () => {
+    const under = all()
+      .filter(([nodeType, p]) => p.minReferences !== undefined && p.minReferences < tokenFloor(nodeType, p))
+      .map(([nodeType, p]) => `${p.id}: declares ${p.minReferences}, its tokens name ${tokenFloor(nodeType, p)}`)
+    expect(under).toEqual([])
+  })
+
+  it("no preset declares exactly what its tokens already say (the declaration is for prose, not tokens)", () => {
+    const redundant = all()
+      .filter(([nodeType, p]) => p.minReferences !== undefined && p.minReferences === tokenFloor(nodeType, p))
+      .map(([, p]) => p.id)
+    expect(redundant).toEqual([])
+  })
+
+  /**
+   * Groups whose presets mix photo-based and text-only entries on purpose.
+   * Every other group is all-or-nothing, so a preset added to a photo group
+   * without its declaration fails here instead of shipping as text-only.
+   */
+  const MIXED_GROUPS: Readonly<Record<string, string>> = {
+    "generate-image/Realism & Authentic":
+      "text-only realism shots beside two that put the user's own photo in the frame ({image:1:person}, {image:1:product})",
+  }
+
+  it("every group is all photo-based or all text-only, except the listed mixed groups", () => {
+    const groups = new Map<string, { photo: string[]; text: string[] }>()
+    for (const [nodeType, p] of all()) {
+      if (!p.group) continue
+      const key = `${nodeType}/${p.group}`
+      const g = groups.get(key) ?? { photo: [], text: [] }
+      ;(effective(nodeType, p) > 0 ? g.photo : g.text).push(p.id)
+      groups.set(key, g)
+    }
+    const mixed = [...groups.entries()]
+      .filter(([key, g]) => g.photo.length > 0 && g.text.length > 0 && !(key in MIXED_GROUPS))
+      .map(([key, g]) => `${key}: photo [${g.photo.join(", ")}] vs text-only [${g.text.join(", ")}]`)
+    expect(mixed).toEqual([])
+  })
+
+  it("each listed mixed group is still mixed (an entry that stopped mixing leaves the list)", () => {
+    for (const key of Object.keys(MIXED_GROUPS)) {
+      const [nodeType, ...rest] = key.split("/")
+      const group = rest.join("/")
+      const presets = (FACTORY_PRESETS[nodeType!] ?? []).filter((p) => p.group === group)
+      const photo = presets.filter((p) => effective(nodeType!, p) > 0).length
+      expect(photo, key).toBeGreaterThan(0)
+      expect(presets.length - photo, key).toBeGreaterThan(0)
+    }
+  })
+
+  /** The families the product names as working from a connected photo. */
+  const PHOTO_FAMILIES: ReadonlyArray<[nodeType: string, group: string]> = [
+    ["generate-image", "Reference Sheet"],
+    ["generate-image", "Cast & Consistency"],
+    ["generate-image", "Edit by Name"],
+    ["generate-image", "Face Privacy"],
+    ["generate-image", "Edits"],
+    ["generate-image", "Portrait Transformations"],
+    ["generate-image", "Stylized Subject"],
+    ["modify-image", "Edits"],
+    ["modify-image", "Stylized Subject"],
+    ["generate-video", "UGC & Creator"],
+  ]
+
+  it.each(PHOTO_FAMILIES)("%s · %s: every preset needs at least one reference", (nodeType, group) => {
+    const presets = (FACTORY_PRESETS[nodeType] ?? []).filter((p) => p.group === group)
+    expect(presets.length).toBeGreaterThan(0)
+    expect(presets.filter((p) => effective(nodeType, p) < 1).map((p) => p.id)).toEqual([])
+  })
+
+  it("every preset whose prompt uses {image:N} needs at least N references", () => {
+    const short = all()
+      .filter(([nodeType, p]) => effective(nodeType, p) < tokenFloor(nodeType, p))
+      .map(([, p]) => p.id)
+    expect(short).toEqual([])
+    expect(all().filter(([nodeType, p]) => tokenFloor(nodeType, p) > 0).length).toBeGreaterThan(5)
+  })
+
+  it.each([
+    ["generate-image", "generate-image/cast-mega-grid", 2],
+    ["generate-image", "generate-image/character-board", 1],
+    ["generate-image", "generate-image/faceless-3d-head", 1],
+    ["generate-image", "generate-image/product-in-hand", 1],
+    ["generate-image", "generate-image/cinematic-portrait", 0],
+    ["modify-image", "modify-image/background-remove", 1],
+    ["generate-video", "generate-video/ugc-product-closer", 2],
+    ["generate-video", "generate-video/handheld-unboxing", 2],
+    ["generate-video", "generate-video/ugc-talking-head", 1],
+    ["generate-video", "generate-video/slow-push-in", 0],
+  ] as const)("%s %s → %i", (nodeType, id, n) => {
+    const preset = (FACTORY_PRESETS[nodeType] ?? []).find((p) => p.id === id)
+    expect(preset, id).toBeDefined()
+    expect(effective(nodeType, preset!)).toBe(n)
+  })
+})