@nodaro/shared 1.21.0 → 1.23.0

package/src/llm-models.ts

@@ -51,8 +51,44 @@ export interface LlmModelDef {
   structuredOutputMode?: "anthropic-tool" | "kie-response-format" | "responses-json-schema"
   /** If set, fallback to direct Anthropic SDK with this model ID when KIE.ai fails */
   directFallbackModel?: string
+  /**
+   * Google Gemini API model id for the DIRECT lane (generativelanguage, keyed
+   * by `GEMINI_API_KEY`) — the Google-side twin of `directFallbackModel`.
+   * Presence declares "this model CAN be served straight from Google"; absence
+   * pins it to KIE forever. Stated, never derived: Google carries `-preview`
+   * suffixes on unreleased models, so the id routinely differs from both `id`
+   * and `kieSlugOrModel` (`gemini-3.1-pro` → `gemini-3.1-pro-preview`).
+   */
+  directGeminiModel?: string
+  /**
+   * Try the direct-vendor lane FIRST for this model, with KIE as the failure
+   * fallback. Absent (while `directGeminiModel` is set) = KIE first, direct
+   * only when KIE fails.
+   *
+   * This is a per-model COST decision, not just a routing one: the two lanes
+   * bill the same model at materially different unit rates, so a model that
+   * backs a high-volume default (see `LLM_FEATURE_DEFAULTS`) is usually better
+   * left on whichever lane is cheaper. The rate tables for both lanes live in
+   * `backend/src/lib/pricing/llm-cost.ts` — deliberately not in this package,
+   * which is published to npm.
+   *
+   * Mutually exclusive with `preferKie` — the Claude-side half of the same
+   * idea. Guarded by a registry test so the two can't both be set.
+   */
+  preferDirect?: true
   /** Effort levels this model accepts (ascending). Absent/empty = no effort lever, picker hidden. */
   reasoningEfforts?: readonly LlmReasoningEffort[]
+  /**
+   * Effort levels available on the DIRECT lane, when the vendor's own API
+   * accepts more than the aggregator does. Absent = the direct lane offers the
+   * same set as `reasoningEfforts`.
+   *
+   * This exists because `reasoningEfforts` has to stay at the KIE-safe
+   * intersection — sending a level KIE rejects is a hard failure — while the
+   * vendor API accepts the full ladder. Unlocking those extra levels is one of
+   * the concrete things Advanced mode buys.
+   */
+  directReasoningEfforts?: readonly LlmReasoningEffort[]
   /** false = model rejects `temperature` (Claude 5-era, GPT-5.6). Absent = accepts. */
   supportsTemperature?: false
   /** Claude-only: KIE is the preferred routing, direct Anthropic the fallback. */
@@ -85,6 +121,13 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     structuredOutputMode: "kie-response-format",
     supportsImages: true,
     maxOutputTokens: 8192,
+    // KIE-first: no `preferDirect` — direct is the reliability fallback only.
+    // (Per-lane rates are deliberately NOT in this published package; see
+    // backend/src/lib/pricing/llm-cost.ts.)
+    directGeminiModel: "gemini-3-flash-preview",
+    // No `reasoningEfforts` at all on the KIE lane, but the vendor API accepts
+    // the full minimal→high ladder (`none` maps to Google's `minimal`).
+    directReasoningEfforts: ["none", "low", "medium", "high"],
   },
   {
     id: "gemini-3.6-flash",
@@ -102,7 +145,19 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     maxOutputTokens: 8192,
     // KIE's 3.6 endpoint accepts `reasoning_effort: low | high` (thinking
     // level) — exactly the chat-completions wire mapping deriveParams sends.
+    // Google's own API additionally accepts `minimal` and `medium` on this
+    // model; the set stays at the KIE-safe intersection because ONE field
+    // feeds both lanes and this model is KIE-first. Widen it only if/when
+    // `preferDirect` is set here.
     reasoningEfforts: ["low", "high"],
+    // Google's own API additionally accepts `minimal` and `medium` here —
+    // live-verified 2026-07-28. Advanced mode unlocks them.
+    directReasoningEfforts: ["none", "low", "medium", "high"],
+    // KIE-first: this model backs 5 of the LLM_FEATURE_DEFAULTS plus the
+    // video-analysis fast tier, so it carries the highest call volume of any
+    // Gemini entry — the lane with the lower unit cost wins by default and
+    // direct is the reliability fallback only.
+    directGeminiModel: "gemini-3.6-flash",
   },
   {
     id: "claude-haiku-4.5",
@@ -153,6 +208,18 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     structuredOutputMode: "kie-response-format",
     supportsImages: true,
     maxOutputTokens: 16384,
+    directGeminiModel: "gemini-3.1-pro-preview",
+    // Google documents low/medium/high for 3.1 Pro — no `minimal` tier, so
+    // this ladder is deliberately shorter than the flash models'.
+    directReasoningEfforts: ["low", "medium", "high"],
+    // The ONE Gemini model routed direct-first. It is the premium/low-volume
+    // tier (video-analysis `pro`, no LLM_FEATURE_DEFAULTS entry), so the ~4×
+    // list-price premium lands on the smallest call volume — and it is where
+    // the direct lane's capability wins actually matter: real `thinkingLevel`
+    // control, native media ingestion, and a `responseJsonSchema` that honours
+    // `additionalProperties` (KIE's `response_format` silently DROPS
+    // record/map-shaped fields — see the z.record rule in backend/CLAUDE.md).
+    preferDirect: true,
   },
   {
     id: "claude-opus-4.7",
@@ -425,21 +492,45 @@ export function getLlmModel(id: string): LlmModelDef | undefined {
     if (aliased) return aliased
   }
   // Last resort: provider slugs double as historical aliases (e.g. the
-  // dated Anthropic slugs) — accept any model whose slug matches exactly.
-  return LLM_MODELS.find((m) => m.kieSlugOrModel === id || m.directFallbackModel === id)
+  // dated Anthropic slugs, the `-preview`-suffixed Google ids) — accept any
+  // model whose slug matches exactly, on either lane.
+  return LLM_MODELS.find(
+    (m) => m.kieSlugOrModel === id || m.directFallbackModel === id || m.directGeminiModel === id,
+  )
 }
 
 export function getLlmTier(id: string): LlmTier {
   return getLlmModel(id)?.tier ?? "standard"
 }
 
+/**
+ * Effort levels this model actually accepts on the lane it will be served on.
+ *
+ * The two lanes do NOT offer the same ladder: the aggregator accepts a narrower
+ * set than the vendor's own API does, which is one of the concrete things
+ * Advanced mode buys. Kept as one lookup so the UI picker and the wire-side
+ * clamp can never disagree about what's selectable.
+ */
+export function availableReasoningEfforts(
+  modelId: string | undefined,
+  advanced = false,
+): readonly LlmReasoningEffort[] {
+  const model = getLlmModel(modelId ?? "")
+  if (!model) return []
+  if (advanced && supportsAdvancedMode(modelId)) {
+    return model.directReasoningEfforts ?? model.reasoningEfforts ?? []
+  }
+  return model.reasoningEfforts ?? []
+}
+
 /** Highest level the model supports that is ≤ the requested level; undefined = treat as Auto. */
 export function effectiveReasoningEffort(
   modelId: string | undefined,
   requested?: string,
+  advanced = false,
 ): LlmReasoningEffort | undefined {
   if (!requested || !(requested in EFFORT_RANK)) return undefined
-  const levels = getLlmModel(modelId ?? "")?.reasoningEfforts
+  const levels = availableReasoningEfforts(modelId, advanced)
   if (!levels || levels.length === 0) return undefined
   const req = requested as LlmReasoningEffort
   let best: LlmReasoningEffort | undefined
@@ -459,25 +550,107 @@ export function effectiveReasoningEffort(
  * premium stays premium). `high` is the Claude-family server default and
  * never bumps.
  */
-export function buildLlmCreditIdentifier(feature: string, modelId?: string, reasoningEffort?: string): string {
+
+/**
+ * The sampling defaults each LLM feature's route sends when Advanced mode is
+ * OFF — and therefore the values its Advanced panel must seed the sliders with.
+ *
+ * SINGLE SOURCE because the two used to disagree: the routes hardcoded their
+ * own literals while the toggle fell back to 0.7/2048, so the panel displayed
+ * a temperature the run never used, and one arrow-key press on 3D Title's Max
+ * Tokens silently cut its budget from 3072 to 2048 on a node that emits
+ * structured JSON.
+ *
+ * `structuredOutput` marks the features whose prompt asks the model for JSON —
+ * a high temperature measurably degrades schema adherence there, so the panel
+ * warns. Absent `temperature` means the route sends none (vendor default).
+ */
+export interface LlmRouteDefaults {
+  temperature?: number
+  maxTokens?: number
+  structuredOutput?: true
+}
+
+export const LLM_ROUTE_DEFAULTS: Record<string, LlmRouteDefaults> = {
+  "llm-chat":                { temperature: 0.7,  maxTokens: 8192 },
+  "ai-writer":               { temperature: 0.7,  maxTokens: 8192 },
+  "prompt-helper":           { temperature: 0.7,  maxTokens: 8192, structuredOutput: true },
+  "generate-script":         { maxTokens: 16384, structuredOutput: true },
+  "qa-check":                { maxTokens: 1024,  structuredOutput: true },
+  "image-critic":            { maxTokens: 1024,  structuredOutput: true },
+  "image-to-text":           { maxTokens: 1024 },
+  "describe-to-picker":      { structuredOutput: true },
+  "scene-graph-ai":          { temperature: 0.3,  maxTokens: 4096, structuredOutput: true },
+  "after-effects":           { temperature: 0.3,  maxTokens: 2048, structuredOutput: true },
+  "lottie-overlay":          { temperature: 0.3,  maxTokens: 2048, structuredOutput: true },
+  "motion-graphics":         { temperature: 0.3,  maxTokens: 2048, structuredOutput: true },
+  "motion-graphics-lottie":  { temperature: 0.3,  maxTokens: 8192, structuredOutput: true },
+  "3d-title":                { temperature: 0.4,  maxTokens: 3072, structuredOutput: true },
+}
+
+/** Route defaults for a feature; `{}` for an unknown one. */
+export function llmRouteDefaults(feature: string | undefined): LlmRouteDefaults {
+  return (feature && LLM_ROUTE_DEFAULTS[feature]) || {}
+}
+
+/** One step up the economy → standard → premium ladder. Premium is the ceiling. */
+function bumpTier(tier: LlmTier): LlmTier {
+  if (tier === "economy") return "standard"
+  if (tier === "standard") return "premium"
+  return tier
+}
+
+/**
+ * Can this model be run in Advanced mode?
+ *
+ * Advanced mode pins the call to the vendor's own API, which is the only lane
+ * where sampling levers (`temperature`, `maxTokens`) and the full effort range
+ * actually take effect. Capability-derived from the registry — a model without
+ * a direct lane simply cannot offer it, so UI and routes both gate on this
+ * rather than on a hand-maintained model list.
+ */
+export function supportsAdvancedMode(modelId: string | undefined): boolean {
+  return Boolean(modelId && getLlmModel(modelId)?.directGeminiModel)
+}
+
+/** User-facing reason a model can't offer Advanced mode. Single-sourced so the
+ *  config panel's disabled hint and the route's 400 say the same thing. */
+export const ADVANCED_MODE_UNAVAILABLE_REASON =
+  "Advanced mode is available on Gemini models — switch the model to enable it."
+
+export function buildLlmCreditIdentifier(
+  feature: string,
+  modelId?: string,
+  reasoningEffort?: string,
+  advancedMode?: boolean,
+): string {
   if (!modelId) return feature
   let tier = getLlmTier(modelId)
   const eff = effectiveReasoningEffort(modelId, reasoningEffort)
-  if (eff !== undefined && EFFORT_TIER_BUMP.has(eff)) {
-    if (tier === "economy") tier = "standard"
-    else if (tier === "standard") tier = "premium"
-  }
+  if (eff !== undefined && EFFORT_TIER_BUMP.has(eff)) tier = bumpTier(tier)
+  // Advanced mode routes to the vendor's own API, which bills materially more
+  // per token than the aggregator. It bumps INDEPENDENTLY of the effort bump —
+  // the two are separate cost levers and genuinely stack, so a max-effort
+  // advanced economy call lands at premium. The bump is ignored on a model that
+  // can't run advanced at all, so a stale flag never inflates a bill.
+  if (advancedMode && supportsAdvancedMode(modelId)) tier = bumpTier(tier)
   if (tier === "standard") return feature
   return `${feature}:${tier}`
 }
 
 /**
- * Resolve llmModel (+ reasoningEffort) from raw body for creditGuard preHandler
- * (before Zod parsing). Returns the credit identifier for the given feature.
+ * Resolve llmModel (+ reasoningEffort, advancedMode) from raw body for the
+ * creditGuard preHandler (before Zod parsing). Returns the credit identifier
+ * for the given feature.
  */
 export function resolveLlmCreditId(feature: string, body: unknown): string {
   const b = body as Record<string, unknown> | undefined
-  return buildLlmCreditIdentifier(feature, b?.llmModel as string | undefined, b?.reasoningEffort as string | undefined)
+  return buildLlmCreditIdentifier(
+    feature,
+    b?.llmModel as string | undefined,
+    b?.reasoningEffort as string | undefined,
+    b?.advancedMode === true,
+  )
 }
 
 /** Models capable of video-analysis: capability-derived, never hand-listed (route-enum-sync convention). */

package/src/model-catalog.ts

@@ -1815,11 +1815,11 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     description: "Legacy fast-tier analysis model (pre-2026-07). Kept so stored raw-model configs keep running and keep pricing under their own identifier; new fast-tier runs use the current fast model.",
     useCases: ["video-analysis", "shot-list", "fast"],
     pricing: [
-      { identifier: "video-analysis:gemini-3-flash", credits: 9, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3-flash:60s", credits: 2 },
-      { identifier: "video-analysis:gemini-3-flash:180s", credits: 3 },
-      { identifier: "video-analysis:gemini-3-flash:360s", credits: 6 },
-      { identifier: "video-analysis:gemini-3-flash:600s", credits: 9, note: "10-min ceiling" },
+      { identifier: "video-analysis:gemini-3-flash", credits: 112, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:gemini-3-flash:60s", credits: 21 },
+      { identifier: "video-analysis:gemini-3-flash:180s", credits: 24 },
+      { identifier: "video-analysis:gemini-3-flash:360s", credits: 68 },
+      { identifier: "video-analysis:gemini-3-flash:600s", credits: 112, note: "10-min ceiling" },
     ],
   },
   "gemini-3.6-flash-video-analysis": {
@@ -1832,11 +1832,11 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     description: "Analyze a video into a structured shot list (scenes, camera, audio) — fast, economy tier. Billed per duration bucket.",
     useCases: ["video-analysis", "shot-list", "fast"],
     pricing: [
-      { identifier: "video-analysis:gemini-3.6-flash", credits: 25, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3.6-flash:60s", credits: 5 },
-      { identifier: "video-analysis:gemini-3.6-flash:180s", credits: 6 },
-      { identifier: "video-analysis:gemini-3.6-flash:360s", credits: 15 },
-      { identifier: "video-analysis:gemini-3.6-flash:600s", credits: 25, note: "10-min ceiling" },
+      { identifier: "video-analysis:gemini-3.6-flash", credits: 291, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:gemini-3.6-flash:60s", credits: 54 },
+      { identifier: "video-analysis:gemini-3.6-flash:180s", credits: 63 },
+      { identifier: "video-analysis:gemini-3.6-flash:360s", credits: 175 },
+      { identifier: "video-analysis:gemini-3.6-flash:600s", credits: 291, note: "10-min ceiling" },
     ],
   },
   "gemini-3.1-pro-video-analysis": {
@@ -1849,11 +1849,11 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     description: "Analyze a video into a structured shot list (scenes, camera, audio) — higher-fidelity, default tier. Billed per duration bucket.",
     useCases: ["video-analysis", "shot-list", "cinematic"],
     pricing: [
-      { identifier: "video-analysis:gemini-3.1-pro", credits: 33, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3.1-pro:60s", credits: 6 },
-      { identifier: "video-analysis:gemini-3.1-pro:180s", credits: 8 },
-      { identifier: "video-analysis:gemini-3.1-pro:360s", credits: 20 },
-      { identifier: "video-analysis:gemini-3.1-pro:600s", credits: 33, note: "10-min ceiling" },
+      { identifier: "video-analysis:gemini-3.1-pro", credits: 448, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:gemini-3.1-pro:60s", credits: 84 },
+      { identifier: "video-analysis:gemini-3.1-pro:180s", credits: 96 },
+      { identifier: "video-analysis:gemini-3.1-pro:360s", credits: 269 },
+      { identifier: "video-analysis:gemini-3.1-pro:600s", credits: 448, note: "10-min ceiling" },
     ],
   },
   // Both mixed tiers are variants of the same advanced multi-engine analysis
@@ -1869,11 +1869,11 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     description: "Our most advanced analysis tier — multiple analysis engines combined into one result for maximum completeness and accuracy. Billed per duration bucket.",
     useCases: ["video-analysis", "shot-list", "premium", "most-complete"],
     pricing: [
-      { identifier: "video-analysis:mixed", credits: 57, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:mixed:60s", credits: 10 },
-      { identifier: "video-analysis:mixed:180s", credits: 13 },
-      { identifier: "video-analysis:mixed:360s", credits: 35 },
-      { identifier: "video-analysis:mixed:600s", credits: 57, note: "10-min ceiling" },
+      { identifier: "video-analysis:mixed", credits: 739, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:mixed:60s", credits: 137 },
+      { identifier: "video-analysis:mixed:180s", credits: 158 },
+      { identifier: "video-analysis:mixed:360s", credits: 443 },
+      { identifier: "video-analysis:mixed:600s", credits: 739, note: "10-min ceiling" },
     ],
   },
 }

package/src/video-analysis-pricing.ts

@@ -24,8 +24,11 @@
  * `VIDEO_CLIP_CREDITS` uses in `film-pricing.ts`. It is what the frontend's
  * client-side cost preview (`estimateNodeCredits` in
  * workflow-editor/types.ts) reads instead of calling the formula directly.
- * A backend test (`video-analysis-cost.test.ts`) cross-checks this table
- * against the live formula so it can't silently drift.
+ * The formula's own test in `@nodaroai/cloud-plugins`
+ * (`src/plugins/video-analysis/__tests__/cost.test.ts`) cross-checks this table
+ * against it and fails on drift. There is deliberately NO app-side formula to
+ * check against — it was moved private in 2026-07 and the old backend test
+ * went with it.
  */
 
 export const VIDEO_ANALYSIS_DURATION_BUCKETS = [60, 180, 360, 600] as const
@@ -47,27 +50,27 @@ export const VIDEO_ANALYSIS_WINDOW = { LEN: WINDOW_LEN, STRIDE: WINDOW_STRIDE, O
  */
 export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
   // Legacy fast-tier model (pre-2026-07) — kept for stored raw-id configs.
-  "video-analysis:gemini-3-flash:60s": 2,
-  "video-analysis:gemini-3-flash:180s": 3,
-  "video-analysis:gemini-3-flash:360s": 6,
-  "video-analysis:gemini-3-flash:600s": 9,
+  "video-analysis:gemini-3-flash:60s": 21,
+  "video-analysis:gemini-3-flash:180s": 24,
+  "video-analysis:gemini-3-flash:360s": 68,
+  "video-analysis:gemini-3-flash:600s": 112,
   // Current fast tier — regenerated from the private formula for its backing
   // model; higher than the legacy fast schedule but still ≤ pro per bucket.
-  "video-analysis:gemini-3.6-flash:60s": 5,
-  "video-analysis:gemini-3.6-flash:180s": 6,
-  "video-analysis:gemini-3.6-flash:360s": 15,
-  "video-analysis:gemini-3.6-flash:600s": 25,
-  "video-analysis:gemini-3.1-pro:60s": 6,
-  "video-analysis:gemini-3.1-pro:180s": 8,
-  "video-analysis:gemini-3.1-pro:360s": 20,
-  "video-analysis:gemini-3.1-pro:600s": 33,
+  "video-analysis:gemini-3.6-flash:60s": 54,
+  "video-analysis:gemini-3.6-flash:180s": 63,
+  "video-analysis:gemini-3.6-flash:360s": 175,
+  "video-analysis:gemini-3.6-flash:600s": 291,
+  "video-analysis:gemini-3.1-pro:60s": 84,
+  "video-analysis:gemini-3.1-pro:180s": 96,
+  "video-analysis:gemini-3.1-pro:360s": 269,
+  "video-analysis:gemini-3.1-pro:600s": 448,
   // Mixed tiers (`mixed` + `mixed-fast`) share ONE credit family — they are
   // variants of the same engine plan (plan internals live in the private
   // analysis plugin). Admin-tunable via model_pricing like every other row.
-  "video-analysis:mixed:60s": 10,
-  "video-analysis:mixed:180s": 13,
-  "video-analysis:mixed:360s": 35,
-  "video-analysis:mixed:600s": 57,
+  "video-analysis:mixed:60s": 137,
+  "video-analysis:mixed:180s": 158,
+  "video-analysis:mixed:360s": 443,
+  "video-analysis:mixed:600s": 739,
 }
 
 /**

package/src/video-analysis.ts

@@ -20,6 +20,148 @@
 import { z } from "zod"
 
 export const VIDEO_ANALYSIS_MAX_SCENE_SEC = 8
+
+/**
+ * Camera VIEWPOINT — where the camera is relative to the subject. The axis
+ * `shotType` does not carry, and the one the analyzer had been improvising.
+ *
+ * Two failures this fixes, both from real jobs:
+ *
+ *  1. `shotType` is framing SIZE (Wide … Extreme Close-Up), so a true angle had
+ *     nowhere to go and landed in the MOVEMENT field instead:
+ *     `"camera": "low angle static"`. That loses the angle to anything reading
+ *     `camera` and pollutes the movement vocabulary.
+ *  2. The relational viewpoints — `Over-the-Shoulder`, `POV` — were conventions
+ *     inside the `shotType` list, competing with the sizes for one slot. So an
+ *     over-the-shoulder MEDIUM had to pick one and threw the other away. They
+ *     belong here, leaving `shotType` free to state the size: an OTS medium is
+ *     `shotType: "Medium"` + `angle: "over-the-shoulder"`, which is strictly more
+ *     than either field could carry alone.
+ *
+ * A closed enum rather than free text precisely because improvisation is the
+ * failure being fixed. Absent means EYE-LEVEL — the overwhelming default, so
+ * omitting it costs nothing on most shots (the same "absence is the default"
+ * shape as `transitionOut` and appearance variations).
+ *
+ * `from-behind` and `over-the-shoulder` also carry real meaning downstream: a
+ * face is not visible in either, which is what auto-cast needs to know before
+ * choosing one as an identity reference.
+ */
+export const VIDEO_ANALYSIS_SHOT_ANGLES = [
+  // Vertical placement and roll — the classical "angles".
+  "eye-level", "low", "high", "overhead", "worms-eye", "dutch",
+  // Relational viewpoints — where the camera sits with respect to the subject.
+  "over-the-shoulder", "pov", "profile", "from-behind",
+] as const
+export type VideoAnalysisShotAngle = (typeof VIDEO_ANALYSIS_SHOT_ANGLES)[number]
+
+/** Viewpoints in which the subject's FACE is not visible — so a frame shot this
+ *  way is a poor identity reference however good its framing otherwise is. */
+export const VIDEO_ANALYSIS_FACELESS_ANGLES: ReadonlySet<string> = new Set(["over-the-shoulder", "from-behind"])
+
+/**
+ * Effects applied to the PICTURE of a shot. An array — a shot can be grainy and
+ * vignetted at once — and absent when the image is clean, which is most shots.
+ *
+ * Scoped deliberately to things done to the IMAGE, and NOT to compositing that
+ * asserts what is in the shot (picture-in-picture, split screen). That line
+ * matters: a real job invented `{slot:creator} overlay talking to camera` across
+ * nine scenes for a man who is never seen, so a field for "there is an inset of a
+ * person here" would hand that fabrication a legitimate home. An effect is
+ * verifiable in the pixels; a claim about who is inset is not.
+ *
+ * `dissolve` and `fade` are NOT here either — they are edits BETWEEN shots and
+ * belong to `transitionOut`.
+ */
+export const VIDEO_ANALYSIS_VISUAL_EFFECTS = [
+  "blur", "pixelate", "glitch", "grain", "vignette", "flash", "distortion", "double-exposure",
+] as const
+export type VideoAnalysisVisualEffect = (typeof VIDEO_ANALYSIS_VISUAL_EFFECTS)[number]
+
+/**
+ * Visible edit INTO the next shot.
+ *
+ * `dissolve` (a cross-fade from one image to the other) is distinct from `fade`
+ * (through black or white). Collapsing both onto `fade` — as this enum did — makes
+ * a recreation render the wrong edit, and the two look nothing alike.
+ */
+export const VIDEO_ANALYSIS_TRANSITIONS = ["cut", "fade", "dissolve", "wipe", "whip"] as const
+export type VideoAnalysisTransition = (typeof VIDEO_ANALYSIS_TRANSITIONS)[number]
+
+/**
+ * Time manipulation — slow motion, ramps, timelapse, freeze, reverse.
+ *
+ * Previously unrepresentable anywhere in the schema, so a recreation rendered
+ * every shot at normal speed no matter what the footage did. It is a first-class
+ * lever in every video model and a real editing decision in most action footage.
+ *
+ * `"normal"` is deliberately NOT a member: absence is normal speed, so there is
+ * exactly one way to say "nothing unusual here" and the field costs nothing on
+ * the majority of shots.
+ */
+export const VIDEO_ANALYSIS_SPEED_EFFECTS = ["slow-motion", "ramp-in", "ramp-out", "timelapse", "freeze", "reverse"] as const
+export type VideoAnalysisSpeedEffect = (typeof VIDEO_ANALYSIS_SPEED_EFFECTS)[number]
+
+/**
+ * The CLIP-LEVEL look — one source of truth for the properties that belong to
+ * the whole piece rather than any one shot.
+ *
+ * Colour grade, camera format and lens character were previously only ever prose
+ * inside each scene's `visual`, which meant a 43-scene analysis re-decided the
+ * grade forty-three independent times with nothing holding them consistent. That
+ * is the same drift problem entity slots solve for people: state it once, apply it
+ * everywhere. A recreation reads this alongside every scene.
+ *
+ * Every field optional — an analyzer that cannot read the format should say
+ * nothing rather than guess, and a per-scene deviation still belongs in that
+ * scene's `visual` prose.
+ */
+export const clipLookSchema = z.object({
+  /**
+   * The rendering MEDIUM — "live-action photoreal", "2D anime", "stop-motion
+   * claymation", "3D render", "oil painting", "pixel art".
+   *
+   * The most consequential field in this object, and orthogonal to every other
+   * one: two shots with identical grade, lens, lighting and framing still look
+   * nothing alike when one is live action and the other is an oil painting. Get
+   * this wrong and a recreation renders the whole piece in the wrong medium,
+   * which no amount of correct grade or lighting can rescue.
+   *
+   * Mirrors the product's Style picker, whose catalog defines exactly this axis
+   * and states its independence from lighting, colour-look, atmosphere and lens.
+   * A clip that genuinely changes medium partway (live action with an animated
+   * insert) states the deviation in that scene's `visual`, as with `lighting`.
+   */
+  style: z.string().optional(),
+  /** Colour grade / palette — "muted teal-and-orange, crushed blacks". */
+  grade: z.string().optional(),
+  /** Camera or film FORMAT and stock — "anamorphic digital", "16mm film grain". */
+  format: z.string().optional(),
+  /** Lens character — "wide-angle, shallow depth of field throughout". */
+  lens: z.string().optional(),
+  /** Overall lighting style — "hard single-source daylight, deep shadow". */
+  lighting: z.string().optional(),
+  /** What KIND of piece this is — "cinematic trailer", "talking-head vlog". */
+  genre: z.string().optional(),
+  /**
+   * The visual INFLUENCE the piece clearly evokes — a cinematographer, director,
+   * photographer or named aesthetic ("shot like Deakins", "Wes Anderson
+   * symmetry", "80s Kodachrome editorial").
+   *
+   * The highest-leverage field here by a distance: a couple of words transfer a
+   * whole aesthetic that would otherwise take a paragraph of grade, lens and
+   * lighting prose to approximate — which is exactly why the product already
+   * exposes it as a curated picker ("Photographer / Artist") whose catalog ships
+   * `in the style of …` prompt hints. The analyzer had no way to read it back.
+   *
+   * Deliberately conservative: OMIT unless the footage genuinely evokes a
+   * well-known, nameable style. A confident misattribution is worse than silence,
+   * because it drags an entire wrong aesthetic into every regenerated shot — so
+   * describing the look in `grade`/`lighting` always beats guessing a name.
+   */
+  influence: z.string().optional(),
+})
+export type ClipLook = z.infer<typeof clipLookSchema>
 export const VIDEO_ANALYSIS_ENTITY_SOURCES = ["wired-character", "wired-object", "wired-location", "wired-creature"] as const
 export type VideoAnalysisEntitySource = (typeof VIDEO_ANALYSIS_ENTITY_SOURCES)[number]
 /** Matches {slot:<id>} tokens. Distinct from NODE_REF_PATTERN / {image:N} grammars. */
@@ -108,8 +250,27 @@ const windowSceneBase = z.object({
   label: z.string().min(1),
   shotType: z.string().min(1),
   camera: z.string(),
+  /** Camera VIEWPOINT. Absent ⇒ eye-level. Keeps `camera` to pure MOVEMENT and
+   *  frees `shotType` to state the SIZE even on an over-the-shoulder or POV. */
+  angle: z.enum(VIDEO_ANALYSIS_SHOT_ANGLES).optional(),
+  /** Time manipulation. Absent ⇒ normal speed. */
+  speed: z.enum(VIDEO_ANALYSIS_SPEED_EFFECTS).optional(),
   visual: z.string().min(1),
-  transitionOut: z.enum(["cut", "fade", "wipe", "whip"]).optional(),
+  /**
+   * Text burned into the PICTURE of this shot — titles, captions, lower-thirds,
+   * subtitles — verbatim, in its original script. Absent when the frame carries
+   * none.
+   *
+   * Doctrine already asks for on-screen text inside `visual` prose, but a
+   * recreation needs to know discretely whether to RENDER text at all, and
+   * `translateOnScreenTextToEnglish` had no structured field to land in. It is
+   * also the signal the auto-cast frame judge reads: picture text belonging to an
+   * earlier scene's speech means the shot is replayed footage under a voice-over.
+   */
+  onScreenText: z.string().optional(),
+  /** Effects on this shot's PICTURE. Absent ⇒ a clean image. */
+  effects: z.array(z.enum(VIDEO_ANALYSIS_VISUAL_EFFECTS)).optional(),
+  transitionOut: z.enum(VIDEO_ANALYSIS_TRANSITIONS).optional(),
   // Array of concurrent layers (music + speech + sfx together); [] = silence.
   audio: z.array(audioLayerSchema),
   /** slotId → variationId for slots wearing a NON-default look in this scene
@@ -125,6 +286,9 @@ export type WindowScene = z.infer<typeof windowSceneSchema>
 /** What the MODEL emits per window (strict-JSON footer schema). scenes has NO min. */
 export const windowAnalysisSchema = z.object({
   language: z.string().optional(),
+  /** The clip-level look as read from THIS window. Merge folds the windows
+   *  field-by-field (first non-empty wins), like `language`. */
+  look: clipLookSchema.optional(),
   slots: z.array(entitySlotSchema),
   scenes: z.array(windowSceneSchema),
 })
@@ -147,6 +311,10 @@ export const videoAnalysisResultSchema = z.object({
     title: z.string().optional(),
     language: z.string().optional(),
   }),
+  /** Clip-level look, merged across windows. Deliberately a sibling of `meta`
+   *  rather than a member: `meta` is probed fact (ffprobe dimensions, probed
+   *  duration), while this is the model's reading of the photography. */
+  look: clipLookSchema.optional(),
   slots: z.array(entitySlotSchema),
   scenes: z.array(analyzedSceneSchema).min(1),
   /** CAST VARIATIONS (§4 cap handling): looks the analyzer's merge FOLDED into
@@ -267,6 +435,28 @@ export function dropUnknownSpeakers(
   return { audio: dropped.length > 0 ? out : audio, dropped }
 }
 
+/**
+ * Fold each window's reading of the clip look into one, FIELD BY FIELD: the first
+ * window that had something to say about a field wins it.
+ *
+ * Per-field rather than first-window-wins-everything because the windows see
+ * different footage — an opening window may read the grade confidently while only
+ * a later one contains the shot that reveals the format. Mirrors how `language` is
+ * resolved across windows rather than taken from window 0.
+ *
+ * Returns undefined when no window said anything, so an analysis with nothing to
+ * report omits the field rather than shipping an empty object.
+ */
+export function mergeClipLook(looks: ReadonlyArray<ClipLook | undefined>): ClipLook | undefined {
+  const out: Record<string, string> = {}
+  for (const look of looks) {
+    for (const [k, v] of Object.entries(look ?? {})) {
+      if (typeof v === "string" && v.trim() && !out[k]) out[k] = v.trim()
+    }
+  }
+  return Object.keys(out).length > 0 ? (out as ClipLook) : undefined
+}
+
 /** Substitute {slot:x}: castMap binding wins, else the slot's description, else literal id. */
 export function renderAnalyzedScene(scene: { visual: string }, slots: EntitySlot[], castMap?: Record<string, string>): string {
   const byId = new Map(slots.map((s) => [s.slotId, s]))