@nodaro/shared 3.11.0 → 3.12.1

package/src/__tests__/trigger-feeds.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest"
+import { buildFeedMaps, nodeFeedsAnything } from "../trigger-feeds.js"
+
+const node = (id: string, extra: Record<string, unknown> = {}) => ({ id, ...extra })
+const edge = (source: string, target: string) => ({ source, target })
+
+describe("buildFeedMaps — every way one node feeds another", () => {
+  it("a drawn edge feeds; an edge whose end left the graph feeds nothing; a self-loop feeds nothing", () => {
+    const { children, parents } = buildFeedMaps([node("a"), node("b")], [edge("a", "b"), edge("a", "gone"), edge("gone", "b"), edge("b", "b")])
+    expect(children.get("a")).toEqual(["b"])
+    expect(children.get("b")).toBeUndefined()
+    expect(parents.get("b")).toEqual(["a"])
+    expect(children.has("gone")).toBe(false)
+  })
+
+  it("a node inside a Group feeds the group", () => {
+    const { children } = buildFeedMaps([node("img", { parentId: "G" }), node("G")], [])
+    expect(children.get("img")).toEqual(["G"])
+  })
+
+  it("a field mapping feeds its node by sourceNodeId, even with no edge", () => {
+    const { children, parents } = buildFeedMaps(
+      [node("style"), node("img", { data: { fieldMappings: { prompt: { sourceNodeId: "style" }, seed: { sourceNodeId: "gone" } } } })],
+      [],
+    )
+    expect(children.get("style")).toEqual(["img"])
+    expect(parents.get("img")).toEqual(["style"])
+  })
+})
+
+describe("nodeFeedsAnything — the editor's 'is this trigger wired?'", () => {
+  it("agrees with the maps in both directions", () => {
+    const nodes = [node("sched"), node("img"), node("G"), node("member", { parentId: "G" })]
+    expect(nodeFeedsAnything(nodes, [edge("sched", "img")], "sched")).toBe(true)
+    expect(nodeFeedsAnything(nodes, [edge("sched", "gone")], "sched")).toBe(false)
+    expect(nodeFeedsAnything(nodes, [], "member")).toBe(true)
+    expect(nodeFeedsAnything(nodes, [], "sched")).toBe(false)
+  })
+})

package/src/__tests__/video-duration-auto.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest"
+import {
+  VIDEO_DURATION_AUTO,
+  isAutoVideoDuration,
+  supportsAutoVideoDuration,
+  maxVideoDurationSec,
+  pricedOutputDurationSec,
+  buildVideoCreditModelIdentifier,
+  normalizeModelInput,
+  validateModelInput,
+  MODEL_CATALOG,
+  SEEDANCE_2_PROVIDERS,
+} from "../index.js"
+
+/**
+ * Auto duration (`duration: -1`) — the model picks the clip length. The risk is
+ * entirely on the billing side: `commit_credits` refunds a surplus but never
+ * collects a deficit, so an Auto run must be PRICED at the longest clip the
+ * model can render, on every lane, by default.
+ */
+describe("auto video duration", () => {
+  it("is KIE's own sentinel, from a number or a string", () => {
+    expect(VIDEO_DURATION_AUTO).toBe(-1)
+    expect(isAutoVideoDuration(-1)).toBe(true)
+    expect(isAutoVideoDuration("-1")).toBe(true)
+    for (const v of [undefined, null, 0, 1, 8, "8", "auto", NaN]) expect(isAutoVideoDuration(v), String(v)).toBe(false)
+  })
+
+  it("is a catalog capability of exactly the Seedance 2 family", () => {
+    const declared = Object.keys(MODEL_CATALOG).filter((id) => MODEL_CATALOG[id]!.autoDuration === true).sort()
+    expect(declared).toEqual([...SEEDANCE_2_PROVIDERS].sort())
+    for (const id of declared) expect(supportsAutoVideoDuration(id)).toBe(true)
+    expect(supportsAutoVideoDuration("kling-3.0")).toBe(false)
+    expect(supportsAutoVideoDuration(undefined)).toBe(false)
+  })
+
+  it("prices at the model's LONGEST clip — the top tier is also the catalog's longest duration", () => {
+    for (const id of SEEDANCE_2_PROVIDERS) {
+      const ceiling = maxVideoDurationSec(id)!
+      expect(ceiling, id).toBe(Math.max(...MODEL_CATALOG[id]!.durations!))
+      expect(pricedOutputDurationSec(id, VIDEO_DURATION_AUTO), id).toBe(ceiling)
+      expect(pricedOutputDurationSec(id, "-1"), id).toBe(ceiling)
+    }
+    expect(pricedOutputDurationSec("seedance-2-5", -1)).toBe(30)
+    expect(pricedOutputDurationSec("seedance-2", -1)).toBe(15)
+  })
+
+  it("never prices the cheapest tier for Auto (the under-reserve this guards)", () => {
+    expect(buildVideoCreditModelIdentifier("seedance-2-5", -1, undefined, undefined, undefined, "480p")).toBe("seedance-2-5:30s:480p")
+    expect(buildVideoCreditModelIdentifier("seedance-2", -1, undefined, undefined, undefined, "720p", true)).toBe("seedance-2:15s:720p-ref")
+  })
+
+  it("a model without the capability prices its render default, not a ceiling it will not render", () => {
+    expect(pricedOutputDurationSec("minimax-h3", -1)).toBe(pricedOutputDurationSec("minimax-h3", undefined))
+    expect(pricedOutputDurationSec("seedance-2-5", 0)).toBe(pricedOutputDurationSec("seedance-2-5", undefined))
+  })
+
+  it("passes the catalog normalizer and validator only where declared", () => {
+    expect(normalizeModelInput("seedance-2-5", { duration: -1 }).duration).toBe(-1)
+    expect(validateModelInput("seedance-2-5", { duration: -1 })).toBeNull()
+    const other = Object.keys(MODEL_CATALOG).find((id) => MODEL_CATALOG[id]!.durations && !MODEL_CATALOG[id]!.autoDuration)!
+    expect(normalizeModelInput(other, { duration: -1 }).duration).toBe(MODEL_CATALOG[other]!.durations![0])
+    expect(validateModelInput(other, { duration: -1 })?.field).toBe("duration")
+  })
+})

package/src/__tests__/video-duration.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest"
+import { editPlanSourceDurationSec, extractVideoDurationFromNode } from "../video-duration.js"
+
+describe("editPlanSourceDurationSec", () => {
+  it("reads a video node's own length first", () => {
+    expect(editPlanSourceDurationSec({ duration: 90 })).toBe(90)
+    expect(editPlanSourceDurationSec({ activeResultIndex: 0, generatedResults: [{ duration: 42 }] })).toBe(42)
+    expect(extractVideoDurationFromNode({ duration: 90 })).toBe(90)
+  })
+
+  it("reads the audio lane's metadata.durationSeconds (upload-audio: unstamped, trusted as ever)", () => {
+    expect(editPlanSourceDurationSec({ url: "https://cdn/a.mp3", metadata: { durationSeconds: 2700 } })).toBe(2700)
+  })
+
+  it("rejects nonsense lengths", () => {
+    for (const bad of [0, -1, Number.NaN, Number.POSITIVE_INFINITY, "2700", null]) {
+      expect(editPlanSourceDurationSec({ metadata: { durationSeconds: bad } })).toBeUndefined()
+    }
+    expect(editPlanSourceDurationSec(undefined)).toBeUndefined()
+    expect(editPlanSourceDurationSec({})).toBeUndefined()
+  })
+})
+
+// The read-side invariant. A length stamped with the media it was measured from
+// is trusted only while that media is still the node's — so NO writer can make
+// it stale: not a copilot patch, an MCP workflow-JSON write, an import, a
+// run-time override, nor code that has not been written yet. A mismatch reads as
+// "unknown", and every caller then falls to its safe side instead of
+// under-bucketing a longer file.
+describe("editPlanSourceDurationSec — a stamped length is bound to its media", () => {
+  const stamped = (mediaUrl: string) => ({ durationSeconds: 720, mediaUrl })
+
+  it("trusts the length while the stamp matches the node's extracted audio", () => {
+    expect(
+      editPlanSourceDurationSec({ extractedAudioUrl: "https://cdn/ep41.mp3", metadata: stamped("https://cdn/ep41.mp3") }),
+    ).toBe(720)
+  })
+
+  it("ignores it once the media was swapped underneath — whoever swapped it", () => {
+    // e.g. copilot `patchNodes { extractedAudioUrl }` / MCP update_workflow_json:
+    // a shallow merge that replaces the url and carries `metadata` along.
+    expect(
+      editPlanSourceDurationSec({ extractedAudioUrl: "https://host/ep42-3h.mp3", metadata: stamped("https://cdn/ep41.mp3") }),
+    ).toBeUndefined()
+  })
+
+  it("ignores it when the media was cleared", () => {
+    expect(editPlanSourceDurationSec({ extractedAudioUrl: "", metadata: stamped("https://cdn/ep41.mp3") })).toBeUndefined()
+    expect(editPlanSourceDurationSec({ metadata: stamped("https://cdn/ep41.mp3") })).toBeUndefined()
+  })
+
+  it("accepts a stamp matching the node's `url` field too (upload-style nodes)", () => {
+    expect(editPlanSourceDurationSec({ url: "https://cdn/a.mp3", metadata: stamped("https://cdn/a.mp3") })).toBe(720)
+    expect(editPlanSourceDurationSec({ url: "https://cdn/b.mp3", metadata: stamped("https://cdn/a.mp3") })).toBeUndefined()
+  })
+})

package/src/__tests__/video-link.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect } from "vitest"
+import {
+  SOCIAL_VIDEO_HOSTS,
+  YOUTUBE_HOSTS,
+  INSTAGRAM_HOSTS,
+  VIDEO_LINK_TOLERANT_CONSUMER_TYPES,
+  hasUrlParserHazard,
+  hostnameMatchesAllowlist,
+  isSocialVideoUrl,
+  detectVideoLinkPlatform,
+  videoLinkDownloadedFile,
+  resolveVideoLinkOutput,
+  videoLinkNeedsDownload,
+} from "../video-link.js"
+
+describe("social video host allowlist", () => {
+  it("admits the domain itself and true subdomains only", () => {
+    expect(hostnameMatchesAllowlist("youtube.com", YOUTUBE_HOSTS)).toBe(true)
+    expect(hostnameMatchesAllowlist("www.youtube.com", YOUTUBE_HOSTS)).toBe(true)
+    expect(hostnameMatchesAllowlist("m.youtu.be", YOUTUBE_HOSTS)).toBe(true)
+    expect(hostnameMatchesAllowlist("YOUTUBE.COM.", YOUTUBE_HOSTS)).toBe(true)
+  })
+
+  it("rejects a lookalike host that merely CONTAINS an allowlisted name", () => {
+    expect(hostnameMatchesAllowlist("evilyoutube.com", YOUTUBE_HOSTS)).toBe(false)
+    expect(hostnameMatchesAllowlist("youtube.com.attacker.example", YOUTUBE_HOSTS)).toBe(false)
+    // "x.com" is a substring of "netflix.com" — the old loose regex called this X.
+    expect(isSocialVideoUrl("https://www.netflix.com/watch/1")).toBe(false)
+  })
+
+  it("keeps the YouTube and Instagram subsets inside the full list", () => {
+    for (const h of [...YOUTUBE_HOSTS, ...INSTAGRAM_HOSTS]) {
+      expect(SOCIAL_VIDEO_HOSTS).toContain(h)
+    }
+  })
+
+  it("isSocialVideoUrl never throws on junk", () => {
+    expect(isSocialVideoUrl("")).toBe(false)
+    expect(isSocialVideoUrl("not a url")).toBe(false)
+    expect(isSocialVideoUrl("ftp://youtube.com/x")).toBe(false)
+    expect(isSocialVideoUrl("https://www.tiktok.com/@a/video/1")).toBe(true)
+    expect(isSocialVideoUrl("https://www.tiktok.com/@a/video/1", YOUTUBE_HOSTS)).toBe(false)
+  })
+})
+
+describe("links that URL parsers read differently", () => {
+  const BACKSLASH = "https://tiktok.com\\@169.254.169.254/latest/meta-data"
+
+  it("flags a backslash and every ASCII control character, and nothing else", () => {
+    expect(hasUrlParserHazard(BACKSLASH)).toBe(true)
+    for (const ch of ["\t", "\n", "\r", "\u0000", "\u001f", "\u007f"]) {
+      expect(hasUrlParserHazard(`https://youtu.be/aqz${ch}-KE-bpKQ`)).toBe(true)
+    }
+    expect(hasUrlParserHazard("https://www.youtube.com/watch?v=aqz-KE-bpKQ&t=30s#x")).toBe(false)
+    expect(hasUrlParserHazard("https://pub-x.r2.dev/avideo%20preview/98.mp4")).toBe(false)
+    expect(hasUrlParserHazard("https://example.com/שלום עולם.mp4")).toBe(false)
+    expect(hasUrlParserHazard("")).toBe(false)
+  })
+
+  it("is refused as a social link even though its WHATWG host is allowlisted", () => {
+    // The reading THIS file would make: host tiktok.com. The download tool is
+    // handed the raw string and may read 169.254.169.254.
+    expect(new URL(BACKSLASH).hostname).toBe("tiktok.com")
+    expect(isSocialVideoUrl(BACKSLASH)).toBe(false)
+    expect(detectVideoLinkPlatform(BACKSLASH)).toBe("unknown")
+    expect(videoLinkNeedsDownload({ youtubeUrl: BACKSLASH })).toBe(false)
+  })
+})
+
+describe("consumers that do not need the video file", () => {
+  it("names exactly the three readers that take the audio track or the page link", () => {
+    expect([...VIDEO_LINK_TOLERANT_CONSUMER_TYPES].sort()).toEqual(["dubbing", "suno-cover", "transcribe"])
+  })
+})
+
+describe("detectVideoLinkPlatform", () => {
+  it.each([
+    ["https://www.youtube.com/watch?v=aqz-KE-bpKQ", "youtube"],
+    ["https://youtu.be/aqz-KE-bpKQ?si=x", "youtube"],
+    ["https://music.youtube.com/watch?v=aqz-KE-bpKQ", "youtube"],
+    ["https://www.instagram.com/reels/DaK89TnRB5m/", "instagram"],
+    ["https://vm.tiktok.com/ZS99nqdaG/", "tiktok"],
+    ["https://x.com/someone/status/123", "twitter"],
+    ["https://twitter.com/someone/status/123", "twitter"],
+    ["https://fb.watch/abc/", "facebook"],
+    ["https://www.facebook.com/reel/123", "facebook"],
+    ["https://cdn.nodaro.ai/videos/yt-1.mp4", "unknown"],
+    ["https://www.netflix.com/watch/1", "unknown"],
+    ["garbage", "unknown"],
+  ])("%s → %s", (url, platform) => {
+    expect(detectVideoLinkPlatform(url)).toBe(platform)
+  })
+})
+
+describe("Video URL node output", () => {
+  const YT = "https://www.youtube.com/watch?v=aqz-KE-bpKQ"
+  const FILE = "https://cdn.nodaro.ai/videos/yt-1.mp4"
+
+  it("emits the downloaded file when there is one", () => {
+    expect(resolveVideoLinkOutput({ youtubeUrl: YT, downloadedVideoUrl: FILE, downloadedFromUrl: YT })).toBe(FILE)
+  })
+
+  it("trusts a downloaded file with no recorded source — every node saved before the field existed", () => {
+    expect(resolveVideoLinkOutput({ youtubeUrl: YT, downloadedVideoUrl: FILE })).toBe(FILE)
+  })
+
+  it("does NOT emit a file that was downloaded from a different link", () => {
+    const data = { youtubeUrl: "https://youtu.be/otherVideo01", downloadedVideoUrl: FILE, downloadedFromUrl: YT }
+    expect(videoLinkDownloadedFile(data)).toBeUndefined()
+    // Falls back to the link itself, never to the wrong video.
+    expect(resolveVideoLinkOutput(data)).toBe("https://youtu.be/otherVideo01")
+  })
+
+  it("passes a direct file link through untouched (the Welcome Demo / saved-template shape)", () => {
+    expect(resolveVideoLinkOutput({ youtubeUrl: ` ${FILE} ` })).toBe(FILE)
+    expect(videoLinkNeedsDownload({ youtubeUrl: FILE })).toBe(false)
+  })
+
+  it("is undefined for an empty node", () => {
+    expect(resolveVideoLinkOutput({})).toBeUndefined()
+    expect(resolveVideoLinkOutput({ youtubeUrl: "   " })).toBeUndefined()
+  })
+
+  it("needs a download exactly when the link is social and no file matches it", () => {
+    expect(videoLinkNeedsDownload({ youtubeUrl: YT })).toBe(true)
+    expect(videoLinkNeedsDownload({ youtubeUrl: YT, downloadedVideoUrl: FILE, downloadedFromUrl: YT })).toBe(false)
+    expect(videoLinkNeedsDownload({ youtubeUrl: YT, downloadedVideoUrl: FILE })).toBe(false)
+    expect(videoLinkNeedsDownload({ youtubeUrl: "https://youtu.be/otherVideo01", downloadedVideoUrl: FILE, downloadedFromUrl: YT })).toBe(true)
+    expect(videoLinkNeedsDownload({ youtubeUrl: "https://example.com/page" })).toBe(false)
+    expect(videoLinkNeedsDownload({})).toBe(false)
+  })
+
+  it("ignores non-string junk in the fields", () => {
+    expect(resolveVideoLinkOutput({ youtubeUrl: 5, downloadedVideoUrl: null })).toBeUndefined()
+    expect(videoLinkNeedsDownload({ youtubeUrl: { a: 1 } })).toBe(false)
+  })
+})

package/src/__tests__/workflow-export-strip.test.ts

@@ -1,8 +1,30 @@
 import { describe, it, expect } from "vitest"
-import { stripExportContent } from "../workflow-export.js"
+import { stripExportContent, stripUnownedRefs } from "../workflow-export.js"
 import { EXECUTION_DATA_KEYS } from "../node-runtime-keys.js"
 import type { GenericNode } from "../types.js"
 
+describe("stripExportContent — a Schedule Trigger never exports armed", () => {
+  it("drops `active` and keeps the schedule itself", () => {
+    const node: GenericNode = {
+      id: "s1",
+      type: "schedule-trigger",
+      data: { label: "Daily", rules: [{ id: "rule-1", kind: "days", every: 1, hour: 9, minute: 0 }], timezone: "Asia/Jerusalem", maxExecutions: 3, active: true },
+    }
+    const [out] = stripExportContent([node])
+    const data = out.data as Record<string, unknown>
+    expect(data.active).toBeUndefined()
+    expect(data.rules).toEqual([{ id: "rule-1", kind: "days", every: 1, hour: 9, minute: 0 }])
+    expect(data.timezone).toBe("Asia/Jerusalem")
+    expect(data.maxExecutions).toBe(3)
+  })
+
+  it("a schedule that was never armed is exported unchanged", () => {
+    const node: GenericNode = { id: "s1", type: "schedule-trigger", data: { label: "Daily", rules: [{ id: "rule-1", kind: "days", every: 1, hour: 9, minute: 0 }] } }
+    const [out] = stripExportContent([node])
+    expect(out.data).toEqual(node.data)
+  })
+})
+
 /**
  * Invariant guard for the template-export leak class (audit R2-H4): a
  * "shareable" template export must never carry runtime/result fields —
@@ -36,6 +58,42 @@ describe("stripExportContent — template export hygiene", () => {
     expect(outData.shots, "shots (Kling-3 config) must NOT be stripped").toBe("SENSITIVE_RUNTIME_VALUE")
   })
 
+  it("clears a Webhook Output's credentialId and a publisher's connectionId — pointers at rows the importer does not own", () => {
+    const hook: GenericNode = {
+      id: "h1",
+      type: "webhook-output",
+      data: { url: "https://mine.example/hook", credentialId: "11111111-1111-4111-8111-111111111111", params: [] },
+    }
+    const post: GenericNode = { id: "p1", type: "telegram-post", data: { connectionId: "conn-1", text: "hello" } }
+    const [outHook, outPost] = stripExportContent([hook, post])
+    expect((outHook.data as Record<string, unknown>).credentialId).toBeUndefined()
+    expect((outHook.data as Record<string, unknown>).url).toBe("https://mine.example/hook")
+    expect((outPost.data as Record<string, unknown>).connectionId).toBeUndefined()
+    expect((outPost.data as Record<string, unknown>).text).toBe("hello")
+  })
+
+  it("stripUnownedRefs alone covers the asset-bundle export, which keeps every other field", () => {
+    const hook: GenericNode = {
+      id: "h1",
+      type: "webhook-output",
+      data: { url: "https://mine.example/hook", credentialId: "11111111-1111-4111-8111-111111111111", webhookResponseBody: "kept by this pass" },
+    }
+    const other: GenericNode = { id: "g1", type: "generate-image", data: { credentialId: "not-a-webhook", prompt: "a cat" } }
+    const [outHook, outOther] = stripUnownedRefs([hook, other])
+    expect((outHook.data as Record<string, unknown>).credentialId).toBeUndefined()
+    // Only the owner-bound pointer goes; the bundle's verbatim-data contract holds for the rest.
+    expect((outHook.data as Record<string, unknown>).webhookResponseBody).toBe("kept by this pass")
+    // A node type that has no owner-bound field is returned as-is.
+    expect(outOther).toBe(other)
+    expect(hook.data.credentialId, "input not mutated").toBe("11111111-1111-4111-8111-111111111111")
+  })
+
+  it("the webhook delivery receipt is a runtime key — a reflected secret never rides a template", () => {
+    for (const key of ["webhookSuccess", "webhookStatusCode", "webhookResponseBody"]) {
+      expect(EXECUTION_DATA_KEYS.has(key), key).toBe(true)
+    }
+  })
+
   it("clears faceDbId / referencedWorkflowId on face + sub-workflow template nodes", () => {
     const face: GenericNode = { id: "f1", type: "face", data: { faceDbId: "exporter-face-id", name: "Hero" } }
     const sub: GenericNode = { id: "s1", type: "sub-workflow", data: { referencedWorkflowId: "exporter-wf-id" } }

package/src/caption-styles.ts

@@ -1,3 +1,5 @@
+import type { SupportedFontName } from "./supported-fonts.js"
+
 /**
  * Caption styles for the add-captions node. Static path uses FFmpeg drawtext;
  * kinetic styles render via Remotion (BurnCaptions composition).
@@ -29,3 +31,241 @@ const KINETIC_SET = new Set<string>(KINETIC_CAPTION_STYLES)
 export function isKineticCaptionStyle(style: string | undefined | null): style is KineticCaptionStyle {
   return style !== null && style !== undefined && KINETIC_SET.has(style)
 }
+
+// ── Named "looks" ──────────────────────────────────────────────────────────
+// A look is a bundle of visual levers so a caption reads well with one field
+// instead of eight. Shared because the ids are wire contract (route Zod, MCP
+// schema, SDK type) and the value table is consumed by BOTH the worker (render)
+// and the canvas preview — deliberately given away, not creative doctrine.
+export const CAPTION_LOOK_IDS = ["outline", "clean"] as const
+export type CaptionLookId = (typeof CAPTION_LOOK_IDS)[number]
+
+/** What an unset `look` means on a KINETIC style. ONE-LINE FLIP: set to "clean"
+ *  to make an unset caption render as the pre-look-system lever set (face pinned)
+ *  instead. */
+export const DEFAULT_CAPTION_LOOK: CaptionLookId = "outline"
+
+/** What an unset `look` means on the static `subtitle` style: the plain read —
+ *  a pinned neutral sans, no outline, no casing. A subtitle must never be left
+ *  with NO face: the Remotion render would fall back to headless Chrome's default
+ *  SERIF, so adding e.g. a stroke to a subtitle would silently flip its font away
+ *  from the sans the plain FFmpeg subtitle draws. */
+export const DEFAULT_SUBTITLE_LOOK: CaptionLookId = "clean"
+
+/**
+ * The lever field names that are MEANINGLESS on a `subtitle` render and so are
+ * rejected on it: `highlightColor` (subtitle has no per-word spoken cursor to
+ * colour) and `animate` (subtitle has no motion to switch off). The STYLING
+ * levers (look/fontFamily/fontWeight/strokeColor/strokeWidth/uppercase/positionY)
+ * are NOT here any more — a `subtitle` carrying any of them now routes to the
+ * Remotion renderer (see `captionRoutesToRemotion`), which applies them exactly
+ * as it does for the kinetic styles. Single source of truth for the route's
+ * reject-on-subtitle guard and the frontend's "don't send a stale lever" strip.
+ * `color`/`backgroundColor` are deliberately absent — FFmpeg subtitle honours
+ * those too.
+ */
+export const KINETIC_ONLY_CAPTION_LEVER_KEYS = [
+  "highlightColor",
+  "animate",
+] as const
+export type KineticOnlyCaptionLeverKey = (typeof KINETIC_ONLY_CAPTION_LEVER_KEYS)[number]
+
+/**
+ * Does an add-captions request need the Remotion renderer, vs the cheap static
+ * FFmpeg drawtext path? A caption routes to Remotion when it needs anything the
+ * one-fixed-string drawtext pass cannot do:
+ *   - per-segment treatments (`segments`),
+ *   - a kinetic style,
+ *   - any STYLING lever (look/font/weight/stroke/uppercase/position_y/
+ *     max_words_per_line) — FFmpeg drawtext can't apply a webfont face, weight,
+ *     outline, casing, a free vertical position, or line grouping,
+ *   - TIMED captions (a wired `transcript` or an explicit `captions[]` array),
+ *   - auto-transcription, i.e. no `text` to burn as one static block.
+ * Plain-`text` `subtitle` with no lever stays on FFmpeg (unchanged, cheap).
+ *
+ * SINGLE SOURCE for BOTH the worker dispatch (handleAddCaptions) AND the credit
+ * id (buildAddCaptionsCreditId) so the renderer and the price never drift: a
+ * Remotion render bills as `add-captions:kinetic`, a plain drawtext burn as
+ * `add-captions`.
+ */
+export function captionRoutesToRemotion(input: {
+  style?: string | null
+  text?: string | null
+  segments?: readonly unknown[] | null
+  transcript?: unknown
+  captions?: readonly unknown[] | null
+  look?: unknown
+  fontFamily?: unknown
+  fontWeight?: unknown
+  strokeColor?: unknown
+  strokeWidth?: unknown
+  uppercase?: unknown
+  positionY?: unknown
+  maxWordsPerLine?: unknown
+}): boolean {
+  if (input.segments && input.segments.length > 0) return true
+  if (isKineticCaptionStyle(input.style)) return true
+  // From here the style is `subtitle` (or unset → the subtitle default).
+  // `null` is "not set", exactly like `undefined`: stored node JSON (an agent's
+  // write, an import, a cleared field) carries nulls, and a null lever that
+  // counted as a lever would route a plain subtitle to Remotion — and its price
+  // — for a lever nobody chose.
+  const isSet = (v: unknown): boolean => v !== undefined && v !== null
+  const hasStylingLever =
+    isSet(input.look) ||
+    isSet(input.fontFamily) ||
+    isSet(input.fontWeight) ||
+    isSet(input.strokeColor) ||
+    isSet(input.strokeWidth) ||
+    isSet(input.uppercase) ||
+    isSet(input.positionY) ||
+    isSet(input.maxWordsPerLine)
+  if (hasStylingLever) return true
+  if (input.transcript !== undefined && input.transcript !== null) return true
+  if (input.captions && input.captions.length > 0) return true
+  // No `text` to burn as one static block → the only caption source is
+  // transcription, which produces TIMED captions the drawtext pass can't show.
+  if (!input.text) return true
+  return false
+}
+
+/**
+ * `maxWordsPerLine` — caps how many words a caption LINE (or tiktok-words page)
+ * may hold, on top of the frame-width budget, sentence ends and pauses that
+ * already close a line. 1–2 gives the punchy CapCut read; unset = fit the width.
+ * Applies to every line/page-grouped render (word-highlight, karaoke, bouncy,
+ * tiktok-words, and a Remotion-rendered subtitle); inert on word-pop (always one
+ * word). Bounds single-sourced here for the route Zod, the plan schema, the MCP
+ * schema, the CLI and the canvas panel.
+ */
+export const CAPTION_MAX_WORDS_PER_LINE_MIN = 1
+export const CAPTION_MAX_WORDS_PER_LINE_MAX = 20
+
+/**
+ * Numeric caption levers and their wire bounds — the SAME limits the route Zod
+ * and the render-plan schema enforce. Single-sourced so the coercion below and
+ * those schemas cannot disagree (a guard test pins the route to these).
+ */
+export const CAPTION_LEVER_BOUNDS = {
+  fontSize: { min: 12, max: 200 },
+  strokeWidth: { min: 0, max: 40 },
+  positionY: { min: 0, max: 100 },
+  fontWeight: { min: 100, max: 900 },
+  maxWordsPerLine: { min: CAPTION_MAX_WORDS_PER_LINE_MIN, max: CAPTION_MAX_WORDS_PER_LINE_MAX },
+} as const
+
+type CaptionNumericLeverKey = keyof typeof CAPTION_LEVER_BOUNDS
+const CAPTION_NUMERIC_LEVER_KEYS = Object.keys(CAPTION_LEVER_BOUNDS) as CaptionNumericLeverKey[]
+
+/**
+ * COERCE, never reject: bring the numeric caption levers of node data that
+ * never passed a Zod (a workflow written by an agent, an import, a template, a
+ * FieldMapping) into the range the render plan accepts. Without this an
+ * out-of-range value only surfaces when the plan schema throws — mid-run, after
+ * credits are reserved. A `null` / non-finite / non-numeric value is DROPPED (the
+ * render default applies); an out-of-range one is clamped; `fontWeight` snaps to the
+ * nearest 100 and `maxWordsPerLine` to a whole number. Pure; returns a copy and
+ * leaves every other field untouched. Applied by payload-builder to the node's
+ * top level and to each `segments[]` entry.
+ */
+export function normalizeCaptionNumericLevers<T extends Record<string, unknown>>(input: T): T {
+  const out: Record<string, unknown> = { ...input }
+  for (const key of CAPTION_NUMERIC_LEVER_KEYS) {
+    if (!(key in out) || out[key] === undefined) continue
+    // `null` is "not set": drop it rather than carry it — the render plan's
+    // numeric schema rejects a null, mid-run, after credits are reserved.
+    if (out[key] === null) {
+      delete out[key]
+      continue
+    }
+    const raw = typeof out[key] === "string" && (out[key] as string).trim() !== "" ? Number(out[key]) : out[key]
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      delete out[key]
+      continue
+    }
+    const { min, max } = CAPTION_LEVER_BOUNDS[key]
+    const shaped = key === "fontWeight" ? Math.round(raw / 100) * 100 : key === "maxWordsPerLine" ? Math.round(raw) : raw
+    out[key] = Math.min(max, Math.max(min, shaped))
+  }
+  return out as T
+}
+
+/** The concrete levers a look (and any explicit override) resolves to. */
+export interface CaptionLookLevers {
+  fontFamily?: SupportedFontName
+  fontWeight?: number
+  color?: string
+  backgroundColor?: string
+  strokeColor?: string
+  strokeWidth?: number
+  highlightColor?: string
+  uppercase?: boolean
+}
+
+/** Outline width = 10% of font size (min 2px). `paint-order: stroke fill` puts
+ *  half the stroke OUTSIDE the glyph, so the visible rim is ~5% of font size. */
+export function autoStrokeWidth(fontSize: number): number {
+  return Math.max(2, Math.round(fontSize * 0.1))
+}
+
+/** Each look is a function of font size (so the outline tracks the text size). */
+export const CAPTION_LOOKS: Record<CaptionLookId, (fontSize: number) => CaptionLookLevers> = {
+  // The TikTok / CapCut read: heavy geometric sans, caps, white on a thick black
+  // outline, yellow spoken word.
+  outline: (fs) => ({
+    fontFamily: "Montserrat",
+    fontWeight: 900,
+    uppercase: true,
+    color: "#ffffff",
+    strokeColor: "#000000",
+    strokeWidth: autoStrokeWidth(fs),
+    highlightColor: "#FFE600",
+  }),
+  // The pre-look lever set with the face pinned (it never was): per-style weight,
+  // soft shadow only, no casing, no outline.
+  clean: () => ({ fontFamily: "Inter", color: "#ffffff" }),
+}
+
+/**
+ * Resolve a look + explicit overrides into concrete levers. An explicit lever
+ * always wins over the look; `strokeWidth: 0` explicitly means "no outline".
+ * The plan then carries concrete levers only — nothing to resolve at render.
+ */
+export function resolveCaptionLook(
+  look: CaptionLookId | undefined,
+  explicit: CaptionLookLevers,
+  fontSize: number,
+): CaptionLookLevers {
+  // COERCE, never throw. The route Zod rejects a bad `look`, but the orchestrator /
+  // authored-JSON / import / Copilot paths write `look` straight onto node data with
+  // no validation (payload-builder passes `look: data.look` verbatim — the CLAUDE.md
+  // pitfall 5b class). An unknown id here would throw AFTER a paid transcription and
+  // fail the whole run, so an out-of-vocabulary look falls back to the default preset.
+  const preset = CAPTION_LOOKS[look ?? DEFAULT_CAPTION_LOOK] ?? CAPTION_LOOKS[DEFAULT_CAPTION_LOOK]
+  const out: CaptionLookLevers = { ...preset(fontSize) }
+  for (const k of Object.keys(explicit) as (keyof CaptionLookLevers)[]) {
+    if (explicit[k] !== undefined) (out[k] as CaptionLookLevers[typeof k]) = explicit[k]
+  }
+  return out
+}
+
+/**
+ * Resolve the concrete render levers for a caption, applying the DEFAULT look the
+ * way each STYLE expects: an unset `look` means `outline` on a kinetic style (the
+ * TikTok/CapCut read) and `clean` on the static `subtitle` (the plain read — a
+ * pinned neutral sans, no outline, no casing). So a subtitle that routes to
+ * Remotion never inherits the outline house-style unless asked, AND is never left
+ * with no face at all (which renders as headless Chrome's default serif). A named
+ * look always wins; explicit levers override either. SINGLE SOURCE for the worker
+ * top-level levers, the per-segment resolver, and the frontend config/preview
+ * mirror, so the per-style default can't drift between them.
+ */
+export function resolveCaptionLevers(
+  style: string | undefined | null,
+  look: CaptionLookId | undefined,
+  explicit: CaptionLookLevers,
+  fontSize: number,
+): CaptionLookLevers {
+  const effective = look ?? (isKineticCaptionStyle(style) ? DEFAULT_CAPTION_LOOK : DEFAULT_SUBTITLE_LOOK)
+  return resolveCaptionLook(effective, explicit, fontSize)
+}

package/src/credit-identifiers.ts

@@ -28,6 +28,8 @@ import {
   getVideoAudioCapability,
 } from "./model-constants.js"
 import { isFlux2Model, FLUX2_RES_MP, type Flux2Model } from "./flux2-pricing.js"
+import { VIDEO_DURATION_AUTO } from "./video-duration-auto.js"
+import { uiResolutionFill } from "./video-ui-defaults.js"
 import { MODEL_CATALOG, normalizeModelInput, defaultResolutionFor, type ModelInputAdjustment } from "./model-catalog.js"
 
 /**
@@ -461,6 +463,35 @@ export function buildVideoCreditModelIdentifier(
   return identifier
 }
 
+/**
+ * The credit identifier a Video to Video node's Seedance EDIT lane reserves
+ * under. Seedance has no v2v endpoint — the lane is a text-to-video job in edit
+ * shape with the source clip as reference video 1 — so it prices on the
+ * REFERENCE-VIDEO ladder at the model's LONGEST clip (Auto duration), and the
+ * measured settlement refunds down to what was actually delivered.
+ *
+ * It exists because that is a 7-positional-argument call with four
+ * easy-to-transpose slots, and FOUR surfaces must agree on it exactly: the
+ * orchestrator's reservation (payload-builder.ts), the backend pre-run
+ * estimator (ee/billing/credits.ts), the node's cost pill, and the frontend
+ * run-level estimate (config-panels/helpers.ts). A quote that disagrees with
+ * the reserve is the documented `price_not_configured` / blank-pill trap.
+ *
+ * `resolution` is the node's one `v2vResolution` field; when unset the model's
+ * own UI fill is priced, which is what the lane will send.
+ */
+export function seedanceVideoEditCreditId(provider: string, resolution?: string): string {
+  return buildVideoCreditModelIdentifier(
+    provider,
+    VIDEO_DURATION_AUTO,
+    undefined,
+    "text-to-video",
+    undefined,
+    resolution ?? uiResolutionFill(provider),
+    /* hasVideoRef */ true,
+  )
+}
+
 /** What the video credit identifier PRICES for a request, for the levers whose
  *  priced value must also be the value we SEND. */
 export interface PricedVideoSelection {