@nodaro/shared 1.4.1

package/src/__tests__/default-video-provider.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest"
+import {
+  DEFAULT_VIDEO_PROVIDER,
+  DEFAULT_VIDEO_DURATION_SEC,
+  applyDefaultVideoSelection,
+  buildVideoCreditModelIdentifier,
+  MODEL_CATALOG,
+} from "../index.js"
+
+// Guards the platform-wide default video model. If the default is ever
+// retired from the catalog, loses a mode, or its cheapest tier stops
+// resolving, this fails BEFORE users hit price/validation errors.
+describe("DEFAULT_VIDEO_PROVIDER", () => {
+  it("exists in the catalog and supports BOTH t2v and i2v (unified-node default)", () => {
+    const entry = MODEL_CATALOG[DEFAULT_VIDEO_PROVIDER]
+    expect(entry).toBeDefined()
+    expect(entry.modes).toContain("t2v")
+    expect(entry.modes).toContain("i2v")
+  })
+
+  it("supports the 480p tier the omitted-resolution path lands on", () => {
+    expect(MODEL_CATALOG[DEFAULT_VIDEO_PROVIDER].resolutions).toContain("480p")
+  })
+
+  it("nothing-specified request resolves to the cheapest seeded composite", () => {
+    const sel = applyDefaultVideoSelection({})
+    const id = buildVideoCreditModelIdentifier(
+      sel.provider, sel.duration, undefined, "image-to-video", undefined, undefined, false,
+    )
+    expect(id).toBe(`${DEFAULT_VIDEO_PROVIDER}:${DEFAULT_VIDEO_DURATION_SEC}s:480p`)
+  })
+})
+
+describe("applyDefaultVideoSelection", () => {
+  it("omitted both → default provider + default duration", () => {
+    expect(applyDefaultVideoSelection({})).toEqual({
+      provider: DEFAULT_VIDEO_PROVIDER,
+      duration: DEFAULT_VIDEO_DURATION_SEC,
+    })
+  })
+
+  it("explicit provider keeps its own duration semantics (no forced duration)", () => {
+    expect(applyDefaultVideoSelection({ provider: "kling" })).toEqual({
+      provider: "kling",
+      duration: undefined,
+    })
+  })
+
+  it("explicit duration is never overridden", () => {
+    expect(applyDefaultVideoSelection({ duration: 10 })).toEqual({
+      provider: DEFAULT_VIDEO_PROVIDER,
+      duration: 10,
+    })
+    expect(applyDefaultVideoSelection({ provider: "veo3.1", duration: 8 })).toEqual({
+      provider: "veo3.1",
+      duration: 8,
+    })
+  })
+
+  it("empty-string provider counts as omitted", () => {
+    expect(applyDefaultVideoSelection({ provider: "" }).provider).toBe(DEFAULT_VIDEO_PROVIDER)
+  })
+})

package/src/__tests__/entity-image-handle.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest"
+import { resolveEffectiveSourceType, ENTITY_IMAGE_HANDLE_TYPES } from "../entity-image-handle.js"
+
+const ENTITY_REF_HANDLE: Record<string, string> = {
+  character: "characterRef",
+  location: "locationRef",
+  object: "objectRef",
+  creature: "creatureRef",
+}
+
+describe("resolveEffectiveSourceType (entity image handle → upload-image)", () => {
+  it("remaps every entity type's `image` handle to a plain image producer", () => {
+    for (const entity of ENTITY_IMAGE_HANDLE_TYPES) {
+      expect(resolveEffectiveSourceType(entity, "image")).toBe("upload-image")
+    }
+  })
+
+  it("leaves the identity `*Ref` handle as the entity type", () => {
+    for (const entity of ENTITY_IMAGE_HANDLE_TYPES) {
+      expect(resolveEffectiveSourceType(entity, ENTITY_REF_HANDLE[entity])).toBe(entity)
+    }
+  })
+
+  it("leaves the bare/legacy no-handle case as the entity type", () => {
+    expect(resolveEffectiveSourceType("character", undefined)).toBe("character")
+    expect(resolveEffectiveSourceType("character", null)).toBe("character")
+  })
+
+  it("does not remap non-entity producers on the `image` handle", () => {
+    expect(resolveEffectiveSourceType("generate-image", "image")).toBe("generate-image")
+    expect(resolveEffectiveSourceType("upload-image", "image")).toBe("upload-image")
+  })
+
+  it("returns empty string for an undefined source type", () => {
+    expect(resolveEffectiveSourceType(undefined, "image")).toBe("")
+  })
+
+  it("ENTITY_IMAGE_HANDLE_TYPES is exactly the four entity nodes with an image handle", () => {
+    expect([...ENTITY_IMAGE_HANDLE_TYPES].sort()).toEqual(
+      ["character", "creature", "location", "object"],
+    )
+  })
+})

package/src/__tests__/entity-variants.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest"
+import {
+  OBJECT_ASSET_VARIANTS,
+  LOCATION_ASSET_VARIANTS,
+  CHARACTER_ASSET_VARIANTS,
+} from "../entity-asset-types.js"
+
+describe("hoisted entity variant value-lists", () => {
+  it("object variants match the values currently in generate-object-asset.ts", () => {
+    expect(OBJECT_ASSET_VARIANTS.angles).toEqual(["front", "side", "top", "back", "three-quarter"])
+    expect(OBJECT_ASSET_VARIANTS.materials).toEqual(["wood", "metal", "glass", "plastic", "fabric", "stone"])
+    expect(OBJECT_ASSET_VARIANTS.variations).toEqual(["clean", "weathered", "damaged", "ornate", "minimal"])
+  })
+  it("location variants match the values currently in generate-location-asset.ts", () => {
+    expect(LOCATION_ASSET_VARIANTS.timeOfDay).toEqual([
+      "dawn", "morning", "noon", "afternoon", "golden hour", "dusk", "blue hour", "night", "midnight",
+    ])
+    expect(LOCATION_ASSET_VARIANTS.weather).toEqual([
+      "clear", "cloudy", "light rain", "heavy rain", "storm", "snow", "blizzard", "fog", "mist",
+    ])
+    expect(LOCATION_ASSET_VARIANTS.seasons).toEqual(["spring", "summer", "autumn", "winter"])
+    expect(LOCATION_ASSET_VARIANTS.angles).toEqual([
+      "wide", "medium", "closeup", "aerial", "low-angle", "eye-level", "bird's-eye", "dutch tilt",
+    ])
+    expect(LOCATION_ASSET_VARIANTS.lighting).toEqual([
+      "soft natural", "harsh sunlight", "golden", "blue hour", "neon", "candlelit", "cinematic", "dramatic chiaroscuro",
+    ])
+  })
+  it("character variants are still present (unchanged)", () => {
+    expect(CHARACTER_ASSET_VARIANTS.angles).toContain("3/4 left")
+    expect(CHARACTER_ASSET_VARIANTS.expressions).toHaveLength(11)
+  })
+})

package/src/__tests__/fal-lip-sync-sets.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest"
+import {
+  LIP_SYNC_PROVIDERS,
+  VIDEO_INPUT_LIP_SYNC_PROVIDERS,
+  FAL_LIP_SYNC_PROVIDERS,
+  REPLICATE_LIP_SYNC_PROVIDERS,
+} from "../model-constants.js"
+
+describe("sync-lipsync-v3 provider-set membership", () => {
+  it("is listed in LIP_SYNC_PROVIDERS (widens the lip-sync route Zod enum)", () => {
+    expect(LIP_SYNC_PROVIDERS).toContain("sync-lipsync-v3")
+  })
+
+  it("is in FAL_LIP_SYNC_PROVIDERS", () => {
+    expect(FAL_LIP_SYNC_PROVIDERS.has("sync-lipsync-v3")).toBe(true)
+  })
+
+  it("is in VIDEO_INPUT_LIP_SYNC_PROVIDERS (video-driven dubbing)", () => {
+    expect(VIDEO_INPUT_LIP_SYNC_PROVIDERS.has("sync-lipsync-v3")).toBe(true)
+  })
+
+  it("is NOT in REPLICATE_LIP_SYNC_PROVIDERS (it's a fal model, not Replicate)", () => {
+    expect(REPLICATE_LIP_SYNC_PROVIDERS.has("sync-lipsync-v3" as never)).toBe(false)
+  })
+
+  it("FAL and REPLICATE lip-sync sets are disjoint", () => {
+    for (const p of FAL_LIP_SYNC_PROVIDERS) {
+      expect(REPLICATE_LIP_SYNC_PROVIDERS.has(p as never)).toBe(false)
+    }
+  })
+})

package/src/__tests__/featured-entities.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest"
+import { FEATURED_ENTITIES, getFeaturedEntities } from "../featured-entities.js"
+
+describe("FEATURED_ENTITIES", () => {
+  it("covers the three pipeline entity types", () => {
+    expect(Object.keys(FEATURED_ENTITIES).sort()).toEqual([
+      "character",
+      "location",
+      "object",
+    ])
+  })
+
+  it("every preset has a unique id within its type and a usable description", () => {
+    for (const [type, presets] of Object.entries(FEATURED_ENTITIES)) {
+      const ids = presets.map((p) => p.id)
+      expect(new Set(ids).size, `${type} ids unique`).toBe(ids.length)
+      for (const p of presets) {
+        expect(p.label.length, `${type}/${p.id} label`).toBeGreaterThan(0)
+        expect(p.description.length, `${type}/${p.id} description`).toBeGreaterThan(20)
+      }
+    }
+  })
+})
+
+describe("getFeaturedEntities", () => {
+  it("returns presets for a known type", () => {
+    expect(getFeaturedEntities("character").length).toBeGreaterThan(0)
+  })
+
+  it("returns an empty array for an unknown type (e.g. scene)", () => {
+    expect(getFeaturedEntities("scene")).toEqual([])
+  })
+})

package/src/__tests__/film-pricing.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest"
+import {
+  estimateFilmCredits,
+  FILM_BASE_CREDITS,
+  VIDEO_CLIP_CREDITS,
+} from "../film-pricing.js"
+
+describe("estimateFilmCredits", () => {
+  it("includes the fixed base for the shortest film", () => {
+    const est = estimateFilmCredits(5, "kling-turbo")
+    // 5s / 5s clip = 1 shot; perShot = 11 + 2 + 2 = 15; base 45 → 60.
+    expect(est.baseCredits).toBe(FILM_BASE_CREDITS)
+    expect(est.shotCount).toBe(1)
+    expect(est.totalCredits).toBe(60)
+    expect(est.modelKnown).toBe(true)
+  })
+
+  it("scales shot count with duration / clipSeconds", () => {
+    // 60s / 5s = 12 shots; perShot 15 → 180 + 45 = 225.
+    const est = estimateFilmCredits(60, "kling-turbo")
+    expect(est.shotCount).toBe(12)
+    expect(est.totalCredits).toBe(225)
+  })
+
+  it("is model-driven — premium models cost far more per second", () => {
+    const budget = estimateFilmCredits(60, "veo3_lite")
+    const premium = estimateFilmCredits(60, "veo3")
+    expect(premium.totalCredits).toBeGreaterThan(budget.totalCredits * 3)
+  })
+
+  it("seedance-2 (8s clips, ref) — 30s film", () => {
+    // 30 / 8 = ceil 4 shots; perShot = 50 + 2 + 2 = 54; 4*54 = 216 + 45 = 261.
+    const est = estimateFilmCredits(30, "seedance-2")
+    expect(est.shotCount).toBe(4)
+    expect(est.totalCredits).toBe(261)
+  })
+
+  it("long film (30 min) on a quality model is thousands of credits", () => {
+    const est = estimateFilmCredits(1800, "seedance-2")
+    // 1800 / 8 = 225 shots × 54 = 12150 + 45 = 12195.
+    expect(est.shotCount).toBe(225)
+    expect(est.totalCredits).toBe(12195)
+  })
+
+  it("falls back to the default rate when no model is pinned (Auto)", () => {
+    const auto = estimateFilmCredits(60)
+    const turbo = estimateFilmCredits(60, "kling-turbo")
+    expect(auto.modelKnown).toBe(false)
+    expect(auto.totalCredits).toBe(turbo.totalCredits) // default = kling-turbo
+  })
+
+  it("reports a credits-per-second figure", () => {
+    const est = estimateFilmCredits(60, "kling-turbo")
+    expect(est.creditsPerSecond).toBeGreaterThan(0)
+    expect(est.creditsPerSecond).toBeCloseTo(225 / 60, 1)
+  })
+
+  it("every pinnable model in the table has positive cost + clip length", () => {
+    for (const [model, c] of Object.entries(VIDEO_CLIP_CREDITS)) {
+      expect(c.credits, `${model} credits`).toBeGreaterThan(0)
+      expect(c.clipSeconds, `${model} clipSeconds`).toBeGreaterThan(0)
+    }
+  })
+})

package/src/__tests__/filter-condition.test.ts

@@ -0,0 +1,285 @@
+import { describe, it, expect } from "vitest"
+import {
+  evaluateCondition,
+  evaluateConditionGroup,
+  resolveConditionValue,
+  tryParseJson,
+  type FilterListCondition,
+  type FilterListOperator,
+} from "../filter-condition.js"
+
+function cond(partial: Partial<FilterListCondition> & { operator: FilterListCondition["operator"] }): FilterListCondition {
+  return {
+    field: partial.field ?? "",
+    value: partial.value ?? "",
+    valueType: partial.valueType ?? "static",
+    ...partial,
+  }
+}
+
+describe("evaluateCondition — operator semantics (parity with filter-list)", () => {
+  it("starts_with / ends_with match string prefixes / suffixes", () => {
+    expect(evaluateCondition({ url: "https://foo" }, "", cond({ field: "url", operator: "starts_with", value: "https" }))).toBe(true)
+    expect(evaluateCondition({ file: "a.jpg" }, "", cond({ field: "file", operator: "ends_with", value: ".jpg" }))).toBe(true)
+    expect(evaluateCondition({ url: "ftp://bar" }, "", cond({ field: "url", operator: "starts_with", value: "https" }))).toBe(false)
+  })
+
+  it("regex matches", () => {
+    expect(evaluateCondition({ v: "hello" }, "", cond({ field: "v", operator: "regex", value: "^h[elo]+$" }))).toBe(true)
+    // invalid pattern => drop
+    expect(evaluateCondition({ v: "x" }, "", cond({ field: "v", operator: "regex", value: "[unclosed" }))).toBe(false)
+    // empty value => drop
+    expect(evaluateCondition({ v: "x" }, "", cond({ field: "v", operator: "regex", value: "" }))).toBe(false)
+  })
+
+  it("contains stringifies numeric values", () => {
+    expect(evaluateCondition({ v: 432 }, "", cond({ field: "v", operator: "contains", value: "3" }))).toBe(true)
+  })
+
+  it("numeric-first equality", () => {
+    expect(evaluateCondition({ v: 432 }, "", cond({ field: "v", operator: "=", value: "432" }))).toBe(true)
+    expect(evaluateCondition({ v: "432" }, "", cond({ field: "v", operator: "=", value: "432" }))).toBe(true)
+  })
+
+  it("exists / not_exists only null/undefined-sensitive", () => {
+    expect(evaluateCondition({ v: "" }, "", cond({ field: "v", operator: "exists" }))).toBe(true)
+    expect(evaluateCondition({ v: null }, "", cond({ field: "v", operator: "exists" }))).toBe(false)
+    expect(evaluateCondition({ other: 1 }, "", cond({ field: "v", operator: "not_exists" }))).toBe(true)
+  })
+
+  it("empty field path uses the whole item", () => {
+    expect(evaluateCondition("hello world", "hello world", cond({ operator: "contains", value: "world" }))).toBe(true)
+  })
+})
+
+describe("evaluateConditionGroup — AND/OR", () => {
+  const item = { url: "https://example.com/news", label: "news today" }
+  const c1 = cond({ field: "url", operator: "starts_with", value: "https" })
+  const c2 = cond({ field: "label", operator: "contains", value: "news" })
+  const c3 = cond({ field: "label", operator: "contains", value: "sports" })
+
+  it("AND requires all conditions", () => {
+    expect(evaluateConditionGroup(item, "", [c1, c2], "AND")).toBe(true)
+    expect(evaluateConditionGroup(item, "", [c1, c3], "AND")).toBe(false)
+  })
+
+  it("OR accepts any match", () => {
+    expect(evaluateConditionGroup(item, "", [c1, c3], "OR")).toBe(true)
+    expect(evaluateConditionGroup(item, "", [c3, cond({ field: "label", operator: "contains", value: "weather" })], "OR")).toBe(false)
+  })
+
+  it("empty condition list evaluates to true (tautology)", () => {
+    expect(evaluateConditionGroup(item, "", [], "AND")).toBe(true)
+    expect(evaluateConditionGroup(item, "", [], "OR")).toBe(true)
+  })
+
+  it("ignores conditions with a missing operator", () => {
+    expect(evaluateConditionGroup(item, "", [{ operator: "" as unknown as FilterListCondition["operator"], value: "" }], "AND")).toBe(true)
+  })
+})
+
+describe("resolveConditionValue — trigger + relative-window tokens", () => {
+  it("resolves trigger.last_triggered_at when triggerData is passed", () => {
+    const out = resolveConditionValue("{{trigger.last_triggered_at}}", "variable", { last_triggered_at: "2026-01-01T00:00:00Z" })
+    expect(out).toBe("2026-01-01T00:00:00Z")
+  })
+
+  it("falls back to empty string without triggerData", () => {
+    expect(resolveConditionValue("{{trigger.last_triggered_at}}", "variable")).toBe("")
+  })
+
+  it("resolves a last_N_hours token to a valid ISO timestamp in the past", () => {
+    const out = resolveConditionValue("{{last_N_hours:3}}", "variable")
+    const t = Date.parse(out)
+    expect(Number.isFinite(t)).toBe(true)
+    expect(t).toBeLessThan(Date.now())
+  })
+
+  it("passes through a plain string when not variable and has no template", () => {
+    expect(resolveConditionValue("hello", "static")).toBe("hello")
+  })
+})
+
+describe("resolveConditionValue — {Node Label} variable refs", () => {
+  it("substitutes a single {Label} ref from the variables map", () => {
+    const vars = new Map([["DateNode", "2026-04-21T00:00:00Z"]])
+    expect(resolveConditionValue("{DateNode}", "static", undefined, vars)).toBe("2026-04-21T00:00:00Z")
+  })
+
+  it("leaves unknown {Label} refs intact (same behavior as resolveNodeRefs)", () => {
+    const vars = new Map([["Foo", "bar"]])
+    expect(resolveConditionValue("{Missing}", "static", undefined, vars)).toBe("{Missing}")
+  })
+
+  it("preserves JSON-literal condition values that happen to contain braces", () => {
+    const vars = new Map([["Foo", "bar"]])
+    expect(resolveConditionValue('{"k":"v"}', "static", undefined, vars)).toBe('{"k":"v"}')
+  })
+
+  it("mixes {Label} refs with {{built-in tokens}} in the same value", () => {
+    const vars = new Map([["DateNode", "2026-04-21T00:00:00Z"]])
+    const out = resolveConditionValue("{DateNode} < {{trigger.last_triggered_at}}", "static", { last_triggered_at: "2026-05-01T00:00:00Z" }, vars)
+    expect(out).toBe("2026-04-21T00:00:00Z < 2026-05-01T00:00:00Z")
+  })
+
+  it("works without variables map (backward compat)", () => {
+    expect(resolveConditionValue("{{now}}", "variable")).toMatch(/^\d{4}-\d{2}-\d{2}T/)
+  })
+
+  it("resolves a variable ref even when valueType is 'static'", () => {
+    const vars = new Map([["X", "42"]])
+    expect(resolveConditionValue("{X}", "static", undefined, vars)).toBe("42")
+  })
+})
+
+describe("evaluateCondition — variables in the condition value", () => {
+  it("threads variables through options and matches against resolved value", () => {
+    const vars = new Map([["Threshold", "100"]])
+    const passed = evaluateCondition(
+      { likes: 150 },
+      "",
+      cond({ field: "likes", operator: ">", value: "{Threshold}" }),
+      undefined,
+      { variables: vars },
+    )
+    expect(passed).toBe(true)
+  })
+
+  it("compares equality against a resolved variable", () => {
+    const vars = new Map([["Expected", "hello"]])
+    const passed = evaluateCondition(
+      { greeting: "hello" },
+      "",
+      cond({ field: "greeting", operator: "=", value: "{Expected}" }),
+      undefined,
+      { variables: vars },
+    )
+    expect(passed).toBe(true)
+  })
+})
+
+describe("evaluateConditionGroup — variables in options", () => {
+  it("passes variables through to evaluateCondition", () => {
+    const vars = new Map([["Min", "10"]])
+    const result = evaluateConditionGroup(
+      { score: 50 },
+      "",
+      [cond({ field: "score", operator: ">", value: "{Min}" })],
+      "AND",
+      undefined,
+      { variables: vars },
+    )
+    expect(result).toBe(true)
+  })
+})
+
+describe("tryParseJson", () => {
+  it("parses JSON objects", () => {
+    expect(tryParseJson('{"a":1}')).toEqual({ a: 1 })
+  })
+
+  it("parses JSON arrays", () => {
+    expect(tryParseJson("[1,2,3]")).toEqual([1, 2, 3])
+  })
+
+  it("returns non-JSON-looking strings untouched", () => {
+    expect(tryParseJson("hello world")).toBe("hello world")
+  })
+
+  it("returns malformed JSON untouched", () => {
+    expect(tryParseJson("{not json")).toBe("{not json")
+  })
+
+  it("non-string values are passed through", () => {
+    const obj = { a: 1 }
+    expect(tryParseJson(obj)).toBe(obj)
+  })
+})
+
+describe("evaluateCondition — case sensitivity option", () => {
+  const mkCond = (operator: FilterListOperator, value: string, field = ""): FilterListCondition =>
+    ({ operator, value, field })
+
+  // Default behavior: case-sensitive (preserves existing production semantics)
+
+  it("default behavior is case-sensitive — contains", () => {
+    expect(evaluateCondition("HELLO world", "HELLO world", mkCond("contains", "hello"))).toBe(false)
+    expect(evaluateCondition("HELLO world", "HELLO world", mkCond("contains", "HELLO"))).toBe(true)
+  })
+
+  it("default behavior is case-sensitive — equals", () => {
+    expect(evaluateCondition("Apple", "Apple", mkCond("=", "apple"))).toBe(false)
+    expect(evaluateCondition("Apple", "Apple", mkCond("=", "Apple"))).toBe(true)
+  })
+
+  // Explicit caseSensitive: true — identical to default, exercised for completeness
+
+  it("caseSensitive: true — explicit opt-in matches default", () => {
+    expect(evaluateCondition("HELLO", "HELLO", mkCond("contains", "hello"), undefined,
+      { caseSensitive: true })).toBe(false)
+    expect(evaluateCondition("HELLO hello", "HELLO hello", mkCond("contains", "hello"), undefined,
+      { caseSensitive: true })).toBe(true)
+  })
+
+  it("caseSensitive: true — equals, starts_with, ends_with are strict", () => {
+    expect(evaluateCondition("Apple", "Apple", mkCond("=", "apple"), undefined,
+      { caseSensitive: true })).toBe(false)
+    expect(evaluateCondition("Apple", "Apple", mkCond("starts_with", "apple"), undefined,
+      { caseSensitive: true })).toBe(false)
+    expect(evaluateCondition("Apple", "Apple", mkCond("ends_with", "pple"), undefined,
+      { caseSensitive: true })).toBe(true)
+  })
+
+  // caseSensitive: false — the new case-insensitive mode
+
+  it("caseSensitive: false — contains", () => {
+    expect(evaluateCondition("HELLO world", "HELLO world", mkCond("contains", "hello"), undefined,
+      { caseSensitive: false })).toBe(true)
+    expect(evaluateCondition("Foo", "Foo", mkCond("contains", "BAR"), undefined,
+      { caseSensitive: false })).toBe(false)
+  })
+
+  it("caseSensitive: false — equals, not_equals, starts_with, ends_with", () => {
+    expect(evaluateCondition("Apple", "Apple", mkCond("=", "apple"), undefined,
+      { caseSensitive: false })).toBe(true)
+    expect(evaluateCondition("Apple", "Apple", mkCond("!=", "APPLE"), undefined,
+      { caseSensitive: false })).toBe(false)
+    expect(evaluateCondition("Apple Pie", "Apple Pie", mkCond("starts_with", "apple"), undefined,
+      { caseSensitive: false })).toBe(true)
+    expect(evaluateCondition("Apple Pie", "Apple Pie", mkCond("ends_with", "PIE"), undefined,
+      { caseSensitive: false })).toBe(true)
+  })
+
+  it("caseSensitive: false — not_contains respects the flag", () => {
+    expect(evaluateCondition("HELLO world", "HELLO world", mkCond("not_contains", "hello"), undefined,
+      { caseSensitive: false })).toBe(false)
+    expect(evaluateCondition("HELLO world", "HELLO world", mkCond("not_contains", "xyz"), undefined,
+      { caseSensitive: false })).toBe(true)
+  })
+
+  // Non-text operators are never affected by the flag
+
+  it("ignores the option for non-text operators — >, <, exists, not_exists", () => {
+    expect(evaluateCondition("5", "5", mkCond(">", "3"), undefined,
+      { caseSensitive: true })).toBe(true)
+    expect(evaluateCondition("5", "5", mkCond(">", "3"), undefined,
+      { caseSensitive: false })).toBe(true)
+    expect(evaluateCondition("value", "value", mkCond("exists", ""), undefined,
+      { caseSensitive: true })).toBe(true)
+    // not_exists is null/undefined-sensitive only. Use a field path pointing at
+    // a missing key so the fieldValue is legitimately undefined under both settings.
+    expect(evaluateCondition({ other: 1 }, "", mkCond("not_exists", "", "v"), undefined,
+      { caseSensitive: false })).toBe(true)
+    expect(evaluateCondition({ other: 1 }, "", mkCond("not_exists", "", "v"), undefined,
+      { caseSensitive: true })).toBe(true)
+  })
+
+  it("regex operator is always driven by the pattern itself — option ignored", () => {
+    // Users can use `(?i)` flags or explicitly matching patterns for
+    // case-insensitive regex. The caseSensitive option does not modify the regex.
+    expect(evaluateCondition("Apple", "Apple", mkCond("regex", "^apple$"), undefined,
+      { caseSensitive: false })).toBe(false)
+    expect(evaluateCondition("Apple", "Apple", mkCond("regex", "^Apple$"), undefined,
+      { caseSensitive: false })).toBe(true)
+  })
+})

package/src/__tests__/freecut-protocol.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest"
+import {
+  NODARO_LOAD_VIDEO,
+  NODARO_LOAD_TIMELINE,
+  NODARO_IMPORT_FILES,
+  NODARO_RESET_PROJECT,
+  FREECUT_READY,
+  FREECUT_EXPORT_COMPLETE,
+  FREECUT_EXPORT_PROGRESS,
+  FREECUT_REQUEST_IMPORT,
+} from "../freecut-protocol.js"
+
+describe("freecut protocol constants", () => {
+  it("pins the wire strings the fork mirrors", () => {
+    expect({
+      NODARO_LOAD_VIDEO,
+      NODARO_LOAD_TIMELINE,
+      NODARO_IMPORT_FILES,
+      NODARO_RESET_PROJECT,
+      FREECUT_READY,
+      FREECUT_EXPORT_COMPLETE,
+      FREECUT_EXPORT_PROGRESS,
+      FREECUT_REQUEST_IMPORT,
+    }).toEqual({
+      NODARO_LOAD_VIDEO: "NODARO_LOAD_VIDEO",
+      NODARO_LOAD_TIMELINE: "NODARO_LOAD_TIMELINE",
+      NODARO_IMPORT_FILES: "NODARO_IMPORT_FILES",
+      NODARO_RESET_PROJECT: "NODARO_RESET_PROJECT",
+      FREECUT_READY: "FREECUT_READY",
+      FREECUT_EXPORT_COMPLETE: "FREECUT_EXPORT_COMPLETE",
+      FREECUT_EXPORT_PROGRESS: "FREECUT_EXPORT_PROGRESS",
+      FREECUT_REQUEST_IMPORT: "FREECUT_REQUEST_IMPORT",
+    })
+  })
+})

package/src/__tests__/generate-text-items.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest"
+import { splitGeneratedItems, GENERATE_TEXT_DELIMITER } from "../generate-text-items"
+
+describe("splitGeneratedItems", () => {
+  it("splits on the delimiter, trims, drops empties", () => {
+    expect(splitGeneratedItems(`a${GENERATE_TEXT_DELIMITER}  b  ${GENERATE_TEXT_DELIMITER}c`)).toEqual(["a", "b", "c"])
+  })
+  it("collapses blank/whitespace-only segments", () => {
+    expect(splitGeneratedItems(`  one  ${GENERATE_TEXT_DELIMITER}   ${GENERATE_TEXT_DELIMITER}  two  `)).toEqual(["one", "two"])
+  })
+  it("no delimiter → single trimmed item", () => {
+    expect(splitGeneratedItems("just one block")).toEqual(["just one block"])
+  })
+  it("empty/undefined → []", () => {
+    expect(splitGeneratedItems("")).toEqual([])
+    expect(splitGeneratedItems(undefined)).toEqual([])
+    expect(splitGeneratedItems("   ")).toEqual([])
+  })
+})

package/src/__tests__/generated-results.test.ts

@@ -0,0 +1,50 @@
+import { spreadJsonArrayIfSingleton } from "../generated-results.js"
+
+describe("spreadJsonArrayIfSingleton", () => {
+  it("spreads a single JSON-array string into stringified elements", () => {
+    const input = [JSON.stringify([{ a: 1 }, { a: 2 }])]
+    const result = spreadJsonArrayIfSingleton(input)
+    expect(result).toEqual(['{"a":1}', '{"a":2}'])
+  })
+
+  it("preserves string elements verbatim (no double-stringify)", () => {
+    const input = [JSON.stringify(["hello", "world"])]
+    const result = spreadJsonArrayIfSingleton(input)
+    expect(result).toEqual(["hello", "world"])
+  })
+
+  it("leaves multi-item lists alone", () => {
+    const input = [JSON.stringify([1, 2]), JSON.stringify([3, 4])]
+    const result = spreadJsonArrayIfSingleton(input)
+    expect(result).toBe(input)
+  })
+
+  it("leaves non-JSON single items alone", () => {
+    const input = ["just a sentence"]
+    const result = spreadJsonArrayIfSingleton(input)
+    expect(result).toBe(input)
+  })
+
+  it("leaves JSON objects (non-array) alone", () => {
+    const input = [JSON.stringify({ a: 1, b: 2 })]
+    const result = spreadJsonArrayIfSingleton(input)
+    expect(result).toBe(input)
+  })
+
+  it("leaves an empty JSON array alone", () => {
+    const input = ["[]"]
+    const result = spreadJsonArrayIfSingleton(input)
+    expect(result).toBe(input)
+  })
+
+  it("handles whitespace-padded JSON arrays", () => {
+    const input = ["  [1, 2, 3]  "]
+    const result = spreadJsonArrayIfSingleton(input)
+    expect(result).toEqual(["1", "2", "3"])
+  })
+
+  it("leaves empty list alone", () => {
+    const result = spreadJsonArrayIfSingleton([])
+    expect(result).toEqual([])
+  })
+})