@nodaro/prompts 1.29.0 → 1.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -20,7 +20,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^3.17.0"
+    "@nodaro/shared": "^3.19.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/caption-treatments.test.ts

@@ -0,0 +1,155 @@
+// packages/prompts/src/__tests__/caption-treatments.test.ts
+import { describe, it, expect } from "vitest"
+import { captionRoutesToRemotion, type CaptionPlan } from "@nodaro/shared"
+import {
+  BODY_CAPTIONS_PRESET_ID,
+  CAPTION_LEVERS_BY_LANGUAGE,
+  CAPTION_SEGMENT_LEVER_KEYS,
+  HOOK_PLATE_PRESET_ID,
+  hookPlateCaptionSegments,
+} from "../caption-treatments.js"
+import { getFactoryPresets } from "../factory-presets.js"
+
+type CaptionInput = Parameters<typeof captionRoutesToRemotion>[0]
+const data = (id: string) => getFactoryPresets("add-captions").find((p) => p.id === id)!.data
+const levers = (d: Readonly<Record<string, unknown>>) => Object.fromEntries(Object.entries(d).filter(([k]) => CAPTION_SEGMENT_LEVER_KEYS.includes(k)))
+const PLATE = levers(data(HOOK_PLATE_PRESET_ID))
+const BODY = levers(data(BODY_CAPTIONS_PRESET_ID))
+const KARAOKE = data("add-captions/karaoke")
+const WORDS = [
+  { text: "so", startMs: 1600, endMs: 1900 },
+  { text: "I", startMs: 2000, endMs: 2200 },
+  { text: "opened", startMs: 2200, endMs: 2600 },
+  { text: "Acme", startMs: 2600, endMs: 4000 },
+]
+const PLAN: CaptionPlan = { v: 1, hookText: " Saved 3 hours a week ", hookEndMs: 1600, bodyEndMs: 4300, captions: WORDS }
+const SEGMENT_SHAPE_KEYS = new Set([...CAPTION_SEGMENT_LEVER_KEYS, "startMs", "endMs", "text", "captions"])
+
+describe("hookPlateCaptionSegments — windows and sources", () => {
+  it("emits the plate, then the body, with the opening line untrimmed and the words as captions", () => {
+    const r = hookPlateCaptionSegments(PLAN)
+    expect(r.dropped).toEqual([])
+    expect(r.segments).toEqual([
+      { startMs: 0, endMs: 1600, text: " Saved 3 hours a week ", ...PLATE },
+      { startMs: 1600, endMs: 4300, captions: WORDS, ...BODY },
+    ])
+  })
+
+  it("the plate's levers are Hook Plate's segment levers (autoTranscribe is not a segment key)", () => {
+    expect(PLATE).not.toHaveProperty("autoTranscribe")
+    expect(hookPlateCaptionSegments(PLAN).segments[0]).not.toHaveProperty("autoTranscribe")
+  })
+
+  it("every emitted key is a segment lever, a time, the text or the captions", () => {
+    for (const s of hookPlateCaptionSegments({ ...PLAN, language: "he" }, { bodyLevers: KARAOKE }).segments)
+      for (const k of Object.keys(s)) expect(SEGMENT_SHAPE_KEYS.has(k), k).toBe(true)
+  })
+})
+
+describe("hookPlateCaptionSegments — drop cases (never throws)", () => {
+  it("a blank opening line → body only, still starting where the opening line ends", () => {
+    const r = hookPlateCaptionSegments({ ...PLAN, hookText: "   " })
+    expect(r.dropped).toEqual(["hook"])
+    expect(r.segments).toHaveLength(1)
+    expect(r.segments[0]).toMatchObject({ startMs: 1600, endMs: 4300 })
+  })
+  it("no body words → plate only", () => {
+    const r = hookPlateCaptionSegments({ ...PLAN, captions: [] })
+    expect(r.dropped).toEqual(["body"])
+    expect(r.segments.map((s) => s.text)).toEqual([" Saved 3 hours a week "])
+  })
+  it("a video that ends before the opening line → the plate ends with the video, the body is dropped", () => {
+    const r = hookPlateCaptionSegments({ ...PLAN, videoDurationMs: 1000 })
+    expect(r.segments).toEqual([{ startMs: 0, endMs: 1000, text: " Saved 3 hours a week ", ...PLATE }])
+    expect(r.dropped).toEqual(["body"])
+  })
+  it("a video length of 0 → both dropped", () => {
+    expect(hookPlateCaptionSegments({ ...PLAN, videoDurationMs: 0 })).toEqual({ segments: [], dropped: ["hook", "body"] })
+  })
+  it("a video that ends exactly where the opening line ends → plate only", () => {
+    const r = hookPlateCaptionSegments({ ...PLAN, videoDurationMs: 1600 })
+    expect(r.segments).toHaveLength(1)
+    expect(r.dropped).toEqual(["body"])
+  })
+  it("a body that ends at or before the opening line's end → body dropped", () => {
+    for (const bodyEndMs of [1600, 1000]) expect(hookPlateCaptionSegments({ ...PLAN, bodyEndMs }).dropped).toEqual(["body"])
+  })
+  it("a negative or non-finite hookEndMs → both dropped", () => {
+    for (const hookEndMs of [-1, Number.NaN, Number.POSITIVE_INFINITY, "1600" as unknown as number])
+      expect(hookPlateCaptionSegments({ ...PLAN, hookEndMs })).toEqual({ segments: [], dropped: ["hook", "body"] })
+  })
+  it("the body never starts before the opening line ends, whatever the video length", () => {
+    for (const videoDurationMs of [0, 500, 1599, 1600, 1601, 99_999])
+      for (const s of hookPlateCaptionSegments({ ...PLAN, videoDurationMs }).segments) if (s.captions) expect(s.startMs).toBe(1600)
+  })
+  it("never throws on non-numeric times", () => {
+    expect(() => hookPlateCaptionSegments({ ...PLAN, bodyEndMs: Number.NaN })).not.toThrow()
+    expect(() => hookPlateCaptionSegments({ ...PLAN, videoDurationMs: Number.NaN })).not.toThrow()
+    expect(hookPlateCaptionSegments({ ...PLAN, videoDurationMs: Number.NaN }).dropped).toEqual(["hook", "body"])
+  })
+})
+
+describe("hookPlateCaptionSegments — language levers", () => {
+  it("he → Rubik and uppercase false on both segments, winning over a bodyLevers fontFamily", () => {
+    const r = hookPlateCaptionSegments({ ...PLAN, language: "he" }, { bodyLevers: { ...BODY, fontFamily: "Anton" } })
+    expect(r.segments).toHaveLength(2)
+    for (const s of r.segments) expect(s).toMatchObject({ fontFamily: "Rubik", uppercase: false })
+  })
+  it("a regional or capitalised Hebrew tag gets the Hebrew levers", () => {
+    for (const language of ["he-IL", "HE", "he_IL"])
+      for (const s of hookPlateCaptionSegments({ ...PLAN, language }).segments) expect(s, language).toMatchObject({ fontFamily: "Rubik", uppercase: false })
+  })
+  it("en, an unmapped tag, an inherited key name or no language → neither key", () => {
+    for (const language of ["en", "fr", "constructor", undefined])
+      for (const s of hookPlateCaptionSegments({ ...PLAN, language }).segments) {
+        expect(s, String(language)).not.toHaveProperty("fontFamily")
+        expect(s, String(language)).not.toHaveProperty("uppercase")
+      }
+  })
+})
+
+describe("hookPlateCaptionSegments — body levers", () => {
+  it("bodyLevers restyle the body only", () => {
+    const [plate, body] = hookPlateCaptionSegments(PLAN, { bodyLevers: KARAOKE }).segments
+    expect(body).toMatchObject({ style: "karaoke", fontSize: 56, position: "bottom" })
+    expect(plate).toEqual({ startMs: 0, endMs: 1600, text: " Saved 3 hours a week ", ...PLATE })
+  })
+  it("bodyLevers keep only segment levers, and drop null and undefined values", () => {
+    const body = hookPlateCaptionSegments(PLAN, {
+      bodyLevers: { ...KARAOKE, autoTranscribe: true, text: "x", label: "Captions", fontFamily: null, strokeColor: undefined },
+    }).segments[1]!
+    for (const k of ["autoTranscribe", "label", "fontFamily", "strokeColor"]) expect(body, k).not.toHaveProperty(k)
+    expect(body.text).toBeUndefined()
+    expect(body.style).toBe("karaoke")
+  })
+  it("no bodyLevers, or none left after filtering → Body Captions", () => {
+    for (const opts of [undefined, {}, { bodyLevers: {} }, { bodyLevers: { autoTranscribe: true, label: "x" } }])
+      expect(hookPlateCaptionSegments(PLAN, opts).segments[1]).toEqual({ startMs: 1600, endMs: 4300, captions: WORDS, ...BODY })
+  })
+})
+
+describe("hookPlateCaptionSegments — the plate never falls back to drawtext", () => {
+  it("every plate segment, sent alone, routes to the styled renderer — for every mapped language and for none", () => {
+    for (const language of [undefined, ...Object.keys(CAPTION_LEVERS_BY_LANGUAGE)]) {
+      const plate = hookPlateCaptionSegments({ ...PLAN, language }).segments[0]!
+      expect(plate.text, String(language)).toBeDefined()
+      expect(captionRoutesToRemotion(plate as CaptionInput), String(language)).toBe(true)
+    }
+  })
+  it("bodyLevers never reach the plate", () => {
+    const plate = hookPlateCaptionSegments(PLAN, { bodyLevers: { fontFamily: "Anton", backgroundColor: "#FF0000", positionY: 90, style: "karaoke" } }).segments[0]
+    expect(plate).toEqual({ startMs: 0, endMs: 1600, text: " Saved 3 hours a week ", ...PLATE })
+  })
+})
+
+describe("caption lever constants", () => {
+  it("CAPTION_SEGMENT_LEVER_KEYS is the route's segment keys without times and words", () => {
+    expect([...CAPTION_SEGMENT_LEVER_KEYS].sort()).toEqual(
+      ["style", "position", "fontSize", "color", "backgroundColor", "look", "fontFamily", "fontWeight", "strokeColor", "strokeWidth", "highlightColor", "uppercase", "positionY", "animate", "maxWordsPerLine"].sort(),
+    )
+  })
+  it("every language entry uses segment lever keys only", () => {
+    for (const entry of Object.values(CAPTION_LEVERS_BY_LANGUAGE))
+      for (const k of Object.keys(entry)) expect(CAPTION_SEGMENT_LEVER_KEYS.includes(k), k).toBe(true)
+  })
+})

package/src/__tests__/creator-presets.test.ts

@@ -0,0 +1,151 @@
+// packages/prompts/src/__tests__/creator-presets.test.ts
+import { describe, it, expect } from "vitest"
+import { captionRoutesToRemotion, presetApplyClearKeys } from "@nodaro/shared"
+import { getFactoryPresets, type FactoryPreset } from "../factory-presets.js"
+
+/** Words that name a recording or viewing device. Plural forms included. */
+const DEVICE_WORDS = /\b(?:smartphones?|iphones?|phones?|cameras?|lens(?:es)?|webcams?|laptops?|tablets?|screens?|monitors?|displays?|tripods?|selfie[ -]sticks?)\b/i
+/** "adult", or an age phrase in the twenties to sixties. */
+const ADULT = /\badults?\b|\bin (?:her|his|their) (?:early |mid-|late )?(?:twenties|thirties|forties|fifties|sixties)\b/i
+
+function preset(nodeType: string, id: string): FactoryPreset {
+  const p = getFactoryPresets(nodeType).find((x) => x.id === id)
+  if (!p) throw new Error(`${id} is missing from the ${nodeType} catalog`)
+  return p
+}
+
+describe("creator-preset test helpers (self-check)", () => {
+  it("the device pattern finds device words and their plurals, and leaves ordinary words alone", () => {
+    for (const s of ["a phone in hand", "two cameras", "the lenses", "a selfie stick", "on screen"]) expect(s).toMatch(DEVICE_WORDS)
+    for (const s of ["a hand-held microphone", "deep focus", "the viewer at eye level"]) expect(s).not.toMatch(DEVICE_WORDS)
+  })
+  it("the adult pattern accepts 'adult' and twenties-to-sixties age phrases only", () => {
+    for (const s of ["an adult woman", "in her late twenties", "in his thirties", "in their mid-forties"]) expect(s).toMatch(ADULT)
+    for (const s of ["a teenager", "in her teens", "a young woman"]) expect(s).not.toMatch(ADULT)
+  })
+  it("preset() finds a shipped preset and refuses a missing one", () => {
+    expect(preset("add-captions", "add-captions/clean-subtitles").group).toBe("Caption Styles")
+    expect(() => preset("add-captions", "add-captions/does-not-exist")).toThrow()
+  })
+})
+
+describe("Wave 0 — Casual Creator voices", () => {
+  const VOICES = ["voice-design/casual-creator-female", "voice-design/casual-creator-male"]
+
+  it("ships both in Narration & Character, right after Meditation Guide, carrying only a voice description", () => {
+    for (const id of VOICES) {
+      const p = preset("voice-design", id)
+      expect(p.group).toBe("Narration & Character")
+      expect(Object.keys(p.data)).toEqual(["voiceDescription"])
+    }
+    const ids = getFactoryPresets("voice-design").map((p) => p.id)
+    const i = ids.indexOf("voice-design/meditation-guide")
+    expect(ids.slice(i + 1, i + 3)).toEqual(VOICES)
+  })
+
+  it("every new voice description names an adult and no recording device", () => {
+    for (const id of VOICES) {
+      const d = preset("voice-design", id).data.voiceDescription as string
+      expect(d, id).toMatch(ADULT)
+      expect(d, id).not.toMatch(DEVICE_WORDS)
+    }
+  })
+})
+
+describe("Wave 0 — room tones", () => {
+  const TONES = ["text-to-audio/living-room-tone", "text-to-audio/kitchen-hum", "text-to-audio/cafe-murmur"]
+
+  it("ships three loopable room tones in the ambience shape, right after Sci-Fi Drone", () => {
+    for (const id of TONES) {
+      const p = preset("text-to-audio", id)
+      expect(p.group).toBe("Ambiences (loopable)")
+      expect(Object.keys(p.data)).toEqual(["provider", "duration", "loop", "promptInfluence", "prompt"])
+      expect(p.data).toMatchObject({ provider: "elevenlabs-sfx", duration: 22, loop: true, promptInfluence: 0.4 })
+    }
+    const ids = getFactoryPresets("text-to-audio").map((p) => p.id)
+    const i = ids.indexOf("text-to-audio/scifi-drone")
+    expect(ids.slice(i + 1, i + 4)).toEqual(TONES)
+  })
+})
+
+describe("Wave 0 — Site Screenshot Summary", () => {
+  it("ships in Extraction right after Product Description, structured, asking for the five labelled lines", () => {
+    const p = preset("image-to-text", "image-to-text/site-screenshot-summary")
+    expect(p.group).toBe("Extraction")
+    expect(p.data.detailLevel).toBe("structured")
+    const prompt = p.data.customPrompt as string
+    for (const label of ["Section:", "Headings:", "Figures:", "Brand:", "First look:"]) expect(prompt).toContain(label)
+    expect(prompt).toContain("exactly as written")
+    const ids = getFactoryPresets("image-to-text").map((x) => x.id)
+    expect(ids[ids.indexOf("image-to-text/product-desc") + 1]).toBe("image-to-text/site-screenshot-summary")
+  })
+})
+
+describe("Wave 0 — Hook Generator", () => {
+  it("ships in Writing & Marketing right after the script writer, at temperature 0.9, with node defaults for tokens and model", () => {
+    const p = preset("llm-chat", "llm-chat/hook-generator")
+    expect(p.group).toBe("Writing & Marketing")
+    expect(p.data.temperature).toBe(0.9)
+    expect(p.data.maxTokens).toBeUndefined()
+    expect(p.data.llmModel).toBeUndefined()
+    const ids = getFactoryPresets("llm-chat").map((x) => x.id)
+    expect(ids[ids.indexOf("llm-chat/script-writer") + 1]).toBe("llm-chat/hook-generator")
+  })
+
+  it("states the hook limit and the craft in words, and no rate figure", () => {
+    const s = preset("llm-chat", "llm-chat/hook-generator").data.systemPrompt as string
+    expect(s).toContain("at most 8 words")
+    expect(s).toContain("write 10 different opening lines")
+    expect(s).not.toMatch(/per second/i)
+  })
+})
+
+describe("Wave 0 — Hook Plate and Body Captions", () => {
+  const HOOK_PLATE_ID = "add-captions/hook-plate"
+  const BODY_ID = "add-captions/body-captions"
+  type CaptionInput = Parameters<typeof captionRoutesToRemotion>[0]
+  const asInput = (d: Readonly<Record<string, unknown>>): CaptionInput => d as CaptionInput
+  // The eight levers that move a subtitle off the plain drawtext burn (captionRoutesToRemotion).
+  const ROUTING_LEVERS: readonly string[] = ["look", "fontFamily", "fontWeight", "strokeColor", "strokeWidth", "uppercase", "positionY", "maxWordsPerLine"]
+
+  // Other Nodaro services render these values; a change here changes their output, so it needs its owner's review.
+  it("Hook Plate and Body Captions carry exactly these values", () => {
+    expect(preset("add-captions", HOOK_PLATE_ID).data).toEqual({
+      style: "subtitle", look: "clean", position: "top", positionY: 20, fontSize: 32, fontWeight: 800,
+      maxWordsPerLine: 4, color: "#111111", backgroundColor: "#FFFFFF", autoTranscribe: false,
+    })
+    expect(preset("add-captions", BODY_ID).data).toEqual({
+      style: "word-highlight", look: "outline", position: "bottom", positionY: 72, fontSize: 32,
+      maxWordsPerLine: 3, color: "#FFFFFF", autoTranscribe: true,
+    })
+  })
+
+  it("both sit in Caption Styles, right after Top Banner", () => {
+    const ids = getFactoryPresets("add-captions").map((p) => p.id)
+    const i = ids.indexOf("add-captions/top-banner")
+    expect(ids.slice(i + 1, i + 3)).toEqual([HOOK_PLATE_ID, BODY_ID])
+    for (const id of [HOOK_PLATE_ID, BODY_ID]) expect(preset("add-captions", id).group).toBe("Caption Styles")
+  })
+
+  it("Hook Plate with its line wired as text routes to the styled renderer", () => {
+    expect(captionRoutesToRemotion(asInput({ ...preset("add-captions", HOOK_PLATE_ID).data, text: "Sample hook line" }))).toBe(true)
+  })
+
+  it("negative control: the same plate stripped of its eight routing levers would burn through drawtext", () => {
+    const stripped = Object.fromEntries(
+      Object.entries({ ...preset("add-captions", HOOK_PLATE_ID).data, text: "Sample hook line" }).filter(([k]) => !ROUTING_LEVERS.includes(k)),
+    )
+    expect(captionRoutesToRemotion(asInput(stripped))).toBe(false)
+  })
+
+  it("applying Body Captions or Clean Subtitles over Hook Plate leaves no plate lever", () => {
+    const applied = (node: Readonly<Record<string, unknown>>, p: Readonly<Record<string, unknown>>) =>
+      ({ ...node, ...Object.fromEntries(presetApplyClearKeys(p, "add-captions").map((k) => [k, undefined])), ...p }) as Record<string, unknown>
+    const plate = preset("add-captions", HOOK_PLATE_ID).data
+    const overBody = applied(plate, preset("add-captions", BODY_ID).data)
+    expect(overBody.backgroundColor).toBeUndefined()
+    expect(overBody.fontWeight).toBeUndefined()
+    const overClean = applied(plate, preset("add-captions", "add-captions/clean-subtitles").data)
+    for (const k of ["backgroundColor", "look", "positionY", "fontWeight", "maxWordsPerLine"]) expect(overClean[k], k).toBeUndefined()
+  })
+})

package/src/__tests__/factory-presets.test.ts

@@ -6,6 +6,7 @@ import { STYLE_IDS } from "../index.js"
 import { joinPromptParts } from "../resolve-prompt.js"
 import { nodeSupportsPromptAffixes } from "../node-prompt-fields.js"
 import { IMAGE_GEN_PROVIDERS, MODIFY_IMAGE_PROVIDERS, VIDEO_GEN_PROVIDERS, VIDEO_TO_VIDEO_PROVIDERS, MUSIC_PROVIDERS, SUNO_MODELS, TTS_PROVIDERS, TEXT_TO_AUDIO_PROVIDERS, ALL_CAPTION_STYLES, COMBINE_TRANSITION_IDS, AUDIO_CROSSFADE_CURVE_IDS, aspectRatioOptionsByKind, durationsByMode, IMAGE_PROMPT_MAX, MODEL_CATALOG, NATIVE_NEGATIVE_VIDEO_PROVIDERS, VIDEO_DURATION_AUTO, supportsAutoVideoDuration } from "@nodaro/shared"
+import { CAPTION_LOOK_IDS, CAPTION_MAX_WORDS_PER_LINE_MAX, CAPTION_MAX_WORDS_PER_LINE_MIN, KINETIC_ONLY_CAPTION_LEVER_KEYS, SUPPORTED_FONT_NAMES } from "@nodaro/shared"
 
 /**
  * The text a preset ACTUALLY sends: a preset may ship its doctrine as pre/post
@@ -740,6 +741,37 @@ describe("add-captions factory preset data validity", () => {
     }
   })
 
+  it("keeps every look lever valid: positionY 0-100, a known look and font, fontWeight a 100-step in 100-900, maxWordsPerLine in bounds", () => {
+    for (const p of presets) {
+      const d = p.data
+      if (d.positionY !== undefined) {
+        expect(d.positionY as number, `${p.id}: positionY`).toBeGreaterThanOrEqual(0)
+        expect(d.positionY as number, `${p.id}: positionY`).toBeLessThanOrEqual(100)
+      }
+      if (d.look !== undefined) expect(CAPTION_LOOK_IDS, `${p.id}: look`).toContain(d.look as never)
+      if (d.fontFamily !== undefined) expect(SUPPORTED_FONT_NAMES, `${p.id}: fontFamily`).toContain(d.fontFamily as never)
+      if (d.fontWeight !== undefined) {
+        const w = d.fontWeight as number
+        expect(w % 100, `${p.id}: fontWeight step`).toBe(0)
+        expect(w, `${p.id}: fontWeight`).toBeGreaterThanOrEqual(100)
+        expect(w, `${p.id}: fontWeight`).toBeLessThanOrEqual(900)
+      }
+      if (d.maxWordsPerLine !== undefined) {
+        const m = d.maxWordsPerLine as number
+        expect(Number.isInteger(m), `${p.id}: maxWordsPerLine integer`).toBe(true)
+        expect(m).toBeGreaterThanOrEqual(CAPTION_MAX_WORDS_PER_LINE_MIN)
+        expect(m).toBeLessThanOrEqual(CAPTION_MAX_WORDS_PER_LINE_MAX)
+      }
+    }
+  })
+
+  it("a subtitle preset carries no kinetic-only lever (the route rejects them on subtitle)", () => {
+    for (const p of presets) {
+      if (p.data.style !== "subtitle") continue
+      for (const k of KINETIC_ONLY_CAPTION_LEVER_KEYS) expect(p.data[k], `${p.id}: ${k}`).toBeUndefined()
+    }
+  })
+
   it("groups every preset under a folder", () => {
     for (const p of presets) expect(p.group, `${p.id}: missing group`).toBeTruthy()
   })
@@ -1124,3 +1156,34 @@ describe("generate-video/edit-video — the Seedance 2.5 edit shape, up front",
   })
 })
 
+
+describe("factory preset data carries no null", () => {
+  // The canvas sends a node's levers as they are, and the routes' optional fields reject null —
+  // a null in a preset would fail the run with a 400. "Unset" is expressed by leaving the key out.
+  const nullPaths = (data: Readonly<Record<string, unknown>>): string[] => {
+    const out: string[] = []
+    for (const [k, v] of Object.entries(data)) {
+      if (v === null) {
+        out.push(k)
+      } else if (Array.isArray(v)) {
+        v.forEach((x, i) => {
+          if (x === null) out.push(`${k}[${i}]`)
+        })
+      } else if (typeof v === "object") {
+        for (const [k2, v2] of Object.entries(v as Record<string, unknown>)) if (v2 === null) out.push(`${k}.${k2}`)
+      }
+    }
+    return out
+  }
+
+  it("finds a null at the top level and one level down (self-check)", () => {
+    expect(nullPaths({ a: null, b: { c: null }, d: [null], e: 1 })).toEqual(["a", "b.c", "d[0]"])
+  })
+
+  it("no factory preset data value is null", () => {
+    const offenders = Object.values(FACTORY_PRESETS)
+      .flat()
+      .flatMap((p) => nullPaths(p.data).map((path) => `${p.id}.${path}`))
+    expect(offenders, `null values: ${offenders.join(", ")}`).toEqual([])
+  })
+})

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"