@nodaro/prompts 1.28.0 → 1.29.0

package/src/__tests__/transition-timing-catalogs.test.ts

@@ -151,3 +151,44 @@ describe("transition timing catalogs", () => {
     expect(singlesWithDims).toEqual(["transition", "character-fx", "character-motion"])
   })
 })
+
+describe("the blended-cut flags on the picker catalog", () => {
+  // What a consumer that reads only `getPickerCatalog("transition")` (Studio) builds its Blend lever from:
+  // the blendable cut rows, and the duration step that blends them. See transitions-blended-cut.test.ts.
+  it("the transition options carry `blendable` on exactly seamless-match and jump-match, beside `instant`", () => {
+    const flagged = transitionCatalog.options!.filter((o) => o.blendable)
+    expect(flagged.map((o) => o.id)).toEqual(["seamless-match", "jump-match"])
+    for (const o of flagged) expect(o.instant, o.id).toBe(true)
+    expect(transitionCatalog.options!.some((o) => o.blendsCut)).toBe(false)
+  })
+
+  it("the `duration` dimension carries `blendsCut` on `short` only; the other dimensions carry neither flag", () => {
+    for (const dim of transitionCatalog.dimensions!) {
+      const blendsCut = dim.options.filter((o) => o.blendsCut).map((o) => o.id)
+      expect(blendsCut, dim.field).toEqual(dim.field === "duration" ? ["short"] : [])
+      expect(dim.options.some((o) => o.blendable), dim.field).toBe(false)
+    }
+  })
+
+  it("Character FX and Character Motion carry neither flag", () => {
+    for (const nodeType of ["character-fx", "character-motion"]) {
+      const cat = PICKER_CATALOGS.find((c) => c.nodeType === nodeType)!
+      const rows = [...(cat.options ?? []), ...(cat.dimensions ?? []).flatMap((d) => d.options)]
+      expect(rows.some((o) => o.blendable || o.blendsCut), nodeType).toBe(false)
+    }
+  })
+
+  it("the wire projection carries no cut flag, like `instant` (in-memory catalog only)", () => {
+    // Publishing them on `/v1/picker-catalogs` (and `@nodaro/shared` / the SDK) would be a deliberate,
+    // additive change carrying all three flags together, not drift.
+    for (const detail of ["compact", "full"] as const) {
+      const wire = projectPickerCatalog(transitionCatalog, { detail })
+      const rows = [...(wire.options ?? []), ...(wire.dimensions ?? []).flatMap((d) => d.options)]
+      for (const row of rows) {
+        for (const flag of ["instant", "blendable", "blendsCut"]) {
+          expect(Object.prototype.hasOwnProperty.call(row, flag), `${detail} ${row.id} ${flag}`).toBe(false)
+        }
+      }
+    }
+  })
+})

package/src/__tests__/transitions-blended-cut.test.ts

@@ -0,0 +1,325 @@
+/**
+ * THE BLENDED CUT (2026-10-04 test round). On `seamless-match` and `jump-match`, Duration `short` turns the
+ * hard cut into a blended cut: the anti-blend sentence inside the first pick's parentheses is REPLACED by
+ * "instead of a hard cut, the two shots blend into each other over about 1 second" ("about 1 second" is the
+ * `short` row's own term). Everything else about the clause is the hard cut's: the position clause (`full`
+ * dropped), no duration clause, no intensity clause.
+ *
+ * Everything else renders exactly as before: the two rows at Auto / Instant / Medium / Long, the other six
+ * cuts at every duration, every non-cut, every mixed pick, a blendable cut beside a cut that is not, and the
+ * direction fold (`renderTransitionBases`, which has no duration).
+ *
+ * The approved strings are pinned byte for byte from `fixtures/blended-cut-approved.json`: `approved` (the
+ * approved strings) and `ruleDerived` (the two-row multi-picks the approved rule produces) are copied from
+ * the review page, so a wording change there comes back for approval and is never made by hand. `hardCut`
+ * holds the same two rows at every other duration (today's hard cut); it shares their bodies, so a reword of
+ * either row changes it together with `approved`. Multi-picks with any other row are proven structurally
+ * below, so a reword of another row never touches this file.
+ */
+import { readFileSync } from "node:fs"
+import { describe, expect, it } from "vitest"
+import {
+  INSTANT_CUT_CLAUSE,
+  TRANSITIONS,
+  TRANSITION_DURATIONS,
+  TRANSITION_INTENSITIES,
+  TRANSITION_POSITIONS,
+  blendedCutClause,
+  composeTransitionHintFromConnections,
+  getTransitionTerm,
+  isBlendableTransition,
+  isInstantTransition,
+  renderTransitionBases,
+  type TransitionHintScope,
+  type TransitionTiming,
+  type TransitionTimingOption,
+} from "../transitions.js"
+import { renderDirectionHints } from "../direction-registry.js"
+
+type Case = {
+  readonly key: string
+  readonly ids: string | string[]
+  readonly timing: TransitionTiming
+  readonly scopes: TransitionHintScope[]
+  readonly text: string
+}
+const FIXTURE = JSON.parse(
+  readFileSync(new URL("./fixtures/blended-cut-approved.json", import.meta.url), "utf8"),
+) as { blendSentence: string; approved: Case[]; ruleDerived: Case[]; hardCut: Case[] }
+
+/** The approved sentence, typed once here so the test file itself shows it. */
+const BLEND = "instead of a hard cut, the two shots blend into each other over about 1 second"
+const BLENDABLE = ["seamless-match", "jump-match"] as const
+const CUTS = TRANSITIONS.filter((t) => t.instant).map((t) => t.id)
+const OTHER_CUTS = CUTS.filter((id) => !(BLENDABLE as readonly string[]).includes(id))
+const NON_CUTS = TRANSITIONS.filter((t) => !t.instant && t.id !== "auto").map((t) => t.id)
+const ALL_IDS = TRANSITIONS.map((t) => t.id)
+
+const POSITIONS = [undefined, ...TRANSITION_POSITIONS.map((o) => o.id)]
+const DURATIONS = [undefined, ...TRANSITION_DURATIONS.map((o) => o.id)]
+const INTENSITIES = [undefined, ...TRANSITION_INTENSITIES.map((o) => o.id)]
+const SCOPES: TransitionHintScope[] = ["clip", "shot"]
+
+const compose = (
+  ids: string | readonly string[],
+  timing: TransitionTiming | undefined,
+  scope: TransitionHintScope = "clip",
+  mode: "full" | "compact" = "full",
+) => composeTransitionHintFromConnections(ids as string | string[], [], [], timing, mode, { scope })
+
+/** Levers with every unset field left out, so `undefined` and an absent field are the same case. */
+function levers(position?: string, duration?: string, intensity?: string): TransitionTiming {
+  const t: Record<string, string> = {}
+  if (position !== undefined) t.position = position
+  if (duration !== undefined) t.duration = duration
+  if (intensity !== undefined) t.intensity = intensity
+  return t as TransitionTiming
+}
+
+const count = (haystack: string, needle: string) => haystack.split(needle).length - 1
+
+describe("blended cut — the catalog", () => {
+  it("marks exactly seamless-match and jump-match blendable, and both are cuts", () => {
+    expect(TRANSITIONS.filter((t) => t.blendable).map((t) => t.id)).toEqual([...BLENDABLE])
+    for (const id of BLENDABLE) expect(isInstantTransition(id), id).toBe(true)
+  })
+
+  it("marks exactly the `short` duration as the step that blends a cut, with a term to blend over", () => {
+    const rows = (TRANSITION_DURATIONS as ReadonlyArray<TransitionTimingOption>).filter((d) => d.blendsCut)
+    expect(rows.map((d) => d.id)).toEqual(["short"])
+    expect(rows[0]!.term).toBe("about 1 second")
+  })
+
+  it("the fixture carries the same sentence", () => {
+    expect(FIXTURE.blendSentence).toBe(BLEND)
+  })
+})
+
+describe("isBlendableTransition", () => {
+  it("is true for each blendable row and for the two together, in either order", () => {
+    for (const id of BLENDABLE) expect(isBlendableTransition(id), id).toBe(true)
+    expect(isBlendableTransition(["seamless-match", "jump-match"])).toBe(true)
+    expect(isBlendableTransition(["jump-match", "seamless-match"])).toBe(true)
+  })
+
+  it("is false for the other six cuts, every non-cut, mixed picks and empty values", () => {
+    expect(OTHER_CUTS).toEqual(["none", "snap-to-black", "match-cut", "smash-cut", "jump-cut", "action-relay"])
+    for (const id of [...OTHER_CUTS, ...NON_CUTS]) expect(isBlendableTransition(id), id).toBe(false)
+    expect(isBlendableTransition(["seamless-match", "match-cut"])).toBe(false)
+    expect(isBlendableTransition(["jump-match", "cross-dissolve"])).toBe(false)
+    expect(isBlendableTransition("auto")).toBe(false)
+    expect(isBlendableTransition("nonexistent")).toBe(false)
+    expect(isBlendableTransition("")).toBe(false)
+    expect(isBlendableTransition([])).toBe(false)
+    expect(isBlendableTransition(undefined)).toBe(false)
+    expect(isBlendableTransition(null)).toBe(false)
+  })
+})
+
+describe("blendedCutClause", () => {
+  it("`short` gives the approved sentence", () => {
+    expect(blendedCutClause("short")).toBe(BLEND)
+  })
+
+  it("every other value gives nothing", () => {
+    for (const d of ["auto", "instant", "medium", "long", "nonexistent", "", undefined]) {
+      expect(blendedCutClause(d), String(d)).toBe("")
+    }
+  })
+})
+
+describe("blended cut — the approved strings, byte for byte", () => {
+  it("the tile default of each row at Short (also inline, so the approved text reads here)", () => {
+    expect(compose("seamless-match", { duration: "short" })).toBe(
+      "invisible cut (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; instead of a hard cut, the two shots blend into each other over about 1 second)",
+    )
+    expect(compose("jump-match", { duration: "short" })).toBe(
+      "match cut on a jump (the subject launches into a jump, and at the height of the leap the picture cuts to " +
+        "a new place. The camera follows the arc of the jump at the same speed on both sides of the cut, and the " +
+        "subject stays at the same place in the frame. In the second shot the same jump carries on without a " +
+        "break, and the subject comes down and lands in the new place. The shot ends on the subject landed in the " +
+        "second shot, fully resolved; instead of a hard cut, the two shots blend into each other over about 1 second)",
+    )
+  })
+
+  it("covers 12 approved cases: both rows on a tile, mid-clip, mid-shot and in the END slot, and the ignored levers", () => {
+    expect(FIXTURE.approved.map((c) => c.key)).toEqual(
+      BLENDABLE.flatMap((id) =>
+        ["short|tile", "short|mid-clip", "short|mid-shot", "short|end-slot", "short+natural|tile", "short+full|clip"].map(
+          (seat) => `${id}|${seat}`,
+        ),
+      ),
+    )
+  })
+
+  it.each(FIXTURE.approved)("$key", ({ ids, timing, scopes, text }) => {
+    expect(count(text, BLEND)).toBe(1)
+    expect(text).not.toContain(INSTANT_CUT_CLAUSE)
+    for (const scope of scopes) {
+      expect(compose(ids, timing, scope), scope).toBe(text)
+      expect(compose(ids, timing, scope, "compact"), `${scope} compact`).toBe(text)
+    }
+  })
+})
+
+describe("blended cut — the multi-pick rule (both picks blendable, Short: the sentence once, in the first parentheses)", () => {
+  it("covers both orders of the two rows", () => {
+    expect(FIXTURE.ruleDerived).toHaveLength(8)
+  })
+
+  it.each(FIXTURE.ruleDerived)("$key", ({ ids, timing, scopes, text }) => {
+    expect(count(text, BLEND)).toBe(1)
+    expect(text).not.toContain(INSTANT_CUT_CLAUSE)
+    // The sentence rides the first pick; the second keeps its plain wording.
+    const [first] = renderTransitionBases(ids as string[])
+    expect(text.startsWith(first!.replace(INSTANT_CUT_CLAUSE, BLEND))).toBe(true)
+    for (const scope of scopes) expect(compose(ids, timing, scope), scope).toBe(text)
+  })
+
+  it("a blendable cut beside a cut that is not stays a hard cut", () => {
+    for (const pair of [["seamless-match", "match-cut"], ["none", "jump-match"], ["jump-match", "action-relay"]]) {
+      const out = compose(pair, { position: "middle", duration: "short", intensity: "natural" })
+      expect(out, pair.join("+")).toBe(compose(pair, { position: "middle" }))
+      expect(count(out, INSTANT_CUT_CLAUSE)).toBe(1)
+      expect(out).not.toContain(BLEND)
+    }
+  })
+
+  it("a cut beside a non-cut is unchanged: no cut sentence, and the duration and intensity clauses stay", () => {
+    for (const pair of [["seamless-match", "cross-dissolve"], ["whip-pan", "jump-match"]]) {
+      const out = compose(pair, { position: "end", duration: "short", intensity: "natural" })
+      expect(out).toBe(
+        renderTransitionBases(pair).join(", and ") +
+          ", the transition occurs at the end of the clip, lasting approximately 1 second, with natural timing",
+      )
+      expect(out).not.toContain(INSTANT_CUT_CLAUSE)
+      expect(out).not.toContain(BLEND)
+    }
+  })
+
+  it("a no-op `auto` beside a blendable cut does not stop the blend", () => {
+    for (const id of BLENDABLE) {
+      for (const pick of [["auto", id], [id, "auto"]]) {
+        expect(compose(pick, { position: "middle", duration: "short" }), pick.join("+")).toBe(
+          compose(id, { position: "middle", duration: "short" }),
+        )
+      }
+    }
+  })
+})
+
+describe("blended cut — what stays a hard cut", () => {
+  it.each(FIXTURE.hardCut)("today's text: $key", ({ ids, timing, scopes, text }) => {
+    expect(text).not.toContain(BLEND)
+    for (const scope of scopes) expect(compose(ids, timing, scope), scope).toBe(text)
+  })
+
+  it("the two rows at Auto, Instant, Medium and Long render the hard cut, at every position and intensity", () => {
+    for (const id of BLENDABLE) {
+      for (const duration of [undefined, "auto", "instant", "medium", "long"]) {
+        for (const position of POSITIONS) for (const intensity of INTENSITIES) for (const scope of SCOPES) {
+          const out = compose(id, levers(position, duration, intensity), scope)
+          expect(out, `${id} ${position} ${duration} ${intensity} ${scope}`).toBe(compose(id, levers(position), scope))
+          expect(count(out, INSTANT_CUT_CLAUSE)).toBe(1)
+          expect(out).not.toContain(BLEND)
+        }
+      }
+    }
+  })
+
+  it("the other six cuts render the hard cut at every duration, Short included", () => {
+    for (const id of OTHER_CUTS) {
+      for (const duration of DURATIONS) {
+        for (const position of POSITIONS) for (const intensity of INTENSITIES) for (const scope of SCOPES) {
+          const out = compose(id, levers(position, duration, intensity), scope)
+          expect(out, `${id} ${position} ${duration} ${intensity} ${scope}`).toBe(compose(id, levers(position), scope))
+          expect(count(out, INSTANT_CUT_CLAUSE)).toBe(1)
+          expect(out).not.toContain(BLEND)
+        }
+      }
+    }
+  })
+
+  it("a non-cut never carries the blend sentence, and keeps its Short duration clause", () => {
+    for (const id of NON_CUTS) {
+      const out = compose(id, { duration: "short" })
+      expect(out, id).toContain("lasting approximately 1 second")
+      expect(out, id).not.toContain(BLEND)
+    }
+  })
+
+  it("a blended cut carries no span, duration or intensity clause", () => {
+    for (const pick of [...BLENDABLE.map((id) => [id]), ["seamless-match", "jump-match"], ["jump-match", "seamless-match"]]) {
+      for (const position of POSITIONS) for (const intensity of INTENSITIES) for (const scope of SCOPES) {
+        const out = compose(pick, levers(position, "short", intensity), scope)
+        expect(count(out, BLEND), `${pick} ${position} ${intensity} ${scope}`).toBe(1)
+        for (const word of ["spans", "lasting", "timing", "energy", "flourish"]) expect(out).not.toContain(word)
+      }
+    }
+  })
+})
+
+describe("blended cut — the direction fold never blends", () => {
+  it("renderTransitionBases keeps the hard cut for every single and ordered pair", () => {
+    const picks: string[][] = ALL_IDS.map((id) => [id])
+    for (const a of ALL_IDS) for (const b of ALL_IDS) if (a !== b) picks.push([a, b])
+    for (const pick of picks) {
+      const bases = renderTransitionBases(pick)
+      expect(bases.join(" ")).not.toContain(BLEND)
+      expect(bases.join(", and ")).toBe(compose(pick, undefined))
+    }
+  })
+
+  it("the server fold of `direction.transition` keeps the hard cut", () => {
+    for (const id of BLENDABLE) {
+      const [fold] = renderDirectionHints({ transition: id }, { surface: "video" })
+      expect(fold).toBe(compose(id, undefined))
+      expect(fold).toContain(INSTANT_CUT_CLAUSE)
+      expect(fold).not.toContain(BLEND)
+    }
+  })
+})
+
+describe("blended cut — the rule holds for every row and lever (self-consistency sweep)", () => {
+  /** A pick blends iff every contributing id is a blendable cut and the duration is `short`. */
+  const blends = (pick: readonly string[], duration: string | undefined) =>
+    duration === "short" &&
+    pick.filter((id) => getTransitionTerm(id).length > 0).every((id) => (BLENDABLE as readonly string[]).includes(id)) &&
+    pick.some((id) => getTransitionTerm(id).length > 0)
+
+  function check(pick: readonly string[], timing: TransitionTiming, scope: TransitionHintScope) {
+    const out = compose(pick, timing, scope)
+    const label = `${pick.join("+")} ${JSON.stringify(timing)} ${scope}`
+    const allCuts = isInstantTransition(pick.filter((id) => getTransitionTerm(id).length > 0))
+    const { duration, ...rest } = timing
+    if (blends(pick, duration)) {
+      // Exactly the hard cut with its anti-blend sentence swapped, once.
+      const hard = compose(pick, rest, scope)
+      expect(count(hard, INSTANT_CUT_CLAUSE), label).toBe(1)
+      expect(out, label).toBe(hard.replace(INSTANT_CUT_CLAUSE, BLEND))
+    } else {
+      expect(out, label).not.toContain(BLEND)
+      // On an all-cut pick a duration never changes anything else.
+      if (allCuts) expect(out, label).toBe(compose(pick, rest, scope))
+    }
+  }
+
+  it("every row alone, at every position, duration and intensity, in both scopes", () => {
+    for (const id of ALL_IDS) {
+      for (const position of POSITIONS) for (const duration of DURATIONS) for (const intensity of INTENSITIES) {
+        for (const scope of SCOPES) check([id], levers(position, duration, intensity), scope)
+      }
+    }
+  })
+
+  it("every ordered pair, at the levers that decide a blend", () => {
+    for (const a of ALL_IDS) for (const b of ALL_IDS) {
+      if (a === b) continue
+      for (const duration of [undefined, "short", "medium"]) for (const position of [undefined, "middle", "full"]) {
+        check([a, b], levers(position, duration, "natural"), "clip")
+      }
+    }
+  })
+})

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

@@ -506,8 +506,10 @@ describe("F8 cut bodies (2026-10-03 A/B: F8 arm B on snap-to-black, jump-match a
     expect(composeTransitionHintFromConnections(id, [], [])).toBe(clause)
   })
 
-  it.each(ROWS)("$id at middle / short / natural keeps only the position", ({ id, term, body }) => {
-    const levers = { position: "middle", duration: "short", intensity: "natural" } as const
+  // `long`: a duration every cut ignores. Short on `jump-match` is a blended cut, pinned in
+  // transitions-blended-cut.test.ts.
+  it.each(ROWS)("$id at middle / long / natural keeps only the position", ({ id, term, body }) => {
+    const levers = { position: "middle", duration: "long", intensity: "natural" } as const
     expect(composeTransitionHintFromConnections(id, [], [], levers)).toBe(
       `${term} (${body}; ${INSTANT_CUT_CLAUSE}), the transition occurs in the middle of the clip`,
     )
@@ -770,8 +772,10 @@ describe("double-exposure body (2026-10-04: dblexp3 D1, the silhouette wording)"
 })
 
 describe("L1 — a cut spans nothing, so `full` adds no clause", () => {
+  // `long`: a duration every cut ignores. Short on `seamless-match` / `jump-match` is a blended cut, and
+  // its `full` (also dropped) is pinned in transitions-blended-cut.test.ts.
   it.each(INSTANT_IDS)("%s + full renders no position clause", (id) => {
-    const out = composeTransitionHintFromConnections(id, [], [], { position: "full", duration: "short", intensity: "natural" })
+    const out = composeTransitionHintFromConnections(id, [], [], { position: "full", duration: "long", intensity: "natural" })
     expect(out).not.toContain("spans")
     expect(out).toBe(composeTransitionHintFromConnections(id, [], []))
   })

package/src/picker-catalogs.ts

@@ -124,13 +124,30 @@ export interface PickerOption {
   /**
    * Transitions only: present (`true`) on a row whose mechanism is a CUT, so
    * 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.
+   * `isInstantTransition`. A consumer that only reads this catalog (Studio
+   * builds the transition levers 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. On this in-memory catalog only: the wire projection
+   * (`projectPickerCatalog`) does not carry it.
    */
   readonly instant?: true
+  /**
+   * Transitions only: present (`true`) on a CUT that a `blendsCut` duration
+   * turns into a BLENDED CUT — see `Transition.blendable` /
+   * `isBlendableTransition`. Always beside `instant`. A consumer offers such a
+   * row's Duration as a Blend lever (hard cut, or one of the `blendsCut`
+   * steps of the catalog's `duration` dimension). Carried like `instant`, and
+   * like it on this in-memory catalog only.
+   */
+  readonly blendable?: true
+  /**
+   * Transition `duration` dimension only: present (`true`) on the step that
+   * blends a `blendable` cut (`short`) — see `TransitionTimingOption.blendsCut`
+   * / `blendedCutClause`. On this in-memory catalog only.
+   */
+  readonly blendsCut?: true
   /**
    * PER-OPTION PARAMETERS — extra node-data fields that apply only while THIS
    * option is picked, each with its own rows (Transitions: a wipe's
@@ -197,6 +214,10 @@ interface BaseCatalogEntry {
   readonly adultOnly?: true
   /** Transitions: see `Transition.instant`. Propagated into the flattened option as `instant: true`. */
   readonly instant?: boolean
+  /** Transitions: see `Transition.blendable`. Propagated into the flattened option as `blendable: true`. */
+  readonly blendable?: boolean
+  /** Transition durations: see `TransitionTimingOption.blendsCut`. Propagated as `blendsCut: true`. */
+  readonly blendsCut?: boolean
   /** Transitions: see `Transition.options`. Propagated as the option's `params`. */
   readonly options?: ReadonlyArray<{
     readonly field: string
@@ -238,6 +259,8 @@ function toOptions<T extends BaseCatalogEntry>(
     if (categoryField) opt.category = e[categoryField] as unknown as string
     if (e.adultOnly) opt.adultOnly = true
     if (e.instant) opt.instant = true
+    if (e.blendable) opt.blendable = true
+    if (e.blendsCut) opt.blendsCut = true
     if (e.options?.length) {
       opt.params = e.options.map((o) => ({
         field: o.field,