@nodaro/shared 3.11.0 → 3.12.0

package/src/speaker-layouts.ts

@@ -0,0 +1,220 @@
+/**
+ * Speaker-view presentation registries — the STRUCTURAL vocabulary behind an
+ * EDL segment's `layout` (see `EdlLayout` in `edl.ts`).
+ *
+ * What lives here is structure only: which layout ids exist, how many slots
+ * each takes, which output aspects a renderer exists for, which speaker-switch
+ * ids exist and whether they consume output time, and the atomic emphasis
+ * styles. Taste — default emphasis, which transitions are allowed or preferred
+ * for a show, timing defaults — is deliberately NOT here.
+ *
+ * Every list is widened ADDITIVELY. That is why a finding judged against one of
+ * these registries is a validation WARNING, never an issue: an older validator
+ * must never reject an EDL written by a newer producer that knows more ids.
+ * An executor that cannot honour an id refuses it itself.
+ */
+import type { Edl } from "./edl.js"
+import { COMBINE_TRANSITIONS } from "./combine-transitions.js"
+import { resolveEdlSegmentSlots } from "./edl-multicam.js"
+
+export const EDL_TARGET_ASPECTS = ["16:9", "9:16", "1:1", "4:5"] as const
+export type EdlTargetAspect = (typeof EDL_TARGET_ASPECTS)[number]
+
+const TARGET_ASPECT_SET: ReadonlySet<string> = new Set(EDL_TARGET_ASPECTS)
+
+/** Narrow an open `Edl.meta.targetAspect` (or any value) to a known aspect. */
+export function isEdlTargetAspect(v: unknown): v is EdlTargetAspect {
+  return typeof v === "string" && TARGET_ASPECT_SET.has(v)
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+//  Layouts
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface SpeakerLayoutSheet {
+  readonly id: string
+  /** Inclusive slot-count range when a segment lists `layout.slots`. */
+  readonly minSlots: number
+  readonly maxSlots: number
+  /** The output aspects this layout is DRAWN for (a renderer exists) — not "looks good". Widened additively. */
+  readonly aspects: readonly EdlTargetAspect[]
+}
+
+export const SPEAKER_LAYOUTS: readonly SpeakerLayoutSheet[] = [
+  { id: "single", minSlots: 1, maxSlots: 1, aspects: EDL_TARGET_ASPECTS },
+  { id: "side-by-side", minSlots: 2, maxSlots: 2, aspects: ["16:9", "1:1"] },
+  { id: "stacked", minSlots: 2, maxSlots: 2, aspects: ["9:16", "4:5", "1:1"] },
+  { id: "grid", minSlots: 2, maxSlots: 6, aspects: EDL_TARGET_ASPECTS },
+  { id: "pip", minSlots: 2, maxSlots: 2, aspects: EDL_TARGET_ASPECTS },
+]
+
+export const SPEAKER_LAYOUT_IDS: readonly string[] = SPEAKER_LAYOUTS.map((l) => l.id)
+
+const LAYOUTS_BY_ID: ReadonlyMap<string, SpeakerLayoutSheet> = new Map(SPEAKER_LAYOUTS.map((l) => [l.id, l]))
+
+export function getSpeakerLayout(id: string): SpeakerLayoutSheet | undefined {
+  return LAYOUTS_BY_ID.get(id)
+}
+
+/** Omitted query fields are unconstrained. */
+export function speakerLayoutAllows(
+  sheet: SpeakerLayoutSheet,
+  q: { readonly aspect?: EdlTargetAspect; readonly slotCount?: number },
+): boolean {
+  if (q.aspect !== undefined && !sheet.aspects.includes(q.aspect)) return false
+  if (q.slotCount !== undefined && !(q.slotCount >= sheet.minSlots && q.slotCount <= sheet.maxSlots)) return false
+  return true
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+//  Speaker switches (EdlLayout.transition.type)
+// ─────────────────────────────────────────────────────────────────────────
+
+/** The one prefix of the time-consuming (cross-source blend) switch family. */
+const XFADE_SWITCH_PREFIX = "xfade:"
+
+/** D17: a switch consumes output time iff it is in the `xfade:*` family. THE one overlap rule (edl.ts uses it). */
+export function speakerSwitchOverlaps(type: string): boolean {
+  return typeof type === "string" && type.startsWith(XFADE_SWITCH_PREFIX)
+}
+
+export interface SpeakerSwitchSheet {
+  /** "cut" | "pan" | "zoom" | `xfade:${combine id}` */
+  readonly id: string
+  /** = `speakerSwitchOverlaps(id)`, derived, never hand-set. */
+  readonly overlaps: boolean
+  /** true only for `pan`: an eased sweep between two regions of ONE picture source. */
+  readonly requiresSameSource: boolean
+}
+
+const switchSheet = (id: string, requiresSameSource: boolean): SpeakerSwitchSheet => ({
+  id,
+  overlaps: speakerSwitchOverlaps(id),
+  requiresSameSource,
+})
+
+/** `cut` / `pan` / `zoom` consume no time (pan: a geometry tween inside ONE
+ *  source; zoom: a tween inside each segment). The `xfade:*` family is DERIVED
+ *  from every combine-videos transition that is a real ffmpeg xfade (so never
+ *  `cut`, which has no xfade) — it is never hand-listed here. */
+export const SPEAKER_SWITCHES: readonly SpeakerSwitchSheet[] = [
+  switchSheet("cut", false),
+  switchSheet("pan", true),
+  switchSheet("zoom", false),
+  ...COMBINE_TRANSITIONS.filter((t) => t.xfade !== null).map((t) => switchSheet(XFADE_SWITCH_PREFIX + t.id, false)),
+]
+
+export const SPEAKER_SWITCH_IDS: readonly string[] = SPEAKER_SWITCHES.map((s) => s.id)
+
+const SWITCHES_BY_ID: ReadonlyMap<string, SpeakerSwitchSheet> = new Map(SPEAKER_SWITCHES.map((s) => [s.id, s]))
+
+/** A plain lookup: `undefined` for an unknown id (never throws). */
+export function getSpeakerSwitch(id: string): SpeakerSwitchSheet | undefined {
+  return SWITCHES_BY_ID.get(id)
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+//  Emphasis (EdlLayout.emphasis.style)
+// ─────────────────────────────────────────────────────────────────────────
+
+/** Atomic emphasis styles; `layout.emphasis.style` is a "+"-joined set of
+ *  them. `none` stands alone (it means "no emphasis"), and an atom appears at
+ *  most once. */
+export const SPEAKER_EMPHASIS_STYLES = ["none", "scale", "border", "dim"] as const
+export type SpeakerEmphasisStyle = (typeof SPEAKER_EMPHASIS_STYLES)[number]
+
+const EMPHASIS_STYLE_SET: ReadonlySet<string> = new Set(SPEAKER_EMPHASIS_STYLES)
+
+/** Split a `+`-joined style into its atoms: trimmed, empties dropped. */
+export function parseSpeakerEmphasisStyle(style: string): readonly string[] {
+  if (typeof style !== "string") return []
+  return style
+    .split("+")
+    .map((atom) => atom.trim())
+    .filter((atom) => atom.length > 0)
+}
+
+/** At least one atom, every atom a known `SPEAKER_EMPHASIS_STYLES` id, no
+ *  atom repeated, and `none` only on its own ("none+scale" contradicts itself). */
+export function isKnownSpeakerEmphasisStyle(style: string): boolean {
+  const atoms = parseSpeakerEmphasisStyle(style)
+  if (atoms.length === 0 || !atoms.every((atom) => EMPHASIS_STYLE_SET.has(atom))) return false
+  if (new Set(atoms).size !== atoms.length) return false
+  return !(atoms.includes("none") && atoms.length > 1)
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+//  Registry-derived findings
+// ─────────────────────────────────────────────────────────────────────────
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object"
+
+/** Registry-derived findings — ALL warning-class. Pure; never throws (guard non-array sources/segments the
+ *  way validateEdl does). `validateEdl` already includes these in its `warnings`; call this directly only
+ *  when you want the presentation findings alone. */
+export function speakerPresentationWarnings(edl: Edl): readonly string[] {
+  const warnings: string[] = []
+  if (!isObject(edl)) return warnings
+  // Guard a raw object that skipped normalizeEdl, exactly as validateEdl does.
+  const safe: Edl = {
+    ...edl,
+    sources: Array.isArray(edl.sources) ? edl.sources : [],
+    segments: Array.isArray(edl.segments) ? edl.segments : [],
+  }
+
+  const rawAspect = isObject(safe.meta) ? safe.meta.targetAspect : undefined
+  const aspect = isEdlTargetAspect(rawAspect) ? rawAspect : undefined
+  if (rawAspect != null && aspect === undefined) {
+    warnings.push(`meta.targetAspect "${String(rawAspect)}" is not a known target aspect (known: ${EDL_TARGET_ASPECTS.join(", ")})`)
+  }
+
+  safe.segments.forEach((seg, i) => {
+    if (!isObject(seg) || !isObject(seg.layout)) return
+    const at = `segment[${i}] "${seg.id}"`
+    const layout = seg.layout
+
+    // 1. The layout mode, its slot count, and the output aspect.
+    const sheet = typeof layout.mode === "string" ? getSpeakerLayout(layout.mode) : undefined
+    if (!sheet) {
+      warnings.push(`${at}: unknown layout mode "${String(layout.mode)}" (known: ${SPEAKER_LAYOUT_IDS.join(", ")})`)
+    } else {
+      const slotCount = Array.isArray(layout.slots) ? layout.slots.length : 0
+      if (slotCount > 0 && !speakerLayoutAllows(sheet, { slotCount })) {
+        const range = sheet.minSlots === sheet.maxSlots ? `${sheet.minSlots}` : `${sheet.minSlots}–${sheet.maxSlots}`
+        warnings.push(`${at}: layout "${sheet.id}" takes ${range} slot(s), got ${slotCount}`)
+      }
+      if (aspect !== undefined && !speakerLayoutAllows(sheet, { aspect })) {
+        warnings.push(`${at}: layout "${sheet.id}" is not drawn for targetAspect ${aspect} (drawn for: ${sheet.aspects.join(", ")})`)
+      }
+    }
+
+    // 2. The switch into this segment.
+    if (isObject(layout.transition)) {
+      const type = layout.transition.type
+      const sw = typeof type === "string" ? getSpeakerSwitch(type) : undefined
+      if (!sw) {
+        warnings.push(`${at}: unknown layout transition "${String(type)}" (known: ${SPEAKER_SWITCHES.filter((s) => !s.overlaps).map((s) => s.id).join(", ")}, or ${XFADE_SWITCH_PREFIX}<id> for a combine-videos transition that is a real ffmpeg xfade — never ${XFADE_SWITCH_PREFIX}cut)`)
+      } else if (sw.requiresSameSource && i > 0) {
+        // Only a one-picture → one-picture boundary has a defined "picture
+        // source"; any other shape (multi-slot, no video) is not judged here.
+        const prev = safe.segments[i - 1]
+        const cur = resolveEdlSegmentSlots(safe, seg)
+        const before = isObject(prev) ? resolveEdlSegmentSlots(safe, prev) : []
+        if (cur.length === 1 && before.length === 1 && cur[0].source !== before[0].source) {
+          warnings.push(`${at}: switch "${sw.id}" moves within ONE picture source, but the previous segment shows "${before[0].source}" and this one "${cur[0].source}"`)
+        }
+      }
+    }
+
+    // 3. The emphasis style.
+    if (isObject(layout.emphasis) && !isKnownSpeakerEmphasisStyle(layout.emphasis.style as string)) {
+      const style = String(layout.emphasis.style)
+      const atoms = parseSpeakerEmphasisStyle(layout.emphasis.style as string)
+      warnings.push(atoms.length > 0 && atoms.every((a) => EMPHASIS_STYLE_SET.has(a))
+        ? `${at}: emphasis style "${style}" — "none" must stand alone and no style may repeat`
+        : `${at}: unknown emphasis style "${style}" (a "+"-joined set of: ${SPEAKER_EMPHASIS_STYLES.join(", ")})`)
+    }
+  })
+
+  return warnings
+}

package/src/transcribe-preflight.ts

@@ -0,0 +1,101 @@
+import {
+  DEFAULT_TRANSCRIBE_NODE_PROVIDER,
+  transcribeLaneSupportsWordTimestamps,
+  transcribeProvidersWithWordTimestamps,
+} from "./model-constants.js"
+
+/**
+ * Pre-run checks for the transcribe → captions chain.
+ *
+ * A transcription lane that cannot return per-word timings (`whisper`) still
+ * RUNS and BILLS — it just hands back phrase segments with `words: []`. Anything
+ * downstream that needs words then fails AFTER the transcription was paid for.
+ * These helpers let every run surface (the editor's DAG, the backend
+ * orchestrator, single-node Run) refuse BEFORE any spend, with one message.
+ * Pure: no I/O, no framework types — callers pass plain nodes/edges.
+ */
+
+/** The refusal for a lane that can't return word timings; `null` when it can.
+ *  An absent provider resolves to the transcribe NODE default. */
+export function transcribeWordTimestampsRefusal(provider: string | null | undefined): string | null {
+  const lane = provider || DEFAULT_TRANSCRIBE_NODE_PROVIDER
+  if (transcribeLaneSupportsWordTimestamps(lane)) return null
+  return `the "${lane}" engine does not return word timings — pick ${transcribeProvidersWithWordTimestamps().join(" or ")}`
+}
+
+export interface PreflightGraphNode {
+  readonly id: string
+  readonly type?: string | null
+  readonly data?: Record<string, unknown> | null
+}
+export interface PreflightGraphEdge {
+  readonly source: string
+  readonly target: string
+  readonly sourceHandle?: string | null
+  readonly targetHandle?: string | null
+}
+
+export interface WordlessTranscriptFeed {
+  readonly transcribeNodeId: string
+  /** The add-captions node that would receive a transcript with no words. */
+  readonly consumerNodeId: string
+  readonly provider: string
+  readonly message: string
+}
+
+// Handle ids (generated map: backend/src/lib/mcp/generated/node-handles.ts).
+const TRANSCRIBE_JSON_OUT = "json"
+const TRANSCRIPT_IN = "transcript"
+const APPLY_EDL_JSON_OUT = "json"
+
+/**
+ * Every transcribe node on a word-INCAPABLE lane whose `json` output reaches an
+ * add-captions `transcript` input — directly, or through apply-edl, which remaps
+ * the transcript and re-emits it on its own `json` handle. add-captions rejects a
+ * transcript with no words, so such a run can only fail, after paying for the
+ * transcription. Skipped nodes are ignored on both ends.
+ *
+ * The engine is read from node data and nothing else can change it: `provider`
+ * is not a mappable field on transcribe, so what this check sees IS what runs.
+ * add-captions' own "transcript has no words" guard stays as defence in depth
+ * for a transcript that arrives from anywhere other than a transcribe node.
+ */
+export function findWordlessTranscriptFeeds(
+  nodes: readonly PreflightGraphNode[],
+  edges: readonly PreflightGraphEdge[],
+): WordlessTranscriptFeed[] {
+  const byId = new Map(nodes.map((n) => [n.id, n]))
+  const isSkipped = (n: PreflightGraphNode | undefined): boolean => !n || n.data?.skipped === true
+  const out: WordlessTranscriptFeed[] = []
+
+  for (const node of nodes) {
+    if (node.type !== "transcribe" || isSkipped(node)) continue
+    const provider = (typeof node.data?.provider === "string" && node.data.provider) || DEFAULT_TRANSCRIBE_NODE_PROVIDER
+    const refusal = transcribeWordTimestampsRefusal(provider)
+    if (!refusal) continue
+
+    // Walk the transcript's path: transcribe.json → [apply-edl.transcript → apply-edl.json]* → add-captions.transcript
+    const seen = new Set<string>()
+    const frontier: Array<{ id: string; outHandle: string }> = [{ id: node.id, outHandle: TRANSCRIBE_JSON_OUT }]
+    while (frontier.length > 0) {
+      const { id, outHandle } = frontier.pop()!
+      for (const e of edges) {
+        if (e.source !== id || (e.sourceHandle ?? null) !== outHandle || e.targetHandle !== TRANSCRIPT_IN) continue
+        const target = byId.get(e.target)
+        if (isSkipped(target)) continue
+        if (target!.type === "add-captions") {
+          out.push({
+            transcribeNodeId: node.id,
+            consumerNodeId: target!.id,
+            provider,
+            message: `Captions need word timings, but ${refusal}.`,
+          })
+        } else if (target!.type === "apply-edl" && !seen.has(target!.id)) {
+          seen.add(target!.id)
+          frontier.push({ id: target!.id, outHandle: APPLY_EDL_JSON_OUT })
+        }
+      }
+    }
+  }
+  return out
+}

package/src/trigger-feeds.ts

@@ -0,0 +1,59 @@
+/**
+ * Every way one node FEEDS another — the ONE definition the server's run
+ * scope (`triggerRunScope`) and the editor's "is this trigger wired?" read
+ * from, so the card can never say "the branch" while the server runs the
+ * whole workflow, or the other way round:
+ *
+ * - a drawn edge whose two ends are both on the graph (a delta that deleted a
+ *   node leaves its edges behind; those feed nothing);
+ * - Group membership: a node inside a Group feeds the group (`parentId`),
+ *   the way the engine orders a group after its members;
+ * - a field mapping: `data.fieldMappings[field].sourceNodeId` feeds the node
+ *   that carries the mapping, even after the edge it was made from is gone.
+ */
+
+export interface FeedNode {
+  readonly id: string
+  readonly parentId?: string | null
+  readonly data?: unknown
+}
+
+export interface FeedEdge {
+  readonly source: string
+  readonly target: string
+}
+
+export interface FeedMaps {
+  /** node id → the ids it feeds */
+  readonly children: ReadonlyMap<string, ReadonlyArray<string>>
+  /** node id → the ids that feed it */
+  readonly parents: ReadonlyMap<string, ReadonlyArray<string>>
+}
+
+export function buildFeedMaps(nodes: ReadonlyArray<FeedNode>, edges: ReadonlyArray<FeedEdge>): FeedMaps {
+  const live = new Set(nodes.map((n) => n.id))
+  const children = new Map<string, string[]>()
+  const parents = new Map<string, string[]>()
+  const feeds = (source: string, target: string) => {
+    if (!live.has(source) || !live.has(target) || source === target) return
+    children.set(source, [...(children.get(source) ?? []), target])
+    parents.set(target, [...(parents.get(target) ?? []), source])
+  }
+  for (const edge of edges) feeds(edge.source, edge.target)
+  for (const n of nodes) {
+    if (typeof n.parentId === "string" && n.parentId) feeds(n.id, n.parentId)
+    const mappings = (n.data as { fieldMappings?: unknown } | null | undefined)?.fieldMappings
+    if (mappings && typeof mappings === "object") {
+      for (const mapping of Object.values(mappings as Record<string, unknown>)) {
+        const sourceNodeId = (mapping as { sourceNodeId?: unknown } | null)?.sourceNodeId
+        if (typeof sourceNodeId === "string" && sourceNodeId) feeds(sourceNodeId, n.id)
+      }
+    }
+  }
+  return { children, parents }
+}
+
+/** Does this node feed anything? A trigger that does not runs the whole workflow. */
+export function nodeFeedsAnything(nodes: ReadonlyArray<FeedNode>, edges: ReadonlyArray<FeedEdge>, nodeId: string): boolean {
+  return (buildFeedMaps(nodes, edges).children.get(nodeId) ?? []).length > 0
+}

package/src/trigger-node-types.ts

@@ -0,0 +1,20 @@
+/**
+ * The node types the server projects onto `workflow_triggers` rows when a
+ * workflow is saved (backend `lib/workflow-trigger-sync.ts`), and that the
+ * editor therefore asks the server to re-project after its own saves. One
+ * vocabulary for both sides: a projected type added here reaches the
+ * editor's "does this save need a sync?" question by construction.
+ */
+export const SCHEDULE_TRIGGER_NODE_TYPE = "schedule-trigger"
+export const WEBHOOK_TRIGGER_NODE_TYPE = "webhook-trigger"
+export const TELEGRAM_TRIGGER_NODE_TYPE = "telegram-trigger"
+
+export const PROJECTED_TRIGGER_NODE_TYPES: ReadonlySet<string> = new Set([
+  SCHEDULE_TRIGGER_NODE_TYPE,
+  WEBHOOK_TRIGGER_NODE_TYPE,
+  TELEGRAM_TRIGGER_NODE_TYPE,
+])
+
+export function isProjectedTriggerNodeType(type: unknown): type is string {
+  return typeof type === "string" && PROJECTED_TRIGGER_NODE_TYPES.has(type)
+}

package/src/video-duration-auto.ts

@@ -0,0 +1,18 @@
+/**
+ * "Auto" video duration — the model decides the clip length. The wire value is
+ * KIE's own (`duration: -1`): on a video EDIT the output takes the source
+ * clip's length, on any other run the model picks within its valid range.
+ * Stored in the ordinary numeric `duration` field (node data, routes, presets,
+ * MCP) so every surface that can carry a duration can carry Auto. Which models
+ * accept it is a catalog capability (`MODEL_CATALOG[id].autoDuration`), read
+ * through `supportsAutoVideoDuration`.
+ *
+ * Import-free on purpose: the catalog and the constants module both need it,
+ * and they already depend on each other.
+ */
+export const VIDEO_DURATION_AUTO = -1
+
+export function isAutoVideoDuration(duration: unknown): boolean {
+  const n = typeof duration === "string" ? parseInt(duration, 10) : duration
+  return n === VIDEO_DURATION_AUTO
+}

package/src/video-duration.ts

@@ -23,3 +23,35 @@ export function extractVideoDurationFromNode(
   }
   return undefined
 }
+
+/** Duration (seconds) of an edit-plan SOURCE node's media, for the reserve
+ *  bucket. Extends {@link extractVideoDurationFromNode} with the AUDIO lane:
+ *  `upload-audio` (and URL-imported audio) write their length to
+ *  `metadata.durationSeconds` ONLY — never `generatedResults[].duration` /
+ *  `data.duration` — so a podcast's audio master would otherwise resolve to
+ *  undefined and reserve the 180-minute ceiling (a ~6× overbill). A
+ *  `reference-audio` node records its extracted file's length in the same field,
+ *  stamped with `metadata.mediaUrl` (see the binding check below).
+ *
+ *  Deliberately a NEW function, not a change to `extractVideoDurationFromNode`,
+ *  so no other node's duration read shifts — this fallback is edit-plan-scoped. */
+export function editPlanSourceDurationSec(
+  data: Record<string, unknown> | undefined,
+): number | undefined {
+  const fromVideo = extractVideoDurationFromNode(data)
+  if (fromVideo !== undefined) return fromVideo
+  const meta = data?.metadata as { durationSeconds?: unknown; mediaUrl?: unknown } | undefined
+  // A length stamped with the media it was measured from is trusted ONLY while
+  // that media is still the node's. This is the read-side invariant that makes a
+  // stale length impossible whoever changed the url — a copilot patch, an MCP
+  // workflow-JSON write, an import, a run-time input override, or code not yet
+  // written: a mismatch reads as "unknown", and every caller then falls to its
+  // safe side (the transcript clock, the reserve-time probe, the ceiling bucket)
+  // instead of under-bucketing a longer file. An UNSTAMPED length (upload-audio,
+  // nodes saved before the stamp existed) is trusted as it always was.
+  if (typeof meta?.mediaUrl === "string" && meta.mediaUrl !== data?.extractedAudioUrl && meta.mediaUrl !== data?.url) {
+    return undefined
+  }
+  const d = meta?.durationSeconds
+  return typeof d === "number" && Number.isFinite(d) && d > 0 ? d : undefined
+}

package/src/video-link.ts

@@ -0,0 +1,167 @@
+/**
+ * The Video URL node (`youtube-video`) and the social-video import path —
+ * structural vocabulary shared by the canvas, the orchestrator and the
+ * download routes. Host names and a node-output rule only; no prompt content.
+ *
+ * ONE list, three readers:
+ *   - the backend's yt-dlp routes (`lib/url-validator.ts` re-exports these),
+ *     where the list IS the SSRF gate — yt-dlp does its own DNS + HTTP, so
+ *     nothing but this exact-suffix match stands between a pasted link and an
+ *     internal address;
+ *   - the editor, which decides from the same list whether a pasted link is
+ *     one it should download (it must never offer a host the server refuses,
+ *     nor sit on one the server accepts);
+ *   - both workflow engines, which read a node's output through
+ *     `resolveVideoLinkOutput`.
+ *
+ * ⚠️ Adding a host here ADMITS it to a server-side fetch. It is a security
+ * decision, not a UI one — only fixed, reputable domains whose DNS an attacker
+ * cannot control.
+ */
+export const SOCIAL_VIDEO_HOSTS = [
+  "youtube.com", "youtu.be",
+  "tiktok.com",
+  "instagram.com",
+  "twitter.com", "x.com",
+  "facebook.com", "fb.watch", "fb.com",
+] as const
+
+/** YouTube-only subset (the metadata probe and the client ladder are YouTube-only). */
+export const YOUTUBE_HOSTS = ["youtube.com", "youtu.be"] as const
+
+/** Instagram-only subset (the download path's proxy failover is Instagram-scoped). */
+export const INSTAGRAM_HOSTS = ["instagram.com"] as const
+
+const TIKTOK_HOSTS = ["tiktok.com"] as const
+const TWITTER_HOSTS = ["twitter.com", "x.com"] as const
+const FACEBOOK_HOSTS = ["facebook.com", "fb.watch", "fb.com"] as const
+
+/**
+ * Exact registrable-domain match against an allowlist: the domain itself or a
+ * true subdomain (`www.youtube.com`, `m.youtu.be`). A host that merely
+ * CONTAINS an allowlisted name (`evilyoutube.com`, `youtube.com.attacker.example`,
+ * or `netflix.com` for `x.com`) does not match.
+ */
+export function hostnameMatchesAllowlist(hostname: string, domains: readonly string[]): boolean {
+  const h = hostname.toLowerCase().replace(/\.$/, "") // strip FQDN trailing dot
+  return domains.some((d) => {
+    const dom = d.toLowerCase()
+    return h === dom || h.endsWith("." + dom)
+  })
+}
+
+/**
+ * True when the RAW link carries a character that URL parsers read differently:
+ * a backslash or an ASCII control character.
+ *
+ * Every check in this file parses the WHATWG way (Node, the browser), where a
+ * backslash in an http(s) URL is a slash — `https://tiktok.com\@10.0.0.1/x` has
+ * host `tiktok.com`. A parser that ends the authority at `/` alone reads the
+ * same string as a user name at host `10.0.0.1`. The download tools are handed
+ * the raw string and do their own parsing, DNS and HTTP, so a link the two
+ * readings can disagree on is refused outright rather than reasoned about. Tabs
+ * and newlines are dropped silently by one parser and kept by another — same
+ * answer. No real video link contains any of these.
+ */
+export function hasUrlParserHazard(url: string): boolean {
+  for (let i = 0; i < url.length; i++) {
+    const code = url.charCodeAt(i)
+    if (code === 0x5c || code <= 0x1f || code === 0x7f) return true
+  }
+  return false
+}
+
+/** True for an http(s) URL whose host is on the allowlist. Never throws. */
+export function isSocialVideoUrl(url: string, domains: readonly string[] = SOCIAL_VIDEO_HOSTS): boolean {
+  if (hasUrlParserHazard(url)) return false
+  try {
+    const parsed = new URL(url)
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false
+    return hostnameMatchesAllowlist(parsed.hostname, domains)
+  } catch {
+    return false
+  }
+}
+
+export type VideoLinkPlatform = "youtube" | "facebook" | "tiktok" | "instagram" | "twitter" | "unknown"
+
+/** Which supported platform a link belongs to — by exact host, never by substring. */
+export function detectVideoLinkPlatform(url: string): VideoLinkPlatform {
+  if (isSocialVideoUrl(url, YOUTUBE_HOSTS)) return "youtube"
+  if (isSocialVideoUrl(url, FACEBOOK_HOSTS)) return "facebook"
+  if (isSocialVideoUrl(url, TIKTOK_HOSTS)) return "tiktok"
+  if (isSocialVideoUrl(url, INSTAGRAM_HOSTS)) return "instagram"
+  if (isSocialVideoUrl(url, TWITTER_HOSTS)) return "twitter"
+  return "unknown"
+}
+
+/**
+ * Node types that can use a Video URL node WITHOUT its downloaded file, because
+ * they never read the video: `suno-cover` and `transcribe` take the node's
+ * separately-fetched audio track (`downloadedAudioUrl`), and `dubbing` hands the
+ * page link to a provider that fetches it itself. A run whose only consumers of
+ * a link are these must not be made to download — or to choose a part of — a
+ * video nobody will look at. Structural vocabulary: it mirrors those three
+ * server-side readers; add a type here only together with its reader.
+ */
+export const VIDEO_LINK_TOLERANT_CONSUMER_TYPES: ReadonlySet<string> = new Set([
+  "suno-cover",
+  "transcribe",
+  "dubbing",
+])
+
+/**
+ * The fields of a Video URL node's data that decide what it emits. Open-ended
+ * on purpose: both engines hand over the node's whole `data` bag, and a closed
+ * shape with only optional members would refuse it as having nothing in common.
+ */
+export interface VideoLinkNodeFields {
+  readonly youtubeUrl?: unknown
+  readonly downloadedVideoUrl?: unknown
+  readonly downloadedFromUrl?: unknown
+  readonly [key: string]: unknown
+}
+
+function trimmed(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined
+  const t = value.trim()
+  return t === "" ? undefined : t
+}
+
+/**
+ * The stored file that belongs to the node's CURRENT link, or undefined.
+ *
+ * `downloadedFromUrl` binds a file to the link it came from. The editor clears
+ * the file whenever the link is edited, but a link can also change where no
+ * editor is looking — an agent or an import rewriting the workflow JSON — and
+ * without the binding the node would go on emitting the PREVIOUS video, which
+ * is worse than emitting none. A node saved before the field existed has no
+ * binding and is trusted as it always was.
+ */
+export function videoLinkDownloadedFile(data: VideoLinkNodeFields): string | undefined {
+  const file = trimmed(data.downloadedVideoUrl)
+  if (!file) return undefined
+  const from = trimmed(data.downloadedFromUrl)
+  if (from && from !== trimmed(data.youtubeUrl)) return undefined
+  return file
+}
+
+/**
+ * What a Video URL node emits on its `video` handle: the downloaded file when
+ * one matches the link, else the link itself. The fallback is load-bearing — a
+ * DIRECT file link (`https://cdn…/clip.mp4`) is a legitimate value of the URL
+ * field and is never downloaded, so it must pass through.
+ */
+export function resolveVideoLinkOutput(data: VideoLinkNodeFields): string | undefined {
+  return videoLinkDownloadedFile(data) ?? trimmed(data.youtubeUrl)
+}
+
+/**
+ * True when the node holds a social link with no file for it yet — the state
+ * in which its output is a web PAGE, which no video consumer can read.
+ */
+export function videoLinkNeedsDownload(data: VideoLinkNodeFields): boolean {
+  const url = trimmed(data.youtubeUrl)
+  if (!url || !isSocialVideoUrl(url)) return false
+  return videoLinkDownloadedFile(data) === undefined
+}