@nodaro/prompts 1.23.0 → 1.25.0

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

@@ -368,7 +368,7 @@
         }
       },
       "ctx": null,
-      "expected": "locked off static camera, no camera movement"
+      "expected": "The camera is locked on a solid tripod and does not move at all for the entire shot: it never travels, never rotates, never tilts, never changes focal length. The viewpoint is completely fixed and the framing stays exactly the same from the first frame to the last.\nLife within the scene carries on naturally, but the camera holds perfectly still throughout.\nNo camera movement of any kind, no drift, no sway, no zoom."
     },
     {
       "key": "camera-motion/id:arc-left",
@@ -407,7 +407,7 @@
         }
       },
       "ctx": null,
-      "expected": "parallax camera motion, lateral movement that emphasizes the depth separation between foreground and background elements, foreground objects appearing to move faster than distant ones"
+      "expected": "The camera makes a small, smooth sideways move that shows off the depth of the scene through parallax. It eases gently a short way across, staying at the same distance and keeping its aim forward.\nThe defining quality is a STRONG parallax gradient: the nearest foreground elements slide across noticeably and quickly, the mid-distance elements shift more gently, and the most distant elements barely move at all — one smooth continuous gradient of speed from near to far that makes the separation between the layers obvious. Nothing is frozen; everything shifts, just by very different amounts according to its distance.\nThe move is modest and ambient rather than a full travelling shot: a gentle reveal of depth, not a journey across the scene.\nThe lens does not change; the camera does not push in, pull back, rotate, or shake.\nNo zoom, no forward or backward travel, no rotation, no handheld shake."
     },
     {
       "key": "camera-motion/pre-post",
@@ -422,7 +422,7 @@
         }
       },
       "ctx": null,
-      "expected": "shot on location, locked off static camera, no camera movement, no text overlays"
+      "expected": "shot on location, The camera is locked on a solid tripod and does not move at all for the entire shot: it never travels, never rotates, never tilts, never changes focal length. The viewpoint is completely fixed and the framing stays exactly the same from the first frame to the last.\nLife within the scene carries on naturally, but the camera holds perfectly still throughout.\nNo camera movement of any kind, no drift, no sway, no zoom. no text overlays"
     },
     {
       "key": "camera-motion/with-ctx",
@@ -466,7 +466,7 @@
           }
         ]
       },
-      "expected": "locked off static camera, no camera movement, beginning with wide shot, full body of the subject with visible surroundings, ending with with a calm, centered expression"
+      "expected": "The camera is locked on a solid tripod and does not move at all for the entire shot: it never travels, never rotates, never tilts, never changes focal length. The viewpoint is completely fixed and the framing stays exactly the same from the first frame to the last.\nLife within the scene carries on naturally, but the camera holds perfectly still throughout.\nNo camera movement of any kind, no drift, no sway, no zoom. beginning with wide shot, full body of the subject with visible surroundings, ending with with a calm, centered expression"
     },
     {
       "key": "camera-motion/with-ctx-pre-post",
@@ -512,7 +512,7 @@
           }
         ]
       },
-      "expected": "handheld, locked off static camera, no camera movement, beginning with wide shot, full body of the subject with visible surroundings, ending with with a calm, centered expression, 35mm"
+      "expected": "handheld, The camera is locked on a solid tripod and does not move at all for the entire shot: it never travels, never rotates, never tilts, never changes focal length. The viewpoint is completely fixed and the framing stays exactly the same from the first frame to the last.\nLife within the scene carries on naturally, but the camera holds perfectly still throughout.\nNo camera movement of any kind, no drift, no sway, no zoom. beginning with wide shot, full body of the subject with visible surroundings, ending with with a calm, centered expression, 35mm"
     },
     {
       "key": "character-fx/id:auto",
@@ -2896,7 +2896,7 @@
         }
       },
       "ctx": null,
-      "expected": "no transition, hard cut, instantaneous switch from first shot to second shot"
+      "expected": "hard cut (no transition, instantaneous switch from first shot to second shot; an abrupt single-frame hard cut, no dissolve, crossfade or superimposition; the two images never blend)"
     },
     {
       "key": "transition/id:auto",
@@ -2922,7 +2922,7 @@
         }
       },
       "ctx": null,
-      "expected": "the first and second scenes blend as a translucent double exposure where both images coexist semi-transparently on the frame, the first image then gradually fades out leaving the second image fully resolved"
+      "expected": "double exposure (the first and second scenes blend as a translucent double exposure where both images coexist semi-transparently on the frame, the first image then gradually fades out leaving the second image fully resolved)"
     },
     {
       "key": "transition/id:dream-ripple",
@@ -2935,7 +2935,7 @@
         }
       },
       "ctx": null,
-      "expected": "a circular ripple radiates outward across the frame as if the image were the surface of water, and where the ripple passes the first scene is replaced by the second scene"
+      "expected": "dream ripple (a circular ripple radiates outward across the frame as if the image were the surface of water, and where the ripple passes the first scene is replaced by the second scene)"
     },
     {
       "key": "transition/multi-pick",
@@ -2951,7 +2951,7 @@
         }
       },
       "ctx": null,
-      "expected": "no transition, hard cut, instantaneous switch from first shot to second shot, and smooth cross-dissolve transition where the first shot gradually fades out as the second shot fades in"
+      "expected": "hard cut (no transition, instantaneous switch from first shot to second shot), and cross-dissolve (smooth cross-dissolve transition where the first shot gradually fades out as the second shot fades in)"
     },
     {
       "key": "transition/pre-post",
@@ -2966,7 +2966,7 @@
         }
       },
       "ctx": null,
-      "expected": "shot on location, no transition, hard cut, instantaneous switch from first shot to second shot, no text overlays"
+      "expected": "shot on location, hard cut (no transition, instantaneous switch from first shot to second shot; an abrupt single-frame hard cut, no dissolve, crossfade or superimposition; the two images never blend), no text overlays"
     },
     {
       "key": "transition/timing",
@@ -2982,7 +2982,7 @@
         }
       },
       "ctx": null,
-      "expected": "smooth cross-dissolve transition where the first shot gradually fades out as the second shot fades in, the transition occurs in the middle of the clip, lasting approximately 1 second, with dynamic energy and assertive flourish"
+      "expected": "cross-dissolve (smooth cross-dissolve transition where the first shot gradually fades out as the second shot fades in), the transition occurs in the middle of the clip, lasting approximately 1 second, with dynamic energy and assertive flourish"
     },
     {
       "key": "transition/timing-auto",
@@ -2998,7 +2998,7 @@
         }
       },
       "ctx": null,
-      "expected": "no transition, hard cut, instantaneous switch from first shot to second shot"
+      "expected": "hard cut (no transition, instantaneous switch from first shot to second shot; an abrupt single-frame hard cut, no dissolve, crossfade or superimposition; the two images never blend)"
     },
     {
       "key": "transition/timing-instant",
@@ -3014,7 +3014,7 @@
         }
       },
       "ctx": null,
-      "expected": "no transition, hard cut, instantaneous switch from first shot to second shot, the transition occurs in the middle of the clip, with dynamic energy and assertive flourish"
+      "expected": "hard cut (no transition, instantaneous switch from first shot to second shot; an abrupt single-frame hard cut, no dissolve, crossfade or superimposition; the two images never blend), the transition occurs in the middle of the clip"
     },
     {
       "key": "transition/with-ctx",
@@ -3058,7 +3058,7 @@
           }
         ]
       },
-      "expected": "no transition, hard cut, instantaneous switch from first shot to second shot, starting from wide shot, full body of the subject with visible surroundings, ending at with a calm, centered expression"
+      "expected": "hard cut (no transition, instantaneous switch from first shot to second shot; an abrupt single-frame hard cut, no dissolve, crossfade or superimposition; the two images never blend), starting from wide shot, full body of the subject with visible surroundings, ending at with a calm, centered expression"
     },
     {
       "key": "transition/with-ctx-timing-multi-pick",
@@ -3110,7 +3110,7 @@
           }
         ]
       },
-      "expected": "on the beat, no transition, hard cut, instantaneous switch from first shot to second shot, and smooth cross-dissolve transition where the first shot gradually fades out as the second shot fades in, the transition occurs at the end of the clip, lasting approximately 3 seconds, with subtle restrained energy and minimal flourish, starting from wide shot, full body of the subject with visible surroundings, ending at with a calm, centered expression, hold the last frame"
+      "expected": "on the beat, hard cut (no transition, instantaneous switch from first shot to second shot), and cross-dissolve (smooth cross-dissolve transition where the first shot gradually fades out as the second shot fades in), the transition occurs at the end of the clip, lasting approximately 3 seconds, with subtle restrained energy and minimal flourish, starting from wide shot, full body of the subject with visible surroundings, ending at with a calm, centered expression, hold the last frame"
     },
     {
       "key": "unknown/type",

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

@@ -50,8 +50,9 @@ describe("sentence-style camera-motion hints compose cleanly", () => {
   })
 
   it("keeps a clause-style hint byte-identical to the pre-joiner output", () => {
-    expect(composeCameraMotionHintFromConnections("static", ["wide shot"], [])).toBe(
-      "locked off static camera, no camera movement, beginning with wide shot",
+    // roll-left kept its one-clause catalog wording through the Camera Motion Lab.
+    expect(composeCameraMotionHintFromConnections("roll-left", ["wide shot"], [])).toBe(
+      "camera rolls counterclockwise around the lens axis, beginning with wide shot",
     )
   })
 })

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

@@ -1,11 +1,18 @@
 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, …,
@@ -25,6 +32,7 @@ const INSTANT_IDS = [
 ]
 
 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", () => {
@@ -61,22 +69,35 @@ describe("instant transitions — the composer drops the duration lever", () =>
       }
     })
 
-    it(`${mode}: position and intensity still apply to a cut`, () => {
+    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).toContain("with natural unhurried timing")
+      expect(r).not.toContain("unhurried")
       expect(r).not.toContain("lasting approximately")
     })
   }
 
-  it("compact match cut reads term + position + intensity only", () => {
+  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 transition occurs in the middle of the clip, with natural unhurried timing")
+    ).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", () => {
@@ -92,21 +113,130 @@ describe("instant transitions — the composer drops the duration lever", () =>
   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)
   })
 })
 
-describe("instant transitions — on the wire catalog", () => {
-  it("the transition picker options carry instant: true on exactly the cut rows", () => {
-    const options = getPickerCatalog("transition")?.options ?? []
-    expect(options.length).toBe(TRANSITIONS.length)
-    expect(options.filter((o) => o.instant === true).map((o) => o.id).sort()).toEqual([...INSTANT_IDS].sort())
-    // Absent (not `false`) everywhere else, so a non-transition catalog's shape is unchanged.
-    for (const o of options) if (!INSTANT_IDS.includes(o.id)) expect(o).not.toHaveProperty("instant")
+/**
+ * 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("no other catalog grows the field", () => {
-    const camera = getPickerCatalog("camera-motion")?.options ?? []
-    expect(camera.length).toBeGreaterThan(0)
-    for (const o of camera) expect(o).not.toHaveProperty("instant")
+  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"],
       [],