@cueframe/kernel 0.0.1

package/dist/_members/composition/validators/composition.js

@@ -0,0 +1,703 @@
+import { z } from "zod";
+import { zid } from "convex-helpers/server/zod3";
+// Re-export the canonical reframe model so consumers importing from
+// `@cueframe/composition/validators` resolve `Focus` / `ReframeSegment` /
+// `Reframe` here (the camera channel lives in ../reframe; this is the wire
+// validator surface). Replaces the deleted subject-centric CropSubject /
+// CropIntentSegment model — there is one viewport primitive now.
+export { Focus, ReframeSegment, ReframeSegmentFields, Reframe } from "../reframe/index";
+import { Reframe } from "../reframe/index";
+export const 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(),
+});
+const Trim = z.object({
+    start: z.number().nonnegative(),
+    end: z.number().nonnegative(),
+});
+const ExcludedRange = z.object({
+    start: z.number().nonnegative(),
+    end: z.number().nonnegative(),
+    reason: z.string().optional(),
+});
+// (CropOverride deleted 2026-05-25 — replaced by baked-variants substrate.
+// Framing decisions now happen at bake time, not render time.)
+//
+// (CropSubject + CropIntentSegment deleted 2026-06-14 — the subject-centric
+// crop model is fully replaced by the canonical `reframe` model. `Focus` is
+// the WHO/WHAT (re-exported above from ../reframe), `ReframeSegment` is the
+// time-aligned camera segment, `Reframe` = { segments } is the camera channel.
+// Field map: subject.kind→focus.mode (shotScale now lives on the `face`
+// focus variant only), zoomScale→zoom (<1 punches in; default 1), verticalBias
+// →bias.y, lateralBias→bias.x (now OPTIONAL, default 0 when read), intent kept.
+// See ~/brain plan 2026-06-14-cropintents-to-reframe-migration.)
+export const 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(),
+});
+export const 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(),
+});
+export const 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(),
+});
+export const EffectClipSource = z.object({
+    kind: z.literal("effect"),
+    primitiveId: z.string().min(1),
+    params: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * An owned `.cueframe` component composited as a BAKED ALPHA video (Task 2.6b).
+ * Per-tenant component code is NEVER run in the shared cloud renderer — it is
+ * baked locally/isolated to an alpha video and composited as trusted pixels. This
+ * variant carries only the AUTHORED truth (the component file + its props + the
+ * composite z-plane). The DERIVED baked-alpha R2 key is a render artifact and
+ * lives in the `renderAssets` envelope (render-assets SSOT), NOT here — the
+ * composition round-trips `Composition.parse` as pure authored intent, and the
+ * alpha is re-baked on edit. zPlane mirrors OverlayClipSource (compose over/under
+ * the subject matte). Lands on overlay tracks.
+ */
+export const 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(),
+});
+/**
+ * A graphic authored as a standalone HTML/CSS fragment, carried VERBATIM into the
+ * render (dangerouslySetInnerHTML) — the storyboard-first medium. Remotion IS
+ * Chromium (probe #1: AE@fuzz-3% = 0 px), so the cheap headless still and the
+ * final Remotion wrap draw the IDENTICAL markup — the port is a WRAPPER, not a
+ * translation. This variant carries the AUTHORED truth only: the markup + an
+ * optional brand-token map. The graphic's output-space keep-out box is the clip's
+ * `region` (on TimelineClip), NOT here. Lands on overlay tracks; zPlane mirrors
+ * OverlayClipSource (front default; behind-subject world-lock is a follow-up).
+ */
+export const 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(),
+});
+/**
+ * COMPOUND CLIP — a clip whose source is another composition.
+ *
+ * The content union was `TimelineClip | Gap` with a CLOSED source union, so a
+ * sequence could never contain a sequence: a reusable segment (an intro, a
+ * lower-third package, last week's cut) had to be flattened by hand into every
+ * composition that wanted it, and edits to the original reached none of them.
+ *
+ * This is deliberately strategic surface, not an NLE luxury: it is the same
+ * shape `derive_composition` / `fromComposition` traffic in — a composition
+ * addressable AS a clip is how "every format from one edit" becomes a
+ * timeline object rather than a workflow.
+ *
+ * `compositionId` is a REFERENCE — the document does not embed the child, so
+ * the child's edits flow through. Resolution (id → Composition) happens at
+ * projection time via a caller-supplied map; the wire stays self-contained.
+ * `trim` selects a window of the child's own timeline, like a media trim.
+ */
+export const CompositionClipSource = z.object({
+    kind: z.literal("composition"),
+    compositionId: z.string().min(1),
+    trim: Trim.optional(),
+}).strict();
+export const ClipSource = z.discriminatedUnion("kind", [
+    MediaClipSource,
+    ComponentClipSource,
+    OverlayClipSource,
+    EffectClipSource,
+    AlphaLayerClipSource,
+    CardClipSource,
+    CompositionClipSource,
+]);
+// AUTHORED_GRAPHIC_KINDS lives in ./graphicKinds (pure, zero-import) so the
+// Temporal workflow bundle can value-import it without dragging this file's
+// convex-helpers (`zid`) edge into the sandbox. Re-exported here for every
+// non-workflow consumer.
+export { AUTHORED_GRAPHIC_KINDS } from "./graphicKinds";
+export const Transition = z.object({
+    type: z.string().min(1),
+    duration: z.number().positive(),
+});
+const Position = z.object({
+    x: z.number(),
+    y: z.number(),
+});
+/** Phase 5 layer model: the single placement primitive — the output-space rect
+ *  (fractions of the output frame, 0..1) a layer occupies. Mirrors the
+ *  composition-floor `Rect` placement vocabulary already used for captions/overlays.
+ *  Default (omitted) = full frame {x:0,y:0,w:1,h:1}. */
+export const 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),
+});
+/** How a layer's source fills its `region`: `cover` (fill + crop, the renderer
+ *  default) or `contain` (letterbox — routed through a designed band, not flat
+ *  black bars). Omitted = `cover`. */
+export const ClipFit = z.enum(["cover", "contain"]);
+/** One entry of a clip's EFFECT channel — a registered effect primitive plus its
+ *  params. Exported because the `setEffects` op reuses this exact wire shape (the
+ *  op vocabulary never re-describes a validator shape with its own z.object). */
+export const PerClipEffect = z.object({
+    primitiveId: z.string().min(1),
+    params: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * KEYFRAMES — a value that changes over a clip's life.
+ *
+ * The composition had NO time-varying model. `TimelineClip` carried scalar
+ * `opacity` / `scale` / `rotation` / `position`, and the only trace of an
+ * intent to animate them was two error codes with no producer
+ * (`invariants/errors.ts`: `varying_keyframe_time_out_of_range`,
+ * `varying_keyframe_duplicate_time`). Two brain docs read
+ * `registry.ts varyingParams` as the model; it is a list of param NAMES a
+ * primitive accepts, not a value over time. So "we sell motion" was true of the
+ * renderer and false of the document.
+ *
+ * TIME IS CLIP-RELATIVE, and that is the load-bearing decision. Absolute
+ * timeline seconds would desync every keyframe on the clip the moment a ripple
+ * moved it — silently, because nothing about the clip itself would look wrong.
+ * Clip-relative time survives moves, ripples and lane changes untouched; only a
+ * TRIM has to think about it.
+ *
+ * VALUES ARE SCALAR in v1. A vector channel like `position` decomposes into
+ * `position.x` / `position.y` without needing a second shape, so nothing is
+ * lost and the interpolator stays one function.
+ *
+ * `cubicBezier` ships from day one even though the UI will only offer named
+ * easings at first — so the curve editor is additive later rather than a
+ * migration of everything authored before it.
+ */
+export const KeyframeEasing = z.union([
+    z.enum(["linear", "ease", "easeIn", "easeOut", "easeInOut"]),
+    z.object({ cubicBezier: z.tuple([z.number(), z.number(), z.number(), z.number()]) }).strict(),
+]);
+export const 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();
+/** A channel needs two points to vary; one point is just a scalar with extra steps. */
+export const KeyframeChannel = z.array(Keyframe).min(2);
+/** Param paths that may be animated. Closed, so a typo fails loud. */
+export const ANIMATABLE_PARAMS = [
+    "opacity",
+    "scale",
+    "rotation",
+    "position.x",
+    "position.y",
+    "volume",
+];
+export const 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(); // unknown top-level keys fail loud (e.g. clips under the wrong key, or
+// `.strict()` is load-bearing, not cosmetic: Track.contents is a structural
+// union `TimelineClip | Gap`. Without strict, a TimelineClip that fails its OWN
+// validation (e.g. `source.reframe.segments[].zoom > 1`) falls through to Gap,
+// whose default `.strip()` silently DROPS `source`/`fit`/`muted`/… and parses
+// the clip as a bare spacer — the projection then skips the sourceless gap and
+// the clip vanishes with no error (a silent data-loss bug). Strict makes a
+// `source`-bearing object fail Gap too, so the union fails loud and the real
+// per-field error (`zoom must be ≤ 1`) surfaces as a 400. Canonical gaps are
+// authored as exactly {id,startTime,duration}; the renderer's `_kind` tag lives
+// in the RenderInput projection, not here, so strict is safe.
+export const Gap = z
+    .object({
+    id: z.string().min(1),
+    startTime: z.number().nonnegative(),
+    duration: z.number().positive(),
+})
+    .strict();
+// Track.contents is a structural union of TimelineClip | Gap. Discrimination is done
+// by the presence of `source`: TimelineClip has it, Gap does not. Consumers narrowing
+// the union should use `'source' in item` rather than tag-based checks.
+// (The renderer's RenderInput projection adds an explicit `_kind` tag — that
+// lives in the projection layer, not the canonical Composition shape.)
+//
+// ROUTE by that discriminator EXPLICITLY rather than a plain
+// `z.union([TimelineClip, Gap])`. A plain union parses valid clips fine, but on
+// FAILURE it surfaces Gap.strict()'s "Unrecognized key(s): 'source'" for a
+// malformed source-bearing clip — burying the clip's REAL field error (e.g. a
+// component source missing `props`) behind a message that reads as if the clip
+// shouldn't carry a source at all (B4: an author "only found the required shape
+// by tracing the validator"). Here a `source`-bearing item is validated ONLY as
+// a TimelineClip, so ITS error (`source.props` required) surfaces; a sourceless
+// item ONLY as a Gap. Single parse; returns the parsed data (defaults preserved).
+export const 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;
+});
+export const 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(); // unknown Track keys fail loud — notably a PUT that puts clips under
+export const 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(); // unknown top-level keys fail loud; marker extensions go through `metadata`.
+const AccessControl = z.object({
+    public: z.boolean().optional(),
+    readerOrgIds: z.array(z.string()).optional(),
+    writerOrgIds: z.array(z.string()).optional(),
+});
+const LicenseDeclaration = z.object({
+    type: z.string().min(1),
+    source: z.string().optional(),
+    notes: z.string().optional(),
+});
+const CompositionAccessibility = z.object({
+    audioDescriptionTrackId: z.string().optional(),
+    captionsTrackId: z.string().optional(),
+    signLanguageTrackId: z.string().optional(),
+    notes: z.string().optional(),
+});
+/**
+ * Word-level caption timing. Mirrors the TS shape in
+ * `@cueframe/core/render/types#CaptionWord` — kept here as a zod schema
+ * so it validates at the wire boundary. Times are millisecond-based to
+ * match `@remotion/captions`. `emphasis: true` opts a word into the
+ * Captions primitive's emphasis styling (separate font/scale/color).
+ */
+export const 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(),
+});
+/**
+ * Caption styling — mirrors `@cueframe/core/render/types#CaptionStyle`.
+ * All fields optional on the wire so the renderer falls back to the
+ * primitive's defaults / brand kit's `captionStyle` per-field.
+ */
+export const 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) — px values are not accepted")
+        .max(15, "captions style.fontSize is PERCENT of composition height (1-15, default 5) — 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(),
+});
+/**
+ * Top-level captions layer on a Composition. Spans the whole timeline
+ * with consistent style — sibling of `tracks` / `markers`, not an
+ * overlay primitive.
+ *
+ * `words` are timeline-aligned milliseconds (NOT source-relative). The
+ * agent / API path slices the source's transcript to the clip window
+ * and re-bases timestamps to t=0 on insert. `style` is optional; the
+ * renderer falls back to brand kit's `captionStyle` then primitive
+ * defaults.
+ */
+/** One caption SEGMENT (a phrase / sentence) — the content unit the agent
+ *  authors AND a hard caption-page boundary at render: the renderer paginates
+ *  within a segment and never pools words across two, so sentence-bounded
+ *  segments (see `splitIntoSentences`) cut captions at sentence ends. Captions
+ *  are FRONT-ONLY; depth ("behind subject") lives on overlays
+ *  (`OverlayClipSource.zPlane`), never on captions. */
+export const CaptionSegment = z.object({
+    words: z.array(CaptionWord),
+});
+/**
+ * PROVENANCE IS REQUIRED. `segments` is a materialized projection, and until
+ * 2026-08-14 it carried no record of where it came from — which is the whole
+ * bug. `useCaptionMaterialization` said so itself: "once segments exist there is
+ * no reliable way to distinguish 'materialized from this doc' from
+ * 'API-authored', and guessing risks destroying" the authored ones. So nothing
+ * dared re-derive, and captions silently outlived the edits that invalidated
+ * them — a real project carried words timed 1940–4400ms inside a 2.4s
+ * composition, with the render reading those stale times.
+ *
+ * `derived` — a projection of a clip's transcript. Anything that changes that
+ * clip (trim, cut, an excluded range, playback rate) MUST re-derive it, and may,
+ * because `from` says exactly what to recompute from.
+ *
+ * `authored` — a human or agent wrote these words. Never rewritten
+ * automatically; the segmentation is a deliberate choice.
+ *
+ * Segments stay MATERIALIZED rather than resolved at read time on purpose:
+ * `compositionToRenderInput(composition, srcUrls)` takes no transcripts, and a
+ * renderer that had to fetch them would stop being self-contained and
+ * deterministic — which the render cache key depends on.
+ */
+export const 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(),
+    }),
+]);
+/** All caption words across the layer's segments, in order — the flattened view
+ *  consumers that don't care about behind use. */
+export function captionWords(c) {
+    return c.segments.flatMap((s) => s.words);
+}
+export const 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 === undefined
+            ? { 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();
+export const CompositionAuthorKind = z.enum(["user", "agent", "import"]);
+export const 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,
+});