@nodaro/shared 1.20.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/llm-models.test.ts

@@ -10,6 +10,8 @@ import {
   resolveLlmCreditId,
   motionGraphicsFeature,
   effectiveReasoningEffort,
+  supportsAdvancedMode,
+  availableReasoningEfforts,
 } from "../llm-models.js"
 import type { LlmModelDef, LlmTier, LlmFeature } from "../llm-models.js"
 import { PIPELINE_PINNABLE_SCRIPT_LLMS } from "../pipeline-types.js"
@@ -609,3 +611,139 @@ describe("buildLlmCreditIdentifier effort bump (xhigh/max only)", () => {
     expect(resolveLlmCreditId("llm-chat", { llmModel: "gpt-5.6-terra", reasoningEffort: "max" })).toBe("llm-chat:premium")
   })
 })
+
+describe("direct-vendor lane declarations", () => {
+  it("no model declares BOTH preferKie and preferDirect", () => {
+    // They are the two halves of one idea (which lane goes first). Declaring
+    // both is meaningless and would make routing depend on branch order in
+    // llm-client rather than on the registry.
+    const conflicted = LLM_MODELS.filter((m) => m.preferKie && m.preferDirect).map((m) => m.id)
+    expect(conflicted).toEqual([])
+  })
+
+  it("preferDirect is only meaningful alongside a directGeminiModel", () => {
+    const orphaned = LLM_MODELS.filter((m) => m.preferDirect && !m.directGeminiModel).map((m) => m.id)
+    expect(orphaned).toEqual([])
+  })
+
+  it("every direct-lane model id is a non-empty, non-placeholder string", () => {
+    for (const m of LLM_MODELS.filter((x) => x.directGeminiModel)) {
+      expect(m.directGeminiModel!.length, m.id).toBeGreaterThan(0)
+      expect(m.directGeminiModel, m.id).not.toContain(" ")
+    }
+  })
+
+  it("only google-vendor models carry a Gemini direct lane", () => {
+    const misvendored = LLM_MODELS.filter((m) => m.directGeminiModel && m.vendor !== "google").map((m) => m.id)
+    expect(misvendored).toEqual([])
+  })
+
+  it("getLlmModel resolves a model by its direct Google id", () => {
+    // The `-preview`-suffixed Google ids differ from our canonical ids, and
+    // cost/usage reconciliation looks models up by whatever id the wire used.
+    expect(getLlmModel("gemini-3.1-pro-preview")?.id).toBe("gemini-3.1-pro")
+    expect(getLlmModel("gemini-3-flash-preview")?.id).toBe("gemini-3-flash")
+  })
+})
+
+describe("advanced mode", () => {
+  it("is available exactly on models with a direct Gemini lane", () => {
+    for (const m of LLM_MODELS) {
+      expect(supportsAdvancedMode(m.id), m.id).toBe(Boolean(m.directGeminiModel))
+    }
+  })
+
+  it("is unavailable for an unknown or missing model id", () => {
+    expect(supportsAdvancedMode(undefined)).toBe(false)
+    expect(supportsAdvancedMode("not-a-real-model")).toBe(false)
+  })
+
+  it("bumps the credit tier one step", () => {
+    // gemini-3-flash is economy → standard (standard renders as the bare feature)
+    expect(buildLlmCreditIdentifier("llm-chat", "gemini-3-flash")).toBe("llm-chat:economy")
+    expect(buildLlmCreditIdentifier("llm-chat", "gemini-3-flash", undefined, true)).toBe("llm-chat")
+  })
+
+  it("is independent of the effort bump — advanced adds exactly one step", () => {
+    // No Gemini model declares xhigh/max today (their KIE-safe ceiling is
+    // `high`, which never bumps), so the two bumps cannot currently stack in
+    // practice — `max` clamps to `high` first. What must hold regardless is
+    // that advanced adds exactly one step on top of whatever the
+    // effort-clamped tier already is.
+    for (const effort of [undefined, "low", "high", "max"]) {
+      const plain = buildLlmCreditIdentifier("llm-chat", "gemini-3.6-flash", effort)
+      const advanced = buildLlmCreditIdentifier("llm-chat", "gemini-3.6-flash", effort, true)
+      expect(plain, `effort=${effort}`).toBe("llm-chat:economy")
+      expect(advanced, `effort=${effort}`).toBe("llm-chat")
+    }
+  })
+
+  it("never bumps past premium", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "gemini-3.1-pro", "max", true)).toBe("llm-chat:premium")
+  })
+
+  it("ignores the flag on a model that cannot run advanced (no silent overcharge)", () => {
+    // gpt-5.2 has no direct lane — a stale advancedMode flag must not inflate it.
+    expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.2", undefined, true))
+      .toBe(buildLlmCreditIdentifier("llm-chat", "gpt-5.2"))
+    expect(buildLlmCreditIdentifier("llm-chat", "claude-opus-4.7", undefined, true))
+      .toBe(buildLlmCreditIdentifier("llm-chat", "claude-opus-4.7"))
+  })
+
+  it("back-compat: omitting the 4th arg is identical to before for every model", () => {
+    for (const m of LLM_MODELS) {
+      expect(buildLlmCreditIdentifier("x", m.id, "high", false)).toBe(buildLlmCreditIdentifier("x", m.id, "high"))
+    }
+  })
+
+  it("resolveLlmCreditId reads advancedMode from the raw body", () => {
+    expect(resolveLlmCreditId("llm-chat", { llmModel: "gemini-3-flash", advancedMode: true })).toBe("llm-chat")
+    expect(resolveLlmCreditId("llm-chat", { llmModel: "gemini-3-flash" })).toBe("llm-chat:economy")
+    // Only a real boolean true counts — a truthy string must not bump.
+    expect(resolveLlmCreditId("llm-chat", { llmModel: "gemini-3-flash", advancedMode: "yes" })).toBe("llm-chat:economy")
+  })
+})
+
+describe("lane-aware reasoning efforts", () => {
+  it("widens the ladder on the direct lane where the vendor accepts more", () => {
+    expect(availableReasoningEfforts("gemini-3.6-flash")).toEqual(["low", "high"])
+    expect(availableReasoningEfforts("gemini-3.6-flash", true)).toEqual(["none", "low", "medium", "high"])
+  })
+
+  it("exposes an effort lever on models that have none via KIE", () => {
+    // gemini-3-flash declares no reasoningEfforts at all — Advanced is the
+    // only way its effort picker appears.
+    expect(availableReasoningEfforts("gemini-3-flash")).toEqual([])
+    expect(availableReasoningEfforts("gemini-3-flash", true)).toEqual(["none", "low", "medium", "high"])
+  })
+
+  it("respects a shorter direct ladder (3.1 Pro has no minimal tier)", () => {
+    expect(availableReasoningEfforts("gemini-3.1-pro", true)).toEqual(["low", "medium", "high"])
+  })
+
+  it("ignores the advanced flag on a model with no direct lane", () => {
+    const claude = availableReasoningEfforts("claude-sonnet-4.6")
+    expect(availableReasoningEfforts("claude-sonnet-4.6", true)).toEqual(claude)
+  })
+
+  it("clamps against the lane's ladder, not the other lane's", () => {
+    // `medium` is not on 3.6-flash's KIE ladder → clamps down to `low`.
+    expect(effectiveReasoningEffort("gemini-3.6-flash", "medium")).toBe("low")
+    // On the direct lane `medium` is a real level → survives.
+    expect(effectiveReasoningEffort("gemini-3.6-flash", "medium", true)).toBe("medium")
+  })
+
+  it("every directReasoningEfforts entry is a valid effort, ascending", () => {
+    for (const m of LLM_MODELS.filter((x) => x.directReasoningEfforts)) {
+      const levels = m.directReasoningEfforts!
+      for (const l of levels) expect(LLM_REASONING_EFFORTS, m.id).toContain(l)
+      const ranks = levels.map((l) => LLM_REASONING_EFFORTS.indexOf(l))
+      expect(ranks, `${m.id} must be ascending`).toEqual([...ranks].sort((a, b) => a - b))
+    }
+  })
+
+  it("only advanced-capable models declare a direct ladder", () => {
+    const bad = LLM_MODELS.filter((m) => m.directReasoningEfforts && !supportsAdvancedMode(m.id)).map((m) => m.id)
+    expect(bad).toEqual([])
+  })
+})

package/src/__tests__/video-analysis-catalog-sync.test.ts

@@ -0,0 +1,63 @@
+/**
+ * The model catalog hand-copies video-analysis credit values that already live
+ * in `VIDEO_ANALYSIS_BUCKET_CREDITS`. Nothing cross-checked the two, so a
+ * reprice could update the table (and the DB migration) while the catalog kept
+ * quoting the old numbers — and the catalog is what the model browser shows a
+ * user BEFORE they run anything.
+ *
+ * This is the guard that was missing.
+ */
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG } from "../model-catalog.js"
+import {
+  VIDEO_ANALYSIS_BUCKET_CREDITS,
+  VIDEO_ANALYSIS_DURATION_BUCKETS,
+  VIDEO_ANALYSIS_MAX_DURATION_SEC,
+} from "../video-analysis-pricing.js"
+
+/** Every `video-analysis:*` pricing row declared anywhere in the catalog. */
+const catalogRows = Object.values(MODEL_CATALOG)
+  .flatMap((m) => (m.pricing ?? []) as ReadonlyArray<{ identifier: string; credits: number }>)
+  .filter((r) => r.identifier.startsWith("video-analysis:"))
+
+describe("model catalog video-analysis pricing", () => {
+  it("declares at least one row (guard is actually wired to something)", () => {
+    expect(catalogRows.length).toBeGreaterThan(0)
+  })
+
+  it("every bucketed catalog row matches VIDEO_ANALYSIS_BUCKET_CREDITS exactly", () => {
+    const bucketed = catalogRows.filter((r) => /:\d+s$/.test(r.identifier))
+    expect(bucketed.length).toBeGreaterThan(0)
+    for (const row of bucketed) {
+      expect(
+        row.credits,
+        `catalog "${row.identifier}" = ${row.credits} but the table says ${VIDEO_ANALYSIS_BUCKET_CREDITS[row.identifier]}`,
+      ).toBe(VIDEO_ANALYSIS_BUCKET_CREDITS[row.identifier])
+    }
+  })
+
+  it("every bare (no-duration) catalog row equals its max-duration ceiling", () => {
+    // A bare id means "duration unknown", which the route prices at the ceiling.
+    const bare = catalogRows.filter((r) => !/:\d+s$/.test(r.identifier))
+    expect(bare.length).toBeGreaterThan(0)
+    for (const row of bare) {
+      const ceiling = VIDEO_ANALYSIS_BUCKET_CREDITS[`${row.identifier}:${VIDEO_ANALYSIS_MAX_DURATION_SEC}s`]
+      expect(ceiling, `no ceiling row for ${row.identifier}`).toBeDefined()
+      expect(row.credits, `catalog "${row.identifier}" must equal its ${VIDEO_ANALYSIS_MAX_DURATION_SEC}s ceiling`).toBe(ceiling)
+    }
+  })
+
+  it("catalog covers every bucket it claims a model supports", () => {
+    const byModel = new Map<string, Set<number>>()
+    for (const r of catalogRows) {
+      const m = /^video-analysis:(.+):(\d+)s$/.exec(r.identifier)
+      if (!m) continue
+      if (!byModel.has(m[1]!)) byModel.set(m[1]!, new Set())
+      byModel.get(m[1]!)!.add(Number(m[2]))
+    }
+    for (const [model, buckets] of byModel) {
+      expect([...buckets].sort((a, b) => a - b), `${model} bucket coverage`)
+        .toEqual([...VIDEO_ANALYSIS_DURATION_BUCKETS])
+    }
+  })
+})

package/src/__tests__/video-analysis-pricing.test.ts

@@ -113,10 +113,11 @@ describe("video-analysis-pricing", () => {
     }
   })
 
-  // Full drift-detection against the live $-formula lives in
-  // backend/src/lib/pricing/__tests__/video-analysis-cost.test.ts (this
-  // package cannot see the formula post-S5). This is a lightweight shape
-  // check that the precomputed table covers every legal id.
+  // Full drift-detection against the live $-formula lives in the PRIVATE
+  // plugin repo (src/plugins/video-analysis/__tests__/cost.test.ts) — the
+  // formula moved there in 2026-07 and the app-side test was deleted with it,
+  // so nothing in THIS repo can recompute these numbers. This is a lightweight
+  // shape check that the precomputed table covers every legal id.
   it("VIDEO_ANALYSIS_BUCKET_CREDITS has a positive-integer entry for every model × bucket id", () => {
     for (const model of VIDEO_ANALYSIS_LLM_MODELS) {
       for (const bucketSec of VIDEO_ANALYSIS_DURATION_BUCKETS) {

package/src/__tests__/video-analysis.test.ts

@@ -5,8 +5,11 @@ import {
   renderAnalyzedScene, isOversizedScene, aspectRatioFromDims,
   entitySlotSchema, analyzedSceneSchema,
   rewriteSceneBindings, dropUnknownBindings,
+  rewriteSpeakerSlots, dropUnknownSpeakers, mergeClipLook,
+  VIDEO_ANALYSIS_SPEED_EFFECTS, VIDEO_ANALYSIS_SHOT_ANGLES, VIDEO_ANALYSIS_FACELESS_ANGLES,
+  VIDEO_ANALYSIS_VISUAL_EFFECTS, VIDEO_ANALYSIS_TRANSITIONS,
   VIDEO_ANALYSIS_MAX_VARIATIONS, VIDEO_ANALYSIS_VARIATION_SLUGS, VIDEO_ANALYSIS_DEFAULT_VARIATION,
-  type EntitySlot,
+  type EntitySlot, type AudioLayer,
 } from "../video-analysis.js"
 
 const slot: EntitySlot = { slotId: "hero", label: "Protagonist", source: "wired-character", role: "person", description: "tan man, mustache, black tee" }
@@ -148,6 +151,203 @@ describe("binding rewrite helpers (merge consumes — spec §4)", () => {
   })
 })
 
+describe("speech attribution (speakerSlot)", () => {
+  const speech = (content: string, over: Partial<AudioLayer> = {}): AudioLayer => ({ mode: "speech", content, ...over })
+
+  it("rides on speech layers and survives a window round-trip", () => {
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, audio: [speech("As a kid…", { voice: "male, warm", speakerSlot: "hero" })] }],
+    })
+    expect(parsed.scenes[0]!.audio[0]!.speakerSlot).toBe("hero")
+  })
+
+  it("is NOT refined against mode — a mis-tagged music layer must not fail the whole roll", () => {
+    // The window schema IS the enforced decode grammar. Rejecting here would
+    // throw away every scene in a window over one stray field; the sanitizer
+    // below strips it instead.
+    expect(windowAnalysisSchema.safeParse({
+      slots: [slot],
+      scenes: [{ ...baseScene, audio: [{ mode: "music", content: "synth bed", speakerSlot: "hero" }] }],
+    }).success).toBe(true)
+  })
+
+  it("rewriteSpeakerSlots follows a slot through cross-window unification", () => {
+    // Slot unification renames the loser id and rewrites {slot:…} tokens and
+    // variation bindings; attribution has to move with them or it dangles.
+    const audio = [speech("hi", { speakerSlot: "man-2" }), speech("ho", { speakerSlot: "other" })]
+    expect(rewriteSpeakerSlots(audio, { "man-2": "hero" }).map((a) => a.speakerSlot)).toEqual(["hero", "other"])
+  })
+
+  it("rewriteSpeakerSlots is copy-on-write when no layer names a renamed slot", () => {
+    const audio = [speech("hi", { speakerSlot: "hero" }), { mode: "music" as const, content: "bed" }]
+    expect(rewriteSpeakerSlots(audio, { ghost: "other" })).toBe(audio)
+  })
+
+  it("dropUnknownSpeakers strips attribution to a slot that no longer exists", () => {
+    const r = dropUnknownSpeakers([speech("hi", { speakerSlot: "ghost" })], new Set(["hero"]))
+    expect(r.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(r.dropped).toEqual(["ghost"])
+  })
+
+  it("dropUnknownSpeakers strips attribution from music/sfx — nobody is speaking", () => {
+    const r = dropUnknownSpeakers(
+      [{ mode: "sfx", content: "door slam", speakerSlot: "hero" }],
+      new Set(["hero"]),
+    )
+    expect(r.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(r.dropped).toEqual(["hero"])
+  })
+
+  it("dropUnknownSpeakers keeps a valid speaker and every other layer field", () => {
+    const audio = [speech("As a kid…", { voice: "male, warm", speakerSlot: "hero" })]
+    const r = dropUnknownSpeakers(audio, new Set(["hero"]))
+    expect(r.audio).toBe(audio)          // copy-on-write: untouched input returned as-is
+    expect(r.dropped).toEqual([])
+  })
+
+  it("attribution alone must NOT keep a slot alive — that is the phantom narrator", () => {
+    // A slot referenced only as a speaker is a voice with no body (doctrine §5).
+    // deriveSlotRefs reads {slot:…} tokens from `visual` ONLY, so an
+    // attribution-only slot stays invisible to the reference sweep and gets
+    // dropped — then dropUnknownSpeakers removes the dangling attribution.
+    expect(deriveSlotRefs("a lunar plain, no one in frame")).toEqual([])
+    const r = dropUnknownSpeakers([speech("that's me!", { speakerSlot: "creator" })], new Set())
+    expect(r.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(r.dropped).toEqual(["creator"])
+  })
+})
+
+describe("cinematography fields (angle / speed / onScreenText / look)", () => {
+  it("carries angle and speed as closed enums through a window round-trip", () => {
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, angle: "low", speed: "slow-motion", onScreenText: "ACT I" }],
+    })
+    expect(parsed.scenes[0]).toMatchObject({ angle: "low", speed: "slow-motion", onScreenText: "ACT I" })
+  })
+
+  it("supports the RELATIONAL viewpoints, so shotType keeps the size", () => {
+    // These were conventions inside the `shotType` list, competing with the
+    // sizes for one slot — so an over-the-shoulder MEDIUM had to throw one away.
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, shotType: "Medium", angle: "over-the-shoulder" }],
+    })
+    expect(parsed.scenes[0]).toMatchObject({ shotType: "Medium", angle: "over-the-shoulder" })
+    for (const a of ["pov", "profile", "from-behind"]) {
+      expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, angle: a }] }).success).toBe(true)
+    }
+  })
+
+  it("carries picture EFFECTS as an array — a shot can be grainy and vignetted", () => {
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot], scenes: [{ ...baseScene, effects: ["grain", "vignette"] }],
+    })
+    expect(parsed.scenes[0]!.effects).toEqual(["grain", "vignette"])
+  })
+
+  it("keeps compositing OUT of effects — that is where the phantom slot came from", () => {
+    // A field for "there is an inset of a person here" would hand a legitimate
+    // home to the invented `{slot:creator} overlay talking to camera`. An effect
+    // is verifiable in the pixels; a claim about who is inset is not.
+    for (const bad of ["picture-in-picture", "split-screen", "overlay"]) {
+      expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, effects: [bad] }] }).success).toBe(false)
+    }
+  })
+
+  it("transitions distinguish DISSOLVE from FADE — they look nothing alike", () => {
+    // Collapsed onto `fade` before this, so a cross-dissolve was rendered as a
+    // fade through black.
+    expect(VIDEO_ANALYSIS_TRANSITIONS).toContain("dissolve")
+    for (const t of VIDEO_ANALYSIS_TRANSITIONS) {
+      expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, transitionOut: t }] }).success).toBe(true)
+    }
+  })
+
+  it("effects and transitions are NOT the same axis", () => {
+    // `dissolve`/`fade` are edits BETWEEN shots; blur/pixelate are on the picture.
+    for (const t of ["dissolve", "fade", "wipe", "cut"]) {
+      expect(VIDEO_ANALYSIS_VISUAL_EFFECTS).not.toContain(t)
+    }
+    for (const e of VIDEO_ANALYSIS_VISUAL_EFFECTS) {
+      expect(VIDEO_ANALYSIS_TRANSITIONS).not.toContain(e as never)
+    }
+  })
+
+  it("marks the viewpoints where no face is visible — auto-cast reads this", () => {
+    // A reference frame shot from behind cannot cast a face, however well framed.
+    expect([...VIDEO_ANALYSIS_FACELESS_ANGLES].sort()).toEqual(["from-behind", "over-the-shoulder"])
+    for (const a of VIDEO_ANALYSIS_FACELESS_ANGLES) {
+      expect(VIDEO_ANALYSIS_SHOT_ANGLES).toContain(a)   // never a stale literal
+    }
+  })
+
+  it("rejects free-text angle — improvising it is the failure being fixed", () => {
+    // The shipped defect: `"camera": "low angle static"`, because angle had no
+    // field. A free-text `angle` would just move the improvisation.
+    expect(windowAnalysisSchema.safeParse({
+      slots: [slot], scenes: [{ ...baseScene, angle: "low angle static" }],
+    }).success).toBe(false)
+  })
+
+  it("has NO 'normal' speed member — absence is normal, so there is one way to say it", () => {
+    expect(VIDEO_ANALYSIS_SPEED_EFFECTS).not.toContain("normal")
+    expect(windowAnalysisSchema.safeParse({
+      slots: [slot], scenes: [{ ...baseScene, speed: "normal" }],
+    }).success).toBe(false)
+    // …and omitting it is valid.
+    expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [baseScene] }).success).toBe(true)
+  })
+
+  it("keeps every new field OPTIONAL so an older producer still validates", () => {
+    const parsed = windowAnalysisSchema.parse({ slots: [slot], scenes: [baseScene] })
+    expect(parsed.scenes[0]).not.toHaveProperty("angle")
+    expect(parsed.scenes[0]).not.toHaveProperty("speed")
+    expect(parsed.scenes[0]).not.toHaveProperty("onScreenText")
+    expect(parsed).not.toHaveProperty("look")
+  })
+
+  it("the new scene fields reach the RESULT schema, not just the window one", () => {
+    // analyzedSceneSchema extends windowSceneBase — this pins that it stays that
+    // way, since a field the merged result drops is invisible to every consumer.
+    const scene = { ...baseScene, sceneNumber: 1, visualResolved: "x", slotRefs: [], angle: "dutch", speed: "freeze", onScreenText: "THE END" }
+    expect(analyzedSceneSchema.parse(scene)).toMatchObject({ angle: "dutch", speed: "freeze", onScreenText: "THE END" })
+  })
+
+  it("look is a SIBLING of meta, not inside it — meta is measured, look is read", () => {
+    const r = videoAnalysisResultSchema.parse({
+      meta: { durationSec: 10, width: 1920, height: 1080, aspectRatio: "16:9" },
+      look: { grade: "muted teal", format: "anamorphic digital", genre: "cinematic trailer" },
+      slots: [],
+      scenes: [{ ...baseScene, sceneNumber: 1, visualResolved: "x", slotRefs: [] }],
+    })
+    expect(r.look?.format).toBe("anamorphic digital")
+    expect(r.meta).not.toHaveProperty("look")
+  })
+})
+
+describe("mergeClipLook", () => {
+  it("takes the first non-empty value PER FIELD, not the first window wholesale", () => {
+    // Windows see different footage: one may read the grade while only a later
+    // one contains the shot that reveals the format.
+    expect(mergeClipLook([
+      { grade: "muted teal" },
+      { grade: "warm", format: "16mm film grain" },
+      { lens: "anamorphic flare" },
+    ])).toEqual({ grade: "muted teal", format: "16mm film grain", lens: "anamorphic flare" })
+  })
+
+  it("ignores blank strings and trims what it keeps", () => {
+    expect(mergeClipLook([{ grade: "   " }, { grade: "  crushed blacks  " }])).toEqual({ grade: "crushed blacks" })
+  })
+
+  it("returns undefined when nothing was read — never an empty object", () => {
+    expect(mergeClipLook([])).toBeUndefined()
+    expect(mergeClipLook([undefined, {}, { grade: "" }])).toBeUndefined()
+  })
+})
+
 describe("misc", () => {
   it("isOversizedScene flags > 8s only", () => {
     expect(isOversizedScene(0, 8)).toBe(false)

package/src/index.ts

@@ -277,6 +277,9 @@ export {
   getLlmModalityCaps,
   buildLlmCreditIdentifier,
   resolveLlmCreditId,
+  supportsAdvancedMode,
+  availableReasoningEfforts,
+  ADVANCED_MODE_UNAVAILABLE_REASON,
   motionGraphicsFeature,
   effectiveReasoningEffort,
   type LlmTier,