@nodaro/prompts 1.34.0 → 1.36.0

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,11 +1,12 @@
 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
  * `generate-image` (use a connected reference image). `modify-image` is slated for deprecation in
  * favor of `generate-image`, so the catalog lives in ONE place to prevent the two from drifting —
- * when `modify-image` is removed, just drop its key from `FACTORY_PRESETS` below. `nano-banana-pro`
- * is a valid provider for both nodes' enums (IMAGE_GEN_PROVIDERS and MODIFY_IMAGE_PROVIDERS).
+ * when `modify-image` is removed, just drop its key from `FACTORY_PRESETS` below. The provider is
+ * set per node by {@link editProviderFor}.
  */
 const STYLIZED_SUBJECT: ReadonlyArray<{
   readonly slug: string
@@ -18,7 +19,6 @@ const STYLIZED_SUBJECT: ReadonlyArray<{
     name: "Cartoon Person, Real World",
     description: "Subject → 3D cartoon, rest stays photoreal.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Restyle ONLY the person in the reference image into a polished 3D animated character — Pixar/Disney sensibility: soft subsurface skin shading, expressive oversized eyes, smoothly stylized hair, clean rounded forms. Preserve their identity, exact pose, expression, and framing. Everything else stays untouched and fully photorealistic: keep the original background, props, clothing fabric and texture, and the scene's real lighting, shadows, and color grade. Composite the stylized figure into the real plate so it sits naturally — matched light direction, contact shadows, and depth.",
       negativePrompt:
@@ -30,7 +30,6 @@ const STYLIZED_SUBJECT: ReadonlyArray<{
     name: "Caricature, Real Photo",
     description: "Exaggerated cartoon head on a real scene.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Turn ONLY the person into a playful hand-illustrated caricature: enlarge the head, exaggerate their most recognizable features, and amplify expression with bold, confident linework and clean cel-style shading — while keeping them clearly identifiable. Leave everything else exactly as shot and photorealistic: the body proportions below the neck, the clothing, the background, props, and the scene's real lighting and shadows remain unchanged. Blend the caricature head onto the real photo seamlessly with matched lighting and a believable neckline.",
       negativePrompt:
@@ -42,7 +41,6 @@ const STYLIZED_SUBJECT: ReadonlyArray<{
     name: "Anime Person, Real Background",
     description: "Subject → 2D anime, real environment.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Restyle ONLY the person as a crisp 2D anime character — clean ink outlines, flat cel shading with sharp shadow shapes, glossy stylized hair, and expressive anime eyes — while preserving their identity, pose, expression, and framing. Keep the real-world background, environment, props, and the original photographic lighting, shadows, and color completely untouched and photorealistic. Integrate the 2D figure into the live-action plate so the light direction and contact shadows read naturally.",
       negativePrompt:
@@ -54,7 +52,6 @@ const STYLIZED_SUBJECT: ReadonlyArray<{
     name: "Real Person, Cartoon World",
     description: "Inverse — real subject, stylized world.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Inverse stylization: keep the PERSON completely photorealistic and unchanged — real skin, hair, clothing, identity, pose, and framing all preserved exactly. Restyle ONLY the surrounding world into a vibrant, hand-crafted cartoon environment: simplified painterly shapes, bold saturated colors, soft graphic shading, and whimsical stylized props and scenery. Light the real person to match the cartoon world's color and direction so they sit convincingly inside it, with believable contact shadows.",
       negativePrompt:
@@ -66,7 +63,6 @@ const STYLIZED_SUBJECT: ReadonlyArray<{
     name: "Claymation Figure, Real Set",
     description: "Subject → clay figure, real surroundings.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Restyle ONLY the person into a tactile stop-motion claymation figure — molded plasticine surface with visible fingerprints, tool marks, subtle seams, and a soft matte sheen, in the handmade spirit of Aardman puppets — while keeping their identity, pose, expression, and framing. Everything else stays exactly as shot and photorealistic: the real background, set, props, and the scene's natural lighting and shadows are unchanged. Seat the clay figure into the real plate with matched light direction and grounded contact shadows.",
       negativePrompt:
@@ -76,13 +72,23 @@ const STYLIZED_SUBJECT: ReadonlyArray<{
 ]
 
 /** Build the Stylized Subject presets for a node type (id = `<nodeType>/<slug>`). */
+/**
+ * Both preset families are edits of a connected photo, so they run on the platform's edit model,
+ * GPT Image 2.5 Flare (decided 2026-10-08 from the image model bake-off: it kept pose, framing and
+ * product design on every edit). Modify Image takes the i2i id; Generate Image takes the t2i id,
+ * which the platform swaps to the same i2i model whenever a reference image is connected.
+ */
+export function editProviderFor(nodeType: string): string {
+  return nodeType === "modify-image" ? "gpt-image-2-5-flare-i2i" : "gpt-image-2-5-flare"
+}
+
 export function stylizedSubjectFor(nodeType: string): FactoryPreset[] {
   return STYLIZED_SUBJECT.map((p) => ({
     id: `${nodeType}/${p.slug}`,
     name: p.name,
     description: p.description,
     group: "Stylized Subject",
-    data: p.data,
+    data: { provider: editProviderFor(nodeType), ...p.data },
   }))
 }
 
@@ -102,7 +108,6 @@ const IMAGE_EDITS: ReadonlyArray<{
     name: "Remove Background",
     description: "Cut out the subject on white.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Cleanly cut the main subject out of the reference image and place it on a pure, solid white background. Trace a crisp, accurate edge — preserve fine detail like hair strands, fur, and translucent or wispy edges — with no leftover background pixels and no color fringing. Keep the subject itself completely unchanged: same pose, lighting, color, and full silhouette, nothing cropped.",
       negativePrompt:
@@ -114,7 +119,6 @@ const IMAGE_EDITS: ReadonlyArray<{
     name: "Replace Background",
     description: "Swap in a new scene.",
     data: {
-      provider: "nano-banana-pro",
       prompt:
         "Replace the background behind the subject with {scene || a sunlit Mediterranean terrace}. Keep the subject perfectly unchanged — identity, pose, edges, and proportions intact — and composite it into the new scene so it looks truly photographed there: relight the subject's rim and ambient tones to match the new environment, cast believable contact shadows, and match perspective, depth of field, and color grade.",
       negativePrompt:
@@ -126,7 +130,6 @@ const IMAGE_EDITS: ReadonlyArray<{
     name: "Colorize B&W Photo",
     description: "Natural color from grayscale.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Colorize this black-and-white photograph with natural, historically plausible color. Give skin realistic, even tones, and assign believable hues to clothing, foliage, sky, and materials. Preserve every original detail, grain, contrast, and the exact composition — add color only, never invent or remove content.",
       negativePrompt:
@@ -138,7 +141,6 @@ const IMAGE_EDITS: ReadonlyArray<{
     name: "Restore Old Photo",
     description: "Repair scratches, denoise, sharpen.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Restore this old, damaged photograph: remove scratches, dust, creases, stains, and noise, repair torn or missing areas by reconstructing what is plainly there, and gently recover sharpness and tonal detail. Keep the result authentic and true to the original — preserve identity, era, natural film grain, and composition. Repair only; do not beautify, restyle, or invent new features.",
       negativePrompt:
@@ -150,7 +152,6 @@ const IMAGE_EDITS: ReadonlyArray<{
     name: "Relight Scene",
     description: "New lighting, same subject.",
     data: {
-      provider: "nano-banana-pro",
       prompt:
         "Relight the image with {lighting style || soft golden-hour key light from the left}. Re-derive highlights, shadows, ambient fill, and color temperature consistently across the whole frame for a believable, physically plausible result. Keep the subject, pose, expression, materials, and composition completely unchanged — only the lighting changes.",
       negativePrompt:
@@ -162,7 +163,6 @@ const IMAGE_EDITS: ReadonlyArray<{
     name: "Restyle (whole image)",
     description: "Apply an art style to everything.",
     data: {
-      provider: "nano-banana-pro",
       prompt:
         "Restyle the entire image in a {art style || soft watercolor illustration} look, applying the style consistently to the subject, background, and every element. Keep the composition, subject placement, and the subject clearly recognizable — reinterpret texture, color, and rendering, not the underlying content or layout.",
       negativePrompt:
@@ -174,7 +174,6 @@ const IMAGE_EDITS: ReadonlyArray<{
     name: "Doodle Overlay",
     description: "Hand-drawn marker doodles on top — photo stays untouched.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Layer playful hand-drawn doodles ON TOP of the reference photo while keeping every pixel of the underlying photograph completely unchanged — same people, same colors, same lighting, same crop. Doodle style: wobbly hand-drawn felt-tip marker lines in white with a few yellow accents, like quick sketches on a printed photo. Add: loose outline traces hugging one or two key shapes, small sparkles and stars, a hand-drawn thought cloud or speech bubble with a short witty handwritten phrase that reacts to what is actually happening in the photo, and simple arrows or underlines pointing at fun details. Outlines only — never fill shapes with color. Never cover faces or the main focal point; place doodles in empty areas like sky, walls or margins. Keep it balanced: four to seven doodle elements total, charming and confident, not cluttered. The photo is the hero — the doodles are the seasoning.",
       negativePrompt:
@@ -186,13 +185,53 @@ const IMAGE_EDITS: ReadonlyArray<{
     name: "Doodle Overlay · Expressive",
     description: "Looser free-form doodles — the model improvises.",
     data: {
-      provider: "nano-banana-pro",
       promptPrefix:
         "Decorate the reference photo with expressive hand-drawn doodles layered on top, keeping the underlying photograph itself completely unchanged. Free, confident hand-drawn marker linework — wobbly outlines, sparkles, squiggles, little flames or hearts where they fit the mood, and a short handwritten phrase that responds cleverly to the content of the photo (never a generic cliché). Mix of white and one or two bright accent colors. Outline style only, no filled shapes. Compose the doodles around the subject — never on top of faces or the focal point — using empty areas and edges. Loose, playful, zine-like energy: it should feel like a bored genius doodled on a printed photo. Keep the original image pixels intact beneath the doodle layer.",
       negativePrompt:
         "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>`). */
@@ -202,6 +241,6 @@ export function editsFor(nodeType: string): FactoryPreset[] {
     name: p.name,
     description: p.description,
     group: "Edits",
-    data: p.data,
+    data: { provider: editProviderFor(nodeType), ...p.data },
   }))
 }

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/image-reference-doctrine.ts

@@ -13,8 +13,12 @@
  * Source of truth for the semantics documented here (verified 2026-08-25):
  * - `IMAGE_TOKEN_PATTERN` = `/\{image:(\d+)(?::([^}\n]+))?\}/gi`
  * - `expandImageRefTokens`: `{image:N:label}` → `Image N (label)`,
- *   `{image:N}` → `Image N`; out-of-range tokens are left untouched so the
- *   author can see and fix them.
+ *   `{image:N}` → `Image N`.
+ * - A token with no reference at N follows the video resolver's rule
+ *   (`dropUnwiredImageTokens` in `prompt-builder.ts`): `{image:N:label}` →
+ *   `label`, a bare `{image:N}` is dropped. Two places keep a token as typed,
+ *   on purpose: a wired token in a hybrid `Avoid:` line, and the native
+ *   negative prompt of models with their own negative field (e.g. ideogram-v3).
  * - N is the reference's 1-based position in the assembled reference list
  *   (connection order on the `references` handle).
  */
@@ -32,7 +36,7 @@ export const IMAGE_REFERENCE_PROMPT_DOCTRINE: ImageReferenceDoctrine = {
 
 - \`{image:N:label}\` → expands server-side to \`Image N (label)\`, aligned with the numbered reference list sent to the provider.
 - \`{image:N}\` → \`Image N\` (no role named).
-- A token whose N has no wired reference is left as literal text in the final prompt — visible on purpose, so fix the numbering instead of ignoring it.
+- A token whose N has no wired reference falls back to its label (\`{image:3:dog}\` → \`dog\`); a bare \`{image:N}\` is dropped. The prompt still runs but binds nothing at N, so check the numbering against what is wired.
 
 **How to compose**
 - The prompt should be little more than tokens plus glue words: \`{image:1:person} with {image:2:face}\`. The label tells the model what to TAKE from that image — \`person\`, \`face\`, \`background\`, \`settings\`, or a concrete garment/prop name (\`jacket\`).

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-builder.ts

@@ -25,6 +25,7 @@ import { findEntityMentionTokens, entityMentionSlugForRef, knownEntitySlugsFromR
 import type { CharacterDef, ConnectedReference, DescribedReference, IdentityFidelity, IdentityMeta, ReferenceSource, SceneData } from "@nodaro/shared"
 import { appendReferenceLines, referenceDescriptionLine, renderDescribedReferenceLines } from "./described-references.js"
 import { locationReferencePhotoKindLabel, type LocationReferencePhotoKind } from "@nodaro/shared"
+import { tidyReferenceTokenGaps, unboundReferenceTokenText } from "./unbound-reference-tokens.js"
 
 export interface ResolveCharacterMentionsResult {
   /** Prompt with @-tokens replaced by display names + "Use these characters:" directive prepended. */
@@ -3068,7 +3069,16 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
 
     const refsToSend = supportsRefs && finalUrls.length > 0 ? finalUrls : undefined
 
-    return { prompt: finalPrompt, nativeNegativePrompt, referenceImageUrls: refsToSend }
+    // LAST, after the reorder (as the video core runs `resolveReferenceTokens`
+    // last): an `{image:N}` with no image at N becomes its label, or nothing.
+    // The binding test is the one both expanders above use, so a token that
+    // binds is never touched here and every wired output is unchanged.
+    const assembledPrompt = dropUnwiredImageTokens(
+      finalPrompt,
+      (n) => Boolean(tokenFinalSlot(n, nonCharacterRefs, finalIndexByUrl)),
+    )
+
+    return { prompt: assembledPrompt, nativeNegativePrompt, referenceImageUrls: refsToSend }
   }
 
   // -------------------------------------------------------------------------
@@ -3160,6 +3170,9 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
 
   // Expand {image:N} position references in prompt (legacy: → "[reference image N]")
   prompt = expandImagePositionRefs(prompt, allRefs.length)
+  // Then the unwired rule for a token past the last image — same pass, same
+  // binding test, as the connected-reference return above.
+  prompt = dropUnwiredImageTokens(prompt, (n) => hasImageAt(n, allRefs.length))
 
   return { prompt, nativeNegativePrompt, referenceImageUrls: refsToSend }
 }
@@ -3221,6 +3234,61 @@ const STRICT_DEFAULT_SOURCES: ReadonlySet<ReferenceSource> = new Set([
 // newline or `}` so the match can't run away across lines / token boundaries.
 const IMAGE_TOKEN_PATTERN = /\{image:(\d+)(?::([^}\n]+))?\}/gi
 
+/**
+ * The final 1-based slot an `{image:N}` token binds to on the connected-reference
+ * path — the slot of `refs[N - 1]`'s URL — or `undefined` when no image sits at
+ * N (no such reference, or one without a URL). The ONE binding test shared by
+ * both token expanders and the unwired-token pass, so "this token is wired"
+ * means the same thing to all three.
+ */
+function tokenFinalSlot(
+  n: number,
+  refs: readonly ConnectedReference[],
+  finalIndexByUrl: ReadonlyMap<string, number>,
+): number | undefined {
+  const ref = refs[n - 1]
+  return ref?.url ? finalIndexByUrl.get(ref.url) : undefined
+}
+
+/** Whether position N has an image among `count` flat references (the
+ *  no-`connectedReferences` path). Shared by its expander and the unwired pass. */
+function hasImageAt(n: number, count: number): boolean {
+  return n >= 1 && n <= count
+}
+
+/**
+ * The last step of image prompt assembly. Every `{image:N}` token still in the
+ * prompt whose N has no image follows the unwired rule SHARED with the video
+ * resolver (`resolveReferenceTokens`): a labelled token becomes its label, an
+ * unlabelled one is dropped, and the horizontal gap left behind is collapsed
+ * and the prompt trimmed.
+ *
+ * WIRED OUTPUT IS UNCHANGED BY CONSTRUCTION, on two counts:
+ *   - a token whose N binds (`isWired`) is returned verbatim — the expanders
+ *     already rendered every such token they own;
+ *   - the tidy runs only when at least one token was dropped, so a prompt whose
+ *     tokens all bind keeps every doubled space and indent its author typed.
+ *     (The video resolver tidies unconditionally; the image path never did, and
+ *     a wired image prompt stays byte-identical.)
+ *
+ * TWO PLACES KEEP A TOKEN AS TYPED, on purpose:
+ *   - a WIRED token the hybrid format never expands — its expansion covers the
+ *     scene only, so one typed into the negative prompt keeps its text in the
+ *     `Avoid:` line (rewriting it would move a wired output);
+ *   - the native negative prompt (`nativeNegativePrompt`, the models in
+ *     `NATIVE_NEGATIVE_PROMPT_MODELS` such as ideogram-v3) is never read by this
+ *     pass — it goes to the provider's own negative field as typed, wired or not.
+ */
+function dropUnwiredImageTokens(prompt: string, isWired: (n: number) => boolean): string {
+  let dropped = false
+  const out = prompt.replace(IMAGE_TOKEN_PATTERN, (match: string, num: string, label?: string) => {
+    if (isWired(parseInt(num, 10))) return match
+    dropped = true
+    return unboundReferenceTokenText(label)
+  })
+  return dropped ? tidyReferenceTokenGaps(out) : prompt
+}
+
 interface ResolvedIdentity {
   imageIndex: number
   label: string                  // empty string = bare positional ref (no role)
@@ -3506,7 +3574,9 @@ function buildNonCharacterDirectives(
  * consistent identifier in both the bulleted list and the scene description.
  * Numeric indices match the user-typed slug format (`@kira:1:smile`).
  *
- * Out-of-range indices are left untouched so they're visible in the output.
+ * Out-of-range indices are left untouched by this helper. `buildImagePrompt`
+ * then renders any such token by the unwired rule (`dropUnwiredImageTokens`):
+ * its label, or nothing — never the raw token.
  */
 export function expandImageRefTokens(prompt: string, imageCount: number): string {
   return prompt.replace(IMAGE_TOKEN_PATTERN, (match, num, label) => {
@@ -3525,8 +3595,9 @@ export function expandImageRefTokens(prompt: string, imageCount: number): string
  *
  * When the final slot equals the token index (no Phase-0 prefix shifting the
  * positions), the output is byte-identical to `expandImageRefTokens`.
- * Out-of-range tokens (or refs without a URL) are left untouched, matching the
- * "visible so the author can fix it" contract.
+ * Out-of-range tokens (or refs without a URL) are left untouched here; the
+ * assembly's last step, `dropUnwiredImageTokens`, renders them by the unwired
+ * rule with the same `tokenFinalSlot` binding test.
  */
 function expandImageRefTokensForRefs(
   prompt: string,
@@ -3534,9 +3605,7 @@ function expandImageRefTokensForRefs(
   finalIndexByUrl: ReadonlyMap<string, number>,
 ): string {
   return prompt.replace(IMAGE_TOKEN_PATTERN, (match, num, label) => {
-    const n = parseInt(num, 10)
-    const ref = refs[n - 1]
-    const finalIdx = ref?.url ? finalIndexByUrl.get(ref.url) : undefined
+    const finalIdx = tokenFinalSlot(parseInt(num, 10), refs, finalIndexByUrl)
     if (!finalIdx) return match
     return label ? `Image ${finalIdx} (${label})` : `Image ${finalIdx}`
   })
@@ -3571,8 +3640,8 @@ function hybridRolePhrase(label: string, letter: string): string {
 /**
  * Like `expandImageRefTokensForRefs`, but emits the hybrid lettered phrase
  * ("the subject from reference image A") instead of the legacy "Image N
- * (label)". Out-of-range tokens / URL-less refs are left untouched — visible so
- * the author can fix them.
+ * (label)". Out-of-range tokens / URL-less refs are left untouched here and
+ * rendered by the unwired rule at the end of assembly (`dropUnwiredImageTokens`).
  *
  * A `{image:N:label}` pill is a mention chip like any other: `buildRefPillNodes`
  * appends its own trailing space to EVERY pill it builds, the positional
@@ -3591,9 +3660,7 @@ function expandImageRefTokensHybrid(
 ): string {
   const splices: Array<{ offset: number; length: number; phrase: string }> = []
   for (const m of prompt.matchAll(IMAGE_TOKEN_PATTERN)) {
-    const n = parseInt(m[1], 10)
-    const ref = refs[n - 1]
-    const finalIdx = ref?.url ? finalIndexByUrl.get(ref.url) : undefined
+    const finalIdx = tokenFinalSlot(parseInt(m[1], 10), refs, finalIndexByUrl)
     if (!finalIdx) continue
     splices.push({
       offset: m.index ?? 0,
@@ -3669,7 +3736,7 @@ export function expandImagePositionRefs(
 ): string {
   return prompt.replace(IMAGE_TOKEN_PATTERN, (match, num, label) => {
     const n = parseInt(num, 10)
-    if (n < 1 || n > imageCount) return match
+    if (!hasImageAt(n, imageCount)) return match
     if (label) return `Image ${n} (${label})`
     if (names && names[n - 1]) return names[n - 1]
     return `Image ${n}`

package/src/prompt-wizard-categories.ts

@@ -178,6 +178,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedream": "Artistic, painterly styles, creative interpretation",
     "seedream-5-lite": "Lighter Seedream, faster artistic generation",
     "seedream-5-pro": "Flagship Seedream — strongest instruction following, 2K via high quality",
+    "seedream-5-flash": "Fast, low-cost Seedream 5 — quick drafts and iteration at 1K or 2K",
     "z-image": "Experimental, novel generation approaches",
     "wan-2.7":     "Wan 2.7 T2I — 1K/2K/4K, up to 9 ref images",
     "wan-2.7-pro": "Wan 2.7 Pro T2I — higher quality, 1K/2K/4K",
@@ -202,6 +203,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedream-edit": "Artistic style editing",
     "seedream-5-lite-i2i": "Light artistic transformation",
     "seedream-5-pro-i2i": "Pro-grade instruction-based edits, multi-reference",
+    "seedream-5-flash-i2i": "Fast, low-cost Seedream edits — up to 10 input images",
     "flux-kontext": "Character-consistent edits with reference awareness",
     "flux-kontext-max": "Premium character-consistent editing",
     "kontext-multi": "Multi-image Kontext via Replicate — up to 4 refs, no safety filter",
@@ -226,6 +228,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedream-edit": "Artistic style editing",
     "seedream-5-lite-i2i": "Light artistic transformation",
     "seedream-5-pro-i2i": "Pro-grade instruction-based edits, multi-reference",
+    "seedream-5-flash-i2i": "Fast, low-cost Seedream edits — up to 10 input images",
     "flux-kontext": "Character-consistent edits with reference awareness",
     "flux-kontext-max": "Premium character-consistent editing",
     "kontext-multi": "Multi-image Kontext via Replicate — up to 4 refs, no safety filter",
@@ -249,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",
@@ -280,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).",

package/src/realism-wording.ts

@@ -0,0 +1,39 @@
+// packages/prompts/src/realism-wording.ts
+/**
+ * Realism and viewpoint wording for everyday-photo prompts: skin and finish
+ * sentences, the identity-keeping realism instruction for an edit, and the eye-level
+ * viewpoint and empty-hands sentences, worded for any person.
+ */
+
+/** Who a sentence is about: gendered ("she" / "her") or neutral ("the person" / "their"). */
+export interface PersonWords {
+  readonly subject: string
+  readonly possessive: string
+}
+
+export const NEUTRAL_PERSON: PersonWords = { subject: "the person", possessive: "their" }
+
+const cap = (s: string): string => (s.length === 0 ? s : `${s[0]!.toUpperCase()}${s.slice(1)}`)
+
+export const REALISM_SKIN =
+  "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."
+
+export const REALISM_FINISH =
+  "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."
+
+export const REALISM_PASS_INSTRUCTION =
+  "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."
+
+/** The frame by its viewpoint only — never by a device. */
+export function realismViewpoint(p: PersonWords): string {
+  return `${cap(p.subject)} is looking straight at the viewer from eye level, mid-sentence: ${p.possessive} 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.`
+}
+
+export function realismEmptyHands(p: PersonWords): string {
+  return `${cap(p.possessive)} hands are empty; ${p.subject} is holding nothing.`
+}

package/src/unbound-reference-tokens.ts

@@ -0,0 +1,32 @@
+/**
+ * The unwired half of the editor reference-token contract — what a
+ * `{image:N:label}` / `{video:N:label}` / `{audio:N:label}` token becomes when
+ * no reference of its kind sits at its position. ONE rule for every surface:
+ * the video resolver (`resolveReferenceTokens`) and the image prompt builder
+ * (`buildImagePrompt`) both render an unwired token through these two
+ * functions, so the image and video paths cannot drift apart on it.
+ *
+ * Each caller keeps its own token grammar and its own WIRED rendering (video:
+ * `the person from @image_1`; image: `Image 1 (person)` /
+ * `the person from reference image A`); only the unwired outcome is shared.
+ */
+
+/**
+ * The text an unwired token renders to: its label as written, or nothing for a
+ * label-less token. Text a resolver does not rewrite keeps its tokens as typed
+ * — on image prompts a wired token in a hybrid `Avoid:` line and the native
+ * negative prompt, both on purpose (see `dropUnwiredImageTokens`).
+ */
+export function unboundReferenceTokenText(label: string | undefined): string {
+  return label ?? ""
+}
+
+/**
+ * Tidy the gap a dropped token leaves: collapse every run of 2+ HORIZONTAL
+ * whitespace to one space, then trim. The class is `[^\S\r\n]` (NOT `\s`) so
+ * the `\n` / `\n\n` separators between assembled blocks survive — a `\s{2,}`
+ * collapse would merge paragraphs.
+ */
+export function tidyReferenceTokenGaps(prompt: string): string {
+  return prompt.replace(/[^\S\r\n]{2,}/g, " ").trim()
+}