@nodaro/shared 1.4.2

package/src/featured-entities.ts

@@ -0,0 +1,136 @@
+/**
+ * Featured entity starter catalog (north-star §6 ③ — the "Featured" tab of each
+ * entity Library).
+ *
+ * These are app-provided starter presets: a curated visual description per
+ * archetype that the user can drop into an entity's Generate field as a
+ * head-start, instead of writing one from scratch. They are intentionally
+ * ASSETLESS — they seed generation (the user still generates the image with
+ * their chosen model + style), so no hosted sample images are required. The
+ * "Mine" tab (reuse an already-saved image) and "+ New" (Upload / write your
+ * own) cover the other two on-ramps.
+ */
+export interface FeaturedEntity {
+  /** Stable id (unique within its type). */
+  id: string
+  /** Short name shown on the chip. */
+  label: string
+  /** Curated visual description dropped into the Generate field. */
+  description: string
+}
+
+export const FEATURED_ENTITIES: Record<string, readonly FeaturedEntity[]> = {
+  character: [
+    {
+      id: "detective",
+      label: "Grizzled Detective",
+      description:
+        "A weathered private detective in his 50s, stubble, rumpled trench coat, tired but sharp eyes, film-noir presence",
+    },
+    {
+      id: "barista",
+      label: "Cheerful Barista",
+      description:
+        "A cheerful young barista with curly hair, apron over a casual shirt, warm welcoming smile, energetic and approachable",
+    },
+    {
+      id: "elder",
+      label: "Wise Elder",
+      description:
+        "A wise elderly mentor with long grey hair and beard, flowing robes, calm knowing expression, gentle authority",
+    },
+    {
+      id: "adventurer",
+      label: "Young Adventurer",
+      description:
+        "A young adventurer in practical travel gear with a worn backpack, determined expression, sun-weathered skin",
+    },
+    {
+      id: "scientist",
+      label: "Focused Scientist",
+      description:
+        "A focused scientist in a white lab coat, glasses, hair tied back, intelligent and intense demeanor",
+    },
+    {
+      id: "child",
+      label: "Curious Kid",
+      description:
+        "A curious 8-year-old child with bright eyes and colorful casual clothes, playful and full of wonder",
+    },
+  ],
+  location: [
+    {
+      id: "alley",
+      label: "Cyberpunk Alley",
+      description:
+        "A neon-lit cyberpunk alley at night, wet pavement reflecting signs, drifting steam, dense layered urban detail",
+    },
+    {
+      id: "cafe",
+      label: "Cozy Café",
+      description:
+        "A cozy coffee shop interior, warm wood surfaces, soft pendant lighting, hanging plants, a few relaxed patrons",
+    },
+    {
+      id: "forest",
+      label: "Misty Forest",
+      description:
+        "A misty ancient forest at dawn, tall trees, shafts of light through fog, ferns underfoot, ethereal stillness",
+    },
+    {
+      id: "office",
+      label: "Modern Office",
+      description:
+        "A sleek modern office with glass walls, a city skyline view, minimal furniture, bright natural daylight",
+    },
+    {
+      id: "beach",
+      label: "Golden Beach",
+      description:
+        "A tranquil tropical beach at golden hour, soft rolling waves, leaning palm trees, warm low sun",
+    },
+    {
+      id: "bridge",
+      label: "Spaceship Bridge",
+      description:
+        "A futuristic spaceship bridge, glowing control panels, a vast viewport onto a star field, cool blue light",
+    },
+  ],
+  object: [
+    {
+      id: "watch",
+      label: "Vintage Pocket Watch",
+      description:
+        "An ornate vintage gold pocket watch, intricate engraving, slightly worn, on a fine chain",
+    },
+    {
+      id: "sword",
+      label: "Enchanted Sword",
+      description:
+        "A glowing enchanted sword, faint runes etched along the blade, ornate hilt wrapped in leather",
+    },
+    {
+      id: "robot",
+      label: "Retro Robot",
+      description:
+        "A friendly retro-futuristic robot companion, rounded brushed-metal chassis, a single expressive lens eye",
+    },
+    {
+      id: "book",
+      label: "Ancient Spellbook",
+      description:
+        "An ancient leather-bound spellbook, gilded page edges, embossed cover, a faint mysterious glow",
+    },
+    {
+      id: "car",
+      label: "Classic Convertible",
+      description:
+        "A sleek classic convertible sports car, polished chrome trim, vivid glossy paint, whitewall tires",
+    },
+  ],
+}
+
+/** Featured presets for an entity type ("character" | "location" | "object"). */
+export function getFeaturedEntities(type: string): readonly FeaturedEntity[] {
+  return FEATURED_ENTITIES[type] ?? []
+}

package/src/film-pricing.ts

@@ -0,0 +1,117 @@
+/**
+ * Film cost ESTIMATION for the studio preview.
+ *
+ * This is display guidance only — it produces an approximate "this film will
+ * cost ≈ N credits" number so the user can see cost before committing to a
+ * length + model. The ACTUAL charge is still computed at generation time from
+ * `STATIC_CREDIT_COSTS` / the `model_pricing` table per job; this module never
+ * bills.
+ *
+ * Numbers are grounded in the KIE-calibrated per-clip credit costs in
+ * `backend/src/ee/billing/credits.ts` (each entry there is annotated with its
+ * KIE-credit + USD source). A backend test cross-checks `VIDEO_CLIP_CREDITS`
+ * against that source so the estimate can't silently drift from reality.
+ *
+ * Cost structure of a Story→Video film:
+ *   total = BASE  (duration-independent planning + assembly)
+ *         + perShot × shotCount   (the variable, model-driven bulk)
+ * where a shot = one keyframe image + one video clip + one video-critic pass,
+ * and shotCount ≈ ceil(duration / clipSeconds) for the chosen model.
+ */
+
+/**
+ * Duration-independent overhead, in credits:
+ *   script/showrunner LLM chain ~30 · music timeline 4 · editor LLM 3 ·
+ *   final merge 3 · storyboard-cohesion critic 5  ≈ 45.
+ * Mirrors the fixed line items in `estimateUpfrontCredits`
+ * (backend/src/ee/pipelines/credits.ts).
+ */
+export const FILM_BASE_CREDITS = 45
+
+/** Per-shot keyframe image (nano-banana class) — see STATIC_CREDIT_COSTS. */
+export const KEYFRAME_CREDITS_PER_SHOT = 2
+/** Per-shot Video Critic pass (first_last frame mode) — see credits.ts. */
+export const VIDEO_CRITIC_CREDITS_PER_SHOT = 2
+
+export interface VideoClipCost {
+  /** Representative per-clip credit cost at the studio's default config
+   *  (720p; for the Seedance 2 family this is the ref-image variant the
+   *  studio uses for identity). Sourced from STATIC_CREDIT_COSTS. */
+  readonly credits: number
+  /** Representative clip length in seconds for shot-count estimation. */
+  readonly clipSeconds: number
+}
+
+/**
+ * Representative per-clip credit cost for each user-pinnable video model.
+ * Values are the KIE-calibrated credits from STATIC_CREDIT_COSTS at the
+ * studio's typical settings (720p; Seedance 2 = 8s 720p +ref). Keep in sync
+ * with that table — the backend cross-check test guards drift.
+ */
+export const VIDEO_CLIP_CREDITS: Record<string, VideoClipCost> = {
+  "kling-turbo": { credits: 11, clipSeconds: 5 }, // kling-turbo:5s
+  "kling": { credits: 14, clipSeconds: 5 }, // kling:5s
+  "kling-3.0": { credits: 31, clipSeconds: 5 },
+  "seedance": { credits: 7, clipSeconds: 8 }, // seedance:8s
+  "seedance-2": { credits: 50, clipSeconds: 8 }, // seedance-2:8s:720p-ref
+  "seedance-2-fast": { credits: 40, clipSeconds: 8 }, // seedance-2-fast:8s:720p-ref
+  "seedance-2-mini": { credits: 25, clipSeconds: 8 }, // seedance-2-mini:8s:720p-ref
+  "veo3": { credits: 79, clipSeconds: 8 }, // flat per generation (VEO 3.1 Quality)
+  "veo3.1": { credits: 19, clipSeconds: 6 }, // veo3.1 @ 720p
+  "veo3_lite": { credits: 10, clipSeconds: 6 }, // veo3_lite @ 720p
+  "minimax": { credits: 18, clipSeconds: 6 }, // fixed ~6s
+  "hailuo-standard": { credits: 8, clipSeconds: 6 }, // hailuo-standard:6s
+  "wan-turbo": { credits: 13, clipSeconds: 5 }, // 5s 480p
+  "bytedance-lite": { credits: 6, clipSeconds: 5 },
+  "bytedance-pro": { credits: 18, clipSeconds: 5 },
+}
+
+/**
+ * Fallback when no model is pinned (Auto — the Scene Director picks per scene)
+ * or the model isn't in the table. kling-turbo is the cheap, common default
+ * the engine gravitates to, so it's a reasonable "≈" anchor.
+ */
+export const DEFAULT_VIDEO_CLIP_COST: VideoClipCost = VIDEO_CLIP_CREDITS["kling-turbo"]!
+
+export interface FilmCreditEstimate {
+  /** Total estimated credits for the whole film. */
+  readonly totalCredits: number
+  /** Fixed base portion (planning + assembly). */
+  readonly baseCredits: number
+  /** Variable portion (shots × per-shot). */
+  readonly variableCredits: number
+  /** Estimated number of shots (clips) generated. */
+  readonly shotCount: number
+  /** Average credits per second of film (totalCredits / duration). */
+  readonly creditsPerSecond: number
+  /** Whether a known model drove the estimate (false = Auto/fallback). */
+  readonly modelKnown: boolean
+}
+
+/**
+ * Estimate the credit cost of a Story→Video film of `durationSeconds` rendered
+ * with `videoModel`. Approximate, for the studio's cost preview only.
+ */
+export function estimateFilmCredits(
+  durationSeconds: number,
+  videoModel?: string,
+): FilmCreditEstimate {
+  const seconds = Math.max(1, Math.round(durationSeconds))
+  const known = !!videoModel && videoModel in VIDEO_CLIP_CREDITS
+  const clip = known ? VIDEO_CLIP_CREDITS[videoModel!]! : DEFAULT_VIDEO_CLIP_COST
+
+  const shotCount = Math.max(1, Math.ceil(seconds / clip.clipSeconds))
+  const perShot =
+    clip.credits + KEYFRAME_CREDITS_PER_SHOT + VIDEO_CRITIC_CREDITS_PER_SHOT
+  const variableCredits = shotCount * perShot
+  const totalCredits = FILM_BASE_CREDITS + variableCredits
+
+  return {
+    totalCredits,
+    baseCredits: FILM_BASE_CREDITS,
+    variableCredits,
+    shotCount,
+    creditsPerSecond: Math.round((totalCredits / seconds) * 10) / 10,
+    modelKnown: known,
+  }
+}

package/src/filter-condition.ts

@@ -0,0 +1,250 @@
+/** Pure condition evaluator shared by filter-list and router (conditional mode). */
+
+import { evaluateJsonPath } from "./json-path.js"
+import { resolveNodeRefs } from "./node-refs.js"
+
+export type FilterListOperator =
+  | ">" | "<" | ">=" | "<="
+  | "=" | "!="
+  | "contains" | "not_contains"
+  | "starts_with" | "ends_with" | "regex"
+  | "exists" | "not_exists"
+
+export interface FilterListCondition {
+  id?: string
+  field?: string
+  operator: FilterListOperator
+  value?: string
+  valueType?: "static" | "variable"
+  /** UI-only hint on the config panel — irrelevant to evaluation. */
+  mode?: "dropdown" | "custom"
+}
+
+/** AND/OR condition bundle used by the router's conditional mode. When a
+ *  group matches, every routeId is added to activeRoutes. Multiple groups
+ *  union (deduped). */
+export interface RouterConditionGroup {
+  id?: string
+  conditions?: FilterListCondition[]
+  conditionLogic?: "AND" | "OR"
+  routeIds?: string[]
+}
+
+/**
+ * Options for `evaluateCondition` / `evaluateConditionGroup`.
+ */
+export interface EvaluateConditionOptions {
+  /** When `false`, text operators (`contains`, `not_contains`, `starts_with`,
+   *  `ends_with`, `=`, `!=`) compare case-insensitively using case-folded
+   *  string equality.
+   *
+   *  Note: `=` and `!=` lose their default numeric-coercion semantics under
+   *  `caseSensitive: false`. Under the default (case-sensitive), `1 == "1.0"`
+   *  via `valuesEqual`; under `caseSensitive: false`, comparison is pure
+   *  case-folded string equality, so `"1" !== "1.0"`.
+   *
+   *  Default (when undefined): `true` (case-sensitive) — preserves existing
+   *  behavior for all callers.
+   *
+   *  Non-text operators (`>`, `<`, `>=`, `<=`, `exists`, `not_exists`,
+   *  `regex`) are unaffected by this flag. */
+  caseSensitive?: boolean
+  /** Label→output map for `{Node Label}` refs inside condition values.
+   *  Populated from a filter-list / router node's `"variables"` target
+   *  handle. Resolved via `resolveNodeRefs` — unknown labels preserve
+   *  the original `{...}` text, so JSON-literal values stay intact. */
+  variables?: ReadonlyMap<string, string>
+}
+
+export function tryParseJson(item: unknown): unknown {
+  if (typeof item !== "string") return item
+  const trimmed = item.trim()
+  if (!trimmed) return item
+  const first = trimmed[0]
+  if (first !== "{" && first !== "[" && first !== "\"" && !/^-?\d/.test(trimmed) && trimmed !== "true" && trimmed !== "false" && trimmed !== "null") {
+    return item
+  }
+  try { return JSON.parse(trimmed) } catch { return item }
+}
+
+const HOUR_MS = 60 * 60 * 1000
+const DAY_MS = 24 * HOUR_MS
+const WEEK_MS = 7 * DAY_MS
+
+/** Resolve a relative-window token like `last_N_hours:3` to an ISO timestamp
+ *  N units before `Date.now()`. Returns undefined for malformed tokens. */
+export function resolveRelativeWindowToken(key: string): string | undefined {
+  const m = /^last_N_(hours|days|weeks):(-?\d+)$/.exec(key)
+  if (!m) return undefined
+  const n = parseInt(m[2], 10)
+  if (!Number.isFinite(n)) return undefined
+  const unitMs = m[1] === "hours" ? HOUR_MS : m[1] === "days" ? DAY_MS : WEEK_MS
+  return new Date(Date.now() - n * unitMs).toISOString()
+}
+
+/**
+ * Substitute `{{...}}` template tokens — `{{now}}`, `{{trigger.<path>}}`,
+ * and relative-window tokens (`{{last_N_hours:N}}` / days / weeks). Reused
+ * by `resolveConditionValue` (filter-list / router) and `resolveSelectorRefs`
+ * (selector node) so token semantics stay identical across the workflow-engine
+ * ref-resolution surface.
+ *
+ * Pure: returns a new string. Strings with no `{{...}}` tokens pass through
+ * unchanged.
+ */
+export function substituteTriggerTokens(
+  raw: string,
+  triggerData?: Record<string, unknown>,
+): string {
+  if (!/\{\{/.test(raw)) return raw
+  return raw.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_m, expr) => {
+    const key = String(expr).trim()
+    if (key === "now") return new Date().toISOString()
+    if (key === "trigger.last_triggered_at") {
+      const v = triggerData?.last_triggered_at
+      return v == null ? "" : String(v)
+    }
+    if (key.startsWith("trigger.")) {
+      const path = key.slice("trigger.".length)
+      const v = triggerData?.[path]
+      return v == null ? "" : String(v)
+    }
+    const relative = resolveRelativeWindowToken(key)
+    if (relative !== undefined) return relative
+    return ""
+  })
+}
+
+export function resolveConditionValue(
+  raw: string,
+  valueType: string | undefined,
+  triggerData?: Record<string, unknown>,
+  variables?: ReadonlyMap<string, string>,
+): string {
+  let value = raw
+  if (variables && variables.size > 0) {
+    value = resolveNodeRefs(value, variables)
+  }
+  const hasTemplate = /\{\{/.test(value)
+  if (valueType !== "variable" && !hasTemplate) return value
+  return substituteTriggerTokens(value, triggerData)
+}
+
+function asComparableNumber(v: unknown): number {
+  if (typeof v === "number") return v
+  if (typeof v === "boolean") return v ? 1 : 0
+  if (typeof v === "string") {
+    const trimmed = v.trim()
+    if (trimmed === "") return NaN
+    const n = Number(trimmed)
+    if (!isNaN(n)) return n
+    const d = Date.parse(trimmed)
+    if (!isNaN(d)) return d
+  }
+  return NaN
+}
+
+// Numeric-first ordering compare used by >, <, >=, <=. Falls back to
+// localeCompare when either side can't be parsed as a number.
+function compareValues(a: unknown, b: unknown): number {
+  const na = asComparableNumber(a)
+  const nb = asComparableNumber(b)
+  if (!isNaN(na) && !isNaN(nb)) return na - nb
+  return String(a ?? "").localeCompare(String(b ?? ""))
+}
+
+// Numeric-first equality used by = and !=. So "432" == 432, and 432 == "432".
+// Falls back to strict string equality (null/undefined coerced to "") so
+// alpha values still work.
+function valuesEqual(a: unknown, b: unknown): boolean {
+  const na = asComparableNumber(a)
+  const nb = asComparableNumber(b)
+  if (!isNaN(na) && !isNaN(nb)) return na === nb
+  return String(a ?? "") === String(b ?? "")
+}
+
+function applyCase(s: string, caseSensitive: boolean): string {
+  return caseSensitive ? s : s.toLowerCase()
+}
+
+export function evaluateCondition(
+  parsedItem: unknown,
+  rawItem: string,
+  condition: FilterListCondition,
+  triggerData?: Record<string, unknown>,
+  options?: EvaluateConditionOptions,
+): boolean {
+  const path = (condition.field ?? "").trim()
+  let fieldValue: unknown
+  if (path === "") {
+    fieldValue = parsedItem ?? rawItem
+  } else {
+    const matches = evaluateJsonPath(parsedItem ?? rawItem, path)
+    fieldValue = matches.length > 0 ? matches[0] : undefined
+  }
+
+  const targetStr = resolveConditionValue(condition.value ?? "", condition.valueType, triggerData, options?.variables)
+  // Default to case-sensitive when the flag is not explicitly set. This
+  // preserves existing behavior for Router conditional mode and legacy
+  // Filter List nodes that don't carry the new `caseSensitive` field.
+  const cs = options?.caseSensitive ?? true
+  const fieldStr = String(fieldValue ?? "")
+
+  switch (condition.operator) {
+    case "exists":
+      return fieldValue !== undefined && fieldValue !== null
+    case "not_exists":
+      return fieldValue === undefined || fieldValue === null
+    case "contains":
+      return applyCase(fieldStr, cs).includes(applyCase(targetStr, cs))
+    case "not_contains":
+      return !applyCase(fieldStr, cs).includes(applyCase(targetStr, cs))
+    case "starts_with":
+      return applyCase(fieldStr, cs).startsWith(applyCase(targetStr, cs))
+    case "ends_with":
+      return applyCase(fieldStr, cs).endsWith(applyCase(targetStr, cs))
+    case "regex": {
+      if (!targetStr) return false
+      try {
+        return new RegExp(targetStr).test(fieldStr)
+      } catch {
+        return false
+      }
+    }
+    case "=":
+      return cs
+        ? valuesEqual(fieldValue, targetStr)
+        : applyCase(fieldStr, false) === applyCase(targetStr, false)
+    case "!=":
+      return cs
+        ? !valuesEqual(fieldValue, targetStr)
+        : applyCase(fieldStr, false) !== applyCase(targetStr, false)
+    case ">":
+      return compareValues(fieldValue, targetStr) > 0
+    case "<":
+      return compareValues(fieldValue, targetStr) < 0
+    case ">=":
+      return compareValues(fieldValue, targetStr) >= 0
+    case "<=":
+      return compareValues(fieldValue, targetStr) <= 0
+    default:
+      return false
+  }
+}
+
+/** Evaluate a single AND/OR-joined group against one item. Empty condition
+ *  list evaluates to `true` — typical when the user has just added a group
+ *  and hasn't configured any conditions yet. */
+export function evaluateConditionGroup(
+  parsedItem: unknown,
+  rawItem: string,
+  conditions: readonly FilterListCondition[],
+  logic: "AND" | "OR",
+  triggerData?: Record<string, unknown>,
+  options?: EvaluateConditionOptions,
+): boolean {
+  const effective = conditions.filter((c) => c && c.operator)
+  if (effective.length === 0) return true
+  const results = effective.map((c) => evaluateCondition(parsedItem, rawItem, c, triggerData, options))
+  return logic === "OR" ? results.some(Boolean) : results.every(Boolean)
+}

package/src/flux2-pricing.ts

@@ -0,0 +1,18 @@
+/**
+ * Model-id enum + UI resolution options for Replicate Flux 2 image models.
+ *
+ * The provider-$ rate table and the cost/credit FORMULAS derived from it live
+ * in `backend/src/lib/pricing/flux2-cost.ts` (core, not ee/ — the Replicate
+ * 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.
+ */
+
+export type Flux2Model = "flux-2-klein" | "flux-2-pro" | "flux-2-max"
+
+/** Megapixel tiers offered in the UI (strings; the value space for data.resolution). */
+export const FLUX2_RES_MP = ["0.5", "1", "2", "4"] as const
+
+export function isFlux2Model(m: string): m is Flux2Model {
+  return m === "flux-2-klein" || m === "flux-2-pro" || m === "flux-2-max"
+}

package/src/freecut-protocol.ts

@@ -0,0 +1,52 @@
+// Single source of truth for the Nodaro <-> FreeCut iframe postMessage protocol.
+// Imported by app's freecut-editor-modal and Studio's ported modal so the wire
+// format cannot drift. The fork (Nodaro-ai/freecut-fork) mirrors these strings in
+// src/features/embedded/services/embedded-message-handler.ts + use-send-back.ts.
+
+// Nodaro (parent) -> FreeCut (iframe)
+export const NODARO_LOAD_VIDEO = "NODARO_LOAD_VIDEO"
+// Multi-clip analog of NODARO_LOAD_VIDEO: lay N ordered urls on the timeline as
+// sequential clips (FreeCut fetches them itself). Used by Studio's production
+// "Edit in FreeCut" to assemble the whole cut.
+export const NODARO_LOAD_TIMELINE = "NODARO_LOAD_TIMELINE"
+export const NODARO_IMPORT_FILES = "NODARO_IMPORT_FILES"
+export const NODARO_RESET_PROJECT = "NODARO_RESET_PROJECT"
+
+// FreeCut (iframe) -> Nodaro (parent)
+export const FREECUT_READY = "FREECUT_READY"
+export const FREECUT_EXPORT_COMPLETE = "FREECUT_EXPORT_COMPLETE"
+export const FREECUT_EXPORT_PROGRESS = "FREECUT_EXPORT_PROGRESS" // reserved; fork emits it, v1 parents ignore it
+export const FREECUT_REQUEST_IMPORT = "FREECUT_REQUEST_IMPORT"
+
+export interface FreecutImportFile {
+  readonly name: string
+  readonly type: string
+  readonly size: number
+  readonly buffer: ArrayBuffer
+}
+
+export interface NodaroLoadVideoPayload {
+  readonly videoUrl: string
+  readonly videoBuffer?: ArrayBuffer
+  readonly projectJson?: unknown
+  readonly additionalFiles?: ReadonlyArray<FreecutImportFile>
+}
+
+export interface NodaroLoadTimelinePayload {
+  // Ordered clip urls; FreeCut fetches each and lays them end-to-end on the timeline.
+  readonly clips: ReadonlyArray<string>
+}
+
+export interface FreecutExportCompletePayload {
+  readonly videoBuffer: ArrayBuffer
+  readonly projectJson?: unknown
+}
+
+export interface FreecutExportProgressPayload {
+  readonly percent: number
+}
+
+export interface FreecutRequestImportPayload {
+  readonly accept?: string
+  readonly multiple?: boolean
+}