@nodaro/prompts 1.0.1

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

@@ -0,0 +1,350 @@
+import { describe, it, expect } from "vitest"
+import {
+  composeSoundHintFromConnections,
+  type SoundComposition,
+} from "../sound-aggregator.js"
+import type { HintGraphContext, HintNodeLike, HintEdgeLike } from "../parameter-prompt-hint.js"
+
+function ctx(nodes: HintNodeLike[], edges: HintEdgeLike[]): HintGraphContext {
+  return { nodes, edges }
+}
+
+const sunoConsumer = (data: Record<string, unknown> = {}): HintNodeLike => ({
+  id: "consumer", type: "suno-generate", data,
+})
+
+function audioStyleEdge(sourceId: string): HintEdgeLike {
+  return { source: sourceId, target: "consumer", sourceHandle: "out", targetHandle: "audio-style" }
+}
+
+function voiceEdge(sourceId: string): HintEdgeLike {
+  return { source: sourceId, target: "consumer", sourceHandle: "out", targetHandle: "voice" }
+}
+
+describe("composeSoundHintFromConnections — empty cases", () => {
+  it("returns empty composition with no edges", () => {
+    const out = composeSoundHintFromConnections(sunoConsumer(), "suno-generate", ctx([], []))
+    expect(out.text).toBe("")
+    expect(out.fields).toEqual({})
+    expect(out.warnings).toEqual([])
+  })
+
+  it("ignores edges that don't target audio-style", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer(),
+      "suno-generate",
+      ctx(
+        [{ id: "src", type: "music-genre", data: { genre: "electronic" } }],
+        [{ source: "src", target: "consumer", targetHandle: "in" }],
+      ),
+    )
+    expect(out.text).toBe("")
+  })
+})
+
+describe("composeSoundHintFromConnections — Suno Generate", () => {
+  it("composes music nodes into text", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: true }),
+      "suno-generate",
+      ctx(
+        [
+          { id: "g", type: "music-genre", data: { genre: "electronic", subgenre: "synthwave" } },
+          { id: "m", type: "music-mood", data: { energy: "high", emotion: "triumphant" } },
+        ],
+        [audioStyleEdge("g"), audioStyleEdge("m")],
+      ),
+    )
+    expect(out.text).toContain("synthwave")
+    expect(out.text).toContain("triumphant")
+    expect(out.warnings).toEqual([])
+  })
+
+  it("accepts voice-character nodes (Suno V5 supports vocal description)", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: true }),
+      "suno-generate",
+      ctx(
+        [{ id: "v", type: "voice-character", data: { timbre: "warm", gender: "female", accent: "british-rp" } }],
+        [audioStyleEdge("v")],
+      ),
+    )
+    expect(out.text).toContain("warm")
+    expect(out.warnings).toEqual([])
+  })
+
+  it("extracts voice-character.gender → fields.vocalGender (male)", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: true }),
+      "suno-generate",
+      ctx(
+        [{ id: "v", type: "voice-character", data: { gender: "male", timbre: "deep" } }],
+        [audioStyleEdge("v")],
+      ),
+    )
+    expect(out.fields.vocalGender).toBe("male")
+  })
+
+  it("extracts voice-character.gender → fields.vocalGender (female)", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: true }),
+      "suno-generate",
+      ctx(
+        [{ id: "v", type: "voice-character", data: { gender: "female" } }],
+        [audioStyleEdge("v")],
+      ),
+    )
+    expect(out.fields.vocalGender).toBe("female")
+  })
+
+  it("does NOT extract vocalGender for androgynous (Suno's field is binary)", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: true }),
+      "suno-generate",
+      ctx(
+        [{ id: "v", type: "voice-character", data: { gender: "androgynous", timbre: "warm" } }],
+        [audioStyleEdge("v")],
+      ),
+    )
+    expect(out.fields.vocalGender).toBeUndefined()
+    // Text still includes the description
+    expect(out.text).toContain("warm")
+  })
+
+  it("composes mixed music + voice nodes for Suno", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: false }),
+      "suno-generate",
+      ctx(
+        [
+          { id: "g", type: "music-genre", data: { genre: "rock" } },
+          { id: "v", type: "voice-character", data: { gender: "male", timbre: "raspy" } },
+          { id: "d", type: "voice-delivery", data: { emotion: "intense" } },
+        ],
+        [audioStyleEdge("g"), audioStyleEdge("v"), audioStyleEdge("d")],
+      ),
+    )
+    expect(out.text).toMatch(/rock|raspy/)
+    expect(out.fields.vocalGender).toBe("male")
+    expect(out.warnings).toEqual([])
+  })
+})
+
+// Regression: the typed-handle split gave suno-generate three pips
+// (prompt / audio-style / voice). A descriptive voice-character picker dropped
+// onto the "Voice" pip must STILL fold into the output — before, suno had one
+// picker handle and "any picker, any pip" worked. The voice pip's persona
+// producers (suno-voice / voice-design) carry no prompt hint, so they're
+// skipped here and still route to personaId via the input-resolver.
+describe("composeSoundHintFromConnections — Suno Generate, voice pip", () => {
+  it("folds a voice-character picker wired to the VOICE handle (not just audio-style)", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: false }),
+      "suno-generate",
+      ctx(
+        [{ id: "v", type: "voice-character", data: { timbre: "warm", gender: "female", accent: "british-rp" } }],
+        [voiceEdge("v")],
+      ),
+    )
+    expect(out.text).toContain("warm")
+    expect(out.fields.vocalGender).toBe("female")
+  })
+
+  it("collects pickers from audio-style AND voice pips together", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: false }),
+      "suno-generate",
+      ctx(
+        [
+          { id: "g", type: "music-genre", data: { genre: "electronic", subgenre: "synthwave" } },
+          { id: "v", type: "voice-character", data: { timbre: "raspy", gender: "male" } },
+        ],
+        [audioStyleEdge("g"), voiceEdge("v")],
+      ),
+    )
+    expect(out.text).toContain("synthwave")
+    expect(out.text).toContain("raspy")
+    expect(out.fields.vocalGender).toBe("male")
+  })
+
+  it("ignores a suno-voice persona on the voice pip (no hint, no crash)", () => {
+    const out = composeSoundHintFromConnections(
+      sunoConsumer({ customMode: false }),
+      "suno-generate",
+      ctx(
+        [{ id: "p", type: "suno-voice", data: { voiceId: "abc", personaModel: "voice_persona" } }],
+        [voiceEdge("p")],
+      ),
+    )
+    expect(out.text).toBe("")
+    expect(out.warnings).toEqual([])
+  })
+})
+
+describe("composeSoundHintFromConnections — Generate Music (MiniMax)", () => {
+  const minimaxConsumer = (data: Record<string, unknown> = { provider: "minimax" }): HintNodeLike => ({
+    id: "consumer", type: "generate-music", data,
+  })
+
+  it("populates typed fields when provider=minimax", () => {
+    const out = composeSoundHintFromConnections(
+      minimaxConsumer(),
+      "generate-music",
+      ctx(
+        [
+          { id: "g", type: "music-genre", data: { genre: "electronic" } },
+          { id: "m", type: "music-mood", data: { emotion: "triumphant" } },
+          { id: "i", type: "instrumentation", data: { vocalPresence: "instrumental" } },
+        ],
+        [audioStyleEdge("g"), audioStyleEdge("m"), audioStyleEdge("i")],
+      ),
+    )
+    expect(out.fields?.genre).toBeTruthy()
+    expect(out.fields?.mood).toBeTruthy()
+    expect(out.fields?.instrumental).toBe(true)
+  })
+
+  it("falls back to prompt-only for non-minimax providers", () => {
+    const out = composeSoundHintFromConnections(
+      { id: "consumer", type: "generate-music", data: { provider: "musicgen" } },
+      "generate-music",
+      ctx(
+        [{ id: "g", type: "music-genre", data: { genre: "electronic" } }],
+        [audioStyleEdge("g")],
+      ),
+    )
+    expect(out.fields?.genre).toBeUndefined()
+    expect(out.text).toContain("electronic")
+  })
+
+  it("accepts voice nodes (music with vocals benefits from voice description)", () => {
+    const out = composeSoundHintFromConnections(
+      minimaxConsumer(),
+      "generate-music",
+      ctx(
+        [{ id: "v", type: "voice-character", data: { gender: "female", timbre: "smooth" } }],
+        [audioStyleEdge("v")],
+      ),
+    )
+    expect(out.text).toContain("smooth")
+    expect(out.fields.vocalGender).toBe("female")
+    expect(out.warnings).toEqual([])
+  })
+})
+
+describe("composeSoundHintFromConnections — Voice Design", () => {
+  const voiceConsumer: HintNodeLike = { id: "consumer", type: "voice-design", data: {} }
+
+  it("composes voice nodes into voiceDescription", () => {
+    const out = composeSoundHintFromConnections(
+      voiceConsumer,
+      "voice-design",
+      ctx(
+        [
+          { id: "vc", type: "voice-character", data: { age: "middle-aged", gender: "male", timbre: "warm" } },
+          { id: "vd", type: "voice-delivery", data: { archetype: "documentary-narrator", emotion: "reassuring" } },
+        ],
+        [audioStyleEdge("vc"), audioStyleEdge("vd")],
+      ),
+    )
+    expect(out.text).toContain("warm")
+    expect(out.text).toContain("documentary narrator")
+    expect(out.fields?.voiceDescription).toBe(out.text)
+  })
+
+  it("warns on music nodes", () => {
+    const out = composeSoundHintFromConnections(
+      voiceConsumer,
+      "voice-design",
+      ctx(
+        [{ id: "g", type: "music-genre", data: { genre: "electronic" } }],
+        [audioStyleEdge("g")],
+      ),
+    )
+    expect(out.warnings.length).toBeGreaterThan(0)
+  })
+})
+
+describe("composeSoundHintFromConnections — Voice Remix", () => {
+  const remixConsumer: HintNodeLike = { id: "consumer", type: "voice-remix", data: {} }
+
+  it("composes voice nodes into voiceDescription (mirrors voice-design)", () => {
+    const out = composeSoundHintFromConnections(
+      remixConsumer,
+      "voice-remix",
+      ctx(
+        [
+          { id: "vc", type: "voice-character", data: { age: "young-adult", gender: "female", timbre: "bright" } },
+          { id: "vd", type: "voice-delivery", data: { archetype: "friendly-host" } },
+        ],
+        [audioStyleEdge("vc"), audioStyleEdge("vd")],
+      ),
+    )
+    expect(out.text).toContain("bright")
+    expect(out.fields.voiceDescription).toBe(out.text)
+    expect(out.warnings).toEqual([])
+  })
+
+  it("warns on music nodes (Voice Remix is voice-only)", () => {
+    const out = composeSoundHintFromConnections(
+      remixConsumer,
+      "voice-remix",
+      ctx(
+        [{ id: "g", type: "music-genre", data: { genre: "electronic" } }],
+        [audioStyleEdge("g")],
+      ),
+    )
+    expect(out.text).toBe("")
+    expect(out.warnings.length).toBeGreaterThan(0)
+    expect(out.warnings[0]).toContain("Voice Remix")
+  })
+})
+
+describe("composeSoundHintFromConnections — minimax multi-emotion", () => {
+  const minimaxConsumer = (): HintNodeLike => ({
+    id: "consumer", type: "generate-music", data: { provider: "minimax" },
+  })
+
+  it("joins multiple emotions into fields.mood for minimax", () => {
+    const out = composeSoundHintFromConnections(
+      minimaxConsumer(),
+      "generate-music",
+      ctx(
+        [{ id: "m", type: "music-mood", data: { emotion: ["bittersweet", "mysterious"] } }],
+        [audioStyleEdge("m")],
+      ),
+    )
+    expect(out.fields.mood).toContain("bittersweet")
+    expect(out.fields.mood).toContain("mysterious")
+  })
+
+  it("handles single-string emotion for minimax (back-compat)", () => {
+    const out = composeSoundHintFromConnections(
+      minimaxConsumer(),
+      "generate-music",
+      ctx(
+        [{ id: "m", type: "music-mood", data: { emotion: "ethereal" } }],
+        [audioStyleEdge("m")],
+      ),
+    )
+    expect(out.fields.mood).toContain("ethereal")
+  })
+})
+
+describe("composeSoundHintFromConnections — Text to Audio", () => {
+  it("accepts music nodes, warns on voice nodes", () => {
+    const out = composeSoundHintFromConnections(
+      { id: "consumer", type: "text-to-audio", data: {} },
+      "text-to-audio",
+      ctx(
+        [
+          { id: "g", type: "music-genre", data: { genre: "electronic" } },
+          { id: "v", type: "voice-character", data: { timbre: "warm" } },
+        ],
+        [audioStyleEdge("g"), audioStyleEdge("v")],
+      ),
+    )
+    expect(out.text).toContain("electronic")
+    expect(out.warnings.length).toBeGreaterThan(0)
+  })
+})

package/src/__tests__/style-presets.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest"
+import { STYLE_PRESETS, getStylePreset } from "../style-presets.js"
+
+describe("STYLE_PRESETS", () => {
+  it("has a non-trivial catalog", () => {
+    expect(STYLE_PRESETS.length).toBeGreaterThanOrEqual(8)
+  })
+
+  it("every preset has a unique id", () => {
+    const ids = STYLE_PRESETS.map((s) => s.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it("every preset carries usable conditioning + a label + a swatch", () => {
+    for (const s of STYLE_PRESETS) {
+      expect(s.label.length, `${s.id} label`).toBeGreaterThan(0)
+      expect(s.swatch, `${s.id} swatch`).toMatch(/gradient|#/)
+      // visualStyle is the load-bearing directive that conditions generation.
+      expect(s.directives.visualStyle?.length ?? 0, `${s.id} visualStyle`).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe("getStylePreset", () => {
+  it("resolves a known id", () => {
+    expect(getStylePreset("cinematic")?.label).toBe("Cinematic Photography")
+  })
+
+  it("returns undefined for the Auto / empty / unknown case", () => {
+    expect(getStylePreset(undefined)).toBeUndefined()
+    expect(getStylePreset("")).toBeUndefined()
+    expect(getStylePreset("does-not-exist")).toBeUndefined()
+  })
+})

package/src/__tests__/temporal-multi.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest"
+import { buildTemporalHints, TEMPORAL_FIELD_BY_CATEGORY, TEMPORAL_CATEGORY_ORDER } from "../temporal.js"
+
+describe("buildTemporalHints", () => {
+  it("returns empty when nothing is set", () => {
+    const hints = buildTemporalHints({})
+    expect(hints).toEqual([])
+  })
+
+  it("emits one hint per set per-category field, in canonical category order", () => {
+    const hints = buildTemporalHints({
+      temporalSpeed: "slow-motion",
+      temporalFreeze: "bullet-time",
+      temporalDirection: "reverse",
+      temporalShutter: "long-exposure",
+    })
+    expect(hints.length).toBe(4)
+    // Canonical order: speed, freeze, direction, shutter
+    expect(hints[0]).toMatch(/slow motion/i)
+    expect(hints[1]).toMatch(/bullet time/i)
+    expect(hints[2]).toMatch(/reverse/i)
+    expect(hints[3]).toMatch(/long exposure/i)
+  })
+
+  it("ignores the legacy temporal field — multi-category is the sole shape", () => {
+    // Legacy compat layer was removed: the legacy `temporal` field is no
+    // longer read; only per-category fields are considered.
+    const hints = buildTemporalHints({ temporal: "slow-motion" } as Record<string, unknown>)
+    expect(hints).toEqual([])
+  })
+
+  it("ignores empty-string and non-string values", () => {
+    const hints = buildTemporalHints({
+      temporalSpeed: "",
+      temporalFreeze: undefined,
+      temporalDirection: null as unknown as string,
+      temporalShutter: "motion-blur",
+    })
+    expect(hints.length).toBe(1)
+    expect(hints[0]).toMatch(/motion blur/i)
+  })
+
+  it("TEMPORAL_FIELD_BY_CATEGORY covers all categories in order", () => {
+    for (const cat of TEMPORAL_CATEGORY_ORDER) {
+      expect(TEMPORAL_FIELD_BY_CATEGORY[cat]).toBeDefined()
+    }
+  })
+
+  it("TEMPORAL_FIELD_BY_CATEGORY maps each category to the expected field name", () => {
+    expect(TEMPORAL_FIELD_BY_CATEGORY.speed).toBe("temporalSpeed")
+    expect(TEMPORAL_FIELD_BY_CATEGORY.freeze).toBe("temporalFreeze")
+    expect(TEMPORAL_FIELD_BY_CATEGORY.direction).toBe("temporalDirection")
+    expect(TEMPORAL_FIELD_BY_CATEGORY.shutter).toBe("temporalShutter")
+  })
+
+  it("returns empty when an unknown temporal id is given (no hint string)", () => {
+    const hints = buildTemporalHints({ temporalSpeed: "this-is-not-a-real-id" })
+    expect(hints).toEqual([])
+  })
+
+  it("aggregates all 4 categories with the correct prompt-hint substrings", () => {
+    const hints = buildTemporalHints({
+      temporalSpeed: "time-lapse",
+      temporalFreeze: "frozen-subject",
+      temporalDirection: "loop-boomerang",
+      temporalShutter: "stop-motion",
+    })
+    expect(hints.length).toBe(4)
+    expect(hints[0]).toMatch(/time-lapse/i)
+    expect(hints[1]).toMatch(/frozen subject/i)
+    expect(hints[2]).toMatch(/boomerang/i)
+    expect(hints[3]).toMatch(/stop-motion/i)
+  })
+})

package/src/__tests__/transitions.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest"
+import { TRANSITIONS, TRANSITION_IDS, TRANSITION_CATEGORY_ORDER, TRANSITION_CATEGORY_LABELS, composeTransitionHintFromConnections, getTransition, getTransitionLabel, getTransitionPromptHint } from "../transitions.js"
+
+describe("transitions catalog", () => {
+  it("ships 76 unique entries", () => {
+    expect(TRANSITIONS).toHaveLength(76)
+    expect(new Set(TRANSITION_IDS).size).toBe(76)
+  })
+
+  it("every entry has a non-empty id, label, and description", () => {
+    for (const t of TRANSITIONS) {
+      expect(t.id).toMatch(/^[a-z][a-z0-9-]*$/)
+      expect(t.label.length).toBeGreaterThan(0)
+      expect(t.description.length).toBeGreaterThan(0)
+    }
+  })
+
+  it("category counts match the spec §3.3 table", () => {
+    const counts: Record<string, number> = {}
+    for (const t of TRANSITIONS) {
+      counts[t.category] = (counts[t.category] ?? 0) + 1
+    }
+    expect(counts).toEqual({
+      standard: 11, time: 8, element: 14, morph: 9,
+      portal: 10, physics: 9, light: 8, glitch: 7,
+    })
+  })
+
+  it("category order covers every category and matches labels", () => {
+    expect(new Set(TRANSITION_CATEGORY_ORDER)).toEqual(
+      new Set(Object.keys(TRANSITION_CATEGORY_LABELS)),
+    )
+  })
+
+  it("auto has empty promptHint by design", () => {
+    expect(getTransitionPromptHint("auto")).toBe("")
+  })
+
+  it("none has a hard-cut promptHint (not empty)", () => {
+    expect(getTransitionPromptHint("none")).toBe(
+      "no transition, hard cut, instantaneous switch from first shot to second shot",
+    )
+  })
+})
+
+describe("getTransition / getTransitionLabel / getTransitionPromptHint", () => {
+  it("returns the entry for a known id", () => {
+    const t = getTransition("cross-dissolve")
+    expect(t?.label).toBe("Cross-Dissolve")
+  })
+
+  it("returns undefined for nullish + unknown ids", () => {
+    expect(getTransition(undefined)).toBeUndefined()
+    expect(getTransition(null)).toBeUndefined()
+    expect(getTransition("nonexistent")).toBeUndefined()
+  })
+
+  it("getTransitionLabel falls back to title-cased id when unknown", () => {
+    expect(getTransitionLabel("nonexistent-id")).toBe("Nonexistent Id")
+  })
+
+  it("getTransitionPromptHint returns the hint or empty string", () => {
+    expect(getTransitionPromptHint("cross-dissolve")).toContain("cross-dissolve")
+    expect(getTransitionPromptHint("nonexistent")).toBe("")
+  })
+
+  it("getTransitionLabel returns empty string for null/undefined", () => {
+    expect(getTransitionLabel(null)).toBe("")
+    expect(getTransitionLabel(undefined)).toBe("")
+  })
+})
+
+describe("composeTransitionHintFromConnections — single-pick", () => {
+  it("returns the bare hint when no connections + no timing", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", [], [])
+    expect(r).toBe(getTransitionPromptHint("cross-dissolve"))
+  })
+
+  it("returns empty when id is undefined / 'auto' / unknown", () => {
+    expect(composeTransitionHintFromConnections(undefined, ["A"], ["B"])).toBe("")
+    expect(composeTransitionHintFromConnections("unknown-id", ["A"], ["B"])).toBe("")
+    expect(composeTransitionHintFromConnections("auto", ["A"], ["B"])).toBe("")
+  })
+
+  it("treats null like undefined (falsy guard)", () => {
+    // Persisted workflow JSON can deliver null at runtime even though the signature is undefined-only.
+    expect(composeTransitionHintFromConnections(null as unknown as undefined, ["A"], ["B"])).toBe("")
+  })
+
+  it("appends start clause", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", ["morning"], [])
+    expect(r).toMatch(/, starting from morning$/)
+  })
+
+  it("appends end clause", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", [], ["night"])
+    expect(r).toMatch(/, ending at night$/)
+  })
+
+  it("joins multiple start hints with ' and '", () => {
+    const r = composeTransitionHintFromConnections(
+      "cross-dissolve",
+      ["A", "C"],
+      ["B"],
+    )
+    expect(r).toMatch(/, starting from A and C, ending at B$/)
+  })
+})
+
+describe("composeTransitionHintFromConnections — timing clauses", () => {
+  it("appends position clause when non-auto", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", [], [], { position: "end" })
+    expect(r).toContain("the transition occurs at the end of the clip")
+  })
+
+  it("appends duration clause when non-auto", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", [], [], { duration: "medium" })
+    expect(r).toContain("lasting approximately 2 seconds")
+  })
+
+  it("appends intensity clause when non-auto", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", [], [], { intensity: "dynamic" })
+    expect(r).toContain("with dynamic energy and assertive flourish")
+  })
+
+  it("omits clause when value is 'auto'", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", [], [], { position: "auto" })
+    expect(r).not.toContain("the transition occurs")
+  })
+
+  it("appends all three timing clauses in position/duration/intensity order", () => {
+    const r = composeTransitionHintFromConnections(
+      "cross-dissolve",
+      [],
+      [],
+      { position: "end", duration: "medium", intensity: "dynamic" },
+    )
+    const idxPos = r.indexOf("the transition occurs")
+    const idxDur = r.indexOf("lasting approximately")
+    const idxInt = r.indexOf("with dynamic energy")
+    expect(idxPos).toBeGreaterThan(0)
+    expect(idxDur).toBeGreaterThan(idxPos)
+    expect(idxInt).toBeGreaterThan(idxDur)
+  })
+
+  it("composes timing + start + end together in spec §4.2 order", () => {
+    const r = composeTransitionHintFromConnections(
+      "fast-forward-day-night",
+      ["warm golden morning light"],
+      ["deep blue moonlit night"],
+      { position: "end", duration: "medium", intensity: "dynamic" },
+    )
+    expect(r).toContain("the transition occurs at the end of the clip")
+    expect(r).toContain("lasting approximately 2 seconds")
+    expect(r).toContain("with dynamic energy and assertive flourish")
+    expect(r).toContain("starting from warm golden morning light")
+    expect(r).toMatch(/, ending at deep blue moonlit night$/)
+  })
+})
+
+describe("composeTransitionHintFromConnections — multi-pick", () => {
+  it("scalar form is identical to single-element array", () => {
+    const scalar = composeTransitionHintFromConnections("smash-cut", [], [])
+    const array  = composeTransitionHintFromConnections(["smash-cut"], [], [])
+    expect(scalar).toBe(array)
+  })
+
+  it("joins two base hints with ', and '", () => {
+    const r = composeTransitionHintFromConnections(["smash-cut", "white-flash"], [], [])
+    const a = getTransitionPromptHint("smash-cut")
+    const b = getTransitionPromptHint("white-flash")
+    expect(r).toBe(`${a}, and ${b}`)
+  })
+
+  it("dedupes duplicate ids", () => {
+    const r1 = composeTransitionHintFromConnections(["smash-cut", "smash-cut"], [], [])
+    const r2 = composeTransitionHintFromConnections("smash-cut", [], [])
+    expect(r1).toBe(r2)
+  })
+
+  it("caps at 2 ids — extra ids dropped", () => {
+    const a = getTransitionPromptHint("smash-cut")
+    const b = getTransitionPromptHint("white-flash")
+    const r = composeTransitionHintFromConnections(
+      ["smash-cut", "white-flash", "fade-to-black", "wipe"],
+      [],
+      [],
+    )
+    expect(r).toBe(`${a}, and ${b}`)
+  })
+
+  it("returns '' on empty array", () => {
+    expect(composeTransitionHintFromConnections([], [], [])).toBe("")
+  })
+
+  it("filters out 'auto' (empty hint) entries silently", () => {
+    const onlyFade = composeTransitionHintFromConnections("fade-to-black", [], [])
+    const withAuto = composeTransitionHintFromConnections(["auto", "fade-to-black"], [], [])
+    expect(withAuto).toBe(onlyFade)
+  })
+
+  it("applies timing + start/end clauses once at the outer layer (not per-id)", () => {
+    const r = composeTransitionHintFromConnections(
+      ["smash-cut", "white-flash"],
+      ["morning"],
+      ["night"],
+      { intensity: "dynamic" },
+    )
+    expect((r.match(/with dynamic energy/g) ?? []).length).toBe(1)
+    expect(r.indexOf("with dynamic energy")).toBeGreaterThan(r.indexOf(", and "))
+    expect(r.indexOf("starting from morning")).toBeGreaterThan(r.indexOf("with dynamic energy"))
+  })
+})