@nodaro/prompts 1.17.2 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.17.2",
+  "version": "1.19.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",
@@ -20,7 +20,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^3.0.0"
+    "@nodaro/shared": "^3.9.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/assemble-suno-input.test.ts

@@ -181,17 +181,30 @@ describe("assembleSunoInput — persona spread", () => {
 
 describe("assembleSunoInput — duration pass-through", () => {
   it("carries data.duration onto the result verbatim (the provider client gates the send)", () => {
+    const r = assembleSunoInput({
+      node: node({ customMode: true, style: "pop", model: "V6", duration: 120 }),
+      graph: emptyGraph,
+      userPrompt: "song",
+    })
+    expect(r.duration).toBe(120)
+  })
+
+  // The assembler is a FIELD CARRIER, not the duration gate: only the provider
+  // client consults `sunoModelHonoursDuration` (V6 family), so a legacy model
+  // still carries `duration` through this layer unchanged.
+  it("carries data.duration for a LEGACY model too — the gate lives in the provider client", () => {
     const r = assembleSunoInput({
       node: node({ customMode: true, style: "pop", model: "V5_5", duration: 120 }),
       graph: emptyGraph,
       userPrompt: "song",
     })
     expect(r.duration).toBe(120)
+    expect(r.model).toBe("V5_5")
   })
 
   it("no data.duration → undefined", () => {
     const r = assembleSunoInput({
-      node: node({ model: "V5_5" }),
+      node: node({ model: "V6" }),
       graph: emptyGraph,
       userPrompt: "song",
     })

package/src/__tests__/fixtures/parameter-hint-golden.json

@@ -381,7 +381,7 @@
         }
       },
       "ctx": null,
-      "expected": "camera arcs to the left around the subject"
+      "expected": "slow camera arc around the subject through a partial arc, the background sliding to the left across the frame"
     },
     {
       "key": "camera-motion/id:auto",

package/src/__tests__/hint-join.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest"
+import { joinHintFragments } from "../hint-join.js"
+import { composeCameraMotionHintFromConnections, getCameraMotionPromptHint } from "../camera-motions.js"
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+
+/**
+ * The tested camera-motion injections are multi-sentence paragraphs ending in
+ * a period. Every composer used to glue fragments with `", "`, which produced
+ * `"...no pull-out., beginning with ..."`. The joiner keeps the comma between
+ * clause-style fragments (byte-identical to before) and uses a space after a
+ * fragment that already closes a sentence.
+ */
+describe("joinHintFragments", () => {
+  it("keeps the historical comma join for clause-style fragments", () => {
+    expect(joinHintFragments(["slow pan left", "beginning with wide shot"])).toBe(
+      "slow pan left, beginning with wide shot",
+    )
+  })
+
+  it("uses a space after a fragment that already ends a sentence", () => {
+    expect(joinHintFragments(["The camera pans left.", "beginning with wide shot"])).toBe(
+      "The camera pans left. beginning with wide shot",
+    )
+    expect(joinHintFragments(["Hold!", "then cut", "Done?", "fin"])).toBe("Hold! then cut, Done? fin")
+  })
+
+  it("skips empty fragments and never adds or strips punctuation", () => {
+    expect(joinHintFragments(["", "The camera pans left.", ""])).toBe("The camera pans left.")
+    expect(joinHintFragments([])).toBe("")
+  })
+})
+
+describe("sentence-style camera-motion hints compose cleanly", () => {
+  it("never emits a period directly followed by a comma", () => {
+    const composed = composeCameraMotionHintFromConnections("dolly-in", ["wide shot"], ["close-up"])
+    expect(composed).not.toContain(".,")
+    expect(composed.startsWith(getCameraMotionPromptHint("dolly-in"))).toBe(true)
+    expect(composed).toContain("beginning with wide shot, ending with close-up")
+  })
+
+  it("wraps preText/postText around a sentence-style hint without a stray comma", () => {
+    const out = getParameterPromptHint({
+      id: "n1",
+      type: "camera-motion",
+      data: { cameraMotion: "tilt-up", preText: "shot on location", postText: "golden hour" },
+    })
+    expect(out).not.toContain(".,")
+    expect(out.startsWith("shot on location, The camera")).toBe(true)
+    expect(out.endsWith("No zoom, no push-in. golden hour")).toBe(true)
+  })
+
+  it("keeps a clause-style hint byte-identical to the pre-joiner output", () => {
+    expect(composeCameraMotionHintFromConnections("static", ["wide shot"], [])).toBe(
+      "locked off static camera, no camera movement, beginning with wide shot",
+    )
+  })
+})

package/src/__tests__/node-prompt-fields.test.ts

@@ -16,10 +16,10 @@ describe("nodeSupportsPromptAffixes", () => {
     expect(nodeSupportsPromptAffixes("not-a-node")).toBe(false)
     expect(nodeSupportsPromptAffixes(undefined)).toBe(false)
   })
-  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (39 types)", () => {
+  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (40 types)", () => {
     const expected = Object.entries(NODE_PROMPT_FIELDS).filter(([, s]) => s.affixes !== false).map(([t]) => t)
     expect([...PROMPT_AFFIX_NODE_TYPES].sort()).toEqual(expected.sort())
-    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(39)
+    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(40)
   })
   it("getPromptFields still resolves", () => expect(getPromptFields("generate-image")?.prompt).toBe("prompt"))
 })
@@ -28,6 +28,7 @@ describe("promptAffixCoreField — the data key the RUN wraps with pre/post text
   it("most nodes: the editor's primary prompt field", () => {
     expect(promptAffixCoreField("generate-image")).toBe("prompt")
     expect(promptAffixCoreField("llm-chat")).toBe("userInput")
+    expect(promptAffixCoreField("pro-3d-render")).toBe("scenePrompt")
     expect(promptAffixCoreField("generate-3d-scene")).toBe("scenePrompt")
     expect(promptAffixCoreField("edit-3d-scene")).toBe("editPrompt")
     expect(promptAffixCoreField("text-to-speech")).toBe("directText")

package/src/__tests__/scene3d-reference-doctrine.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Scene3D layout-reference doctrine — the wording the 2026-09-10 greybox
+ * experiment's Seedance A/B rerun quotes verbatim, pinned byte-for-byte, plus
+ * the still/clip/cuts variants, the re-run idempotence key and the rule-2
+ * warning builder.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  buildScene3DLayoutScopingLine,
+  buildScene3DUnreferencedFiguresWarning,
+  hasScene3DLayoutScopingLine,
+  renderScene3DLayoutScopingLine,
+  SCENE3D_FIGURE_REFERENCE_RULE,
+  SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE,
+  SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE,
+  SCENE3D_LAYOUT_SCOPING_MARKER,
+  SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE,
+} from "../scene3d-reference-doctrine.js"
+import { renderReferenceCaptionLines } from "../described-references.js"
+
+const CLIP =
+  "LAYOUT reference only — match its subject positions and blocking, its foreground occlusion, its framing, its camera angle, its camera motion and its timing. " +
+  "Ignore its untextured grey clay placeholder look, its flat placeholder colours, its materials, its lighting and its empty background; none of that is the target look. " +
+  "Take the look from the prompt and from the other references"
+
+const STILL =
+  "LAYOUT reference only — match its subject positions and blocking, its foreground occlusion, its framing and its camera angle. " +
+  "Ignore its untextured grey clay placeholder look, its flat placeholder colours, its materials, its lighting and its empty background; none of that is the target look. " +
+  "Take the look from the prompt and from the other references"
+
+describe("SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE — the fixture the A/B rerun quotes", () => {
+  it("is the clip caption: what the reference is for, then what to ignore, plainly", () => {
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE).toBe(CLIP)
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clip).toBe(CLIP)
+  })
+
+  it("is a caption, not a line: no leading binding, no trailing full stop (the renderer adds both)", () => {
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE.startsWith(SCENE3D_LAYOUT_SCOPING_MARKER)).toBe(true)
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE.endsWith(".")).toBe(false)
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE).not.toContain("@video")
+  })
+
+  it("renders on its seat exactly as the platform's rail-caption renderer renders it", () => {
+    const platform = renderReferenceCaptionLines([SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE], undefined, { video: 1, audio: 0 })
+    expect(platform).toEqual([SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clipRendered])
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clipRendered).toBe(`@video_1: ${CLIP}.`)
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.stillRendered).toBe(`@image_1: ${STILL}.`)
+  })
+
+  it("still: drops the motion, timing and cut clauses a single frame cannot carry", () => {
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.still).toBe(STILL)
+    // A still with clip-only facts still reads as a still.
+    expect(buildScene3DLayoutScopingLine({ carries: "still", shots: 4, includesCameraMotion: true })).toBe(STILL)
+  })
+
+  it("clip with several shots names the cut points; one shot is not a cut", () => {
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clipWithCuts).toContain(
+      "its camera angle, its camera motion, its 4 shots and where they cut and its timing.",
+    )
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clip).not.toContain("where they cut")
+  })
+
+  it("clip without a camera move keeps timing but claims no motion", () => {
+    const line = buildScene3DLayoutScopingLine({ carries: "clip", includesCameraMotion: false })
+    expect(line).not.toContain("camera motion")
+    expect(line).toContain("its camera angle and its timing.")
+  })
+
+  it("names what to ignore explicitly — every property of the clay look — and never the target look", () => {
+    for (const word of ["grey clay placeholder look", "placeholder colours", "materials", "lighting", "empty background"]) {
+      expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE).toContain(word)
+    }
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE.toLowerCase()).not.toContain("photoreal")
+  })
+
+  it("renderScene3DLayoutScopingLine trims the binding", () => {
+    expect(renderScene3DLayoutScopingLine(" @image_3 ", { carries: "still" }).startsWith("@image_3: LAYOUT")).toBe(true)
+  })
+})
+
+describe("hasScene3DLayoutScopingLine — the re-run idempotence key", () => {
+  it("recognises the platform's rendered line, per binding", () => {
+    const prompt = `A brief.\n${SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clipRendered}`
+    expect(hasScene3DLayoutScopingLine(prompt, "@video_1")).toBe(true)
+    expect(hasScene3DLayoutScopingLine(prompt, "@video_2")).toBe(false)
+    expect(hasScene3DLayoutScopingLine(prompt, "@video_10")).toBe(false)
+  })
+
+  it("recognises a hand-typed sentence and an older wording, so a pasted line is not doubled", () => {
+    expect(hasScene3DLayoutScopingLine("@video_1 is a LAYOUT reference only: match its seating.", "@video_1")).toBe(true)
+    expect(hasScene3DLayoutScopingLine("@image_2 is an LAYOUT reference only", "@image_2")).toBe(true)
+    expect(hasScene3DLayoutScopingLine("Two people at a table. @video_1 is a great clip.", "@video_1")).toBe(false)
+  })
+
+  it("is false on nothing", () => {
+    expect(hasScene3DLayoutScopingLine(undefined, "@video_1")).toBe(false)
+    expect(hasScene3DLayoutScopingLine("", "@video_1")).toBe(false)
+  })
+})
+
+describe("buildScene3DUnreferencedFiguresWarning — rule 2 as a warning, never a block", () => {
+  it("warns when figures outnumber character references", () => {
+    const w = buildScene3DUnreferencedFiguresWarning({ figureCount: 6, characterReferenceCount: 1 })
+    expect(w).toBeDefined()
+    expect(w?.code).toBe(SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE)
+    expect(w?.missing).toBe(5)
+    expect(w?.message).toBe(
+      "The layout reference shows 6 figures but 1 character reference is attached. " +
+        "A figure without its own character reference takes the clay look of the layout reference. " +
+        "Attach one character reference per figure (5 more).",
+    )
+  })
+
+  it("states the budget when the image-reference cap is known — a clip rides the video rail", () => {
+    const fits = buildScene3DUnreferencedFiguresWarning({ figureCount: 6, characterReferenceCount: 0, imageReferenceCap: 9 })
+    expect(fits?.message).toContain("this model takes 9 image references, which leaves 3 for a location or style plate.")
+    const tight = buildScene3DUnreferencedFiguresWarning({ figureCount: 8, characterReferenceCount: 0, imageReferenceCap: 9 })
+    expect(tight?.message).toContain("does not fit — reference the figures that matter most first.")
+  })
+
+  it("counts the seat a still layout reference occupies against the same budget", () => {
+    const still = buildScene3DUnreferencedFiguresWarning({
+      figureCount: 6,
+      characterReferenceCount: 0,
+      imageReferenceCap: 9,
+      layoutReferenceImageSeats: 1,
+    })
+    expect(still?.message).toContain("leaves 2 for a location or style plate.")
+  })
+
+  it("stays silent when every figure has a reference, when there are no figures, or when the count is unknown", () => {
+    expect(buildScene3DUnreferencedFiguresWarning({ figureCount: 2, characterReferenceCount: 2 })).toBeUndefined()
+    expect(buildScene3DUnreferencedFiguresWarning({ figureCount: 2, characterReferenceCount: 5 })).toBeUndefined()
+    expect(buildScene3DUnreferencedFiguresWarning({ figureCount: 0, characterReferenceCount: 0 })).toBeUndefined()
+    expect(buildScene3DUnreferencedFiguresWarning({ figureCount: undefined, characterReferenceCount: 0 })).toBeUndefined()
+  })
+
+  it("states the rule in user terms", () => {
+    expect(SCENE3D_FIGURE_REFERENCE_RULE).toContain("its own character reference")
+    expect(SCENE3D_FIGURE_REFERENCE_RULE).toContain("two reference slots free")
+  })
+})

package/src/__tests__/sound-aggregator.test.ts

@@ -60,7 +60,7 @@ describe("composeSoundHintFromConnections — Suno Generate", () => {
     expect(out.warnings).toEqual([])
   })
 
-  it("accepts voice-character nodes (Suno V5 supports vocal description)", () => {
+  it("accepts voice-character nodes (Suno V6 supports vocal description)", () => {
     const out = composeSoundHintFromConnections(
       sunoConsumer({ customMode: true }),
       "suno-generate",

package/src/assemble-suno-input.ts

@@ -87,8 +87,9 @@ export interface AssembleSunoResult {
   /**
    * Requested song length in seconds (KIE: 10–360). Passed through from
    * `data.duration` unconditionally — the provider client is the single
-   * gate that only sends it when customMode && model V5_5 (KIE ignores it
-   * elsewhere), so the assembler stays a faithful field carrier.
+   * gate that only sends it when `customMode && sunoModelHonoursDuration(model)`
+   * (the V6 family — V6 / V6_MINI / V6_WILD; KIE ignores it on every earlier
+   * version), so the assembler stays a faithful field carrier.
    */
   duration?: number
   personaId?: string