@ossclip/core 0.1.0

package/src/scene-registry.ts

@@ -0,0 +1,246 @@
+import { z } from "zod/v4";
+import { type Layout, type SceneComponentId } from "./scene-schema";
+
+/**
+ * The scene library's contract, React-free so both the producer brain and the
+ * render layer share one source of truth. Taste lives in the components; the
+ * LLM only fills these props. Copy caps enforce the virality grammar
+ * (short, numeric, high-contrast — BRAINSTORM §4.5).
+ */
+
+export const TitleCardProps = z.object({
+  eyebrow: z.string().max(28).optional(),
+  title: z
+    .string()
+    .min(1)
+    .max(48)
+    .describe("the claim WITHOUT the emphasis token — never repeat the emphasis here"),
+  /** A huge emphasized token — a number or 1–2 punch words ("861%"). */
+  emphasis: z
+    .string()
+    .max(16)
+    .optional()
+    .describe("the number/punch token pulled OUT of the title (e.g. '861%') — not a duplicate of it"),
+  sub: z.string().max(64).optional(),
+});
+
+export const StatCardProps = z.object({
+  label: z.string().min(1).max(28),
+  value: z.string().min(1).max(12),
+  caption: z.string().max(40).optional(),
+  /** Inverted emphasis block (light card on dark stage) for the punch stat. */
+  inverted: z.boolean().default(false),
+});
+
+export const RuleCardProps = z.object({
+  kicker: z.string().min(1).max(24),
+  text: z.string().min(1).max(40),
+  /** Rendered below, struck through — the rejected alternative. */
+  struck: z.string().max(40).optional(),
+});
+
+export const StrikethroughRevealProps = z.object({
+  lines: z
+    .array(
+      z.object({
+        text: z.string().min(1).max(32),
+        struck: z.boolean().default(false),
+        /**
+         * Verdict glyph before the line (R16 §66): `cross` renders ✗ in the
+         * danger color, `check` ✓ in the success color — the wrong-vs-right
+         * list variant. Defaults to none, so every existing production
+         * renders byte-identically.
+         */
+        mark: z.enum(["none", "cross", "check"]).default("none"),
+      }),
+    )
+    .min(1)
+    .max(4),
+});
+
+/**
+ * An enumeration (R16 §67): the speaker lists parallel things and each gets a
+ * bullet row. Born from a real miss — "what you need is AI harness, context
+ * engineering, prompt engineering" was bent into a title-plus-strike card
+ * that struck a thing the speaker RECOMMENDED, because no component said
+ * "list".
+ */
+export const BulletListProps = z.object({
+  /** Small kicker above the list ("WHAT YOU NEED"). */
+  title: z.string().max(28).optional(),
+  items: z.array(z.string().min(1).max(36)).min(2).max(5),
+});
+
+export const FlowDiagramProps = z.object({
+  nodes: z.array(z.string().min(1).max(16)).min(2).max(5),
+  /** Emphasize the terminal node (white chip, like CHURN in the reference). */
+  emphasizeLast: z.boolean().default(true),
+});
+
+export const TerminalMockProps = z.object({
+  windows: z
+    .array(
+      z.object({
+        title: z.string().max(24),
+        lines: z.array(z.string().max(40)).min(1).max(6),
+      }),
+    )
+    .min(1)
+    .max(5),
+  /** Fan-out label under the windows ("OUTPUT ×1"). */
+  fanOut: z.string().max(20).optional(),
+});
+
+export const ChatMockProps = z.object({
+  messages: z
+    .array(
+      z.object({
+        from: z.enum(["user", "agent"]),
+        text: z.string().min(1).max(60),
+      }),
+    )
+    .min(1)
+    .max(4),
+  /**
+   * The comment-CTA word the viewer is asked to type, plain and unformatted —
+   * the render quotes and capitalizes it ('"AGENTS"'), because formatting never
+   * lives in LLM output (FINDINGS §16). Setting it also collapses the scene to
+   * that ONE bubble (FINDINGS §28b), so it is only correct when the ask really
+   * is "comment <word>". A "reply with a number / which one" ask has no word to
+   * type and must leave this unset — `rejectCtaKeyword` drops it if it slips
+   * through, and the exchange in `messages` renders instead.
+   */
+  keyword: z
+    .string()
+    .max(16)
+    .optional()
+    .describe(
+      "ONLY for a 'comment <word>' ask: the single distinctive word the viewer types, " +
+        "plain and unformatted. Leave unset for any other CTA — especially " +
+        "'reply with a number/which one', where there is no word to type. Never a " +
+        "referential filler like 'number', 'answer', 'comment' or 'below'.",
+    ),
+});
+
+export const ScreenshotFrameProps = z.object({
+  /** File name inside the render public dir; omitted → styled placeholder frame. */
+  src: z.string().optional(),
+  label: z.string().max(32).optional(),
+  kenBurns: z.boolean().default(true),
+});
+
+export interface SceneComponentMeta {
+  propsSchema: z.ZodTypeAny;
+  defaultProps: Record<string, unknown>;
+  defaultLayout: Layout;
+  /**
+   * Layouts a REPEAT of this component may use instead, so the same card
+   * treatment twice in one video doesn't read as a template (FINDINGS §20).
+   * Varying the layout is safe where swapping the component is not — layout
+   * is presentation, while a component swap is an editorial judgement that
+   * can demand props the beat has no material for (a StatCard needs a number).
+   *
+   * Invariant, property-tested: an alternate's graphic slot is never SHORTER
+   * than the default's. Components size their type against their default slot
+   * — FlowDiagram literally budgets against `graphic-only` — so moving one
+   * into a smaller slot would re-open the overflow bug of §1/§12. Components
+   * that already sit in the tallest slot therefore have no alternate.
+   */
+  altLayouts: Layout[];
+  /** One-liner the producer prompt uses to pick components. */
+  whenToUse: string;
+}
+
+export const SCENE_REGISTRY: Record<SceneComponentId, SceneComponentMeta> = {
+  TitleCard: {
+    propsSchema: TitleCardProps,
+    defaultProps: { title: "TITLE" },
+    defaultLayout: "pip-bubble",
+    altLayouts: [],
+    whenToUse:
+      "The core claim or hook as big typography; use `emphasis` for a huge number or punch word.",
+  },
+  // Layout mix policy (FINDINGS §4): the speaker's face is the product.
+  // Stat/Rule cards sit UNDER a big face (video-top, the reference's
+  // signature frame); only TitleCard demotes it to a bubble, and only the
+  // diagram/terminal mocks may take the frame alone — briefly.
+  StatCard: {
+    propsSchema: StatCardProps,
+    defaultProps: { label: "METRIC", value: "+0%" },
+    defaultLayout: "video-top",
+    altLayouts: ["blurred-behind"],
+    whenToUse: "One striking metric (value like '+242%', '×3', '5s'); punchline in `caption`.",
+  },
+  RuleCard: {
+    propsSchema: RuleCardProps,
+    defaultProps: { kicker: "RULE", text: "DO THE THING" },
+    defaultLayout: "video-top",
+    altLayouts: ["blurred-behind"],
+    whenToUse:
+      "A prescriptive takeaway ('CAPACITY RULE / CAP ACTIVE AGENTS'); `struck` shows the rejected alternative.",
+  },
+  StrikethroughReveal: {
+    propsSchema: StrikethroughRevealProps,
+    defaultProps: { lines: [{ text: "NOT THIS", struck: true }] },
+    defaultLayout: "blurred-behind",
+    altLayouts: ["graphic-only"],
+    whenToUse:
+      "Negation/contrast beat — big words over the blurred speaker. Strike EVERY line of the " +
+      "phrase the speaker negates, not just its tail — a half-struck claim reads as a typo. " +
+      'For wrong-vs-right lists, set mark: "cross"/"check" (✗/✓) per line instead.',
+  },
+  FlowDiagram: {
+    propsSchema: FlowDiagramProps,
+    defaultProps: { nodes: ["A", "B"] },
+    defaultLayout: "graphic-only",
+    altLayouts: [],
+    whenToUse: "A causal chain or pipeline as chips with arrows (TEAM → AI AGENTS → CHURN).",
+  },
+  TerminalMock: {
+    propsSchema: TerminalMockProps,
+    defaultProps: { windows: [{ title: "terminal-01", lines: ["$ run"] }] },
+    defaultLayout: "graphic-only",
+    altLayouts: [],
+    whenToUse: "Anything about running code/processes/agents — stylized terminal windows.",
+  },
+  ChatMock: {
+    propsSchema: ChatMockProps,
+    defaultProps: { messages: [{ from: "user", text: "hello" }] },
+    defaultLayout: "blurred-behind",
+    altLayouts: ["graphic-only"],
+    whenToUse:
+      "A quoted phrase or exchange as chat bubbles over the blurred speaker; for a comment-CTA beat, set `keyword` to the word viewers should type.",
+  },
+  ScreenshotFrame: {
+    propsSchema: ScreenshotFrameProps,
+    defaultProps: {},
+    defaultLayout: "video-top",
+    altLayouts: ["blurred-behind"],
+    whenToUse: "Reference to a document/PR/review — a framed screenshot look with a label chip.",
+  },
+  BulletList: {
+    propsSchema: BulletListProps,
+    defaultProps: { items: ["FIRST", "SECOND"] },
+    defaultLayout: "blurred-behind",
+    altLayouts: ["graphic-only"],
+    whenToUse:
+      "An ENUMERATION — the speaker lists two or more parallel things " +
+      "('what you need is X, Y, Z'). One bullet per item, optional kicker title. " +
+      "Use this for lists instead of bending TitleCard or StrikethroughReveal around them.",
+  },
+};
+
+/**
+ * Resolution order per PHASE1 §2: componentDefaults ← props ← overrides.
+ * Returns null when the merged result doesn't validate.
+ */
+export function resolveSceneProps(
+  component: SceneComponentId,
+  props: Record<string, unknown>,
+  overrides: Record<string, unknown> = {},
+): Record<string, unknown> | null {
+  const meta = SCENE_REGISTRY[component];
+  const merged = { ...meta.defaultProps, ...props, ...overrides };
+  const parsed = meta.propsSchema.safeParse(merged);
+  return parsed.success ? (parsed.data as Record<string, unknown>) : null;
+}

package/src/scene-schema.ts

@@ -0,0 +1,203 @@
+import { z } from "zod/v4";
+
+/**
+ * How the stage is arranged while a scene is active (BRAINSTORM §4.6, PHASE1
+ * §1). `lower-third` and the two `split-*` layouts are landscape-native
+ * additions (R15 §54) — the frame-aware slot table gives every layout
+ * geometry in BOTH aspects (the split axis follows the frame's long edge:
+ * side-by-side in 16:9, stacked in 9:16), so the editor's layout switch can
+ * never render nothing.
+ */
+export const LayoutSchema = z.enum([
+  "full-bleed",
+  "video-top",
+  "pip-bubble",
+  "graphic-only",
+  "blurred-behind",
+  "lower-third",
+  "split-left",
+  "split-right",
+]);
+export type Layout = z.infer<typeof LayoutSchema>;
+
+export const SceneComponentIdSchema = z.enum([
+  "TitleCard",
+  "StatCard",
+  "RuleCard",
+  "StrikethroughReveal",
+  "FlowDiagram",
+  "TerminalMock",
+  "ChatMock",
+  "ScreenshotFrame",
+  "BulletList",
+]);
+export type SceneComponentId = z.infer<typeof SceneComponentIdSchema>;
+
+/**
+ * Where a scene sits — anchored to transcript word indices, never seconds,
+ * so a cleanup-level change re-resolves cleanly (PHASE1 §5).
+ */
+export const SceneAnchorSchema = z.object({
+  startWord: z.number().int().nonnegative(),
+  endWord: z.number().int().nonnegative(),
+});
+export type SceneAnchor = z.infer<typeof SceneAnchorSchema>;
+
+export const SceneSchema = z.object({
+  id: z.string(),
+  anchor: SceneAnchorSchema,
+  layout: LayoutSchema,
+  component: SceneComponentIdSchema,
+  /** LLM-owned; replaced wholesale on re-plan. Validated against the registry. */
+  props: z.record(z.string(), z.unknown()),
+  /** User-owned; NEVER clobbered by a re-plan. Merged over props at resolve time. */
+  overrides: z.record(z.string(), z.unknown()).default({}),
+  /** Why the producer chose this — surfaced in the report for taste-debugging. */
+  rationale: z.string().optional(),
+});
+export type Scene = z.infer<typeof SceneSchema>;
+
+/** A resolved, output-timed scene — what the composition actually renders. */
+export const SceneCueSchema = z
+  .object({
+  id: z.string(),
+  /**
+   * "graphic" cues come from the producer; "plain" cues are derived filler
+   * (`fillPlainCues`) — one per continuous take, so every second of the
+   * timeline is a selectable block whose framing can be edited. OPTIONAL
+   * rather than defaulted, deliberately: `render-props.json` reaches the
+   * editor as plain JSON with no schema parse, so cues written before this
+   * field existed carry no `kind` at runtime — absence means "graphic", and
+   * a defaulted (required-in-type) field would let code read `.kind` as
+   * always-present when it isn't. Always test `kind === "plain"`, never
+   * `=== "graphic"`.
+   */
+  kind: z.enum(["graphic", "plain"]).optional(),
+  layout: LayoutSchema,
+  /**
+   * Required for graphic cues (the superRefine below enforces it), absent on
+   * plain ones. The optionality is the consumer checklist: TS strict forces
+   * every `cue.component`/`cue.props` reader to state what it does with a
+   * plain cue.
+   */
+  component: SceneComponentIdSchema.optional(),
+  props: z.record(z.string(), z.unknown()).optional(),
+  startSec: z.number().nonnegative(),
+  endSec: z.number().nonnegative(),
+  /**
+   * Overrides the layout's graphic slot for this cue only. Set when the
+   * source already has text where the layout would have drawn, so the graphic
+   * is moved into a genuinely free band instead of being skipped
+   * (FINDINGS §26). Fractions of the frame, like every other rect.
+   */
+  graphicRect: z
+    .object({
+      x: z.number(),
+      y: z.number(),
+      w: z.number(),
+      h: z.number(),
+    })
+    .optional(),
+  /** Per-element nudges from the user's edit layer, by `data-edit-id`. */
+  elements: z.record(z.string(), z.object({
+    dx: z.number().optional(),
+    dy: z.number().optional(),
+    scale: z.number().positive().optional(),
+  })).optional(),
+  /**
+   * How the video sits in this scene's slot, when the automatic face-aware
+   * crop needs a hand (see `SceneOverrideSchema.video`). `scale` under 1 zooms
+   * OUT — more of the source, backdrop showing where it no longer covers.
+   */
+  video: z
+    .object({
+      scale: z.number().positive().max(4).optional(),
+      dy: z.number().optional(),
+      dx: z.number().optional(),
+      /** `false` switches the automatic idle-zoom layer off for this scene. */
+      autoZoom: z.boolean().optional(),
+    })
+    .optional(),
+  /**
+   * The pip bubble, reshaped per scene (R14 §52): mask roundness (0 = square
+   * card, 1 = the default circle) and the slot's top-left placement, frame
+   * fractions. Only consulted when the cue's resolved layout is `pip-bubble` —
+   * it is a property of the bubble, not of the video in general.
+   */
+  pip: z
+    .object({
+      cornerRadius: z.number().min(0).max(1).optional(),
+      x: z.number().min(0).max(1).optional(),
+      y: z.number().min(0).max(1).optional(),
+    })
+    .optional(),
+  /**
+   * Vertical centre for this scene's captions, frame fraction (R15 §56) —
+   * a hand-set anchor that wins over the layout's `captionAnchor` and the
+   * automatic avoidance. Set from the editor; travels on the cue so the
+   * renderer and the preview agree.
+   */
+  captionY: z.number().min(0).max(1).optional(),
+  /** Caption size multiplier for this scene (R16 §64) — scales the track's
+   * base font size, same convention as every other scale control. */
+  captionScale: z.number().min(0.2).max(3).optional(),
+  /** True when the user set an absolute time, detaching this cue from its words. */
+  pinned: z.boolean().optional(),
+  })
+  .superRefine((cue, ctx) => {
+    if (cue.kind !== "plain" && (cue.component === undefined || cue.props === undefined)) {
+      ctx.addIssue({
+        code: "custom",
+        message: "a graphic cue requires component and props; only kind: \"plain\" may omit them",
+      });
+    }
+  });
+export type SceneCue = z.infer<typeof SceneCueSchema>;
+
+/**
+ * Where the speaker's face sits in the SOURCE frame, measured once per source
+ * (FINDINGS §13). The stage derives each layout's vertical crop bias from
+ * this instead of guessing with a constant.
+ */
+export const FaceCropSchema = z.object({
+  /** Vertical center of the face, 0..1 of source height. */
+  centerYFrac: z.number().min(0).max(1),
+  /** Face height as a fraction of source height (informational for now). */
+  sizeFrac: z.number().min(0).max(1).optional(),
+  /**
+   * Horizontal center, 0..1 of source width. Only matters when the source is
+   * WIDER than the slot it fills — a portrait take is cropped vertically and
+   * the speaker's horizontal position is whatever the source framed. A
+   * landscape take in a vertical slot is cropped horizontally instead, and
+   * centring it blindly can crop the speaker out of their own video.
+   */
+  centerXFrac: z.number().min(0).max(1).optional(),
+  /**
+   * The source's width/height. Absent means "the same 9:16 the frame is",
+   * which is what every crop calculation used to assume outright — true for
+   * phone footage, wrong for a webcam recording or a screen capture.
+   */
+  sourceAspect: z.number().positive().optional(),
+});
+export type FaceCrop = z.infer<typeof FaceCropSchema>;
+
+/** Design tokens. Components read ONLY these — no hardcoded colors/fonts. */
+export const ThemeSchema = z.object({
+  bg: z.string().default("#0B0B0E"),
+  fg: z.string().default("#FFFFFF"),
+  accent: z.string().default("#FFE14D"),
+  muted: z.string().default("#9A9AA3"),
+  /** Affirmative green — the ✓ of §66's verdict lines; the editor's own
+   * "Saved" green, so the system stays one palette. */
+  success: z.string().default("#5FBF77"),
+  cardBg: z.string().default("#15151B"),
+  cardBorder: z.string().default("#2A2A33"),
+  danger: z.string().default("#FF5C5C"),
+  radiusPx: z.number().default(24),
+  fontDisplay: z
+    .string()
+    .default("'Inter', 'Helvetica Neue', 'Arial Black', Arial, sans-serif"),
+  fontMono: z.string().default("'SF Mono', 'Cascadia Code', Consolas, monospace"),
+});
+export type Theme = z.infer<typeof ThemeSchema>;
+export const defaultTheme: Theme = ThemeSchema.parse({});

package/src/schema.ts

@@ -0,0 +1,177 @@
+import { z } from "zod/v4";
+
+/** A single transcribed word, in SOURCE time (seconds). */
+export const WordSchema = z.object({
+  text: z.string(),
+  start: z.number().nonnegative(),
+  end: z.number().nonnegative(),
+  conf: z.number().min(0).max(1).optional(),
+});
+export type Word = z.infer<typeof WordSchema>;
+
+export const TranscriptSchema = z.object({
+  language: z.string().default("en"),
+  words: z.array(WordSchema),
+});
+export type Transcript = z.infer<typeof TranscriptSchema>;
+
+export const CleanupLevelSchema = z.enum(["exact", "light", "standard", "aggressive"]);
+export type CleanupLevel = z.infer<typeof CleanupLevelSchema>;
+
+export const RemovalReasonSchema = z.enum(["silence", "pause", "filler", "retake", "user", "clip"]);
+export type RemovalReason = z.infer<typeof RemovalReasonSchema>;
+
+/**
+ * One span of the source timeline. The cutlist is a full partition of
+ * [0, source duration]: every instant is either kept or removed, with a reason.
+ */
+export const SegmentSchema = z.object({
+  srcIn: z.number().nonnegative(),
+  srcOut: z.number().nonnegative(),
+  kind: z.enum(["keep", "remove"]),
+  reason: RemovalReasonSchema.optional(),
+  confidence: z.number().min(0).max(1).optional(),
+});
+export type Segment = z.infer<typeof SegmentSchema>;
+
+export const SpanSchema = z.object({
+  start: z.number(),
+  end: z.number(),
+});
+export type Span = z.infer<typeof SpanSchema>;
+
+export const AnalysisSchema = z.object({
+  /** Acoustic silences (ffmpeg silencedetect), source time. */
+  silences: z.array(SpanSchema),
+  /** Inter-word transcript gaps, incl. leading/trailing dead air. */
+  gaps: z.array(SpanSchema),
+  /**
+   * Regions containing no audible speech, after transcript veto — the
+   * candidate pool every silence/pause cut is drawn from.
+   */
+  cuttable: z.array(SpanSchema),
+  /**
+   * Sub-silence pauses from the RMS series (≥120 ms, below speech − 10 dB):
+   * too short to cut, but they are where phrases actually break. `silences`
+   * has a 0.35 s floor and `gaps` is empty on `-ml 1` output, so this is the
+   * only dense phrase signal the pipeline has (FINDINGS §18).
+   */
+  breaths: z.array(SpanSchema).default([]),
+  /** Standalone filler interjections (um, uh, …). */
+  fillers: z.array(
+    z.object({
+      wordIndex: z.number().int(),
+      text: z.string(),
+      start: z.number(),
+      end: z.number(),
+    }),
+  ),
+});
+export type Analysis = z.infer<typeof AnalysisSchema>;
+
+export const ProbeSchema = z.object({
+  duration: z.number().positive(),
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+  fps: z.number().positive(),
+  hasAudio: z.boolean(),
+});
+export type Probe = z.infer<typeof ProbeSchema>;
+
+export const RenderSettingsSchema = z.object({
+  width: z.number().int().positive().default(1080),
+  height: z.number().int().positive().default(1920),
+  fps: z.number().positive().default(30),
+});
+export type RenderSettings = z.infer<typeof RenderSettingsSchema>;
+
+import { SceneSchema, ThemeSchema } from "./scene-schema";
+
+/** The single source of truth for a production. Every pipeline stage is a pure function over this. */
+export const ProductionSchema = z.object({
+  version: z.literal(1),
+  source: z.object({
+    path: z.string(),
+    probe: ProbeSchema,
+    audioPath: z.string().optional(),
+    mezzaninePath: z.string().optional(),
+    /** Measured face box (FINDINGS §13) — a property of the source; null = no face found. */
+    face: z
+      .object({
+        centerXFrac: z.number(),
+        centerYFrac: z.number(),
+        sizeFrac: z.number(),
+        framesSampled: z.number().int(),
+        framesDetected: z.number().int(),
+      })
+      .nullable()
+      .optional(),
+  }),
+  cleanup: CleanupLevelSchema,
+  /** User intent for the producer brain ("educational video about agents…"). */
+  intent: z.string().optional(),
+  /**
+   * The RAW ASR transcript. `analysis` and `cutlist` index into this array,
+   * so it must stay the untouched one — see `repairs` for the corrections
+   * applied downstream (FINDINGS §17).
+   */
+  transcript: TranscriptSchema.optional(),
+  /**
+   * Mishearing corrections applied before captions, scene copy and grounding.
+   * Kept as a diff rather than a second transcript so the production stays
+   * reproducible: `applyRepairs(transcript, repairs.filter(r => r.applied))`
+   * reconstructs exactly what was rendered.
+   */
+  repairs: z
+    .array(
+      z.object({
+        startWord: z.number().int(),
+        endWord: z.number().int(),
+        heard: z.string(),
+        correction: z.string(),
+        applied: z.boolean(),
+        rejected: z.string().optional(),
+      }),
+    )
+    .optional(),
+  analysis: AnalysisSchema.optional(),
+  cutlist: z.array(SegmentSchema).optional(),
+  /**
+   * Present on a `--clip` run (R19 §93): the target and the resolved window.
+   * `startWord`/`endWord` are indices into the PRE-slice repaired transcript
+   * (the space selection ran in); the seconds are source time and stay
+   * meaningful against the sliced `transcript` stored above.
+   */
+  clip: z
+    .object({
+      targetSec: z.number().positive(),
+      startWord: z.number().int().nonnegative(),
+      endWord: z.number().int().nonnegative(),
+      startSec: z.number().nonnegative(),
+      endSec: z.number().nonnegative(),
+      reason: z.string(),
+    })
+    .optional(),
+  scenes: z.array(SceneSchema).optional(),
+  /**
+   * WHO planned this production (R16 §78). `usage.json` answers "what did
+   * that cost", but it describes one run and a fully-cached re-run makes no
+   * calls — so the provider that actually chose these scenes used to vanish
+   * from the workdir. This travels with the artefact it explains.
+   *
+   * `cached: true` means this run made no LLM calls and the provider named
+   * here is the one carried forward from the run that did.
+   */
+  producer: z
+    .object({
+      provider: z.string(),
+      /** Models seen this run, editorial first — the tiering is visible. */
+      models: z.array(z.string()).default([]),
+      cached: z.boolean().default(false),
+      at: z.string().optional(),
+    })
+    .optional(),
+  theme: ThemeSchema.optional(),
+  render: RenderSettingsSchema,
+});
+export type Production = z.infer<typeof ProductionSchema>;