@nodaro/prompts 1.3.1 → 1.4.0

package/package.json

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

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

@@ -171,3 +171,25 @@ describe("resolveSeedance2Inputs", () => {
     }
   })
 })
+
+describe("promptBindsFirstFrame suffix suppression (overlap colon-position finding)", () => {
+  it("suppresses the trailing sentence when the prompt already binds the first frame", () => {
+    const r = resolveSeedance2Inputs({
+      prompt: "extend @video_1 as follows:use @image_1 as the first frame, it is the last keyframe of @video_1\nbeats",
+      firstFrameUrl: "https://r2/anchor.jpg",
+      refVideoUrls: ["https://r2/ref.mp4"],
+    })
+    expect(r.promptSuffix).toBe("")
+    expect(r.referenceImageUrls).toEqual(["https://r2/anchor.jpg"]) // image still rides
+  })
+
+  it("keeps the sentence for plain prompts and for first+last frame pairs", () => {
+    const plain = resolveSeedance2Inputs({ prompt: "a cat", firstFrameUrl: "https://r2/a.jpg", refVideoUrls: ["https://r2/v.mp4"] })
+    expect(plain.promptSuffix).toContain("opening (first) frame")
+    const both = resolveSeedance2Inputs({
+      prompt: "use @image_1 as the first frame, it is the last keyframe of @video_1",
+      firstFrameUrl: "https://r2/a.jpg", lastFrameUrl: "https://r2/b.jpg", refVideoUrls: ["https://r2/v.mp4"],
+    })
+    expect(both.promptSuffix).toContain("closing (last) frame") // pair sentence kept — last frame has no in-prompt binding
+  })
+})

package/src/seedance-2-inputs.ts

@@ -4,6 +4,9 @@ import { REF_BINDING } from "./video-reference-resolver.js"
 export type Seedance2Mode = "first-frame" | "first-last-frame" | "reference"
 
 export interface Seedance2InputsArgs {
+  /** The generation prompt — used ONLY to detect an existing first-frame
+   *  binding and suppress the duplicate trailing sentence. */
+  prompt?: string
   firstFrameUrl?: string
   lastFrameUrl?: string
   refImageUrls?: readonly string[]
@@ -37,6 +40,19 @@ 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 function resolveSeedance2Inputs(args: Seedance2InputsArgs): Seedance2InputsResult {
   const firstFrameUrl = clean(args.firstFrameUrl)
   const lastFrameUrl = clean(args.lastFrameUrl)
@@ -76,7 +92,10 @@ export function resolveSeedance2Inputs(args: Seedance2InputsArgs): Seedance2Inpu
   if (lastFrameUrl) { referenceImageUrls.push(lastFrameUrl); lastOrdinal = referenceImageUrls.length }
 
   let promptSuffix = ""
-  if (firstOrdinal > 0 && lastOrdinal > 0) {
+  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.