@cueframe/kernel 0.0.1 → 0.1.1

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

@@ -1,703 +0,0 @@
-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,
-});