@cueframe/kernel 0.0.1

package/dist/chunk-ATAF24QG.js

@@ -0,0 +1,735 @@
+import {
+  Reframe
+} from "./chunk-EA6MYCYW.js";
+
+// ../composition/src/validators/composition.ts
+import { z } from "zod";
+import { zid } from "convex-helpers/server/zod3";
+var Format = z.object({
+  aspectRatio: z.enum(["16:9", "9:16", "1:1", "4:5"]),
+  fps: z.union([z.literal(24), z.literal(30), z.literal(60)]).optional(),
+  resolution: z.enum(["hd", "fhd", "4k"]).optional(),
+  // Target platform (the suggestion's primary platform: tiktok/ig/youtube/…),
+  // frozen into the snapshot so the floor's safe-zone placement clears that
+  // surface's UI chrome. Output-determining → part of the render cache key.
+  // Normalized at lookup (see safe-zones normalizePlatform); absent → broadcast.
+  platform: z.string().optional()
+});
+var Trim = z.object({
+  start: z.number().nonnegative(),
+  end: z.number().nonnegative()
+});
+var ExcludedRange = z.object({
+  start: z.number().nonnegative(),
+  end: z.number().nonnegative(),
+  reason: z.string().optional()
+});
+var MediaClipSource = z.object({
+  kind: z.literal("media"),
+  mediaId: zid("mediaItems"),
+  trim: Trim.optional(),
+  excludedRanges: z.array(ExcludedRange).optional(),
+  volume: z.number().min(0).max(4).optional(),
+  muted: z.boolean().optional(),
+  playbackRate: z.number().positive().optional(),
+  sync: z.enum(["video", "independent"]).optional(),
+  /**
+   * Ken-Burns motion preset for `kind: "image"` tracks. The renderer's
+   * `<StillFrame>` reads this to drive a per-frame transform over the
+   * clip's duration. Default is `"in"` (gentle zoom-in) — chosen because
+   * still photos with zero motion read as "broken video" against
+   * surrounding b-roll. Set to `"none"` to opt out. Ignored on non-image
+   * tracks.
+   */
+  kenBurns: z.enum(["in", "out", "pan-l", "pan-r", "none"]).optional(),
+  /**
+   * Audio mix override for `kind: "audio"` tracks (SFX / music beds).
+   * `volumeDb` is decibels relative to source (negative = quieter); the
+   * renderer converts to linear gain via `10^(dB/20)`. Default at render
+   * time is -12 dB for stock SFX beds — quiet enough to sit under VO
+   * without ducking. `fadeInMs` / `fadeOutMs` interpolate linearly from
+   * silence to `volumeDb` (and back) at the clip's edges; default 200 ms
+   * each. All three are ignored on non-audio tracks.
+   */
+  volumeDb: z.number().optional(),
+  fadeInMs: z.number().nonnegative().optional(),
+  fadeOutMs: z.number().nonnegative().optional(),
+  /**
+   * Loop the underlying media until the clip's `duration` runs out, instead
+   * of letting the media play to its natural end and freezing on the last
+   * frame (video / gif) or going silent (audio). Used by gif enrichment
+   * clips that may be shorter than the moment they cover, and by sfx
+   * ambient beds. Ignored on `kind: "image"` tracks (stills don't have a
+   * source timeline to loop).
+   */
+  loop: z.boolean().optional(),
+  /**
+   * What this audio-track clip IS, for mix policy + eval. Absent on video/image
+   * clips (the track-family enum on TimelineClip stays untouched — nothing
+   * downstream switches on family; `audioRole` lives on the SOURCE like
+   * `volumeDb`). SFX vs music vs VO is otherwise indistinguishable to the
+   * duck/master/eval logic. (`sfxCompile` stamps `sfx`/`music`; VO is future.)
+   * `ambience` is a bed that HOLDS under VO — it loops, sits at the BOTTOM of the
+   * mix, and is NEVER duck-stamped (founder ruling: ambience does not duck under
+   * speech; no beat map, no anchor semantics).
+   */
+  audioRole: z.enum(["sfx", "music", "vo", "ambience"]).optional(),
+  /**
+   * Speech-aware ducking (music / vo roles only). Deterministic: the render
+   * derives the duck envelope from the composition's OWN timeline-aligned
+   * caption words — no audio analysis, no ffmpeg sidechain. `duckDb` is the
+   * gain applied during speech (e.g. -12); `attackMs`/`releaseMs` ramp the
+   * envelope in/out (defaults 150 / 400). `windows` are explicit speech spans
+   * (timeline ms) — REQUIRED when the composition has no captions; when
+   * captions exist the projection derives windows from `captions.segments`
+   * words and `windows` MUST be absent (one SSOT, no drift).
+   */
+  duck: z.object({
+    duckDb: z.number().max(0),
+    attackMs: z.number().nonnegative(),
+    releaseMs: z.number().nonnegative(),
+    windows: z.array(z.object({ startMs: z.number(), endMs: z.number() })).optional()
+  }).optional(),
+  /**
+   * SFX event anchor — provenance + re-resolution handle for a hit bound to a
+   * graphic/transition entrance. NOT consumed at render (`startTime` stays the
+   * single placement truth; see the sfxCompile drift note). `clipId` is the
+   * overlay/video clip whose entrance this hits; `offsetMs` is vs that clip's
+   * `startTime` (usually 0). Exists so re-resolution + eval can re-derive the
+   * binding after an amendment. Absent on non-SFX audio clips.
+   */
+  anchor: z.object({
+    clipId: z.string().min(1),
+    offsetMs: z.number()
+  }).optional(),
+  /**
+   * The camera channel — the canonical `reframe` model. `segments` tile the
+   * clip's duration and animate a source→output viewport: each carries WHO
+   * the camera tracks (`focus`), HOW TIGHT (`zoom`, <1 punches in), an optional
+   * fine framing nudge (`bias`), and optional zoom-ramp easing (`ease`). The
+   * derive math (deriveTrajectory) honors these directly — no closed-enum
+   * framing names, no hardcoded scale constants.
+   *
+   * When omitted, the renderer plays the raw source (no crop). When present,
+   * the variant cache keys by `hashReframe(reframe.segments)`.
+   *
+   * Replaces the deleted subject-centric `cropIntents` (2026-06-14 cutover —
+   * one viewport primitive for all clip kinds).
+   */
+  reframe: Reframe.optional()
+});
+var ComponentClipSource = z.object({
+  kind: z.literal("component"),
+  componentId: z.string().min(1),
+  props: z.record(z.string(), z.unknown()),
+  /** Depth plane, mirroring OverlayClipSource — without this field the cloud
+   *  motion-preset sink's zPlane carry was silently STRIPPED at parse (Opus
+   *  review F1), planting a lane asymmetry that would fire the day cards are
+   *  allowed behind-subject. NOTE: the save-time component→custom desugar must
+   *  also carry it when behind-cards land. */
+  zPlane: z.enum(["front", "behind-subject"]).optional()
+});
+var OverlayClipSource = z.object({
+  kind: z.literal("overlay"),
+  primitiveId: z.string().min(1),
+  params: z.record(z.string(), z.unknown()),
+  /** Launch-grade depth (spec 2026-06-11): which z-plane this overlay renders on.
+   *  'behind-subject' = under the subject cut-out (the matte occludes it).
+   *  Extensible enum, NOT a boolean — later planes ('behind-background') are additive.
+   *  Default front. Depth fields (zPlane/anchor/parallax) mirror the TS shape in
+   *  `@cueframe/core/render/types#CompositionOverlay`. */
+  zPlane: z.enum(["front", "behind-subject"]).optional(),
+  /** Durable anchor in SCENE space (source-normalized [0,1]); projected through the
+   *  clip's crop trajectory at render (world-lock). System-computed default; agent may set. */
+  anchor: z.object({ space: z.literal("scene"), x: z.number().min(0).max(1), y: z.number().min(0).max(1) }).optional(),
+  /** Differential vs camera motion: 0 = locked to scene; small ± = depth parallax. */
+  parallax: z.number().min(-0.3).max(0.3).optional()
+});
+var EffectClipSource = z.object({
+  kind: z.literal("effect"),
+  primitiveId: z.string().min(1),
+  params: z.record(z.string(), z.unknown()).optional()
+});
+var AlphaLayerClipSource = z.object({
+  kind: z.literal("alpha-layer"),
+  componentId: z.string().min(1),
+  props: z.record(z.string(), z.unknown()),
+  zPlane: z.enum(["front", "behind-subject"]).optional()
+});
+var CardClipSource = z.object({
+  kind: z.literal("card"),
+  /** Standard HTML/CSS, verbatim. A `<style>` block may be inlined. No <script>
+   *  (innerHTML never executes it) — decoration only. Required + non-empty. */
+  html: z.string().min(1),
+  /** Brand-token bindings: each value is a literal OR a whole-string `$brand:<path>`
+   *  ref. Resolved deep at render (resolveBrandRefsDeep — the SAME resolver the
+   *  graphics compiler + alpha bake use) into `--cf-<key>` CSS custom properties on
+   *  the wrapper box; the authored CSS references them as `var(--cf-<key>)`. Keeps
+   *  the payload standard CSS while staying brand-resolvable, with no inline-string
+   *  substitution. */
+  tokens: z.record(z.string(), z.string()).optional(),
+  /** Depth plane. FRONT ONLY for now — behind-subject cards are not wired into
+   *  the matte pipeline (the depth predicates in depth.ts / variant-keys /
+   *  resolve-behind-placement exclude card), so admitting "behind-subject" here
+   *  would render the card unoccluded with no matte and no error. The wire
+   *  refuses it LOUDLY instead; widen to the OverlayClipSource enum when the
+   *  behind wiring lands (review finding 2026-07-10). */
+  zPlane: z.literal("front").optional()
+});
+var CompositionClipSource = z.object({
+  kind: z.literal("composition"),
+  compositionId: z.string().min(1),
+  trim: Trim.optional()
+}).strict();
+var ClipSource = z.discriminatedUnion("kind", [
+  MediaClipSource,
+  ComponentClipSource,
+  OverlayClipSource,
+  EffectClipSource,
+  AlphaLayerClipSource,
+  CardClipSource,
+  CompositionClipSource
+]);
+var Transition = z.object({
+  type: z.string().min(1),
+  duration: z.number().positive()
+});
+var Position = z.object({
+  x: z.number(),
+  y: z.number()
+});
+var Region = z.object({
+  // Output-space fractions in [0,1]. Bounded like opacity / overlay anchors so a
+  // mis-authored rect (x<0, w>1) fails LOUD at the wire boundary instead of the
+  // renderer sizing the source to e.g. 2× the frame. (x+w ≤ 1 / y+h ≤ 1 is the
+  // intent but left unrefined to keep `Region` a plain object for zodToConvex
+  // derivation; a rect that fits the bounds but spills past an edge is clipped by
+  // the box's overflow:hidden, not a crash.)
+  x: z.number().min(0).max(1),
+  y: z.number().min(0).max(1),
+  w: z.number().positive().max(1),
+  h: z.number().positive().max(1)
+});
+var ClipFit = z.enum(["cover", "contain"]);
+var PerClipEffect = z.object({
+  primitiveId: z.string().min(1),
+  params: z.record(z.string(), z.unknown()).optional()
+});
+var KeyframeEasing = z.union([
+  z.enum(["linear", "ease", "easeIn", "easeOut", "easeInOut"]),
+  z.object({ cubicBezier: z.tuple([z.number(), z.number(), z.number(), z.number()]) }).strict()
+]);
+var Keyframe = z.object({
+  /** Seconds from the clip's own start — NOT timeline time. See above. */
+  time: z.number().nonnegative(),
+  value: z.number(),
+  /** How to reach this keyframe from the previous one. Default `linear`. */
+  easing: KeyframeEasing.optional()
+}).strict();
+var KeyframeChannel = z.array(Keyframe).min(2);
+var ANIMATABLE_PARAMS = [
+  "opacity",
+  "scale",
+  "rotation",
+  "position.x",
+  "position.y",
+  "volume"
+];
+var TimelineClip = z.object({
+  id: z.string().min(1),
+  startTime: z.number().nonnegative(),
+  duration: z.number().positive(),
+  source: ClipSource,
+  /** The clip's track FAMILY — mirrors `Track.kind`, distinct from `source.kind`
+   *  (content). OPTIONAL: most clips' family derives unambiguously from the
+   *  source (overlay/effect/component/alpha-layer → overlay/effect), so existing
+   *  authored clips need no migration. It is load-bearing ONLY for `media`
+   *  sources, which are ambiguous (a media clip can be video | audio | image) —
+   *  there `kind` is the clip's self-describing family and `clip.add` requires it
+   *  (or a target track) to route. See `resolveClipKind` (@cueframe/composition-ops). */
+  kind: z.enum(["video", "audio", "image", "overlay", "effect"]).optional(),
+  opacity: z.number().min(0).max(1).optional(),
+  scale: z.number().positive().optional(),
+  rotation: z.number().optional(),
+  position: Position.optional(),
+  /** Phase 5: output-space placement rect (default = full frame). The single
+   *  placement primitive; position/scale/rotation are the animation channel. */
+  region: Region.optional(),
+  /** Phase 5: how the source fills `region` (default `cover`). */
+  fit: ClipFit.optional(),
+  effects: z.array(PerClipEffect).optional(),
+  transitionIn: Transition.optional(),
+  /**
+   * A/V LINK GROUP. Clips sharing an id move, trim and delete together.
+   *
+   * Not polish — a correctness property. Without it, selecting a video clip
+   * does not select its audio, so every ripple, move and trim silently desyncs
+   * sound from picture and the user finds out at playback. Every editor this
+   * repo has been measured against carries the same field; ours had none
+   * (`grep linkGroup` returned nothing across `cueframe/src` and
+   * `packages/composition/src` on 2026-08-23).
+   *
+   * Membership is the ONLY thing stored. What a link implies — expand the
+   * selection, carry the group through a move — is behaviour, and lives in
+   * `../timeline/link.ts` so both lanes get it from one implementation.
+   */
+  linkGroupId: z.string().min(1).optional(),
+  /**
+   * Time-varying parameter channels, keyed by param path. A param present here
+   * OVERRIDES its scalar sibling for the clip's whole duration — the scalar
+   * stays as the value a still frame or a non-animating renderer reads.
+   */
+  // STRING-keyed with a refine, not enum-keyed — deliberately. An enum-keyed
+  // record derives to a convex validator zodToConvexFields cannot build
+  // ("Record keys must be strings or ids"), which made the convex-schemas
+  // module THROW AT IMPORT — a deploy-path failure no typecheck showed (review
+  // finding 2026-08-24; caught only by a module-load check). The closed-set
+  // guarantee survives in the refine: an unknown param still fails loud.
+  animate: z.record(z.string(), KeyframeChannel).superRefine((channels, ctx) => {
+    for (const key of Object.keys(channels)) {
+      if (!ANIMATABLE_PARAMS.includes(key)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [key],
+          message: `"${key}" is not an animatable param (${ANIMATABLE_PARAMS.join(", ")})`
+        });
+      }
+    }
+  }).optional()
+}).strict();
+var Gap = z.object({
+  id: z.string().min(1),
+  startTime: z.number().nonnegative(),
+  duration: z.number().positive()
+}).strict();
+var TrackContent = z.unknown().transform((val, ctx) => {
+  const hasSource = !!val && typeof val === "object" && "source" in val;
+  const res = (hasSource ? TimelineClip : Gap).safeParse(val);
+  if (!res.success) {
+    for (const issue of res.error.issues) ctx.addIssue(issue);
+    return z.NEVER;
+  }
+  return res.data;
+});
+var Track = z.object({
+  id: z.string().min(1),
+  kind: z.enum(["video", "audio", "image", "overlay", "effect"]),
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  /**
+   * TRACK-LEVEL GAIN, linear, multiplied into every clip on the track.
+   *
+   * The mixer had per-clip volume and nothing above it, so "turn the music
+   * down" meant editing every music clip and re-editing each new one. Absent =
+   * unity; the projection only multiplies when it is present, so an untouched
+   * composition renders byte-identically to before this field existed.
+   */
+  volume: z.number().min(0).max(4).optional(),
+  contents: z.array(TrackContent)
+}).strict();
+var Marker = z.object({
+  id: z.string().min(1),
+  startTime: z.number().nonnegative(),
+  endTime: z.number().nonnegative().optional(),
+  kind: z.string().min(1),
+  name: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+}).strict();
+var AccessControl = z.object({
+  public: z.boolean().optional(),
+  readerOrgIds: z.array(z.string()).optional(),
+  writerOrgIds: z.array(z.string()).optional()
+});
+var LicenseDeclaration = z.object({
+  type: z.string().min(1),
+  source: z.string().optional(),
+  notes: z.string().optional()
+});
+var CompositionAccessibility = z.object({
+  audioDescriptionTrackId: z.string().optional(),
+  captionsTrackId: z.string().optional(),
+  signLanguageTrackId: z.string().optional(),
+  notes: z.string().optional()
+});
+var CaptionWord = z.object({
+  text: z.string().min(1),
+  startMs: z.number().nonnegative(),
+  endMs: z.number().nonnegative(),
+  emphasis: z.boolean().optional(),
+  // Hand-drawn marker annotation drawn over this word (color via
+  // CaptionStyle.annotationColor). Mirrors the renderer's CaptionWord.
+  annotate: z.enum(["circle", "underline"]).optional()
+});
+var CaptionStyle = z.object({
+  fontFamily: z.string().min(1).optional(),
+  // Font size in PERCENT OF COMPOSITION HEIGHT — the caption sizing unit across
+  // the whole system: the Captions primitive resolves `height * fontSize/100`,
+  // the composition floor sizes the caption band from the same percent
+  // (buildFloorInput's DEFAULT_CAPTION_FONT_PCT = 5), and the authoring tools
+  // already document it as "% of video height (default 5)" bounded 1-15. NOT
+  // px: the wire previously accepted any positive number, so a px-intent value
+  // (e.g. 31 — memoir/P2surf E2E 2026-07-22) silently rendered 31% of 1080 =
+  // 335px giant tokens whose multi-line page overflowed the frame: the
+  // bottom-anchored block spilled into the upper half while unspoken page words
+  // sat at opacity 0 ("giant pale ghost, no caption at the bottom"). Bounded
+  // [1,15] so px-intent values are rejected LOUDLY at author time instead of
+  // rendering garbage.
+  fontSize: z.number().min(1, "captions style.fontSize is PERCENT of composition height (1-15, default 5) \u2014 px values are not accepted").max(15, "captions style.fontSize is PERCENT of composition height (1-15, default 5) \u2014 px values are not accepted").optional().describe("Font size as % of composition height (1-15, default 5). NOT px."),
+  fontWeight: z.number().int().min(100).max(900).optional(),
+  color: z.string().min(1).optional(),
+  highlightColor: z.string().min(1).optional(),
+  backgroundColor: z.string().optional(),
+  // Caption backdrop plate — the legibility background behind the WHOLE caption
+  // block (distinct from emphasisPlate, which plates individual emphasis runs).
+  //   'glass' — a frosted backdrop-blur pill (DEFAULT); premium, footage reads through.
+  //   'solid' — an opaque dark plate (punchy / social look).
+  //   'none'  — no plate; captions rely on the text shadow (legible only on
+  //             controlled / dark backdrops — a deliberate opt-out).
+  // Replaces the old per-frame legibility scrim.
+  plate: z.enum(["glass", "solid", "none"]).optional(),
+  position: z.enum(["top", "center", "bottom"]).optional(),
+  textTransform: z.enum(["none", "uppercase", "capitalize"]).optional(),
+  emphasisColor: z.string().optional(),
+  // CSS gradient for emphasis TEXT fill (bg-clip-text) — overrides
+  // emphasisColor when set, ignored under a plate.
+  emphasisGradient: z.string().optional(),
+  emphasisScale: z.number().positive().optional(),
+  emphasisFontFamily: z.string().optional(),
+  emphasisFontWeight: z.number().int().min(100).max(900).optional(),
+  emphasisTextTransform: z.enum(["none", "uppercase", "capitalize"]).optional(),
+  emphasisLetterSpacing: z.number().optional(),
+  // Italic vs normal slope on emphasis words. The serif-emphasis style
+  // mirrors the SFxP reference set's italic serif emphasis treatment.
+  // Default 'normal' (most variants are upright); preset 'serif-emphasis@1'
+  // ships 'italic'.
+  emphasisFontStyle: z.enum(["normal", "italic"]).optional(),
+  // Per-word entrance motion (the shared TextMotion vocabulary). Each word
+  // enters on its spoken beat, staggered so two never fire together:
+  //   'fade'       — opacity-only reveal.
+  //   'word-pop'   — opacity + spring scale-settle.
+  //   'stagger-up' — opacity + upward translate.
+  //   'none'       — static (no entrance).
+  // Brand kits drive this via $brand:motion.entrance; an author may set it too.
+  entrance: z.enum(["none", "fade", "word-pop", "stagger-up"]).optional(),
+  entranceMs: z.number().nonnegative().optional(),
+  entranceStaggerMs: z.number().nonnegative().optional(),
+  exitMs: z.number().nonnegative().optional(),
+  // Emphasis highlighter plate (editorial caption look): a rounded plate
+  // behind each contiguous emphasis run, with an alternating second color.
+  emphasisPlate: z.boolean().optional(),
+  emphasisPlateColor: z.string().optional(),
+  emphasisPlateTextColor: z.string().optional(),
+  emphasisPlateAltColor: z.string().optional(),
+  emphasisPlateAltTextColor: z.string().optional(),
+  emphasisPlateRadius: z.number().nonnegative().optional(),
+  emphasisPlatePadX: z.number().optional(),
+  emphasisPlatePadY: z.number().optional(),
+  // Marker stroke color for CaptionWord.annotate.
+  annotationColor: z.string().optional(),
+  // Caption block max width as % of composition width (wider = phrase spreads).
+  // Bounded ≤100: a >100 value cannot mean anything but overflow (same
+  // unit-misread class as fontSize above).
+  maxWidthPercent: z.number().positive().max(100, "captions style.maxWidthPercent is % of composition width (max 100)").optional()
+});
+var CaptionSegment = z.object({
+  words: z.array(CaptionWord)
+});
+var CompositionCaptions = z.discriminatedUnion("source", [
+  z.object({
+    source: z.literal("derived"),
+    /** The clip these words are a projection OF. Re-derive from this. */
+    from: z.object({ clipId: z.string() }),
+    segments: z.array(CaptionSegment),
+    style: CaptionStyle.optional()
+  }),
+  z.object({
+    source: z.literal("authored"),
+    segments: z.array(CaptionSegment),
+    style: CaptionStyle.optional()
+  })
+]);
+function captionWords(c) {
+  return c.segments.flatMap((s) => s.words);
+}
+var Composition = z.object({
+  // Self-diagnosing version envelope. Zod's default "Invalid literal value,
+  // expected 1" reads like a value-range complaint; the agent's most common
+  // first-run mistake is OMITTING the envelope entirely (ctx.data === undefined),
+  // so name it. A present-but-wrong value still gets the explicit literal-1
+  // instruction. (errorMap is runtime-only — the emitted JSON Schema stays
+  // `const: 1`, so no codegen regen.)
+  v: z.literal(1, {
+    errorMap: (_issue, ctx) => ctx.data === void 0 ? { message: 'Missing version envelope: add top-level "v": 1 to the composition.' } : { message: `Invalid version envelope: top-level "v" must be the literal 1 (got ${JSON.stringify(ctx.data)}).` }
+  }),
+  format: Format,
+  tracks: z.array(Track),
+  markers: z.array(Marker).optional(),
+  captions: CompositionCaptions.optional(),
+  // (fitMode deleted 2026-05-25 baked-variants substrate replacement.
+  // The variant + composition.format.aspectRatio together pick the
+  // output; no render-time fit decision needed. Historical snapshots in
+  // `compositionVersions.snapshotJson` that still carry this field are
+  // tolerated by the .passthrough() at the Composition schema's tail —
+  // the field is inert at render time.)
+  // (brandKitId removed 2026-06-29 — brand is PROJECT-scoped. `projects.brandKitId`
+  // is the brand SSOT; render resolves the kit from the project (P1.1) and the
+  // compose-time brand eval sources the kit id from a non-wire side channel. A
+  // composition no longer carries a brand pointer.)
+  sourceSuggestionId: z.string().optional(),
+  license: LicenseDeclaration.optional(),
+  licenseVerification: z.enum([
+    "attested",
+    "cueframe-verified",
+    "third-party-verified"
+  ]).optional(),
+  accessibility: CompositionAccessibility.optional(),
+  ownerOrgId: z.string().optional(),
+  acl: AccessControl.optional()
+  // TOP-LEVEL STRICT (was .passthrough()): an unknown top-level key is almost
+  // always a client mistake — most importantly a whole composition wrapped one
+  // level too deep (`{composition:{…}}`), which under passthrough produced the
+  // misdirecting "v/format/tracks required" with no clue about the stray key.
+  // strict() makes zod emit a standard `unrecognized_keys` issue naming the
+  // offending key, so the error is self-diagnosing — uniformly for any stray
+  // top-level key, not a special-case. Nested objects keep their own (lenient)
+  // behavior, preserving forward-compat for fields inside tracks/clips/etc.
+}).strict();
+var CompositionAuthorKind = z.enum(["user", "agent", "import"]);
+var CompositionVersion = z.object({
+  id: z.string().min(1),
+  compositionId: zid("compositions"),
+  predecessorId: z.string().optional(),
+  createdAt: z.number(),
+  // epoch ms — see CONVEX_ADAPTATIONS.md
+  etag: z.string().min(1),
+  authorKind: CompositionAuthorKind,
+  // load-bearing for multi-agent lineage
+  authorId: z.string().optional(),
+  // userId for 'user', agentId for 'agent', source for 'import'
+  composition: Composition
+});
+
+// ../composition/src/graphics-plan/schemas.ts
+import { z as z2 } from "zod";
+var GRAPHICS_PLAN_VERSION = "gp-1";
+var Version = z2.literal(GRAPHICS_PLAN_VERSION);
+var PlanRect = Region;
+var GraphicRole = z2.enum([
+  "title-card",
+  // topic-setter / opener card
+  "stat",
+  // a single headline number + label
+  "lower-third",
+  // name/title tag over the speaker
+  "pull-quote",
+  // a short quoted line
+  "hero",
+  // big behind-subject phrase (zPlane: behind-subject)
+  "logo-tag",
+  // small brand mark / watermark beat
+  // ── the beat carries an ARGUMENT, not a caption ──
+  "enumeration",
+  // a list of short items ("LBO modelling / VDR diligence / customer cubes")
+  "sequence",
+  // an ordered chain of steps — often the POINT is that it is too long
+  "comparison"
+  // labelled values set against each other (a benchmark, a before/after)
+]);
+var Copy = z2.object({
+  headline: z2.string().max(120).optional(),
+  sub: z2.string().max(200).optional(),
+  value: z2.string().max(40).optional(),
+  label: z2.string().max(80).optional(),
+  /** Ordered short items — an `enumeration`'s bullets, a `sequence`'s steps. */
+  items: z2.array(z2.string().max(80)).max(8).optional(),
+  /**
+   * Labelled values for a `comparison`.
+   *
+   * `value` is a STRING, deliberately — not `number | string`. The plan owns the words, and a
+   * comparison's words include their units: a planner writes "10 min", "98%", "$4.2M", never
+   * 600. A number would have to be re-unitised downstream by someone who doesn't know what it
+   * meant.
+   *
+   * It is also a hard constraint: `submit_compose_plan` is a STRICT Anthropic tool
+   * (`strict: true`, schemas.ts), and a `z.union` here becomes an `anyOf` in the tool schema.
+   * That is what stalled the planner on 2026-07-13 — it ran, could not satisfy the schema, and
+   * never called the tool at all. Keep every field in this schema a single concrete type.
+   */
+  series: z2.array(z2.object({ label: z2.string().max(40), value: z2.string().max(16) })).max(8).optional()
+}).strict();
+var ContentBeat = z2.object({
+  id: z2.string().min(1),
+  /** Clip-relative seconds. */
+  atSec: z2.number().min(0),
+  durSec: z2.number().positive(),
+  role: GraphicRole,
+  copy: Copy,
+  /** Editorial WHY — the beat this graphic serves (for review + the judge). */
+  intent: z2.string().min(1).max(400),
+  /** Higher = more important; drives drop order under budget. */
+  priority: z2.number().int().min(0).max(10).default(5)
+}).strict();
+var ContentPlan = z2.object({
+  version: Version,
+  beats: z2.array(ContentBeat)
+}).strict();
+var ElementRole = z2.enum([
+  "headline",
+  // primary large text
+  "value",
+  // the stat number / the one word to remember
+  "label",
+  // supporting text
+  "sublabel",
+  // secondary supporting text
+  "logo",
+  // brand mark
+  "accent-shape",
+  // decorative block/line/underline
+  "backdrop"
+  // solid fill (takeover cards only)
+]);
+var StyleRole = z2.enum([
+  "heading",
+  "body",
+  "accent",
+  "surface",
+  "on-accent",
+  "on-surface"
+]);
+var ZPlane = z2.enum(["front", "behind-subject"]);
+var LayoutElement = z2.object({
+  elId: z2.string().min(1),
+  role: ElementRole,
+  /** Solved CLEAR of `keepOut` (except intentional behind-subject heroes). */
+  box: PlanRect,
+  styleRole: StyleRole,
+  z: ZPlane.default("front"),
+  /** The text this element renders (from the ContentPlan). Omitted for
+   *  logo / accent-shape / backdrop. */
+  text: z2.string().max(200).optional(),
+  /** Index into the editorial type scale (mirrors composition-floor
+   *  Treatment.typeScaleStep) — a SCALE STEP, not a raw px guess. */
+  typeScaleStep: z2.number().int().min(0).max(8).optional()
+}).strict();
+var EPS = 1e-6;
+var rectsOverlapEps = (a, b) => a.x < b.x + b.w - EPS && a.x + a.w > b.x + EPS && a.y < b.y + b.h - EPS && a.y + a.h > b.y + EPS;
+var LayoutPlan = z2.object({
+  version: Version,
+  beatId: z2.string().min(1),
+  /** Output aspect context (pixels); placement itself is in [0,1] fractions. */
+  frame: z2.object({ w: z2.number().positive(), h: z2.number().positive() }).strict(),
+  /** INPUT (not authored): face keep-out rects at this beat, from the
+   *  composition-floor. The layout stage MUST place `front` elements clear of
+   *  these — carried on the plan so a reviewer/compiler can verify it. */
+  keepOut: z2.array(PlanRect),
+  /** INPUT: safe-zone insets (title-safe / action-safe fractions). */
+  safe: z2.object({
+    titleSafe: z2.number().min(0).max(1),
+    actionSafe: z2.number().min(0).max(1)
+  }).strict(),
+  elements: z2.array(LayoutElement),
+  /** Set when the solver could NOT place a beat's graphic legally (e.g. the
+   *  face fills the legal area). Makes a drop OBSERVABLE — distinct from a
+   *  beat that legitimately had no copy (both yield elements:[]). The producer
+   *  can surface it; the compiler skips it. */
+  dropped: z2.object({ reason: z2.string().min(1) }).strict().optional()
+}).strict().superRefine((plan, ctx) => {
+  for (const el of plan.elements) {
+    if (el.z === "behind-subject") continue;
+    const b = el.box;
+    if (b.x + b.w > 1 + EPS || b.y + b.h > 1 + EPS) {
+      ctx.addIssue({ code: z2.ZodIssueCode.custom, message: `element ${el.elId} box spills past the frame`, path: ["elements"] });
+    }
+    for (const ko of plan.keepOut) {
+      if (rectsOverlapEps(b, ko)) {
+        ctx.addIssue({ code: z2.ZodIssueCode.custom, message: `element ${el.elId} overlaps a face keep-out (text on the speaker)`, path: ["elements"] });
+      }
+    }
+  }
+});
+var EnterType = z2.enum(["reveal", "fade", "rise", "count-up", "wipe"]);
+var EmphasisType = z2.enum(["pulse", "underline", "color-shift"]);
+var ExitType = z2.enum(["fade", "fall", "wipe", "cut"]);
+var Ease = z2.enum(["spring", "ease-out", "ease-in-out", "linear"]);
+var EnterMotion = z2.object({
+  type: EnterType,
+  atMs: z2.number().min(0),
+  durMs: z2.number().positive(),
+  ease: Ease.default("spring"),
+  /** Per-child stagger (ms) for multi-part reveals. */
+  stagger: z2.number().min(0).optional()
+}).strict();
+var EmphasisMotion = z2.object({ type: EmphasisType, atMs: z2.number().min(0), durMs: z2.number().positive() }).strict();
+var ExitMotion = z2.object({ type: ExitType, atMs: z2.number().min(0), durMs: z2.number().positive() }).strict();
+var MotionElement = z2.object({
+  elId: z2.string().min(1),
+  enter: EnterMotion,
+  emphasis: EmphasisMotion.optional(),
+  exit: ExitMotion.optional()
+}).strict();
+var MotionPlan = z2.object({
+  version: Version,
+  beatId: z2.string().min(1),
+  elements: z2.array(MotionElement)
+}).strict();
+var GraphicsPlan = z2.object({
+  version: Version,
+  content: ContentPlan,
+  layouts: z2.array(LayoutPlan),
+  motions: z2.array(MotionPlan)
+}).strict();
+
+export {
+  Format,
+  MediaClipSource,
+  ComponentClipSource,
+  OverlayClipSource,
+  EffectClipSource,
+  AlphaLayerClipSource,
+  CardClipSource,
+  CompositionClipSource,
+  ClipSource,
+  Transition,
+  Region,
+  ClipFit,
+  PerClipEffect,
+  KeyframeEasing,
+  Keyframe,
+  KeyframeChannel,
+  ANIMATABLE_PARAMS,
+  TimelineClip,
+  Gap,
+  TrackContent,
+  Track,
+  Marker,
+  CaptionWord,
+  CaptionStyle,
+  CaptionSegment,
+  CompositionCaptions,
+  captionWords,
+  Composition,
+  CompositionAuthorKind,
+  CompositionVersion,
+  GRAPHICS_PLAN_VERSION,
+  PlanRect,
+  GraphicRole,
+  Copy,
+  ContentBeat,
+  ContentPlan,
+  ElementRole,
+  StyleRole,
+  ZPlane,
+  LayoutElement,
+  LayoutPlan,
+  EnterType,
+  EmphasisType,
+  ExitType,
+  Ease,
+  EnterMotion,
+  EmphasisMotion,
+  ExitMotion,
+  MotionElement,
+  MotionPlan,
+  GraphicsPlan
+};