@nodaro/prompts 1.35.0 → 1.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.35.0",
+  "version": "1.37.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -20,7 +20,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^3.26.0"
+    "@nodaro/shared": "^3.27.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/creator-presets.test.ts

@@ -1,7 +1,11 @@
 // packages/prompts/src/__tests__/creator-presets.test.ts
 import { describe, it, expect } from "vitest"
-import { captionRoutesToRemotion, presetApplyClearKeys } from "@nodaro/shared"
+import { aspectRatioOptionsByKind, captionRoutesToRemotion, MODELS_WITH_REFERENCE_IMAGE_SUPPORT, normalizeNodeModelParams, presetApplyClearKeys, resolveNodeRefs, resolveNormalizedImageGen, type ConnectedReference, type SourceImageSize } from "@nodaro/shared"
 import { getFactoryPresets, type FactoryPreset } from "../factory-presets.js"
+import { assembleImageInput } from "../assemble-image-input.js"
+import { computeNodePrompt } from "../resolve-prompt.js"
+import { resolveReferenceTokens } from "../video-reference-resolver.js"
+import { NEUTRAL_PERSON, REALISM_FINISH, REALISM_PASS_INSTRUCTION, REALISM_SKIN, realismEmptyHands, realismViewpoint } from "../realism-wording.js"
 
 /** Words that name a recording or viewing device. Plural forms included. */
 const DEVICE_WORDS = /\b(?:smartphones?|iphones?|phones?|cameras?|lens(?:es)?|webcams?|laptops?|tablets?|screens?|monitors?|displays?|tripods?|selfie[ -]sticks?)\b/i
@@ -149,3 +153,344 @@ describe("Wave 0 — Hook Plate and Body Captions", () => {
     for (const k of ["backgroundColor", "look", "positionY", "fontWeight", "maxWordsPerLine"]) expect(overClean[k], k).toBeUndefined()
   })
 })
+
+/** Every prompt-bearing field, joined — what the device and slot checks read. */
+const allText = (d: Readonly<Record<string, unknown>>) =>
+  ["promptPrefix", "prompt", "promptSuffix", "negativePrompt"].map((k) => d[k]).filter((v): v is string => typeof v === "string").join(" ")
+const wiredRunPrompts = (d: Readonly<Record<string, unknown>>): Record<"legacy" | "hybrid" | "urlsOnly", string> => {
+  const userPrompt = resolveNodeRefs(computeNodePrompt("generate-image", { ...d }, { refMap: new Map() }), new Map())
+  const wired = Math.max(0, ...[...userPrompt.matchAll(/\{image:(\d+)[^{}]*\}/gi)].map((m) => Number(m[1])))
+  const refs: ConnectedReference[] = Array.from({ length: wired }, (_, i) => ({
+    id: `ref-${i + 1}`, defaultName: `Reference ${i + 1}`, source: "wired-image", url: `https://example.com/ref-${i + 1}.jpg`,
+  }))
+  const provider = d.provider as string
+  return {
+    legacy: assembleImageInput({ userPrompt, provider, referenceFormat: "legacy", connectedReferences: refs }).prompt,
+    hybrid: assembleImageInput({ userPrompt, provider, referenceFormat: "hybrid", connectedReferences: refs }).prompt,
+    urlsOnly: assembleImageInput({ userPrompt, provider, extraReferenceImageUrls: refs.map((r) => r.url) }).prompt,
+  }
+}
+/** What the image route makes of a preset's levers with `refs` photos connected (and, when known, the size of the photo
+ *  being transformed): the credit tier, the ratio it runs at and anything it had to change. */
+const imageRouteRun = (node: string, d: Readonly<Record<string, unknown>>, refs: number, sourceImage?: SourceImageSize) =>
+  resolveNormalizedImageGen({
+    provider: d.provider as string, aspectRatio: d.aspectRatio, resolution: d.resolution, quality: d.quality, refCount: refs, sourceImage,
+    // Generate Image moves a text-to-image model to its image-to-image sibling once a photo is connected; Modify Image already names that sibling.
+    swapToI2i: node === "generate-image",
+  })
+/** The aspect ratio the workflow write step stores for one node of `type` carrying `d`. */
+const storedAspectRatio = (type: string, d: Readonly<Record<string, unknown>>) =>
+  normalizeNodeModelParams([{ id: "node", type, data: { ...d } }]).nodes[0]!.data.aspectRatio
+/** A preset's data without the named wording fields — what is left is its levers. */
+const leversOf = (d: Readonly<Record<string, unknown>>, ...wording: string[]) => Object.fromEntries(Object.entries(d).filter(([k]) => !wording.includes(k)))
+
+const REALISM_IDS = [
+  "unretouched-portrait", "phone-selfie", "candid-snapshot", "mirror-selfie",
+  "creator-at-home", "video-call-frame", "macro-skin-study", "product-in-hand",
+].map((s) => `generate-image/${s}`)
+const REALISM_REFERENCE_IDS = ["generate-image/creator-at-home", "generate-image/product-in-hand"]
+/** Each Realism preset's levers, and the credit tier the image route charges for them (its reference connected where it takes one). */
+const REALISM_RUNS: Readonly<Record<string, readonly [levers: Readonly<Record<string, string>>, creditId: string]>> = {
+  "generate-image/unretouched-portrait": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "3:4" }, "gpt-image-2:2K"],
+  "generate-image/phone-selfie": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "3:4" }, "gpt-image-2:2K"],
+  "generate-image/candid-snapshot": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "3:4" }, "gpt-image-2:2K"],
+  "generate-image/mirror-selfie": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "9:16" }, "gpt-image-2:2K"],
+  "generate-image/creator-at-home": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "9:16" }, "gpt-image-2-i2i:2K"],
+  "generate-image/video-call-frame": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "16:9" }, "gpt-image-2:2K"],
+  "generate-image/macro-skin-study": [{ provider: "seedream-5-pro", quality: "high", aspectRatio: "1:1" }, "seedream-5-pro:high"],
+  "generate-image/product-in-hand": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "3:4" }, "gpt-image-2-i2i:2K"],
+}
+
+describe("Wave 1 — Realism & Authentic", () => {
+  const group = () => getFactoryPresets("generate-image").filter((p) => p.group === "Realism & Authentic")
+
+  it("ships exactly these eight presets, in order, each on its model with that model's one lever, and no negativePrompt", () => {
+    expect(group().map((p) => p.id)).toEqual(REALISM_IDS)
+    expect(Object.keys(REALISM_RUNS)).toEqual(REALISM_IDS)
+    for (const p of group()) {
+      expect(leversOf(p.data, "prompt"), p.id).toEqual(REALISM_RUNS[p.id]![0])
+      expect(p.data.negativePrompt, p.id).toBeUndefined()
+    }
+  })
+
+  it("the image route runs each one on its levers unchanged, at its model's tier", () => {
+    for (const id of REALISM_IDS) {
+      const run = imageRouteRun("generate-image", preset("generate-image", id).data, REALISM_REFERENCE_IDS.includes(id) ? 1 : 0)
+      expect(run.adjustments, id).toEqual([])
+      expect(run.identifier, id).toBe(REALISM_RUNS[id]![1])
+    }
+  })
+
+  it("composes the selected fragments", () => {
+    const text = (slug: string) => preset("generate-image", `generate-image/${slug}`).data.prompt as string
+    for (const slug of ["unretouched-portrait", "phone-selfie", "candid-snapshot", "mirror-selfie", "creator-at-home", "macro-skin-study"]) expect(text(slug), slug).toContain(REALISM_SKIN)
+    for (const slug of ["unretouched-portrait", "phone-selfie", "candid-snapshot", "mirror-selfie", "creator-at-home", "video-call-frame", "product-in-hand"]) expect(text(slug), slug).toContain(REALISM_FINISH)
+    expect(text("phone-selfie")).toContain(realismViewpoint(NEUTRAL_PERSON))
+    expect(text("phone-selfie")).toContain(realismEmptyHands(NEUTRAL_PERSON))
+  })
+
+  it("names no device — the mirror self-portrait may say phone", () => {
+    for (const id of REALISM_IDS) {
+      const text = allText(preset("generate-image", id).data)
+      // A mirror self-portrait shows the phone in hand.
+      const scanned = id === "generate-image/mirror-selfie" ? text.replace(/\bphone\b/gi, "") : text
+      expect(scanned, id).not.toMatch(DEVICE_WORDS)
+    }
+  })
+
+  it("every subject slot has a default naming an adult; every setting slot has a default", () => {
+    for (const id of [...REALISM_IDS, ...UGC_IDS]) {
+      const text = allText(preset(id.split("/")[0]!, id).data)
+      for (const m of text.matchAll(/\{subject([^{}]*)\}/g)) {
+        expect(m[1], `${id}: {subject} needs a default`).toMatch(/\|\|/)
+        expect(m[1]!.split("||")[1], `${id}: the default names an adult`).toMatch(ADULT)
+      }
+      for (const m of text.matchAll(/\{setting([^{}]*)\}/g)) expect(m[1], `${id}: {setting} needs a default`).toMatch(/\|\|\s*\S/)
+    }
+  })
+
+  it("labels every reference token, and reads whole when the references are wired", () => {
+    const TOKEN = /\{(?:image|video|audio):\d+(:[^{}]*)?\}/gi
+    const count = (s: string, part: string) => s.split(part).length - 1
+    for (const id of REALISM_REFERENCE_IDS) expect(MODELS_WITH_REFERENCE_IMAGE_SUPPORT.has(preset("generate-image", id).data.provider as string), id).toBe(true)
+    const withTokens: string[] = []
+    for (const id of REALISM_IDS) {
+      const d = preset("generate-image", id).data
+      const text = allText(d)
+      const labels: string[] = []
+      for (const m of text.matchAll(TOKEN)) {
+        expect(m[1], `${id}: ${m[0]} needs a label`).toBeTruthy()
+        labels.push(m[1]!.slice(1))
+      }
+      if (labels.length > 0) withTokens.push(id)
+      const bare = text.replace(TOKEN, "")
+      for (const [path, out] of Object.entries(wiredRunPrompts(d))) {
+        const legacyReferenceLine = path === "legacy" ? 1 : 0
+        for (const label of new Set(labels)) {
+          const tokens = labels.filter((l) => l === label).length
+          expect(count(out, label), `${id} (${path}): ${label}`).toBeGreaterThanOrEqual(count(bare, label) + tokens + legacyReferenceLine)
+        }
+        expect(out, `${id} (${path})`).not.toMatch(/ {2}/)
+        expect(out, `${id} (${path})`).not.toMatch(/[{}]/)
+        expect(out, `${id} (${path})`).not.toMatch(/\bfrom\s+[.,;:!?]/)
+      }
+    }
+    expect(withTokens).toEqual(REALISM_REFERENCE_IDS)
+  })
+})
+
+describe("Wave 1 — Skin Detail Sheet", () => {
+  it("is a Reference Sheet board on seedream-5-pro at high quality, carrying the never-merge clause in pre/post text and no negativePrompt", () => {
+    const p = preset("generate-image", "generate-image/skin-detail-sheet")
+    expect(p.group).toBe("Reference Sheet")
+    expect(leversOf(p.data, "promptPrefix", "promptSuffix")).toEqual({ provider: "seedream-5-pro", quality: "high", aspectRatio: "3:2" })
+    expect(MODELS_WITH_REFERENCE_IMAGE_SUPPORT.has(p.data.provider as string)).toBe(true)
+    // The connected face photo moves the run to Seedream's image-to-image model, at the same tier.
+    const run = imageRouteRun("generate-image", p.data, 1)
+    expect(run.adjustments).toEqual([])
+    expect(run.identifier).toBe("seedream-5-pro-i2i:high")
+    expect(p.data.prompt).toBeUndefined()
+    expect(p.data.promptPrefix as string).toContain("never merging or omitting a panel")
+    expect(p.data.promptPrefix as string).toContain(REALISM_SKIN)
+    expect(p.data.negativePrompt).toBeUndefined()
+    expect(allText(p.data)).not.toMatch(DEVICE_WORDS)
+    const ids = getFactoryPresets("generate-image").map((x) => x.id)
+    expect(ids[ids.indexOf("generate-image/pet-board") + 1]).toBe("generate-image/skin-detail-sheet")
+  })
+})
+
+describe("Wave 1 — Edits", () => {
+  const SLUGS = ["add-skin-realism", "natural-photo-finish", "phone-camera-look", "undo-beauty-filter"]
+  const FINISH = { provider: "nano-banana-2-1", aspectRatio: "auto", resolution: "2K" }
+  const UNDO = { aspectRatio: "auto", quality: "high" }
+  /** Each Edit's levers per node. Modify Image's provider list names Seedream's image-to-image id, not the text-to-image one. */
+  const LEVERS: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>> = {
+    "generate-image": { "add-skin-realism": FINISH, "natural-photo-finish": FINISH, "phone-camera-look": FINISH, "undo-beauty-filter": { provider: "seedream-5-pro", ...UNDO } },
+    "modify-image": { "add-skin-realism": FINISH, "natural-photo-finish": FINISH, "phone-camera-look": FINISH, "undo-beauty-filter": { provider: "seedream-5-pro-i2i", ...UNDO } },
+  }
+
+  it("ships the four Edits on both image nodes after the Doodle Overlay pair, each on its model and levers, as pre-text only", () => {
+    for (const node of ["generate-image", "modify-image"]) {
+      const ids = getFactoryPresets(node).map((x) => x.id)
+      const i = ids.indexOf(`${node}/doodle-overlay-expressive`)
+      expect(ids.slice(i + 1, i + 5)).toEqual(SLUGS.map((s) => `${node}/${s}`))
+      for (const s of SLUGS) {
+        const p = preset(node, `${node}/${s}`)
+        expect(p.group).toBe("Edits")
+        expect(typeof p.data.promptPrefix, p.id).toBe("string")
+        expect(leversOf(p.data, "promptPrefix"), p.id).toEqual(LEVERS[node]![s])
+        // Every Edit asks for "auto", to keep the photo's shape. Undo Beauty Filter's model lists no
+        // native "auto"; how each node resolves it is pinned in the Undo Beauty Filter test below.
+        expect(p.data.aspectRatio, p.id).toBe("auto")
+        if (s !== "undo-beauty-filter") expect(aspectRatioOptionsByKind("image")[p.data.provider as string]?.map((o) => o.value), p.id).toContain("auto")
+        expect((p.data.promptPrefix as string).length).toBeLessThanOrEqual(2000)
+        expect(allText(p.data), p.id).not.toMatch(DEVICE_WORDS)
+      }
+    }
+  })
+
+  it("Undo Beauty Filter keeps the photo's shape on both nodes", () => {
+    // The write step stores "auto" as written, and the run takes the model's listed ratio nearest the
+    // connected photo's size, on Seedream 5 Pro's image-to-image model at high quality.
+    const photos: ReadonlyArray<readonly [SourceImageSize, string]> = [[{ width: 1104, height: 1472 }, "3:4"], [{ width: 1600, height: 1000 }, "3:2"]]
+    for (const node of ["generate-image", "modify-image"]) {
+      const d = preset(node, `${node}/undo-beauty-filter`).data
+      expect(storedAspectRatio(node, d), node).toBe("auto")
+      for (const [photo, ratio] of photos) {
+        const run = imageRouteRun(node, d, 1, photo)
+        expect(run.aspectRatio, `${node} ${photo.width}x${photo.height}`).toBe(ratio)
+        expect(run.modelId, node).toBe("seedream-5-pro-i2i")
+        expect(run.identifier, node).toBe("seedream-5-pro-i2i:high")
+      }
+    }
+  })
+
+  it("Add Skin Realism is the realism instruction verbatim; the finish edits carry the finish sentence", () => {
+    expect(preset("generate-image", "generate-image/add-skin-realism").data.promptPrefix).toBe(REALISM_PASS_INSTRUCTION)
+    for (const s of ["natural-photo-finish", "phone-camera-look"])
+      expect(preset("generate-image", `generate-image/${s}`).data.promptPrefix as string, s).toContain(REALISM_FINISH)
+  })
+})
+
+describe("Wave 1 — Realism Audit", () => {
+  it("is a structured Creative reading that answers ten yes/no questions and ends with a count", () => {
+    const p = preset("image-to-text", "image-to-text/realism-audit")
+    expect(p.group).toBe("Creative")
+    expect(p.data.detailLevel).toBe("structured")
+    const prompt = p.data.customPrompt as string
+    expect(prompt).toContain("Tells found: N of 10")
+    for (let n = 1; n <= 10; n++) expect(prompt).toContain(`${n}. `)
+    expect(prompt.length).toBeLessThanOrEqual(2000)
+  })
+})
+
+/** The prompt as a run sends it with nothing wired: slot defaults applied, reference tokens dropped to their labels. */
+const unwired = (text: string) =>
+  resolveReferenceTokens(resolveNodeRefs(text, new Map([["nothing-wired", ""]])), { image: 0, video: 0, audio: 0 }) ?? ""
+
+const UGC_IDS = [
+  "ugc-talking-head", "ugc-product-closer", "handheld-unboxing", "get-ready-with-me",
+  "street-qa", "reaction-shot", "acts-on-phone",
+].map((s) => `generate-video/${s}`)
+// The action is typing on a phone while looking down at it; its screen faces away.
+const PHONE_CLOSER_SENTENCE = "In the last seconds the person picks up a phone and looks down into its screen while typing on it for a moment, then looks back up at the viewer; the screen faces away from the camera."
+
+describe("Wave 2 — UGC & Creator", () => {
+  const group = () => getFactoryPresets("generate-video").filter((p) => p.group === "UGC & Creator")
+
+  it("ships exactly these seven, in order, on Seedance 2.5 at 9:16 and 720p with audio, 8 s except the 5 s answer and reaction, and no negativePrompt", () => {
+    const SHORT = ["generate-video/street-qa", "generate-video/reaction-shot"]
+    expect(group().map((p) => p.id)).toEqual(UGC_IDS)
+    for (const p of group()) {
+      expect(p.data, p.id).toMatchObject({ provider: "seedance-2-5", aspectRatio: "9:16", resolution: "720p", generateAudio: true })
+      expect(p.data.duration, p.id).toBe(SHORT.includes(p.id) ? 5 : 8)
+      expect(p.data.negativePrompt, p.id).toBeUndefined()
+    }
+  })
+
+  it("every prompt ends with the subtitle-free tail", () => {
+    for (const id of UGC_IDS)
+      expect((preset("generate-video", id).data.prompt as string).endsWith("Keep it subtitle-free, do not generate a watermark."), id).toBe(true)
+  })
+
+  it("names no device outside the one pinned sentence", () => {
+    // The one pinned sentence is the only text the scan skips: the phone closer, in one preset.
+    for (const id of UGC_IDS) {
+      let text = allText(preset("generate-video", id).data)
+      if (id === "generate-video/acts-on-phone") text = text.split(PHONE_CLOSER_SENTENCE).join(" ")
+      expect(text, id).not.toMatch(DEVICE_WORDS)
+    }
+    expect(preset("generate-video", "generate-video/acts-on-phone").data.prompt as string).toContain(PHONE_CLOSER_SENTENCE)
+  })
+
+  it("a default spoken line is one sentence with its numbers in words", () => {
+    let lines = 0
+    for (const id of UGC_IDS) {
+      for (const m of (preset("generate-video", id).data.prompt as string).matchAll(/\{line \|\| ([^{}]*)\}/g)) {
+        lines += 1
+        expect(m[1], id).toMatch(/^[^.!?]*[.!?]$/)
+        expect(m[1], id).not.toMatch(/\d/)
+      }
+    }
+    expect(lines).toBe(5)
+  })
+
+  it("labels every reference token, and reads whole with nothing wired", () => {
+    for (const id of UGC_IDS) {
+      const text = allText(preset("generate-video", id).data)
+      for (const m of text.matchAll(/\{(?:image|video|audio):\d+(:[^{}]*)?\}/gi)) expect(m[1], `${id}: ${m[0]} needs a label`).toBeTruthy()
+      const out = unwired(text)
+      expect(out, id).not.toMatch(/ {2}/)
+      expect(out, id).not.toMatch(/[{}]/)
+      expect(out, id).not.toMatch(/\bfrom\s+[.,;:!?]/)
+    }
+  })
+
+  it("the rows that carry a spoken line tell the user to type it with numbers as words", () => {
+    for (const id of UGC_IDS) {
+      const p = preset("generate-video", id)
+      if (/\{line \|\|/.test(p.data.prompt as string)) expect(p.description, id).toMatch(/numbers as words/)
+    }
+    expect(preset("generate-video", "generate-video/street-qa").description).toContain("staged")
+  })
+})
+
+const WRITER_CLOSER = "closer — the last line. It ends on one simple physical action the speaker can do on camera."
+const closerParts = (s: string) => s.split("\n\n").filter((part) => part.startsWith("closer —"))
+
+describe("Wave 2 — UGC Monologue Writer", () => {
+  const p = () => preset("llm-chat", "llm-chat/ugc-monologue-writer")
+  it("sits in Writing & Marketing after Hook Generator, set to Claude Opus 5.5 at high effort, at temperature 0.8 and 2048 tokens", () => {
+    expect(p().group).toBe("Writing & Marketing")
+    expect(p().data).toMatchObject({ llmModel: "claude-opus-5.5", reasoningEffort: "high", temperature: 0.8, maxTokens: 2048 })
+    const ids = getFactoryPresets("llm-chat").map((x) => x.id)
+    expect(ids[ids.indexOf("llm-chat/hook-generator") + 1]).toBe("llm-chat/ugc-monologue-writer")
+  })
+  it("pins the closer to one simple physical action", () => {
+    const s = p().data.systemPrompt as string
+    expect(s.length).toBeLessThanOrEqual(10_000)
+    expect(s).toContain("at most 8 words")
+    for (const k of ['"hook"', '"beats"', '"closer"']) expect(s).toContain(k)
+    expect(s).not.toMatch(/per second/i)
+    expect(closerParts(s)).toEqual([WRITER_CLOSER])
+  })
+})
+
+describe("UGC Monologue Writer — Hebrew paragraph", () => {
+  it("carries the Hebrew craft paragraph and still passes the Writer's checks", () => {
+    const s = preset("llm-chat", "llm-chat/ugc-monologue-writer").data.systemPrompt as string
+    expect(s).toContain("When the script is in Hebrew:")
+    expect(s.indexOf("When the script is in Hebrew:")).toBeLessThan(s.indexOf("Return only this JSON"))
+    expect(s.match(/at most 8 words/g)?.length).toBe(2)
+    expect(s).not.toMatch(/per second/i)
+    expect(closerParts(s)).toEqual([WRITER_CLOSER])
+    expect(s.length).toBeLessThanOrEqual(10_000)
+  })
+})
+
+describe("Wave 2 — Phone Footage Look", () => {
+  it("is a Restyle Look on Wan 2.7 VideoEdit that keeps the source's own sound and length, whose description warns it is for b-roll, with the finish sentence and no device in its text", () => {
+    const p = preset("video-to-video", "video-to-video/phone-footage-look")
+    expect(p.group).toBe("Restyle Looks")
+    expect(leversOf(p.data, "promptPrefix", "negativePrompt")).toEqual({
+      provider: "wan-videoedit", v2vResolution: "720p", videoEditDuration: "0", audioSetting: "origin", promptExtend: false,
+    })
+    expect(p.description).toContain("b-roll")
+    expect(p.description).toContain("not for talking clips")
+    expect(p.data.promptPrefix as string).toContain(REALISM_FINISH)
+    expect((p.data.negativePrompt as string).length).toBeLessThanOrEqual(500)
+    expect(allText(p.data)).not.toMatch(DEVICE_WORDS)
+  })
+})
+
+describe("Wave 2 — UGC Ad script style guide", () => {
+  it("keeps its name and slot, is set to Claude Opus 5.5 at high effort, and asks for the payload first, spoken texture, the exact brand, digits and only the user's figures — without the JSON shape", () => {
+    const p = preset("generate-script", "generate-script/ugc-ad")
+    expect(p.name).toBe("UGC Ad (Hook–Show–Proof–Opinion)")
+    expect(p.data).toMatchObject({ llmModel: "claude-opus-5.5", reasoningEffort: "high" })
+    const g = p.data.styleGuide as string
+    expect(g).toContain("{product}")
+    for (const s of ["claim the viewer can check", "contractions", "exactly as given", "as digits", "Use only figures the user supplies", "take the Proof from the topic"]) expect(g).toContain(s)
+    expect(g).not.toContain('"hook"')
+  })
+})

package/src/__tests__/factory-presets.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest"
 import { FACTORY_PRESETS, getFactoryPresets, groupFactoryPresets } from "../factory-presets.js"
-import { extractPresetData, PRESET_APPLY_CLEAR_KEYS } from "@nodaro/shared"
+import { extractPresetData, LLM_MODEL_IDS, PRESET_APPLY_CLEAR_KEYS } from "@nodaro/shared"
 import { COMPOSER_PLAN_MAP, COMPOSER_PLAN_FIELDS } from "@nodaro/shared"
 import { STYLE_IDS } from "../index.js"
 import { joinPromptParts } from "../resolve-prompt.js"
@@ -54,6 +54,13 @@ describe("FACTORY_PRESETS", () => {
     }
   })
 
+  it("names an LLM only by an id the routes accept", () => {
+    for (const p of Object.values(FACTORY_PRESETS).flat()) {
+      if (p.data.llmModel === undefined) continue
+      expect(LLM_MODEL_IDS, `${p.id}: llmModel ${String(p.data.llmModel)}`).toContain(p.data.llmModel as never)
+    }
+  })
+
   it("generate-image factory presets use a known image provider", () => {
     for (const p of getFactoryPresets("generate-image")) {
       if (p.data.provider !== undefined) {
@@ -280,13 +287,30 @@ describe("generate-image factory preset data validity", () => {
     }
   })
 
-  it("every generate-image preset has a non-empty negativePrompt", () => {
+  // These presets carry their whole wording in the prompt; an added negative list would change the wording they were written with.
+  const NEGATIVE_EXEMPT: ReadonlySet<string> = new Set([
+    "generate-image/unretouched-portrait", "generate-image/phone-selfie", "generate-image/candid-snapshot",
+    "generate-image/mirror-selfie", "generate-image/creator-at-home", "generate-image/video-call-frame",
+    "generate-image/macro-skin-study", "generate-image/product-in-hand", "generate-image/skin-detail-sheet",
+    "generate-image/add-skin-realism", "generate-image/natural-photo-finish", "generate-image/phone-camera-look",
+    "generate-image/undo-beauty-filter",
+  ])
+
+  it("every generate-image preset has a non-empty negativePrompt (except the exempt ones, which carry none)", () => {
     for (const p of presets) {
+      if (NEGATIVE_EXEMPT.has(p.id)) {
+        expect(p.data.negativePrompt, `${p.id}: carries its whole wording in the prompt`).toBeUndefined()
+        continue
+      }
       const neg = (p.data.negativePrompt as string | undefined) ?? ""
       expect(neg.trim().length, `${p.id}: missing negativePrompt`).toBeGreaterThan(0)
     }
   })
 
+  it("every negative-exempt id exists", () => {
+    for (const id of NEGATIVE_EXEMPT) expect(presets.some((p) => p.id === id), id).toBe(true)
+  })
+
   it("non-style-pinned generate-image prompts are substantive (no thin one-liners)", () => {
     for (const p of presets) {
       if (p.data.style !== undefined) continue // style field carries the look; short prompt is fine

package/src/__tests__/node-prompt-fields.test.ts

@@ -16,10 +16,10 @@ describe("nodeSupportsPromptAffixes", () => {
     expect(nodeSupportsPromptAffixes("not-a-node")).toBe(false)
     expect(nodeSupportsPromptAffixes(undefined)).toBe(false)
   })
-  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (41 types)", () => {
+  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (42 types)", () => {
     const expected = Object.entries(NODE_PROMPT_FIELDS).filter(([, s]) => s.affixes !== false).map(([t]) => t)
     expect([...PROMPT_AFFIX_NODE_TYPES].sort()).toEqual(expected.sort())
-    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(41)
+    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(42)
   })
   it("getPromptFields still resolves", () => expect(getPromptFields("generate-image")?.prompt).toBe("prompt"))
 })

package/src/__tests__/realism-wording.test.ts

@@ -0,0 +1,41 @@
+// packages/prompts/src/__tests__/realism-wording.test.ts
+import { describe, it, expect } from "vitest"
+import * as wording from "../realism-wording.js"
+
+// These strings are read at run time by other Nodaro services; changing one changes their output on the next deploy, so a change needs its owner's review.
+describe("realism wording (frozen)", () => {
+  it("exports exactly the selected fragments and the two person functions", () => {
+    expect(Object.keys(wording).sort()).toEqual(
+      ["NEUTRAL_PERSON", "REALISM_FINISH", "REALISM_PASS_INSTRUCTION", "REALISM_SKIN", "realismEmptyHands", "realismViewpoint"].sort(),
+    )
+  })
+
+  it("keeps every fragment's text", () => {
+    expect(wording.REALISM_SKIN).toBe(
+      "Skin shows its real structure: visible pores that vary in size across the nose and cheeks, fine vellus hair catching the light, faint uneven pigmentation, a little redness around the nostrils, natural oil on the forehead.",
+    )
+    expect(wording.REALISM_FINISH).toBe(
+      "The plain look of an everyday small-sensor snapshot: colour left as it was recorded, deep focus from the nearest shoulder to the background, a fine grain in the darker areas, bright areas that fade rather than clip.",
+    )
+    expect(wording.REALISM_PASS_INSTRUCTION).toBe(
+      "Make this photo look like an unretouched everyday snapshot: skin that shows its pores, its fine hairs and the small changes in tone real skin has, colour left as it was recorded, everything sharp from the shoulders to the background, a little grain in the shadows. Take out anything that makes it look rendered — smoothed, waxy or airbrushed skin, a glow, over-sharpened edges — and add no text or icons. Otherwise it stays the same person in the same frame: the face and its proportions, hair, clothing, pose and background as they are.",
+    )
+  })
+
+  it("keeps the viewpoint and empty-hands sentences, neutral and gendered", () => {
+    expect(wording.realismViewpoint(wording.NEUTRAL_PERSON)).toBe(
+      "The person is looking straight at the viewer from eye level, mid-sentence: their face and shoulders close up, the framing loose and a little crooked, both arms relaxed and down out of the frame. The whole image is the photograph itself, edge to edge, with no text or icons anywhere.",
+    )
+    expect(wording.realismViewpoint({ subject: "she", possessive: "her" })).toBe(
+      "She is looking straight at the viewer from eye level, mid-sentence: her face and shoulders close up, the framing loose and a little crooked, both arms relaxed and down out of the frame. The whole image is the photograph itself, edge to edge, with no text or icons anywhere.",
+    )
+    expect(wording.realismEmptyHands(wording.NEUTRAL_PERSON)).toBe("Their hands are empty; the person is holding nothing.")
+    expect(wording.realismEmptyHands({ subject: "he", possessive: "his" })).toBe("His hands are empty; he is holding nothing.")
+  })
+
+  it("names no device", () => {
+    const DEVICE_WORDS = /\b(?:smartphones?|iphones?|phones?|cameras?|lens(?:es)?|webcams?|laptops?|tablets?|screens?|monitors?|displays?|tripods?|selfie[ -]sticks?)\b/i
+    for (const s of [wording.REALISM_SKIN, wording.REALISM_FINISH, wording.REALISM_PASS_INSTRUCTION, wording.realismViewpoint(wording.NEUTRAL_PERSON), wording.realismEmptyHands(wording.NEUTRAL_PERSON)])
+      expect(s).not.toMatch(DEVICE_WORDS)
+  })
+})

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

@@ -1,5 +1,13 @@
 import type { FactoryPreset } from "./types.js"
 import { stylizedSubjectFor, editsFor } from "./shared-image.js"
+import { NEUTRAL_PERSON, REALISM_FINISH, REALISM_SKIN, realismEmptyHands, realismViewpoint } from "../realism-wording.js"
+
+/** Joins the sentences of one prompt with single spaces. */
+const sentences = (...parts: string[]): string => parts.join(" ")
+/** The model and resolution the Realism & Authentic presets render with. */
+const REALISM_MODEL = { provider: "gpt-image-2", resolution: "2K" } as const
+/** The model and quality the close skin studies render with (Macro Skin Study, Skin Detail Sheet). */
+const SKIN_STUDY_MODEL = { provider: "seedream-5-pro", quality: "high" } as const
 
 export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
   // ── Reference Sheet ──────────────────────────────────────────────────────
@@ -168,6 +176,22 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
         "illustration, cartoon, 3d render, garbled text, misspelled labels, watermark, deformed anatomy, inconsistent markings between panels, wrong breed, blurry, low resolution",
     },
   },
+  {
+    id: "generate-image/skin-detail-sheet",
+    name: "Skin Detail Sheet",
+    description: "Connect a sharp face photo → a six-panel skin reference.",
+    group: "Reference Sheet",
+    data: {
+      ...SKIN_STUDY_MODEL,
+      aspectRatio: "3:2",
+      promptPrefix: sentences(
+        "Create a single skin detail reference sheet titled \"SKIN DETAIL SHEET\" from the attached photo of the person, the single source of truth for identity, skin tone and features. The same person, the same light and the same unretouched skin in every panel. Six panels — render ALL six panel headings exactly as written, never merging or omitting a panel: PANEL 01 — FULL FACE (front, eye level) · PANEL 02 — LEFT CHEEK & NOSE · PANEL 03 — RIGHT CHEEK & JAW · PANEL 04 — FOREHEAD & HAIRLINE · PANEL 05 — EYES & BROWS · PANEL 06 — LIPS & CHIN. In every panel:",
+        REALISM_SKIN,
+        "Flat, even daylight, neutral colour, everything sharp.",
+      ),
+      promptSuffix: "Plain neutral grey background, thin white panel labels in English. Use this sheet as a visual reference for consistent skin detail of this person across generations.",
+    },
+  },
   // ── Cast & Consistency (clean grids per the multi-character workflow:
   // sterile neutral-background reference grids built to be FED BACK as identity
   // anchors — unlike the editorial boards above, decoration here is noise.
@@ -1703,4 +1727,94 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
   // instruction lives in the prompt, not `style`.
   ...stylizedSubjectFor("generate-image"),
   ...editsFor("generate-image"),
+
+  // ── Realism & Authentic ──────────────────────────────────────────────────
+  {
+    id: "generate-image/unretouched-portrait",
+    name: "Unretouched Portrait",
+    description: "Straight-on head-and-shoulders portrait, real skin, everyday finish.",
+    group: "Realism & Authentic",
+    data: {
+      ...REALISM_MODEL,
+      aspectRatio: "3:4",
+      prompt: sentences("{subject || An adult woman in her thirties with dark shoulder-length hair}, a straight-on head-and-shoulders portrait at eye level against a plain pale wall, soft daylight from one side.", REALISM_SKIN, REALISM_FINISH),
+    },
+  },
+  {
+    id: "generate-image/phone-selfie",
+    name: "Phone Selfie",
+    description: "Eye-level, arm's-length self-portrait look.",
+    group: "Realism & Authentic",
+    data: {
+      ...REALISM_MODEL,
+      aspectRatio: "3:4",
+      prompt: sentences("{subject || An adult woman in her late twenties with her hair tied back}, {setting || on a couch at home, a cushion and a lamp behind}.", realismViewpoint(NEUTRAL_PERSON), realismEmptyHands(NEUTRAL_PERSON), REALISM_SKIN, REALISM_FINISH),
+    },
+  },
+  {
+    id: "generate-image/candid-snapshot",
+    name: "Candid Phone Snapshot",
+    description: "Caught mid-moment, an everyday snapshot.",
+    group: "Realism & Authentic",
+    data: {
+      ...REALISM_MODEL,
+      aspectRatio: "3:4",
+      prompt: sentences("{subject || An adult man in his thirties} caught mid-moment, not posing, glancing away, the framing a little crooked, part of the scene cut by the edge, {setting || at a kitchen table at home}.", REALISM_SKIN, REALISM_FINISH),
+    },
+  },
+  {
+    id: "generate-image/mirror-selfie",
+    name: "Mirror Selfie",
+    description: "Mirror self-portrait, phone in hand.",
+    group: "Realism & Authentic",
+    data: {
+      ...REALISM_MODEL,
+      aspectRatio: "9:16",
+      prompt: sentences("{subject || An adult woman in her twenties} photographs their reflection in a full-length mirror {setting || in a hallway at home}, a phone held at chest height with its back toward the mirror.", REALISM_SKIN, REALISM_FINISH),
+    },
+  },
+  {
+    id: "generate-image/creator-at-home",
+    name: "Creator at Home · Waist-Up",
+    description: "A waist-up reference of the same person — wire a face photo into the references.",
+    group: "Realism & Authentic",
+    data: {
+      ...REALISM_MODEL,
+      aspectRatio: "9:16",
+      prompt: sentences("Waist-up photo of {image:1:person}, an adult, standing at home in front of a plain wall, arms relaxed, empty hands.", REALISM_SKIN, REALISM_FINISH),
+    },
+  },
+  {
+    id: "generate-image/video-call-frame",
+    name: "Webcam / Video-Call Frame",
+    description: "Chest-up video-call framing.",
+    group: "Realism & Authentic",
+    data: {
+      ...REALISM_MODEL,
+      aspectRatio: "16:9",
+      prompt: sentences("{subject || An adult man in his forties}, chest-up, a little off-centre, slightly wide, seen from a fixed point just above eye level about an arm's length away, a softly lit room behind, flat even light from the front.", REALISM_FINISH),
+    },
+  },
+  {
+    id: "generate-image/macro-skin-study",
+    name: "Macro Skin Study",
+    description: "A close study of one area of skin.",
+    group: "Realism & Authentic",
+    data: {
+      ...SKIN_STUDY_MODEL,
+      aspectRatio: "1:1",
+      prompt: sentences("{feature || the left cheek and the side of the nose} of {subject || an adult woman in her thirties}, filling the frame, everything sharp front to back, flat cool daylight, neutral colour, a plain study of the skin, not a glamour shot.", REALISM_SKIN),
+    },
+  },
+  {
+    id: "generate-image/product-in-hand",
+    name: "Product in Hand — phone photo",
+    description: "Wire a photo of the product into the references.",
+    group: "Realism & Authentic",
+    data: {
+      ...REALISM_MODEL,
+      aspectRatio: "3:4",
+      prompt: sentences("{subject || An adult woman in her thirties} holds {image:1:product} at chest height toward the viewer, label facing out, {setting || in a bright room at home}.", REALISM_FINISH),
+    },
+  },
 ]