@nodaro/prompts 1.39.0 → 1.40.0

package/src/provider-prompt-doctrine.ts

@@ -245,7 +245,7 @@ const GEMINI_OMNI_DOCTRINE: ProviderPromptDoctrine = {
     "Multimodal Google video with native audio: text-to-video, image-to-video, and video-edit through the same prompt surface. 4/6/8/10s; 720p/1080p or 4K tier.",
     "Structure like the platform default: subject → action → scene → lighting → camera → style. Quote dialogue lines to have them spoken; describe SFX/ambience plainly in the prompt.",
     "Text-to-video REQUIRES a concrete aspect ratio (the API hard-rejects a missing one); image runs infer aspect from the input.",
-    "Reference images ride along as additional imageUrls — bind them in the prompt ('the woman from the first image'). Video-edit: wire a source clip and describe the change, not the whole scene.",
+    "Reference images ride in image_urls, your references first — bind them by ordinal ('the woman from @image_1'); a wired start frame is appended after them and bound as the opening frame. Video-edit: describe the change.",
   ],
   doctrine: `Prompt structure (no public Google prompt guide exists for the Omni video endpoint —
 the API contract is the doctrine source, like MiniMax H3; structure guidance mirrors the
@@ -254,7 +254,7 @@ subject → action → scene/environment → lighting → camera movement → st
 
 **Modes (picked from the wired inputs)**
 - Nothing visual → text-to-video. A concrete aspect ratio is REQUIRED — the API hard-rejects a missing one (Nodaro sends the node's ratio; there is no adaptive).
-- Image(s) wired → image-to-video: the first image anchors the scene; extra images are references — bind each in the prompt ("the woman from the first image", "the interior from the second image").
+- Image(s) wired → image-to-video. Your reference images come FIRST, in your order (\`@image_1\`, \`@image_2\`, …) — bind each in the prompt ("the woman from @image_1", "the interior from @image_2"); a wired start frame is appended after them and the platform names it as the opening frame.
 - Source video wired → video-edit (served through the same handle): describe the CHANGE ("replace the daylight with dusk, keep the motion and framing"), not a full re-description.
 
 **Audio (native)**
@@ -284,6 +284,7 @@ descriptions of static/unchanged parts — spend the words on what MOVES.
 **Image-to-video (the primary mode)**
 - The input image is the FIRST FRAME, not a loose reference: composition, subject identity, and visual style carry over. Describe motion and camera only ("she turns toward the window as the camera slowly pushes in"); re-describing the still wastes adherence.
 - grok-imagine-video-1.5 accepts up to 7 images (identity/scene references beyond the first frame); at 1080p only ONE image is allowed.
+- grok-i2v with reference images: images are addressed \`@image(n)\` in array order. Your references come first (\`@image(1)\` is your first reference); a wired start frame is appended after them and the platform names it as the opening frame.
 
 **Audio (video-1.5)**
 - Native audio generates with the clip — background music, SFX, and lip-synced dialogue. Quote the spoken line; describe the music/SFX plainly. There is no audio toggle on the KIE contract — cue (or exclude) sound in the prompt text.
@@ -382,6 +383,46 @@ Source: KIE Wan 3.0 market contract (docs.kie.ai/market/wan/3-0-video,
 docs.kie.ai/market/wan/3-0-video-prime). Captured 2026-09-01.`,
 }
 
+// Vidu Q4 — no public Q4 prompt guide is captured, so like Wan 3.0 / MiniMax H3
+// the body is KIE contract facts plus the platform-standard structure. The
+// contract names references "reference image 2" / "reference audio 1"; the
+// editor's reference tokens emit the platform-wide `@image_N` / `@audio_N`
+// binding instead (see ref-binding.ts), which is what this doctrine teaches.
+const VIDU_Q4_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["vidu-q4"],
+  heading: "Vidu Q4 (vidu-q4)",
+  tips: [
+    "A start frame alone animates that frame (prompt optional). Any reference image or audio switches to reference mode: the prompt is REQUIRED and the start frame joins the reference images.",
+    "Reference mode: 1-15 images, up to 3 audio clips (MP3 only, 3-12s each). Name each by ordinal — \"the man from @image_2 says … in the voice of @audio_1\".",
+    "No text-only runs and no end frame: wire a start frame or at least one reference image.",
+    "3-16s (default 5); 540p / 720p (default) / 1080p / 2K / 4K; reference runs take 16:9 / 9:16 / 1:1 / 4:3 / 3:4. Prompt cap 20,000 chars.",
+    "`audio` is ON by default (synchronized sound). Cue the sound you want or state the exclusion; dialogue is not verified here, so plan key lines as a TTS + lip-sync pass.",
+  ],
+  doctrine: `Prompt structure (no public Vidu Q4 prompt guide is captured — the KIE API contract is the
+doctrine source; platform-standard structure applies):
+subject → action → scene/environment → lighting → camera movement → style → constraints.
+
+**Modes (picked by what is wired)**
+- Start frame only → image-to-video. The frame anchors the shot and its aspect ratio; describe MOTION and camera, not the still. The prompt is optional.
+- Any reference image or reference audio → reference-to-video. The prompt is REQUIRED. A wired start frame cannot be sent as a frame here, so the platform adds it to the reference images (after the caller's own, ordinals unchanged) and names it in the prompt as the opening frame.
+- There is no text-only mode and no first+last frame mode.
+
+**Reference binding**
+- Refer to inputs by ordinal in attachment order. In the editor the reference tokens emit "@image_N" / "@audio_N" — write the binding explicitly ("the woman from @image_1 turns to the man from @image_2 and says …, in the voice of @audio_1").
+- Caps: 1-15 reference images (JPG / PNG / WEBP) and 0-3 reference audio clips. Audio must be MP3, each 3-12 seconds — the platform refuses any other format or length before the run starts.
+
+**Duration, resolution, aspect**
+- 3-16 seconds (default 5). 540p / 720p (default) / 1080p / 2K / 4K.
+- Image-to-video has no aspect setting — the output inherits the start frame's shape. Reference runs take 16:9 (default) / 9:16 / 1:1 / 4:3 / 3:4.
+- Prompts up to 20,000 characters.
+
+**Audio**
+- The "audio" boolean defaults ON and generates synchronized sound with the clip (the contract says "dialogue and sound effects"). Describe the soundscape plainly or state the exclusion, or turn the toggle off for a silent clip.
+
+Source: KIE Vidu Q4 market contracts (docs.kie.ai/market/vidu-q4/image-to-video,
+docs.kie.ai/market/vidu-q4/reference-to-video). Captured 2026-10-17.`,
+}
+
 const HAPPYHORSE_DOCTRINE: ProviderPromptDoctrine = {
   providers: ["happyhorse", "happyhorse-i2v", "happyhorse-ref2v", "happyhorse-edit"],
   heading: "HappyHorse 1.1 (happyhorse, happyhorse-i2v, happyhorse-ref2v)",
@@ -398,7 +439,7 @@ subject → action → scene/environment → lighting → camera movement → st
 **Contract facts (KIE, per-mode pages)**
 - Prompts: any language, up to 5000 non-Chinese / 2500 Chinese characters — excess is TRUNCATED silently, so put the load-bearing content first.
 - Duration 3-15s (default 5), billed per second. Resolution 720p / 1080p (default). Aspect 16:9 (default) / 9:16 / 1:1 / 4:3 / 3:4.
-- Modes: text-to-video (happyhorse), image-to-video (happyhorse-i2v), reference-to-video (happyhorse-ref2v) — ref2v preserves wired identities; name each reference in the prompt so the binding is explicit.
+- Modes: text-to-video (happyhorse), image-to-video (happyhorse-i2v), reference-to-video (happyhorse-ref2v) — ref2v preserves wired identities; name each reference in the prompt so the binding is explicit, as \`[Image N]\` in array order: your references come first (\`[Image 1]\` is your first), and a wired start frame is appended after them and named as the opening frame.
 
 **Style guidance (platform-standard, honestly generic)**
 - One camera movement per shot; physical, quantified action ("slowly raises a hand") over abstract emotion words; state exclusions ("no on-screen text, no watermark") in the prompt.
@@ -440,6 +481,7 @@ export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
   GROK_IMAGINE_DOCTRINE,
   WAN_DOCTRINE,
   WAN_3_DOCTRINE,
+  VIDU_Q4_DOCTRINE,
   HAPPYHORSE_DOCTRINE,
   RUNWAY_KIE_DOCTRINE,
 ]

package/src/ref-binding.ts

@@ -28,10 +28,14 @@
  * 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 {
+export function identityRefsSentence(
+  firstOrdinal: number,
+  lastOrdinal: number,
+  ordinal: (n: number) => string = REF_BINDING.ordinal,
+): 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.`
+    ? `${ordinal(firstOrdinal)} is an identity reference for this shot's subjects — match its subject's exact appearance; it is not a frame.`
+    : `${ordinal(firstOrdinal)} through ${ordinal(lastOrdinal)} are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.`
 }
 
 export const REF_BINDING = {
@@ -44,6 +48,27 @@ export const REF_BINDING = {
     `Use @image_${n} as the ${role} (${role === "opening" ? "first" : "last"}) frame of the video.`,
 } as const
 
+/** A binding sentence's ordinal + frame directive in one provider syntax. */
+export interface ImageBinding {
+  ordinal: (n: number) => string
+  frame: (n: number, role: "opening" | "closing") => string
+}
+
+/**
+ * The image binding in a provider's OWN reference syntax
+ * (`videoProviderReferenceSyntax` in @nodaro/shared). `@image_N` IS
+ * {@link REF_BINDING} — the platform swap point, byte for byte; the other two
+ * spell the same sentence in the form the provider documents.
+ */
+export function imageBindingFor(syntax: "@image_N" | "@image(n)" | "[Image N]"): ImageBinding {
+  if (syntax === "@image_N") return { ordinal: REF_BINDING.ordinal, frame: REF_BINDING.frame }
+  const ordinal = syntax === "@image(n)" ? (n: number) => `@image(${n})` : (n: number) => `[Image ${n}]`
+  return {
+    ordinal,
+    frame: (n, role) => `Use ${ordinal(n)} as the ${role} (${role === "opening" ? "first" : "last"}) frame of the video.`,
+  }
+}
+
 /**
  * The instruction that makes Seedance EDIT a wired clip rather than use it as a
  * style reference — the Video to Video node's Seedance lane prepends it to the

package/src/resolve-prompt.ts

@@ -2,6 +2,7 @@ import { resolveNodeRefs } from "@nodaro/shared/workflow"
 import { readPromptAffixes, type PromptAffixes } from "@nodaro/shared/nodes"
 import { SOCIAL_POST_NODE_TYPES } from "@nodaro/shared/social"
 import { joinSentences } from "./hint-join.js"
+import { ownEntry } from "./own-entry.js"
 
 export interface ResolvePromptArgs {
   override?: string
@@ -165,7 +166,7 @@ export function computeNodePrompt(
         ? [data.directText as string | undefined]
         : []
   } else {
-    const fields = NODE_PROMPT_CANDIDATE_FIELDS[nodeType] ?? ["prompt"]
+    const fields = ownEntry(NODE_PROMPT_CANDIDATE_FIELDS, nodeType) ?? ["prompt"]
     typed = fields.map((f) => data[f] as string | undefined)
   }
   return resolvePrompt({ override, typed, wired, refMap, appendWired, affixes: readPromptAffixes(data) })

package/src/seedance-2-inputs.ts

@@ -1,5 +1,5 @@
 import { SEEDANCE_2_REF_LIMITS } from "@nodaro/shared/models"
-import { REF_BINDING } from "./video-reference-resolver.js"
+import { placeFramesAfterReferences } from "./frame-reference-slots.js"
 
 export type Seedance2Mode = "first-frame" | "first-last-frame" | "reference"
 
@@ -46,18 +46,7 @@ const cleanList = (xs?: readonly string[]): string[] =>
  * reference_image_urls (after the user's own images, so their @Image ordinals do
  * not shift) and named in a doctrine-compliant prompt suffix.
  */
-/** True when the prompt ALREADY binds an image as the first/opening frame —
- *  e.g. the gvp overlap transport's colon-position directive ("use @image_1
- *  as the first frame, it is the last keyframe of @video_1"). Field finding
- *  (2026-07-20): the first-frame directive only works adjacent to the extend
- *  colon; a duplicate sentence at the END of the prompt (this resolver's
- *  default position) dilutes it back into coin-flip behavior — so when the
- *  prompt carries its own binding, the suffix is suppressed (the frame image
- *  itself still rides the reference list). */
-export function promptBindsFirstFrame(prompt: string | undefined): boolean {
-  if (!prompt) return false
-  return /@image_\d+\s+as\s+the\s+(first|opening)\s*(\(first\))?\s*frame/i.test(prompt)
-}
+export { promptBindsFirstFrame } from "./frame-reference-slots.js"
 
 export function resolveSeedance2Inputs(args: Seedance2InputsArgs): Seedance2InputsResult {
   const limits = args.limits ?? SEEDANCE_2_REF_LIMITS
@@ -85,33 +74,19 @@ export function resolveSeedance2Inputs(args: Seedance2InputsArgs): Seedance2Inpu
   }
 
   // Reference mode: keep both frames (explicit intent), drop trailing user images
-  // 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, limits.images - frameCount)
-  const keptUserImages = refImages.slice(0, userImageSlots)
-  const droppedRefImages = refImages.length - keptUserImages.length
-
-  const referenceImageUrls: string[] = [...keptUserImages]
-  let firstOrdinal = 0
-  let lastOrdinal = 0
-  if (firstFrameUrl) { referenceImageUrls.push(firstFrameUrl); firstOrdinal = referenceImageUrls.length }
-  if (lastFrameUrl) { referenceImageUrls.push(lastFrameUrl); lastOrdinal = referenceImageUrls.length }
-
-  let promptSuffix = ""
-  const suppressFrameSentence = promptBindsFirstFrame(args.prompt)
-  if (suppressFrameSentence && firstOrdinal > 0 && lastOrdinal === 0) {
-    // The prompt already binds the first frame at its own (working) position.
-  } else if (firstOrdinal > 0 && lastOrdinal > 0) {
-    // Combined sentence — REF_BINDING.frame() emits a single-frame sentence, so use
-    // REF_BINDING.ordinal() for each ordinal inline to keep the combined wording AND
-    // route both ordinals through the single swap-point.
-    promptSuffix = `Use ${REF_BINDING.ordinal(firstOrdinal)} as the opening (first) frame and ${REF_BINDING.ordinal(lastOrdinal)} as the closing (last) frame of the video.`
-  } else if (firstOrdinal > 0) {
-    promptSuffix = REF_BINDING.frame(firstOrdinal, "opening")
-  } else if (lastOrdinal > 0) {
-    promptSuffix = REF_BINDING.frame(lastOrdinal, "closing")
-  }
+  // if the image cap is exceeded. Frames are appended AFTER the kept user images
+  // so existing user @Image ordinals are preserved — the platform convention
+  // (placeFramesAfterReferences), shared with every frames-in-the-list model.
+  const placed = placeFramesAfterReferences({
+    prompt: args.prompt,
+    firstFrameUrl,
+    lastFrameUrl,
+    refImageUrls: refImages,
+    imageCap: limits.images,
+  })
+  const referenceImageUrls = placed.imageUrls
+  const promptSuffix = placed.promptSuffix
+  const droppedRefImages = placed.droppedRefImages
 
   return {
     mode: "reference",

package/src/veo-i2v-inputs.ts

@@ -1,5 +1,4 @@
-import { promptBindsFirstFrame } from "./seedance-2-inputs.js"
-import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js"
+import { placeFramesAfterReferences } from "./frame-reference-slots.js"
 
 /**
  * VEO 3.x i2v input resolution — the mutually-exclusive sibling of
@@ -8,13 +7,15 @@ import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js
  * [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).
+ * to REFERENCE_2_VIDEO with the frames bound in prose (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.
+ * THE PLATFORM CONVENTION (2026-10-18, `placeFramesAfterReferences`): the
+ * caller's references take the first seats, so their image token N is their
+ * Nth reference; the start frame — and the end frame, VEO takes one — follow
+ * them, bound as the opening / closing frame. At the 3-ingredient cap the
+ * frames are kept (explicit intent) and trailing references drop, reported.
+ * (Until then the anchor took seat 1 and an end frame was surrendered.)
  *
  * BYTE-IDENTICAL with no references: plain frame mode, frames kept, no
  * generationType, no suffix — exactly what every veo i2v call has always
@@ -30,14 +31,15 @@ export interface VeoI2vInputsArgs {
 }
 
 export interface VeoI2vInputsResult {
-  /** The `imageUrls` payload: frames in plain mode, [anchor, ...refs] in
+  /** The `imageUrls` payload: frames in plain mode, [...refs, start, end?] 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. */
+  /** Always false since the frames-after-references convention: an end frame
+   *  is kept in reference mode. Kept for callers that log it. */
   droppedEndFrame: boolean
 }
 
@@ -55,14 +57,19 @@ export function resolveVeoI2vInputs(args: VeoI2vInputsArgs): VeoI2vInputsResult
       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")
+  const placed = placeFramesAfterReferences({
+    prompt: args.prompt,
+    firstFrameUrl: args.firstFrameUrl,
+    lastFrameUrl: args.endFrameUrl,
+    refImageUrls: refs,
+    imageCap: VEO_INGREDIENT_SLOTS,
+    bindIdentities: true,
+  })
   return {
-    imageUrls: [args.firstFrameUrl, ...kept],
+    imageUrls: placed.imageUrls,
     generationType: "REFERENCE_2_VIDEO",
-    promptSuffix: [frameSentence, identityRefsSentence(2, kept.length + 1)].filter(Boolean).join(" "),
-    droppedRefImages,
-    droppedEndFrame: Boolean(args.endFrameUrl),
+    promptSuffix: placed.promptSuffix,
+    droppedRefImages: placed.droppedRefImages,
+    droppedEndFrame: false,
   }
 }

package/src/video-reference-resolver.ts

@@ -54,7 +54,7 @@ import { tidyReferenceTokenGaps, unboundReferenceTokenText } from "./unbound-ref
 // 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
 // importer of this module — and the package index's `export *` — keeps working.
-export { REF_BINDING, identityRefsSentence, SEEDANCE_VIDEO_EDIT_PREFIX, buildSeedanceVideoEditPrompt } from "./ref-binding.js"
+export { REF_BINDING, identityRefsSentence, imageBindingFor, SEEDANCE_VIDEO_EDIT_PREFIX, buildSeedanceVideoEditPrompt, type ImageBinding } from "./ref-binding.js"
 export { resolveRefIdTokens, type RefIdTokenContext } from "./ref-id-tokens.js"