@nodaro/prompts 1.28.0 → 1.30.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/caption-treatments.ts

@@ -0,0 +1,109 @@
+// packages/prompts/src/caption-treatments.ts
+import type { CaptionPlan, SupportedFontName } from "@nodaro/shared"
+import { ADD_CAPTIONS_PRESETS } from "./factory-presets/video-edit.js"
+
+export const HOOK_PLATE_PRESET_ID = "add-captions/hook-plate"
+export const BODY_CAPTIONS_PRESET_ID = "add-captions/body-captions"
+
+/** Levers a spoken language needs on every caption segment; a language with no entry adds none. */
+export interface CaptionLanguageLevers {
+  readonly fontFamily?: SupportedFontName
+  readonly uppercase?: boolean
+}
+
+/**
+ * Keyed by primary language tag. Hebrew: one face that carries Hebrew and Latin, so a Latin
+ * brand inside a Hebrew line is drawn in the same face, and no upper-casing, so the brand keeps
+ * its spelling.
+ */
+export const CAPTION_LEVERS_BY_LANGUAGE: Readonly<Record<string, CaptionLanguageLevers>> = {
+  he: { fontFamily: "Rubik", uppercase: false },
+}
+
+/** The add-captions segment keys a lever set may carry: the segment schema minus times and words. */
+export const CAPTION_SEGMENT_LEVER_KEYS: readonly string[] = [
+  "style", "position", "fontSize", "color", "backgroundColor", "look", "fontFamily", "fontWeight",
+  "strokeColor", "strokeWidth", "highlightColor", "uppercase", "positionY", "animate", "maxWordsPerLine",
+]
+
+export type CaptionSegmentRole = "hook" | "body"
+
+export interface HookPlateSegmentsOptions {
+  /** The body's levers; default = the Body Captions preset. Keys outside CAPTION_SEGMENT_LEVER_KEYS are ignored. */
+  readonly bodyLevers?: Readonly<Record<string, unknown>>
+}
+
+export interface HookPlateSegmentsResult {
+  /** Route-shaped (camelCase) `segments`. Empty means "no captions". */
+  readonly segments: Record<string, unknown>[]
+  /** Segments left out, in order hook, body. */
+  readonly dropped: CaptionSegmentRole[]
+}
+
+const LEVER_KEYS: ReadonlySet<string> = new Set(CAPTION_SEGMENT_LEVER_KEYS)
+
+/** A lever set: segment lever keys only, without null or undefined values. */
+function pickLevers(source: Readonly<Record<string, unknown>> | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  if (!source) return out
+  for (const [k, v] of Object.entries(source)) if (LEVER_KEYS.has(k) && v !== undefined && v !== null) out[k] = v
+  return out
+}
+
+function presetLevers(id: string): Record<string, unknown> {
+  const preset = ADD_CAPTIONS_PRESETS.find((p) => p.id === id)
+  if (!preset) throw new Error(`The ${id} caption preset is missing from the catalog.`)
+  return pickLevers(preset.data)
+}
+
+const PLATE_LEVERS = presetLevers(HOOK_PLATE_PRESET_ID)
+const BODY_LEVERS = presetLevers(BODY_CAPTIONS_PRESET_ID)
+
+function languageLevers(tag: string | undefined): CaptionLanguageLevers {
+  if (typeof tag !== "string") return {}
+  const primary = tag.trim().split(/[-_]/)[0]!.toLowerCase()
+  return Object.hasOwn(CAPTION_LEVERS_BY_LANGUAGE, primary) ? CAPTION_LEVERS_BY_LANGUAGE[primary]! : {}
+}
+
+const isTime = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n)
+
+/**
+ * One caption plan → the `segments` of one add-captions request: the opening line as the Hook
+ * Plate, then the body's words in the Body Captions style (or the caller's own body levers).
+ * The styling is read from the two presets, never restated here. Pure: no I/O.
+ */
+export function hookPlateCaptionSegments(plan: CaptionPlan, opts: HookPlateSegmentsOptions = {}): HookPlateSegmentsResult {
+  const hookEnd = plan.hookEndMs
+  if (!isTime(hookEnd) || hookEnd < 0) return { segments: [], dropped: ["hook", "body"] }
+  const language = languageLevers(plan.language)
+  const limit = typeof plan.videoDurationMs === "number" ? plan.videoDurationMs : Number.POSITIVE_INFINITY
+  const segments: Record<string, unknown>[] = []
+  const dropped: CaptionSegmentRole[] = []
+
+  const plateEnd = Math.min(hookEnd, limit)
+  if (plateEnd > 0 && typeof plan.hookText === "string" && /\S/.test(plan.hookText)) {
+    segments.push({ startMs: 0, endMs: plateEnd, text: plan.hookText, ...PLATE_LEVERS, ...language })
+  } else {
+    dropped.push("hook")
+  }
+
+  // The body starts where the opening line ends, even when no plate is shown, so it never
+  // draws over the opening line.
+  const bodyEnd = Math.min(plan.bodyEndMs, limit)
+  const words = Array.isArray(plan.captions) ? plan.captions : []
+  const chosen = pickLevers(opts.bodyLevers)
+  const bodyLevers = Object.keys(chosen).length > 0 ? chosen : BODY_LEVERS
+  if (bodyEnd > hookEnd && words.length > 0) {
+    segments.push({
+      startMs: hookEnd,
+      endMs: bodyEnd,
+      captions: words.map((w) => ({ text: w.text, startMs: w.startMs, endMs: w.endMs })),
+      ...bodyLevers,
+      ...language,
+    })
+  } else {
+    dropped.push("body")
+  }
+
+  return { segments, dropped }
+}

package/src/factory-presets/sfx.ts

@@ -53,6 +53,27 @@ export const TEXT_TO_AUDIO_PRESETS: readonly FactoryPreset[] = [
     group: "Ambiences (loopable)",
     data: { provider: "elevenlabs-sfx", duration: 22, loop: true, promptInfluence: 0.5, prompt: "low sci-fi ambient drone, ominous spaceship hum" },
   },
+  {
+    id: "text-to-audio/living-room-tone",
+    name: "Living Room Tone",
+    description: "Quiet, lived-in room.",
+    group: "Ambiences (loopable)",
+    data: { provider: "elevenlabs-sfx", duration: 22, loop: true, promptInfluence: 0.4, prompt: "quiet living room room tone, faint air and a soft distant household hum, steady and even, an empty room at rest" },
+  },
+  {
+    id: "text-to-audio/kitchen-hum",
+    name: "Kitchen Hum",
+    description: "Fridge hum in a still kitchen.",
+    group: "Ambiences (loopable)",
+    data: { provider: "elevenlabs-sfx", duration: 22, loop: true, promptInfluence: 0.4, prompt: "home kitchen room tone, a low steady refrigerator hum with faint air, calm and continuous, an empty kitchen at rest" },
+  },
+  {
+    id: "text-to-audio/cafe-murmur",
+    name: "Café Murmur",
+    description: "Soft, indistinct café chatter.",
+    group: "Ambiences (loopable)",
+    data: { provider: "elevenlabs-sfx", duration: 22, loop: true, promptInfluence: 0.4, prompt: "café background ambience, a soft indistinct murmur of distant conversation and the occasional faint cup clink, steady and even, no clear words" },
+  },
 
   // ── UI & Stingers ────────────────────────────────────────────────────────
   {

package/src/factory-presets/text.ts

@@ -80,6 +80,24 @@ export const LLM_CHAT_PRESETS: readonly FactoryPreset[] = [
       temperature: 0.7,
     },
   },
+  {
+    id: "llm-chat/hook-generator",
+    name: "Hook Generator",
+    description: "10 opening lines for a talking-to-camera video.",
+    group: "Writing & Marketing",
+    data: {
+      systemPrompt:
+        "You write opening lines for short vertical videos in which one person talks straight to the camera about a product, a site or an idea. Given the user's topic, write 10 different opening lines.\n\n" +
+        "Every line:\n" +
+        "- is one short spoken clause of at most 8 words;\n" +
+        "- leads with the payload the viewer can check: a number, a price, a time saved, a before and after, a contrast with the usual way, or a named result;\n" +
+        "- opens on the claim itself — no greeting, no filler word, no introduction of the product before the claim;\n" +
+        "- sounds said, not written: plain words, contractions welcome, no hashtags, no emoji, no stage directions;\n" +
+        "- spells the product or brand exactly as the user gives it and writes numbers as digits.\n\n" +
+        "Vary the angle across the 10: a surprising number, a price, time saved, a mistake to avoid, a before and after, a contrast, a named result, a direct question. Write in the language the user writes in. Return only the numbered list, one line each.",
+      temperature: 0.9,
+    },
+  },
 
   // ── Utility ──────────────────────────────────────────────────────────────
   {
@@ -273,6 +291,17 @@ export const IMAGE_TO_TEXT_PRESETS: readonly FactoryPreset[] = [
     group: "Extraction",
     data: { detailLevel: "detailed", customPrompt: "Write a compelling e-commerce product description based on this product image." },
   },
+  {
+    id: "image-to-text/site-screenshot-summary",
+    name: "Site Screenshot Summary",
+    description: "Section, headings and figures from a web page.",
+    group: "Extraction",
+    data: {
+      detailLevel: "structured",
+      customPrompt:
+        "Describe this website screenshot as five labelled lines. Section: which part of the site it is (for example the top of the home page, a feature, how it works, reviews, pricing, sign-up, navigation or footer). Headings: every heading exactly as written. Figures: every number, price, rating and date exactly as written, each with what it refers to. Brand: the product or company name exactly as spelled. First look: what a viewer notices first, in one sentence. Write \"none\" on a line with nothing to report.",
+    },
+  },
 
   // ── Creative ─────────────────────────────────────────────────────────────
   {

package/src/factory-presets/video-edit.ts

@@ -95,6 +95,20 @@ export const ADD_CAPTIONS_PRESETS: readonly FactoryPreset[] = [
     group: "Caption Styles",
     data: { style: "subtitle", position: "top", fontSize: 36, color: "#FFFFFF", autoTranscribe: true },
   },
+  {
+    id: "add-captions/hook-plate",
+    name: "Hook Plate",
+    description: "Your opening line as a bold plate near the top.",
+    group: "Caption Styles",
+    data: { style: "subtitle", look: "clean", position: "top", positionY: 20, fontSize: 32, fontWeight: 800, maxWordsPerLine: 4, color: "#111111", backgroundColor: "#FFFFFF", autoTranscribe: false },
+  },
+  {
+    id: "add-captions/body-captions",
+    name: "Body Captions",
+    description: "Word-by-word captions under the face.",
+    group: "Caption Styles",
+    data: { style: "word-highlight", look: "outline", position: "bottom", positionY: 72, fontSize: 32, maxWordsPerLine: 3, color: "#FFFFFF", autoTranscribe: true },
+  },
 ]
 
 export const COMBINE_VIDEOS_PRESETS: readonly FactoryPreset[] = [

package/src/factory-presets/voice.ts

@@ -115,6 +115,20 @@ export const VOICE_DESIGN_PRESETS: readonly FactoryPreset[] = [
     group: "Narration & Character",
     data: { voiceDescription: "A calm, soft-spoken meditation guide with a slow, breathy, reassuring delivery." },
   },
+  {
+    id: "voice-design/casual-creator-female",
+    name: "Casual Creator (female)",
+    description: "Relaxed, warm, everyday.",
+    group: "Narration & Character",
+    data: { voiceDescription: "An adult woman in her late twenties talking casually to the viewer as if telling a friend about something she tried: relaxed, warm and upbeat, a natural conversational pace with small pauses, a light neutral American accent, recorded close and dry in a quiet room, never polished or announcer-like." },
+  },
+  {
+    id: "voice-design/casual-creator-male",
+    name: "Casual Creator (male)",
+    description: "Relaxed, warm, everyday.",
+    group: "Narration & Character",
+    data: { voiceDescription: "An adult man in his late twenties talking casually to the viewer as if telling a friend about something he tried: relaxed, warm and upbeat, a natural conversational pace with small pauses, a light neutral American accent, recorded close and dry in a quiet room, never polished or announcer-like." },
+  },
 
   // ── Professional & Assistant ─────────────────────────────────────────────
   {

package/src/index.ts

@@ -88,6 +88,7 @@ export * from "./prompt-wizard-categories.js"
 export * from "./resolve-prompt.js"
 export * from "./node-prompt-fields.js"
 export * from "./factory-presets.js"
+export * from "./caption-treatments.js"
 export * from "./style-presets.js"
 export * from "./object-asset-presets.js"
 export * from "./factory-snippets/index.js"