@nodaro/prompts 1.1.1 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "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__/parameter-registry-sync.test.ts

@@ -22,7 +22,7 @@
  */
 
 import { describe, it, expect } from "vitest"
-import { PARAMETER_NODE_TYPES, getParameterValue } from "@nodaro/shared"
+import { PARAMETER_NODE_TYPES, HINT_EXEMPT_PARAMETER_TYPES, getParameterValue } from "@nodaro/shared"
 import { getParameterPromptHint } from "../parameter-prompt-hint.js"
 
 // Catalog-driven types need real ids — the prompt-hint builders look them up.
@@ -155,16 +155,11 @@ const SAMPLE_DATA_BY_TYPE: Record<string, Record<string, unknown>> = {
 }
 
 // Types that intentionally do NOT inject a prompt hint via
-// getParameterPromptHint. They carry pure runtime parameters (counts,
-// durations, aspect ratios, motion intensity) consumed by the executor
-// directly, not appended to a downstream prompt.
-const HINT_EXEMPT: ReadonlySet<string> = new Set([
-  "motion",
-  "style-guide",
-  "scene-count",
-  "duration",
-  "aspect-ratio",
-])
+// getParameterPromptHint. Canonical set lives in @nodaro/shared next to
+// PARAMETER_NODE_TYPES — Test 4 below keeps it honest by asserting each
+// member REALLY returns "" (so a type can't be quietly exempted to dodge a
+// missing-case failure).
+const HINT_EXEMPT = HINT_EXEMPT_PARAMETER_TYPES
 
 // =============================================================================
 // Test 1 — every type in the set has a sample (forces the developer who adds

package/src/__tests__/seedance-extend.test.ts

@@ -21,11 +21,12 @@ describe("seedance-2-extend shared wiring", () => {
     expect(m.pricing[0]!.identifier).toBe("seedance-2-extend")
   })
 
-  it("stitch constants match the spike-validated recipe (4 tail / 3 head / 0.15s fades)", () => {
+  it("stitch constants match the spike-validated recipe (4 tail / 3 head / 0.15s fades / 2s ref tail)", () => {
     expect(SEEDANCE_2_EXTEND_STITCH).toEqual({
       trimTailFrames: 4,
       trimHeadFrames: 3,
       audioFadeSec: 0.15,
+      referenceTailSeconds: 2,
     })
   })
 

package/src/parameter-prompt-hint.ts

@@ -273,6 +273,12 @@ export function getParameterPromptHint(
 
     case "tone":
       return asStr(data.tone).trim()
+    case "style-guide":
+      // The node's whole purpose is injecting its style text into consumer
+      // prompts; without this case, {Style Guide} refs stayed as literal
+      // brace text and direct wires injected nothing (only fieldMappings
+      // worked, via getParameterValue).
+      return asStr(data.text).trim()
     case "text-prompt":
       return asStr(data.text).trim()
     default:

package/src/prompt-wizard-categories.ts

@@ -162,6 +162,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "nano-banana": "Fast generation, style flexibility, reference image support",
     "nano-banana-pro": "Higher quality Nano Banana with better detail",
     "nano-banana-2": "Latest Nano Banana with resolution options (1K/2K/4K)",
+    "nano-banana-2-lite": "Fast, low-cost 1K generation for drafts and iteration",
     "gpt-image": "Creative concepts, illustration, variable quality tiers",
     "gpt-image-2": "Latest GPT Image — sharp text, photorealism, 1K/2K/4K resolution",
     "grok": "General purpose, good text understanding",
@@ -172,6 +173,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "qwen": "Versatile, good prompt adherence",
     "seedream": "Artistic, painterly styles, creative interpretation",
     "seedream-5-lite": "Lighter Seedream, faster artistic generation",
+    "seedream-5-pro": "Flagship Seedream — strongest instruction following, 2K via high quality",
     "z-image": "Experimental, novel generation approaches",
     "wan-2.7":     "Wan 2.7 T2I — 1K/2K/4K, up to 9 ref images",
     "wan-2.7-pro": "Wan 2.7 Pro T2I — higher quality, 1K/2K/4K",
@@ -194,6 +196,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "qwen-edit": "Instruction-based editing",
     "seedream-edit": "Artistic style editing",
     "seedream-5-lite-i2i": "Light artistic transformation",
+    "seedream-5-pro-i2i": "Pro-grade instruction-based edits, multi-reference",
     "flux-kontext": "Character-consistent edits with reference awareness",
     "flux-kontext-max": "Premium character-consistent editing",
     "kontext-multi": "Multi-image Kontext via Replicate — up to 4 refs, no safety filter",
@@ -216,6 +219,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "qwen-edit": "Instruction-based editing",
     "seedream-edit": "Artistic style editing",
     "seedream-5-lite-i2i": "Light artistic transformation",
+    "seedream-5-pro-i2i": "Pro-grade instruction-based edits, multi-reference",
     "flux-kontext": "Character-consistent edits with reference awareness",
     "flux-kontext-max": "Premium character-consistent editing",
     "kontext-multi": "Multi-image Kontext via Replicate — up to 4 refs, no safety filter",

package/src/provider-prompt-doctrine.ts

@@ -7,10 +7,18 @@
  *   4. compact recipes in MCP tool descriptions point here via get_node_skill
  *
  * Sources, in precedence order (conflicts resolve top-down):
+ *   Seedance 2.0:
  *   - Official BytePlus ModelArk "Dreamina Seedance 2.0 series prompt guide"
  *     https://docs.byteplus.com/en/docs/ModelArk/2222480
  *   - Official launch post https://seed.bytedance.com/en/blog/official-launch-of-seedance-2-0
  *   - KIE API docs https://docs.kie.ai/market/bytedance/seedance-2
+ *   Kling:
+ *   - Official "Kling Video 2.6 Audio User Guide"
+ *     https://kling.ai/quickstart/klingai-video-26-audio-user-guide
+ *   - fal.ai "Kling 3.0 Prompting Guide" https://blog.fal.ai/kling-3-0-prompting-guide/
+ *   - KIE API docs https://docs.kie.ai/market/kling/kling-3-0
+ *   - Live KIE-path dialogue probe 2026-07-16 (scripted lines spoken verbatim,
+ *     lip-synced, on both kling-2.6 and kling-3.0 with sound=true)
  */
 export interface ProviderPromptDoctrine {
   /** MODEL_CATALOG ids this doctrine covers. */
@@ -66,8 +74,46 @@ precise subject → action details → scene/environment → lighting & color to
 - Repeated extension degrades quality: prefer high-definition reference assets and avoid stacking many continuations.`,
 }
 
+const KLING_AUDIO_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["kling", "kling-3.0", "kling-3-omni"],
+  heading: "Kling 2.6 / 3.0 / 3 Omni (kling, kling-3.0, kling-3-omni)",
+  tips: [
+    "Kling speaks scripted dialogue natively with lip sync — quote the line and enable sound: [Anna: warm calm voice]: \"We made it.\" On kling/kling-3.0 audio raises the credit cost; kling-3-omni includes it.",
+    "Structure prompts as Scene → character/element → Motion → Audio → style. Put ALL sound in one 'Audio:' block: dialogue in quotes, then SFX and ambience described plainly ('rain tapping on glass, no music').",
+    "Give each speaker a stable label + voice description and reuse it exactly — [Detective: low raspy voice, tired] — pronouns or renamed speakers break voice binding in multi-character scenes.",
+    "Tone words in the bracket steer delivery (whispering, crying, fast urgent voice); pace with 'Immediately' / 'after a pause'. 2.6 voices are English/Chinese only; 3.0 adds dialects and code-switching.",
+    "kling-3.0 wired references become @element_name mentions (handled automatically by the editor); multi-shot mode forces sound ON. Kling 2.6 prompts cap at 1000 chars — keep the Audio block tight.",
+    "Say what should NOT sound: 'no background music, no other sounds' — otherwise Kling invents a music bed under dialogue.",
+  ],
+  doctrine: `Prompt structure: Scene (setting, light) → Character/Element (who, appearance) → Motion (action, camera) → Audio (dialogue / SFX / ambience / music) → Others (style, emotion).
+
+**Dialogue (native speech + lip sync — verified on the KIE path 2026-07-16)**
+- Quote the spoken line and enable the sound toggle; the model bakes the voice AND matching lip movement: the woman says "The quick brown fox jumps over the lazy dog."
+- Prefer labeled dialogue with a voice description: [Character label: voice/tone description]: "line". Example: [Exhausted Partner: trembling frustrated voice]: "You never listen to me."
+- Keep character labels unique and reuse them verbatim — never switch to pronouns mid-prompt; the label is what binds a voice to a speaker across lines. Kling 2.6 additionally supports [Character@VoiceName] platform-voice binding.
+- Tone words inside the bracket steer delivery: whispering, crying voice, controlled serious voice, fast urgent voice. Sequence speech with temporal markers ("Immediately", "after a pause") when two lines must not overlap.
+- Languages: Kling 2.6 outputs English/Chinese voices only (other languages are auto-translated to English). Kling 3.0 supports multiple languages, dialects, accents, and code-switching within one scene — mark the language explicitly ("says in Japanese …").
+
+**SFX / ambience / music**
+- Put them in the same Audio block, described plainly: "Rain tapping softly on the window, distant thunder, no music."
+- State exclusions explicitly — "no background music, no other sounds" — or the model tends to add a bed under dialogue.
+
+**Toggle + cost**
+- The audio lever is the node's sound toggle (KIE \`sound\` param). On kling (2.6) and kling-3.0 enabling audio raises the credit cost (the \`:audio\` composite); kling-3.0 generates audio by DEFAULT — pass sound: false for the cheaper silent tier. kling-3-omni (Replicate) includes audio in its flat per-duration rate.
+- Multi-shot kling-3.0 (\`multi_shots\`) forces sound ON — budget for the audio rate.
+
+**References & elements (kling-3.0 / omni)**
+- Wired references are injected as \`kling_elements\` and MUST be mentioned as @element_name in the prompt — the editor's {image:N} tokens and the server prefixer handle this automatically; when hand-writing prompts, mention every element or it is silently ignored.
+- kling-3-omni is image-to-video only (start frame required) and accepts up to 7 reference images; element voice references (element_input_audio_urls, 5-30s clips) bind a voice to an element.
+
+**Limits**
+- Kling 2.6 prompts cap at 1000 characters — front-load scene + dialogue and trim style tails first. kling-3.0 accepts long prompts.
+- Durations: 2.6 = 5/10s; 3.0/omni = 3-15s. A spoken line needs roughly 1s per 2-3 words — don't script more dialogue than the clip can hold.`,
+}
+
 export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
   SEEDANCE_2_DOCTRINE,
+  KLING_AUDIO_DOCTRINE,
 ]
 
 const DOCTRINE_BY_PROVIDER: ReadonlyMap<string, ProviderPromptDoctrine> = new Map(