@nodaro/shared 1.4.1

package/src/character-voice.ts

@@ -0,0 +1,151 @@
+import type { TtsProvider } from "./model-constants.js"
+
+/**
+ * How the TTS layer resolves a voice id. Mirrors `CharacterVoice.voiceType` on
+ * the frontend character node: `premade` voices resolve by NAME, `library` /
+ * `custom` voices resolve by ID. Carry it alongside the id or premade-vs-library
+ * resolution misroutes (see backend `direct-tts.ts`).
+ */
+export type VoiceType = "premade" | "library" | "custom"
+
+/**
+ * A character's saved voice as supplied to the voiced-video orchestration on
+ * `POST /v1/generate-video`. A deliberate subset of the frontend `CharacterVoice`:
+ * only the fields the server needs to synthesise speech (no `voiceName` /
+ * `traits` / `previewUrl`, which are display-only and never read server-side).
+ *
+ * `speaker` is the join key: it matches a {@link DialogueLine}.speaker so a
+ * multi-speaker prompt routes each line to its own voice. Omit it for a
+ * single-voice clip (one spec, no dialogue attribution needed).
+ */
+export interface CharacterVoiceSpec {
+  /** ElevenLabs voice id, or the premade voice NAME when `voiceType === "premade"`. */
+  readonly voiceId: string
+  /** How the TTS layer resolves {@link voiceId}. Defaults to `"premade"` downstream. */
+  readonly voiceType?: VoiceType
+  /** Recommended TTS provider for this voice; forwarded as `provider` to TTS. */
+  readonly ttsProvider?: TtsProvider
+  /**
+   * Speaker label this voice belongs to (e.g. "Anna"). Joined to
+   * {@link DialogueLine}.speaker case-insensitively (trimmed). Omit for a
+   * single-voice clip.
+   */
+  readonly speaker?: string
+}
+
+/** One attributed line of dialogue: who speaks (`speaker`) and what they say (`line`). */
+export interface DialogueLine {
+  readonly speaker: string
+  readonly line: string
+}
+
+/**
+ * A dialogue line resolved to a concrete voice, in the exact shape the
+ * ElevenLabs Dialogue v3 primitive (`POST /v1/text-to-dialogue`) consumes:
+ * `{ text, voice }` per line, in order. `voiceType` rides along so the TTS layer
+ * resolves premade-by-name vs library/custom-by-id correctly.
+ */
+export interface ResolvedDialogueVoiceLine {
+  readonly text: string
+  readonly voice: string
+  readonly voiceType?: VoiceType
+}
+
+// Quote characters built from code points so this file stays pure ASCII. The
+// published @nodaro/shared package must survive a re-save in any locale, and a
+// literal curly quote or em-dash here is exactly the CP1255 mojibake hazard that
+// has reached main before. RDQUO/LDQUO = curly double quotes, RAQUO/LAQUO =
+// guillemets, RSQUO = right single quote (apostrophe inside a name like O'Brien).
+const RDQUO = String.fromCharCode(0x201d)
+const LDQUO = String.fromCharCode(0x201c)
+const RAQUO = String.fromCharCode(0x00bb)
+const LAQUO = String.fromCharCode(0x00ab)
+const RSQUO = String.fromCharCode(0x2019)
+
+/**
+ * Matches one attributed, QUOTED line of dialogue. Built with `new RegExp` +
+ * `String.raw` so the regex backslashes stay literal while the non-ASCII quote
+ * characters are injected from the code-point consts above.
+ *
+ * - A leading boundary lookbehind (`^`, newline, sentence punctuation, or a
+ *   CLOSING quote) keeps the speaker capture from bridging a sentence: e.g.
+ *   "...kitchen. Anna: "hi"" yields speaker "Anna", not "kitchen. Anna", and the
+ *   speaker after a closing quote ("hi" Gordon: "yo") is still found.
+ * - Speaker = 1 to 4 short words (names are short; no "." inside a token).
+ * - Body = the first quoted run in straight, curly, or guillemet quotes.
+ *
+ * Requiring quotes is what stops cinematic direction ("Setting: a forest",
+ * "Camera: dolly in") from being read as dialogue.
+ */
+const ATTRIBUTED_DIALOGUE_RE = new RegExp(
+  String.raw`(?<=^|[\n\r.!?;,"${RDQUO}${RAQUO}])\s*([\p{L}][\p{L}\p{N}'${RSQUO}-]*(?:\s+[\p{L}][\p{L}\p{N}'${RSQUO}-]*){0,3})\s*:\s*(?:"([^"]+)"|${LDQUO}([^${RDQUO}]+)${RDQUO}|${LAQUO}([^${RAQUO}]+)${RAQUO})`,
+  "gu",
+)
+
+/**
+ * Extract attributed dialogue (`Speaker: "line"`) from a free-text prompt.
+ *
+ * Deterministic and intentionally conservative (see {@link ATTRIBUTED_DIALOGUE_RE}):
+ * only QUOTED lines attributed to a short speaker label are matched. Callers that
+ * already have structured dialogue (studio prompt chips) should pass it directly
+ * and skip this parser. Order is preserved (it drives the stitched dialogue
+ * track). Returns `[]` when no attributed quoted dialogue is found.
+ */
+export function parseAttributedDialogue(prompt: string): DialogueLine[] {
+  if (!prompt) return []
+  const out: DialogueLine[] = []
+  for (const m of prompt.matchAll(ATTRIBUTED_DIALOGUE_RE)) {
+    const speaker = m[1]?.trim() ?? ""
+    const line = (m[2] ?? m[3] ?? m[4] ?? "").trim()
+    if (speaker && line) out.push({ speaker, line })
+  }
+  return out
+}
+
+/**
+ * Resolve each dialogue line to a concrete voice by joining `line.speaker` to
+ * `voices[].speaker` (case-insensitive, trimmed) - the "Speaker mapping" model.
+ *
+ * Fallback order for an unmatched / unattributed line: the matched speaker's
+ * voice -> `defaultVoiceId` -> the sole voice (when exactly one spec is given) ->
+ * the first voice. A line resolves to nothing only when there are no voices and
+ * no default, in which case it is dropped (the caller decides whether an empty
+ * result means "no dialogue to synthesise"). This mirrors the pipeline's
+ * non-fatal missing-voice behaviour (`allowDefaultVoiceFallback`).
+ */
+export function resolveDialogueVoices(
+  dialogue: readonly DialogueLine[],
+  voices: readonly CharacterVoiceSpec[],
+  defaultVoiceId?: string,
+): ResolvedDialogueVoiceLine[] {
+  const bySpeaker = new Map<string, CharacterVoiceSpec>()
+  for (const v of voices) {
+    const key = v.speaker?.trim().toLowerCase()
+    if (key) bySpeaker.set(key, v)
+  }
+  const soleVoice = voices.length === 1 ? voices[0] : undefined
+  const firstVoice = voices[0]
+
+  const lineFor = (text: string, spec: CharacterVoiceSpec): ResolvedDialogueVoiceLine => ({
+    text,
+    voice: spec.voiceId,
+    ...(spec.voiceType ? { voiceType: spec.voiceType } : {}),
+  })
+
+  const out: ResolvedDialogueVoiceLine[] = []
+  for (const { speaker, line } of dialogue) {
+    const text = line.trim()
+    if (!text) continue
+    const matched = bySpeaker.get(speaker.trim().toLowerCase())
+    if (matched) {
+      out.push(lineFor(text, matched))
+    } else if (defaultVoiceId) {
+      out.push({ text, voice: defaultVoiceId })
+    } else if (soleVoice) {
+      out.push(lineFor(text, soleVoice))
+    } else if (firstVoice) {
+      out.push(lineFor(text, firstVoice))
+    }
+  }
+  return out
+}

package/src/cinematic-avatar-pricing.ts

@@ -0,0 +1,111 @@
+/**
+ * Cinematic Avatar (HeyGen `type:"cinematic_avatar"`) duration-clamping +
+ * credit-identifier helpers. Single source of truth for the NON-monetary side
+ * of cinematic-avatar billing — imported by the frontend node UI and the
+ * backend route/orchestrator.
+ *
+ * The provider-$ rate table and the USD/credit cost FORMULAS derived from it
+ * live in `backend/src/lib/pricing/cinematic-avatar-cost.ts` (core, not ee/ —
+ * the HeyGen provider integration needs them regardless of edition). They
+ * were moved out of this package (published Apache-2.0 on npm — an
+ * irrevocable grant) per the 2026-07-06 public-flip IP audit, S5.
+ *
+ * ─── How this differs from ai-avatar pricing ────────────────────────────────
+ * Cinematic Avatar is a generative clip (Seedance-style pipeline) driven by a
+ * prompt + 1–3 avatar look ids. Crucially, `duration` is a USER PARAMETER
+ * (4–15s, clamped) and is therefore KNOWN at submit time — unlike ai-avatar's
+ * text/audio script whose clip length is only estimated. So the reserve here is
+ * EXACT (no duration-bucket estimation): the credit id encodes the exact
+ * requested duration, and the metered true-up at commit refunds nothing in the
+ * common case (provider returns the requested duration).
+ * ────────────────────────────────────────────────────────────────────────────
+ */
+
+export type CinematicResolution = "720p" | "1080p"
+
+/** Minimum / maximum / default user-selectable duration (seconds). */
+export const CINEMATIC_MIN_DURATION_SEC = 4
+export const CINEMATIC_MAX_DURATION_SEC = 15
+export const CINEMATIC_DEFAULT_DURATION_SEC = 10
+export const CINEMATIC_DEFAULT_RESOLUTION: CinematicResolution = "720p"
+
+const ALLOWED_RESOLUTIONS = new Set<CinematicResolution>(["720p", "1080p"])
+
+/**
+ * Clamp a (possibly invalid) duration to the legal 4–15s range, rounding to a
+ * whole second. Falls back to the default (10s) for non-finite input.
+ */
+export function clampCinematicDuration(durationSec: number | undefined): number {
+  const n = Number(durationSec)
+  if (!Number.isFinite(n)) return CINEMATIC_DEFAULT_DURATION_SEC
+  const rounded = Math.round(n)
+  return Math.min(
+    CINEMATIC_MAX_DURATION_SEC,
+    Math.max(CINEMATIC_MIN_DURATION_SEC, rounded),
+  )
+}
+
+/**
+ * Composite credit identifier for an EXACT-duration reserve.
+ *
+ * Format: `cinematic-avatar:<resolution>:<durationSec>s`
+ * e.g. `cinematic-avatar:720p:10s`.
+ */
+export function cinematicCreditId(
+  resolution: CinematicResolution,
+  durationSec: number,
+): string {
+  return `cinematic-avatar:${resolution}:${durationSec}s`
+}
+
+/**
+ * Resolve the credit identifier from a raw request body BEFORE Zod validation.
+ * Called at creditGuard preHandler time — mirrors resolveAiAvatarCreditId.
+ *
+ * Reads `resolution` (default 720p) and `duration` (default 10, clamped 4–15)
+ * straight off the raw body. Because duration is a user parameter known at
+ * submit time, the reserve id is EXACT — no bucketing.
+ *
+ * ─── autoDuration → reserve at the MAX-duration ceiling ──────────────────────
+ * When `autoDuration` is true, the provider DROPS `duration` and HeyGen picks
+ * the clip length itself, so the actual metered length is UNKNOWN at submit
+ * time and can exceed the requested/default `duration`. The metered true-up at
+ * commit (commit_credits) can ONLY refund a surplus — it never charges more
+ * when the actual exceeds the reserved hold. Reserving under the default-10s
+ * hold therefore silently undercharges any auto clip longer than 10s (a revenue
+ * leak). To preserve the refund-only invariant, reserve under the MAXIMUM
+ * possible hold (`cinematic-avatar:<res>:15s`) so the true-up can only refund.
+ */
+export function resolveCinematicCreditId(
+  body: Record<string, unknown> | undefined,
+): string {
+  const rawResolution = body?.resolution as string | undefined
+  const resolution: CinematicResolution =
+    rawResolution !== undefined && ALLOWED_RESOLUTIONS.has(rawResolution as CinematicResolution)
+      ? (rawResolution as CinematicResolution)
+      : CINEMATIC_DEFAULT_RESOLUTION
+
+  // autoDuration → HeyGen-chosen length, unknown at submit time → reserve at the
+  // 15s ceiling so the metered true-up can only ever refund (never charge more).
+  if (body?.autoDuration === true) {
+    return cinematicCreditId(resolution, CINEMATIC_MAX_DURATION_SEC)
+  }
+
+  const durationSec = clampCinematicDuration(body?.duration as number | undefined)
+  return cinematicCreditId(resolution, durationSec)
+}
+
+/**
+ * All 24 reserve credit IDs — every (resolution × duration) combination.
+ * 2 resolutions × 12 durations (4..15s) = 24.
+ * Seeded in STATIC_CREDIT_COSTS and the model_pricing migration so
+ * getModelCreditBaseCost never hard-fails (503 price_not_configured) for any
+ * legal creditGuard input.
+ */
+export const CINEMATIC_RESERVE_IDS: string[] = [...ALLOWED_RESOLUTIONS].flatMap((resolution) => {
+  const ids: string[] = []
+  for (let d = CINEMATIC_MIN_DURATION_SEC; d <= CINEMATIC_MAX_DURATION_SEC; d++) {
+    ids.push(cinematicCreditId(resolution, d))
+  }
+  return ids
+})

package/src/clone-utils.ts

@@ -0,0 +1,46 @@
+/**
+ * Utilities for detecting and filtering expanded loop clones.
+ * Shared between frontend (store, persistence, execution) and backend (orchestrator).
+ */
+
+import type { GenericNode, GenericEdge } from "./types.js"
+
+/** Matches node IDs like `node_7_iter_0`, `node_7_iter_1`, etc. */
+export const ITER_CLONE_PATTERN = /_iter_\d+$/
+
+/** Returns true if the node is an expanded loop clone (by flag or ID pattern). */
+export function isExpandedClone(node: GenericNode): boolean {
+  return !!(node.data as Record<string, unknown>).__expandedClone || ITER_CLONE_PATTERN.test(node.id)
+}
+
+/**
+ * Filter out expanded clone nodes and edges that reference them.
+ * Unhides original nodes that were hidden during loop expansion.
+ * Optionally filters sub-workflow nodes (prefix `__sub_`).
+ */
+export function filterCloneNodes<N extends GenericNode, E extends GenericEdge>(
+  nodes: N[],
+  edges: E[],
+  options?: { filterSubWorkflow?: boolean },
+): { nodes: N[]; edges: E[] } {
+  const filterSub = options?.filterSubWorkflow ?? false
+
+  const cloneIds = new Set(
+    nodes.filter((n) => isExpandedClone(n)).map((n) => n.id),
+  )
+
+  const filteredNodes = nodes
+    .filter((n) => {
+      if (cloneIds.has(n.id)) return false
+      if (filterSub && n.id.startsWith("__sub_")) return false
+      return true
+    })
+    .map((n) => (n.hidden ? { ...n, hidden: false } as N : n))
+
+  const filteredEdges = edges.filter((e) => {
+    if (filterSub && (e as { id?: string }).id?.startsWith("__sub_")) return false
+    return !cloneIds.has(e.source) && !cloneIds.has(e.target)
+  })
+
+  return { nodes: filteredNodes, edges: filteredEdges }
+}