@nodaro/shared 1.4.2

package/src/json-path.ts

@@ -0,0 +1,52 @@
+/**
+ * Evaluate a dot-notation path against a JSON value.
+ *
+ * Auto-iterates arrays at any depth: if the current value is an array,
+ * the evaluator iterates and applies the remaining path to each element,
+ * flattening results. This lets simple paths like "caption" work on a
+ * top-level array and "pages.markdown" work on a nested array without
+ * any wildcard syntax.
+ *
+ * Returns an array of values. Missing properties are skipped (empty for
+ * that branch). Null/undefined leaf values are included — callers coerce.
+ * Empty path returns `[value]` (a single-element array wrapping the
+ * value) when the value is scalar/object, or the array elements flat
+ * when the root is an array.
+ */
+export function evaluateJsonPath(value: unknown, path: string): unknown[] {
+  const segments = path.length === 0 ? [] : path.split(".")
+  return walk(value, segments, 0)
+}
+
+/**
+ * Coerce an array of unknown values (typically from evaluateJsonPath) to
+ * strings, skipping null/undefined.  Primitives are stringified; objects
+ * are JSON-encoded.
+ */
+export function stringifyPathResults(raw: unknown[]): string[] {
+  const out: string[] = []
+  for (const v of raw) {
+    if (v === null || v === undefined) continue
+    if (typeof v === "string") out.push(v)
+    else if (typeof v === "number" || typeof v === "boolean") out.push(String(v))
+    else out.push(JSON.stringify(v))
+  }
+  return out
+}
+
+function walk(value: unknown, segments: string[], offset: number): unknown[] {
+  if (Array.isArray(value)) {
+    const results: unknown[] = []
+    for (const item of value) {
+      for (const v of walk(item, segments, offset)) results.push(v)
+    }
+    return results
+  }
+  if (offset >= segments.length) return [value]
+  if (value !== null && typeof value === "object") {
+    const head = segments[offset]
+    if (!Object.hasOwn(value as object, head)) return []
+    return walk((value as Record<string, unknown>)[head], segments, offset + 1)
+  }
+  return []
+}

package/src/lip-sync-pricing.ts

@@ -0,0 +1,90 @@
+/**
+ * Lip-sync per-second pricing helpers.
+ *
+ * KIE.ai Kling AI Avatar 2.0 (May 2026) raised the max input audio from 15s
+ * to 5 minutes and bills per-second. We bucket the requested audio duration
+ * into discrete tiers and use composite credit identifiers
+ * (e.g. `kling-avatar:60s`) so credit reservation scales with input length.
+ *
+ * InfiniTalk still enforces a 15s upstream cap.
+ */
+
+export const LIP_SYNC_DURATION_BUCKETS = [15, 30, 60, 120, 300] as const
+
+export type LipSyncDurationBucket = typeof LIP_SYNC_DURATION_BUCKETS[number]
+
+/** Round a measured audio duration up to the next supported bucket. */
+export function pickLipSyncBucket(seconds: number): LipSyncDurationBucket {
+  if (!Number.isFinite(seconds) || seconds <= 0) return LIP_SYNC_DURATION_BUCKETS[0]
+  for (const b of LIP_SYNC_DURATION_BUCKETS) {
+    if (seconds <= b) return b
+  }
+  return 300
+}
+
+/**
+ * Upper audio-duration limit per lip-sync provider, in seconds.
+ * Anything longer must be trimmed (server-side) before sending upstream.
+ */
+export const LIP_SYNC_MAX_AUDIO_SECONDS: Record<string, number> = {
+  "kling-avatar": 300,
+  "kling-avatar-pro": 300,
+  "infinitalk": 15,
+  // OmniHuman 1.5 — KIE hard limit is < 60s; audio is auto-trimmed to this cap.
+  "omnihuman-1-5": 60,
+  // HeyGen Lipsync Precision + Sync Lipsync 2 Pro — billed per output second.
+  // 5-min ceiling for credit bucketing (mirrors kling-avatar). MUST be set:
+  // the default fallback below is 15s, which would clamp every request to the
+  // 15s bucket and silently under-charge long clips.
+  "heygen-lipsync-precision": 300,
+  "lipsync-2-pro": 300,
+  // Sync Lipsync v3 (fal.ai) — per-second dubbing, 5-min ceiling for bucketing.
+  "sync-lipsync-v3": 300,
+  // Volcengine (KIE) — video-to-video dubbing, per-second, 5-min ceiling.
+  "volcengine-lipsync": 300,
+}
+
+export function getLipSyncMaxAudioSeconds(provider: string): number {
+  return LIP_SYNC_MAX_AUDIO_SECONDS[provider] ?? 15
+}
+
+/** Providers whose credit cost varies with audio duration. */
+const PER_SECOND_LIP_SYNC_PROVIDERS = new Set([
+  "kling-avatar",
+  "kling-avatar-pro",
+  // OmniHuman 1.5 — /sec, bucketed by audio length (60s cap).
+  "omnihuman-1-5",
+  "heygen-lipsync-precision",
+  "lipsync-2-pro",
+  // Sync Lipsync v3 (fal.ai) — billed per output second (/min).
+  "sync-lipsync-v3",
+  // Volcengine (KIE) — video-to-video dubbing, billed per output second.
+  "volcengine-lipsync",
+])
+
+export function isPerSecondLipSyncProvider(provider: string): boolean {
+  return PER_SECOND_LIP_SYNC_PROVIDERS.has(provider)
+}
+
+/**
+ * Build the credit identifier for a lip-sync request.
+ *
+ * For kling-avatar / kling-avatar-pro, returns `<provider>:<bucket>s`.
+ * For other providers, returns the bare provider name (caller appends
+ * any extra dimensions like resolution).
+ *
+ * If `audioDurationSec` is missing, defaults to the provider's max cap so
+ * credit reservation covers the worst case and any overage is refunded
+ * after the worker reconciles the actual KIE cost.
+ */
+export function buildLipSyncCreditId(
+  provider: string,
+  audioDurationSec: number | undefined,
+): string {
+  if (!isPerSecondLipSyncProvider(provider)) return provider
+  const cap = getLipSyncMaxAudioSeconds(provider)
+  const requested = audioDurationSec === undefined || audioDurationSec <= 0
+    ? cap
+    : Math.min(audioDurationSec, cap)
+  return `${provider}:${pickLipSyncBucket(requested)}s`
+}

package/src/list-merge.ts

@@ -0,0 +1,40 @@
+import { tryParseJson } from "./filter-condition.js"
+
+/**
+ * Element-wise merge across upstream lists with modulo-wrap.
+ *
+ * Used by the `merge-lists` node's "zip" mode. Each output position i takes
+ * `lists[j][i % lists[j].length]` from every input; JSON objects are spread
+ * into a single object (later sources override earlier ones on key conflicts),
+ * non-object items are stringified and concatenated.
+ *
+ * Length semantics mirror the DAG's existing fan-out behavior: the result
+ * length equals `max(len)` across non-empty inputs. Shorter inputs cycle.
+ * This means a single-item upstream (e.g. a JSON-process node emitting one
+ * object, or a list with one row) is automatically injected into every
+ * element of a longer list.
+ */
+export function zipMergeLists(lists: ReadonlyArray<ReadonlyArray<string>>): string[] {
+  const nonEmpty = lists.filter((l) => l.length > 0)
+  if (nonEmpty.length === 0) return []
+  if (nonEmpty.length === 1) return [...nonEmpty[0]]
+
+  const maxLen = Math.max(...nonEmpty.map((l) => l.length))
+  const out: string[] = []
+  for (let i = 0; i < maxLen; i++) {
+    const merged: Record<string, unknown> = {}
+    const rawItems: string[] = []
+    let hasObject = false
+    for (const list of nonEmpty) {
+      const item = list[i % list.length]
+      rawItems.push(item)
+      const parsed = tryParseJson(item)
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        hasObject = true
+        Object.assign(merged, parsed as Record<string, unknown>)
+      }
+    }
+    out.push(hasObject ? JSON.stringify(merged) : rawItems.join(""))
+  }
+  return out
+}

package/src/list-sort.ts

@@ -0,0 +1,122 @@
+/** Pure sort helper shared by the frontend DAG executor and the backend
+ *  orchestrator. Contract: reorder stringified list items (as produced by
+ *  `collectUpstreamListItems` peers) by an optional dot-path field, with
+ *  Auto/Text/Number/Date comparison and asc/desc direction. Items whose
+ *  key is missing, empty, or uncoerceable under the chosen type are always
+ *  appended last — regardless of direction. */
+
+import { evaluateJsonPath } from "./json-path.js"
+import { tryParseJson } from "./filter-condition.js"
+
+export type SortType = "auto" | "text" | "number" | "date"
+export type SortDirection = "asc" | "desc"
+
+export interface SortListOptions {
+  field: string
+  sortType: SortType
+  direction: SortDirection
+}
+
+// Natural numeric-aware, case-insensitive locale compare. Declared once so
+// both the Text branch and the Auto fallback reuse the same Collator.
+const textCollator = new Intl.Collator(undefined, {
+  sensitivity: "base",
+  numeric: true,
+})
+
+interface KeyedItem {
+  item: string
+  key: number | string
+  keyKind: "number" | "text" | "invalid"
+}
+
+function extractRawKey(item: string, field: string): unknown {
+  if (field === "") return item
+  const parsed = tryParseJson(item)
+  const matches = evaluateJsonPath(parsed, field)
+  return matches.length > 0 ? matches[0] : undefined
+}
+
+function isMissing(v: unknown): boolean {
+  if (v === undefined || v === null) return true
+  if (typeof v === "string" && v.trim() === "") return true
+  return false
+}
+
+function toNumberKey(v: unknown): number | undefined {
+  if (typeof v === "number") return Number.isFinite(v) ? v : undefined
+  if (typeof v === "boolean") return v ? 1 : 0
+  if (typeof v === "string") {
+    const trimmed = v.trim()
+    if (trimmed === "") return undefined
+    const n = Number(trimmed)
+    return Number.isFinite(n) ? n : undefined
+  }
+  return undefined
+}
+
+function toDateKey(v: unknown): number | undefined {
+  if (v instanceof Date) {
+    const t = v.getTime()
+    return Number.isFinite(t) ? t : undefined
+  }
+  if (typeof v === "number") return Number.isFinite(v) ? v : undefined
+  if (typeof v === "string") {
+    const t = Date.parse(v)
+    return Number.isFinite(t) ? t : undefined
+  }
+  return undefined
+}
+
+function coerceKey(raw: unknown, sortType: SortType): Pick<KeyedItem, "key" | "keyKind"> {
+  if (isMissing(raw)) return { key: "", keyKind: "invalid" }
+
+  if (sortType === "number") {
+    const n = toNumberKey(raw)
+    return n === undefined
+      ? { key: "", keyKind: "invalid" }
+      : { key: n, keyKind: "number" }
+  }
+
+  if (sortType === "date") {
+    const d = toDateKey(raw)
+    return d === undefined
+      ? { key: "", keyKind: "invalid" }
+      : { key: d, keyKind: "number" }
+  }
+
+  if (sortType === "text") {
+    return { key: typeof raw === "string" ? raw : JSON.stringify(raw), keyKind: "text" }
+  }
+
+  // auto: try number → date → text.
+  const asNum = toNumberKey(raw)
+  if (asNum !== undefined) return { key: asNum, keyKind: "number" }
+  const asDate = toDateKey(raw)
+  if (asDate !== undefined) return { key: asDate, keyKind: "number" }
+  return { key: typeof raw === "string" ? raw : JSON.stringify(raw), keyKind: "text" }
+}
+
+export function sortListItems(items: readonly string[], opts: SortListOptions): string[] {
+  const { field, sortType, direction } = opts
+  const keyed: KeyedItem[] = items.map((item) => {
+    const raw = extractRawKey(item, field)
+    const { key, keyKind } = coerceKey(raw, sortType)
+    return { item, key, keyKind }
+  })
+
+  const sortable = keyed.filter((k) => k.keyKind !== "invalid")
+  const invalid = keyed.filter((k) => k.keyKind === "invalid")
+
+  const factor = direction === "desc" ? -1 : 1
+  // Array.prototype.sort is guaranteed stable since ES2019 — equal keys
+  // preserve their relative input order.
+  sortable.sort((a, b) => {
+    if (a.keyKind === "number" && b.keyKind === "number") {
+      return ((a.key as number) - (b.key as number)) * factor
+    }
+    return textCollator.compare(String(a.key), String(b.key)) * factor
+  })
+
+  return [...sortable.map((k) => k.item), ...invalid.map((k) => k.item)]
+}

package/src/list-source-resolver.ts

@@ -0,0 +1,50 @@
+/**
+ * Follow a list node's `in` edge chain to its effective upstream source.
+ *
+ * When a `list` node has no manual rows but an incoming connection, the UI
+ * renders its upstream's items (see list-node.tsx's `connectedItems ??
+ * staticItems`). Without this helper, downstream readers would see an empty
+ * list because `extractSourceNodeOutput` for `list` only reads `data.rows`.
+ *
+ * Shared between the frontend DAG executor (`node-input-resolver.ts`) and
+ * the backend orchestrator (`inline-executor.ts`) so both paths resolve
+ * list-connected-mode identically.
+ */
+
+type EdgeShape = {
+  source: string
+  target: string
+  sourceHandle?: string | null
+  targetHandle?: string | null
+}
+
+type NodeShape = {
+  id: string
+  type?: string
+  data: Record<string, unknown>
+}
+
+function hasAnyRow(rows: string[][]): boolean {
+  return rows.some((r) => r.some((v) => v?.trim()))
+}
+
+export function resolveSourceThroughConnectedList<
+  E extends EdgeShape,
+  N extends NodeShape,
+>(edge: E, nodes: ReadonlyArray<N>, edges: ReadonlyArray<E>): E {
+  const visited = new Set<string>()
+  let current = edge
+  while (true) {
+    const src = nodes.find((n) => n.id === current.source)
+    if (!src || src.type !== "list") return current
+    if (visited.has(src.id)) return current
+    visited.add(src.id)
+    const rows = (src.data.rows as string[][] | undefined) ?? []
+    if (hasAnyRow(rows)) return current
+    const inEdge = edges.find(
+      (e) => e.target === src.id && e.targetHandle === "in",
+    )
+    if (!inEdge) return current
+    current = inEdge
+  }
+}

package/src/llm-models.ts

@@ -0,0 +1,245 @@
+/**
+ * LLM Model Registry — shared between frontend and backend.
+ *
+ * Single source of truth for available chat/LLM models routed through KIE.ai,
+ * with direct Anthropic SDK fallback for Claude models. This is the
+ * NON-monetary side of the registry (model ids, capabilities, tiers,
+ * feature defaults). The provider-$ per-token rate table and the
+ * `calculateLlmCost` formula derived from it live in
+ * `backend/src/lib/pricing/llm-cost.ts` (core, not ee/ — internal LLM cost
+ * logging 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: "Keep the model-id enum; strip prices
+ * + measurement notes."
+ */
+
+export type LlmTier = "economy" | "standard" | "premium"
+export type KieApiFormat = "chat-completions" | "messages" | "responses"
+
+export interface LlmModelDef {
+  id: string
+  displayName: string
+  desc: string
+  tier: LlmTier
+  kieFormat: KieApiFormat
+  /** For chat-completions: the slug prefix (e.g. "gemini-3-flash").
+   *  For messages: the model id sent in the body (e.g. "claude-haiku-4-5-v1messages").
+   *  For responses: the model id sent in the body (e.g. "gpt-5-4"). */
+  kieSlugOrModel: string
+  vendor: "anthropic" | "google" | "openai"
+  supportsImages: boolean
+  maxOutputTokens: number
+  /**
+   * How this model can be forced into schema-valid structured output.
+   * - "anthropic-tool"       → direct Anthropic SDK forced tool_choice (guaranteed).
+   * - "kie-response-format"  → KIE chat-completions `response_format: json_schema`
+   *                            (verified enforced for Gemini via KIE).
+   * - undefined              → no native structured mode (GPT-via-KIE doesn't honor
+   *                            response_format); callers fall back to parse + retry.
+   * Capability-driven so `llmCompleteStructured` never hardcodes provider ids.
+   */
+  structuredOutputMode?: "anthropic-tool" | "kie-response-format"
+  /** If set, fallback to direct Anthropic SDK with this model ID when KIE.ai fails */
+  directFallbackModel?: string
+}
+
+export const LLM_MODELS: readonly LlmModelDef[] = [
+  {
+    id: "gemini-3-flash",
+    displayName: "Gemini 3 Flash",
+    desc: "Fast and cheap, good for simple tasks",
+    tier: "economy",
+    kieFormat: "chat-completions",
+    kieSlugOrModel: "gemini-3-flash",
+    vendor: "google",
+    structuredOutputMode: "kie-response-format",
+    supportsImages: true,
+    maxOutputTokens: 8192,
+  },
+  {
+    id: "claude-haiku-4.5",
+    displayName: "Claude Haiku 4.5",
+    desc: "Fast economy, good reasoning",
+    tier: "economy",
+    kieFormat: "messages",
+    kieSlugOrModel: "claude-haiku-4-5",
+    vendor: "anthropic",
+    structuredOutputMode: "anthropic-tool",
+    supportsImages: true,
+    maxOutputTokens: 8192,
+    directFallbackModel: "claude-haiku-4-5-20251001",
+  },
+  {
+    id: "claude-sonnet-4.6",
+    displayName: "Claude Sonnet 4.6",
+    desc: "Balanced quality and speed",
+    tier: "standard",
+    kieFormat: "messages",
+    kieSlugOrModel: "claude-sonnet-4-6",
+    vendor: "anthropic",
+    structuredOutputMode: "anthropic-tool",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    directFallbackModel: "claude-sonnet-4-6",
+  },
+  {
+    id: "gpt-5.2",
+    displayName: "GPT-5.2",
+    desc: "Strong general purpose",
+    tier: "standard",
+    kieFormat: "chat-completions",
+    kieSlugOrModel: "gpt-5-2",
+    vendor: "openai",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+  },
+  {
+    id: "gemini-3.1-pro",
+    displayName: "Gemini 3.1 Pro",
+    desc: "Advanced reasoning, large context",
+    tier: "premium",
+    kieFormat: "chat-completions",
+    kieSlugOrModel: "gemini-3.1-pro",
+    vendor: "google",
+    structuredOutputMode: "kie-response-format",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+  },
+  {
+    id: "claude-opus-4.7",
+    displayName: "Claude Opus 4.7",
+    desc: "Highest quality, complex tasks",
+    tier: "premium",
+    kieFormat: "messages",
+    kieSlugOrModel: "claude-opus-4-7",
+    vendor: "anthropic",
+    structuredOutputMode: "anthropic-tool",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    directFallbackModel: "claude-opus-4-7",
+  },
+  {
+    id: "gpt-5.4",
+    displayName: "GPT-5.4",
+    desc: "Latest GPT, premium quality",
+    tier: "premium",
+    kieFormat: "responses",
+    kieSlugOrModel: "gpt-5-4",
+    vendor: "openai",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+  },
+] as const
+
+export const LLM_MODEL_IDS = LLM_MODELS.map((m) => m.id)
+
+/** Vision models that can return GUARANTEED structured output — the
+ *  describe-to-picker analyzer forces a schema over an image, so its model
+ *  pickers AND the backend route gate offer exactly these: Anthropic (forced
+ *  tool) + Gemini (KIE `response_format`). GPT-via-KIE has no native structured
+ *  mode (parse+retry only), so it's excluded. Single source of truth so the
+ *  picker, the config panel, and the route gate can't drift. */
+export const STRUCTURED_VISION_MODELS = LLM_MODELS.filter(
+  (m) => m.supportsImages && m.structuredOutputMode != null,
+)
+
+export type LlmFeature =
+  | "ai-writer"
+  | "llm-chat"
+  | "prompt-helper"
+  | "scene-graph-ai"
+  | "after-effects"
+  | "motion-graphics"
+  | "motion-graphics-lottie"
+  | "lottie-overlay"
+  | "3d-title"
+  | "image-to-text"
+  | "describe-to-picker"
+  | "qa-check"
+  | "generate-script"
+  | "translate"
+  | "image-critic"
+
+/** Engine-dependent LlmFeature for the motion-graphics node (design §8: every credit-id site must branch on engine). */
+export function motionGraphicsFeature(engine?: string): LlmFeature {
+  return engine === "lottie" ? "motion-graphics-lottie" : "motion-graphics"
+}
+
+/** Feature → default model when user hasn't selected one */
+export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
+  "ai-writer": "claude-sonnet-4.6",
+  "llm-chat": "gemini-3-flash",
+  "prompt-helper": "gemini-3-flash",
+  "scene-graph-ai": "claude-sonnet-4.6",
+  "after-effects": "claude-sonnet-4.6",
+  "motion-graphics": "claude-sonnet-4.6",
+  "motion-graphics-lottie": "claude-sonnet-4.6",
+  "lottie-overlay": "claude-sonnet-4.6",
+  "3d-title": "claude-sonnet-4.6",
+  "image-to-text": "claude-sonnet-4.6",
+  "describe-to-picker": "claude-opus-4.7",
+  "qa-check": "claude-sonnet-4.6",
+  "generate-script": "gemini-3-flash",
+  "translate": "gemini-3-flash",
+  "image-critic": "claude-sonnet-4.6",
+}
+
+/**
+ * Per-model multimodal input capabilities. Drives both frontend UI gating
+ * and backend route-level filtering for the LLM Chat node references.
+ *
+ * As of 2026-05: Claude Messages API supports text + image only (no audio,
+ * no video). Gemini 2/3 family supports image + video + audio natively.
+ * GPT-5.x via KIE chat-completions / responses supports image only — audio
+ * input requires a separate audio-capable model we don't route to today.
+ */
+export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean; audio: boolean }> = {
+  "gemini-3-flash":    { image: true,  video: true,  audio: true  },
+  "gemini-3.1-pro":    { image: true,  video: true,  audio: true  },
+  "claude-haiku-4.5":  { image: true,  video: false, audio: false },
+  "claude-sonnet-4.6": { image: true,  video: false, audio: false },
+  "claude-opus-4.7":   { image: true,  video: false, audio: false },
+  "gpt-5.2":           { image: true,  video: false, audio: false },
+  "gpt-5.4":           { image: true,  video: false, audio: false },
+}
+
+/** Capability lookup with safe default — unknown models get image-only. */
+export function getLlmModalityCaps(modelId: string | undefined): { image: boolean; video: boolean; audio: boolean } {
+  if (!modelId) return { image: true, video: false, audio: false }
+  return LLM_MODALITY_CAPS[modelId] ?? { image: true, video: false, audio: false }
+}
+
+export function getLlmModel(id: string): LlmModelDef | undefined {
+  return LLM_MODELS.find((m) => m.id === id)
+}
+
+export function getLlmTier(id: string): LlmTier {
+  return getLlmModel(id)?.tier ?? "standard"
+}
+
+/**
+ * Build a composite credit identifier for an LLM feature.
+ * - economy tier → "ai-writer:economy"
+ * - standard tier → "ai-writer" (no suffix — backward compatible)
+ * - premium tier → "ai-writer:premium"
+ */
+export function buildLlmCreditIdentifier(feature: string, modelId?: string): string {
+  if (!modelId) return feature
+  const tier = getLlmTier(modelId)
+  if (tier === "standard") return feature
+  return `${feature}:${tier}`
+}
+
+/**
+ * Resolve llmModel from raw body for creditGuard preHandler (before Zod parsing).
+ * Returns the credit identifier for the given feature + optional model.
+ */
+export function resolveLlmCreditId(feature: string, body: unknown): string {
+  const llmModel = (body as Record<string, unknown>)?.llmModel as string | undefined
+  return buildLlmCreditIdentifier(feature, llmModel)
+}
+
+/** Models capable of video-analysis: capability-derived, never hand-listed (route-enum-sync convention). */
+export const VIDEO_ANALYSIS_LLM_MODELS: string[] = LLM_MODELS
+  .filter((m) => getLlmModalityCaps(m.id).video && getLlmModalityCaps(m.id).audio)
+  .map((m) => m.id)