@nodaro/prompts 1.0.1

package/src/__tests__/prompt-wizard-categories.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest"
+import {
+  getCategoriesForNodeType,
+  isWizardSupported,
+  MUSIC_WIZARD_CATEGORIES,
+} from "../prompt-wizard-categories.js"
+
+describe("suno-generate:style wizard target", () => {
+  it("reuses MUSIC categories and is supported", () => {
+    // The composite `:style` target drives the SAME music wizard form as the
+    // base `suno-generate` node — it only changes the OUTPUT shape (tags vs
+    // prose), handled in the backend system-prompt builder.
+    expect(getCategoriesForNodeType("suno-generate:style")).toEqual(MUSIC_WIZARD_CATEGORIES)
+    expect(isWizardSupported("suno-generate:style")).toBe(true)
+  })
+})
+
+describe("suno-generate:negativeStyle + :lyrics wizard targets", () => {
+  // Task 5 extends the Phase-D composite-key pattern to two more Suno fields.
+  // BOTH reuse the SAME music wizard FORM as `:style`/`suno-generate`; only the
+  // backend OUTPUT framing differs (avoid-tags / sectioned lyrics).
+  it("negativeStyle reuses MUSIC categories and is supported", () => {
+    expect(getCategoriesForNodeType("suno-generate:negativeStyle")).toEqual(MUSIC_WIZARD_CATEGORIES)
+    expect(isWizardSupported("suno-generate:negativeStyle")).toBe(true)
+  })
+
+  it("lyrics reuses MUSIC categories and is supported", () => {
+    expect(getCategoriesForNodeType("suno-generate:lyrics")).toEqual(MUSIC_WIZARD_CATEGORIES)
+    expect(isWizardSupported("suno-generate:lyrics")).toBe(true)
+  })
+})

package/src/__tests__/provider-prompt-doctrine.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest"
+import {
+  PROVIDER_PROMPT_DOCTRINES,
+  getPromptDoctrine,
+  getPromptTips,
+} from "../provider-prompt-doctrine.js"
+import { MODEL_CATALOG } from "@nodaro/shared"
+
+describe("PROVIDER_PROMPT_DOCTRINES", () => {
+  it("every doctrine maps to real catalog providers and has tips + body", () => {
+    expect(PROVIDER_PROMPT_DOCTRINES.length).toBeGreaterThan(0)
+    for (const d of PROVIDER_PROMPT_DOCTRINES) {
+      expect(d.providers.length).toBeGreaterThan(0)
+      for (const p of d.providers) expect(MODEL_CATALOG[p]).toBeDefined()
+      expect(d.tips.length).toBeGreaterThanOrEqual(3)
+      expect(d.tips.length).toBeLessThanOrEqual(6)
+      for (const t of d.tips) expect(t.length).toBeLessThanOrEqual(220)
+      expect(d.doctrine.length).toBeGreaterThan(500)
+      expect(d.heading.length).toBeGreaterThan(0)
+    }
+  })
+
+  it("resolves by provider id, returns undefined/[] for providers without doctrine", () => {
+    expect(getPromptDoctrine("seedance-2")).toBeDefined()
+    expect(getPromptDoctrine("seedance-2-fast")).toBeDefined()
+    expect(getPromptDoctrine("veo3.1")).toBeUndefined()
+    expect(getPromptTips("seedance-2").length).toBeGreaterThan(0)
+    expect(getPromptTips("veo3.1")).toEqual([])
+  })
+
+  it("seedance doctrine encodes the official rules and bans the unstable patterns", () => {
+    const d = getPromptDoctrine("seedance-2")!
+    // untimed Shot N storyboards, never "(0-3s)" timestamps
+    expect(d.doctrine).toContain("Shot 1")
+    expect(d.doctrine).toMatch(/timestamp/i)
+    expect(d.doctrine).not.toMatch(/Shot \d+\s*\(\d+\s*[-–]\s*\d+s\)/)
+    // headshot + full-body identity rule (NOT multi-view)
+    expect(d.doctrine).toMatch(/headshot/i)
+    expect(d.doctrine).toMatch(/multi-view|three-view/i)
+    // audio symbol semantics + Nodaro brace caveat
+    expect(d.doctrine).toContain("（")
+    expect(d.doctrine).toContain("<")
+    expect(d.doctrine).toMatch(/quoted|quotes/i)
+    // edit/extend "reference" keyword trap
+    expect(d.doctrine).toMatch(/reference Video/i)
+    // no native negative-prompt param
+    expect(d.doctrine).toMatch(/negative/i)
+  })
+})

package/src/__tests__/resolve-prompt-append.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest"
+import { resolvePrompt, computeNodePrompt, composeNegative } from "../resolve-prompt.js"
+
+// `appendWired` (generate-image / generate-video only): the connected (wired)
+// prompt is APPENDED to the typed prompt instead of being a fallback. Every
+// other node type keeps the legacy precedence (override > typed > wired).
+const NO_REFS = new Map<string, string>()
+
+describe("composeNegative", () => {
+  it("joins typed + wired with '. '", () => {
+    expect(composeNegative("blurry", "low-res")).toBe("blurry. low-res")
+  })
+  it("typed alone when no wired; wired alone when no typed", () => {
+    expect(composeNegative("blurry", undefined)).toBe("blurry")
+    expect(composeNegative(undefined, "low-res")).toBe("low-res")
+  })
+  it("drops empty / whitespace parts → ''", () => {
+    expect(composeNegative("  ", "")).toBe("")
+    expect(composeNegative(undefined, undefined)).toBe("")
+  })
+})
+
+describe("resolvePrompt — appendWired", () => {
+  it("appends wired to the typed base, joined '. '", () => {
+    expect(resolvePrompt({ typed: ["a cat"], wired: "shot on film", refMap: NO_REFS, appendWired: true }))
+      .toBe("a cat. shot on film")
+  })
+
+  it("typed only when wired is absent/blank", () => {
+    expect(resolvePrompt({ typed: ["a cat"], wired: "  ", refMap: NO_REFS, appendWired: true })).toBe("a cat")
+    expect(resolvePrompt({ typed: ["a cat"], refMap: NO_REFS, appendWired: true })).toBe("a cat")
+  })
+
+  it("wired only when typed is empty", () => {
+    expect(resolvePrompt({ typed: [], wired: "shot on film", refMap: NO_REFS, appendWired: true })).toBe("shot on film")
+  })
+
+  it("an override (list fan-out item) fully replaces — wired does NOT append onto it", () => {
+    expect(resolvePrompt({ override: "OVR", typed: ["a cat"], wired: "film", refMap: NO_REFS, appendWired: true }))
+      .toBe("OVR")
+  })
+
+  it("WITHOUT appendWired: legacy precedence is byte-unchanged (typed wins, wired = fallback)", () => {
+    expect(resolvePrompt({ typed: ["a cat"], wired: "film", refMap: NO_REFS })).toBe("a cat")
+    expect(resolvePrompt({ typed: [], wired: "film", refMap: NO_REFS })).toBe("film")
+    expect(resolvePrompt({ override: "OVR", typed: ["a cat"], wired: "film", refMap: NO_REFS })).toBe("OVR")
+  })
+
+  it("computeNodePrompt threads appendWired for generate-image; other types unchanged", () => {
+    expect(
+      computeNodePrompt("generate-image", { prompt: "a cat" }, { wired: "film", refMap: NO_REFS, appendWired: true }),
+    ).toBe("a cat. film")
+    // video-to-video does NOT pass appendWired → wired stays a fallback
+    expect(
+      computeNodePrompt("video-to-video", { prompt: "a cat" }, { wired: "film", refMap: NO_REFS }),
+    ).toBe("a cat")
+  })
+})

package/src/__tests__/resolve-prompt.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest"
+import { resolvePrompt, computeNodePrompt, computeLlmChatFields } from "../resolve-prompt.js"
+const M = new Map<string, string>()
+const R = new Map([["Hero", "a knight"]])
+describe("resolvePrompt", () => {
+  it("override wins", () => expect(resolvePrompt({ override: "o", typed: ["t"], wired: "w", refMap: M })).toBe("o"))
+  it("first present typed candidate wins over wired", () =>
+    expect(resolvePrompt({ typed: [undefined, "  ", "t2"], wired: "w", refMap: M })).toBe("t2"))
+  it("falls through empty typed to wired", () =>
+    expect(resolvePrompt({ typed: ["", "   "], wired: "w", refMap: M })).toBe("w"))
+  it("nothing -> empty string", () => expect(resolvePrompt({ typed: [], refMap: M })).toBe(""))
+  it("resolves {Label} refs on the chosen branch", () =>
+    expect(resolvePrompt({ typed: ["x {Hero} y"], refMap: R })).toBe("x a knight y"))
+})
+describe("computeNodePrompt", () => {
+  const M = new Map<string, string>()
+  it("generate-image: typed prompt wins over wired", () =>
+    expect(computeNodePrompt("generate-image", { prompt: "typed" }, { wired: "wire", refMap: M })).toBe("typed"))
+  it("image-to-video: falls back to motionPrompt when prompt empty", () =>
+    expect(computeNodePrompt("image-to-video", { prompt: "", motionPrompt: "mp" }, { wired: "wire", refMap: M })).toBe("mp"))
+  it("text-to-audio: falls back to data.text", () =>
+    expect(computeNodePrompt("text-to-audio", { prompt: "", text: "t" }, { wired: "wire", refMap: M })).toBe("t"))
+  it("text-to-speech direct: uses directText", () =>
+    expect(computeNodePrompt("text-to-speech", { textSource: "direct", directText: "d" }, { wired: "wire", refMap: M })).toBe("d"))
+  it("text-to-speech connected: wire only (no typed)", () =>
+    expect(computeNodePrompt("text-to-speech", { textSource: "connected", directText: "ignored" }, { wired: "wire", refMap: M })).toBe("wire"))
+  it("video-retake: does not crash (not in NODE_MAPPABLE_FIELDS)", () =>
+    expect(computeNodePrompt("video-retake", { prompt: "vr" }, { wired: "w", refMap: M })).toBe("vr"))
+  it("social-publish: uses caption", () =>
+    expect(computeNodePrompt("social-publish", { caption: "c" }, { wired: "w", refMap: M })).toBe("c"))
+  it("override wins for any node", () =>
+    expect(computeNodePrompt("generate-image", { prompt: "typed" }, { wired: "w", override: "o", refMap: M })).toBe("o"))
+  it("unknown node defaults to ['prompt']", () =>
+    expect(computeNodePrompt("whatever", { prompt: "p" }, { refMap: M })).toBe("p"))
+})
+describe("computeLlmChatFields", () => {
+  const M = new Map<string, string>()
+  it("typed fields win; override beats typed userInput", () => {
+    expect(computeLlmChatFields({ userInput: "u", systemPrompt: "s" },
+      { wiredUserInput: "wu", wiredSystemPrompt: "ws", refMap: M })).toEqual({ userInput: "u", systemPrompt: "s" })
+    expect(computeLlmChatFields({ userInput: "u", systemPrompt: "s" },
+      { override: "o", wiredUserInput: "wu", wiredSystemPrompt: "ws", refMap: M }).userInput).toBe("o")
+  })
+})

package/src/__tests__/role-picker-shared.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Unified Reference Roles — Phase D Task 1 (shared role-picker support).
+ *
+ * Two shared changes that back the editor role-picker (Tasks 2-3):
+ *
+ *  (A) Custom-role VERBATIM relaxation in the HYBRID resolvers — a free-form
+ *      role typed in a mention's variant/role slot (e.g. `@kira:1:earrings`)
+ *      that doesn't resolve to a real matched variant now survives verbatim
+ *      ("the earrings from …") instead of collapsing to the source default
+ *      ("the person from …"). Applies to character (image + video) and location.
+ *
+ *  (B) Location bare-slug ROLE parsing — a slash-less, non-mode 3rd segment now
+ *      parses as a role (previously null → literal text). The F2 follow-up
+ *      REMOVED the preset gate, so a CUSTOM slug (`@old-library:1:foobar`) parses
+ *      as `role: "foobar"` too, mirroring the character parser. Legacy stays
+ *      byte-identical NOT via the parser but via the resolver's `if (t.role)
+ *      continue` guard — a role token (preset OR custom) is skipped in the legacy
+ *      path, so it stays literal text with no bullet / phrase promotion.
+ *      `normalizeRoleSlug` maps the slug back to the phrase key so the non-noun
+ *      specials (`empty-background` → `empty background`) key `roleToPhrase`
+ *      correctly; a custom slug passes through verbatim.
+ *
+ * Existing `@-mention` / variant / mode parsing + the legacy resolvers stay
+ * byte-identical — those suites are the guard.
+ */
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+import { parseLocationMentionToken } from "@nodaro/shared"
+import { normalizeRoleSlug } from "@nodaro/shared"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const kira: ConnectedReference = {
+  id: "k", defaultName: "Kira", source: "wired-character",
+  url: "https://cdn/kira.png", characterSlug: "kira",
+}
+const library: ConnectedReference = {
+  id: "l", defaultName: "Old Library", source: "wired-location",
+  url: "https://cdn/library.png", locationSlug: "old-library",
+}
+
+describe("(A) character custom-role verbatim relaxation — image hybrid", () => {
+  it("PRESET role-only @kira:1:clothes → 'the clothes from reference image A' (pin)", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@kira:1:clothes on a runway",
+      connectedReferences: [kira],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the clothes from reference image A on a runway")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("CUSTOM role @kira:1:earrings → 'the earrings from reference image A' (NOT 'person')", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@kira:1:earrings on a runway",
+      connectedReferences: [kira],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the earrings from reference image A on a runway")
+    expect(out.prompt).not.toContain("the person from reference image A")
+    expect(out.referenceImageUrls).toContain("https://cdn/kira.png")
+  })
+})
+
+describe("(A) character custom-role verbatim relaxation — video hybrid", () => {
+  it("CUSTOM role @kira:1:earrings → 'the earrings from @image_1' (NOT 'person')", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1:earrings spins", wiredCharRefs: [kira], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the earrings from @image_1 spins")
+    expect(out.prompt).not.toContain("the person from @image_1")
+    expect(out.additionalUrls).toContain("https://cdn/kira.png")
+  })
+
+  it("PRESET role @kira:1:face → 'the face from @image_1' (pin, unchanged)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1:face runs", wiredCharRefs: [kira], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the face from @image_1 runs")
+  })
+})
+
+describe("(B) location bare-slug role parsing — image hybrid", () => {
+  it("@old-library:1:background → 'the background from reference image A', token replaced inline", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@old-library:1:background a chase scene",
+      connectedReferences: [library],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the background from reference image A")
+    // Token resolved → no literal slug left behind, no legacy block.
+    expect(out.prompt).not.toContain("@old-library:1:background")
+    expect(out.prompt).not.toContain("Use these locations:")
+    expect(out.referenceImageUrls).toContain("https://cdn/library.png")
+  })
+
+  it("@old-library:1:empty-background → 'the background … (without its foreground objects)'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@old-library:1:empty-background a chase scene",
+      connectedReferences: [library],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain(
+      "the background from reference image A (without its foreground objects)",
+    )
+    expect(out.prompt).not.toContain("@old-library:1:empty-background")
+  })
+
+  it("CUSTOM role @old-library:1:foobar → 'the foobar from reference image A' (verbatim, F2)", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@old-library:1:foobar a chase scene",
+      connectedReferences: [library],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the foobar from reference image A")
+    expect(out.prompt).not.toContain("@old-library:1:foobar")
+    expect(out.prompt).not.toContain("Use these locations:")
+    expect(out.referenceImageUrls).toContain("https://cdn/library.png")
+  })
+})
+
+describe("(B) location parser additive change — direct", () => {
+  it("@old-library:1:background parses as a role (slug stored verbatim)", () => {
+    expect(parseLocationMentionToken("@old-library:1:background")).toEqual({
+      locationSlug: "old-library", imageIndex: 1,
+      bucket: null, variant: null, usageMode: null, role: "background",
+    })
+  })
+
+  it("@old-library:1:empty-background parses as a role (slug form)", () => {
+    expect(parseLocationMentionToken("@old-library:1:empty-background")).toEqual({
+      locationSlug: "old-library", imageIndex: 1,
+      bucket: null, variant: null, usageMode: null, role: "empty-background",
+    })
+  })
+
+  it("real variant @old-library:1:weather/rain still parses as a variant (unchanged, no role)", () => {
+    expect(parseLocationMentionToken("@old-library:1:weather/rain")).toEqual({
+      locationSlug: "old-library", imageIndex: 1,
+      bucket: "weather", variant: "rain", usageMode: null,
+    })
+  })
+
+  it("CUSTOM bare slug @old-library:1:foobar now parses as a role (parser gate removed, F2)", () => {
+    expect(parseLocationMentionToken("@old-library:1:foobar")).toEqual({
+      locationSlug: "old-library", imageIndex: 1,
+      bucket: null, variant: null, usageMode: null, role: "foobar",
+    })
+  })
+
+  it("known mode @old-library:1:layout still parses as a usage mode (unchanged)", () => {
+    expect(parseLocationMentionToken("@old-library:1:layout")).toEqual({
+      locationSlug: "old-library", imageIndex: 1,
+      bucket: null, variant: null, usageMode: "layout",
+    })
+  })
+})
+
+describe("normalizeRoleSlug (slug ↔ phrase key)", () => {
+  it("maps the multi-word location preset slug back to its phrase key", () => {
+    expect(normalizeRoleSlug("empty-background")).toBe("empty background")
+  })
+  it("passes single-token + hyphenated-key roles through unchanged", () => {
+    expect(normalizeRoleSlug("background")).toBe("background")
+    expect(normalizeRoleSlug("as-is")).toBe("as-is")
+  })
+  it("passes free-form custom slugs through unchanged", () => {
+    expect(normalizeRoleSlug("rooftop-view")).toBe("rooftop-view")
+  })
+})
+
+describe("legacy (no referenceFormat) is NOT affected by the relaxation", () => {
+  it("legacy never emits the hybrid role phrase for char or location mentions", () => {
+    const charOut = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@kira:1:earrings poses",
+      connectedReferences: [kira],
+    })
+    expect(charOut.prompt).not.toContain("the earrings from reference image")
+
+    const locOut = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@old-library:1:background scene",
+      connectedReferences: [library],
+    })
+    expect(locOut.prompt).not.toContain("the background from reference image")
+  })
+
+  it("CUSTOM location role @old-library:1:foobar stays LITERAL in legacy (byte-identical, F2)", () => {
+    // The parser now accepts `foobar` as a role, but the legacy resolver's
+    // `if (t.role) continue` guard skips ANY role token (preset or custom): no
+    // inline replacement, no bullet, no `Use these locations:` block — the raw
+    // token survives verbatim exactly as it did pre-Phase-D (parser → null).
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@old-library:1:foobar a chase scene",
+      connectedReferences: [library],
+    })
+    expect(out.prompt).toContain("@old-library:1:foobar")
+    expect(out.prompt).not.toContain("Use these locations:")
+    expect(out.prompt).not.toContain("the foobar from reference image")
+  })
+})

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

@@ -0,0 +1,173 @@
+import { describe, it, expect } from "vitest"
+import { resolveSeedance2Inputs } from "../seedance-2-inputs.js"
+
+describe("resolveSeedance2Inputs", () => {
+  it("first frame only, no references → strict first-frame, no suffix", () => {
+    const r = resolveSeedance2Inputs({ firstFrameUrl: "https://a/first.png" })
+    expect(r.mode).toBe("first-frame")
+    expect(r.firstFrameUrl).toBe("https://a/first.png")
+    expect(r.lastFrameUrl).toBeUndefined()
+    expect(r.referenceImageUrls).toEqual([])
+    expect(r.promptSuffix).toBe("")
+  })
+
+  it("first + last frame, no references → strict first-last-frame", () => {
+    const r = resolveSeedance2Inputs({ firstFrameUrl: "https://a/f.png", lastFrameUrl: "https://a/l.png" })
+    expect(r.mode).toBe("first-last-frame")
+    expect(r.firstFrameUrl).toBe("https://a/f.png")
+    expect(r.lastFrameUrl).toBe("https://a/l.png")
+    expect(r.promptSuffix).toBe("")
+  })
+
+  it("nothing connected → first-frame with no urls, no suffix", () => {
+    const r = resolveSeedance2Inputs({})
+    expect(r.mode).toBe("first-frame")
+    expect(r.firstFrameUrl).toBeUndefined()
+    expect(r.referenceImageUrls).toEqual([])
+    expect(r.promptSuffix).toBe("")
+  })
+
+  it("first frame + one reference image → reference mode, frame appended last, ordinal 2", () => {
+    const r = resolveSeedance2Inputs({ firstFrameUrl: "https://a/first.png", refImageUrls: ["https://a/ref.png"] })
+    expect(r.mode).toBe("reference")
+    expect(r.firstFrameUrl).toBeUndefined()
+    expect(r.lastFrameUrl).toBeUndefined()
+    expect(r.referenceImageUrls).toEqual(["https://a/ref.png", "https://a/first.png"])
+    expect(r.promptSuffix).toBe("Use @image_2 as the opening (first) frame of the video.")
+  })
+
+  it("first + last frame + two reference images → reference, frames at 3 and 4", () => {
+    const r = resolveSeedance2Inputs({
+      firstFrameUrl: "https://a/f.png", lastFrameUrl: "https://a/l.png",
+      refImageUrls: ["https://a/r1.png", "https://a/r2.png"],
+    })
+    expect(r.referenceImageUrls).toEqual(["https://a/r1.png", "https://a/r2.png", "https://a/f.png", "https://a/l.png"])
+    expect(r.promptSuffix).toBe("Use @image_3 as the opening (first) frame and @image_4 as the closing (last) frame of the video.")
+  })
+
+  it("reference audio + first frame (no images/videos) → reference mode, frame as Image 1, audio passed through", () => {
+    const r = resolveSeedance2Inputs({ firstFrameUrl: "https://a/f.png", refAudioUrls: ["https://a/voice.mp3"] })
+    expect(r.mode).toBe("reference")
+    expect(r.referenceImageUrls).toEqual(["https://a/f.png"])
+    expect(r.referenceAudioUrls).toEqual(["https://a/voice.mp3"])
+    expect(r.promptSuffix).toBe("Use @image_1 as the opening (first) frame of the video.")
+  })
+
+  it("last frame only, no first frame, no references → reference, closing-frame hint", () => {
+    const r = resolveSeedance2Inputs({ lastFrameUrl: "https://a/l.png" })
+    expect(r.mode).toBe("reference")
+    expect(r.referenceImageUrls).toEqual(["https://a/l.png"])
+    expect(r.promptSuffix).toBe("Use @image_1 as the closing (last) frame of the video.")
+  })
+
+  it("9 user images + first + last → frames kept, 2 user images dropped, ordinals 8 and 9", () => {
+    const refs = Array.from({ length: 9 }, (_, i) => `https://a/r${i}.png`)
+    const r = resolveSeedance2Inputs({ firstFrameUrl: "https://a/f.png", lastFrameUrl: "https://a/l.png", refImageUrls: refs })
+    expect(r.referenceImageUrls).toHaveLength(9)
+    expect(r.referenceImageUrls[7]).toBe("https://a/f.png")
+    expect(r.referenceImageUrls[8]).toBe("https://a/l.png")
+    expect(r.droppedRefImages).toBe(2)
+    expect(r.promptSuffix).toBe("Use @image_8 as the opening (first) frame and @image_9 as the closing (last) frame of the video.")
+  })
+
+  it("blank/whitespace urls are ignored", () => {
+    const r = resolveSeedance2Inputs({ firstFrameUrl: "   ", refImageUrls: ["", "  ", "https://a/r.png"] })
+    expect(r.mode).toBe("reference")
+    expect(r.referenceImageUrls).toEqual(["https://a/r.png"])
+    expect(r.promptSuffix).toBe("")
+  })
+
+  it("caps reference videos at 3 and audio at 3", () => {
+    const r = resolveSeedance2Inputs({
+      refImageUrls: ["https://a/r.png"],
+      refVideoUrls: ["v1", "v2", "v3", "v4"], refAudioUrls: ["a1", "a2", "a3", "a4"],
+    })
+    expect(r.referenceVideoUrls).toEqual(["v1", "v2", "v3"])
+    expect(r.referenceAudioUrls).toEqual(["a1", "a2", "a3"])
+  })
+
+  // ---------------------------------------------------------------------------
+  // Frame-ordinal ↔ array-position INVARIANT (drift guard).
+  //
+  // The frame `@image_N` numbers the resolver writes into `promptSuffix` must be
+  // the literal 1-based positions of `firstFrameUrl` / `lastFrameUrl` in the
+  // returned `referenceImageUrls`, AND must be strictly greater than the count
+  // of user reference images (frames always come AFTER user refs, never in a
+  // user-ref slot). This locks the resolver's internal numbering so a future
+  // refactor of the append order or suffix wording can't silently desync the
+  // ordinal it tells the model from where the frame actually sits in the array.
+  //
+  // NB: this guards the resolver in ISOLATION. The combined-case interaction
+  // (a @-mentioned character that also fills the i2v start-frame slot while
+  // other refs are present) is covered at the payload-builder + provider seam —
+  // see backend `seedance2-multimodal.test.ts` "combined case" tests.
+  // ---------------------------------------------------------------------------
+  describe("frame-ordinal ↔ array-position invariant", () => {
+    // Parse every `@image_N` ordinal out of the suffix in document order. The
+    // regex tolerates both the `@image_N` form (current) and a legacy `Image N`
+    // form so the invariant holds across the REF_BINDING swap-point flip.
+    const ordinalsIn = (suffix: string): number[] =>
+      Array.from(suffix.matchAll(/@?image[_ ](\d+)/gi)).map((m) => parseInt(m[1], 10))
+
+    const refShapes: Array<{ name: string; refs: string[] }> = [
+      { name: "0 user refs", refs: [] },
+      { name: "1 user ref", refs: ["https://a/u1.png"] },
+      { name: "2 user refs", refs: ["https://a/u1.png", "https://a/u2.png"] },
+    ]
+    const frameShapes: Array<{ name: string; first?: string; last?: string }> = [
+      { name: "first-only", first: "https://a/first.png" },
+      { name: "first+last", first: "https://a/first.png", last: "https://a/last.png" },
+      { name: "last-only", last: "https://a/last.png" },
+    ]
+
+    for (const rs of refShapes) {
+      for (const fs of frameShapes) {
+        it(`${rs.name} × ${fs.name}: suffix ordinals == array positions, all > user-ref count`, () => {
+          const r = resolveSeedance2Inputs({
+            firstFrameUrl: fs.first,
+            lastFrameUrl: fs.last,
+            refImageUrls: rs.refs,
+          })
+
+          // Strict first/last-frame mode (a first frame with NO references) does
+          // not number anything: frames ride `firstFrameUrl`/`lastFrameUrl` and
+          // the suffix is empty. The frame-ordinal invariant is reference-mode
+          // only, so assert the strict-mode contract and stop here.
+          if (r.mode !== "reference") {
+            expect(rs.refs.length).toBe(0)
+            expect(r.referenceImageUrls).toEqual([])
+            expect(r.promptSuffix).toBe("")
+            expect(r.firstFrameUrl).toBe(fs.first)
+            return
+          }
+
+          const userRefCount = rs.refs.length
+          const arr = r.referenceImageUrls
+
+          // 1-based position of each frame URL in the final array (0 = absent).
+          const firstPos = fs.first ? arr.indexOf(fs.first) + 1 : 0
+          const lastPos = fs.last ? arr.indexOf(fs.last) + 1 : 0
+
+          // Every frame URL present must actually be in the array.
+          if (fs.first) expect(firstPos).toBeGreaterThan(0)
+          if (fs.last) expect(lastPos).toBeGreaterThan(0)
+
+          // Frames sit strictly AFTER every user-ref slot (no collision).
+          if (firstPos) expect(firstPos).toBeGreaterThan(userRefCount)
+          if (lastPos) expect(lastPos).toBeGreaterThan(userRefCount)
+
+          // The suffix's `@image_N` ordinals are EXACTLY the array positions, in
+          // the order the suffix names them (first frame before last frame).
+          const expectedOrdinals: number[] = []
+          if (firstPos) expectedOrdinals.push(firstPos)
+          if (lastPos) expectedOrdinals.push(lastPos)
+          expect(ordinalsIn(r.promptSuffix)).toEqual(expectedOrdinals)
+
+          // User refs occupy the first `userRefCount` slots verbatim — frames
+          // never displace them.
+          expect(arr.slice(0, userRefCount)).toEqual(rs.refs)
+        })
+      }
+    }
+  })
+})

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

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest"
+import { PROVIDER_CAPABILITIES } from "../index.js"
+import { EXTEND_VIDEO_PROVIDERS, MODEL_CATALOG, SEEDANCE_2_EXTEND_STITCH, buildVideoCreditModelIdentifier } from "@nodaro/shared"
+
+/**
+ * seedance-2-extend: extend ANY video by URL — bare-template continuation
+ * generation + trim-stitch (spike-validated).
+ */
+describe("seedance-2-extend shared wiring", () => {
+  it("is a registered extend provider", () => {
+    expect(EXTEND_VIDEO_PROVIDERS).toContain("seedance-2-extend")
+  })
+
+  it("catalog entry drives the levers (extend mode, 4-15s, three resolutions)", () => {
+    const m = MODEL_CATALOG["seedance-2-extend"]!
+    expect(m.modes).toEqual(["extend"])
+    expect(m.family).toBe("Bytedance")
+    expect(m.durations).toEqual([4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+    expect(m.resolutions).toEqual(["480p", "720p", "1080p"])
+    expect(m.pricing.length).toBeGreaterThanOrEqual(4)
+    expect(m.pricing[0]!.identifier).toBe("seedance-2-extend")
+  })
+
+  it("stitch constants match the spike-validated recipe (4 tail / 3 head / 0.15s fades)", () => {
+    expect(SEEDANCE_2_EXTEND_STITCH).toEqual({
+      trimTailFrames: 4,
+      trimHeadFrames: 3,
+      audioFadeSec: 0.15,
+    })
+  })
+
+  it("is advertised to the wizard's extend-video capabilities", () => {
+    expect(PROVIDER_CAPABILITIES["extend-video"]!["seedance-2-extend"]).toMatch(/ANY video/i)
+  })
+
+  it("credit identifiers snap to duration tiers with a :res suffix (no -ref dimension)", () => {
+    expect(buildVideoCreditModelIdentifier("seedance-2-extend", 6, undefined, undefined, undefined, "480p"))
+      .toBe("seedance-2-extend:8s:480p") // 6s snaps into the 8s tier
+    expect(buildVideoCreditModelIdentifier("seedance-2-extend", 4, undefined, undefined, undefined, "720p"))
+      .toBe("seedance-2-extend:4s:720p")
+    expect(buildVideoCreditModelIdentifier("seedance-2-extend", 15, undefined, undefined, undefined, "1080p"))
+      .toBe("seedance-2-extend:15s:1080p")
+  })
+})