@nodaro/prompts 1.38.0 → 1.40.0

package/src/factory-presets/references.ts

@@ -0,0 +1,81 @@
+import { IMAGE_TOKEN_PATTERN } from "../image-token-pattern.js"
+import { getPromptFields, nodeSupportsPromptAffixes, promptAffixCoreField } from "../node-prompt-fields.js"
+import { NODE_PROMPT_CANDIDATE_FIELDS } from "../resolve-prompt.js"
+import { ownEntry } from "../own-entry.js"
+import { MODELS_WITH_REFERENCE_IMAGE_SUPPORT, imageReferenceLimit } from "@nodaro/shared/models"
+
+/**
+ * The most reference images any image model takes. A preset can never need
+ * more than some model could be sent, so a count is clamped to it — a typo
+ * like `{image:99999}` must not tell a client to ask for 99,999 photos.
+ */
+export const MAX_PRESET_REFERENCES: number = Math.max(
+  1,
+  ...[...MODELS_WITH_REFERENCE_IMAGE_SUPPORT].map((provider) => imageReferenceLimit(provider)),
+)
+
+/**
+ * The data fields of `nodeType` a reference token can sit in — every field the
+ * run reads its prompt from: the candidate fields `computeNodePrompt` joins
+ * (`NODE_PROMPT_CANDIDATE_FIELDS` — how a preset's prompt is resolved when it
+ * runs, on the canvas and through `presetId` alike), the prompt-field
+ * registry's own prompt and negative fields, the field the run wraps with
+ * pre/post text, and the pre/post text itself where the node takes it. A node
+ * whose prompt lives elsewhere (`llm-chat` → `userInput`) is read where its
+ * prompt really is; a type with no prompt (an app namespace) has none.
+ */
+function promptFieldsOf(nodeType: string): string[] {
+  const spec = getPromptFields(nodeType)
+  const candidates = ownEntry(NODE_PROMPT_CANDIDATE_FIELDS, nodeType) ?? []
+  if (!spec && candidates.length === 0) return []
+  const fields = new Set<string>(candidates)
+  if (spec) {
+    fields.add(spec.prompt)
+    if (spec.negative) fields.add(spec.negative)
+  }
+  const core = promptAffixCoreField(nodeType)
+  if (core) fields.add(core)
+  if (nodeSupportsPromptAffixes(nodeType)) {
+    fields.add("promptPrefix")
+    fields.add("promptSuffix")
+  }
+  return [...fields]
+}
+
+/** The highest `{image:N}` / `{image:N:label}` position in `text`, or 0. */
+function highestImageToken(text: string): number {
+  let highest = 0
+  for (const match of text.matchAll(IMAGE_TOKEN_PATTERN)) {
+    const n = Number.parseInt(match[1] ?? "", 10)
+    if (Number.isInteger(n) && n > highest) highest = n
+  }
+  return highest
+}
+
+/**
+ * How many connected reference images a preset works from — 0 for a preset
+ * that needs none. A client shows a preset with a non-zero count as "needs a
+ * photo" (`needsImage`) and asks for that many before running it.
+ *
+ * Two sources, and the larger wins:
+ *   - the `{image:N}` / `{image:N:label}` tokens in the preset's prompt fields
+ *     (the highest N): a template that names its references always reports them;
+ *   - `declared` — the factory preset's own `minReferences`, for presets whose
+ *     prompt refers to "the attached photo" in words, which no data field marks.
+ *     A user preset has no declaration, so its count comes from its tokens.
+ *
+ * Pure; never throws. A declaration that is not a positive whole number is
+ * ignored, and the result is at most {@link MAX_PRESET_REFERENCES}.
+ */
+export function presetMinReferences(
+  nodeType: string,
+  data: Readonly<Record<string, unknown>>,
+  declared?: number,
+): number {
+  let count = typeof declared === "number" && Number.isInteger(declared) && declared > 0 ? declared : 0
+  for (const field of promptFieldsOf(nodeType)) {
+    const value = data[field]
+    if (typeof value === "string") count = Math.max(count, highestImageToken(value))
+  }
+  return Math.min(count, MAX_PRESET_REFERENCES)
+}

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

@@ -89,6 +89,8 @@ export function stylizedSubjectFor(nodeType: string): FactoryPreset[] {
     description: p.description,
     group: "Stylized Subject",
     data: { provider: editProviderFor(nodeType), ...p.data },
+    // Restyles the person in the connected photo ("the reference image").
+    minReferences: 1,
   }))
 }
 
@@ -242,5 +244,7 @@ export function editsFor(nodeType: string): FactoryPreset[] {
     description: p.description,
     group: "Edits",
     data: { provider: editProviderFor(nodeType), ...p.data },
+    // Every edit operates on the connected photo.
+    minReferences: 1,
   }))
 }

package/src/factory-presets/types.ts

@@ -12,6 +12,14 @@ export interface FactoryPreset {
   readonly groupKind?: "folder" | "section"
   /** Capture-shaped config (no label / fieldMappings / runtime keys). */
   readonly data: Readonly<Record<string, unknown>>
+  /**
+   * How many connected reference images the preset works from, stated for a
+   * preset whose prompt refers to "the attached photo" in words (Reference
+   * Sheet, Portrait Transformations, Stylized Subject, Edits, …). Leave it out
+   * otherwise: `{image:N}` tokens in the prompt are counted on their own, and
+   * the count a client sees is the larger of the two (`presetMinReferences`).
+   */
+  readonly minReferences?: number
 }
 
 /** A render-ready bucket of factory presets sharing one `group` (or the leading

package/src/frame-reference-slots.ts

@@ -0,0 +1,92 @@
+import { identityRefsSentence, imageBindingFor } from "./ref-binding.js"
+
+/**
+ * WHERE A START / END FRAME GOES WHEN IT SHARES A MODEL'S REFERENCE LIST — the
+ * one platform convention (2026-10-18), for every video model whose frames and
+ * reference images travel in a single image array (`videoProviderAppendsFrames`
+ * in @nodaro/shared):
+ *
+ *   - the caller's own reference images come FIRST, in their order, so the
+ *     caller's image token N (`{image:N}`, `{ref:<id>}`, a typed ordinal)
+ *     always means their Nth reference;
+ *   - the frames are appended AFTER them (start, then end) and named in the
+ *     prompt as the opening / closing frame, in the provider's own syntax;
+ *   - at the image cap the frames are KEPT — they are explicit intent — and
+ *     trailing caller references are dropped and reported.
+ *
+ * `bindIdentities` adds the identity sentence the flat-image-list models carry
+ * (Gemini Omni, VEO, Grok, HappyHorse: nothing in their payload says which
+ * entries are identities, so the prompt says it). The Seedance-family resolver
+ * calls this without it — byte for byte what it always emitted.
+ */
+export interface FrameReferenceSlotsArgs {
+  /** Consulted only to skip a duplicate opening-frame sentence. */
+  prompt?: string
+  firstFrameUrl?: string
+  lastFrameUrl?: string
+  /** The caller's own reference images, in priority order. */
+  refImageUrls?: readonly (string | undefined)[]
+  /** The provider's image cap — frames and references together. */
+  imageCap: number
+  /** The provider's reference syntax (`videoProviderReferenceSyntax`). */
+  syntax?: "@image_N" | "@image(n)" | "[Image N]"
+  bindIdentities?: boolean
+}
+
+export interface FrameReferenceSlotsResult {
+  /** `[...keptRefs, start?, end?]` — never longer than `imageCap` (bar the frames themselves). */
+  imageUrls: string[]
+  promptSuffix: string
+  /** Trailing caller references dropped to keep the frames. */
+  droppedRefImages: number
+  /** 1-based seats of the frames in `imageUrls`; 0 when absent. */
+  firstFrameOrdinal: number
+  lastFrameOrdinal: number
+}
+
+export function placeFramesAfterReferences(args: FrameReferenceSlotsArgs): FrameReferenceSlotsResult {
+  const refs = (args.refImageUrls ?? []).filter((u): u is string => typeof u === "string" && u.trim().length > 0)
+  const frameCount = (args.firstFrameUrl ? 1 : 0) + (args.lastFrameUrl ? 1 : 0)
+  const kept = refs.slice(0, Math.max(0, args.imageCap - frameCount))
+  const droppedRefImages = refs.length - kept.length
+
+  const imageUrls = [...kept]
+  let firstFrameOrdinal = 0
+  let lastFrameOrdinal = 0
+  if (args.firstFrameUrl) { imageUrls.push(args.firstFrameUrl); firstFrameOrdinal = imageUrls.length }
+  if (args.lastFrameUrl) { imageUrls.push(args.lastFrameUrl); lastFrameOrdinal = imageUrls.length }
+
+  const syntax = args.syntax ?? "@image_N"
+  const binding = imageBindingFor(syntax)
+  // The duplicate-binding check reads the platform's `@image_N` form, which is
+  // the only form a caller's prompt can already carry it in.
+  const promptBindsStart = syntax === "@image_N" && promptBindsFirstFrame(args.prompt)
+  let frameSentence = ""
+  if (promptBindsStart && firstFrameOrdinal > 0 && lastFrameOrdinal === 0) {
+    // The prompt already binds the first frame at its own (working) position.
+  } else if (firstFrameOrdinal > 0 && lastFrameOrdinal > 0) {
+    frameSentence = `Use ${binding.ordinal(firstFrameOrdinal)} as the opening (first) frame and ${binding.ordinal(lastFrameOrdinal)} as the closing (last) frame of the video.`
+  } else if (firstFrameOrdinal > 0) {
+    frameSentence = binding.frame(firstFrameOrdinal, "opening")
+  } else if (lastFrameOrdinal > 0) {
+    frameSentence = binding.frame(lastFrameOrdinal, "closing")
+  }
+  const identitySentence = args.bindIdentities && kept.length > 0 && frameCount > 0
+    ? identityRefsSentence(1, kept.length, binding.ordinal)
+    : ""
+  const promptSuffix = [frameSentence, identitySentence].filter(Boolean).join(" ")
+  return { imageUrls, promptSuffix, droppedRefImages, firstFrameOrdinal, lastFrameOrdinal }
+}
+
+/** 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)
+}

package/src/gemini-omni-inputs.ts

@@ -1,30 +1,33 @@
 import { VIDEO_REF_LIMITS_BY_PROVIDER } from "@nodaro/shared/models"
 
-import { promptBindsFirstFrame } from "./seedance-2-inputs.js"
-import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js"
+import { placeFramesAfterReferences } from "./frame-reference-slots.js"
 
 /**
  * Gemini Omni Video i2v input resolution — the sibling of
  * `resolveSeedance2Inputs` for a model whose multimodal channel is ONE flat
  * `image_urls` list.
  *
+ * THE PLATFORM CONVENTION (2026-10-18, `placeFramesAfterReferences`): the
+ * caller's identity references come first, so their image token N is their Nth
+ * reference, and the start frame is appended after them. Until then the frame
+ * led the list, so a caller's `@image_1` landed on the frame.
+ *
  * 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.
+ * roles in a prompt suffix: the references are identity references, explicitly
+ * not frames, and the last image is the opening frame.
  *
  * 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.
+ * frame always kept (the convention's tie-break), 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
@@ -34,7 +37,7 @@ import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js
 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. */
+  /** The start frame — always kept, appended after the references. */
   firstFrameUrl: string
   /** Identity references, in priority order (trailing ones drop first). */
   refImageUrls?: Array<string | undefined>
@@ -48,7 +51,7 @@ export interface GeminiOmniI2vInputsArgs {
 }
 
 export interface GeminiOmniI2vInputsResult {
-  /** `[firstFrameUrl, ...keptRefs]` — the `image_urls` payload, quota-fitted. */
+  /** `[...keptRefs, firstFrameUrl]` — the `image_urls` payload, quota-fitted. */
   imageUrls: string[]
   /** The role-binding sentences; empty when no reference survived the budget. */
   promptSuffix: string
@@ -64,18 +67,16 @@ function geminiOmniInputSlots(provider: string | undefined): number {
 }
 
 export function resolveGeminiOmniI2vInputs(args: GeminiOmniI2vInputsArgs): GeminiOmniI2vInputsResult {
-  const refs = (args.refImageUrls ?? []).filter((u): u is string => typeof u === "string" && u.length > 0)
   const slots = geminiOmniInputSlots(args.provider) - (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 }
+  const placed = placeFramesAfterReferences({
+    prompt: args.prompt,
+    firstFrameUrl: args.firstFrameUrl,
+    refImageUrls: args.refImageUrls,
+    imageCap: Math.max(1, slots),
+    bindIdentities: true,
+  })
+  if (placed.imageUrls.length === 1) {
+    return { imageUrls: placed.imageUrls, promptSuffix: "", droppedRefImages: placed.droppedRefImages }
+  }
+  return { imageUrls: placed.imageUrls, promptSuffix: placed.promptSuffix, droppedRefImages: placed.droppedRefImages }
 }

package/src/image-reference-doctrine.ts

@@ -6,9 +6,9 @@
  * the video node skills.
  *
  * Unlike the per-provider video doctrines, this is a PLATFORM mechanism: the
- * token grammar and expansion are Nodaro's own (`prompt-builder.ts` —
- * `IMAGE_TOKEN_PATTERN`, `expandImageRefTokens`), so there is one doctrine,
- * not one per model family.
+ * token grammar and expansion are Nodaro's own (`image-token-pattern.ts` —
+ * `IMAGE_TOKEN_PATTERN`; `prompt-builder.ts` — `expandImageRefTokens`), so
+ * there is one doctrine, not one per model family.
  *
  * Source of truth for the semantics documented here (verified 2026-08-25):
  * - `IMAGE_TOKEN_PATTERN` = `/\{image:(\d+)(?::([^}\n]+))?\}/gi`

package/src/image-token-pattern.ts

@@ -0,0 +1,13 @@
+/**
+ * The `{image:N}` / `{image:N:label}` reference-token grammar — one pattern for
+ * the image prompt assembly (`prompt-builder.ts`) and for the preset metadata
+ * that reads which references a template names (`factory-presets/references.ts`).
+ *
+ * Group 1 = position (1-based), group 2 = optional label. The label allows
+ * spaces (multi-word labels like "clothes and shoes") but never a newline or
+ * `}`, so a match can't run away across lines or token boundaries.
+ *
+ * Global on purpose (callers use `.replace` / `.matchAll`, which never leave a
+ * `lastIndex` behind); never call `.test` / `.exec` on it.
+ */
+export const IMAGE_TOKEN_PATTERN = /\{image:(\d+)(?::([^}\n]+))?\}/gi

package/src/node-prompt-fields.ts

@@ -25,6 +25,7 @@
 
 import type { SnippetMedia } from "./factory-snippets/types.js"
 import { NODE_PROMPT_CANDIDATE_FIELDS } from "./resolve-prompt.js"
+import { ownEntry } from "./own-entry.js"
 
 /** Which lucide glyph a node's prompt affordance uses. Kept as a string so this
  *  module stays icon-library-free; mapped to a component in the strip button. */
@@ -136,9 +137,10 @@ export const NODE_PROMPT_FIELDS: Readonly<Record<string, PromptFieldSpec>> = {
   "edit-plan": { prompt: "instructions", promptLabel: "Editing instructions", media: "video", inline: false },
 }
 
-/** The prompt-field spec for a node type, or undefined if it has none. */
+/** The prompt-field spec for a node type, or undefined if it has none (an
+ *  Object.prototype member name such as `constructor` has none). */
 export function getPromptFields(nodeType: string | undefined): PromptFieldSpec | undefined {
-  return nodeType ? NODE_PROMPT_FIELDS[nodeType] : undefined
+  return nodeType ? ownEntry(NODE_PROMPT_FIELDS, nodeType) : undefined
 }
 
 /** True when this node type has a registered, quick-editable prompt field. */
@@ -206,7 +208,7 @@ export function promptFieldCarriesAffixes(nodeType: string | undefined, promptFi
   const core = promptAffixCoreField(nodeType)
   if (core === undefined) return false
   if (promptField === undefined) return getPromptFields(nodeType)!.prompt === core
-  return promptField === core || (NODE_PROMPT_CANDIDATE_FIELDS[nodeType!] ?? []).includes(promptField)
+  return promptField === core || (ownEntry(NODE_PROMPT_CANDIDATE_FIELDS, nodeType) ?? []).includes(promptField)
 }
 
 /** The affix-capable node types, derived from the registry (never hand-listed). */

package/src/own-entry.ts

@@ -0,0 +1,11 @@
+/**
+ * A registry keyed by node type is a plain object, and the key is
+ * caller-supplied (`?nodeType=` on a public route, a preset row's `node_type`,
+ * workflow JSON). A plain `record[key] ?? fallback` reads an Object.prototype
+ * member for `"constructor"`, `"toString"` or `"__proto__"` — a function or
+ * the prototype itself, which the caller then maps or iterates and throws on.
+ * This reads an OWN entry only, so such a name is "no such type".
+ */
+export function ownEntry<T>(record: Readonly<Record<string, T>>, key: string | undefined): T | undefined {
+  return key !== undefined && Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined
+}

package/src/prompt-builder.ts

@@ -5,6 +5,7 @@
  */
 
 import { joinSentences } from "./hint-join.js"
+import { IMAGE_TOKEN_PATTERN } from "./image-token-pattern.js"
 import { resolveTemplate, applyTemplate } from "./prompt-templates.js"
 import { NATIVE_NEGATIVE_PROMPT_MODELS, MODELS_WITH_REFERENCE_IMAGE_SUPPORT, imageReferenceLimit, getMaxImagePromptChars, getMaxNegativePromptChars } from "@nodaro/shared/models"
 import { getStylePromptHint, isDeniedStyleId } from "./style.js"
@@ -3276,11 +3277,9 @@ const STRICT_DEFAULT_SOURCES: ReadonlySet<ReferenceSource> = new Set([
   "wired-location",
 ])
 
-/** Matches `{image:N}` and `{image:N:label}` tokens.
- *  Group 1 = position, group 2 = optional label. */
-// Label allows spaces (multi-word labels like "clothes and shoes") but never a
-// newline or `}` so the match can't run away across lines / token boundaries.
-const IMAGE_TOKEN_PATTERN = /\{image:(\d+)(?::([^}\n]+))?\}/gi
+// `IMAGE_TOKEN_PATTERN` (`{image:N}` / `{image:N:label}`) lives in
+// image-token-pattern.ts, shared with the preset metadata that reads which
+// references a template names.
 
 /**
  * The final 1-based slot an `{image:N}` token binds to on the connected-reference

package/src/prompt-style-section.ts

@@ -51,7 +51,7 @@ import {
   renderDirectionHintClauses,
   type DirectionFamily,
   type DirectionFields,
-  type DirectionHintMode,
+  type DirectionRenderOptions,
   type DirectionStyleGroup,
 } from "./direction-registry.js"
 
@@ -159,7 +159,7 @@ export function asBodyClauses(texts: readonly string[]): SlottedPromptClause[] {
  */
 export function partitionStyleClauses(
   direction: DirectionFields | undefined,
-  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+  opts: DirectionRenderOptions,
 ): SlottedPromptClause[] {
   return renderDirectionHintClauses(direction, opts).map((clause) => ({
     text: clause.text,
@@ -185,7 +185,7 @@ export function styleSectionFromClauses(clauses: readonly SlottedPromptClause[])
  */
 export function renderStyleSection(
   direction: DirectionFields | undefined,
-  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+  opts: DirectionRenderOptions,
 ): string {
   return styleSectionFromClauses(partitionStyleClauses(direction, opts))
 }

package/src/prompt-wizard-categories.ts

@@ -267,6 +267,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "gemini-omni-flash": "Google Gemini Omni Flash — faster, cheaper Omni tier; multimodal video with native audio, 4–10s, up to 4K.",
     "wan-3": "Wan 3.0 — multimodal refs (10 images / 5 videos / 5 audio) or first+last frame, native audio, 2–30s, 480p/720p/1080p",
     "wan-3-prime": "Wan 3.0 Prime — high-speed Wan 3.0 tier; same surface, faster turnaround at a higher rate",
+    "vidu-q4": "Vidu Q4 — start frame or up to 15 reference images + 3 MP3 audio refs, native audio, 3–16s, 540p–4K (image required)",
     "grok-imagine-video-1.5": "Grok Imagine 1.5 — image-to-video only; requires an input image",
   },
   "image-to-video": {
@@ -303,6 +304,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "gemini-omni-flash": "Google Gemini Omni Flash — faster, cheaper Omni tier; multimodal video with native audio, 4–10s, up to 4K.",
     "wan-3": "Wan 3.0 — multimodal refs (10 images / 5 videos / 5 audio) or first+last frame, native audio, 2–30s, 480p/720p/1080p",
     "wan-3-prime": "Wan 3.0 Prime — high-speed Wan 3.0 tier; same surface, faster turnaround at a higher rate",
+    "vidu-q4": "Vidu Q4 — animate a start frame, or direct up to 15 reference images + 3 MP3 audio refs; native audio, 3–16s, 540p–4K",
     "grok-imagine-video-1.5": "Grok Imagine 1.5 — stylized animation, 1–15s, 480p/720p (image required)",
   },
   "video-to-video": {

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