@nodaro/prompts 1.7.2 → 1.8.0

package/src/temporal.ts

@@ -15,6 +15,8 @@
  * frontend DAG executor and the backend orchestrator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type TemporalCategory = "speed" | "freeze" | "direction" | "shutter"
 
 export interface Temporal {
@@ -23,33 +25,43 @@ export interface Temporal {
   readonly category: TemporalCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Compact professional term injected in compact hint mode (see `term.ts`).
+   *
+   * Authored where the picker label is a UI compound ("Reverse / Rewind",
+   * "Loop / Boomerang") or a bare word that reads as something else entirely
+   * inside a prompt — "Forward" as a camera move rather than playback
+   * direction, "Moving Subject" as a plain description of the action rather
+   * than the frozen-world effect it selects here.
+   */
+  readonly term?: string
 }
 
 export const TEMPORALS: ReadonlyArray<Temporal> = [
   // Speed (6)
-  { id: "real-time",      label: "Real-time",         category: "speed",     description: "Normal playback speed",                   promptHint: "real-time playback, normal speed" },
+  { id: "real-time",      label: "Real-time",         category: "speed",     description: "Normal playback speed",                   promptHint: "real-time playback, normal speed", term: "real-time playback" },
   { id: "slow-motion",    label: "Slow Motion",       category: "speed",     description: "Moderately slowed footage",               promptHint: "slow motion, footage slowed down with smooth deliberate movement" },
-  { id: "super-slow-mo",  label: "Super Slow-mo",     category: "speed",     description: "Extremely slow footage",                  promptHint: "super slow motion, extreme high-speed slow-mo capturing motion at a fraction of real time" },
+  { id: "super-slow-mo",  label: "Super Slow-mo",     category: "speed",     description: "Extremely slow footage",                  promptHint: "super slow motion, extreme high-speed slow-mo capturing motion at a fraction of real time", term: "super slow motion" },
   { id: "time-lapse",     label: "Time-lapse",        category: "speed",     description: "Compressed time, fast passage",           promptHint: "time-lapse, highly compressed time showing hours or days passing in seconds" },
   { id: "hyper-lapse",    label: "Hyper-lapse",       category: "speed",     description: "Moving time-lapse",                       promptHint: "hyper-lapse, time-lapse combined with forward camera motion, accelerated movement through space" },
   { id: "speed-ramp",     label: "Speed Ramp",        category: "speed",     description: "Dynamic speed change mid-shot",           promptHint: "speed ramp, dynamic speed change within the shot from slow motion to real-time or faster" },
 
   // Freeze (4)
-  { id: "full-freeze",    label: "Full Freeze-frame", category: "freeze",    description: "All motion frozen",                       promptHint: "full freeze-frame, all motion in the scene completely frozen like a photograph" },
+  { id: "full-freeze",    label: "Full Freeze-frame", category: "freeze",    description: "All motion frozen",                       promptHint: "full freeze-frame, all motion in the scene completely frozen like a photograph", term: "freeze frame" },
   { id: "bullet-time",    label: "Bullet Time",       category: "freeze",    description: "Subject frozen, camera orbits",           promptHint: "bullet time effect, subject completely frozen mid-motion while camera orbits around them, Matrix-style" },
-  { id: "frozen-subject", label: "Frozen Subject",    category: "freeze",    description: "Subject frozen, world moves",             promptHint: "frozen subject with moving world, subject remains completely still while the environment continues in motion" },
-  { id: "moving-subject", label: "Moving Subject",    category: "freeze",    description: "Subject moves, world frozen",             promptHint: "moving subject with frozen world, subject continues in motion while everything else in the scene is completely frozen" },
+  { id: "frozen-subject", label: "Frozen Subject",    category: "freeze",    description: "Subject frozen, world moves",             promptHint: "frozen subject with moving world, subject remains completely still while the environment continues in motion", term: "frozen subject, world in motion" },
+  { id: "moving-subject", label: "Moving Subject",    category: "freeze",    description: "Subject moves, world frozen",             promptHint: "moving subject with frozen world, subject continues in motion while everything else in the scene is completely frozen", term: "moving subject, frozen world" },
 
   // Direction (3)
-  { id: "forward",        label: "Forward",           category: "direction", description: "Normal forward playback",                 promptHint: "forward playback, time moving forward in the natural direction" },
-  { id: "reverse",        label: "Reverse / Rewind",  category: "direction", description: "Time plays backwards",                    promptHint: "reverse playback, time and motion running backwards" },
-  { id: "loop-boomerang", label: "Loop / Boomerang",  category: "direction", description: "Forward then reverse",                    promptHint: "boomerang loop, playing forward then reversing back, creating a looping motion" },
+  { id: "forward",        label: "Forward",           category: "direction", description: "Normal forward playback",                 promptHint: "forward playback, time moving forward in the natural direction", term: "forward playback" },
+  { id: "reverse",        label: "Reverse / Rewind",  category: "direction", description: "Time plays backwards",                    promptHint: "reverse playback, time and motion running backwards", term: "reverse playback" },
+  { id: "loop-boomerang", label: "Loop / Boomerang",  category: "direction", description: "Forward then reverse",                    promptHint: "boomerang loop, playing forward then reversing back, creating a looping motion", term: "boomerang loop" },
 
   // Shutter (5)
   { id: "long-exposure",  label: "Long Exposure",     category: "shutter",   description: "Motion trails and streaks",               promptHint: "long exposure effect, motion trails and light streaks from slow shutter speed" },
-  { id: "crisp-shutter",  label: "Crisp Shutter",     category: "shutter",   description: "Sharp motion, no blur",                   promptHint: "crisp shutter, sharp motion captured with fast shutter speed and no motion blur" },
+  { id: "crisp-shutter",  label: "Crisp Shutter",     category: "shutter",   description: "Sharp motion, no blur",                   promptHint: "crisp shutter, sharp motion captured with fast shutter speed and no motion blur", term: "fast shutter, sharp motion" },
   { id: "motion-blur",    label: "Motion Blur",       category: "shutter",   description: "Pronounced directional blur",             promptHint: "pronounced motion blur, moving subjects blur directionally from slower-than-normal shutter speed" },
-  { id: "stutter-strobe", label: "Stutter / Strobe",  category: "shutter",   description: "Strobe-effect jerky motion",              promptHint: "stutter or strobe effect, jerky discontinuous motion with visible frame steps" },
+  { id: "stutter-strobe", label: "Stutter / Strobe",  category: "shutter",   description: "Strobe-effect jerky motion",              promptHint: "stutter or strobe effect, jerky discontinuous motion with visible frame steps", term: "strobe stutter effect" },
   { id: "stop-motion",    label: "Stop-motion",       category: "shutter",   description: "Stepped frame-by-frame motion",           promptHint: "stop-motion animation style, stepped frame-by-frame motion with characteristic discrete movement" },
 ] as const
 
@@ -85,6 +97,16 @@ export function getTemporalPromptHint(id: string | undefined | null): string {
   return getTemporal(id)?.promptHint ?? ""
 }
 
+/**
+ * The COMPACT counterpart of `getTemporalPromptHint`: the short professional
+ * term ("super slow motion", "reverse playback", "boomerang loop") a consumer
+ * injects instead of the full mechanism description. Same lookup, same
+ * empty-string-on-miss behavior.
+ */
+export function getTemporalTerm(id: string | undefined | null): string {
+  return resolveTerm(getTemporal(id))
+}
+
 export const TEMPORAL_IDS: ReadonlyArray<string> = TEMPORALS.map((t) => t.id)
 
 /**
@@ -121,6 +143,34 @@ export interface TemporalValue {
 const TEMPORAL_FIELDS_IN_ORDER: ReadonlyArray<readonly [keyof TemporalValue, TemporalCategory]> =
   TEMPORAL_CATEGORY_ORDER.map((cat) => [TEMPORAL_FIELD_BY_CATEGORY[cat], cat] as const)
 
+type TemporalHintData = Record<string, unknown> & {
+  temporalSpeed?: unknown
+  temporalFreeze?: unknown
+  temporalDirection?: unknown
+  temporalShutter?: unknown
+}
+
+/**
+ * The one walk over the per-category temporal fields, parameterized by how a
+ * single selected id turns into a fragment. `buildTemporalHints` (verbose) and
+ * `buildTemporalTerms` (compact) both delegate here, so the two can never
+ * disagree about WHICH ids contribute or in what order — only about how each
+ * one is phrased.
+ */
+function collectTemporalFragments(
+  data: TemporalHintData,
+  fragmentFor: (id: string) => string,
+): string[] {
+  const out: string[] = []
+  for (const [field] of TEMPORAL_FIELDS_IN_ORDER) {
+    const id = data[field]
+    if (typeof id !== "string" || id.length === 0) continue
+    const fragment = fragmentFor(id)
+    if (fragment) out.push(fragment)
+  }
+  return out
+}
+
 /**
  * Aggregate all enabled per-category temporal prompt hints from a consumer's
  * data, in canonical category order (speed, freeze, direction, shutter).
@@ -139,13 +189,25 @@ export function buildTemporalHints(
     temporalDirection?: unknown
     temporalShutter?: unknown
   },
+  mode: PickerHintMode = "full",
 ): string[] {
-  const hints: string[] = []
-  for (const [field] of TEMPORAL_FIELDS_IN_ORDER) {
-    const id = data[field]
-    if (typeof id !== "string" || id.length === 0) continue
-    const hint = getTemporalPromptHint(id)
-    if (hint) hints.push(hint)
-  }
-  return hints
+  if (mode === "compact") return buildTemporalTerms(data)
+  return collectTemporalFragments(data, getTemporalPromptHint)
+}
+
+/**
+ * The COMPACT counterpart of `buildTemporalHints`: the same per-category walk
+ * in the same canonical order, emitting each selection's short professional
+ * term ("super slow motion", "bullet time", "reverse playback") instead of its
+ * full mechanism description.
+ */
+export function buildTemporalTerms(
+  data: Record<string, unknown> & {
+    temporalSpeed?: unknown
+    temporalFreeze?: unknown
+    temporalDirection?: unknown
+    temporalShutter?: unknown
+  },
+): string[] {
+  return collectTemporalFragments(data, getTemporalTerm)
 }

package/src/term.ts

@@ -0,0 +1,155 @@
+/**
+ * Compact professional TERMS for picker-catalog entries.
+ *
+ * Every picker catalog entry carries a long `promptHint` — a full mechanism
+ * description injected downstream by `getParameterPromptHint`. A `term` is the
+ * SHORT form of the same entry: the two-to-four word phrase a professional
+ * would actually write in a prompt ("whip pan left", "hard cut", "medium
+ * close-up") when the consumer wants a compact instruction instead of a
+ * paragraph.
+ *
+ * The split of responsibilities is:
+ *   - `label`       → what USERS see in the picker.
+ *   - `promptHint`  → what MODELS read in verbose ("full") hint mode.
+ *   - `term`        → what MODELS read in compact hint mode.
+ *
+ * ---------------------------------------------------------------------------
+ * THE CONVENTION EVERY CATALOG FOLLOWS
+ * ---------------------------------------------------------------------------
+ * 1. The catalog's entry interface gains an OPTIONAL `term?: string`. It is
+ *    authored only where the label does not already read as the professional
+ *    term (see `isSuspiciousDerivedTerm` for the failure shapes); everywhere
+ *    else the lowercased label IS the term and no data is added.
+ * 2. Alongside each `get<Name>PromptHint(id)` getter, the catalog exports a
+ *    sibling `get<Name>Term(id)` implemented as
+ *      `export function get<Name>Term(id: string | undefined | null): string {
+ *         return resolveTerm(get<Name>(id))
+ *       }`
+ *    — same arity, same lookup, same empty-string-on-miss behavior, so the two
+ *    getters can never disagree about which entry they are describing.
+ * 3. An authored `term` is:
+ *      - lowercase,
+ *      - at most `TERM_MAX_CHARS` characters,
+ *      - at most 8 words,
+ *      - with NO trailing period,
+ *      - phrased the way a professional cinematographer / photographer /
+ *        sound designer / stylist would write it in a prompt.
+ *    Entries with no standard trade term (exotic morph/portal transitions and
+ *    the like) get a short descriptive phrase instead — never a sentence, and
+ *    never the long `promptHint`.
+ * 4. An entry whose `promptHint` is `""` — the no-op "auto" / "none" entries —
+ *    injects NOTHING, so its resolved term is `""` too. `resolveTerm` enforces
+ *    that; do not author a `term` on such an entry expecting it to be used.
+ *
+ * A guard test (`__tests__/catalog-terms.test.ts`) walks every registered
+ * catalog and fails for entries whose label cannot be safely lowercased into a
+ * term and that have no explicit `term` authored — so the convention above is
+ * enforced, not merely documented.
+ */
+
+/** Hard cap on an authored/derived term. Longer than this is a hint, not a term. */
+export const TERM_MAX_CHARS = 60
+
+/**
+ * How verbose a picker node's injected fragment is.
+ *
+ *  - `"full"`    — the long `promptHint` (the historical, and still default,
+ *                  behavior; output is byte-identical to before hint modes
+ *                  existed).
+ *  - `"compact"` — the short professional `term` instead.
+ *
+ * ONLY the base catalog fragment swaps. The user's `preText` / `postText`
+ * free text, the transition / camera-motion / character-fx timing and
+ * start-state/end-state clauses, multi-pick joining, and multi-dimension
+ * composition all apply exactly the same in both modes.
+ *
+ * "The same" means the same MEANING, not always the same string. Where a
+ * wrapper is grammatically fused to the long hint it cannot simply be reused:
+ * the character-fx composer names its target by rewriting the words "the
+ * subject" inside a full hint, and a bare term has no such words, so compact
+ * mode names the target with an explicit `"{target}: {effect}"` prefix. When a
+ * catalog's grammar IS its meaning — Material's `"made of ..."`, Held Prop's
+ * `"holding a ..."` — that grammar is authored into the term itself rather
+ * than left for a consumer to re-add, because a projected `term` is injected
+ * standalone by thin clients that have no composer at all.
+ *
+ * A picker node selects the mode via an optional `hintMode` field on its node
+ * data; absent (or any unrecognized value) means `"full"`.
+ */
+export type PickerHintMode = "full" | "compact"
+
+/**
+ * The minimal shape of a catalog entry that can resolve a term: an id, the
+ * user-facing label, the long hint (whose emptiness marks a no-op entry), and
+ * the optional authored short term.
+ */
+export interface TermCarrier {
+  readonly id: string
+  readonly label: string
+  readonly promptHint: string
+  readonly term?: string
+}
+
+/** Parenthetical segments — "Ultra-wide (14mm)", "ISO 1600 (visible grain)". */
+const PARENTHETICAL = /\([^)]*\)/g
+
+/**
+ * Mechanical label → term derivation: lowercase, drop parenthetical segments,
+ * collapse whitespace, trim.
+ *
+ * Deliberately NOT clever: it does not split on "/" or strip category nouns.
+ * A label like "None / Hard Cut" or "Fog / Mist" has to SURFACE as suspicious
+ * (see `isSuspiciousDerivedTerm`) so a human authors the right term — guessing
+ * here would quietly inject the wrong wording into every prompt.
+ */
+export function deriveTerm(label: string): string {
+  return label
+    .replace(PARENTHETICAL, " ")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+/** Punctuation that marks a UI compound / annotation rather than a trade term. */
+const SUSPICIOUS_CHARS = ["/", "(", ")", ":", "&", "→", "×"] as const
+
+export interface SuspiciousTermOptions {
+  /**
+   * Treat a single-word derived term as suspicious. Set for catalogs whose
+   * labels are bare MODIFIERS that only read as a professional term with
+   * their category noun attached — lighting "Short" → "short lighting",
+   * color-look "Warm" → "warm grade".
+   */
+  readonly bareWordSuspicious?: boolean
+}
+
+/**
+ * Is the mechanically-derived term unsafe to inject as-is?
+ *
+ * True when the label is a UI compound or carries an annotation ("None / Hard
+ * Cut", "Ultra-wide (14mm)", "Key: Rembrandt"), when nothing survives the
+ * derivation, or — under `bareWordSuspicious` — when the result is a lone word
+ * that needs its category noun to mean anything to a model.
+ */
+export function isSuspiciousDerivedTerm(
+  label: string,
+  opts: SuspiciousTermOptions = {},
+): boolean {
+  if (SUSPICIOUS_CHARS.some((c) => label.includes(c))) return true
+  const derived = deriveTerm(label)
+  if (derived.length === 0) return true
+  if (opts.bareWordSuspicious && !derived.includes(" ")) return true
+  return false
+}
+
+/**
+ * The single resolution point every consumer reads: an explicit `term` when
+ * the catalog authored one, the derived label otherwise, and `""` for a no-op
+ * entry (missing entry, or an "auto"/"none" entry whose `promptHint` is empty
+ * and which therefore injects nothing).
+ */
+export function resolveTerm(entry: TermCarrier | undefined | null): string {
+  if (!entry) return ""
+  if (entry.promptHint === "") return ""
+  return entry.term ?? deriveTerm(entry.label)
+}

package/src/transitions.ts

@@ -12,6 +12,8 @@
  * "starting from <X>, ending at <Y>".
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type TransitionCategory =
   | "standard"
   | "time"
@@ -28,6 +30,16 @@ export interface Transition {
   readonly category: TransitionCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Optional authored compact term (see `term.ts`). Authored where the
+   * lowercased label is not what an editor would write in a prompt — a UI
+   * compound ("None / Hard Cut" → "hard cut"), an annotation the derivation
+   * drops ("Fast-Forward (Day → Night)" → "day-to-night time-lapse"), a bare
+   * word that collides with another meaning ("Melt Down", "Channel Flip",
+   * "Roll"), or a coinage that is not the trade term ("Seamless Match" →
+   * "invisible cut"). Everywhere else the label IS the term.
+   */
+  readonly term?: string
 }
 
 export type TransitionPosition = "auto" | "start" | "middle" | "end" | "full"
@@ -42,47 +54,53 @@ export interface TransitionTiming {
 
 export const TRANSITIONS: ReadonlyArray<Transition> = [
   // ============================================================================
-  // STANDARD — 11 entries — classical editing transitions
+  // STANDARD — 14 entries — classical editing transitions
   // ============================================================================
   { 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" },
+    promptHint: "no transition, hard cut, instantaneous switch from first shot to second shot", term: "hard cut" },
   { 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",
     promptHint: "fade to black: the first shot gradually darkens to full black, holds briefly, then the second shot fades up from black" },
   { 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" },
   { 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" },
   { 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" },
   { 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" },
+    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",
-    promptHint: "linear wipe transition: a clean diagonal line sweeps across the frame, revealing the second shot behind it" },
+    promptHint: "linear wipe transition: a clean diagonal line sweeps across the frame, revealing the second shot behind it", term: "linear wipe" },
   { 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" },
+    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" },
+    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" },
+  { 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" },
 
   // ============================================================================
   // TIME — 8 entries — temporal shifts (same or related scene, different time, or memory)
   // ============================================================================
   { id: "fast-forward-day-night",  label: "Fast-Forward (Day → Night)", category: "time", description: "Time-lapse day to night same scene",
-    promptHint: "fast-forward time-lapse transition: the sun visibly arcs across the sky, shadows sweep, clouds streak, sky shifts from daylight blue through golden hour to deep night, stars emerge, all while framing and camera position remain locked on the same scene" },
+    promptHint: "fast-forward time-lapse transition: the sun visibly arcs across the sky, shadows sweep, clouds streak, sky shifts from daylight blue through golden hour to deep night, stars emerge, all while framing and camera position remain locked on the same scene", term: "day-to-night time-lapse" },
   { id: "fast-forward-night-day",  label: "Fast-Forward (Night → Day)", category: "time", description: "Time-lapse night to dawn same scene",
-    promptHint: "fast-forward time-lapse transition: stars fade, the sky shifts from deep night through pre-dawn blue to golden sunrise, shadows sweep in reverse, all while framing and camera position remain locked on the same scene" },
+    promptHint: "fast-forward time-lapse transition: stars fade, the sky shifts from deep night through pre-dawn blue to golden sunrise, shadows sweep in reverse, all while framing and camera position remain locked on the same scene", term: "night-to-day time-lapse" },
   { 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" },
+    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" },
+    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" },
   { 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" },
+    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" },
+    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" },
   { 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" },
+    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",
     promptHint: "brief flashback transition: the frame washes with a soft warm or desaturated tint, faint ripple distortion crosses the image as the present scene fades, and a remembered earlier moment resolves into focus on the same subject" },
 
@@ -96,7 +114,7 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "sand-scatter",      label: "Sand Scatter",       category: "element", description: "Subject becomes sand, blown away, reforms",
     promptHint: "the subject crumbles into fine sand that is swept away by a gust of wind in a swirling vortex, then the sand particles converge and re-form into the new subject" },
   { id: "fire-burnup",       label: "Burn-Up",            category: "element", description: "Subject burns to embers, embers reform",
-    promptHint: "the subject ignites and burns from edges inward into glowing embers and ash, the embers swirl through the frame and re-ignite into the new subject" },
+    promptHint: "the subject ignites and burns from edges inward into glowing embers and ash, the embers swirl through the frame and re-ignite into the new subject", term: "burn to embers and reform" },
   { id: "smoke-puff",        label: "Smoke Puff",         category: "element", description: "Subject vanishes in smoke, reappears",
     promptHint: "the subject vanishes in a soft puff of smoke that billows outward and fills the frame, the smoke then clears to reveal the new subject in the new scene" },
   { id: "magic-sparkles",    label: "Magic Sparkles",     category: "element", description: "Particle dissolve à la Avengers / apparition",
@@ -112,7 +130,7 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "aurora-sweep",      label: "Aurora Sweep",       category: "element", description: "Aurora curtain sweeps across, scene changes behind",
     promptHint: "a luminous green and violet aurora curtain ripples across the entire frame, the bright bands obscure the first scene, and as the aurora dissipates the second scene resolves in the clear sky" },
   { id: "sakura-petals",     label: "Sakura Storm",       category: "element", description: "Cherry blossom petals storm across the frame",
-    promptHint: "a dense storm of cherry blossom petals swirls in from one side and fills the frame in soft pink motion, the petals cluster to fully veil the image, then drift past to reveal the new scene" },
+    promptHint: "a dense storm of cherry blossom petals swirls in from one side and fills the frame in soft pink motion, the petals cluster to fully veil the image, then drift past to reveal the new scene", term: "cherry blossom petal storm" },
   { id: "garden-bloom",      label: "Garden Bloom",       category: "element", description: "Flowers bloom outward, parting to reveal new scene",
     promptHint: "lush flowers and vines rapidly grow and bloom outward from the edges of the frame, the foliage spreads to overtake the entire image, then parts open like curtains to reveal the new scene behind" },
   { id: "powder-burst",      label: "Powder Burst",       category: "element", description: "Colored powder bursts across frame and clears",
@@ -124,9 +142,9 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "liquid-morph",      label: "Liquid Morph",       category: "morph", description: "Subject melts and reforms as new subject",
     promptHint: "smooth liquid morph: the first subject's surface becomes fluid and continuously deforms, flowing without breaks into the silhouette and details of the second subject" },
   { id: "pixelate-reform",   label: "Pixelate & Reform",  category: "morph", description: "Pixelates, scatters, reforms as new",
-    promptHint: "the first subject pixelates into large mosaic blocks that scatter outward across the frame, then the blocks converge and resolve into the new subject" },
+    promptHint: "the first subject pixelates into large mosaic blocks that scatter outward across the frame, then the blocks converge and resolve into the new subject", term: "pixelate and reform" },
   { id: "shatter-glass",     label: "Shatter & Reform",   category: "morph", description: "Subject shatters like glass, reforms",
-    promptHint: "the first subject shatters like glass into hundreds of shards that fly outward, then the shards reverse direction in reverse time and reassemble into the new subject" },
+    promptHint: "the first subject shatters like glass into hundreds of shards that fly outward, then the shards reverse direction in reverse time and reassemble into the new subject", term: "shatter like glass and reform" },
   { id: "origami-fold",      label: "Origami Fold",       category: "morph", description: "Subject folds like paper into new subject",
     promptHint: "the first subject creases and folds like sheets of origami paper, the folds rotate and re-arrange in elegant geometric steps, and the final fold reveals the new subject" },
   { id: "vortex-swirl",      label: "Vortex Swirl",       category: "morph", description: "Subject swirls into vortex, unwinds as new",
@@ -138,10 +156,10 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "polygon-shatter",   label: "Polygon Shatter",    category: "morph", description: "Subject fragments into low-poly chunks, reassembles",
     promptHint: "the first subject fractures into low-polygon faceted chunks that explode outward in slow motion, the polygons then reverse course and re-assemble in clean geometric flight paths into the silhouette of the new subject" },
   { id: "melt-down",         label: "Melt Down",          category: "morph", description: "Subject melts into puddle, reforms as new",
-    promptHint: "the first subject's form softens and melts downward like wax, collapsing into a glossy puddle on the ground, the puddle then surges upward and re-solidifies into the new subject standing in the new scene" },
+    promptHint: "the first subject's form softens and melts downward like wax, collapsing into a glossy puddle on the ground, the puddle then surges upward and re-solidifies into the new subject standing in the new scene", term: "melt into a puddle and reform" },
 
   // ============================================================================
-  // PORTAL — 10 entries — zoom-into-object world-jumps
+  // PORTAL — 12 entries — zoom-into-object world-jumps
   // ============================================================================
   { id: "zoom-into-eye",     label: "Zoom Into Eye",        category: "portal", description: "Push into pupil, new world inside",
     promptHint: "the camera pushes into a tight macro of the subject's eye, the pupil dilates and fills the frame, and the new scene materialises from within the pupil as if the pupil itself were a portal" },
@@ -156,16 +174,20 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "fall-into-hole",    label: "Fall Into Hole",       category: "portal", description: "Camera falls through opening",
     promptHint: "the floor or ground opens beneath the camera and the camera falls downward through the opening, tumbling, and emerges into the new scene below" },
   { 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" },
+    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" },
   { 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",
-    promptHint: "a translucent luminous form rises out of the first subject's body and shoots forward through the frame as a ghost-like soul, then dives into a new body in the new scene where the second subject animates to life" },
+    promptHint: "a translucent luminous form rises out of the first subject's body and shoots forward through the frame as a ghost-like soul, then dives into a new body in the new scene where the second subject animates to life", term: "soul leaves body and enters another" },
+  { id: "mask-transition",   label: "Mask Transition",   category: "portal", description: "Foreground object blacks out the frame, camera pulls through",
+    promptHint: "mask transition: a foreground object or a passer-by sweeps across the lens and fills the frame with darkness, the camera keeps travelling forward through the black, then pulls out of the darkness into the new scene", term: "mask transition" },
+  { id: "zoom-through",      label: "Zoom Through",      category: "portal", description: "Camera magnifies one detail until the new scene unfolds inside it",
+    promptHint: "zoom-through transition: the camera magnifies one small detail of the frame further and further until the detail loses its texture and fills the image entirely, and the new scene unfolds from within it", term: "zoom-through transition" },
 
   // ============================================================================
-  // PHYSICS — 9 entries — force-driven transitions
+  // PHYSICS — 10 entries — force-driven transitions
   // ============================================================================
   { id: "explosion-blast",   label: "Explosion Blast",    category: "physics", description: "Explosion wipes frame, new scene emerges",
     promptHint: "an explosion erupts from the center of the frame with a bright fireball that expands to fill the frame, and as the fireball dissipates the new scene is revealed" },
@@ -182,9 +204,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" },
+    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" },
   { 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" },
 
   // ============================================================================
   // LIGHT — 8 entries — flash and lens FX
@@ -216,11 +240,11 @@ export const TRANSITIONS: ReadonlyArray<Transition> = [
   { id: "datamosh",          label: "Datamosh",           category: "glitch", description: "Motion-vector smear bleeds scenes",
     promptHint: "datamosh transition: the motion vectors of the first scene continue smearing into the pixels of the second scene, creating a fluid pixel-bleed handoff" },
   { id: "channel-flip",      label: "Channel Flip",       category: "glitch", description: "TV channel flip with static",
-    promptHint: "a brief burst of TV static and channel-flip artifacts sweeps the frame, and the new scene resolves as if changing channels on an old television" },
+    promptHint: "a brief burst of TV static and channel-flip artifacts sweeps the frame, and the new scene resolves as if changing channels on an old television", term: "tv channel flip with static" },
   { id: "hologram-flicker",  label: "Hologram Flicker",   category: "glitch", description: "Hologram-style flicker materialises new scene",
     promptHint: "a hologram-style flicker with horizontal interference bands and chromatic aberration overtakes the frame for a beat, and resolves into the new scene as if it materialised from a projection" },
   { id: "display-wipe",      label: "Display Wipe",       category: "glitch", description: "Scene compresses into display, expands to new scene",
-    promptHint: "the first scene compresses into a small floating display screen at the center of the frame with a CRT power-on/off animation and scanline flicker, the display then expands outward and unfolds into the new scene full-frame" },
+    promptHint: "the first scene compresses into a small floating display screen at the center of the frame with a CRT power-on/off animation and scanline flicker, the display then expands outward and unfolds into the new scene full-frame", term: "compress into a screen and expand out" },
   { id: "double-exposure",   label: "Double Exposure",    category: "glitch", description: "Two scenes overlay translucent, first fades to second",
     promptHint: "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" },
 ]
@@ -260,6 +284,19 @@ export function getTransitionPromptHint(id: string | undefined | null): string {
   return getTransition(id)?.promptHint ?? ""
 }
 
+/**
+ * Compact professional TERM for an id — the short phrase an editor would write
+ * in a prompt ("hard cut", "invisible cut", "day-to-night time-lapse"), as
+ * opposed to the paragraph-length `promptHint`.
+ *
+ * Same lookup and same empty-string-on-miss behavior as
+ * `getTransitionPromptHint`, so the two can never disagree about which entry
+ * they describe. The no-op "Auto" entry resolves to `""` in both.
+ */
+export function getTransitionTerm(id: string | undefined | null): string {
+  return resolveTerm(getTransition(id))
+}
+
 export const TRANSITION_IDS: ReadonlyArray<string> = TRANSITIONS.map((t) => t.id)
 
 // ---------------------------------------------------------------------------
@@ -298,17 +335,27 @@ const INTENSITY_CLAUSES: Record<Exclude<TransitionIntensity, "auto">, string> =
  * - n base hints joined with ", and "
  * - Timing/start/end clauses apply ONCE at the outer layer, not per-id
  * - 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.
  */
 export function composeTransitionHintFromConnections(
   transitionId: string | ReadonlyArray<string> | undefined,
   startHints: ReadonlyArray<string>,
   endHints: ReadonlyArray<string>,
   timing?: TransitionTiming,
+  mode: PickerHintMode = "full",
 ): string {
   const ids = Array.isArray(transitionId)
     ? Array.from(new Set(transitionId)).slice(0, 2)
     : transitionId ? [transitionId] : []
-  const baseHints = ids.map(getTransitionPromptHint).filter((h) => h.length > 0)
+  // 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)
   if (baseHints.length === 0) return ""
 
   const combinedBase = baseHints.join(", and ")