@nodaro/prompts 1.23.0 → 1.25.1

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/camera-motions.ts

@@ -53,7 +53,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Static",
     category: "default",
     description: "Fixed camera, no movement",
-    promptHint: "locked off static camera, no camera movement",
+    promptHint: "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.",
     term: "locked-off static camera",
   },
   {
@@ -61,7 +61,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Handheld",
     category: "default",
     description: "Natural handheld shake",
-    promptHint: "handheld camera with subtle natural shake and micro movements",
+    promptHint: "The camera is HANDHELD, held in an operator's hands rather than on any support, so it carries the constant small live motion of a real person holding it: a continuous gentle shake and wobble, tiny irregular drifts and corrections in every direction, a slight bob in time with breathing, never settling completely still even for a moment.\nThe motion is small and organic, never a large or deliberate move: the camera stays roughly where it is and keeps roughly the same framing, it simply never locks off. It does not travel toward anything, away from anything, or off to any side; it holds its position and only jitters around it. The unsteadiness is human and slightly random, not a smooth mechanical sway and not a rhythmic loop.\nThe lens does not change and the camera does not travel anywhere, orbit, or turn to a new direction; it just floats and jitters in place as if held.\nThe framing stays broadly the same across the shot, loosely on the subject, wandering by only small amounts.\nNo zoom, no deliberate camera move, no forward or backward travel, no rotation to a new angle, no smooth glide.",
     term: "handheld camera",
   },
   {
@@ -69,7 +69,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Steadicam",
     category: "default",
     description: "Smooth stabilized walking shot",
-    promptHint: "smooth steadicam shot, gliding stabilized movement through the scene",
+    promptHint: "The camera moves with the perfectly smooth, floating quality of a Steadicam or gimbal: it glides gently and continuously, with none of the shake, jitter or bob of a handheld rig. Every bit of movement is buttery, damped and stabilised, as if the camera were floating on air.\nThe motion is a slow, graceful drift through the scene — easing a little forward and around with fluid, gliding ease — always even and controlled, never abrupt, never trembling, never correcting.\nThe lens does not change. The framing stays loosely on the subject throughout, the glide being gentle enough that the composition holds.\nThe single defining quality is SMOOTHNESS: this is the opposite of handheld — no shake whatsoever, only silky stabilised floating motion.\nNo zoom, no jitter, no handheld shake, no abrupt moves.",
     term: "smooth steadicam shot",
   },
 
@@ -271,14 +271,14 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Dutch Angle",
     category: "roll",
     description: "Static tilted frame for tension",
-    promptHint: "dutch angle, canted tilted frame for tension",
+    promptHint: "The shot begins level, then the camera rolls a little way around its own lens axis and STOPS at a fixed cant, holding that tilted Dutch-angle framing for the rest of the shot. It is a single small settling roll into a tilt, not a continuous spin: the frame tips perhaps fifteen or twenty degrees off level and then stays there, canted and still, for an uneasy, tense feeling.\nOnly the roll axis is involved: the camera stays in the same position, does not travel, does not pan or tilt its aim up or down, and the lens does not change. The horizon starts level and ends clearly canted, then holds.\nBecause it is a pure roll, there is no parallax: the whole frame turns as one flat picture, near and far together.\nLife in the scene carries on gently while the framing holds its tilt.\nNo zoom, no travel, no continuous spinning, no returning to level once canted.",
   },
   {
     id: "spin-360",
     label: "Full 360 Spin",
     category: "roll",
     description: "Camera rotates a full 360° on its axis",
-    promptHint: "full 360 degree spin, the camera rotates a complete revolution on its own lens axis",
+    promptHint: "The camera rotates a FULL 360 degrees around its own lens axis in one continuous even spin, and keeps turning the same way without pausing until the picture has come all the way back to level exactly as it started. The horizon sweeps from level, round through fully sideways on one side, through completely upside-down, through fully sideways on the other side, and back to level — one complete unbroken revolution.\nOnly the roll axis is involved: the camera stays in exactly the same position, does not travel, does not pan or tilt its aim, and the lens does not change. It spins about the axis running straight out through the lens.\nBecause it is a pure roll, there is no parallax: the whole frame turns as one flat picture, near and far rotating together by the same amount.\nThe spin is smooth and continuous at an even speed, going round only once and ending back at level.\nNo zoom, no travel, no pan, no tilt of the aim, no reversal of the spin direction.",
     term: "full 360 degree camera roll",
   },
 
@@ -403,7 +403,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Ronin Glide",
     category: "tracking",
     description: "Slow gliding move on a Ronin/Movi gimbal",
-    promptHint: "ronin glide, slow gliding move on a Ronin or Movi gimbal, cinematic float without any shake",
+    promptHint: "ronin gimbal glide, ultra-smooth floating tracking movement following the subject",
     term: "slow gliding gimbal move",
   },
   {
@@ -411,7 +411,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Serpentine Track",
     category: "tracking",
     description: "Camera weaves through obstacles in S-curves",
-    promptHint: "serpentine track, the camera weaves through obstacles in S-curves, snaking forward along a winding path",
+    promptHint: "serpentine tracking shot, camera weaves smoothly side to side while following the subject",
     term: "serpentine tracking shot",
   },
 
@@ -421,7 +421,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "POV",
     category: "special",
     description: "First person point of view",
-    promptHint: "POV shot, first person perspective as seen through the subject's eyes",
+    promptHint: "POV shot, first person perspective as seen through the subject's eyes. The viewpoint moves forward at a calm, unhurried walking pace — steady and gentle, never a fast rush or a vehicle-like travel speed. No body parts, hands or feet ever enter the frame; only the point of view itself drifts smoothly forward.",
     term: "first person pov shot",
   },
   {
@@ -429,7 +429,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Over The Shoulder",
     category: "special",
     description: "Frame past a character's shoulder",
-    promptHint: "over the shoulder shot, framing past one character's shoulder onto another",
+    promptHint: "Over the shoulder shot: the camera is already framed past the near character's shoulder onto the second character from the very first frame, with no push-in or approach - the framing and distance stay constant throughout, at most a very small handheld-style settle. No camera travel toward or away from either character. No dialogue, no spoken words, no lip movement suggesting speech - completely silent, ambient sound only if any.",
     term: "over-the-shoulder shot",
   },
   {
@@ -453,7 +453,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Aerial",
     category: "special",
     description: "High altitude drone-style shot",
-    promptHint: "aerial drone shot, high altitude slow forward movement over the landscape",
+    promptHint: "The camera is airborne and sinks straight downward through the air, losing altitude like an aircraft lowering itself vertically. Its aim is completely fixed: the horizon line stays at exactly the same height across the frame from the first moment to the last, and the camera never dips or tips its view downward at all — what it points at does not change, only where it is in space.\nAs the camera drops in height, everything in view slides UPWARD through the frame together because the viewpoint is lower: whatever stands tall rises up the frame and grows, and more of what lies far below climbs into view from the bottom. This vertical sliding of the whole scene is the ONLY change; the angle of view is frozen.\nNo tilting, no dipping the aim down, no looking further down, no rotation, no forward travel — the horizon must remain pinned at its starting height while the camera simply loses altitude.",
     term: "high altitude aerial drone shot",
   },
   {
@@ -461,7 +461,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Helicopter",
     category: "special",
     description: "Wide high-altitude sweeping aerial",
-    promptHint: "helicopter shot, high altitude wide sweeping aerial pass with strong lateral movement",
+    promptHint: "helicopter shot, sweeping aerial movement banking around the scene",
     term: "sweeping helicopter aerial shot",
   },
   {
@@ -469,7 +469,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Fly Over",
     category: "special",
     description: "Low fast aerial pass over the scene",
-    promptHint: "fly over shot, low altitude drone passing quickly over the scene with strong forward motion",
+    promptHint: "The camera flies steadily FORWARD through the air at a constant height, cruising ahead toward what lies in front of it without ever changing altitude. Its height stays exactly the same from start to finish — it does not descend, does not climb, does not dip its aim; it simply travels forward at cruising speed.\nBecause it moves forward, whatever lies ahead grows closer and sweeps toward the camera and past it on both sides, near things rushing by faster than far things. The horizon holds at exactly the same height in the frame the whole time.\nNo descending, no climbing, no tilting the aim, no rotation — only steady level forward flight at a fixed altitude.",
     term: "low aerial fly-over pass",
   },
   {
@@ -501,7 +501,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Rack Focus",
     category: "special",
     description: "Pull focus between foreground and background",
-    promptHint: "rack focus, lens focus shifts from a foreground subject to a background subject (or vice versa), the unfocused plane blurs",
+    promptHint: "The camera itself never moves, never zooms and never changes its framing — it is completely locked in place for the whole shot. Only the lens's focus plane shifts. It starts sharply focused on the nearest element in the frame, with everything further back a soft out-of-focus blur. Then the focus pulls smoothly across to the far background, which becomes crisp and sharp, while the near foreground that was sharp a moment ago now falls out of focus and blurs instead. The two states — near-sharp/far-blurred, then near-blurred/far-sharp — must read as clearly opposite. No camera travel, no zoom, no change in composition — only which plane is sharp changes.",
   },
 
   // Modern / social-video vocabulary
@@ -510,7 +510,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Handheld Vlog",
     category: "default",
     description: "Casual vlog-style handheld",
-    promptHint: "casual handheld vlog-style camera, slight wandering and natural shake, talking-to-camera framing",
+    promptHint: "The camera is a casual handheld vlog camera, held at arm's length by the subject or a companion, with the loose, informal quality of someone filming themselves. It has clear handheld shake and small bobbing motion, but looser and more wandering than a careful operator: it drifts around a bit, reframes casually, bobs as if the holder is shifting their weight or gesturing.\nThe framing sits fairly close and personal, roughly on the subject, wandering by moderate amounts as a vlogger's arm naturally would — informal and lively, not locked or composed.\nThe motion has personality and looseness: more movement than a careful handheld, unpolished and spontaneous, but it stays broadly in place rather than travelling off anywhere.\nThe lens does not change; the camera does not glide smoothly (that would be a steadicam) and does not travel deliberately in any direction.\nNo zoom, no smooth stabilised glide, no deliberate directional move, no tripod stillness.",
     term: "handheld vlog-style camera",
   },
   {
@@ -518,7 +518,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "POV Walk",
     category: "tracking",
     description: "First-person walking POV",
-    promptHint: "first-person POV walking camera, GoPro-style head-mounted perspective with natural footstep movement",
+    promptHint: "first-person POV walking shot, camera as the subject's eyes with natural head-bob as they walk forward",
     term: "first person walking pov",
   },
   {
@@ -541,23 +541,23 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Screen Tap",
     category: "special",
     description: "On-screen finger-tap transition",
-    promptHint: "camera transition triggered by an on-screen finger tap, TikTok-native pacing with snap to the next subject",
-    term: "on-screen finger-tap transition",
+    promptHint: "An abrupt hard snap-cut transition: the camera instantly jumps to a new framing of the scene with no gradual movement in between, a fast decisive jolt rather than any smooth pan, push or travel. No object, hand, finger, or UI element ever appears in the frame. TikTok-native snap pacing.",
+    term: "abrupt snap-cut transition",
   },
   {
     id: "phone-flip",
     label: "Phone Flip",
     category: "special",
     description: "Front/rear camera flip",
-    promptHint: "camera-flip transition where the phone visibly rotates between the front and rear sensors, brief blur during the swap",
-    term: "front-to-rear phone camera flip",
+    promptHint: "A rapid flip-transition, functioning as a hard cut rather than a smooth continuous rotation: the entire frame snaps through one quick full rotation in a fraction of a second, with strong motion blur through the spin, then lands upright again immediately on a new framing of the scene. This is abrupt and near-instant, never a slow, smooth, or continuously spinning carousel-like rotation. No object, hand, phone, or UI element ever appears in the frame.",
+    term: "fast flip-cut transition",
   },
   {
     id: "gentle-drift",
     label: "Gentle Drift",
     category: "default",
     description: "Slow ambient floating motion",
-    promptHint: "gentle camera drift, a slow ambient floating motion with no specific direction, the camera barely moves but never sits perfectly still, evocative of contemplative atmospheric shots",
+    promptHint: "The camera drifts with an extremely slow, gentle, ambient floating motion, as if suspended and barely stirring in still air. There is no shake and no deliberate direction: it simply floats, drifting a tiny amount one way and then easing another, aimless and dreamlike.\nThe movement is minimal and continuous — the camera never sits perfectly still, but it never travels anywhere either; it hovers almost in place, wandering by only the smallest amounts, smooth and weightless throughout.\nThe pace is contemplative and calm, the drift so slow it is only just perceptible. The picture stays sharp; there is no motion blur.\nThe lens does not change and the framing stays broadly the same, resting loosely on the subject.\nNo zoom, no shake, no jitter, no deliberate directional move, no travel across the scene.",
     term: "slow gentle camera drift",
   },
   {
@@ -565,7 +565,7 @@ export const CAMERA_MOTIONS: ReadonlyArray<CameraMotion> = [
     label: "Parallax",
     category: "default",
     description: "Lateral motion with foreground/background depth separation",
-    promptHint: "parallax camera motion, lateral movement that emphasizes the depth separation between foreground and background elements, foreground objects appearing to move faster than distant ones",
+    promptHint: "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.",
     term: "lateral parallax camera move",
   },
 ]

package/src/direction-registry.ts

@@ -67,7 +67,7 @@ import { getEraPromptHint, getEraTerm } from "./era.js"
 import { getBackdropPromptHint, getBackdropTerm } from "./backdrop.js"
 import { buildActionFxHints } from "./action-fx.js"
 import { getTemporalPromptHint, getTemporalTerm } from "./temporal.js"
-import { getTransitionPromptHint, getTransitionTerm } from "./transitions.js"
+import { renderTransitionBases } from "./transitions.js"
 import { getLoopSubjectPromptHint, getLoopSubjectTerm } from "./loop-subject.js"
 
 /** Which generation stages fold a dimension. */
@@ -251,7 +251,7 @@ export const DIRECTION_FIELDS = [
   { key: "temporalFreeze", surface: "video", family: "motion", maxPicks: 1, render: temporal },
   { key: "temporalDirection", surface: "video", family: "motion", maxPicks: 1, render: temporal },
   { key: "temporalShutter", surface: "video", family: "motion", maxPicks: 1, render: temporal },
-  { key: "transition", surface: "video", family: "motion", maxPicks: 2, render: perId(getTransitionPromptHint, getTransitionTerm) },
+  { key: "transition", surface: "video", family: "motion", maxPicks: 2, render: renderTransitionBases },
   { key: "loopSubject", surface: "video", family: "motion", maxPicks: 1, render: perId(getLoopSubjectPromptHint, getLoopSubjectTerm) },
 
   // ── LEGACY BLOCK — see the table doc above. Placed LAST, in today's exact

package/src/picker-catalogs.ts

@@ -121,10 +121,10 @@ export interface PickerOption {
   readonly term: string
   /**
    * Transitions only: present (`true`) on a row whose mechanism is a CUT, so
-   * it takes no duration — see `Transition.instant` / `isInstantTransition`.
-   * A consumer that only reads this wire catalog (Studio builds the transition
-   * Duration lever from `getPickerCatalog("transition")`) hides that lever for
-   * such a row. Carried from the base catalog; a row a catalog pack ADDS has
+   * it takes no duration and no intensity — see `Transition.instant` /
+   * `isInstantTransition`. A consumer that only reads this wire catalog
+   * (Studio builds the transition Duration lever from
+   * `getPickerCatalog("transition")`) hides those levers for such a row. Carried from the base catalog; a row a catalog pack ADDS has
    * it only when the pack's own option says so, and absent means "has a
    * duration" — the safe reading, since the composer then behaves as before.
    */

package/src/transitions.ts

@@ -48,9 +48,21 @@ export interface Transition {
    * second on the change, and it obliges with a dissolve: a match cut rendered
    * as a 1.75 s cross-dissolve in QA. The composer therefore skips the duration
    * lever when every picked transition is instant, and consumers (the picker
-   * UI, Studio) read `isInstantTransition` to hide that lever. Position and
-   * intensity still apply — WHERE the cut lands, and how hard it hits, are
-   * real choices.
+   * UI, Studio) read `isInstantTransition` to hide that lever.
+   *
+   * The same holds for INTENSITY: every intensity clause describes how the
+   * change PERFORMS over time ("natural unhurried timing", "wild flourishes and
+   * dramatic distortion"), and a cut has no performance to shape — "unhurried"
+   * on a match cut is another invitation to blend. So the composer drops the
+   * intensity clause too when every pick is instant. Position still applies —
+   * WHERE the cut lands is a real choice — except `full`: a single-frame cut
+   * cannot "span the entire clip", so that clause is dropped on an all-instant
+   * pick (start / middle / end still place the cut).
+   *
+   * The bare term is not enough on its own either: "match cut" still came back
+   * as a ~1 s superimposition in prod QA (seedance-2-5). The composer therefore
+   * puts `INSTANT_CUT_CLAUSE` inside an all-instant pick's parentheses, once — the explicit
+   * anti-blend instruction that made the model render a true single-frame cut.
    */
   readonly instant?: boolean
 }
@@ -121,11 +133,11 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "seasonal-shift",          label: "Seasonal Shift",             category: "time", description: "Same scene through changing seasons",
     promptHint: "accelerated seasonal time-lapse: foliage transitions from spring green to summer lushness to autumn red-gold to winter bare, leaves fall and regrow, snow accumulates and melts, all within the same locked framing", term: "seasonal time-lapse" },
   { id: "aging",                   label: "Aging",                      category: "time", description: "Subject visibly ages forward in time",
-    promptHint: "accelerated aging transition: the subject visibly ages forward — skin develops fine lines then deeper wrinkles, hair lightens to silver, posture shifts subtly, while the framing holds steady on the face", term: "accelerated aging" },
+    promptHint: "accelerated aging transition: the subject visibly ages forward - fine lines deepen into wrinkles, hair greys to silver, posture settles - while the framing stays unchanged", term: "accelerated aging" },
   { id: "rewind",                  label: "Rewind",                     category: "time", description: "Time reverses, motion plays backward",
-    promptHint: "rewind transition: time reverses and all motion plays smoothly backward, water flows up, debris reassembles, the subject's recent actions undo, with a faint VHS-rewind tracking distortion at the edges", term: "reverse-motion rewind" },
+    promptHint: "rewind transition: reverse motion: the actions just seen are undone exactly as they happened, in reverse order and at the same pace, the subject retracing each step to where it began, ending on the end frame", term: "reverse-motion rewind" },
   { id: "freeze-frame-jump",       label: "Freeze-Frame Jump",          category: "time", description: "Action freezes, jumps forward in time",
-    promptHint: "freeze-frame transition: motion arrests mid-action, the frame holds frozen for a beat, then snaps to a new moment hours or days later in the same scene with subjects in different positions", term: "freeze-frame time jump" },
+    promptHint: "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", term: "freeze-frame time jump" },
   { id: "weather-shift",           label: "Weather Shift",              category: "time", description: "Same scene through changing weather",
     promptHint: "accelerated weather transition: same scene, framing locked — clear sky darkens to storm clouds, rain begins and intensifies then clears, sun returns through breaking clouds", term: "weather time-lapse" },
   { id: "flashback",               label: "Flashback",                  category: "time", description: "Memory-flashback into a past moment of the subject",
@@ -193,7 +205,7 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "zoom-into-mirror",  label: "Zoom Into Mirror",     category: "portal", description: "Push into mirror, scene inside reflection",
     promptHint: "the camera pushes toward a mirror in the scene, the mirror's reflection fills the frame, and the camera passes through the mirror surface into the reflected world which becomes the new scene" },
   { id: "zoom-into-screen",  label: "Zoom Into Screen",     category: "portal", description: "Push into TV/phone screen",
-    promptHint: "the camera pushes toward a screen visible in the scene (TV, phone, monitor), the screen's image fills the frame, and the camera passes through into that image which becomes the new scene" },
+    promptHint: "the camera pushes toward a screen visible in the scene, such as a TV, phone or monitor, the screen's image fills the frame, and the camera passes through into that image which becomes the new scene" },
   { id: "zoom-into-book",    label: "Zoom Into Book",       category: "portal", description: "Push into book page illustration",
     promptHint: "the camera pushes down into an illustrated page in a book, the illustration grows to fill the frame, and the illustration comes alive as the new scene" },
   { id: "walk-through-door", label: "Walk Through Doorway", category: "portal", description: "Through doorway into new scene",
@@ -203,7 +215,7 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "pull-out-reveal",   label: "Pull-Out Reveal",      category: "portal", description: "Reveals scene was a picture in larger context",
     promptHint: "the camera pulls back rapidly and reveals that the entire first scene was actually contained within a picture, painting, screen, or window in a larger second scene", term: "pull-back reveal" },
   { id: "zoom-into-mouth",   label: "Zoom Into Mouth",      category: "portal", description: "Push into open mouth, emerges in new world inside",
-    promptHint: "the camera pushes into the subject's open mouth, the dark interior fills the frame, and the camera passes through the throat into the new scene which materialises as if emerging from inside the body" },
+    promptHint: "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" },
   { id: "push-through-glass", label: "Push Through Glass",   category: "portal", description: "Camera pushes through pane of glass into new world",
     promptHint: "the camera pushes toward a pane of glass in the scene, the surface ripples like liquid as the camera passes through with a faint refraction, and the space on the other side resolves as the new scene" },
   { id: "soul-jump",         label: "Soul Jump",            category: "portal", description: "Translucent soul leaves body, enters new body",
@@ -343,6 +355,99 @@ export function isInstantTransition(
   return ids.every((one) => getTransition(one)?.instant === true)
 }
 
+/**
+ * The anti-blend instruction an all-instant transition pick carries — the ONE
+ * place this sentence lives (see `Transition.instant`). Each row keeps its own
+ * meaning in its own hint (a match cut still matches shapes, snap to black
+ * still holds black for a beat); this clause only forbids the blend a video
+ * model otherwise puts between the two images. Measured on prod with
+ * seedance-2-5: with it, a match cut renders as a true single-frame hard cut,
+ * with and without an end frame; without it, as a ~1 s dissolve.
+ */
+export const INSTANT_CUT_CLAUSE =
+  "an abrupt single-frame hard cut, no dissolve, crossfade or superimposition; the two images never blend"
+
+/**
+ * A short "<label>: " heading at the head of a hint ("match cut: …", "whip pan
+ * transition: …", "fast-forward time-lapse transition: …"). At most five words
+ * with no clause punctuation, so a colon deep inside a sentence never matches.
+ * ANY such heading is stripped — including one on a catalog-pack row — because
+ * the term already names the move (documented in
+ * `docs/design/catalog-pack-seam.md` and `docs/nodes/parameters/transition.md`).
+ */
+const LEADING_LABEL = /^\s*((?:[^\s:,;.()]+\s+){0,4}[^\s:,;.()]+)\s*:\s+/
+
+const normalizePhrase = (s: string): string => s.trim().toLowerCase().replace(/\s+/g, " ")
+
+/**
+ * The hint BODY that goes inside a transition's parentheses: the promptHint
+ * with its leading "<label>:" heading removed (the term already names it) and
+ * any comma-separated item that merely restates the term dropped (`none`'s
+ * "no transition, hard cut, instantaneous switch …" loses its "hard cut").
+ */
+function transitionHintBody(id: string, term: string): string {
+  const hint = getTransitionPromptHint(id).replace(LEADING_LABEL, "").trim()
+  const t = normalizePhrase(term)
+  return hint
+    .split(/,\s*/)
+    .filter((item) => normalizePhrase(item) !== t)
+    .join(", ")
+    .trim()
+}
+
+/**
+ * One picked transition as a VIDEO prompt reads it: `<term> (<hint body>)`.
+ * The term names the move in the editor's own words; the parentheses carry the
+ * model-facing mechanism, which the term alone does not convey (a bare "match
+ * cut" rendered as a dissolve on prod). `withCutClause` appends
+ * `; INSTANT_CUT_CLAUSE` inside the parentheses. A row whose hint is just its
+ * term (or empty) renders as the term alone; an unknown id or "auto" as "".
+ */
+function transitionFragment(id: string, withCutClause: boolean): string {
+  const term = getTransitionTerm(id)
+  if (!term) return ""
+  const inner = [transitionHintBody(id, term), withCutClause ? INSTANT_CUT_CLAUSE : ""]
+    .filter((part) => part.length > 0)
+    .join("; ")
+  return inner.length > 0 && normalizePhrase(inner) !== normalizePhrase(term)
+    ? `${term} (${inner})`
+    : term
+}
+
+/**
+ * The transition BASE fragments for a pick — one `<term> (<hint body>)` per id
+ * that resolves to a term, in pick order. When EVERY contributing id is
+ * instant, the FIRST fragment's parentheses also carry `; INSTANT_CUT_CLAUSE`
+ * (once per pick — two cuts picked together are still one cut). FIRST, not
+ * last: the direction fold sheds fragments from the TAIL under a provider cap,
+ * so the clause rides the fragment that survives longest. A mixed pick carries
+ * no clause: its non-cut is meant to blend.
+ *
+ * The same text in both hint modes. A transition only ever reaches a VIDEO
+ * prompt (the registry row is `surface: "video"`; the canvas node is in
+ * `VIDEO_ONLY_PARAMETER_NODE_TYPES`), and there the bare compact term was not
+ * enough to steer the model, so the mode no longer changes a transition.
+ *
+ * Each fragment is ONE string, parentheses included: the cap-aware assemblers
+ * shed whole fragments from the tail, so a fragment is kept or dropped whole
+ * and can never lose its hint or its clause on its own.
+ *
+ * Shared by `composeTransitionHintFromConnections` (the canvas transition node,
+ * Studio's transition clauses) and the direction registry's `transition` row
+ * (the server fold of `direction.transition`), so both paths word a transition
+ * identically.
+ */
+export function renderTransitionBases(
+  ids: ReadonlyArray<string>,
+  _mode: PickerHintMode = "full",
+): string[] {
+  // Only ids that contribute a fragment count — a no-op "auto" beside a cut
+  // must not make the pick look non-instant.
+  const picked = ids.filter((id) => getTransitionTerm(id).length > 0)
+  const instant = isInstantTransition(picked)
+  return picked.map((id, i) => transitionFragment(id, instant && i === 0))
+}
+
 // ---------------------------------------------------------------------------
 // Graph-aware composer — start/end input handles + timing fields + multi-pick
 // ---------------------------------------------------------------------------
@@ -388,7 +493,7 @@ export const TRANSITION_DURATIONS = [
 export const TRANSITION_INTENSITIES = [
   { id: "auto",    label: "Auto",    description: "Let the model judge it",      promptHint: "", term: "" },
   { id: "subtle",  label: "Subtle",  description: "Restrained, minimal flourish", promptHint: "with subtle restrained energy and minimal flourish", term: "subtly" },
-  { id: "natural", label: "Natural", description: "Unhurried, unforced timing",  promptHint: "with natural unhurried timing", term: "at a natural pace" },
+  { id: "natural", label: "Natural", description: "Unhurried, unforced timing",  promptHint: "with natural timing", term: "at a natural pace" },
   { id: "dynamic", label: "Dynamic", description: "Assertive, energetic",        promptHint: "with dynamic energy and assertive flourish", term: "energetically" },
   { id: "crazy",   label: "Crazy",   description: "Extreme, wild, distorted",    promptHint: "with extreme exaggerated energy, wild flourishes, and dramatic distortion", term: "wildly exaggerated" },
 ] as const satisfies ReadonlyArray<TransitionTimingOption>
@@ -411,6 +516,35 @@ function clausesOf<T extends TransitionTimingOption>(
 }
 
 const POSITION_CLAUSES = clausesOf(TRANSITION_POSITIONS)
+
+/**
+ * Where the composed hint lands. `"clip"` (the default) is a whole video's
+ * prompt, so a position is placed within "the clip". `"shot"` is one shot's
+ * time window inside a multi-shot prompt (`0-2s — …`, `2-4s — …`): there "the
+ * middle of the clip" points the model at the wrong span, so the position
+ * clause says "of this shot" instead.
+ */
+export type TransitionHintScope = "clip" | "shot"
+
+export interface TransitionHintOptions {
+  readonly scope?: TransitionHintScope
+}
+
+/**
+ * The position clauses for a shot window — DERIVED from `POSITION_CLAUSES`, so
+ * the catalog stays the one source of the wording: every " of the clip" reads
+ * " of this shot", and `full`'s "the entire clip" reads "this entire shot".
+ * `transitions-scope.test.ts` pins that every non-auto row changes, so a
+ * reword that drops either phrase fails loudly instead of quietly saying
+ * "clip" inside a shot window.
+ */
+const SHOT_POSITION_CLAUSES: typeof POSITION_CLAUSES = Object.fromEntries(
+  Object.entries(POSITION_CLAUSES).map(([id, clause]) => [
+    id,
+    clause.replace(/ of the clip\b/g, " of this shot").replace(/ the entire clip\b/g, " this entire shot"),
+  ]),
+) as typeof POSITION_CLAUSES
+
 const DURATION_CLAUSES = clausesOf(TRANSITION_DURATIONS)
 const INTENSITY_CLAUSES = clausesOf(TRANSITION_INTENSITIES)
 
@@ -422,17 +556,22 @@ const INTENSITY_CLAUSES = clausesOf(TRANSITION_INTENSITIES)
  *
  * Behavior:
  * - 0 hints (no transition, empty array, or all-empty hints) → ""
- * - n base hints joined with ", and "
+ * - each pick rendered `<term> (<hint body>)` (`renderTransitionBases`),
+ *   n picks joined with ", and "
  * - Timing/start/end clauses apply ONCE at the outer layer, not per-id
- * - The duration clause is dropped when every picked id is instant (a cut —
- *   see `isInstantTransition`); position and intensity still apply
+ * - When every picked id is instant (a cut — see `isInstantTransition`) the
+ *   first base's parentheses carry `INSTANT_CUT_CLAUSE` once, and the
+ *   duration and intensity clauses are dropped; position still applies,
+ *   except `full` — a single-frame cut spans nothing, so it adds no clause
  * - null input is treated like undefined (falsy short-circuit → returns "")
  *
- * @param mode `"compact"` builds the base from each transition's short
- *   professional `term` ("hard cut") instead of its full mechanism paragraph.
- *   Everything else — the ", and " multi-pick join, the position/duration/
- *   intensity clauses, and the "starting from"/"ending at" clauses — is
- *   emitted identically in both modes.
+ * @param mode Accepted for the picker-hint signature; a transition composes
+ *   the same text in both modes — each pick as `<term> (<hint body>)`, see
+ *   `renderTransitionBases`.
+ * @param options `scope: "shot"` when the hint is folded into one shot's time
+ *   window of a multi-shot prompt — the position clause then says "of this
+ *   shot" instead of "of the clip" (and `full`, on a non-cut, "spans this
+ *   entire shot"). Omitted, the wording is the clip's.
  */
 export function composeTransitionHintFromConnections(
   transitionId: string | ReadonlyArray<string> | undefined,
@@ -440,32 +579,33 @@ export function composeTransitionHintFromConnections(
   endHints: ReadonlyArray<string>,
   timing?: TransitionTiming,
   mode: PickerHintMode = "full",
+  options?: TransitionHintOptions,
 ): string {
   const ids = Array.isArray(transitionId)
     ? Array.from(new Set(transitionId)).slice(0, 2)
     : transitionId ? [transitionId] : []
-  // ONLY the base fragment swaps in compact mode — the multi-pick join, the
-  // timing clauses and the start/end clauses below are identical either way.
-  const resolveBase = mode === "compact" ? getTransitionTerm : getTransitionPromptHint
-  // Only ids that contribute a base hint count below — a no-op "auto" beside a
-  // cut must not make the pick look non-instant.
-  const picked = ids.filter((id) => resolveBase(id).length > 0)
-  const baseHints = picked.map(resolveBase)
+  const baseHints = renderTransitionBases(ids, mode)
   if (baseHints.length === 0) return ""
+  // Same "contributes a fragment" filter `renderTransitionBases` applies.
+  const instant = isInstantTransition(ids.filter((id) => getTransitionTerm(id).length > 0))
 
   const combinedBase = baseHints.join(", and ")
   const parts: string[] = [combinedBase]
 
-  if (timing?.position && timing.position !== "auto") {
-    parts.push(POSITION_CLAUSES[timing.position])
+  // "Spans the entire clip" beside a single-frame cut contradicts it, so an
+  // all-instant pick drops `full`; start / middle / end still place the cut.
+  if (timing?.position && timing.position !== "auto" && !(instant && timing.position === "full")) {
+    const clauses = options?.scope === "shot" ? SHOT_POSITION_CLAUSES : POSITION_CLAUSES
+    parts.push(clauses[timing.position])
   }
-  // A cut has no duration: "lasting approximately 1 second" on a match cut
-  // makes the model render a one-second dissolve. Skipped only when EVERY
-  // picked id is instant — a mixed pick still has a non-cut to time.
-  if (timing?.duration && timing.duration !== "auto" && !isInstantTransition(picked)) {
+  // A cut has no duration and no performance: "lasting approximately 1
+  // second" or "with natural timing" on a match cut makes the model
+  // render a dissolve. Skipped only when EVERY picked id is instant — a mixed
+  // pick still has a non-cut to time and shape.
+  if (timing?.duration && timing.duration !== "auto" && !instant) {
     parts.push(DURATION_CLAUSES[timing.duration])
   }
-  if (timing?.intensity && timing.intensity !== "auto") {
+  if (timing?.intensity && timing.intensity !== "auto" && !instant) {
     parts.push(INTENSITY_CLAUSES[timing.intensity])
   }