@nodaro/prompts 1.21.0 → 1.25.0

package/src/transitions.ts

@@ -41,6 +41,30 @@ export interface Transition {
    * "invisible cut"). Everywhere else the label IS the term.
    */
   readonly term?: string
+  /**
+   * `true` on rows whose mechanism IS A CUT — the change happens between two
+   * frames, so it has no duration to time. A duration clause ("lasting
+   * approximately 1 second") on such a row tells the video model to spend a
+   * 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.
+   *
+   * 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
 }
 
 /**
@@ -73,7 +97,7 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   // ============================================================================
   { id: "auto",              label: "Auto",              category: "standard", description: "Let the model choose", promptHint: "" },
   { id: "none",              label: "None / Hard Cut",   category: "standard", description: "Instantaneous switch, no transition",
-    promptHint: "no transition, hard cut, instantaneous switch from first shot to second shot", term: "hard cut" },
+    promptHint: "no transition, hard cut, instantaneous switch from first shot to second shot", term: "hard cut" , instant: true },
   { id: "cross-dissolve",    label: "Cross-Dissolve",    category: "standard", description: "Gradual blend between shots",
     promptHint: "smooth cross-dissolve transition where the first shot gradually fades out as the second shot fades in" },
   { id: "fade-to-black",     label: "Fade to Black",     category: "standard", description: "Darkens to black, second emerges",
@@ -81,11 +105,11 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "fade-to-white",     label: "Fade to White",     category: "standard", description: "Blooms to white, second emerges",
     promptHint: "fade to white: the first shot brightens until the frame is pure white, then the second shot resolves out of the white" },
   { id: "snap-to-black",     label: "Snap to Black",     category: "standard", description: "Instant cut to full black for a beat, then the next shot",
-    promptHint: "snap to black: the first shot cuts instantly to full black with no fade, the frame holds pure black for a single beat, then the second shot cuts in at full brightness", term: "snap to black" },
+    promptHint: "snap to black: the first shot cuts instantly to full black with no fade, the frame holds pure black for a single beat, then the second shot cuts in at full brightness", term: "snap to black" , instant: true },
   { id: "match-cut",         label: "Match Cut",         category: "standard", description: "Shape or motion match across shots",
-    promptHint: "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" },
+    promptHint: "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: true },
   { id: "smash-cut",         label: "Smash Cut",         category: "standard", description: "Jarring abrupt cut between contrasting shots",
-    promptHint: "smash cut: an abrupt jarring transition between two visually or tonally contrasting shots with no fade, on a beat" },
+    promptHint: "smash cut: an abrupt jarring transition between two visually or tonally contrasting shots with no fade, on a beat" , instant: true },
   { id: "iris",              label: "Iris",              category: "standard", description: "Circular iris closes, then opens on second",
     promptHint: "iris transition: a circular vignette closes inward over the first shot until the frame is black, then opens outward to reveal the second shot", term: "iris wipe" },
   { id: "wipe",              label: "Wipe",              category: "standard", description: "Linear wipe replaces first shot",
@@ -93,11 +117,11 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "roll-transition",   label: "Roll",              category: "standard", description: "Frame rolls 90-180°, second shot upright on landing",
     promptHint: "the frame rolls along the camera axis with a smooth 90 to 180 degree rotation, motion-blurred during the roll, and as the rotation completes the new shot is upright and stable in frame", term: "camera roll transition" },
   { id: "seamless-match",    label: "Seamless Match",    category: "standard", description: "Hidden cut disguised by matched motion and color",
-    promptHint: "hidden seamless transition: the camera motion, color palette, and on-screen motion at the end of the first shot continue exactly across the cut into the second shot, so the boundary is invisible and the two shots feel like one unbroken take", term: "invisible cut" },
+    promptHint: "hidden seamless transition: the camera motion, color palette, and on-screen motion at the end of the first shot continue exactly across the cut into the second shot, so the boundary is invisible and the two shots feel like one unbroken take", term: "invisible cut" , instant: true },
   { id: "whip-pan",          label: "Whip Pan",          category: "standard", description: "Camera whips sideways into blur, next shot rides the same direction",
     promptHint: "whip pan transition: 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", term: "whip pan" },
   { id: "jump-cut",          label: "Jump Cut",          category: "standard", description: "Same framing, time skips forward",
-    promptHint: "jump cut: the framing, lens, and camera position stay identical across the cut while time skips abruptly forward, so the subject snaps to a new position inside what still reads as one continuous shot", term: "jump cut" },
+    promptHint: "jump cut: the framing, lens, and camera position stay identical across the cut while time skips abruptly forward, so the subject snaps to a new position inside what still reads as one continuous shot", term: "jump cut" , instant: true },
 
   // ============================================================================
   // TIME — 8 entries — temporal shifts (same or related scene, different time, or memory)
@@ -109,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" },
   { 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",
@@ -181,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",
@@ -191,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",
@@ -219,11 +243,11 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "vehicle-explosion", label: "Vehicle Explosion",  category: "physics", description: "Vehicle detonates in foreground, scene changes behind",
     promptHint: "a vehicle in the foreground erupts in a violent explosion of fire and twisted metal, the fireball expands toward the camera and washes the frame in orange flame, and as the smoke parts the second scene resolves" },
   { id: "jump-match",        label: "Jump Match",         category: "physics", description: "Subject jumps, landing matches into new scene",
-    promptHint: "the subject jumps upward and out of frame at the end of the first shot, with matched velocity the camera follows the arc, and on landing the subject is in a new location seamlessly continuing the same jump", term: "match cut on a jump" },
+    promptHint: "the subject jumps upward and out of frame at the end of the first shot, with matched velocity the camera follows the arc, and on landing the subject is in a new location seamlessly continuing the same jump", term: "match cut on a jump" , instant: true },
   { id: "hand-swipe",        label: "Hand Swipe",         category: "physics", description: "Hand swipes across lens, scene changes during occlusion",
     promptHint: "a hand sweeps across the camera lens at close range, fully occluding the frame in motion blur for a single beat, and as the hand exits the opposite side the scene has changed to the new setting" },
   { id: "action-relay",      label: "Action Match",      category: "physics", description: "Subject exits on an action and lands in the new scene mid-move",
-    promptHint: "match cut on action: the subject exits the frame on a committed action — a stride, a throw, a turn — and enters the new scene on the same beat continuing that movement at matched speed and direction, so the action carries unbroken across the cut", term: "match cut on action" },
+    promptHint: "match cut on action: the subject exits the frame on a committed action — a stride, a throw, a turn — and enters the new scene on the same beat continuing that movement at matched speed and direction, so the action carries unbroken across the cut", term: "match cut on action" , instant: true },
 
   // ============================================================================
   // LIGHT — 8 entries — flash and lens FX
@@ -314,6 +338,116 @@ export function getTransitionTerm(id: string | undefined | null): string {
 
 export const TRANSITION_IDS: ReadonlyArray<string> = TRANSITIONS.map((t) => t.id)
 
+/**
+ * Whether a transition is a CUT — instantaneous by nature, so it takes no
+ * duration (see `Transition.instant`). Reads through `getTransition`, so it
+ * answers for the same entry every other getter describes; an unknown id, the
+ * no-op "auto" and an empty value are all `false`.
+ *
+ * A multi-pick (`string[]`) is instant only when EVERY picked id is: a cut
+ * paired with a dissolve still has a dissolve to time.
+ */
+export function isInstantTransition(
+  id: string | ReadonlyArray<string> | undefined | null,
+): boolean {
+  const ids = typeof id === "string" ? [id] : id ? [...id] : []
+  if (ids.length === 0) return false
+  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
 // ---------------------------------------------------------------------------
@@ -359,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>
@@ -382,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)
 
@@ -393,15 +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
+ * - 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,
@@ -409,26 +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
-  const baseHints = ids.map(resolveBase).filter((h) => h.length > 0)
+  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])
   }
-  if (timing?.duration && timing.duration !== "auto") {
+  // 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])
   }
 

package/src/video-reference-resolver.ts

@@ -46,7 +46,7 @@ import { insertBeforeStyleSection } from "./prompt-style-section.js"
 // The binding surface string and the id-addressed token resolver live in their
 // own modules (see them for the contracts); re-exported here so every existing
 // importer of this module — and the package index's `export *` — keeps working.
-export { REF_BINDING, identityRefsSentence } from "./ref-binding.js"
+export { REF_BINDING, identityRefsSentence, SEEDANCE_VIDEO_EDIT_PREFIX, buildSeedanceVideoEditPrompt } from "./ref-binding.js"
 export { resolveRefIdTokens, type RefIdTokenContext } from "./ref-id-tokens.js"