@nodaro/prompts 1.35.0 → 1.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.35.0",
+  "version": "1.36.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,10 @@
 // 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 { 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 +152,213 @@ 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) {
+      const text = allText(preset("generate-image", 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)
+  })
+})

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

@@ -280,13 +280,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__/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),
+    },
+  },
 ]

package/src/factory-presets/index.ts

@@ -1,3 +1,4 @@
+import { T2I_TO_I2I_VARIANT } from "@nodaro/shared"
 import type { FactoryPreset } from "./types.js"
 import { stylizedSubjectFor, editsFor } from "./shared-image.js"
 import { GENERATE_IMAGE_PRESETS } from "./generate-image.js"
@@ -14,6 +15,19 @@ import { LOTTIE_OVERLAY_PRESETS } from "./lottie-overlay.js"
 export type { FactoryPreset, FactoryPresetGroup } from "./types.js"
 export { groupFactoryPresets } from "./types.js"
 
+/**
+ * A shared preset as Modify Image takes it. Modify Image always works from a source photo, so its
+ * provider list names a model's image-to-image id where the model has a separate one
+ * (`seedream-5-pro` → `seedream-5-pro-i2i`). The shared catalogs may carry the text-to-image id
+ * Generate Image takes — its route switches to that same image-to-image model once a photo is
+ * connected. Providers with no separate image-to-image id are left as they are.
+ */
+function forModifyImage(p: FactoryPreset): FactoryPreset {
+  const provider = p.data.provider
+  const imageToImage = typeof provider === "string" ? T2I_TO_I2I_VARIANT[provider] : undefined
+  return imageToImage ? { ...p, data: { ...p.data, provider: imageToImage } } : p
+}
+
 /** System/factory presets shipped with the app. Assembled here in the original
  *  single-file key order; each value lives in its per-domain module. */
 export const FACTORY_PRESETS: Readonly<Record<string, readonly FactoryPreset[]>> = {
@@ -22,7 +36,7 @@ export const FACTORY_PRESETS: Readonly<Record<string, readonly FactoryPreset[]>>
   // modify-image shares the Stylized Subject + Edits catalogs with generate-image
   // (single source of truth in STYLIZED_SUBJECT / IMAGE_EDITS). modify-image is
   // slated for deprecation in favor of generate-image — when removed, drop this key.
-  "modify-image": [...stylizedSubjectFor("modify-image"), ...editsFor("modify-image")],
+  "modify-image": [...stylizedSubjectFor("modify-image"), ...editsFor("modify-image")].map(forModifyImage),
   "generate-video": GENERATE_VIDEO_PRESETS,
   "text-to-speech": TEXT_TO_SPEECH_PRESETS,
   "text-to-audio": TEXT_TO_AUDIO_PRESETS,

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

@@ -1,4 +1,5 @@
 import type { FactoryPreset } from "./types.js"
+import { REALISM_FINISH, REALISM_PASS_INSTRUCTION } from "../realism-wording.js"
 
 /**
  * Selective-stylization presets shared by `modify-image` (transform an input photo) and
@@ -190,6 +191,47 @@ const IMAGE_EDITS: ReadonlyArray<{
         "altered photo, restyled or recolored scene, covered faces, filled color blocks, sticker or clipart look, cliché phrases, garbled or misspelled handwriting, cluttered composition, watermark, blurry",
     },
   },
+  {
+    slug: "add-skin-realism",
+    name: "Add Skin Realism",
+    description: "Brings back visible skin texture — same person, same photo.",
+    data: { provider: "nano-banana-2-1", aspectRatio: "auto", resolution: "2K", promptPrefix: REALISM_PASS_INSTRUCTION },
+  },
+  {
+    slug: "natural-photo-finish",
+    name: "Natural Photo Finish",
+    description: "Takes out a rendered-looking finish, keeps the photo.",
+    data: {
+      provider: "nano-banana-2-1",
+      aspectRatio: "auto",
+      resolution: "2K",
+      promptPrefix: `Keep this photo as it is and take out only what makes it look rendered: smoothed, waxy or airbrushed skin, a glow, over-sharpened edges, hair too perfect to be real. ${REALISM_FINISH} Otherwise the same people, framing, pose and background.`,
+    },
+  },
+  {
+    slug: "phone-camera-look",
+    name: "Phone Camera Look",
+    description: "Re-finishes a photo as an everyday snapshot.",
+    data: {
+      provider: "nano-banana-2-1",
+      aspectRatio: "auto",
+      resolution: "2K",
+      promptPrefix: `Re-finish this photo, changing nothing in it: ${REALISM_FINISH} Same people, framing, pose and background.`,
+    },
+  },
+  {
+    slug: "undo-beauty-filter",
+    name: "Undo Beauty Filter",
+    description: "Reverses smoothing and reshaping on a real photo.",
+    data: {
+      provider: "seedream-5-pro",
+      // "auto" keeps the photo's shape: this model lists no native "auto", so on either node the
+      // run takes its listed ratio nearest the connected photo.
+      aspectRatio: "auto",
+      quality: "high",
+      promptPrefix: "Undo the beauty filter on this photo: bring back the person's real skin texture, the natural shape of the face, jaw, nose and eyes, and the real colour of skin and lips. Change nothing else: the same person, expression, hair, clothing, framing and background.",
+    },
+  },
 ]
 
 /** Build the Edits presets for a node type (id = `<nodeType>/<slug>`). */

package/src/factory-presets/text.ts

@@ -318,4 +318,15 @@ export const IMAGE_TO_TEXT_PRESETS: readonly FactoryPreset[] = [
     group: "Creative",
     data: { detailLevel: "detailed", customPrompt: "Describe this image as a detailed text-to-image generation prompt: subject, style, lighting, composition and lens. Return only the prompt." },
   },
+  {
+    id: "image-to-text/realism-audit",
+    name: "Realism Audit",
+    description: "Lists the signs an image was generated, with a count.",
+    group: "Creative",
+    data: {
+      detailLevel: "structured",
+      customPrompt:
+        "Check this image for signs that it was generated rather than photographed. Answer each question yes or no, with a few words why. 1. Is the skin smooth, waxy or airbrushed, with no visible pores? 2. Is the face unusually symmetrical, or are the teeth unnaturally even and white? 3. Are any hands or fingers malformed, merged or the wrong count? 4. Is any text, logo or sign garbled? 5. Is the background blurred far more than an everyday snapshot would be? 6. Are the catchlights in the eyes perfect rings, or identical in both eyes? 7. Is the hair uniformly perfect, with no flyaways? 8. Do edges look over-sharpened or haloed? 9. Is there a glow or bloom on the skin? 10. Do shadows or reflections disagree with the light? Finish with one line: \"Tells found: N of 10\".",
+    },
+  },
 ]

package/src/index.ts

@@ -90,6 +90,7 @@ export { stripAudioTags } from "./audio-tags.js"
 export * from "./node-prompt-fields.js"
 export * from "./factory-presets.js"
 export * from "./caption-treatments.js"
+export * from "./realism-wording.js"
 export * from "./style-presets.js"
 export * from "./object-asset-presets.js"
 export * from "./factory-snippets/index.js"

package/src/prompt-wizard-categories.ts

@@ -252,7 +252,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedance-2-fast": "Seedance 2.0 Fast — same multimodal + audio capabilities, cheaper and quicker",
     "seedance-2-mini": "Seedance 2.0 Mini — same multimodal + audio capabilities, budget tier, 480p/720p, 4-15s",
     "seedance-2-5": "Seedance 2.5 — up to 30s in ONE shot (no stitching), wider multimodal refs (30 images / 10 videos / 10 audio), native audio, 480p/720p/1080p",
-    "minimax-h3": "MiniMax Hailuo 3 — premium multimodal refs (9 images / 3 videos / 3 audio), always-on audio, 2K or 768P, 4-15s per-second pricing",
+    "minimax-h3": "MiniMax H3 — premium multimodal refs (9 images / 3 videos / 3 audio), always-on audio, 2K or 768P, 4-15s per-second pricing",
     "wan": "Versatile, good for animations and transformations",
     "wan-turbo": "Faster Wan generation",
     "hailuo-standard": "Standard quality, cost-effective",
@@ -283,7 +283,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedance-2-fast": "Seedance 2.0 Fast — same capabilities, cheaper and quicker",
     "seedance-2-mini": "Seedance 2.0 Mini — same capabilities, budget tier, 480p/720p",
     "seedance-2-5": "Seedance 2.5 — start/end frame + wide multimodal refs, native audio, up to 30s, 480p/720p/1080p",
-    "minimax-h3": "MiniMax Hailuo 3 — first/last frame + multimodal refs, always-on audio, 2K or 768P, 4-15s",
+    "minimax-h3": "MiniMax H3 — first/last frame + multimodal refs, always-on audio, 2K or 768P, 4-15s",
     "hailuo-2.3-pro": "Premium Hailuo animation",
     "hailuo-2.3": "Standard Hailuo animation",
     "hailuo-standard": "Cost-effective animation",

package/src/provider-prompt-doctrine.ts

@@ -23,7 +23,7 @@
  *   - KIE API docs https://docs.kie.ai/market/kling/kling-3-0
  *   - Live KIE-path dialogue probe 2026-07-16 (scripted lines spoken verbatim,
  *     lip-synced, on both kling-2.6 and kling-3.0 with sound=true)
- *   MiniMax Hailuo 3:
+ *   MiniMax H3:
  *   - KIE API docs https://docs.kie.ai/market/minimax-h3 (text-to-video /
  *     image-to-video / reference-to-video — the API contract is the doctrine
  *     source: limits, modes, aspect rules, pricing dimensions). No live probe
@@ -160,7 +160,7 @@ const KLING_AUDIO_DOCTRINE: ProviderPromptDoctrine = {
 
 const MINIMAX_H3_DOCTRINE: ProviderPromptDoctrine = {
   providers: ["minimax-h3"],
-  heading: "MiniMax Hailuo 3 (minimax-h3)",
+  heading: "MiniMax H3 (minimax-h3)",
   tips: [
     "Natural-language prompts up to 7000 chars. Front-load what matters: subject → action → scene/environment → lighting → camera move → style. One camera movement per shot.",
     "Output 2K (default) or 768P (cheaper tier). Aspect: pure text-to-video needs a concrete ratio (21:9/16:9/4:3/1:1/3:4/9:16); reference runs default to adaptive (match the input).",