@nodaro/prompts 1.33.0 → 1.35.0

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

@@ -4,8 +4,8 @@ import type { FactoryPreset } from "./types.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 +18,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 +29,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 +40,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 +51,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 +62,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 +71,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 +107,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 +118,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 +129,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 +140,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 +151,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 +162,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 +173,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,7 +184,6 @@ 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:
@@ -202,6 +199,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/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/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

@@ -162,6 +162,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "nano-banana": "Fast generation, style flexibility, reference image support",
     "nano-banana-pro": "Higher quality Nano Banana with better detail",
     "nano-banana-2": "Latest Nano Banana with resolution options (1K/2K/4K)",
+    "nano-banana-2-1": "Nano Banana 2.1 — sharper quality, prompt adherence, character consistency and text rendering, 1K/2K/4K",
     "nano-banana-2-lite": "Fast, low-cost 1K generation for drafts and iteration",
     "gpt-image": "Creative concepts, illustration, variable quality tiers",
     "gpt-image-2": "Latest GPT Image — sharp text, photorealism, 1K/2K/4K resolution",
@@ -177,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",
@@ -201,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",
@@ -225,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",

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

package/src/video-reference-resolver.ts

@@ -42,6 +42,7 @@ import {
 import { REF_BINDING } from "./ref-binding.js"
 import { resolveRefIdTokens } from "./ref-id-tokens.js"
 import { insertBeforeStyleSection } from "./prompt-style-section.js"
+import { tidyReferenceTokenGaps, unboundReferenceTokenText } from "./unbound-reference-tokens.js"
 
 // The binding surface string and the id-addressed token resolver live in their
 // own modules (see them for the contracts); re-exported here so every existing
@@ -76,19 +77,22 @@ const REFERENCE_TOKEN_RE = /\{(image|video|audio):(\d+)(?::([a-zA-Z0-9_ -]+))?\}
  *   - `N < 1` or `N > counts[kind]` (out of range / no such reference) → drop to
  *     the bare `label` (or empty if label-less). This is the legacy
  *     `stripVideoImageTokens` strip behavior: drop the token, keep the label text.
+ *     The rendering is `unboundReferenceTokenText` — shared with the image prompt
+ *     builder, which applies the same rule to its own unwired `{image:N}` tokens.
  *   - in range, label present → `REF_BINDING[kind](label, N)`
  *     (e.g. `the person from @image_2`).
  *   - in range, no label → the bare `@${kind}_${N}` (the ref-only default): the
  *     binding lands with no descriptive wrapper.
  *
  * Runs of 2+ HORIZONTAL whitespace (left behind by a dropped label-less token)
- * collapse to one space, the result is trimmed, and an empty result becomes
- * `undefined` — matching the `stripVideoImageTokens` contract so this can replace
- * it cleanly. The collapse class is `[^\S\r\n]` (NOT `\s`) on purpose: Task 2.4
- * applies this to the FULLY-ASSEMBLED core prompt, which carries `\n\n` block
- * separators between the "Use these characters:" directive block and the body —
- * a `\s{2,}` collapse would silently merge those paragraphs. Horizontal-only
- * collapse preserves newline structure while still tidying the dropped-token gap.
+ * collapse to one space, the result is trimmed (`tidyReferenceTokenGaps`, also
+ * shared with the image builder), and an empty result becomes `undefined` —
+ * matching the `stripVideoImageTokens` contract so this can replace it cleanly.
+ * The collapse class is `[^\S\r\n]` (NOT `\s`) on purpose: the core applies this
+ * to the FULLY-ASSEMBLED prompt, which carries `\n\n` block separators between
+ * the "Use these characters:" directive block and the body — a `\s{2,}` collapse
+ * would silently merge those paragraphs. Horizontal-only collapse preserves
+ * newline structure while still tidying the dropped-token gap.
  * The `kind` is lowercased before indexing `counts`/`REF_BINDING`, so a
  * case-variant token (`{Image:1}`) resolves to the same binding rather than
  * mis-classifying as out-of-range.
@@ -98,19 +102,15 @@ export function resolveReferenceTokens(
   counts: ReferenceCounts,
 ): string | undefined {
   if (!prompt) return prompt
-  return (
-    prompt
-      .replace(REFERENCE_TOKEN_RE, (_match, rawKind: string, nStr: string, label?: string) => {
-        const kind = rawKind.toLowerCase() as keyof ReferenceCounts
-        const n = parseInt(nStr, 10)
-        if (n < 1 || n > counts[kind]) return label ?? ""
-        if (label) return REF_BINDING[kind](label, n)
-        return `@${kind}_${n}`
-      })
-      // Horizontal whitespace only — preserve `\n` / `\n\n` block separators.
-      .replace(/[^\S\r\n]{2,}/g, " ")
-      .trim() || undefined
-  )
+  return tidyReferenceTokenGaps(
+    prompt.replace(REFERENCE_TOKEN_RE, (_match, rawKind: string, nStr: string, label?: string) => {
+      const kind = rawKind.toLowerCase() as keyof ReferenceCounts
+      const n = parseInt(nStr, 10)
+      if (n < 1 || n > counts[kind]) return unboundReferenceTokenText(label)
+      if (label) return REF_BINDING[kind](label, n)
+      return `@${kind}_${n}`
+    }),
+  ) || undefined
 }