@nodaro/prompts 1.7.0 → 1.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "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",

package/src/__tests__/gemini-omni-inputs.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest"
+
+import { resolveGeminiOmniI2vInputs } from "../gemini-omni-inputs.js"
+
+/**
+ * Gemini Omni i2v input resolution — the flat `image_urls` sibling of the
+ * seedance-2 resolver. The stakes: an unbound image list reads as loose
+ * context to a multimodal model (field finding 2026-08-14 — identity refs
+ * rode every keyframes call and the cast still drifted), and an unbudgeted
+ * list trips KIE's 7-input hard reject.
+ */
+describe("resolveGeminiOmniI2vInputs", () => {
+  const FIRST = "https://r2/anchor.png"
+  const refs = (n: number) => Array.from({ length: n }, (_, i) => `https://r2/ref-${i + 1}.png`)
+
+  it("binds the roles: image 1 is the opening frame, the rest are identities — not frames", () => {
+    const r = resolveGeminiOmniI2vInputs({ prompt: "a walk on the beach", firstFrameUrl: FIRST, refImageUrls: refs(3) })
+    expect(r.imageUrls).toEqual([FIRST, ...refs(3)])
+    expect(r.promptSuffix).toBe(
+      "Use @image_1 as the opening (first) frame of the video. " +
+        "@image_2 through @image_4 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+    )
+    expect(r.droppedRefImages).toBe(0)
+  })
+
+  it("a single reference gets the singular sentence", () => {
+    const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(1) })
+    expect(r.promptSuffix).toContain("@image_2 is an identity reference")
+    expect(r.promptSuffix).not.toContain("through")
+  })
+
+  it("no references ⇒ byte-identical plain i2v: single image, no suffix", () => {
+    const r = resolveGeminiOmniI2vInputs({ prompt: "p", firstFrameUrl: FIRST })
+    expect(r).toEqual({ imageUrls: [FIRST], promptSuffix: "", droppedRefImages: 0 })
+  })
+
+  it("drops TRAILING references to fit the 7-input quota — the start frame is never the one that goes", () => {
+    const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(9) })
+    expect(r.imageUrls).toHaveLength(7)
+    expect(r.imageUrls[0]).toBe(FIRST)
+    expect(r.imageUrls.at(-1)).toBe("https://r2/ref-6.png")
+    expect(r.droppedRefImages).toBe(3)
+    // The binding names exactly the kept span.
+    expect(r.promptSuffix).toContain("@image_2 through @image_7")
+  })
+
+  it("a connected source video eats two slots (images + 2×videos ≤ 7)", () => {
+    const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(9), videoConnected: true })
+    expect(r.imageUrls).toHaveLength(5)
+    expect(r.droppedRefImages).toBe(5)
+  })
+
+  it("suppresses the opening-frame sentence when the prompt already binds it, keeping the identity sentence", () => {
+    const r = resolveGeminiOmniI2vInputs({
+      prompt: "use @image_1 as the first frame, it is the last keyframe of @video_1",
+      firstFrameUrl: FIRST,
+      refImageUrls: refs(2),
+    })
+    expect(r.promptSuffix).not.toContain("opening (first) frame")
+    expect(r.promptSuffix).toContain("identity references")
+  })
+
+  it("skips empty/undefined reference entries without burning slots", () => {
+    const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: [undefined, "", ...refs(2)] })
+    expect(r.imageUrls).toEqual([FIRST, ...refs(2)])
+    expect(r.droppedRefImages).toBe(0)
+  })
+})

package/src/__tests__/seedance-2-inputs.test.ts

@@ -193,3 +193,51 @@ describe("promptBindsFirstFrame suffix suppression (overlap colon-position findi
     expect(both.promptSuffix).toContain("closing (last) frame") // pair sentence kept — last frame has no in-prompt binding
   })
 })
+
+// ---------------------------------------------------------------------------
+// Per-provider limits (2026-08-15): Seedance 2.5 carries the same three input
+// kinds with much wider caps (30 / 10 / 10). The resolver takes the limits as
+// an argument — defaulting to the 2.0 caps so every existing caller is
+// byte-identical — and the adapter passes the provider's own.
+// ---------------------------------------------------------------------------
+
+describe("resolveSeedance2Inputs — per-provider limits", () => {
+  const WIDE = { images: 30, videos: 10, audio: 10 }
+  const refs = (n: number) => Array.from({ length: n }, (_, i) => `https://r2/ref-${i + 1}.png`)
+
+  it("keeps 12 reference images + both frames under the 2.5 caps (the 2.0 default would drop 5)", () => {
+    const r = resolveSeedance2Inputs({
+      firstFrameUrl: "https://r2/first.png",
+      lastFrameUrl: "https://r2/last.png",
+      refImageUrls: refs(12),
+      limits: WIDE,
+    })
+    expect(r.mode).toBe("reference")
+    expect(r.referenceImageUrls).toHaveLength(14)
+    expect(r.droppedRefImages).toBe(0)
+    // Frames still ride LAST, ordinals bound to their true positions.
+    expect(r.promptSuffix).toContain("@image_13")
+    expect(r.promptSuffix).toContain("@image_14")
+  })
+
+  it("videos and audio slice to the provided caps", () => {
+    const r = resolveSeedance2Inputs({
+      refImageUrls: refs(1),
+      refVideoUrls: Array.from({ length: 12 }, (_, i) => `https://r2/v${i}.mp4`),
+      refAudioUrls: Array.from({ length: 12 }, (_, i) => `https://r2/a${i}.mp3`),
+      limits: WIDE,
+    })
+    expect(r.referenceVideoUrls).toHaveLength(10)
+    expect(r.referenceAudioUrls).toHaveLength(10)
+  })
+
+  it("omitting limits keeps the 2.0 caps byte-identical (9-slot drop-trailing)", () => {
+    const r = resolveSeedance2Inputs({
+      firstFrameUrl: "https://r2/first.png",
+      lastFrameUrl: "https://r2/last.png",
+      refImageUrls: refs(12),
+    })
+    expect(r.referenceImageUrls).toHaveLength(9)
+    expect(r.droppedRefImages).toBe(5)
+  })
+})

package/src/__tests__/veo-i2v-inputs.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest"
+
+import { resolveVeoI2vInputs } from "../veo-i2v-inputs.js"
+
+/**
+ * VEO 3.x i2v input resolution. VEO's API makes frame conditioning and
+ * reference ingredients mutually exclusive (one imageUrls array, ≤3, whose
+ * meaning flips with generationType) — so an anchored call that must carry
+ * identity references moves to REFERENCE_2_VIDEO with the anchor in seat 1.
+ * References win the seats (the 2026-08-14 standing rule: refs are a must,
+ * frames additional): the end anchor is dropped in reference mode.
+ */
+describe("resolveVeoI2vInputs", () => {
+  const FIRST = "https://r2/anchor.png"
+  const refs = (n: number) => Array.from({ length: n }, (_, i) => `https://r2/ref-${i + 1}.png`)
+
+  it("no references ⇒ plain frame mode, byte-identical: frames kept, no generationType, no suffix", () => {
+    const r = resolveVeoI2vInputs({ prompt: "p", firstFrameUrl: FIRST, endFrameUrl: "https://r2/end.png" })
+    expect(r).toEqual({
+      imageUrls: [FIRST, "https://r2/end.png"],
+      promptSuffix: "",
+      droppedRefImages: 0,
+      droppedEndFrame: false,
+    })
+  })
+
+  it("references flip the call to REFERENCE_2_VIDEO with the anchor in seat 1, capped at 3", () => {
+    const r = resolveVeoI2vInputs({ prompt: "p", firstFrameUrl: FIRST, refImageUrls: refs(4) })
+    expect(r.generationType).toBe("REFERENCE_2_VIDEO")
+    expect(r.imageUrls).toEqual([FIRST, "https://r2/ref-1.png", "https://r2/ref-2.png"])
+    expect(r.droppedRefImages).toBe(2)
+    expect(r.promptSuffix).toBe(
+      "Use @image_1 as the opening (first) frame of the video. " +
+        "@image_2 through @image_3 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+    )
+  })
+
+  it("the end anchor is DROPPED in reference mode — references win the seats", () => {
+    const r = resolveVeoI2vInputs({ firstFrameUrl: FIRST, endFrameUrl: "https://r2/end.png", refImageUrls: refs(2) })
+    expect(r.imageUrls).toEqual([FIRST, "https://r2/ref-1.png", "https://r2/ref-2.png"])
+    expect(r.droppedEndFrame).toBe(true)
+  })
+
+  it("a single kept reference gets the singular sentence", () => {
+    const r = resolveVeoI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(1) })
+    expect(r.promptSuffix).toContain("@image_2 is an identity reference")
+  })
+
+  it("suppresses the opening-frame sentence when the prompt already binds it", () => {
+    const r = resolveVeoI2vInputs({
+      prompt: "use @image_1 as the first frame, it is the last keyframe of @video_1",
+      firstFrameUrl: FIRST,
+      refImageUrls: refs(1),
+    })
+    expect(r.promptSuffix).not.toContain("opening (first) frame")
+    expect(r.promptSuffix).toContain("identity reference")
+  })
+})

package/src/gemini-omni-inputs.ts

@@ -0,0 +1,73 @@
+import { VIDEO_REF_LIMITS_BY_PROVIDER } from "@nodaro/shared"
+
+import { promptBindsFirstFrame } from "./seedance-2-inputs.js"
+import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js"
+
+/**
+ * Gemini Omni Video i2v input resolution — the sibling of
+ * `resolveSeedance2Inputs` for a model whose multimodal channel is ONE flat
+ * `image_urls` list.
+ *
+ * WHY BINDING IS LOAD-BEARING: Gemini Omni receives the start frame and the
+ * identity references in the same array, with nothing in the payload marking
+ * which is which. A multimodal model treats unbound images as loose context —
+ * field finding (recast keyframes run, 2026-08-14): the identity references
+ * rode every call and the cast still drifted part to part, because the prompt
+ * never said the images WERE identities to keep. So the resolver names the
+ * roles in a prompt suffix, through the same `REF_BINDING` swap-point every
+ * other video binding uses: image 1 is the opening frame; the rest are
+ * identity references, explicitly not frames.
+ *
+ * BUDGETED, NEVER REJECTED, for the list this resolver assembles: KIE's quota
+ * is `images + 2×videos ≤ 7`, and `runGeminiOmni` hard-rejects overflow. That
+ * reject is right for a caller-assembled list (the user's own images should
+ * not silently thin out) and wrong for THIS merge, where the overflow is our
+ * own construction — so trailing references are dropped to fit, the start
+ * frame always kept, mirroring `resolveSeedance2Inputs`' drop-trailing
+ * convention, and the drop count is reported for the caller to log.
+ *
+ * BYTE-IDENTICAL when there is nothing to bind: no references ⇒ no suffix and
+ * a single-image list — exactly what every plain gemini-omni i2v call has
+ * always sent.
+ */
+
+export interface GeminiOmniI2vInputsArgs {
+  /** The composed prompt, used only to detect an existing first-frame binding. */
+  prompt?: string
+  /** The start frame — always kept, always first in the list. */
+  firstFrameUrl: string
+  /** Identity references, in priority order (trailing ones drop first). */
+  refImageUrls?: Array<string | undefined>
+  /** A connected source video occupies 2 of the 7 input slots (KIE quota). */
+  videoConnected?: boolean
+}
+
+export interface GeminiOmniI2vInputsResult {
+  /** `[firstFrameUrl, ...keptRefs]` — the `image_urls` payload, quota-fitted. */
+  imageUrls: string[]
+  /** The role-binding sentences; empty when no reference survived the budget. */
+  promptSuffix: string
+  /** References dropped to fit the quota — surface in a log, never silently. */
+  droppedRefImages: number
+}
+
+/** The catalog-declared cap (7) — read from the shared limits map so the
+ *  wire-contract number has one home; the literal is only the safety net. */
+const GEMINI_OMNI_INPUT_SLOTS = VIDEO_REF_LIMITS_BY_PROVIDER["gemini-omni-video"]?.images ?? 7
+
+export function resolveGeminiOmniI2vInputs(args: GeminiOmniI2vInputsArgs): GeminiOmniI2vInputsResult {
+  const refs = (args.refImageUrls ?? []).filter((u): u is string => typeof u === "string" && u.length > 0)
+  const slots = GEMINI_OMNI_INPUT_SLOTS - (args.videoConnected ? 2 : 0)
+  const refSlots = Math.max(0, slots - 1)
+  const kept = refs.slice(0, refSlots)
+  const droppedRefImages = refs.length - kept.length
+  const imageUrls = [args.firstFrameUrl, ...kept]
+  if (kept.length === 0) return { imageUrls, promptSuffix: "", droppedRefImages }
+
+  // The opening-frame sentence is suppressed when the prompt already binds it
+  // at its own (working) position — same field-finding rule as seedance-2: a
+  // duplicate directive at the end dilutes the one that works.
+  const frameSentence = promptBindsFirstFrame(args.prompt) ? "" : REF_BINDING.frame(1, "opening")
+  const promptSuffix = [frameSentence, identityRefsSentence(2, kept.length + 1)].filter(Boolean).join(" ")
+  return { imageUrls, promptSuffix, droppedRefImages }
+}

package/src/index.ts

@@ -20,6 +20,8 @@ export * from "./sound-aggregator.js"
 export * from "./assemble-suno-input.js"
 export * from "./assemble-image-input.js"
 export * from "./seedance-2-inputs.js"
+export * from "./gemini-omni-inputs.js"
+export * from "./veo-i2v-inputs.js"
 export * from "./person.js"
 export * from "./picker-catalogs.js"
 export * from "./picker-analyzer-registry.js"
@@ -66,3 +68,4 @@ export * from "./style-presets.js"
 export * from "./object-asset-presets.js"
 export * from "./factory-snippets/index.js"
 export * from "./picker-wiring.js"
+export * from "./surround-fill.js"

package/src/picker-wiring.ts

@@ -6,7 +6,7 @@
  * Pure data, no React. Extracted from the app's parameter-picker-registry so
  * THREE consumers share one definition and cannot drift:
  *   1. The app's community fallback registry (chip pickers, no rich previews).
- *   2. `@nodaroai/picker-ui`'s rich registry (attaches preview/Picker renderers).
+ *   2. `@nodaro/picker-ui`'s registry (attaches preview/Picker renderers).
  *   3. Nodaro Cine's builder panels.
  *
  * Renderers (preview components, multi-dim Picker components) deliberately do

package/src/prompt-wizard-categories.ts

@@ -166,6 +166,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "gpt-image": "Creative concepts, illustration, variable quality tiers",
     "gpt-image-2": "Latest GPT Image — sharp text, photorealism, 1K/2K/4K resolution",
     "grok": "General purpose, good text understanding",
+    "grok-2": "Grok Imagine 2 — expressive, high-contrast, stylized output",
     "imagen4": "Google's latest, strong photorealism and text rendering",
     "imagen4-fast": "Faster Imagen 4 variant",
     "imagen4-ultra": "Highest quality Imagen 4",
@@ -242,7 +243,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedance-2": "Seedance 2.0 — multimodal refs (9 images / 3 videos / 3 audio), native multi-track audio, multi-shot storytelling, 4-15s",
     "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",
+    "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",
     "wan": "Versatile, good for animations and transformations",
     "wan-turbo": "Faster Wan generation",
@@ -270,7 +271,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedance-2": "Seedance 2.0 — start/end frame + multimodal refs, native audio, 4-15s",
     "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",
+    "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",
     "hailuo-2.3-pro": "Premium Hailuo animation",
     "hailuo-2.3": "Standard Hailuo animation",

package/src/provider-prompt-doctrine.ts

@@ -62,7 +62,7 @@ precise subject → action details → scene/environment → lighting & color to
 **Generation differences (seedance-2-5 vs the 2.0 SKUs)**
 - A single 2.5 shot runs to 30s, where every 2.0 SKU stops at 15s. Plan a complete 4-6 shot beat inside ONE generation instead of splitting it into two clips and stitching — no seam to hide, and continuity holds because it never leaves the model.
 - 2.5 also takes far more reference material (30 images / 10 videos / 10 audio vs 9/3/3). Treat that as room for COVERAGE — more distinct characters, locations and props in one shot — not as licence to pile refs onto one identity. The "ONE headshot + ONE full-body, 4-5 assets total" rule above still produces the best likeness on 2.5.
-- 2.5 renders at 480p/720p only: there is no 1080p or 4K tier, so route a job that needs one to seedance-2 (which has both) or upscale afterwards.
+- 2.5 renders at 480p/720p/1080p (1080p since 2026-08-17): there is no 4K tier, so route a job that needs 4K to seedance-2 (which has it) or upscale afterwards.
 - With a start frame, 2.5 always derives the output aspect from that frame — an explicit aspect ratio is rejected outright, so compose the frame at the ratio you want.
 
 **References (when reference media is attached)**
@@ -87,8 +87,7 @@ precise subject → action details → scene/environment → lighting & color to
 - More than 4 referenced people gets unstable: group people into composite images of ≤4 first (image generation), then reference those composites.
 - Repeated extension degrades quality: prefer high-definition reference assets and avoid stacking many continuations.
 
-**Auto-path formula (community-sourced enrichment — apiyi.com Seedance 2.0 prompt guide,
-higgsfield.ai 4K breakdown; captured 2026-08-09)**
+**Auto-path formula (community-sourced enrichment; captured 2026-08-09)**
 - Six steps IN ORDER, 60-100 words total (longer measurably degrades): Subject → Action → Environment → Camera → Style → Constraints.
 - ONE primary camera instruction per shot. Compound moves chain with "then": "camera slow tracking then subtle rise" — never two competing verbs. The 8 reliable camera types: push-in, pull-out, pan, tracking, orbit/arc, aerial, handheld, locked-off.
 - SEPARATE camera movement from subject movement — the single biggest quality lever: "The dancer spins slowly. Camera holds fixed framing." — never "spinning camera around a dancing person".

package/src/resolve-prompt.ts

@@ -94,7 +94,18 @@ export function computeNodePrompt(
   let typed: ReadonlyArray<string | undefined>
   if (nodeType === "text-to-speech") {
     // data.text is a phantom field on TTS; only directText (gated) is real.
-    typed = data.textSource === "direct" ? [data.directText as string | undefined] : []
+    //
+    // The gate is a PREFERENCE, not a lock: when textSource is "connected" we
+    // still fall back to typed text if nothing is wired. Writers flip the gate
+    // (PromptFieldSpec.promptGate), but data reaches nodes from places no
+    // writer touches — workflows saved before that fix, JSON imports, MCP
+    // writes, templates — and there the text sat visible in the node while the
+    // run failed with "no text found" (founder, 2026-08-14). Coerce rather
+    // than reject, same principle as normalizeModelInput.
+    typed =
+      data.textSource === "direct" || !present(wired)
+        ? [data.directText as string | undefined]
+        : []
   } else {
     const fields = NODE_PROMPT_CANDIDATE_FIELDS[nodeType] ?? ["prompt"]
     typed = fields.map((f) => data[f] as string | undefined)

package/src/seedance-2-inputs.ts

@@ -12,6 +12,12 @@ export interface Seedance2InputsArgs {
   refImageUrls?: readonly string[]
   refVideoUrls?: readonly string[]
   refAudioUrls?: readonly string[]
+  /** Per-provider input caps (2026-08-15). The Seedance 2.x GENERATIONS share
+   *  this resolver's whole mode logic but not their caps — 2.5 takes the same
+   *  three kinds at 30/10/10 where 2.0 stops at 9/3/3. Defaults to the 2.0
+   *  caps so every existing caller is byte-identical; the adapter passes the
+   *  provider's own entry from VIDEO_REF_LIMITS_BY_PROVIDER. */
+  limits?: { images: number; videos: number; audio: number }
 }
 
 export interface Seedance2InputsResult {
@@ -54,11 +60,12 @@ export function promptBindsFirstFrame(prompt: string | undefined): boolean {
 }
 
 export function resolveSeedance2Inputs(args: Seedance2InputsArgs): Seedance2InputsResult {
+  const limits = args.limits ?? SEEDANCE_2_REF_LIMITS
   const firstFrameUrl = clean(args.firstFrameUrl)
   const lastFrameUrl = clean(args.lastFrameUrl)
   const refImages = cleanList(args.refImageUrls)
-  const refVideos = cleanList(args.refVideoUrls).slice(0, SEEDANCE_2_REF_LIMITS.videos)
-  const refAudios = cleanList(args.refAudioUrls).slice(0, SEEDANCE_2_REF_LIMITS.audio)
+  const refVideos = cleanList(args.refVideoUrls).slice(0, limits.videos)
+  const refAudios = cleanList(args.refAudioUrls).slice(0, limits.audio)
 
   const hasAnyReference = refImages.length > 0 || refVideos.length > 0 || refAudios.length > 0
 
@@ -81,7 +88,7 @@ export function resolveSeedance2Inputs(args: Seedance2InputsArgs): Seedance2Inpu
   // if the 9-image cap is exceeded. Frames are appended AFTER the kept user
   // images so existing user @Image ordinals are preserved.
   const frameCount = (firstFrameUrl ? 1 : 0) + (lastFrameUrl ? 1 : 0)
-  const userImageSlots = Math.max(0, SEEDANCE_2_REF_LIMITS.images - frameCount)
+  const userImageSlots = Math.max(0, limits.images - frameCount)
   const keptUserImages = refImages.slice(0, userImageSlots)
   const droppedRefImages = refImages.length - keptUserImages.length
 

package/src/style-presets.ts

@@ -1,7 +1,7 @@
 import type { StyleDirectives } from "@nodaro/shared"
 
 /**
- * Style Gallery presets (north-star §6 ①).
+ * Style Gallery presets.
  *
  * Each preset is a named "look" the user picks at Start. Picking one sets the
  * pipeline's `style_directives`, which the Showrunner folds into the plan's

package/src/surround-fill.ts

@@ -0,0 +1,67 @@
+/**
+ * Surround continuation — the fill prompt.
+ *
+ * Prompt engineering, so it lives here and not in `@nodaro/shared`: that
+ * package is published to npm under Apache-2.0, where every release is an
+ * irrevocable grant. This package is never published (`"private": true`).
+ * `@nodaro/shared` keeps only the wire contract — the direction enum and the
+ * carried-fraction defaults the route Zod schema and the SDK input type need.
+ */
+import type { SurroundDirection } from "@nodaro/shared"
+
+/** Which edge of the NEW frame holds the carried pixels vs the painted region. */
+const EDGE: Record<SurroundDirection, { carried: string; painted: string }> = {
+  right: { carried: "left", painted: "right" },
+  left: { carried: "right", painted: "left" },
+  up: { carried: "bottom", painted: "top" },
+  down: { carried: "top", painted: "bottom" },
+}
+
+/** What a tilt must actually render (NOT a continuation of the landscape). */
+const TILT_SUBJECT: Record<"up" | "down", { word: string; subject: string; where: string }> = {
+  up: {
+    word: "up",
+    subject: "the open sky directly overhead — sky, clouds, or (for an interior) the canopy or ceiling",
+    where: "overhead",
+  },
+  down: {
+    word: "down",
+    subject: "the ground directly below — terrain, floor, or water surface",
+    where: "below",
+  },
+}
+
+/**
+ * Build the fill prompt the model receives alongside the half-carry composite.
+ *
+ * `userPrompt` (an optional scene hint from the caller) is woven in front. PAN
+ * directions get the seamless-continuation prompt (with the anti-golden-hour
+ * negative that fights the documented warm-regrade drift). TILT directions get a
+ * subject-forcing prompt — render the sky / ground overhead / below, explicitly
+ * NOT a mirrored landscape — which is what stops the vertical echo.
+ */
+export function buildSurroundFillPrompt(direction: SurroundDirection, userPrompt?: string): string {
+  const scene = userPrompt && userPrompt.trim() ? `${userPrompt.trim()}. ` : ""
+  const { carried, painted } = EDGE[direction]
+
+  if (direction === "up" || direction === "down") {
+    const t = TILT_SUBJECT[direction]
+    return (
+      `${scene}` +
+      `This is a camera tilted straight ${t.word} from the same scene. The ${carried} strip holds real, finished pixels from the edge of the horizon view; the ${painted} region is flat gray and MUST be painted as ${t.subject}. ` +
+      `Render what is genuinely ${t.where} — do NOT repeat, mirror, or continue the landscape, and do NOT draw a horizon line or distant scenery in the painted region. ` +
+      `CRITICAL: keep the ${carried} strip unchanged and match the scene's EXACT lighting, time of day, white balance, and color grade — the same light as the ${carried} strip; no golden hour, no sunset, no warm relight, no cinematic regrade. ` +
+      `Blend smoothly into the ${carried} strip with no visible seam. No people, no text, no labels, no watermarks.`
+    )
+  }
+
+  // pan (right / left)
+  return (
+    `${scene}` +
+    `This is a partial frame: the ${carried} portion contains real, finished pixels and the ${painted} portion is flat gray that MUST be painted in. ` +
+    `Paint ONLY the ${painted} gray region as a natural, seamless continuation of the ${carried} portion — same scene, same perspective, continuing the horizon, geometry, and content across the boundary with no break. ` +
+    `Keep the ${carried} portion completely unchanged. ` +
+    `CRITICAL: do NOT change the lighting, exposure, white balance, or time of day. Match the ${carried} portion's EXACT light, color temperature, and contrast across the whole frame — if it is flat overcast daylight, keep flat overcast daylight. No golden hour, no sunset, no warm relight, no cinematic regrade. ` +
+    `The seam between the ${carried} and ${painted} portions must be invisible. No people, no text, no labels, no watermarks.`
+  )
+}

package/src/veo-i2v-inputs.ts

@@ -0,0 +1,68 @@
+import { promptBindsFirstFrame } from "./seedance-2-inputs.js"
+import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js"
+
+/**
+ * VEO 3.x i2v input resolution — the mutually-exclusive sibling of
+ * `resolveGeminiOmniI2vInputs`. VEO's API carries ONE `imageUrls` array
+ * (≤3) whose meaning flips with `generationType`: plain i2v reads it as
+ * [first(, last)] frames; REFERENCE_2_VIDEO reads every entry as a
+ * reference ingredient. Frames and identities cannot ride separate
+ * channels, so an anchored call that must carry identity references moves
+ * to REFERENCE_2_VIDEO with the anchor in seat 1, bound in prose as the
+ * opening frame (requested, not pixel-guaranteed — the accepted trade,
+ * same as seedance-2's reference mode).
+ *
+ * REFERENCES WIN THE SEATS (the 2026-08-14 standing rule: refs are a must,
+ * frames additional): the end anchor is dropped in reference mode rather
+ * than spending one of three seats on a closing guess. The caller logs it.
+ *
+ * BYTE-IDENTICAL with no references: plain frame mode, frames kept, no
+ * generationType, no suffix — exactly what every veo i2v call has always
+ * sent.
+ */
+
+export interface VeoI2vInputsArgs {
+  /** Used only to detect an existing first-frame binding (seedance rule). */
+  prompt?: string
+  firstFrameUrl: string
+  endFrameUrl?: string
+  refImageUrls?: Array<string | undefined>
+}
+
+export interface VeoI2vInputsResult {
+  /** The `imageUrls` payload: frames in plain mode, [anchor, ...refs] in
+   *  reference mode — never more than VEO's 3-ingredient cap. */
+  imageUrls: string[]
+  /** Present (REFERENCE_2_VIDEO) exactly when references ride. */
+  generationType?: "REFERENCE_2_VIDEO"
+  promptSuffix: string
+  droppedRefImages: number
+  /** True when an end anchor was surrendered to reference mode. */
+  droppedEndFrame: boolean
+}
+
+/** VEO's ingredient cap — the adapter's REFERENCE_2_VIDEO path has always
+ *  sliced to 3 (kie/video.ts), mirrored in VIDEO_REF_LIMITS_BY_PROVIDER. */
+const VEO_INGREDIENT_SLOTS = 3
+
+export function resolveVeoI2vInputs(args: VeoI2vInputsArgs): VeoI2vInputsResult {
+  const refs = (args.refImageUrls ?? []).filter((u): u is string => typeof u === "string" && u.length > 0)
+  if (refs.length === 0) {
+    return {
+      imageUrls: args.endFrameUrl ? [args.firstFrameUrl, args.endFrameUrl] : [args.firstFrameUrl],
+      promptSuffix: "",
+      droppedRefImages: 0,
+      droppedEndFrame: false,
+    }
+  }
+  const kept = refs.slice(0, VEO_INGREDIENT_SLOTS - 1)
+  const droppedRefImages = refs.length - kept.length
+  const frameSentence = promptBindsFirstFrame(args.prompt) ? "" : REF_BINDING.frame(1, "opening")
+  return {
+    imageUrls: [args.firstFrameUrl, ...kept],
+    generationType: "REFERENCE_2_VIDEO",
+    promptSuffix: [frameSentence, identityRefsSentence(2, kept.length + 1)].filter(Boolean).join(" "),
+    droppedRefImages,
+    droppedEndFrame: Boolean(args.endFrameUrl),
+  }
+}

package/src/video-reference-resolver.ts

@@ -50,6 +50,18 @@ import type { ConnectedReference } from "@nodaro/shared"
  * the body `{image:N}` tokens through `REF_BINDING[kind]` — so the five arrows
  * are the ONLY emission sites for the binding surface string.
  */
+/**
+ * The identity-reference binding sentence shared by the flat-image-list
+ * resolvers (gemini-omni, veo i2v): names the ordinal span as identities and
+ * says the two things a multimodal model needs to hear — match exactly, and
+ * these are not frames. One spelling; both resolvers ride it.
+ */
+export function identityRefsSentence(firstOrdinal: number, lastOrdinal: number): string {
+  return firstOrdinal === lastOrdinal
+    ? `${REF_BINDING.ordinal(firstOrdinal)} is an identity reference for this shot's subjects — match its subject's exact appearance; it is not a frame.`
+    : `${REF_BINDING.ordinal(firstOrdinal)} through ${REF_BINDING.ordinal(lastOrdinal)} are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.`
+}
+
 export const REF_BINDING = {
   image: (label: string, n: number) => `the ${label} from @image_${n}`,
   video: (label: string, n: number) => `the ${label} from @video_${n}`,