@nodaro/prompts 1.21.0 → 1.25.0

package/src/__tests__/parameter-hint-mode.test.ts

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs"
 
 import { getParameterPromptHint } from "../parameter-prompt-hint.js"
 import { PICKER_CATALOGS, type PickerCatalog, type PickerOption } from "../picker-catalogs.js"
+import { renderTransitionBases } from "../transitions.js"
 import type { HintGraphContext, HintNodeLike } from "@nodaro/shared"
 
 /**
@@ -145,6 +146,15 @@ describe("hint mode: compact injects the term instead of the promptHint", () =>
     const compact = getParameterPromptHint(node)
     const full = getParameterPromptHint(withMode(node, "full"))
 
+    // A transition only ever reaches a VIDEO prompt, where it renders as
+    // `term (hint)` in BOTH modes — the bare term did not steer the model
+    // (see `renderTransitionBases`). The mode is deliberately inert there.
+    if (probe.nodeType === "transition") {
+      expect(compact).toBe(full)
+      expect(compact.startsWith(`${probe.option.term} (`)).toBe(true)
+      return
+    }
+
     expect(compact).toContain(probe.option.term)
     expect(full).toContain(probe.option.promptHint)
     if (probe.shortens) {
@@ -170,7 +180,7 @@ describe("hint mode: compact preserves everything but the base fragment", () =>
     expect(compact.length).toBeLessThan(full.length)
   })
 
-  it("transition timing clauses are emitted identically in compact mode", () => {
+  it("transition clauses are emitted identically in compact mode", () => {
     const data = {
       transition: "cross-dissolve",
       position: "middle",
@@ -181,8 +191,8 @@ describe("hint mode: compact preserves everything but the base fragment", () =>
     expect(compact).toContain("the transition occurs in the middle of the clip")
     expect(compact).toContain("lasting approximately 1 second")
     expect(compact).toContain("with dynamic energy and assertive flourish")
-    expect(compact).toContain("cross-dissolve")
-    expect(compact.length).toBeLessThan(getParameterPromptHint({ id: "n1", type: "transition", data }).length)
+    expect(compact).toContain("cross-dissolve (")
+    expect(compact).toBe(getParameterPromptHint({ id: "n1", type: "transition", data }))
   })
 
   it("character-fx timing clauses are emitted identically in compact mode", () => {
@@ -256,7 +266,7 @@ describe("hint mode: compact preserves everything but the base fragment", () =>
     expect(compact).toBe(term)
   })
 
-  it("multi-pick joins the TERMS with the same ', and ' separator", () => {
+  it("transition multi-pick joins each `term (hint)` with the same ', and ' separator", () => {
     const options = registeredOptions("transition").filter((o) => o.promptHint.length > 0)
     const [a, b] = options
     const compact = getParameterPromptHint({
@@ -264,7 +274,9 @@ describe("hint mode: compact preserves everything but the base fragment", () =>
       type: "transition",
       data: { transition: [a.id, b.id], hintMode: "compact" },
     })
-    expect(compact).toBe(`${a.term}, and ${b.term}`)
+    expect(compact).toBe(renderTransitionBases([a.id, b.id]).join(", and "))
+    expect(compact.startsWith(`${a.term} (`)).toBe(true)
+    expect(compact).toContain(`, and ${b.term} (`)
   })
 
   it("multi-dimension composition still walks every dimension", () => {

package/src/__tests__/prompt-style-section.test.ts

@@ -27,7 +27,7 @@ import { getCameraFormatPromptHint } from "../camera-format.js"
 import { getFramingPromptHint } from "../framing.js"
 import { getLightingPromptHint } from "../lighting.js"
 import { getCameraMotionTerm } from "../camera-motions.js"
-import { getTransitionTerm } from "../transitions.js"
+import { renderTransitionBases } from "../transitions.js"
 
 /**
  * THE `[style]` SECTION CONTRACT, at the level it is defined: clauses in, one
@@ -97,7 +97,7 @@ describe("partitionStyleClauses — which slot a clause lands in", () => {
       ).map((c) => [c.text, c.slot]),
     )
     expect(slots.get(getCameraMotionTerm(CAMERA_MOTION))).toBe("body")
-    expect(slots.get(getTransitionTerm(TRANSITION))).toBe("body")
+    expect(slots.get(renderTransitionBases([TRANSITION])[0])).toBe("body")
     expect(slots.get(getStylePromptHint(STYLE))).toBe("film")
     expect(slots.get(getFramingPromptHint(SHOT_SIZE))).toBe("scene")
   })

package/src/__tests__/transitions-instant.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it } from "vitest"
+import {
+  INSTANT_CUT_CLAUSE,
+  TRANSITIONS,
+  TRANSITION_DURATIONS,
+  TRANSITION_INTENSITIES,
+  composeTransitionHintFromConnections,
+  getTransitionPromptHint,
+  getTransitionTerm,
+  isInstantTransition,
+  renderTransitionBases,
+} from "../transitions.js"
+import { getPickerCatalog } from "../picker-catalogs.js"
+import { VIDEO_HINT_MODE_DEFAULT, renderDirectionHints } from "../direction-registry.js"
+import { composeVideoPromptText } from "../assemble-video-input.js"
+
+/**
+ * F5 (transition QA, 2026-09-22): a duration clause on a cut ("match cut, …,
+ * lasting approximately 1 second") made the video model render a 1.75 s
+ * dissolve. Rows whose mechanism IS a cut carry `instant: true`, and the
+ * composer drops the duration lever for them.
+ */
+const INSTANT_IDS = [
+  "none",
+  "snap-to-black",
+  "match-cut",
+  "smash-cut",
+  "seamless-match",
+  "jump-cut",
+  "jump-match",
+  "action-relay",
+]
+
+const DURATION_HINTS = TRANSITION_DURATIONS.map((d) => d.promptHint).filter((h) => h.length > 0)
+const INTENSITY_HINTS = TRANSITION_INTENSITIES.map((d) => d.promptHint).filter((h) => h.length > 0)
+
+describe("instant transitions — the catalog marker", () => {
+  it("marks exactly the cut rows", () => {
+    expect(TRANSITIONS.filter((t) => t.instant).map((t) => t.id).sort()).toEqual([...INSTANT_IDS].sort())
+  })
+
+  it("isInstantTransition answers per id, and false for unknown / auto / empty", () => {
+    for (const id of INSTANT_IDS) expect(isInstantTransition(id)).toBe(true)
+    expect(isInstantTransition("cross-dissolve")).toBe(false)
+    expect(isInstantTransition("whip-pan")).toBe(false)
+    expect(isInstantTransition("freeze-frame-jump")).toBe(false)
+    expect(isInstantTransition("auto")).toBe(false)
+    expect(isInstantTransition("nonexistent")).toBe(false)
+    expect(isInstantTransition("")).toBe(false)
+    expect(isInstantTransition(undefined)).toBe(false)
+    expect(isInstantTransition(null)).toBe(false)
+    expect(isInstantTransition([])).toBe(false)
+  })
+
+  it("a multi-pick is instant only when every id is", () => {
+    expect(isInstantTransition(["match-cut", "smash-cut"])).toBe(true)
+    expect(isInstantTransition(["match-cut", "cross-dissolve"])).toBe(false)
+  })
+})
+
+describe("instant transitions — the composer drops the duration lever", () => {
+  for (const mode of ["full", "compact"] as const) {
+    it(`${mode}: no duration clause on any instant row, for every duration`, () => {
+      for (const id of INSTANT_IDS) {
+        for (const d of TRANSITION_DURATIONS) {
+          const r = composeTransitionHintFromConnections(id, [], [], { duration: d.id }, mode)
+          for (const hint of DURATION_HINTS) expect(r).not.toContain(hint)
+        }
+      }
+    })
+
+    it(`${mode}: no intensity clause on any instant row, for every intensity`, () => {
+      for (const id of INSTANT_IDS) {
+        for (const i of TRANSITION_INTENSITIES) {
+          const r = composeTransitionHintFromConnections(id, [], [], { intensity: i.id }, mode)
+          for (const hint of INTENSITY_HINTS) expect(r).not.toContain(hint)
+        }
+      }
+    })
+
+    it(`${mode}: position still applies to a cut`, () => {
+      const r = composeTransitionHintFromConnections(
+        "match-cut", [], [], { position: "middle", duration: "short", intensity: "natural" }, mode,
+      )
+      expect(r).toContain("the transition occurs in the middle of the clip")
+      expect(r).not.toContain("unhurried")
+      expect(r).not.toContain("lasting approximately")
+    })
+  }
+
+  it("compact match cut reads term (hint; anti-blend clause) + position only", () => {
+    expect(
+      composeTransitionHintFromConnections(
+        "match-cut", [], [], { position: "middle", duration: "short", intensity: "natural" }, "compact",
+      ),
+    ).toBe(
+      "match cut (the final composition of the first shot matches the opening composition of the second shot " +
+      `in shape, color, and motion, so the cut feels like a visual rhyme; ${INSTANT_CUT_CLAUSE}), ` +
+      "the transition occurs in the middle of the clip",
+    )
+  })
+
+  it("a non-instant row keeps its duration", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", [], [], { duration: "short" })
+    expect(r).toContain("lasting approximately 1 second")
+  })
+
+  it("a mixed pick keeps its duration — the non-cut still has a length", () => {
+    const r = composeTransitionHintFromConnections(["match-cut", "ink-splash"], [], [], { duration: "short" })
+    expect(r).toContain("lasting approximately 1 second")
+  })
+
+  it("a no-op 'auto' beside a cut does not make the pick non-instant", () => {
+    const r = composeTransitionHintFromConnections(["auto", "smash-cut"], [], [], { duration: "long" })
+    expect(r).not.toContain("lasting approximately")
+    expect(r).toContain(INSTANT_CUT_CLAUSE)
+  })
+})
+
+/**
+ * Transition QA, 2026-09-24 (seedance-2-5, prod): the bare term "match cut,
+ * with natural unhurried timing" still rendered as a ~1 s dissolve. Every
+ * transition in a video prompt now reads `<term> (<hint body>)`, and an
+ * all-instant pick carries the anti-blend clause inside its parentheses.
+ */
+describe("transitions in a video prompt — `term (hint)`", () => {
+  const LEVERS = { duration: "short", intensity: "natural" } as const
+
+  it("the six A/B strings (compact, short + natural levers)", () => {
+    const c = (id: string) => composeTransitionHintFromConnections(id, [], [], LEVERS, "compact")
+    expect(c("match-cut")).toBe(
+      "match cut (the final composition of the first shot matches the opening composition of the second shot " +
+      `in shape, color, and motion, so the cut feels like a visual rhyme; ${INSTANT_CUT_CLAUSE})`,
+    )
+    expect(c("none")).toBe(
+      `hard cut (no transition, instantaneous switch from first shot to second shot; ${INSTANT_CUT_CLAUSE})`,
+    )
+    expect(c("whip-pan")).toBe(
+      "whip pan (the camera whips sideways at high speed, smearing the frame into heavy horizontal motion blur, " +
+      "and the second shot enters already travelling in the same direction before it settles into its framing), " +
+      "lasting approximately 1 second, with natural timing",
+    )
+    expect(c("roll-transition")).toBe(
+      `camera roll transition (${getTransitionPromptHint("roll-transition")}), ` +
+      "lasting approximately 1 second, with natural timing",
+    )
+    expect(c("freeze-frame-jump")).toBe(
+      "freeze-frame time jump (all motion stops mid-action and the picture holds still for a beat; only then does it " +
+      "jump to the same view hours or days later, everything in new positions, and motion resumes), " +
+      "lasting approximately 1 second, with natural timing",
+    )
+    expect(c("shatter-glass")).toBe(
+      `shatter like glass and reform (${getTransitionPromptHint("shatter-glass")}), ` +
+      "lasting approximately 1 second, with natural timing",
+    )
+  })
+
+  for (const mode of ["full", "compact"] as const) {
+    it(`${mode}: every row reads \`term (…)\` — the hint never restates its own "<label>:" heading`, () => {
+      for (const t of TRANSITIONS) {
+        const term = getTransitionTerm(t.id)
+        const r = composeTransitionHintFromConnections(t.id, [], [], undefined, mode)
+        if (!term) { expect(r).toBe(""); continue }
+        expect(r.startsWith(`${term} (`), t.id).toBe(true)
+        expect(r.endsWith(")"), t.id).toBe(true)
+        expect(r.slice(term.length + 2).toLowerCase().startsWith(`${term.toLowerCase()}:`), t.id).toBe(false)
+        expect(r).not.toMatch(/\(\s*[^,;()]{1,60}: /)
+      }
+    })
+
+    it(`${mode}: every instant row carries the clause exactly once, inside its parentheses`, () => {
+      for (const id of INSTANT_IDS) {
+        const r = composeTransitionHintFromConnections(id, [], [], undefined, mode)
+        expect(r.endsWith(`; ${INSTANT_CUT_CLAUSE})`), id).toBe(true)
+        expect(r.split(INSTANT_CUT_CLAUSE).length, id).toBe(2)
+      }
+    })
+
+    it(`${mode}: an all-instant multi-pick carries it once, in the first parentheses`, () => {
+      const r = composeTransitionHintFromConnections(["match-cut", "smash-cut"], [], [], undefined, mode)
+      const [a, b] = r.split(", and smash cut (")
+      expect(a.startsWith("match cut (")).toBe(true)
+      expect(a.endsWith(`; ${INSTANT_CUT_CLAUSE})`)).toBe(true)
+      expect(b).not.toContain(INSTANT_CUT_CLAUSE)
+    })
+
+    it(`${mode}: a mixed pick carries no clause and keeps duration and intensity`, () => {
+      const r = composeTransitionHintFromConnections(
+        ["match-cut", "cross-dissolve"], [], [], { position: "end", duration: "short", intensity: "natural" }, mode,
+      )
+      expect(r).not.toContain(INSTANT_CUT_CLAUSE)
+      expect(r).toBe(
+        renderTransitionBases(["match-cut", "cross-dissolve"]).join(", and ") +
+        ", the transition occurs at the end of the clip, lasting approximately 1 second, with natural timing",
+      )
+    })
+
+    it(`${mode}: a non-instant row never carries the clause`, () => {
+      for (const t of TRANSITIONS) {
+        if (t.instant) continue
+        expect(composeTransitionHintFromConnections(t.id, [], [], undefined, mode)).not.toContain(INSTANT_CUT_CLAUSE)
+      }
+    })
+  }
+
+  it("`none` does not say 'hard cut' three times", () => {
+    const r = composeTransitionHintFromConnections("none", [], [], undefined, "compact")
+    expect(r.split("hard cut").length - 1).toBe(2)
+  })
+
+  it("the direction-registry fold (server path) words a transition identically", () => {
+    for (const mode of [VIDEO_HINT_MODE_DEFAULT, "full", "compact"] as const) {
+      expect(renderDirectionHints({ transition: "match-cut" }, { surface: "video", mode }))
+        .toEqual([composeTransitionHintFromConnections("match-cut", [], [])])
+      expect(renderDirectionHints({ transition: "whip-pan" }, { surface: "video", mode }))
+        .toEqual([composeTransitionHintFromConnections("whip-pan", [], [])])
+      // Multi-pick: one fragment per id, the clause only in the first of an all-instant pick.
+      expect(renderDirectionHints({ transition: ["match-cut", "cross-dissolve"] }, { surface: "video", mode }))
+        .toEqual(renderTransitionBases(["match-cut", "cross-dissolve"]))
+    }
+    // A transition never reaches an image prompt.
+    expect(renderDirectionHints({ transition: "match-cut" }, { surface: "image" })).toEqual([])
+  })
+
+  it("under a prompt cap, the tail-shed keeps the anti-blend clause on a two-cut pick", () => {
+    const direction = { transition: ["match-cut", "none"] }
+    const [first, second] = renderTransitionBases(["match-cut", "none"])
+    expect(first.endsWith(`; ${INSTANT_CUT_CLAUSE})`)).toBe(true)
+    expect(second).not.toContain(INSTANT_CUT_CLAUSE)
+    const full = composeVideoPromptText("a knight", direction)!
+    expect(full).toContain(second)
+    // A cap the whole fold does not fit, but the first fragment does: the second
+    // cut is shed and the clause survives with the first. (With the clause on
+    // the LAST fragment, this shed dropped it.)
+    for (const cap of [full.length - 1, `a knight. ${first}`.length]) {
+      const shed = composeVideoPromptText("a knight", direction, undefined, { cap })!
+      expect(shed.length).toBeLessThanOrEqual(cap)
+      expect(shed).not.toContain(second)
+      expect(shed).toContain(INSTANT_CUT_CLAUSE)
+    }
+  })
+})

package/src/__tests__/transitions-scope.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from "vitest"
+import {
+  INSTANT_CUT_CLAUSE,
+  TRANSITIONS,
+  TRANSITION_POSITIONS,
+  composeTransitionHintFromConnections,
+  getTransitionPromptHint,
+} from "../transitions.js"
+import { CHARACTER_FX_INTENSITIES } from "../character-fx.js"
+
+/**
+ * Transition wording round 2 (2026-09-24, from the transition description A/B):
+ *   - `aging` and `zoom-into-mouth` carry new bodies;
+ *   - L1: a cut with position `full` renders no position clause;
+ *   - L5: a hint folded into one shot's time window says "of this shot"
+ *     (and a non-cut's `full` "spans this entire shot").
+ */
+
+const INSTANT_IDS = TRANSITIONS.filter((t) => t.instant).map((t) => t.id)
+const NON_INSTANT_IDS = TRANSITIONS.filter((t) => !t.instant && t.id !== "auto").map((t) => t.id)
+const FULL_CLAUSE = "the transition spans the entire clip"
+const FULL_SHOT_CLAUSE = "the transition spans this entire shot"
+const MATCH_CUT_BASE =
+  "match cut (the final composition of the first shot matches the opening composition of the second shot " +
+  "in shape, color, and motion, so the cut feels like a visual rhyme; " + INSTANT_CUT_CLAUSE + ")"
+
+describe("approved row bodies", () => {
+  it("aging", () => {
+    expect(getTransitionPromptHint("aging")).toBe(
+      "accelerated aging transition: the subject visibly ages forward - fine lines deepen into wrinkles, " +
+        "hair greys to silver, posture settles - while the framing stays unchanged",
+    )
+    expect(composeTransitionHintFromConnections("aging", [], [], { position: "middle", duration: "short", intensity: "natural" })).toBe(
+      "accelerated aging (the subject visibly ages forward - fine lines deepen into wrinkles, hair greys to silver, " +
+        "posture settles - while the framing stays unchanged), the transition occurs in the middle of the clip, " +
+        "lasting approximately 1 second, with natural timing",
+    )
+  })
+
+  it("freeze-frame-jump (stays a timed transition, not a cut)", () => {
+    expect(getTransitionPromptHint("freeze-frame-jump")).toBe(
+      "freeze-frame transition: all motion stops mid-action and the picture holds still for a beat; only then does it " +
+        "jump to the same view hours or days later, everything in new positions, and motion resumes",
+    )
+    expect(composeTransitionHintFromConnections("freeze-frame-jump", [], [], { position: "middle", duration: "short", intensity: "natural" })).toBe(
+      "freeze-frame time jump (all motion stops mid-action and the picture holds still for a beat; only then does it " +
+        "jump to the same view hours or days later, everything in new positions, and motion resumes), " +
+        "the transition occurs in the middle of the clip, lasting approximately 1 second, with natural timing",
+    )
+  })
+
+  it("zoom-into-mouth drops only 'the throat'", () => {
+    expect(getTransitionPromptHint("zoom-into-mouth")).toBe(
+      "the camera pushes into the subject's open mouth, the dark interior fills the frame, and the camera passes " +
+        "through into the new scene which materialises as if emerging from inside the body",
+    )
+  })
+})
+
+describe("L1 — a cut spans nothing, so `full` adds no clause", () => {
+  it.each(INSTANT_IDS)("%s + full renders no position clause", (id) => {
+    const out = composeTransitionHintFromConnections(id, [], [], { position: "full", duration: "short", intensity: "natural" })
+    expect(out).not.toContain("spans")
+    expect(out).toBe(composeTransitionHintFromConnections(id, [], []))
+  })
+
+  it("match cut + full is the fragment alone", () => {
+    expect(composeTransitionHintFromConnections("match-cut", [], [], { position: "full" })).toBe(MATCH_CUT_BASE)
+  })
+
+  it.each(["start", "middle", "end"] as const)("a cut keeps its %s clause", (position) => {
+    const clause = TRANSITION_POSITIONS.find((p) => p.id === position)!.promptHint
+    expect(composeTransitionHintFromConnections("match-cut", [], [], { position })).toBe(`${MATCH_CUT_BASE}, ${clause}`)
+  })
+
+  it.each(NON_INSTANT_IDS)("non-cut %s keeps the full clause", (id) => {
+    expect(composeTransitionHintFromConnections(id, [], [], { position: "full" })).toContain(`, ${FULL_CLAUSE}`)
+  })
+
+  it("a mixed pick (cut + non-cut) keeps the full clause", () => {
+    expect(
+      composeTransitionHintFromConnections(["match-cut", "cross-dissolve"], [], [], { position: "full" }),
+    ).toMatch(new RegExp(`, ${FULL_CLAUSE}$`))
+  })
+
+  it("two cuts together still drop it", () => {
+    expect(
+      composeTransitionHintFromConnections(["match-cut", "smash-cut"], [], [], { position: "full" }),
+    ).not.toContain("spans")
+  })
+})
+
+describe("L5 — scope: shot says 'of this shot'", () => {
+  const window = { scope: "shot" } as const
+
+  it.each([
+    ["start", "the transition occurs at the opening of this shot"],
+    ["middle", "the transition occurs in the middle of this shot"],
+    ["end", "the transition occurs at the end of this shot"],
+  ] as const)("%s in a shot window", (position, clause) => {
+    const out = composeTransitionHintFromConnections("whip-pan", [], [], { position }, "full", window)
+    expect(out).toMatch(new RegExp(`, ${clause}$`))
+    expect(out).not.toContain("of the clip")
+  })
+
+  it("every non-auto position clause actually changes in a shot window (guard against a reword)", () => {
+    for (const p of TRANSITION_POSITIONS.filter((p) => ["start", "middle", "end"].includes(p.id))) {
+      expect(p.promptHint).toContain(" of the clip")
+    }
+    expect(FULL_CLAUSE).toContain(" the entire clip")
+    for (const p of TRANSITION_POSITIONS.filter((p) => p.id !== "auto")) {
+      const out = composeTransitionHintFromConnections("whip-pan", [], [], { position: p.id }, "full", window)
+      expect(out).not.toContain("clip")
+    }
+  })
+
+  it("full in a shot window spans this entire shot (non-cut) and is dropped (cut)", () => {
+    expect(composeTransitionHintFromConnections("whip-pan", [], [], { position: "full" }, "full", window)).toMatch(
+      new RegExp(`, ${FULL_SHOT_CLAUSE}$`),
+    )
+    expect(composeTransitionHintFromConnections("match-cut", [], [], { position: "full" }, "full", window)).toBe(MATCH_CUT_BASE)
+  })
+
+  it.each(NON_INSTANT_IDS)("non-cut %s + full: shot scope spans this entire shot, default scope the entire clip", (id) => {
+    const shot = composeTransitionHintFromConnections(id, [], [], { position: "full" }, "full", window)
+    const clip = composeTransitionHintFromConnections(id, [], [], { position: "full" })
+    expect(shot).toBe(clip.replace(FULL_CLAUSE, FULL_SHOT_CLAUSE))
+    expect(clip).toContain(`, ${FULL_CLAUSE}`)
+  })
+
+  it("a cut in a shot window", () => {
+    expect(composeTransitionHintFromConnections("match-cut", [], [], { position: "middle" }, "full", window)).toBe(
+      `${MATCH_CUT_BASE}, the transition occurs in the middle of this shot`,
+    )
+  })
+
+  it.each(TRANSITIONS.map((t) => t.id))("%s: no scope and scope clip read 'of the clip', unchanged", (id) => {
+    const timing = { position: "middle", duration: "short", intensity: "natural" } as const
+    const plain = composeTransitionHintFromConnections(id, [], [], timing)
+    expect(composeTransitionHintFromConnections(id, [], [], timing, "full", { scope: "clip" })).toBe(plain)
+    if (plain) expect(plain).toContain("in the middle of the clip")
+  })
+})
+
+describe("intensity natural reads 'with natural timing' (transitions only)", () => {
+  it("renders on a non-cut, never 'unhurried'", () => {
+    expect(composeTransitionHintFromConnections("whip-pan", [], [], { intensity: "natural" })).toMatch(/, with natural timing$/)
+    for (const id of NON_INSTANT_IDS) {
+      expect(composeTransitionHintFromConnections(id, [], [], { intensity: "natural" })).not.toContain("unhurried")
+    }
+  })
+
+  it("is still dropped on a cut", () => {
+    expect(composeTransitionHintFromConnections("match-cut", [], [], { intensity: "natural" })).toBe(MATCH_CUT_BASE)
+  })
+
+  it("character-fx keeps its own 'with natural unhurried timing'", () => {
+    expect(CHARACTER_FX_INTENSITIES.find((o) => o.id === "natural")!.promptHint).toBe("with natural unhurried timing")
+  })
+})

package/src/__tests__/transitions.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { TRANSITIONS, TRANSITION_IDS, TRANSITION_CATEGORY_ORDER, TRANSITION_CATEGORY_LABELS, composeTransitionHintFromConnections, getTransition, getTransitionLabel, getTransitionPromptHint } from "../transitions.js"
+import { TRANSITIONS, TRANSITION_IDS, TRANSITION_CATEGORY_ORDER, TRANSITION_CATEGORY_LABELS, composeTransitionHintFromConnections, getTransition, getTransitionLabel, getTransitionPromptHint, renderTransitionBases } from "../transitions.js"
 
 describe("transitions catalog", () => {
   it("ships 82 unique entries", () => {
@@ -74,9 +74,9 @@ describe("getTransition / getTransitionLabel / getTransitionPromptHint", () => {
 })
 
 describe("composeTransitionHintFromConnections — single-pick", () => {
-  it("returns the bare hint when no connections + no timing", () => {
+  it("returns `term (hint)` when no connections + no timing", () => {
     const r = composeTransitionHintFromConnections("cross-dissolve", [], [])
-    expect(r).toBe(getTransitionPromptHint("cross-dissolve"))
+    expect(r).toBe(`cross-dissolve (${getTransitionPromptHint("cross-dissolve")})`)
   })
 
   it("returns empty when id is undefined / 'auto' / unknown", () => {
@@ -168,11 +168,12 @@ describe("composeTransitionHintFromConnections — multi-pick", () => {
     expect(scalar).toBe(array)
   })
 
-  it("joins two base hints with ', and '", () => {
+  it("joins two `term (hint)` fragments 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}`)
+    expect(r).toBe(
+      "smash cut (an abrupt jarring transition between two visually or tonally contrasting shots with no fade, on a beat)" +
+      ", and white flash (" + getTransitionPromptHint("white-flash") + ")",
+    )
   })
 
   it("dedupes duplicate ids", () => {
@@ -182,8 +183,7 @@ describe("composeTransitionHintFromConnections — multi-pick", () => {
   })
 
   it("caps at 2 ids — extra ids dropped", () => {
-    const a = getTransitionPromptHint("smash-cut")
-    const b = getTransitionPromptHint("white-flash")
+    const [a, b] = renderTransitionBases(["smash-cut", "white-flash"])
     const r = composeTransitionHintFromConnections(
       ["smash-cut", "white-flash", "fade-to-black", "wipe"],
       [],

package/src/ad-creative-analysis.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-ad creative analysis — the "expert competitor ad analyst" pass the
+ * social scraper nodes (Meta Ads first; TikTok / Instagram / LinkedIn next)
+ * can run on every ad they return. Node-agnostic on purpose: the input is
+ * "one creative + its copy + a little context", never a Meta-shaped ad.
+ *
+ * The model answers in a fixed JSON shape (the schema lives with the backend
+ * call site); this file owns the WORDS — what each field means and how to
+ * judge it — so the prompt can be tuned without touching the wire contract.
+ */
+
+/** The fields the analysis returns, in the order a reader wants them. */
+export const AD_CREATIVE_ANALYSIS_FIELDS = [
+  "assetType",
+  "format",
+  "visualHooks",
+  "audiences",
+  "graphicIdentity",
+  "copywritingHooks",
+  "usps",
+  "cta",
+  "summary",
+] as const
+export type AdCreativeAnalysisField = (typeof AD_CREATIVE_ANALYSIS_FIELDS)[number]
+
+export const AD_CREATIVE_ANALYSIS_SYSTEM_PROMPT = `You are an expert competitor ad analyst. You look at a competitor's ad — its creative (image or video poster frame) and its copy — and extract the relevant ad information into a structured summary a marketing team can act on.
+
+Judge from what is actually in the creative and copy; never invent claims that are not visible or written. Be concrete and specific (name the objects, colors, people, layouts, words), not generic ("eye-catching visuals"). Write in the language of the ad copy when it is not English, otherwise in English.
+
+Fill every field:
+- assetType: "static" (a still image), "motion" (a video — you see its poster frame), "carousel" (several creatives in one ad), or "unknown".
+- format: the placement the creative is built for — e.g. "in-feed", "story / reel (9:16)", "square feed", "banner / web", judged from its shape and framing.
+- visualHooks: the key visuals and visual angles used to stop the scroll (product close-up, before/after, face + eye contact, big number, screenshot, meme style, UGC selfie, text-on-image…). 2–6 short items.
+- audiences: who the ad represents or addresses (age band, gender, life situation, profession, interest, geography, pain point). 1–5 short items.
+- graphicIdentity: the graphic components — color palette, typography style, logo placement, layout system, illustration vs photo, brand consistency cues. One or two sentences.
+- copywritingHooks: the copywriting angles used in the visual text and in the body (curiosity, urgency, social proof, question, offer, fear of missing out, authority, humor…). 1–6 short items, each naming the angle and quoting or paraphrasing the line that carries it.
+- usps: the unique selling points the ad claims (price, speed, exclusivity, guarantee, results, features). 1–5 short items.
+- cta: the call to action — the button label and/or the closing line that tells the viewer what to do.
+- summary: two to four sentences: what the ad sells, to whom, with what hook, and why it likely works (or does not).`
+
+/**
+ * The organic-content twin of the ad prompt — for scraped social POSTS
+ * (Instagram / TikTok / LinkedIn), not paid ads. SAME output fields (so one
+ * schema and one UI serve both), read for organic content: hooks, audience,
+ * the value/benefit the post conveys (`usps`), and its ask (`cta` — "link in
+ * bio", "follow", a comment prompt, or none).
+ */
+export const POST_CONTENT_ANALYSIS_SYSTEM_PROMPT = `You are an expert social-media content analyst. You look at a single organic post — its creative (image or video cover frame) and its caption — and extract what a marketing team can learn from it into a structured summary.
+
+Judge from what is actually in the creative and caption; never invent claims that are not visible or written. Be concrete and specific (name the objects, colors, people, layouts, words), not generic ("engaging content"). Write in the language of the caption when it is not English, otherwise in English.
+
+Fill every field:
+- assetType: "static" (a still image), "motion" (a video / reel — you see its cover frame), "carousel" (a multi-image post), or "unknown".
+- format: the format the post is built for — e.g. "reel (9:16)", "square feed photo", "carousel", "portrait (4:5)", judged from its shape and framing.
+- visualHooks: the key visuals and visual angles used to stop the scroll (product close-up, before/after, face + eye contact, big text overlay, meme style, UGC selfie, trend/format…). 2–6 short items.
+- audiences: who the post represents or speaks to (age band, gender, life situation, profession, interest, geography, community). 1–5 short items.
+- graphicIdentity: the graphic components — color palette, typography style, logo / handle placement, layout, illustration vs photo, brand consistency cues. One or two sentences.
+- copywritingHooks: the caption / content angles (curiosity, storytelling, question, trend, humor, social proof, education, behind-the-scenes…). 1–6 short items, each naming the angle and quoting or paraphrasing the line that carries it.
+- usps: the value or benefit the post conveys to the viewer (entertainment, education, inspiration, a product benefit, a deal). 1–5 short items.
+- cta: the ask — the caption's call to action ("link in bio", "shop now", "follow", "comment below"), or "none" if the post makes none.
+- summary: two to four sentences: what the post is about, who it speaks to, with what hook, and why it likely performs (or does not).`
+
+export interface AdCreativeAnalysisInput {
+  /** Who is advertising (the Page / account name). */
+  readonly advertiser?: string
+  readonly headline?: string
+  readonly body?: string
+  readonly ctaLabel?: string
+  /** Where the ad points (the landing domain is enough). */
+  readonly landing?: string
+  /** Placements the ad ran on (Facebook, Instagram, TikTok…). */
+  readonly platforms?: readonly string[]
+  /** Creative shape already classified by the caller ("vertical", "square", "horizontal"). */
+  readonly creativeFormat?: string
+  /** "1 video, 2 images" — what the ad carries beyond the one frame the model sees. */
+  readonly mediaSummary?: string
+  /** The user's optional focus ("we sell running shoes — compare against our positioning"). */
+  readonly focus?: string
+}
+
+/**
+ * The user turn's text. The creative itself travels as a separate image
+ * block; this is everything else the analyst should know, one labelled
+ * line per fact, blanks left out.
+ */
+export function buildAdCreativeAnalysisUserText(input: AdCreativeAnalysisInput): string {
+  const lines: string[] = []
+  if (input.advertiser) lines.push(`Account / advertiser: ${input.advertiser}`)
+  if (input.headline) lines.push(`Headline: ${input.headline}`)
+  if (input.body) lines.push(`Body copy:\n${input.body}`)
+  if (input.ctaLabel) lines.push(`CTA button: ${input.ctaLabel}`)
+  if (input.landing) lines.push(`Landing: ${input.landing}`)
+  if (input.platforms && input.platforms.length > 0) lines.push(`Placements: ${input.platforms.join(", ")}`)
+  if (input.creativeFormat) lines.push(`Creative shape: ${input.creativeFormat}`)
+  if (input.mediaSummary) lines.push(`Media: ${input.mediaSummary}`)
+  lines.push("The attached image is the ad's creative (for a video, its poster frame).")
+  if (input.focus) lines.push(`\nAnalyst focus from the user: ${input.focus}`)
+  return lines.join("\n")
+}