@nodaro/prompts 1.29.0 → 1.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.29.0",
+  "version": "1.32.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.23.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/__tests__/i18n-entry-completeness.test.ts

@@ -270,3 +270,35 @@ describe("targeted gap coverage: facial-geometry + brand camera/render entries",
     }
   })
 })
+
+// ---------------------------------------------------------------------------
+// Test 4 — the Camera Motion and Transition pickers carry a LABEL for every
+// option in Japanese and Brazilian Portuguese. Fourteen camera motions (Dolly
+// In, Zoom In, POV, …) had a translated description but no label in pt-BR, so
+// the editor and the docs gallery (which syncs these sidecars) showed the
+// English name. A rig or brand name keeps its canonical form as an explicit
+// label (Steadicam, Snorricam) — a present label is the decision; a missing one
+// is the bug. Scoped to the two locales whose docs pages are held to "no English
+// apart from model names"; extend the list when another locale is held to it.
+// ---------------------------------------------------------------------------
+
+const FULL_LABEL_CATALOGS = ["camera-motions", "transitions"] as const
+const FULL_LABEL_LOCALES: readonly LocaleId[] = ["ja", "pt-BR"]
+
+describe("Camera Motion and Transition labels are complete in ja and pt-BR", () => {
+  const cases: Array<[string, LocaleId]> = []
+  for (const catalogId of FULL_LABEL_CATALOGS) {
+    for (const locale of FULL_LABEL_LOCALES) cases.push([catalogId, locale])
+  }
+
+  it.each(cases)("%s [%s] labels every entry", (catalogId, locale) => {
+    const catalog = CATALOGS.find((c) => c.catalogId === catalogId)
+    expect(catalog, `${catalogId} is not a registered picker catalog`).toBeDefined()
+    const map = mapFor(catalogId, locale)
+    const unlabelled = (catalog?.options ?? []).filter((o) => !has(map[o.id]?.label)).map((o) => o.id)
+    expect(
+      unlabelled,
+      `packages/shared/src/i18n/${catalogId}.${locale}.ts has no label for these ids, so the picker shows the English name`,
+    ).toEqual([])
+  })
+})

package/src/__tests__/node-send-text.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest"
+import { TEXT_REQUIRED_NODE_TYPES, computeAiWriterInput, computeNodeSendText } from "../node-send-text.js"
+
+/**
+ * "What text would this node send?" — answered by the executor's own prompt
+ * rule per type, so the orchestrator's empty-input skip can never disagree
+ * with the request the node would make.
+ */
+const none = new Map<string, string>()
+
+describe("computeNodeSendText", () => {
+  it("answers for every text-requiring type and for no other (totality)", () => {
+    for (const type of TEXT_REQUIRED_NODE_TYPES) {
+      expect(typeof computeNodeSendText(type, {}, { refMap: none }), type).toBe("string")
+    }
+    // Video nodes and social posts stay out: an empty prompt on an image-to-video is a legal request, an empty caption the author's choice.
+    expect(computeNodeSendText("image-to-video", {}, { refMap: none })).toBeUndefined()
+    expect(computeNodeSendText("combine-text", { text: "x" }, { refMap: none })).toBeUndefined()
+    expect(computeNodeSendText("telegram-post", {}, { refMap: none })).toBeUndefined()
+  })
+
+  it("llm-chat: the wired text when the node typed none; nothing when both are empty; a typed prompt runs on its own", () => {
+    expect(computeNodeSendText("llm-chat", {}, { wired: "the posts", refMap: none })).toBe("the posts")
+    expect(computeNodeSendText("llm-chat", {}, { wired: "", refMap: none })).toBe("")
+    expect(computeNodeSendText("llm-chat", {}, { refMap: none })).toBe("")
+    expect(computeNodeSendText("llm-chat", { userInput: "Write a poem" }, { wired: "", refMap: none })).toContain("Write a poem")
+  })
+
+  it("llm-chat: a fan-out item outranks the wire", () => {
+    expect(computeNodeSendText("llm-chat", {}, { override: "item 1", wired: "all", refMap: none })).toBe("item 1")
+  })
+
+  it("llm-chat: a typed template whose {Ref} resolves to nothing is still a non-empty request (the stated residual)", () => {
+    const refMap = new Map([["Feed", ""]])
+    const text = computeNodeSendText("llm-chat", { userInput: "Summarize: {Feed}" }, { wired: "", refMap })
+    expect(text?.trim().length).toBeGreaterThan(0)
+  })
+
+  it("ai-writer: a fan-out item, else the wire, else the typed userInput, else the legacy prompt", () => {
+    expect(computeAiWriterInput({ userInput: "typed", prompt: "legacy" }, { override: "item", wired: "wire" })).toBe("item")
+    expect(computeAiWriterInput({ userInput: "typed", prompt: "legacy" }, { wired: "wire" })).toBe("wire")
+    expect(computeAiWriterInput({ userInput: "typed", prompt: "legacy" }, { wired: "  " })).toBe("typed")
+    expect(computeAiWriterInput({ prompt: "legacy" }, {})).toBe("legacy")
+    expect(computeAiWriterInput({}, { wired: "" })).toBe("")
+    expect(computeNodeSendText("ai-writer", {}, { wired: "", refMap: none })).toBe("")
+  })
+
+  it("generate-script: the topic is the wire or the typed prompt", () => {
+    expect(computeNodeSendText("generate-script", { prompt: "a cat" }, { refMap: none })).toContain("a cat")
+    expect(computeNodeSendText("generate-script", {}, { wired: "", refMap: none })).toBe("")
+  })
+
+  it("generate-music: typed lyrics count as something to send when the prompt is empty", () => {
+    expect(computeNodeSendText("generate-music", { lyrics: "la la" }, { wired: "", refMap: none })).toBe("la la")
+    expect(computeNodeSendText("generate-music", {}, { wired: "", refMap: none })).toBe("")
+  })
+
+  it("collection-write: the item (a fan-out row, else the wire), else a typed title / text / link; nothing of those is nothing to save", () => {
+    const refMap = new Map<string, string>()
+    expect(computeNodeSendText("collection-write", {}, { wired: "", refMap })).toBe("")
+    expect(computeNodeSendText("collection-write", { title: " " }, { wired: "", refMap })).toBe("")
+    expect(computeNodeSendText("collection-write", { link: "https://news.example.test/daily" }, { wired: "", refMap })).toBe("https://news.example.test/daily")
+    expect(computeNodeSendText("collection-write", { title: "Daily" }, { wired: "the wire", refMap })).toBe("the wire")
+    expect(computeNodeSendText("collection-write", {}, { override: "row 3", wired: "the wire", refMap })).toBe("row 3")
+  })
+
+  it("prompt pre/post text never counts as something to send: an empty core with a prefix is nothing", () => {
+    const refMap = new Map<string, string>()
+    const affixed = { userInput: "", promptPrefix: "Write a news item about:", promptSuffix: "Keep it short." }
+    expect(computeNodeSendText("llm-chat", affixed, { wired: "", refMap })).toBe("")
+    expect(computeNodeSendText("generate-script", { prompt: "", promptPrefix: "Topic:" }, { wired: "", refMap })).toBe("")
+    expect(computeNodeSendText("text-to-speech", { promptPrefix: "Say:" }, { wired: "", refMap })).toBe("")
+    // With a core, the decision is on the core — non-empty either way.
+    expect(computeNodeSendText("llm-chat", affixed, { wired: "the posts", refMap })).not.toBe("")
+  })
+
+  it("generate-image: the prompt it would send (a fan-out row, else the wire, else the typed prompt); nothing of those is nothing", () => {
+    const refMap = new Map<string, string>()
+    expect(computeNodeSendText("generate-image", { prompt: "" }, { wired: "", refMap })).toBe("")
+    expect(computeNodeSendText("generate-image", { prompt: "a city at dusk" }, { wired: "", refMap })).toBe("a city at dusk")
+    expect(computeNodeSendText("generate-image", { prompt: "" }, { wired: "a cover for the story", refMap })).toBe("a cover for the story")
+    expect(computeNodeSendText("generate-image", { prompt: "", promptPrefix: "Photo of" }, { wired: "", refMap })).toBe("")
+  })
+
+  it("text-to-speech / text-to-audio: the wired text passes through; nothing wired and nothing typed is nothing", () => {
+    expect(computeNodeSendText("text-to-speech", {}, { wired: "read this", refMap: none })).toContain("read this")
+    expect(computeNodeSendText("text-to-speech", {}, { wired: "", refMap: none })).toBe("")
+    expect(computeNodeSendText("text-to-audio", {}, { wired: "rain", refMap: none })).toContain("rain")
+    expect(computeNodeSendText("text-to-audio", {}, { refMap: none })).toBe("")
+  })
+})

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

@@ -321,5 +321,7 @@ describe("blended cut — the rule holds for every row and lever (self-consisten
         check([a, b], levers(position, duration, "natural"), "clip")
       }
     }
-  })
+    // An exhaustive sweep: under a second locally, but past vitest's 5 s default
+    // on a loaded 2-vCPU CI runner (it timed out there three times on 2026-10-05).
+  }, 60_000)
 })

package/src/audio-tags.ts

@@ -0,0 +1,36 @@
+/**
+ * Remove inline `[audio tags]` from speech text, for a model that does not
+ * perform them (it would read them aloud). Pure, dependency-free: the
+ * backend's credit counter (lib/speech-credits.ts), its payload builder and
+ * the editor's estimate (frontend/src/lib/speech-estimate.ts) all read it, so
+ * the two engines count exactly the same characters.
+ *
+ * A tag is `[`, one or more characters that are not `]`, then `]` — what
+ * `/\[[^\]]+\]/g` matches. That pattern is quadratic on an unclosed run of `[`
+ * (every `[` rescans to the end of the text), and the credit counter runs this
+ * on raw request text on the API and orchestrator event loops, so the scan is
+ * written by hand: one `indexOf` per `[`, and when no `]` is left no later `[`
+ * can match either, so the rest of the text is kept in one slice.
+ */
+function removeBracketTags(text: string): string {
+  let out = ""
+  let from = 0
+  let open = text.indexOf("[")
+  while (open !== -1) {
+    const close = text.indexOf("]", open + 1)
+    if (close === -1) break
+    if (close === open + 1) {
+      // "[]" is not a tag (needs 1+ characters); the "[" stays and the scan moves on.
+      open = text.indexOf("[", open + 1)
+      continue
+    }
+    out += text.slice(from, open)
+    from = close + 1
+    open = text.indexOf("[", from)
+  }
+  return out + text.slice(from)
+}
+
+export function stripAudioTags(text: string): string {
+  return removeBracketTags(text).replace(/\s{2,}/g, " ").trim()
+}