@nodaro/prompts 1.51.0 → 1.53.0

package/dist/index.js

@@ -2,13 +2,13 @@ export { BODY_CAPTIONS_PRESET_ID, BRAND_PRESETS, BRAND_PRESET_IDS, BRAND_PRESET_
 export { readDirectionFields, readStructuredFields, readSubjectFields } from './chunk-ZRORO6OM.js';
 export { TEXT_REQUIRED_NODE_TYPES, WIRED_OUTPUT_NODE_TYPES, computeAiWriterInput, computeNodeSendText, stripAudioTags } from './chunk-YS6HOWMW.js';
 export { NODE_PROMPT_CANDIDATE_FIELDS, NODE_PROMPT_FIELDS, PROMPT_AFFIX_CORE_FIELD_OVERRIDES, PROMPT_AFFIX_NODE_TYPES, applyPromptAffixes, composeNegative, computeLlmChatFields, computeNodePrompt, computeScriptTopic, getPromptFields, getSnippetMedia, joinPromptParts, nodeHasInlinePrompt, nodeHasPromptField, nodeSupportsPromptAffixes, promptAffixCoreField, promptFieldCarriesAffixes, promptPartSeparator, resolvePrompt } from './chunk-N6VMPG5S.js';
-export { REF_BINDING, SEEDANCE_VIDEO_EDIT_PREFIX, appendField, appendMusicMeta, assembleImageInput, assembleSunoInput, buildSeedanceVideoEditPrompt, buildSurroundFillPrompt, composeSoundHintFromConnections, composeVideoPromptText, getEffectiveSunoCustomMode, identityRefsSentence, imageBindingFor, placeFramesAfterReferences, planFrameDelivery, promptBindsFirstFrame, resolveGeminiOmniI2vInputs, resolveRefIdTokens, resolveReferenceTokens, resolveSeedance2Inputs, resolveVeoI2vInputs, resolveVideoReferenceCore, truncateForField } from './chunk-HETYHGGW.js';
+export { REF_BINDING, SEEDANCE_VIDEO_EDIT_PREFIX, appendField, appendMusicMeta, assembleImageInput, assembleSunoInput, buildSeedanceVideoEditPrompt, buildSurroundFillPrompt, composeSoundHintFromConnections, composeVideoPromptText, getEffectiveSunoCustomMode, identityRefsSentence, imageBindingFor, placeFramesAfterReferences, planFrameDelivery, promptBindsFirstFrame, resolveGeminiOmniI2vInputs, resolveRefIdTokens, resolveReferenceTokens, resolveSeedance2Inputs, resolveVeoI2vInputs, resolveVideoReferenceCore, truncateForField } from './chunk-XR7RAHZI.js';
 export { ANGLE_LABELS, ASPECT_RATIO_LABELS, MAX_SUBJECT_KEYS, MOVEMENT_LABELS, SCENE_PROMPT_MAX_LENGTH, SHOT_LABELS, STYLE_SECTION_GAP, STYLE_SECTION_HEADER, SUBJECT_ARRAY_CEILING, SUBJECT_CUSTOM_AGE_KEY, SUBJECT_FIELDS, SUBJECT_FOLD_KEYS, SUBJECT_ID_MAX_CHARS, SUBJECT_IMAGE_HINT_MODE_DEFAULT, SUBJECT_KEYS, SUBJECT_KEY_MAX_CHARS, SUBJECT_VIDEO_HINT_MODE_DEFAULT, appendReferenceLines, applyReferenceOrderToVideo, asBodyClauses, buildIdentityDirectives, buildImagePrompt, buildImagePromptSegments, buildImagePromptWithOverflow, buildReferenceBlocks, buildScenePrompt, composeSectionedPrompt, endsInsideStyleSection, expandImagePositionRefs, expandImageRefTokens, getRegisteredSubjectKeys, insertBeforeStyleSection, normalizeSubjectFields, partitionStyleClauses, referenceDescriptionLine, renderDescribedReferenceLines, renderReferenceCaptionLines, renderStructuredFields, renderStyleSection, renderSubjectHints, resolveCharacterMentions, resolveLocationMentions, sectionedClauseCosts, splitStyleSection, styleSectionFromClauses, styleSlotFor, subjectFieldsForSurface, truncateText } from './chunk-YAIPYPMM.js';
 import './chunk-GILUVQQJ.js';
 export { keepableDirectionHints } from './chunk-JZOPMVGY.js';
 export { PROMPT_HINT_SEPARATOR, joinPromptHints } from './chunk-35UHMDGS.js';
 export { computePackSidecarCoverage } from './chunk-FDOG7BNB.js';
-export { AD_CREATIVE_ANALYSIS_FIELDS, AD_CREATIVE_ANALYSIS_SYSTEM_PROMPT, AUDIO_WIZARD_CATEGORIES, DEFAULT_OWN_MOTION, IMAGE_REFERENCE_PROMPT_DOCTRINE, IMAGE_WIZARD_CATEGORIES, LLM_CHAT_WIZARD_CATEGORIES, MUSIC_WIZARD_CATEGORIES, OWN_MOTION_NODE_TYPES, POST_CONTENT_ANALYSIS_SYSTEM_PROMPT, PROVIDER_CAPABILITIES, PROVIDER_PROMPT_DOCTRINES, REFERENCE_IMAGE_ROLES, SCENE3D_FIGURE_REFERENCE_RULE, SCENE3D_FREE_PLATE_SLOTS, SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE, SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE, SCENE3D_LAYOUT_SCOPING_FOR, SCENE3D_LAYOUT_SCOPING_IGNORE, SCENE3D_LAYOUT_SCOPING_LOOK_SOURCE, SCENE3D_LAYOUT_SCOPING_MARKER, SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE, TEXT_WIZARD_CATEGORIES, VIDEO_WIZARD_CATEGORIES, appendScene3DStillScopingLines, buildAdCreativeAnalysisUserText, buildCharacterPrompt, buildCreaturePrompt, buildFaceTemplateInputs, buildLocationMotionPrompt, buildLocationPrompt, buildLocationRefinePrompt, buildMotionPrompt, buildObjectMotionPrompt, buildObjectPrompt, buildScene3DLayoutScopingLine, buildScene3DUnreferencedFiguresWarning, getCategoriesForNodeType, getPromptDoctrine, getPromptTips, hasScene3DLayoutScopingLine, isWizardSupported, ownMotionHint, renderScene3DLayoutScopingLine, scene3DLayoutVideoCaptions } from './chunk-T4TZY5ST.js';
+export { AD_CREATIVE_ANALYSIS_FIELDS, AD_CREATIVE_ANALYSIS_SYSTEM_PROMPT, AUDIO_WIZARD_CATEGORIES, DEFAULT_OWN_MOTION, IMAGE_REFERENCE_PROMPT_DOCTRINE, IMAGE_WIZARD_CATEGORIES, LLM_CHAT_WIZARD_CATEGORIES, MUSIC_WIZARD_CATEGORIES, OWN_MOTION_NODE_TYPES, POST_CONTENT_ANALYSIS_SYSTEM_PROMPT, PROVIDER_CAPABILITIES, PROVIDER_PROMPT_DOCTRINES, REFERENCE_IMAGE_ROLES, SCENE3D_FIGURE_REFERENCE_RULE, SCENE3D_FREE_PLATE_SLOTS, SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE, SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE, SCENE3D_LAYOUT_SCOPING_FOR, SCENE3D_LAYOUT_SCOPING_IGNORE, SCENE3D_LAYOUT_SCOPING_LOOK_SOURCE, SCENE3D_LAYOUT_SCOPING_MARKER, SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE, TEXT_WIZARD_CATEGORIES, VIDEO_WIZARD_CATEGORIES, appendScene3DStillScopingLines, buildAdCreativeAnalysisUserText, buildCharacterPrompt, buildCreaturePrompt, buildFaceTemplateInputs, buildLocationMotionPrompt, buildLocationPrompt, buildLocationRefinePrompt, buildMotionPrompt, buildObjectMotionPrompt, buildObjectPrompt, buildScene3DLayoutScopingLine, buildScene3DUnreferencedFiguresWarning, getCategoriesForNodeType, getPromptDoctrine, getPromptTips, hasScene3DLayoutScopingLine, isWizardSupported, ownMotionHint, renderScene3DLayoutScopingLine, scene3DLayoutVideoCaptions } from './chunk-PHCYQWJP.js';
 export { CINEMATIC_LOOK_TAIL, FILM_STILL_PREFIX, NEUTRAL_PERSON, REALISM_FINISH, REALISM_PASS_INSTRUCTION, REALISM_SKIN, REFERENCE_RULES, REFERENCE_RULES_MULTI_PERSON, SCENE_FRAME_RULE, filmStillPrefix, realismEmptyHands, realismViewpoint, referenceRulesBlock } from './chunk-T64D26P4.js';
 export { DEFAULT_IDENTITY_LOCK, DEFAULT_TEMPLATES, applyTemplate, buildIdentityLockLine, characterLockToRefLock, collectIdentityLockClause, getIdentityLockClause, hasUpstreamCharacter, resolveTemplate, toIdentityLockMode, withForcedIdentityLock } from './chunk-BQWIPLLR.js';
 import './chunk-ADMHDFHB.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "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",
@@ -70,7 +70,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^3.56.0"
+    "@nodaro/shared": "^3.58.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/frame-reference-slots.test.ts

@@ -30,6 +30,22 @@ describe("placeFramesAfterReferences", () => {
     )
   })
 
+  it("writes plain `image N` sentences that say what each image is", () => {
+    const start = placeFramesAfterReferences({ firstFrameUrl: "F", refImageUrls: R(2), imageCap: 6, syntax: "image N", bindIdentities: true })
+    expect(start.promptSuffix).toBe(
+      "image 3 is the opening (first) frame of the video. image 1 and image 2 are references for the subject; they are not frames.",
+    )
+    const both = placeFramesAfterReferences({ firstFrameUrl: "F", lastFrameUrl: "L", refImageUrls: R(3), imageCap: 6, syntax: "image N", bindIdentities: true })
+    expect(both.promptSuffix).toBe(
+      "image 4 is the opening (first) frame and image 5 is the closing (last) frame of the video. image 1, image 2 and image 3 are references for the subject; they are not frames.",
+    )
+    const one = placeFramesAfterReferences({ lastFrameUrl: "L", refImageUrls: R(1), imageCap: 6, syntax: "image N", bindIdentities: true })
+    expect(one.promptSuffix).toBe("image 2 is the closing (last) frame of the video. image 1 is a reference for the subject; it is not a frame.")
+    // Never the platform's `@image_N` duplicate check: a prompt carrying it is not this syntax's binding.
+    const prompted = placeFramesAfterReferences({ prompt: "use @image_2 as the first frame", firstFrameUrl: "F", refImageUrls: R(1), imageCap: 6, syntax: "image N" })
+    expect(prompted.promptSuffix).toBe("image 2 is the opening (first) frame of the video.")
+  })
+
   it("skips the opening sentence when the prompt already binds it (@image_N form)", () => {
     const r = placeFramesAfterReferences({ prompt: "use @image_2 as the first frame", firstFrameUrl: "F", refImageUrls: R(1), imageCap: 9 })
     expect(r.promptSuffix).toBe("")

package/src/frame-reference-slots.ts

@@ -1,4 +1,4 @@
-import { identityRefsSentence, imageBindingFor } from "./ref-binding.js"
+import { imageBindingFor, type ImageReferenceSyntax } from "./ref-binding.js"
 
 /**
  * WHERE A START / END FRAME GOES WHEN IT SHARES A MODEL'S REFERENCE LIST — the
@@ -29,7 +29,7 @@ export interface FrameReferenceSlotsArgs {
   /** The provider's image cap — frames and references together. */
   imageCap: number
   /** The provider's reference syntax (`videoProviderReferenceSyntax`). */
-  syntax?: "@image_N" | "@image(n)" | "[Image N]"
+  syntax?: ImageReferenceSyntax
   bindIdentities?: boolean
 }
 
@@ -65,14 +65,14 @@ export function placeFramesAfterReferences(args: FrameReferenceSlotsArgs): Frame
   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.`
+    frameSentence = binding.frames(firstFrameOrdinal, lastFrameOrdinal)
   } 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)
+    ? binding.identities(1, kept.length)
     : ""
   const promptSuffix = [frameSentence, identitySentence].filter(Boolean).join(" ")
   return { imageUrls, promptSuffix, droppedRefImages, firstFrameOrdinal, lastFrameOrdinal }

package/src/prompt-wizard-categories.ts

@@ -273,6 +273,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "ltx-2.3-fast": "Lightricks LTX 2.3 Fast — text/image→video, 6–20s, up to 4K",
     "gemini-omni-video": "Google Gemini Omni — multimodal video with native audio, 4–10s, up to 4K.",
     "gemini-omni-flash": "Google Gemini Omni Flash — faster, cheaper Omni tier; multimodal video with native audio, 4–10s, up to 4K.",
+    "gemini-omni-flash-1-2": "Google Gemini Omni Flash 1.2 — video with native audio, 3–15s, 360p to 4K; text, up to 6 reference images, exact first and last frames, or a video edit.",
     "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)",
@@ -311,6 +312,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "ltx-2.3-fast": "Lightricks LTX 2.3 Fast — start/end frame i2v, 6–20s, up to 4K",
     "gemini-omni-video": "Google Gemini Omni — multimodal video with native audio, 4–10s, up to 4K.",
     "gemini-omni-flash": "Google Gemini Omni Flash — faster, cheaper Omni tier; multimodal video with native audio, 4–10s, up to 4K.",
+    "gemini-omni-flash-1-2": "Google Gemini Omni Flash 1.2 — video with native audio, 3–15s, 360p to 4K; text, up to 6 reference images, exact first and last frames, or a video edit.",
     "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",

package/src/provider-prompt-doctrine.ts

@@ -268,6 +268,34 @@ Source: KIE gemini-omni-video market contract (parameters + live behavior probed
 aspect-ratio hard-reject, see providers/kie/video.ts). Captured 2026-08-09.`,
 }
 
+const GEMINI_OMNI_12_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["gemini-omni-flash-1-2"],
+  heading: "Gemini Omni Flash 1.2 (gemini-omni-flash-1-2)",
+  tips: [
+    "Google video with native sound: text-to-video, frames, reference images and video-edit through one prompt surface. Every second from 3 to 15; 360p, 720p, 1080p or 4K.",
+    "Structure like the platform default: subject → action → scene → lighting → camera → style. Quote dialogue lines to have them spoken; describe SFX and ambience plainly.",
+    "Only a start frame (and an end frame) wired: they are sent as exact first and last frames. With reference images wired too, frames join the image list after your references and are named in the prompt.",
+    "Up to 6 reference images: bind them by ordinal ('the woman from @image_1'). No character or voice references on this model. Video-edit: describe the change; the output follows the source clip, up to 15s.",
+  ],
+  doctrine: `Prompt structure (no public Google prompt guide exists for this endpoint — the API
+contract is the doctrine source):
+subject → action → scene/environment → lighting → camera movement → style → constraints.
+
+**Modes (picked from the wired inputs)**
+- Nothing visual → text-to-video.
+- Start frame alone, or start + end frame → exact frames. First + last holds up to 10s; past that the two frames go by the reference route below.
+- Reference images wired → your images come FIRST, in your order (\`@image_1\`, \`@image_2\`, …), up to 6. A wired start or end frame is appended after them and the platform names it in the prompt as the opening or closing frame.
+- Source video wired → video-edit: describe the CHANGE, not a full re-description. The output follows the source clip, which is cut to 15s at most. Up to 5 images may ride beside it.
+
+**Audio (native)**
+- Audio is generated with the clip. Quote dialogue to have it spoken; describe SFX and ambience plainly. State exclusions ("no music") or a bed may be invented.
+
+**Duration & tiers**
+- Any whole second from 3 to 15. 360p is for drafts; 720p and 1080p are close in price; 4K only when the deliverable needs it.
+
+Source: KIE google/gemini-omni-flash-1-2 market contract. Captured 2026-11-09.`,
+}
+
 const GROK_IMAGINE_DOCTRINE: ProviderPromptDoctrine = {
   providers: ["grok-i2v", "grok-imagine-video-1.5"],
   heading: "Grok Imagine (grok-i2v, grok-imagine-video-1.5)",
@@ -521,6 +549,7 @@ export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
   MINIMAX_H3_DOCTRINE,
   VEO_31_DOCTRINE,
   GEMINI_OMNI_DOCTRINE,
+  GEMINI_OMNI_12_DOCTRINE,
   GROK_IMAGINE_DOCTRINE,
   WAN_DOCTRINE,
   WAN_3_DOCTRINE,

package/src/ref-binding.ts

@@ -48,24 +48,61 @@ 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. */
+/** How a video provider addresses its images in the prompt, by array order
+ *  (`VideoReferenceSyntax` in @nodaro/shared). */
+export type ImageReferenceSyntax = "@image_N" | "@image(n)" | "[Image N]" | "image N"
+
+/** The binding sentences — frames and identity references — in one provider syntax. */
 export interface ImageBinding {
   ordinal: (n: number) => string
+  /** One frame: the opening or the closing one. */
   frame: (n: number, role: "opening" | "closing") => string
+  /** A start and an end frame together. */
+  frames: (first: number, last: number) => string
+  /** Seats `first`..`last` are references, not frames. */
+  identities: (first: number, last: number) => string
+}
+
+const roleWords = (role: "opening" | "closing") => `${role} (${role === "opening" ? "first" : "last"})`
+
+/** "image 1", "image 1 and image 2", "image 1, image 2 and image 3". */
+function plainList(first: number, last: number): string {
+  const names = Array.from({ length: last - first + 1 }, (_, i) => `image ${first + i}`)
+  return names.length === 1 ? names[0] : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`
 }
 
 /**
  * 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.
+ * {@link REF_BINDING} — the platform swap point, byte for byte; `@image(n)` and
+ * `[Image N]` spell the same sentences in the form the provider documents.
+ *
+ * `image N` (Gemini Omni Flash 1.2) is plain words, each sentence stating what
+ * an image IS: "image 3 is the opening (first) frame of the video. image 1 and
+ * image 2 are references for the subject; they are not frames." It is the form
+ * KIE's own example uses. In staging runs neither wording made 1.2 open on the
+ * frame: beside references the frame is one more reference, so the sentence
+ * guides the clip and never makes the frame exact.
  */
-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}]`
+export function imageBindingFor(syntax: ImageReferenceSyntax): ImageBinding {
+  if (syntax === "image N") {
+    return {
+      ordinal: (n) => `image ${n}`,
+      frame: (n, role) => `image ${n} is the ${roleWords(role)} frame of the video.`,
+      frames: (first, last) => `image ${first} is the ${roleWords("opening")} frame and image ${last} is the ${roleWords("closing")} frame of the video.`,
+      identities: (first, last) => first === last
+        ? `image ${first} is a reference for the subject; it is not a frame.`
+        : `${plainList(first, last)} are references for the subject; they are not frames.`,
+    }
+  }
+  const ordinal = syntax === "@image_N"
+    ? REF_BINDING.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.`,
+    frame: syntax === "@image_N" ? REF_BINDING.frame : (n, role) => `Use ${ordinal(n)} as the ${roleWords(role)} frame of the video.`,
+    frames: (first, last) => `Use ${ordinal(first)} as the ${roleWords("opening")} frame and ${ordinal(last)} as the ${roleWords("closing")} frame of the video.`,
+    identities: (first, last) => identityRefsSentence(first, last, ordinal),
   }
 }
 

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, imageBindingFor, SEEDANCE_VIDEO_EDIT_PREFIX, buildSeedanceVideoEditPrompt, type ImageBinding } from "./ref-binding.js"
+export { REF_BINDING, identityRefsSentence, imageBindingFor, SEEDANCE_VIDEO_EDIT_PREFIX, buildSeedanceVideoEditPrompt, type ImageBinding, type ImageReferenceSyntax } from "./ref-binding.js"
 export { resolveRefIdTokens, type RefIdTokenContext } from "./ref-id-tokens.js"