@vosjs/studio-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2973 @@
+import { Segment, KeyframeTrack } from '@vosjs/timeline';
+export { Segment } from '@vosjs/timeline';
+import { TimelineEdit } from '@vosjs/shared/timelineEdits';
+import { LaneAdapter } from '@vosjs/editor';
+
+/**
+ * Zoom/pan camera styles — named strategy
+ * presets covering the whole auto-zoom pipeline: how the planner turns clicks
+ * into spans (cluster vs session merging, level clamps, follow default) AND
+ * how the lowering animates the camera (ramp durations, eases, connected-pan
+ * gap, dead-zone follow tuning). One name → one coherent feel.
+ *
+ * The presets are grounded in a measured comparison of the four shipping
+ * strategies (frame-by-frame optical-flow tracking of real exports + source
+ * audits of Recordly/OpenScreen + Cursorful bundle/behavior research):
+ *
+ *  - Cursorful ("glide"): ONE modest zoom (~1.5×) per activity session —
+ *    2+ clicks within a rolling window keep the zoom alive — and the camera
+ *    TRAVELS by panning between focus points while zoomed. Measured zoom ramp
+ *    fits css-bezier(0.26, 0, 0.16, 1): near-zero initial velocity, soft
+ *    landing, zero overshoot. Pan durations scale with distance.
+ *  - Screen Studio "Focused" / Recordly ("focus"): a zoom block per click
+ *    cluster at ~1.8×, spring-settled ramps (~1.5 s in / ~1 s out), direct
+ *    pans across gaps ≤ ~1.35 s, dead-zone cursor follow. The measured
+ *    OpenScreen/Recordly ramp (their bezier filtered through the spring) fits
+ *    css-bezier(0.28, 0.03, 0.09, 1) — that curve IS the family feel.
+ *  - Screen Studio "Smooth" ("cinema"): the same block model, slower and
+ *    more fluid — for content that is watched, not read.
+ *  - "snappy": the studio's original fast cycles, with the defect fixed — the raw
+ *    css-bezier(0.16, 1, 0.3, 1) arrival had an initial velocity 6.25× the
+ *    ramp average (the "jump cut" complaint); competitors always filter that
+ *    curve through a spring. This preset keeps the pace but caps the onset.
+ *  - "cut": Screen Studio's "instant zoom" option — hard cut-in, no glide.
+ *
+ * Style changes are live SET_DATA (the zoom track is data); regenerating
+ * auto spans on a style switch re-plans with the style's planner params while
+ * preserving user-touched ('manual') spans, per the wand contract.
+ */
+
+type ZoomStyleName = 'glide' | 'focus' | 'cinema' | 'snappy' | 'cut' | 'none' | 'keynote' | 'drift';
+/**
+ * The tilt half of a camera style: the Dynamic-tilt
+ * intensity the style ships with, plus optional overrides on the tilt track's
+ * motion constants. A style pick stamps `doc.tiltStyle` with `intensity` and
+ * re-plans auto tilt spans alongside the auto zooms — one name, one coherent
+ * camera sentence (zoom AND lean).
+ */
+interface TiltPersonality {
+    /** Dynamic-tilt intensity this style ships with ('off' = flat card). */
+    intensity: TiltStyleName;
+    /** tilt ramp overrides (seconds); absent = the TILT_RAMP_* constants. */
+    rampIn?: number;
+    rampOut?: number;
+    /** output-time gap ≤ this → swing pose-to-pose (absent = TILT_CHAIN_GAP). */
+    chainGap?: number;
+    /** connected-swing duration (absent = TILT_PAN). */
+    pan?: number;
+}
+interface ZoomStyleParams {
+    /** false = the planner emits nothing (the 'none' style — manual zooms only). */
+    autoZoom: boolean;
+    /** clicks within this many seconds merge into one span (session merge). */
+    clusterGap: number;
+    /** minimum clicks for a cluster to earn a zoom (Cursorful's ≥2 rule). */
+    minClusterClicks: number;
+    /** zoom so the clicked element fills ~this fraction of the frame. */
+    targetFill: number;
+    minLevel: number;
+    maxLevel: number;
+    /** span lead-in before the first click / hold after the last (seconds). */
+    lead: number;
+    hold: number;
+    /** planner emits spans with focusMode 'auto' (cursor-follow camera). */
+    followByDefault: boolean;
+    /** false = typing sessions plan no spans (clicks/dwells still do). */
+    typingZoom: boolean;
+    /** max silence between pings before the typing session ends (seconds). */
+    typingGap: number;
+    /** hold after the last keystroke — the read-what-you-typed beat (seconds). */
+    typingHold: number;
+    /**
+     * Level FLOOR for typing spans, above the style's minLevel: a wide field
+     * (URL bar, dialog search input) fit-clamps to this instead — typing is the
+     * moment being narrated, so it reads a notch punchier than a wide click.
+     */
+    typingMinLevel: number;
+    /** zoom-in ramp duration; arrival lands rampInOverlap into the span. */
+    rampIn: number;
+    rampInOverlap: number;
+    rampOut: number;
+    /** output-time gap ≤ this → pan straight to the next span (no zoom-out). */
+    chainGap: number;
+    /** connected-pan duration. */
+    pan: number;
+    /** arrival ease (zoom-in AND zoom-out). */
+    ease: string;
+    /** connected-pan + follow-recenter ease. */
+    panEase: string;
+    /** recenter when the cursor exits this central fraction of the crop. */
+    followSafeRatio: number;
+    /** seconds the camera takes to glide to a recentered focus. */
+    followRecenter: number;
+    /**
+     * Recenter targets the cursor this many seconds AHEAD of the exit moment
+     * (Cursorful's look-ahead: the camera leads the pointer instead of chasing
+     * a stale position). Sampled from the real track — still deterministic.
+     */
+    followLookahead: number;
+    /** The style's tilt personality — see TiltPersonality. */
+    tilt: TiltPersonality;
+}
+declare const ZOOM_STYLES: Record<ZoomStyleName, ZoomStyleParams>;
+/** The default camera style for new projects (the Cursorful-family strategy). */
+declare const DEFAULT_ZOOM_STYLE: ZoomStyleName;
+/**
+ * Resolve a style name (+ optional per-doc overrides, `doc.zoomParams`) into a
+ * full parameter bundle. Overrides are the "Custom" seam: agents/doc.json can
+ * tune individual params on top of a named preset; the studio shows Custom
+ * while any override is present. Unknown names from hand-edited doc.json fall
+ * back to the default style.
+ */
+declare function resolveZoomStyle(name?: ZoomStyleName, overrides?: Partial<ZoomStyleParams>): ZoomStyleParams;
+/** Picker order + copy for the studio's Camera style control. */
+declare const ZOOM_STYLE_OPTIONS: {
+    name: ZoomStyleName;
+    label: string;
+    hint: string;
+}[];
+
+interface SpeedParams {
+    /** Seconds of no input at all before a stretch counts as idle. */
+    idleMin: number;
+    /** Rate applied to idle stretches. */
+    idleRate: number;
+    /** Seconds a typing session must last to earn a span. */
+    typingMin: number;
+    /** Rate applied to typing passages. */
+    typingRate: number;
+    /** Seconds a scroll run must last to earn a span. */
+    scrollMin: number;
+    /** Rate applied to scroll runs. */
+    scrollRate: number;
+}
+/** Conservative defaults: only stretches nobody wants to watch in real time. */
+declare const DEFAULT_SPEED_PARAMS: SpeedParams;
+/**
+ * An idle gap whose measured frame activity (the digest's per-second
+ * changed-pixel fraction) averages above this is the video PLAYING — the
+ * recording's own playback, a render in progress — not idle. Speeding it up
+ * compresses the payoff. Five real takes (2026-08-25) each had one; the
+ * cursor track alone cannot tell, so this needs the activity witness, and
+ * without one (the studio's ingest) the gap still plans as idle.
+ */
+declare const PLAYBACK_ACTIVITY = 0.1;
+declare function planAutoSpeed(track: readonly CursorEvent[], opts: {
+    durationMs: number;
+    params?: Partial<SpeedParams>;
+    /** Per-SOURCE-second motion bins (0..1) when a digest measured them. */
+    activity?: readonly number[] | null;
+}): SpeedSpan[];
+/**
+ * Scroll runs as [start, last] seconds — the same grouping the speed planner
+ * proposes 2× over, exported for the take digest.
+ */
+declare function scrollRuns(track: readonly CursorEvent[], minLen?: number): [number, number][];
+/**
+ * Idle gaps as [start, end] seconds: no event of ANY kind for ≥ idleMin,
+ * head and tail included — the digest's `idle` moments and the speed
+ * planner's 4× candidates come from this one derivation.
+ */
+declare function idleGaps(track: readonly CursorEvent[], durationS: number, idleMin?: number): [number, number][];
+/** Mean activity over [a, b) source seconds exceeds PLAYBACK_ACTIVITY. */
+declare function isPlayback(activity: readonly number[] | null | undefined, a: number, b: number): boolean;
+
+/** A single input event captured in the page, relative to the recording's t0. */
+interface CursorEvent {
+    /** ms since t0 (recording start). */
+    t: number;
+    /** viewport CSS px. */
+    x: number;
+    y: number;
+    /**
+     * Screen-coordinate CSS px (MouseEvent.screenX/Y) — the mapping anchor for
+     * window/monitor captures, where the viewport is only part of the frame.
+     * Carrying both spaces per event also gives an exact per-event viewport→screen
+     * offset (sx−x, sy−y) for transforming element rects. Absent on old tracks.
+     */
+    sx?: number;
+    sy?: number;
+    /**
+     * `key` is a typing-ACTIVITY ping (throttled): when and where typing is
+     * happening, never what is typed — the payload must not carry key identity
+     * or input contents at any layer. Position/rect follow the `focus`
+     * convention: the focused editable element's center + bounds.
+     */
+    type: 'move' | 'down' | 'up' | 'scroll' | 'focus' | 'key';
+    /** pointer button for down/up (0=left). */
+    button?: 0 | 1 | 2;
+    /** target element bounds at event time — enables element-aware auto-zoom. */
+    rect?: Rect;
+}
+type CursorTrack = CursorEvent[];
+interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Recording metadata needed to map captured pixels ↔ cursor coords ↔ time. */
+interface RecordingMeta {
+    /** device pixel ratio at capture. */
+    dpr: number;
+    /** page/browser zoom at capture. */
+    zoom: number;
+    /** wall-clock origin (Date.now at first frame). */
+    t0: number;
+    durationMs: number;
+    /** captured pixel dimensions. */
+    width: number;
+    height: number;
+    fps: number;
+    /**
+     * The recording's OWN file carries an audio track — unmute preview, mux into
+     * export. After the AT split that track is SYSTEM/tab audio only (it rides
+     * the same stream as the video, sample-aligned by construction); on takes
+     * recorded before the split it is the legacy record-time mic+system mix.
+     */
+    hasAudio?: boolean;
+    /**
+     * A separately-recorded microphone sidecar exists. The mic never
+     * enters the video file — it records through its own audio-only
+     * MediaRecorder so the studio can gain/mute/duck it independently.
+     */
+    hasMic?: boolean;
+    /**
+     * Recorder start skew: wall-clock ms between the main recorder's start and
+     * the mic/cam sidecar recorders' starts (positive = sidecar started later).
+     * Lets the consume path trim/pad a sidecar head instead of assuming t0
+     * equality. Absent on takes without the matching sidecar.
+     */
+    micT0DeltaMs?: number;
+    camT0DeltaMs?: number;
+    /**
+     * Encoded frame dimensions in device px, from the capture track's settings.
+     * `width`/`height` are the CSS-px viewport (the CursorEvent coordinate space);
+     * these are the actual video pixels — same aspect when capture is constrained
+     * to the tab size, but keep both spaces so mapping never assumes it.
+     */
+    captureWidth?: number;
+    captureHeight?: number;
+    /**
+     * The tab viewport changed size mid-take. Capture resolution is fixed for the
+     * whole take, so Chrome letterboxes the resized content — surface a notice.
+     */
+    resizedDuringTake?: boolean;
+    /**
+     * Page URL/title at record start (seeds the browser-bar mock's address pill).
+     * Query/hash are stripped at capture for privacy.
+     */
+    pageUrl?: string;
+    pageTitle?: string;
+    /**
+     * What the frame contains. Absent = 'tab' (back-compat). Non-tab surfaces use
+     * CursorEvent.sx/sy + the geometry rects below to map cursor → capture px
+     * (see normalizeCaptureSpace); tab-only studio features (browser-bar mock,
+     * letterbox notice) are gated off for them.
+     */
+    captureSurface?: 'tab' | 'window' | 'monitor';
+    /**
+     * Target-tab browser-window bounds at record start, screen-coord CSS px
+     * (window.screenX/Y + outerWidth/Height). Anchor for 'window' captures.
+     */
+    windowRect?: Rect;
+    /**
+     * FULL bounds of the display hosting the target window at record start,
+     * screen-coord CSS px (chrome.system.display bounds — the true origin,
+     * including the macOS menu bar; page availLeft/Top only as a fallback).
+     * Anchor for 'monitor' captures; wrong-display shares surface as low
+     * coverage and fall back to no auto-zoom.
+     */
+    screenRect?: Rect;
+    /**
+     * The target window moved or resized during a 'window' take — the single
+     * windowRect anchor can't map the whole track, so the studio drops the
+     * cursor rather than rendering it at stale positions.
+     */
+    windowMovedDuringTake?: boolean;
+    /**
+     * Viewport CSS-px size (innerWidth/Height) of the recorded tab at record
+     * start. On 'window' takes this + windowRect + the cursor events' screen
+     * coords derive the viewport crop that removes the real browser chrome from
+     * the footage (deriveViewportCrop) so the synthetic browser bar applies.
+     */
+    viewport?: {
+        w: number;
+        h: number;
+    };
+    /**
+     * The tab viewport changed size mid-take on a display take (resize, devtools
+     * dock, zoom) — the static viewport crop can't map the whole take, so crop
+     * derivation fails closed.
+     */
+    viewportChangedDuringTake?: boolean;
+    /**
+     * Fraction of a 'window' take during which the target tab's browser window
+     * was the FOCUSED window (chrome.windows.onFocusChanged, pause-gated).
+     * The wrong-window tell that geometry can't provide: cursor events come from
+     * the recorded tab and its window geometry is self-consistent, so sharing a
+     * DIFFERENT window (Finder, another app — even one with identical bounds)
+     * still maps events "in frame". But driving that other window means focusing
+     * it — a low fraction ⇒ the footage isn't the browser window, so cursor
+     * effects and the viewport crop must fail closed (WINDOW_FOCUS_MIN).
+     */
+    windowFocusedFrac?: number;
+    /** Recorder OS (chrome.runtime.getPlatformInfo) — seeds the browser-bar style. */
+    platform?: 'mac' | 'windows' | 'linux';
+    /**
+     * Which recorder produced the artifact. CLI takes synthesize the cursor
+     * track from automation (exact coords, fresh rects, coverage 1 by
+     * construction) and encode WebM; absent means the extension.
+     */
+    producer?: 'extension' | 'cli';
+    /**
+     * The step timeline: when each actions.json step ran, in SOURCE
+     * seconds. This is what makes a cut re-anchorable across re-records — a
+     * span anchored to a step re-times to wherever that step landed in the
+     * new recording (`vos plan --reuse`). CLI takes only; a human recording
+     * has no script and carries none.
+     */
+    steps?: StepSpan[];
+}
+/**
+ * A span's tie to an actions.json step: metadata for `vos plan
+ * --reuse`, which re-times the span onto a NEW recording of the same script
+ * by resolving the step in the new `meta.steps`. NEVER read by lowering —
+ * seconds stay the wire truth (`in`/`out` are always authoritative), so a
+ * human recording with no steps renders identically with or without one.
+ */
+interface StepAnchor {
+    /** The step: its `id` from actions.json when it has one, else its index. */
+    step: string | number;
+    /** Which edge of the step the span's `in` is measured from. Default 'start'. */
+    at?: 'start' | 'end';
+    /** Seconds from that edge to the span's `in` (negative = before it). */
+    offset?: number;
+}
+/** One executed actions.json step's extent in the recording. */
+interface StepSpan {
+    /** index into actions.steps at record time. */
+    step: number;
+    /** the step's own id from actions.json, when it names one — an id lets a
+     *  step move or be reordered without breaking anchors (absent = the index
+     *  is the identity). */
+    id?: string;
+    do: string;
+    selector?: string;
+    /** SOURCE seconds the gesture occupied, [tStart, tEnd]. */
+    tStart: number;
+    tEnd: number;
+    /** the selector never became visible — the gesture did not run. */
+    skipped?: boolean;
+}
+/** Everything the capture extension hands off to the studio. */
+interface RecordingArtifact {
+    /** OPFS key / object URL for the recorded video. */
+    videoKey: string;
+    cursor: CursorTrack;
+    /** object URL for the separately-recorded mic sidecar (the mic/system split). */
+    audioKey?: string;
+    /** object URL for a separately-recorded webcam track (drawn as an editable bubble). */
+    camKey?: string;
+    meta: RecordingMeta;
+}
+/**
+ * Per-span transition speed — how fast the camera/bubble/card moves
+ * into and out of a span's state, as NAMED steps (the category convention:
+ * Screen Studio's speed words, Descript's one knob — never a curve editor).
+ * Multipliers on the lane's own ramp constants, so 'smooth' (absent) is
+ * byte-identical to the pre-feature motion and each lane keeps its feel.
+ * 'instant' is a hard cut: the ramp collapses to the track emitter's 1ms
+ * collision nudge.
+ */
+type TransitionSpeed = 'instant' | 'fast' | 'smooth' | 'slow';
+declare const TRANSITION_SPEED_MULT: Record<TransitionSpeed, number>;
+/** A span's ramp multiplier (absent = 'smooth' = 1, the exact legacy motion). */
+declare function transitionMult(t: TransitionSpeed | undefined): number;
+/**
+ * A speed-change region over a SOURCE-time span (seconds). Footage-anchored
+ * like zoom keyframes — it follows its content through trims/splits, and a
+ * span whose footage is fully cut away simply has no effect (and comes back
+ * if the trim is undone). Non-overlapping (the lane clamps). The lowering
+ * intersects spans with `segments` via @vosjs/timeline `splitBySpeed` into
+ * rated segments; playback, export, and lane display all evaluate those.
+ */
+interface SpeedSpan {
+    /** Stable identity for selection/editing in the timeline UI. */
+    id: string;
+    in: number;
+    out: number;
+    /** Re-record tie to an actions.json step; `in`/`out` stay the truth. */
+    anchor?: StepAnchor;
+    /** Playback rate (> 0): 2 = twice as fast, 0.5 = half speed. */
+    rate: number;
+    /**
+     * The auto-zoom wand contract: 'auto' = planner suggestion
+     * (planAutoSpeed — typing/scroll/idle), replaced by a re-plan; 'manual' =
+     * user/agent work, always preserved. Absent = manual (spans predating the contract).
+     */
+    source?: 'auto' | 'manual';
+}
+/**
+ * Speed-rate bounds. 16 is also Chromium's HTMLMediaElement.playbackRate
+ * ceiling, so preview (native playback) and export (offline resample) can
+ * honor the same range.
+ */
+declare const SPEED_RATE_MIN = 0.1;
+declare const SPEED_RATE_MAX = 16;
+/**
+ * Minimum speed-span length in OUTPUT seconds (the lane converts through the
+ * span's own rate: a 2× span may not shrink below 0.5s of source). A source
+ * floor shrank with the rate — 0.1s of source at 5× was 20ms of screen, a
+ * sliver nobody could grab again.
+ */
+declare const SPEED_SPAN_MIN = 0.25;
+/** Clamp + quantize a speed rate for storage (2 decimals, like "1.75×"). */
+declare function clampSpeedRate(rate: number): number;
+/**
+ * A zoom region over a SOURCE-time span (seconds) — one adjustable clip on the
+ * zoom lane. Footage-anchored like SpeedSpan/CamStyle.window: it follows its
+ * content through trims/splits (a span whose footage is fully cut away renders
+ * nothing, and comes back if the trim is undone; a partially-cut span keeps its
+ * kept extent). Non-overlapping (the lane clamps). The camera ramps in around
+ * `in`, holds `[level, cx, cy]` until `out`, then ramps back to 1× — or pans
+ * straight to the next span when the gap is short (see `zoomTrackFromDoc`).
+ */
+interface ZoomSpan {
+    /** Stable identity for selection/editing (`z{n}` planner, `u{n}` user). */
+    id: string;
+    in: number;
+    out: number;
+    /** Re-record tie to an actions.json step; `in`/`out` stay the truth. */
+    anchor?: StepAnchor;
+    /** zoom level (1 = no zoom), ZOOM_LEVEL_MIN..ZOOM_LEVEL_MAX, 2 decimals. */
+    level: number;
+    /** focus point in normalized [0..1] video-frame coords. */
+    cx: number;
+    cy: number;
+    /** arrival ease (@vosjs/timeline EASINGS name). Absent = the default ramp ease. */
+    ease?: string;
+    /**
+     * Transition speed for THIS span's ramps (in, out, and the pan arriving
+     * here from a chained neighbor). Absent = 'smooth', the camera style's
+     * stock motion; 'instant' is a hard cut.
+     */
+    transition?: TransitionSpeed;
+    /**
+     * 'auto' = the camera follows the cursor through the span (dead-zone
+     * recenter, baked deterministically at lowering — see followFocusEvents);
+     * absent/'manual' = the fixed cx/cy focus.
+     */
+    focusMode?: 'manual' | 'auto';
+    /**
+     * 'auto' = planner suggestion — regenerate replaces these freely, never
+     * 'manual' ones. Any edit gesture promotes the span to 'manual' (OpenScreen's
+     * contract: suggestions are disposable, user work is sacred).
+     */
+    source?: 'auto' | 'manual';
+}
+/** Zoom-level preset chips (OpenScreen-style picker). */
+declare const ZOOM_LEVELS: readonly [1.25, 1.5, 1.8, 2.2, 3.5, 5];
+declare const ZOOM_LEVEL_MIN = 1;
+declare const ZOOM_LEVEL_MAX = 5;
+/** Default level for new/user-created zooms. */
+declare const DEFAULT_ZOOM_LEVEL = 1.8;
+/**
+ * Minimum zoom-span length in OUTPUT seconds (the lane clamps resizes,
+ * converting through the rate in force so the floor is what the eye sees).
+ */
+declare const ZOOM_SPAN_MIN = 0.3;
+/** Clamp + quantize a zoom level for storage (2 decimals, like "1.8×"). */
+declare function clampZoomLevel(level: number): number;
+/**
+ * A tilt region over a SOURCE-time span (seconds) — one adjustable clip on the
+ * tilt lane. Footage-anchored
+ * like ZoomSpan/SpeedSpan: it follows its content through trims/splits and
+ * speed changes (a span whose footage is fully cut away renders nothing, and
+ * comes back if the trim is undone). Non-overlapping (the lane clamps). While
+ * active the card leans to this pose; between spans it returns to the RESTING
+ * FLAT rest pose (there is no static card tilt) — expanded at lowering into an
+ * OUTPUT-time [rx, ry] degree keyframe track (see tiltTrackFromDoc).
+ */
+interface TiltSpan {
+    /** Stable identity for selection/editing (`t{n}` planner, `u{n}` user). */
+    id: string;
+    in: number;
+    out: number;
+    /** Re-record tie to an actions.json step; `in`/`out` stay the truth. */
+    anchor?: StepAnchor;
+    /**
+     * Pose in DEGREES (the CardTilt convention): rx leans the card back/forward,
+     * ry swings it left/right. Gentle values read best (±5..18°).
+     */
+    rx: number;
+    ry: number;
+    /** arrival ease (@vosjs/timeline EASINGS name). Absent = the house tilt ease. */
+    ease?: string;
+    /**
+     * Transition speed for this span's ramps. Absent = 'smooth' (the stock
+     * tilt motion); 'instant' snaps the card to the pose.
+     */
+    transition?: TransitionSpeed;
+    /**
+     * 'auto' = Dynamic-tilt wand suggestion — regenerate replaces these freely,
+     * never 'manual' ones. Any edit gesture promotes the span to 'manual' (the
+     * auto-zoom wand contract).
+     */
+    source?: 'auto' | 'manual';
+}
+/** Hard tilt bound in degrees (schema/lint); UI sliders stay within ±20. */
+declare const TILT_DEG_MAX = 45;
+/** UI slider bound — matches the Card panel's static (rest) tilt sliders. */
+declare const TILT_UI_DEG_MAX = 20;
+/**
+ * Minimum tilt-span length in OUTPUT seconds (the lane clamps resizes). Bigger
+ * than ZOOM_SPAN_MIN because tilt ramps are longer — a pose that can't settle
+ * isn't a pose.
+ */
+declare const TILT_SPAN_MIN = 0.8;
+/** Default pose for user-created spans: a medium three-quarter "showcase" lean. */
+declare const DEFAULT_TILT_POSE: {
+    rx: number;
+    ry: number;
+};
+/** Clamp + quantize a tilt angle for storage (1 decimal, degrees). */
+declare function clampTiltDeg(deg: number): number;
+/**
+ * Dynamic-tilt wand intensity ladder (the category convention — FocuSee ships
+ * Subtle/Default/Strong): the max degrees planAutoTilt will lean per axis.
+ */
+type TiltStyleName = 'off' | 'subtle' | 'medium' | 'strong';
+declare const TILT_INTENSITY_MAX: Record<Exclude<TiltStyleName, 'off'>, number>;
+interface CursorStyle {
+    /**
+     * Draw the cursor dot. Off still keeps the track: auto-zoom cursor-follow
+     * and click effects are independent of whether the dot is painted. Absent
+     * reads as visible (pre-toggle docs).
+     */
+    visible: boolean;
+    /** 0..1 smoothing strength (lerp factor; higher = smoother/laggier). */
+    smoothing: number;
+    /** rendered cursor size in px. */
+    size: number;
+    style: 'default' | 'dot' | 'ring';
+    hideWhenIdle: boolean;
+    clickFx: ClickFxStyle;
+}
+/**
+ * Click-effect styling. Clicks are extracted
+ * at lowering (OUTPUT-anchored — see extractClicks) and drawn by ON_FRAME as a
+ * pure function of t; every field here is a live SET_DATA edit.
+ */
+interface ClickFxStyle {
+    /** ring drawn at the click point ('highlight' glows the clicked element's rect). */
+    style: 'none' | 'ripple' | 'pulse' | 'highlight';
+    /** cursor press dip on real down→up spans — independent of ring style. */
+    press: boolean;
+    intensity: 'subtle' | 'medium' | 'strong';
+    /** resolved hex for rings/glow; 'auto' = neutral white-over-dark-rim. */
+    color: string | 'auto';
+}
+/**
+ * Named intensity levels → resolved multipliers (size/alpha `k`, duration
+ * `dur`), baked into ctx.data at lowering so ON_FRAME needs no registry —
+ * the same pattern as MINIMAL_BAR_THEMES resolving to concrete colors.
+ */
+declare const CLICK_FX_INTENSITY: Record<ClickFxStyle['intensity'], {
+    k: number;
+    dur: number;
+}>;
+/** Webcam bubble overlay — an editable layer composited over the frame. */
+interface CamStyle {
+    visible: boolean;
+    /**
+     * Free placement: the bubble CENTER as frame fractions (the overlay
+     * and zoom cx/cy convention, so positions survive aspect switches). When
+     * present they WIN over `position`; clearing them snaps back to the corner.
+     */
+    x?: number;
+    y?: number;
+    /** corner the bubble is anchored to when x/y are absent. */
+    position: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+    /** bubble diameter as a fraction of frame height (0..1). */
+    size: number;
+    shape: 'circle' | 'rounded';
+    /**
+     * Corner radius in design px for the 'rounded' shape (absent = 18, the
+     * house look; a circle ignores it). Scales with the canvas like every
+     * frame-owned control.
+     */
+    radius?: number;
+    /**
+     * Ring stroke over the bubble edge. Absent = the house ring (3px white at
+     * 0.9 alpha — the pre-existing paint); `width: 0` = no ring.
+     */
+    border?: {
+        width: number;
+        color: string;
+    };
+    /** Bubble shadow. Absent = 'soft', the pre-existing paint. */
+    shadow?: 'none' | 'soft' | 'strong';
+    /** mirror horizontally (selfie view). */
+    mirror: boolean;
+    /**
+     * Show the bubble only during this SOURCE-time span (trimmed on the cam
+     * timeline lane; anchored to footage like zoom keyframes). Absent = always.
+     */
+    window?: Segment;
+}
+/**
+ * A cam pose region over a SOURCE-time span (seconds) — one adjustable clip on
+ * the cam-move lane (MO track: animated cam layouts, the Screen Studio
+ * signature). Footage-anchored like ZoomSpan/TiltSpan: it follows its content
+ * through trims/splits and speed changes (a span whose footage is fully cut
+ * away renders nothing, and comes back if the trim is undone). Non-overlapping
+ * (the lane clamps). While active the bubble holds this pose; outside spans it
+ * rests at the doc's cam style (doc.cam IS the rest pose); spans close together
+ * in output time morph pose-to-pose without returning to rest. Absent pose
+ * fields inherit the rest pose, so a span may move without resizing. Expanded
+ * at lowering into an OUTPUT-time [x, y, size] fraction keyframe track
+ * (camTrackFromDoc) — pure f(t), no springs.
+ */
+interface CamPoseSpan {
+    /** Stable identity for selection/editing (`m{n}` user-created). */
+    id: string;
+    in: number;
+    out: number;
+    /**
+     * Bubble CENTER as frame fractions [0..1] (the cam.x/y and zoom cx/cy
+     * convention — aspect-stable). Absent = the rest pose's center.
+     */
+    x?: number;
+    y?: number;
+    /** Bubble diameter as a fraction of frame height. Absent = the rest size. */
+    size?: number;
+    /** arrival ease (@vosjs/timeline EASINGS name). Absent = the house cam ease. */
+    ease?: string;
+    /**
+     * Transition speed for this span's morphs. Absent = 'smooth' (~0.65s);
+     * 'instant' jump-cuts the bubble to its pose — the Screen Studio layout-cut.
+     */
+    transition?: TransitionSpeed;
+    /**
+     * Reserved for a future auto planner (the wand contract: 'auto' spans are
+     * disposable suggestions). Every studio gesture writes 'manual'.
+     */
+    source?: 'auto' | 'manual';
+}
+/**
+ * Minimum cam-move span length in OUTPUT seconds (the lane clamps resizes).
+ * Between zoom's 0.3 and tilt's 0.8: a bubble move settles faster than a card
+ * pose but still needs its ~0.65s ramp to read as a move, not a jump.
+ */
+declare const CAM_SPAN_MIN = 0.5;
+/** Bubble-size band for pose spans (fractions of frame height; UI + lint). */
+declare const CAM_SIZE_MIN = 0.08;
+declare const CAM_SIZE_MAX = 0.6;
+/** Clamp + quantize a pose size for storage (3 decimals, frame fraction). */
+declare function clampCamSize(size: number): number;
+/** Clamp + quantize a pose center coordinate for storage (3 decimals, [0..1]). */
+declare function clampCamFrac(v: number): number;
+/**
+ * Default pose for user-created cam-move spans: front-and-center, large —
+ * the "talk to camera" moment that is the feature's reason to exist (the
+ * DEFAULT_TILT_POSE philosophy: a new span shows a visible, editable move,
+ * never a no-op).
+ */
+declare const DEFAULT_CAM_POSE: {
+    x: number;
+    y: number;
+    size: number;
+};
+/**
+ * Mock browser chrome drawn as a strip above the video inside the frame card.
+ * Drawn by the compositor (never captured) — the editor-frame pattern every
+ * shot/recorder tool uses. All values travel in `ctx.data.frame` (live T2 edits).
+ */
+interface BrowserBarStyle {
+    kind: 'none' | 'mac-light' | 'mac-dark' | 'windows-light' | 'windows-dark' | 'minimal';
+    /** address-pill text (editable; seeded from the recorded page's URL). */
+    url: string;
+    showUrl: boolean;
+    /** traffic lights (mac) / window buttons (windows). */
+    showControls: boolean;
+    /** bar height in design px (1080-based, same space as padding/radius). */
+    height: number;
+    /**
+     * Minimal-bar color theme — RESOLVED colors (not a palette id) so ON_FRAME
+     * needs no registry lookup (interpreter rule: everything in ctx.data is
+     * self-contained). Absent = the built-in graphite look. Pick from
+     * MINIMAL_BAR_THEMES in the inspector.
+     */
+    theme?: MinimalBarTheme;
+}
+/** Resolved minimal-bar colors. `light` flips the hairline to dark-on-light. */
+interface MinimalBarTheme {
+    id: string;
+    bar: string;
+    pill: string;
+    text: string;
+    light?: boolean;
+}
+/**
+ * Curated minimal-bar palette (Cursorful-style 12 swatches: 6 dark, 6 light).
+ * The first entry matches the built-in default (theme absent).
+ */
+declare const MINIMAL_BAR_THEMES: MinimalBarTheme[];
+/**
+ * A music/SFX clip. OUTPUT-anchored (`start` is final-cut seconds): music and
+ * effects are authored against the cut that remains — unlike zoom keyframes /
+ * cam window, they do NOT follow footage through trims. The mic track stays
+ * source-anchored via the export's segment splice.
+ */
+interface AudioClip {
+    id: string;
+    /** blob URL (or asset URL) of the audio file. */
+    key: string;
+    /** display name (file name or library track title). */
+    name: string;
+    /** placement on the OUTPUT timeline, seconds. */
+    start: number;
+    /** kept span within the source file, seconds (trim). */
+    in: number;
+    out: number;
+    /** full source-file length, seconds — the trim ceiling (set on add). */
+    duration: number;
+    /** linear gain 0..1. */
+    gain: number;
+    /** fade durations, seconds. */
+    fadeIn: number;
+    fadeOut: number;
+    /** loop the [in,out) span to fill `loopLen` output seconds. */
+    loop?: boolean;
+    /** placed output length when looping (≥ span; defaults to the span). */
+    loopLen?: number;
+    /** duck this clip under the mic while speech is detected. */
+    duck?: boolean;
+}
+/** Effective placed length of a clip on the output timeline, seconds. */
+declare function clipLength(clip: Pick<AudioClip, 'in' | 'out' | 'loop' | 'loopLen'>): number;
+/**
+ * Media layer drawn over the CSS `background` and under the card
+ * The flagship option is a vos rendered
+ * to a seamless loop (`vosId` provenance kept for re-bakes + a future live
+ * tier). Video time is OUTPUT-anchored modulo the loop (`bgT = t % duration`)
+ * — trims/speed never retime ambience. Fail-open: while the media loads (or if
+ * it can't), the CSS background underneath still paints — never a black frame.
+ */
+interface BackgroundMedia {
+    kind: 'video' | 'image';
+    /**
+     * Source URL — blob URL (session), /api/assets/{id}/file (saved vos),
+     * https://assets.vos.so/... (pre-baked official), or take-dir relative path
+     * (CLI). Rides the same resolution plumbing as source.videoKey.
+     */
+    key: string;
+    /** Loop length in seconds (video; the bake duration). */
+    duration?: number;
+    /** Provenance: the vos this media was rendered from. */
+    vosId?: string;
+    versionId?: string;
+    /** Poster/thumbnail URL (picker display + reduced-motion; not drawn by the layer). */
+    poster?: string;
+    /** Black scrim over the media, 0..1 — the one legibility dial. */
+    dim: number;
+    /** Blur radius in design px — softens the media behind the card. */
+    blur?: number;
+}
+interface FrameStyle {
+    /** CSS background (gradient/color): always painted — the media underlay/fallback. */
+    background: string;
+    /** Optional media layer (vos loop / image) drawn over the CSS background. */
+    backgroundMedia?: BackgroundMedia | null;
+    padding: number;
+    radius: number;
+    /** shadow strength 0..1. */
+    shadow: number;
+    /** stroke around the card, 0..1 alpha (0 = off). The switch AND the opacity. */
+    border: number;
+    /**
+     * Stroke width in design px (scales with the canvas, like radius), drawn
+     * OUTWARD from the card's edge (a CSS outline) so it never covers footage.
+     * Absent = FRAME_BORDER_WIDTH_DEFAULT, the hairline every take shipped with.
+     */
+    borderWidth?: number;
+    /**
+     * Stroke colour, any CSS colour string. Absent = FRAME_BORDER_COLOR_DEFAULT.
+     * `border` is the alpha it is drawn at, so an opaque colour is correct here.
+     */
+    borderColor?: string;
+    /**
+     * How footage meets an off-ratio frame. 'contain' (default) fits the
+     * whole card inside the padded area, letterboxing onto the background;
+     * 'cover' makes the padded area the card and cover-fills it with footage,
+     * cropped around `focus` — what a 440x280 store tile or a 2.5:1 marquee
+     * demands ("fill the region"). Absent = contain; every existing doc is
+     * byte-identical.
+     */
+    fit?: 'contain' | 'cover';
+    /**
+     * Cover-crop anchor, normalized video-frame fractions (the zoom cx/cy
+     * convention): which point of the footage stays visible when `fit:'cover'`
+     * crops. Absent = center. Ignored under contain.
+     */
+    focus?: {
+        cx: number;
+        cy: number;
+    };
+    aspectRatio: string;
+    browserBar: BrowserBarStyle;
+    /**
+     * Background parallax 0..1: the background media counter-pans subtly
+     * as the zoom camera moves (depth cue). 0/absent = static.
+     */
+    parallax?: number;
+}
+/**
+ * Overlay clips (compositor v2: "elements-shaped data"). Screen-
+ * space clips drawn on the OVERLAY layer (above the card, never tilts, outside
+ * the zoom transform). **OUTPUT-anchored** — trims/speed never retime a title.
+ * The first slice ships `kind: 'text'`; image/video kinds are the next slice and extend this
+ * union without changing the anchoring or transform model.
+ */
+type OverlayKind = 'text' | 'image' | 'video';
+/** Named house text styles — resolved to concrete font/size/color at lowering. */
+type TextOverlayPreset = 'title' | 'caption' | 'label';
+/** Enter/exit transition presets — pure f(t), evaluated in ON_FRAME. */
+type OverlayTransition = 'none' | 'fade' | 'rise';
+/** Text animation vocabulary — entrance presets evaluated per unit. */
+type TextFxKind = 'fade' | 'rise' | 'pop' | 'blur' | 'typewriter';
+type TextFxUnit = 'block' | 'line' | 'word' | 'char';
+type TextFxDirection = 'forward' | 'reverse' | 'center';
+/**
+ * Text entrance animation. When present it OWNS the entrance — the
+ * clip's `enter` string is ignored (a spec with `unit: 'block'` is the
+ * superset of the legacy presets); `exit` stays clip-level. Segmentation is
+ * baked at lowering (deterministic doc-derived data), per-unit progress is
+ * evaluated in ON_FRAME — pure f(t), so scrub/seek/chunk cold-seeks agree.
+ */
+interface TextFxSpec {
+    fx: TextFxKind;
+    /** What animates as one thing (default 'block' — the whole text). */
+    unit?: TextFxUnit;
+    /** Unit start order (default 'forward'; 'center' ripples outward). */
+    direction?: TextFxDirection;
+    /**
+     * Seconds between unit starts. Defaults: typewriter 0.05, other kinds
+     * 0.06 when unit ≠ block, else 0. Clamped at lowering so the whole
+     * entrance fits the clip.
+     */
+    stagger?: number;
+    /** Per-unit seconds (default OVERLAY_TRANSITION_DUR); typewriter ignores it. */
+    duration?: number;
+}
+/**
+ * A pose keyframe on an overlay/object clip (element motion).
+ * `at` is CLIP-LOCAL OUTPUT seconds (0 = the clip's start), so poses ride
+ * along when the clip moves. Values interpolate across the gap between poses
+ * (ease-into per pose, the KeyframeTrack convention); a hold is two identical
+ * poses. The clip's base transform is the value before the first pose, and
+ * absent fields inherit it — a pose may move without resizing. Baked at
+ * lowering into a clip-local keyframe track, sampled in ON_FRAME as pure
+ * f(t): scrub, export and chunked server renders agree by construction.
+ */
+interface MotionPose {
+    /** Clip-local OUTPUT seconds. */
+    at: number;
+    /** Anchor center as frame fractions (the transform.x/y convention). */
+    x?: number;
+    y?: number;
+    /** Scale multiplier (the transform.scale convention). */
+    scale?: number;
+    /** Degrees (the transform.rotation convention). */
+    rotation?: number;
+    /** Opacity MULTIPLIER 0..1 on the clip's own alpha (default 1). */
+    opacity?: number;
+    /** Arrival ease (@vosjs/timeline EASINGS name). Absent = the house motion ease. */
+    ease?: string;
+}
+/** Default pose-to-pose ease: a symmetric in-out (continuous motion between
+ * poses, not a settle — the CapCut/keyframe convention). */
+declare const MOTION_EASE = "power2.inOut";
+interface OverlayTransform {
+    /**
+     * Anchor CENTER as FRACTIONS of the output frame [0..1] (the zoom cx/cy
+     * convention): 0.5/0.5 = frame center at ANY aspect ratio — positions
+     * survive aspect switches (design px did not: the space's width changes
+     * with the aspect, pushing clips off-frame).
+     */
+    x: number;
+    y: number;
+    /** Uniform scale multiplier on the preset size. */
+    scale: number;
+    /** Rotation in degrees (screen-space, about the anchor). */
+    rotation: number;
+}
+interface OverlayClipBase {
+    /** Stable identity for selection/editing in the timeline UI. */
+    id: string;
+    /** OUTPUT-time span (seconds). */
+    start: number;
+    duration: number;
+    transform: OverlayTransform;
+    /** Absent = 'rise' for enter, 'fade' for exit (the house default motion). */
+    enter?: OverlayTransition;
+    exit?: OverlayTransition;
+    /**
+     * Pose keyframes (see MotionPose): the clip's transform animated
+     * over clip-local time, rendered as diamonds on the clip. Optional: absent
+     * lowers byte-identically (no track in data).
+     */
+    motion?: MotionPose[];
+}
+interface TextOverlayClip extends OverlayClipBase {
+    kind: 'text';
+    /** Text content; '\n' breaks lines. */
+    text: string;
+    preset: TextOverlayPreset;
+    /** Font size override in design px (preset default when absent). */
+    size?: number;
+    /** CSS color override (preset default when absent). */
+    color?: string;
+    /**
+     * Font family override — a catalog family name (GET /api/fonts). Unknown
+     * names fail open: used verbatim with the preset stack as fallback.
+     */
+    family?: string;
+    /** Weight override — snapped to the nearest weight the catalog hosts. */
+    weight?: number;
+    /** Synthesized oblique (no italic files are hosted). */
+    italic?: boolean;
+    /** Multi-line alignment within the block (default center). */
+    align?: 'left' | 'center' | 'right';
+    /** Letter spacing in design px at the resolved size (default 0). */
+    letterSpacing?: number;
+    /** Line height multiplier (default OVERLAY_LINE_HEIGHT). */
+    lineHeight?: number;
+    /** Text outline, drawn under the fill. */
+    stroke?: TextOverlayStroke;
+    /** Background pill behind the text block (absent = none). */
+    box?: TextOverlayBox;
+    /** Entrance animation. Absent = the legacy `enter` transition. */
+    fx?: TextFxSpec;
+    /**
+     * Wrap width as a FRACTION of the frame width [0.1..1] (the transform.x
+     * convention — aspect-stable). Absent = no wrapping (lines break only on
+     * explicit \n). Wrapping is greedy over word tokens at measured widths; a
+     * single token wider than the budget gets its own line (no intra-word
+     * breaks). Tokens keep their trailing whitespace, so fx unit sequences
+     * are IDENTICAL wrapped or not — entrances regroup, never recount.
+     */
+    maxWidth?: number;
+}
+interface TextOverlayStroke {
+    /** CSS stroke color. */
+    color: string;
+    /** Stroke width in design px at the resolved size. */
+    width: number;
+}
+/**
+ * Text background pill. Paddings and radius are EMs of the resolved font
+ * size, so the pill scales with the text through size overrides, transform
+ * scale and output resolution alike.
+ */
+interface TextOverlayBox {
+    /** CSS color of the pill. */
+    color: string;
+    /** Extra opacity multiplier on top of the clip's fade alpha (default 1). */
+    opacity?: number;
+    /** Horizontal padding in EMs (default 0.6). */
+    paddingX?: number;
+    /** Vertical padding in EMs (default 0.35). */
+    paddingY?: number;
+    /** Corner radius in EMs (default 0.25); clamped to half the pill height. */
+    radius?: number;
+}
+/**
+ * Image/video overlay (V1b) — a media card on the overlay layer. `key` rides
+ * the same resolution plumbing as source.videoKey / backgroundMedia.key
+ * (blob URL in-session, /api/assets URL saved, take-dir path in CLI takes).
+ * Sized by `width` (fraction of the FRAME width, aspect from the media) ×
+ * transform.scale. Video time is clip-local (t − start), muted (soundtracks
+ * belong to doc.audio), looping optional.
+ */
+interface MediaOverlayClip extends OverlayClipBase {
+    kind: 'image' | 'video';
+    key: string;
+    /**
+     * The card shadow. Absent = 'soft' — the baked look every
+     * doc predating the field renders, so absence lowers byte-identically. 'strong' is the
+     * hero float, 'none' the flat cutout.
+     */
+    shadow?: 'none' | 'soft' | 'strong';
+    /**
+     * An outline stroke drawn over the clipped media edge.
+     * Absent = none. `width` in design px (scales with the canvas like
+     * radius); any CSS color.
+     */
+    border?: {
+        width: number;
+        color: string;
+    };
+    /** Base width as a fraction of the frame width [0..1]. Absent = 0.35. */
+    width?: number;
+    /** Corner radius in design px. Absent = 12 (the house card radius). */
+    radius?: number;
+    /** Opacity 0..1. Absent = 1. */
+    opacity?: number;
+    /** Video only: loop while the clip is active. Absent = hold the last frame. */
+    loop?: boolean;
+}
+type OverlayClip = TextOverlayClip | MediaOverlayClip;
+/**
+ * Ceiling on `transform.scale` for text overlays, shared by the canvas box
+ * and the panel so the two can never disagree about where growth stops (a
+ * 64px title at 8× is a 512px hero word — past that it is a poster, not a
+ * caption). The floor is 0.1 in both places.
+ */
+declare const OVERLAY_SCALE_MAX = 8;
+declare const OVERLAY_MEDIA_DEFAULT_WIDTH = 0.35;
+declare const OVERLAY_MEDIA_DEFAULT_RADIUS = 12;
+/**
+ * World-space object clips (compositor v2). These shapes are
+ * DRAFTED AS THE FUTURE ENGINE SPEC: field names, asset-ref shape, and transform
+ * convention carry to `objects?: ObjectConfig[]` upstream unchanged — today they
+ * run interpreter-side (ON_FRAME reconciles meshes from ctx.data; live
+ * SET_DATA add/remove), and a later engine release swaps the construction site into the engine.
+ *
+ * Conventions (agent-facing units match the rest of the doc):
+ *  - position x/y = FRACTIONS of the frame [0..1] (the overlay/zoom
+ *    convention), z = world units TOWARD the camera from the card plane
+ *    (0 = on the card's depth; 0.5 floats clearly in front).
+ *  - scale = fraction of the FRAME HEIGHT the object's unit size occupies.
+ *  - span (OUTPUT seconds) gates visibility with soft edge fades; absent =
+ *    the whole timeline.
+ */
+type ObjectPrimitiveShape = 'cube' | 'sphere' | 'torus' | 'knot';
+/**
+ * 3D-text material presets — fleet-audited: everything single-sided,
+ * no `dispersion`, transmission only single-sided (the documented
+ * SwiftShader constraints). Resolved to plain material params at lowering.
+ */
+type Text3dMaterial = 'standard' | 'metal' | 'glass' | 'neon';
+type ObjectAsset = 
+/** Curated primitive props — fleet-safe, no asset fetch. */
+{
+    kind: 'primitive';
+    shape: ObjectPrimitiveShape;
+    color?: string;
+}
+/** GLB by key — accepted in the schema for forward compat with the engine spec; loads in a later slice. */
+ | {
+    kind: 'gltf';
+    key: string;
+}
+/**
+ * Extruded 3D text from a hosted typeface JSON. `typeface` is a
+ * catalog slug or family name (GET the list from the typeface catalog;
+ * unknown names fall back to the house face). `depth` is the extrusion as
+ * a fraction of the glyph height (default 0.25); `bevel` defaults on.
+ */
+ | {
+    kind: 'text3d';
+    text: string;
+    typeface?: string;
+    material?: Text3dMaterial;
+    color?: string;
+    depth?: number;
+    bevel?: boolean;
+};
+/** Curated motion presets — pure f(t), deterministic. */
+type ObjectAnimation = 'spin' | 'float';
+/**
+ * A pose keyframe on a 3D object clip (the MotionPose model over
+ * transform3d). `at` is CLIP-LOCAL OUTPUT seconds from the clip's span start
+ * (0 when the clip has no span). Absent fields inherit the base transform3d;
+ * `spin`/`float` presets compose ADDITIVELY on top of the sampled pose.
+ */
+interface MotionPose3D {
+    at: number;
+    /** Frame fractions (the transform3d.x/y convention). */
+    x?: number;
+    y?: number;
+    /** World units toward the camera from the card plane. */
+    z?: number;
+    /** Euler degrees. */
+    rx?: number;
+    ry?: number;
+    rz?: number;
+    /** Fraction of the frame height. */
+    scale?: number;
+    /** Arrival ease (@vosjs/timeline EASINGS name). Absent = the house motion ease. */
+    ease?: string;
+}
+interface ObjectClip {
+    id: string;
+    asset: ObjectAsset;
+    /** OUTPUT-time visibility span; absent = always. */
+    span?: {
+        start: number;
+        duration: number;
+    };
+    transform3d: {
+        x: number;
+        y: number;
+        /** World units toward the camera from the card plane. */
+        z: number;
+        /** Euler degrees. */
+        rx: number;
+        ry: number;
+        rz: number;
+        /** Fraction of the frame height. */
+        scale: number;
+    };
+    animation?: ObjectAnimation | null;
+    /** Pose keyframes (see MotionPose3D). Absent lowers byte-identically. */
+    motion?: MotionPose3D[];
+}
+declare const OBJECT_DEFAULT_SCALE = 0.18;
+/** Enter/exit transition length in seconds (pure f(t) in ON_FRAME). */
+declare const OVERLAY_TRANSITION_DUR = 0.35;
+/** Line height multiplier for multi-line text overlays. */
+declare const OVERLAY_LINE_HEIGHT = 1.25;
+declare const OVERLAY_MIN_DURATION = 0.2;
+/**
+ * The editable project state. An app-level convention that *lowers to* a vos
+ * Composition (it is NOT vos core). Fully serializable.
+ */
+interface ProjectDoc {
+    source: {
+        videoKey: string;
+        cursor: CursorTrack;
+        meta: RecordingMeta;
+        /** object URL for a separately-recorded webcam track, if the take had a camera. */
+        camKey?: string;
+        /**
+         * object URL for the separately-recorded microphone sidecar (AT split).
+         * When present the recording's own audio track (hasAudio) is SYSTEM/tab
+         * audio and micGain governs this sidecar; absent on legacy takes, where
+         * the recording's track is the old record-time mix.
+         */
+        micKey?: string;
+        /**
+         * Decode strategy for the recording (vos VideoElement.frameSource):
+         * 'webcodecs' (frame-accurate, MP4), 'html5' (robust, any format), 'auto'.
+         * Defaults to 'auto' in lowering. Dev uploads use 'html5'; the B2 recorder
+         * (known-good MP4) uses 'webcodecs'.
+         */
+        frameSource?: 'auto' | 'webcodecs' | 'html5';
+        /**
+         * 'image' = videoKey points at a still (screenshot) shown for the doc's
+         * whole duration — the full editing stack (frame, browser bar, zoom, export)
+         * applies unchanged. Defaults to 'video'.
+         */
+        sourceKind?: 'video' | 'image';
+        /**
+         * drawImage source rect (capture px) for window takes: the viewport's rect
+         * inside the captured frame, derived once at doc build (normalizeCaptureSpace)
+         * — crops the real browser chrome out of the footage so the synthetic
+         * browser bar applies. When set, cursor track + meta dims are already in
+         * crop space. Absent = draw the full frame.
+         */
+        crop?: Rect;
+        /**
+         * The derived viewport crop + the full capture dims it was cut from — kept
+         * even while the "Original" frame mode shows the uncropped window, so the
+         * crop can be re-applied losslessly (docToCropSpace/docToFullSpace remap
+         * cursor/zoom/meta between the two spaces; the footage itself always holds
+         * the full frame). Present ⟺ crop derivation succeeded at ingest.
+         */
+        chromeCrop?: {
+            rect: Rect;
+            frameW: number;
+            frameH: number;
+        };
+    };
+    /**
+     * Kept SOURCE-time spans (@vosjs/timeline `Segment`s); the output timeline is
+     * their concatenation — trim/split/cut are all segment edits. Canonical form
+     * is one full-source segment; an empty list is tolerated and means "untrimmed".
+     */
+    segments: Segment[];
+    /**
+     * Speed-change spans (SOURCE time, footage-anchored — see SpeedSpan).
+     * Optional for backward compatibility with persisted docs; absent = all 1×.
+     */
+    speed?: SpeedSpan[];
+    /** Zoom regions (SOURCE time, footage-anchored, non-overlapping — see ZoomSpan). */
+    zoom: ZoomSpan[];
+    /**
+     * Camera style — one named strategy preset driving BOTH the auto-zoom
+     * planner and the camera motion (ramps/eases/pans/follow; see zoomStyle.ts).
+     * Absent = DEFAULT_ZOOM_STYLE.
+     */
+    zoomStyle?: ZoomStyleName;
+    /**
+     * Per-doc overrides on top of the named style — the "Custom" seam for
+     * agents/doc.json (the studio shows Custom while any override is present;
+     * picking a named style clears them). Span edits do NOT set this: the style
+     * describes camera dynamics, spans are content.
+     */
+    zoomParams?: Partial<ZoomStyleParams>;
+    /**
+     * Per-doc overrides for the auto-speed planner: idle/typing/scroll
+     * thresholds and rates. Absent = DEFAULT_SPEED_PARAMS.
+     */
+    speedParams?: Partial<SpeedParams>;
+    /**
+     * Tilt regions (SOURCE time, footage-anchored, non-overlapping — see
+     * TiltSpan). Optional: absent lowers byte-identically (no tiltTrack in data).
+     */
+    tilt?: TiltSpan[];
+    /**
+     * Dynamic-tilt wand intensity (planAutoTilt — the auto-zoom wand contract:
+     * regenerate replaces only `source:'auto'` spans). 'off'/absent = the wand
+     * is off; manual tilt spans work either way.
+     */
+    tiltStyle?: TiltStyleName;
+    /** music/SFX clips on the output timeline (see AudioClip anchoring note). */
+    audio: AudioClip[];
+    /**
+     * Master gain for the VOICE, 0..1. Absent = 1. With a mic sidecar
+     * (source.micKey) this governs the sidecar; on legacy takes it governs the
+     * recording's own (mixed) track.
+     */
+    micGain?: number;
+    /**
+     * Master gain for the recording's own SYSTEM/tab audio track, 0..1. Absent
+     * = 1. Only meaningful on split takes (source.micKey present) — legacy
+     * takes have one track and one fader (micGain).
+     */
+    systemGain?: number;
+    cursor: CursorStyle;
+    cam: CamStyle;
+    /**
+     * Cam pose regions (SOURCE time, footage-anchored, non-overlapping — see
+     * CamPoseSpan). The bubble morphs to a span's pose and back to the rest
+     * pose (doc.cam). Optional: absent lowers byte-identically (no camTrack
+     * in data). Only renders when the take has a cam track (source.camKey).
+     */
+    camMotion?: CamPoseSpan[];
+    frame: FrameStyle;
+    /**
+     * Card presentation (tilt / entrance) — compositor v2. Optional: absent
+     * lowers byte-identically to a pre-v2 doc and renders pixel-identically.
+     */
+    /**
+     * Screen-space overlay clips (text; later image/video) — compositor v2.
+     * OUTPUT-anchored spans on the overlay layer. Optional: absent lowers
+     * byte-identically to a doc predating overlays.
+     */
+    overlays?: OverlayClip[];
+    /**
+     * World-space object clips (interpreter-side; the drafted engine spec).
+     * Optional: absent lowers byte-identically.
+     */
+    objects?: ObjectClip[];
+    export: {
+        resolution: ExportResolution;
+        fps: 30 | 60;
+        format: 'mp4';
+    };
+}
+/** Export quality presets — each names the SHORT edge of the output (see resolveExportSize). */
+type ExportResolution = '720p' | '1080p' | '2k' | '4k';
+declare const EXPORT_SHORT_EDGE: Record<ExportResolution, number>;
+/** Presets in ascending quality order (picker order; recommendedExportResolution walks it). */
+declare const EXPORT_RESOLUTION_OPTIONS: ExportResolution[];
+/**
+ * Default ON (ripple + press, medium, neutral): click emphasis is the point of
+ * the product, and the wrong-window/coverage gates already drop the cursor
+ * track (and with it every click) on takes where effects would misfire.
+ */
+declare const DEFAULT_CLICK_FX: ClickFxStyle;
+declare const DEFAULT_CURSOR_STYLE: CursorStyle;
+declare const DEFAULT_CAM_STYLE: CamStyle;
+declare const DEFAULT_BROWSER_BAR: BrowserBarStyle;
+/**
+ * The frame a NEW take opens on. Once `BACKDROP_DEFAULT_ON`
+ * flips (backdrop.ts), the default is the house loop on its own ground;
+ * until then the brand gradient. Every ingest path spreads this, so the
+ * flip reaches the extension handoff, the in-page recorder, a dropped file
+ * and `vos record` at once; a doc that already carries a frame keeps it.
+ */
+declare const DEFAULT_FRAME_STYLE: FrameStyle;
+/** Border alpha applied when the Frame-border toggle turns on. */
+declare const FRAME_BORDER_DEFAULT = 0.35;
+/**
+ * The border a doc that names no width/colour is drawn with: the hairline
+ * white stroke that was hard-coded in ON_FRAME before the two knobs existed,
+ * so every take made before them renders byte-identically after.
+ */
+declare const FRAME_BORDER_WIDTH_DEFAULT = 1.5;
+declare const FRAME_BORDER_COLOR_DEFAULT = "#ffffff";
+/**
+ * The realistic browser-bar kind matching the recorder's OS — seeds Default
+ * mode so the synthetic chrome looks native to where the take was recorded
+ * (light variants: browsers default light). Windows/Linux get the windows
+ * chrome; when the platform is unknown — a direct upload with no browser
+ * information — we default to macOS.
+ */
+declare function platformBarKind(platform: RecordingMeta['platform']): BrowserBarStyle['kind'];
+/**
+ * Address-pill display text for a recorded page URL: hostname (www. stripped)
+ * plus a non-root path. Empty for non-http(s) or unparsable URLs.
+ */
+declare function pageDisplayUrl(pageUrl: string | undefined): string;
+/** Output aspect-ratio presets (id used as FrameStyle.aspectRatio). Ordered for the picker. */
+interface AspectRatioOption {
+    id: string;
+    label: string;
+}
+declare const ASPECT_RATIOS: AspectRatioOption[];
+/** Numeric width/height ratio for an aspect-ratio id; 'native' resolves from the source meta. */
+declare function aspectRatioValue(id: string, meta: {
+    width: number;
+    height: number;
+}): number;
+/**
+ * Resolve the export pixel dimensions from the chosen aspect ratio + quality. The quality
+ * (`export.resolution`) is the SHORT edge (720/1080/1440/2160), so 16:9 @ 1080p→1920×1080,
+ * 9:16 @ 4k→2160×3840, 1:1 @ 1080p→1080×1080. Dimensions are rounded to even numbers
+ * (H.264 requires it). Unknown values (hand-edited doc.json) fall back to 1080p.
+ */
+declare function resolveExportSize(doc: Pick<ProjectDoc, 'frame' | 'source' | 'export'>, resolution?: ExportResolution): {
+    width: number;
+    height: number;
+};
+/**
+ * The quality-preset → pixels math, free of any document. Every product's
+ * export UI resolves its dimensions through this one function (the shared
+ * ExportDialog included), so a preset name means the same thing everywhere:
+ * before it existed the web app carried three private resolution tables that
+ * disagreed about what "2K" was.
+ */
+declare function exportSizeFor(ratio: number, resolution: ExportResolution): {
+    width: number;
+    height: number;
+};
+
+/**
+ * Capture-space normalization — the single seam that makes window/monitor
+ * recordings look like tab recordings to everything downstream.
+ *
+ * Tab captures record the viewport, so CursorEvent.x/y (viewport CSS px) IS the
+ * cursor space and meta.width/height describes it. For window/monitor captures
+ * the viewport is only part of the frame, so events are mapped into capture
+ * pixels here — once, at doc-build time — using each event's screen coords
+ * (sx/sy) and the geometry sampled at record start. After normalization the
+ * planner, lowering, and composition consume the doc unchanged.
+ *
+ * Window takes additionally get a VIEWPORT CROP when the geometry is clean
+ * (deriveViewportCrop): the real browser
+ * chrome is cut out of the footage at the drawImage seam, the cursor/meta are
+ * rewritten into crop space, and the synthetic browser bar becomes available
+ * exactly as on tab takes. Fail-closed: a wrong crop (chrome sliver, cut page
+ * edge) reads far worse than no crop, so any geometry doubt → no crop.
+ */
+
+interface CaptureNormalization {
+    cursor: CursorTrack;
+    meta: RecordingMeta;
+    /**
+     * Fraction of mapped events that landed inside the captured frame (1 for tab
+     * captures). Low coverage means the user shared a different window/display
+     * than the one hosting the recorded tab — the app should skip auto-zoom and
+     * cursor overlay rather than render them at wrong positions.
+     */
+    coverage: number;
+    /**
+     * Window takes with clean geometry: the viewport's rect inside the capture
+     * frame (capture px) — the drawImage source crop that removes the real
+     * browser chrome. When present, the returned cursor/meta are already in
+     * crop space. Absent = render the full frame.
+     */
+    crop?: Rect;
+}
+/**
+ * Derive the viewport crop for a window take: where the page viewport sits
+ * inside the captured window frame, in capture px.
+ *
+ * Two independent estimators cross-check each other:
+ * 1. event-derived (primary): each event's own viewport→screen offset
+ *    (sx − x, sy − y) — exact wherever the chrome actually is, but needs events;
+ * 2. window-derived: windowRect vs meta.viewport under the chrome-on-top
+ *    assumption (side insets split evenly) — no events needed, but wrong for
+ *    docked devtools / exotic decorations.
+ *
+ * Only offsets agreeing with (2) are kept — this simultaneously validates the
+ * chrome-on-top assumption AND rejects cross-origin-iframe events, whose
+ * offsets are the IFRAME's origin, not the top viewport's. Returns null
+ * (no crop) on any doubt — see the fail-closed matrix in the analysis doc.
+ */
+declare function deriveViewportCrop(cursor: CursorTrack, meta: RecordingMeta): Rect | null;
+/**
+ * Map a cursor track into the capture's pixel space. Identity for tab captures
+ * (or when geometry is missing). For window/monitor captures the returned meta
+ * has width/height set to the capture pixel dimensions (the new cursor space)
+ * and dpr/zoom reset to 1 — cursor space and video pixels now coincide. When a
+ * window take yields a viewport crop, cursor space is the CROPPED frame and
+ * meta dims are the crop dims (downstream layout/planner/zoom need no crop
+ * awareness — only drawImage reads the rect).
+ */
+declare function normalizeCaptureSpace(cursor: CursorTrack, meta: RecordingMeta): CaptureNormalization;
+/** Coverage below this → treat the cursor track as unusable (skip auto-zoom + overlay). */
+declare const CAPTURE_COVERAGE_MIN = 0.5;
+/**
+ * Window takes whose browser window was focused for less than this fraction of
+ * the take are treated as wrong-window shares: cursor track dropped, no
+ * viewport crop (see RecordingMeta.windowFocusedFrac).
+ */
+declare const WINDOW_FOCUS_MIN = 0.5;
+/**
+ * Crop-space ↔ full-space doc remaps — the "Original" frame mode (show the
+ * user's real browser chrome on a cropped window take). The footage always
+ * holds the full frame, so the toggle is a LOSSLESS coordinate remap of the
+ * doc (cursor events/rects, zoom focus points, meta dims) driven by the
+ * chromeCrop record kept from ingest — one undoable patch-store edit, program
+ * string untouched (everything involved lowers into ctx.data). Time-based
+ * state (segments, speed, audio, cam window) is space-independent.
+ *
+ * Both helpers MUTATE a draft doc (call inside the store's edit()) and are
+ * no-ops when the doc is already in the requested space or has no chromeCrop.
+ */
+/** Remap a crop-space doc to full-capture space (show the original chrome). */
+declare function docToFullSpace(d: ProjectDoc): void;
+/** Remap a full-space doc back into crop space (hide the chrome again). */
+declare function docToCropSpace(d: ProjectDoc): void;
+
+/** Build a ProjectDoc from a RecordingArtifact handed off by a recorder. */
+declare function projectFromArtifact(artifact: RecordingArtifact, videoUrl: string): {
+    doc: ProjectDoc;
+    videoUrl: string;
+};
+
+/**
+ * Hosted-doc schema versioning: the scoped reversal of "ProjectDocs
+ * are never persisted" is hosted versions only, and every persisted doc is
+ * stamped `docSchemaVersion` from day one so the migration obligation the
+ * old rule avoided stays bounded to one seam — migrate-on-read, here.
+ *
+ * Local studio sessions still never persist docs; CLI take dirs carry
+ * doc.json under `schema/doc.schema.json` (which tolerates the stamp via
+ * additionalProperties). Both hydration paths (studio handback, `vos
+ * pull`) run through migrateHostedDoc before trusting a hosted doc.
+ */
+/**
+ * 2 = the document FAMILY era: a doc is a recording document (`source`)
+ * or a program document (`program.config`). A v1 doc IS a recording document,
+ * field for field, so 1 → 2 is a stamp; 0 → 1 was a stamp too.
+ */
+declare const DOC_SCHEMA_VERSION = 2;
+/**
+ * Upgrade a hosted doc.json payload to the current schema version.
+ * Unstamped docs are v0 — the pre-stamp era. Every step so far is a stamp
+ * (a post-v1 doc field is optional by doctrine, and v2 only widened the
+ * family), so migration is structural identity. A real shape change chains
+ * its step here.
+ */
+declare function migrateHostedDoc(raw: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * The studio document family.
+ *
+ * A document is an ANCHOR plus the layers every anchor shares. `ProjectDoc`
+ * is the recording-anchored member, field for field what it always was (its
+ * wire, `doc.json`, does not move). `ProgramAnchorDoc` is the program-anchored
+ * member: its anchor IS the user's config — the execution IR, untouched
+ * — plus the tween-timing overlay that used to live only in a
+ * hook. The shared layers are optional on it until the shared modules activate them.
+ *
+ * Discriminated on `source`: every recording doc carries one, no program doc
+ * may.
+ */
+/** One entry of the tween-timing overlay — `@vosjs/tween`'s `TweenEdit`, structurally. */
+interface ProgramTweenEdit {
+    index: number;
+    startTime?: number;
+    duration?: number;
+    ease?: string;
+    to?: Record<string, number>;
+    from?: Record<string, number>;
+}
+interface ProgramAnchorDoc {
+    program: {
+        /** THE user's config, as authored (functions as strings). Never composed here. */
+        config: Record<string, unknown>;
+        /** Retimes over the config's recorded tweens, by spec index. */
+        tweenEdits?: Record<number, ProgramTweenEdit>;
+        /** The anchor's own length when the config's is a placeholder. */
+        duration?: number;
+    };
+    overlays?: OverlayClip[];
+    objects?: ObjectClip[];
+    /** Required, like the recording's: the audio module and its lane read it without a guard. Minted `[]`. */
+    audio: AudioClip[];
+    /** Retime spans over the ANCHOR's clock: the recording's type, `in`/`out` in program seconds. */
+    speed?: SpeedSpan[];
+    export?: ProjectDoc['export'];
+}
+type StudioDoc = ProjectDoc | ProgramAnchorDoc;
+type AnchorKind = 'recording' | 'program';
+declare const anchorKindOf: (doc: StudioDoc) => AnchorKind;
+declare const isRecordingDoc: (doc: StudioDoc) => doc is ProjectDoc;
+declare const isProgramDoc: (doc: StudioDoc) => doc is ProgramAnchorDoc;
+/** A program anchor's own length in seconds: `program.duration`, else the config's. */
+declare function programDuration(doc: ProgramAnchorDoc): number;
+/**
+ * The anchor's SOURCE length: the footage's for a recording, the
+ * program's own for a program. Speed spans, segments and every source-time
+ * floor measure against it.
+ */
+declare function anchorSourceDuration(doc: StudioDoc): number;
+
+/**
+ * Cursor smoothing.
+ *
+ * Raw pointer samples are jittery and irregularly spaced. We resample to a fixed
+ * cadence and apply an exponential lerp — counterintuitively, linear smoothing
+ * beats ease-in-out for cursors (easing stutters between samples). Pure and
+ * deterministic: same input → same output.
+ */
+
+interface SmoothPoint {
+    /** seconds. */
+    t: number;
+    x: number;
+    y: number;
+}
+interface SmoothOptions {
+    /** lerp factor per step, 0..1 (higher = smoother/laggier). Default 0.15. */
+    factor?: number;
+    /** resample cadence in fps. Default 60. */
+    fps?: number;
+    /**
+     * Pull the smoothed path onto each click's true position around the click
+     * instant: click effects anchor at the
+     * click point, so the (laggy) smoothed cursor must arrive on time or the
+     * ring blooms away from the dot. The pull feeds back into the lerp state,
+     * so the path continues from the click point afterwards. Deterministic.
+     */
+    clickSnap?: boolean;
+}
+/**
+ * Produce a smoothed, fixed-cadence cursor path (in seconds) from a raw track.
+ * Only `move`/`down`/`up` events carry positions; others are ignored here —
+ * `scroll` re-emits a stale point, and `focus`/`key` synthesize element
+ * centers the cursor never visited (letting those in would teleport the dot).
+ */
+declare function smoothCursor(track: CursorTrack, options?: SmoothOptions): SmoothPoint[];
+
+/**
+ * A click cluster whose element FITS the frame at less than this level is
+ * not a target: it is a drag (aiming, scrubbing, moving a thing across the
+ * canvas) or a frame-sized surface, and a zoom on it says nothing. Five real
+ * takes (2026-08-25) each carried 1-4 such clusters, planned at the floor
+ * level for 10-25s; every one was dropped by hand. Now they plan nothing.
+ */
+declare const DRAG_FIT_LEVEL = 1.15;
+interface PlanOptions {
+    /** captured frame size (for normalizing rects → [0..1] focus points). */
+    width: number;
+    height: number;
+    /**
+     * Camera style whose planner params seed every default below (zoomStyle.ts).
+     * Explicit options still win. Absent = DEFAULT_ZOOM_STYLE.
+     */
+    style?: ZoomStyleName;
+    /** per-doc overrides on top of the style (doc.zoomParams — the Custom seam). */
+    params?: Partial<ZoomStyleParams>;
+    /** target: zoom so the element fills ~this fraction of the frame. */
+    targetFill?: number;
+    /** clamp zoom level. */
+    minLevel?: number;
+    maxLevel?: number;
+    /** clicks within this many seconds merge into one zoom (session merge). */
+    clusterGap?: number;
+    /** span lead-in before the first click + hold after the last. */
+    lead?: number;
+    hold?: number;
+    /** minimum clicks for a cluster to earn a zoom (Cursorful's ≥2 rule). */
+    minClusterClicks?: number;
+    /** emit spans with focusMode 'auto' (cursor-follow camera). */
+    followByDefault?: boolean;
+    /** typing sessions plan spans. */
+    typingZoom?: boolean;
+    /** max silence between `key` pings before the typing session ends. */
+    typingGap?: number;
+    /** hold after the last keystroke (the read-what-you-typed beat). */
+    typingHold?: number;
+    /** level floor for typing spans (a wide field still reads punchier). */
+    typingMinLevel?: number;
+}
+declare function planAutoZoom(track: CursorTrack, options: PlanOptions): ZoomSpan[];
+
+/** Zoom spans shorter than this (OUTPUT seconds) get no tilt — a pose that
+ * can't settle before the zoom leaves reads as wobble, not emphasis. */
+declare const TILT_AUTO_MIN = 1.2;
+/** Focus offsets under this (|cx−0.5| fraction) don't tilt that axis — a
+ * centered zoom keeps the pure push-in feel; tilt is for off-center focus. */
+declare const TILT_AUTO_DEAD_ZONE = 0.12;
+interface PlanTiltOptions {
+    /** Intensity ladder — max degrees per axis (TILT_INTENSITY_MAX). */
+    intensity: Exclude<TiltStyleName, 'off'>;
+}
+/**
+ * One tilt span per qualifying zoom span, SAME source extents (the tracks
+ * ramp/chain together), pose aimed at the zoom's focus. Spans whose footage
+ * is cut away, whose output run is too short, or whose focus is centered
+ * (both axes inside the dead zone) emit nothing.
+ */
+declare function planAutoTilt(zoom: readonly ZoomSpan[], segments: Segment[], options: PlanTiltOptions): TiltSpan[];
+
+type MomentKind = 'head' | 'tail' | 'click' | 'typing' | 'scroll' | 'dwell' | 'idle' | 'scene';
+/** A rect in normalized [0..1] frame fractions (the zoom cx/cy convention). */
+interface NormRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface Moment {
+    id: string;
+    kind: MomentKind;
+    /** Footage seconds. Instants (scene/head/tail) have in === out. */
+    source: {
+        in: number;
+        out: number;
+    };
+    /** The same window in OUTPUT seconds, null when trimmed away. */
+    output: {
+        in: number;
+        out: number;
+    } | null;
+    /** The source instant the digest frames (null = no frame, e.g. idle). */
+    at: number | null;
+    /** `at` mapped to output time (null when cut or frameless). */
+    outputAt: number | null;
+    /** Normalized focus — copy into a ZoomSpan's cx/cy. */
+    focus: {
+        cx: number;
+        cy: number;
+    } | null;
+    /** Normalized target bounds (element rect union), when the events had one. */
+    rect: NormRect | null;
+    clicks?: number;
+    pings?: number;
+    /** Motion in the window, 0..1 (fraction of changed pixels), null without frames. */
+    activity: number | null;
+    /** Planner spans (from `plan`) that cover this moment, by id. */
+    proposed: {
+        zoom?: string;
+        speed?: string;
+        tilt?: string;
+    };
+    /** Transcript text over the window, when a transcript was merged. */
+    said: string | null;
+}
+interface DigestPlan {
+    zoom: ZoomSpan[];
+    speed: SpeedSpan[];
+    tilt: TiltSpan[];
+}
+interface TranscriptSegment {
+    /** SOURCE seconds (the recording's own clock). */
+    start: number;
+    end: number;
+    text: string;
+}
+interface MomentsOptions {
+    /** Per-SOURCE-second motion bins (0..1) from the frame-diff pass. */
+    bins?: readonly number[] | null;
+    /** Source seconds of visual scene changes (see scenes.ts). */
+    scenes?: readonly number[];
+    transcript?: readonly TranscriptSegment[] | null;
+    /** Idle threshold (seconds); defaults to the speed planner's. */
+    idleMin?: number;
+}
+/**
+ * The three planners, run fresh under the doc's own style — the proposals.
+ * With activity bins (a digest's decode pass), the speed planner can tell
+ * playback from idle.
+ */
+declare function planForDigest(doc: ProjectDoc, activity?: readonly number[] | null): DigestPlan;
+declare function momentsFromDoc(doc: ProjectDoc, plan: DigestPlan, opts?: MomentsOptions): Moment[];
+
+/**
+ * Scene changes from the digest's motion bins: a SOURCE second whose
+ * changed-pixel fraction jumps past `motion` after a second at or below
+ * `quiet` is a scene — a navigation, a dialog, a page swap. A luma diff, not
+ * a scene detector: a video playing inside the page is a permanent change,
+ * and the moment kind says `scene`, never "navigation" — the agent looks at
+ * the frame to say what it was.
+ */
+interface SceneOptions {
+    /** Changed-pixel fraction that reads as a change. */
+    motion?: number;
+    /** The bin before must be at or below this. */
+    quiet?: number;
+}
+/**
+ * Calibrated on a dark-theme CLI take (launch-d2, 2026-08-25): a page swap
+ * moved 0.33–0.36 of a 64×36 luma thumb, a click's own ripple ≤0.03 — so a
+ * quarter of the pixels is a scene and a tenth is still quiet.
+ */
+declare const SCENE_MOTION = 0.25;
+declare const SCENE_QUIET = 0.1;
+declare function sceneChanges(bins: readonly number[], opts?: SceneOptions): number[];
+
+interface CardLayout {
+    /** canvas size the layout was computed for (comp px). */
+    W: number;
+    H: number;
+    /** video destination rect, comp px. Contain: the fitted video. Cover
+     *  the cover-scaled video, positioned by frame.focus — it can
+     *  overflow the card, which crops it. */
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+    /** card rect = browser-bar strip + footage area — what the zoom must keep
+     *  covering. Contain: cardX/cardW equal dx/dw. Cover: the padded area
+     *  itself, which the video rect overflows. */
+    cardX: number;
+    cardY: number;
+    cardW: number;
+    cardH: number;
+}
+/**
+ * Mirror of ON_FRAME's destination-rect math (see the "video destination rect"
+ * block in lowerToComposition's ON_FRAME string). `video` is the source's
+ * pixel size — only its aspect matters (contain-fit scales it).
+ */
+declare function computeCardLayout(frame: FrameStyle, video: {
+    width: number;
+    height: number;
+}, W: number, H: number): CardLayout;
+/**
+ * The doc's card layout at design size (H = 1080, W from the output aspect).
+ * All layout terms scale linearly with the canvas at a fixed aspect, so the
+ * normalized focus bounds computed from this layout hold at ANY render size.
+ *
+ * Viewport-cropped window takes need no special casing here: normalization
+ * rewrote meta.captureWidth/Height to the CROP dims, which is exactly what
+ * ON_FRAME uses as source dims when `d.crop` is set (crp.w/crp.h) — the
+ * golden contract holds through the crop.
+ */
+declare function docCardLayout(doc: Pick<ProjectDoc, 'frame' | 'source'>): CardLayout;
+/**
+ * Largest export preset whose footage card still gets ≥1 captured px per output
+ * px. The composited chrome (background, bar, cursor, effects) is vector-drawn
+ * and real at any size; the footage layer is bounded by capture pixels, so
+ * presets above this one upscale the footage (the picker labels them, never
+ * hides them). Judged on the width of
+ * the contain-fitted card at each preset's output size vs meta.captureWidth
+ * (crop-space when a viewport crop applies — ingest rewrote meta to crop dims).
+ * Floors at the smallest preset for tiny captures.
+ */
+declare function recommendedExportResolution(doc: Pick<ProjectDoc, 'frame' | 'source' | 'export'>): ExportResolution;
+interface CamBubbleRect {
+    /** top-left corner of the bubble's square, design px (docCardLayout space). */
+    x: number;
+    y: number;
+    /** the square's side — the bubble diameter. */
+    size: number;
+    /** corner radius (size/2 for circles, the fixed rounded radius otherwise). */
+    radius: number;
+}
+/**
+ * Host-side mirror of ON_FRAME's webcam-bubble geometry (the "webcam bubble"
+ * block in lowerToComposition) — the picking oracle for the on-canvas cam
+ * layer. Same design space as docCardLayout (H = 1080), and like ON_FRAME the
+ * bubble is FRAME-owned chrome: everything scales by s = H/1080, never the
+ * card-chrome cf. The bubble ignores card tilt/zoom (it paints on the
+ * screen-space overlay plane), so this rect is valid under any camera pose.
+ * camDraw.test.ts pins this to the painted geometry — change them TOGETHER.
+ */
+declare function camBubbleRect(cam: CamStyle, W: number, H?: number): CamBubbleRect;
+interface FocusBounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/**
+ * Focus bounds (normalized video coords) so the zoomed CARD covers the whole
+ * canvas — the crop never reveals background past a card edge at full zoom.
+ *
+ * Derivation: ON_FRAME's transform maps content point p → f + (p − f)·L around
+ * the focus anchor f (fx = dx + zx·dw), so the visible canvas [0, V] shows
+ * content [f − f/L, f + (V − f)/L]. Requiring that window ⊆ the cover range
+ * [o, o + c] and solving for the anchor (k = 1 − 1/L):
+ *
+ *   f ≥ o / k          and          f ≤ (o + c − V/L) / k
+ *
+ * When the zoomed card is too small to cover the canvas (low level + padding),
+ * the bounds cross — collapse to their midpoint (the least-uncovered focus;
+ * 0.5 for a centered card, matching OpenScreen's margin collapse).
+ */
+declare function focusBounds(level: number, layout: CardLayout): FocusBounds;
+/** Clamp a focus point into the bounds for its zoom level. */
+declare function clampFocus(cx: number, cy: number, level: number, layout: CardLayout): {
+    cx: number;
+    cy: number;
+};
+/**
+ * The zoom level a focus rect of this canvas-fraction size
+ * means — the aiming rect's size is purely 1/level, so a corner drag IS a
+ * level drag, and this is the inverse. Floored a hair above the identity so
+ * a drag can never reach level ≈ 1 and dismiss the aiming rect mid-gesture;
+ * clamped and quantized like every stored level (clampZoomLevel).
+ */
+declare function levelForFocusFraction(frac: number): number;
+
+interface ZoomWindow {
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+}
+/** The visible window in normalized video coords at `level` around the focus. */
+declare function zoomWindow(span: {
+    level: number;
+    cx: number;
+    cy: number;
+}, layout: CardLayout): ZoomWindow;
+/**
+ * True when the rect (normalized) sits inside the zoom's visible window, with
+ * `tol` of slack per edge (frame fractions). A level ≤ 1 zoom shows the whole
+ * frame and covers everything.
+ */
+declare function zoomCoversRect(span: {
+    level: number;
+    cx: number;
+    cy: number;
+}, rect: NormRect, layout: CardLayout, tol?: number): boolean;
+
+/**
+ * Style as DATA: the fields of a signed-off take's doc that ARE its
+ * style — camera, speed, tilt personality, frame, cursor, cam bubble, export.
+ * `copyStyle` carries them onto another take deterministically, so a series
+ * shares them by construction and the recipe (CUT.md) only has to say what a
+ * number cannot. Never the spans, overlays or audio: those are the cut.
+ */
+
+declare const STYLE_FIELDS: readonly ["zoomStyle", "zoomParams", "speedParams", "tiltStyle", "frame", "cursor", "cam", "export"];
+type StyleField = (typeof STYLE_FIELDS)[number];
+/** The style fields present on a doc, deep-cloned. */
+declare function pickStyle(doc: ProjectDoc): Partial<Pick<ProjectDoc, StyleField>>;
+/**
+ * A new doc: `to` with `from`'s style fields. A field absent on `from` is
+ * removed from the result (the seed's absence is a choice — the default).
+ */
+declare function copyStyle(from: ProjectDoc, to: ProjectDoc): ProjectDoc;
+
+/**
+ * The digest's crop geometry, pure and shared by the CLI's page and
+ * the fleet's page: cursor/meta coords are CSS px of the viewport (or the
+ * crop space when `source.crop` is set); the frame is capture px. A window
+ * take's crop applies to the FRAME, never to the already-cropped cursor
+ * coords. Both hosts compute boxes here so the two never drift by a dpr.
+ */
+
+interface PxRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A crop box is at least this fraction of the frame width (floor 320px). */
+declare const CROP_MIN_FRAC = 0.25;
+declare const CROP_MIN_PX = 320;
+declare const CROP_MAX_PX = 1024;
+declare const CROP_PAD = 0.25;
+/** Default long edges (px) of the emitted images — the agent's token budget. */
+declare const DIGEST_FULL_MAX = 960;
+declare const DIGEST_CROP_MAX = 640;
+/** Changed-pixel threshold (luma, 0..255) for the motion bins. */
+declare const MOTION_DELTA = 24;
+interface FrameGeometry {
+    /** The region of the frame the doc renders (the viewport crop, or all). */
+    region: PxRect;
+    /** Cursor px → frame px. */
+    scale: number;
+}
+/** The frame's pixel size when no decode has told us: capture px, else CSS×dpr. */
+declare function expectedFrameSize(doc: ProjectDoc): {
+    width: number;
+    height: number;
+};
+declare function frameGeometry(doc: ProjectDoc, frameW: number, frameH: number): FrameGeometry;
+/** The crop box (frame px) around a moment's rect or focus point, or null. */
+declare function cropBox(m: Pick<Moment, 'rect' | 'focus'>, geo: FrameGeometry, meta: {
+    width: number;
+    height: number;
+}): PxRect | null;
+
+declare const DIGEST_VERSION = 1;
+interface DigestImageRef {
+    full: string | null;
+    crop: string | null;
+    /** The crop's source box in FRAME px (what `crop` shows). */
+    box: PxRect | null;
+    fullSize?: {
+        width: number;
+        height: number;
+    } | null;
+    cropSize?: {
+        width: number;
+        height: number;
+    } | null;
+}
+interface DigestTakeFacts {
+    sourceDuration: number;
+    outputDuration: number;
+    width: number;
+    height: number;
+    captureWidth: number | null;
+    captureHeight: number | null;
+    frameWidth: number | null;
+    frameHeight: number | null;
+    surface: string;
+    producer: string;
+    pageUrl: string | null;
+    pageTitle: string | null;
+    hasMic: boolean;
+    hasSystemAudio: boolean;
+    hasCursor: boolean;
+    windowFocusedFrac: number | null;
+}
+interface Digest {
+    digestVersion: number;
+    take: DigestTakeFacts;
+    units: {
+        source: 'seconds of footage';
+        output: 'seconds of the rendered video (trims and speed applied)';
+        focus: 'fractions of the video frame [0..1], the zoom cx/cy convention';
+        activity: 'fraction of pixels that changed, per SOURCE second';
+    };
+    moments: (Moment & {
+        full: string | null;
+        crop: string | null;
+        box: PxRect | null;
+    })[];
+    activity: number[] | null;
+    plan: DigestPlan;
+    doc: {
+        manual: {
+            zoom: number;
+            speed: number;
+            tilt: number;
+            overlays: number;
+        };
+        zoomStyle: string | null;
+        tiltStyle: string | null;
+    };
+    style: {
+        from: string;
+        fields: Record<string, unknown>;
+    } | null;
+    transcript: TranscriptSegment[] | null;
+    images: {
+        full: number;
+        crop: number;
+        sheet: string | null;
+        tokensEstimateClaude: number;
+    };
+}
+interface BuildDigestInput {
+    doc: ProjectDoc;
+    plan: DigestPlan;
+    moments: Moment[];
+    outputDuration: number;
+    bins: number[] | null;
+    frame: {
+        width: number;
+        height: number;
+    } | null;
+    images: Map<string, DigestImageRef>;
+    sheet: string | null;
+    style?: {
+        from: string;
+        doc: ProjectDoc;
+    } | null;
+    transcript?: readonly TranscriptSegment[] | null;
+}
+declare function buildDigest(input: BuildDigestInput): Digest;
+/** OUTPUT seconds of a doc: its kept footage through the rate map. */
+declare function outputDurationOf(doc: ProjectDoc): number;
+
+/** Map an OUTPUT-time range to SOURCE seconds through the doc's rate map. */
+declare function outputRangeToSource(doc: StudioDoc, t0: number, t1: number): {
+    srcIn: number;
+    srcOut: number;
+};
+/**
+ * Re-rate a SOURCE range: spans overlapping it are trimmed (a span split in
+ * two mints a fresh id for the second half), then a manual span at `rate`
+ * covers the range. `rate: null` just clears — the 1× chip.
+ */
+declare function setSpeedInRange(spans: readonly SpeedSpan[], srcIn: number, srcOut: number, rate: number | null): SpeedSpan[];
+/** The Remove chip: drop every span the range touches, whole. */
+declare function removeSpeedInRange(spans: readonly SpeedSpan[], srcIn: number, srcOut: number): SpeedSpan[];
+/**
+ * The Cut chip: subtract a SOURCE range from the kept segments. Segment
+ * order (and any reorder) is preserved; a remainder below MIN_SEGMENT is
+ * dropped with its parent. Never empties the take: cutting everything
+ * returns the original list unchanged.
+ */
+declare function removeSourceRange(segments: readonly Segment[], srcIn: number, srcOut: number): Segment[];
+/**
+ * The Zoom chip: a manual zoom span covering as much of the range as the
+ * lane's non-overlap rule allows — clipped against existing spans, starting
+ * at the first free moment inside the range. Null when the free room is
+ * below the zoom floor (the chip greys out).
+ */
+declare function zoomSpanForRange(zoom: readonly ZoomSpan[], srcIn: number, srcOut: number): ZoomSpan | null;
+
+/** Legacy defaults (= the default style's values); prefer FollowOptions. */
+declare const FOLLOW_SAFE_RATIO: number;
+declare const FOLLOW_RECENTER: number;
+interface FollowOptions {
+    /** recenter when the cursor exits this central fraction of the crop. */
+    safeRatio?: number;
+    /** seconds the camera takes to glide to a recentered focus. */
+    recenter?: number;
+    /** target the cursor this many seconds ahead of the exit moment. */
+    lookahead?: number;
+}
+interface FollowEvent {
+    /** SOURCE seconds — the moment the recenter starts. */
+    t: number;
+    cx: number;
+    cy: number;
+}
+declare function followFocusEvents(span: ZoomSpan, cursor: CursorTrack, space: {
+    w: number;
+    h: number;
+}, layout: CardLayout, options?: FollowOptions): {
+    entry: {
+        cx: number;
+        cy: number;
+    } | null;
+    events: FollowEvent[];
+};
+
+interface LoweredComposition {
+    /** The composed config: the anchor's program plus the studio stack entry. */
+    config: Record<string, unknown>;
+    /** The MAIN program's ctx.data. */
+    data: Record<string, unknown>;
+    /** Each stack entry's own ctx.data, by entry id (`deps.stack` / `SET_DATA { target }`). */
+    stack: Record<string, Record<string, unknown>>;
+    /**
+     * A program anchor's tween-timing overlay: delivered to the player
+     * LIVE (`SET_TWEEN_EDITS`, bridge protocol 8) so a retime never changes
+     * the program string. Absent on a recording, and on a stored (baked)
+     * program config.
+     */
+    tweenEdits?: readonly TimelineEdit[];
+    /** Output duration in seconds (drives the carrier + SET_DURATION). */
+    duration: number;
+}
+/**
+ * Zoom transition shape — deterministic pure keyframes evaluated by TL.sample
+ * (no stateful springs, seek stays a pure function of t). The zoom-in ramp
+ * starts BEFORE the span and lands rampInOverlap into it (the camera arrives
+ * just after the moment it frames); the zoom-out starts at the span's end.
+ * All timing/ease constants come from the doc's zoom STYLE (zoomStyle.ts —
+ * named strategy presets grounded in the measured competitor comparison).
+ * Eases are `css-bezier(…)` curves
+ * (@vosjs/timeline >=0.4.0 — parsed identically by host + runtime bundle).
+ *
+ * Legacy constant names = the DEFAULT style's values, kept for scripts/tests
+ * that reason about "the default ramp" symbolically.
+ */
+declare const ZOOM_RAMP_IN: number;
+declare const ZOOM_RAMP_IN_OVERLAP: number;
+declare const ZOOM_RAMP_OUT: number;
+/** Output-time gap ≤ this → pan straight to the next span (no zoom-out). */
+declare const ZOOM_CHAIN_GAP: number;
+/** Connected-zoom pan duration (compressed into short gaps). */
+declare const ZOOM_PAN: number;
+declare const ZOOM_EASE: string;
+declare const ZOOM_PAN_EASE: string;
+/**
+ * Tilt transition shape (tilt spans). Fixed constants, deliberately NOT the
+ * zoom style's (switching
+ * "Camera style" must not silently change tilt feel; a tiltParams override
+ * layer can arrive later if real use demands it). The eases are the same
+ * measured css-bezier family the default zoom style uses. Unlike zoom, the
+ * pose is SETTLED at span.in (the ramp starts TILT_RAMP_IN before, with no
+ * overlap-into-span): tilt frames a moment, it doesn't chase content.
+ */
+declare const TILT_RAMP_IN = 0.9;
+declare const TILT_RAMP_OUT = 0.8;
+/** Output-time gap ≤ this → swing straight to the next pose (no flatten between). */
+declare const TILT_CHAIN_GAP = 1.35;
+/** Connected-tilt swing duration (compressed into short gaps). */
+declare const TILT_PAN = 0.9;
+declare const TILT_EASE: string;
+declare const TILT_PAN_EASE: string;
+/**
+ * Cam-move transition shape (animated cam layouts). Own constants,
+ * deliberately NOT the zoom style's or tilt's (switching another
+ * subsystem's personality must never silently change the bubble's feel). The
+ * premium band for an in-video layout morph is 0.6–1.0s (Descript's Smart
+ * Transition defaults to 0.8s); the bubble is small chrome, so it sits at the
+ * fast end. Like tilt, the pose is SETTLED at span.in (the ramp starts before,
+ * no overlap-into-span): a cam move frames what follows.
+ */
+declare const CAM_RAMP_IN = 0.65;
+declare const CAM_RAMP_OUT = 0.65;
+/** Output-time gap ≤ this → morph straight to the next pose (no return to rest). */
+declare const CAM_CHAIN_GAP = 1.2;
+/** Connected-move morph duration (compressed into short gaps). */
+declare const CAM_PAN = 0.7;
+declare const CAM_EASE: string;
+declare const CAM_PAN_EASE: string;
+/**
+ * The doc's kept spans with speed spans applied — the OUTPUT-time truth every
+ * downstream consumer evaluates (mapTime in ON_FRAME, duration, zoom remap,
+ * the export's audio splice). An empty segment list means "untrimmed", so
+ * speed spans still apply over one synthesized full-source segment.
+ */
+declare function ratedSegments(doc: StudioDoc): Segment[];
+/**
+ * Map a SOURCE-time span onto the output timeline through the RATED segment
+ * list: the output extent of its KEPT footage (a partially-cut span snaps its
+ * edges into kept footage; a fully-cut span returns null — it follows its
+ * footage, like every source-anchored feature). Rate-aware: output positions
+ * accumulate each piece's (out − in) / rate.
+ */
+declare function spanOutputExtent(segments: Segment[], sIn: number, sOut: number): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Expand the doc's source-anchored zoom spans into a standard @vosjs/timeline
+ * keyframe track in OUTPUT time (values are [level, cx, cy] vectors):
+ *
+ *   rest ──ramp-in──▶ [level,cx,cy] ──hold──▶ span end ──ramp-out──▶ rest
+ *
+ * with one twist: when the output gap to the NEXT span is ≤ ZOOM_CHAIN_GAP,
+ * the camera never returns to rest — it pans straight to the next span's
+ * state over ZOOM_PAN and holds it through the gap (OpenScreen's connected
+ * zooms: the camera glides from focus to focus). Transitions run in output
+ * time, so they never straddle a cut; keyframe times are strictly increasing
+ * (dense spans compress rather than reorder).
+ */
+/** A span enriched by the lowering with baked cursor-follow recenters. */
+interface LoweredZoomSpan extends ZoomSpan {
+    followEvents?: FollowEvent[];
+}
+declare function zoomTrackFromDoc(zoom: LoweredZoomSpan[], segments: Segment[], style?: ZoomStyleParams): KeyframeTrack<number[]>;
+/**
+ * Expand the doc's source-anchored tilt spans into an OUTPUT-time keyframe
+ * track of [rx, ry] DEGREES (ON_FRAME converts to radians at the mesh):
+ *
+ *   flat ──ramp-in──▶ [rx,ry] ──hold──▶ span end ──ramp-out──▶ flat
+ *
+ * Rest is FLAT: there is no static card pose to return to (decided
+ * 2026-08-03 — a lean is a moment on the timeline), which makes this the
+ * exact analog of zoom's level-1 rest. Deliberate
+ * differences from zoomTrackFromDoc: the pose is SETTLED at
+ * span.in (ramp starts TILT_RAMP_IN before, no overlap-into-span), there are
+ * no follow events, and ramps are fixed constants rather than the zoom
+ * style's. Spans ≤ TILT_CHAIN_GAP apart in output time swing pose-to-pose
+ * without flattening between (the connected-zoom rule). Transitions run in
+ * output time so they never straddle a cut; keyframe times are strictly
+ * increasing (dense spans compress rather than reorder).
+ */
+declare function tiltTrackFromDoc(tilt: TiltSpan[], segments: Segment[], motion?: {
+    rampIn?: number;
+    rampOut?: number;
+    chainGap?: number;
+    pan?: number;
+}): KeyframeTrack<number[]>;
+/**
+ * The bubble's rest pose as [x, y, size] frame fractions, resolved through the
+ * SAME oracle the picking layer uses (camBubbleRect) so the corner math can
+ * never fork a third way (draw / pick / lowering). Fractions are resolution-
+ * stable at a fixed aspect: the margin (24·s) and diameter (size·H) both
+ * scale with s = H/1080, so the fraction depends only on the aspect ratio.
+ */
+declare function camRestPose(cam: CamStyle, W: number, H?: number): number[];
+/**
+ * Expand the doc's source-anchored cam pose spans into an OUTPUT-time keyframe
+ * track of [x, y, size] frame fractions (the third consumer of the
+ * span→track seam):
+ *
+ *   rest ──ramp-in──▶ [x,y,size] ──hold──▶ span end ──ramp-out──▶ rest
+ *
+ * Rest is the doc's cam style resolved to fractions (camRestPose) — doc.cam IS
+ * the rest pose, exactly as tilt's rest is flat. The pose is SETTLED at
+ * span.in (ramp starts CAM_RAMP_IN before): a cam move frames what follows.
+ * Spans ≤ CAM_CHAIN_GAP apart in output time morph pose-to-pose without
+ * returning to rest (the connected-zoom rule). Absent pose fields inherit the
+ * rest pose. Transitions run in output time so they never straddle a cut.
+ */
+declare function camTrackFromDoc(cam: CamStyle, spans: CamPoseSpan[], segments: Segment[], W: number, H?: number): KeyframeTrack<number[]>;
+/**
+ * Pose fractions → the bubble square, mirroring ON_FRAME's pose branch (the
+ * 40px floor and the rounded radius ride s, exactly like the static path).
+ */
+declare function camRectFromPose(pose: readonly number[], cam: CamStyle, W: number, H?: number): CamBubbleRect;
+/**
+ * The bubble rect at OUTPUT time t — the time-aware picking oracle.
+ * With no motion spans it is exactly camBubbleRect at the doc's design layout;
+ * with spans it samples the SAME track the lowering ships, so picking can
+ * never drift from the paint (camDraw.test.ts pins both paths). Design space
+ * is docCardLayout's (H = 1080, W from the output aspect).
+ */
+declare function camBubbleRectAt(doc: ProjectDoc, t: number): CamBubbleRect;
+/** A resolved pose keyframe: clip-local time + full value vector. */
+interface MotionKey {
+    at: number;
+    value: number[];
+    ease?: string;
+}
+/**
+ * Bake resolved pose keyframes into a CLIP-LOCAL keyframe track.
+ * The base vector holds until the first pose (a leading keyframe at 0 pins
+ * it), values interpolate across each gap (ease-into per pose), and the last
+ * pose holds to the clip's end (sample clamps). Same emitter, same
+ * interpolator, same purity as the zoom/tilt/cam tracks.
+ */
+declare function motionTrack(base: readonly number[], keys: MotionKey[], dur: number): KeyframeTrack<number[]>;
+/** An overlay clip's base vector: [x, y, scale, rotation, opacityMul]. */
+declare function overlayMotionBase(o: OverlayClip): number[];
+/**
+ * Effective [x, y, scale, rotation, opacityMul] of an overlay clip at
+ * CLIP-LOCAL time t — the host-side mirror of ON_FRAME's sampling (the
+ * picking layer substitutes it into the clip's transform so hit rects track
+ * the animated element). Null = the clip has no motion.
+ */
+declare function overlayMotionPoseAt(o: OverlayClip, t: number): number[] | null;
+/** An object clip's base vector: [x, y, z, rx, ry, rz, scale]. */
+declare function objectMotionBase(o: ObjectClip): number[];
+/**
+ * Effective [x, y, z, rx, ry, rz, scale] of an object clip at CLIP-LOCAL
+ * time t (from the span start; 0 when span-less over `clipDur`). Null = the
+ * clip has no motion. The 3D mirror of overlayMotionPoseAt.
+ */
+declare function objectMotionPoseAt(o: ObjectClip, t: number, clipDur: number): number[] | null;
+/**
+ * The shared layers as the studio entry's data: overlay clips (presets resolved
+ * to plain values HERE, ON_FRAME reads no registry), 3D props (numbers resolved
+ * HERE), the extra font faces SETUP awaits. Every key is omitted when its layer
+ * is absent — data byte parity for docs that never touched it. Both anchors
+ * call this with their own output duration.
+ */
+declare function studioLayerData(layers: {
+    overlays?: OverlayClip[];
+    objects?: ObjectClip[];
+    audio?: AudioClip[];
+}, duration: number): Record<string, unknown>;
+declare function lowerToComposition(doc: ProjectDoc): LoweredComposition;
+
+/**
+ * ONE lowering for the document family: the anchor's program
+ * plus the studio stack entry, on every anchor.
+ *
+ * - A recording lowers to its card program (`lowerToComposition`), which
+ *   already carries the entry.
+ * - A program lowers to the user's config, COMPLETE and untouched (the
+ *   execution IR, D1) with its tween-timing overlay baked into
+ *   `createTimeline`, plus the same entry carrying the shared layers. Params
+ *   and Looks ride the config as authored. `retime` arrives with speed spans
+ *   absent, the engine's identity is the identity.
+ *
+ * The composed config is what the platform stores for a layered program and
+ * what the fleet compiles; the player runs it MINUS every data object (the
+ * structural hash), with `data` and `stack` delivered live.
+ */
+declare function lowerStudioDoc(doc: StudioDoc, opts?: LowerProgramOptions): LoweredComposition;
+interface LowerProgramOptions {
+    /**
+     * Bake the tween overlay into `createTimeline` (the STORED composed
+     * config: the fleet, the watch page and `vos render` have no bridge to
+     * hand an overlay to). Off by default: the player runs the user's
+     * timeline and retimes it live, so the program string is constant
+     * across every timing edit.
+     */
+    bake?: boolean;
+}
+
+/**
+ * `config.retime` for a program with speed spans: output time →
+ * program time through the RATED segments on `data.retime` (the same map
+ * `mapTime` performs; inlined so the config stays self-contained, tested
+ * against it). Reads data live, so a rate edit is SET_DATA, never a LOAD.
+ */
+declare const PROGRAM_RETIME = "(t, data) => {\n  var s = data && data.retime\n  if (!s || !s.length) return t\n  var acc = 0\n  for (var i = 0; i < s.length; i++) {\n    var r = s[i].rate && s[i].rate > 0 ? s[i].rate : 1\n    var d = (s[i].out - s[i].in) / r\n    if (t < acc + d) return s[i].in + (t - acc) * r\n    acc += d\n  }\n  return s[s.length - 1].out\n}";
+/**
+ * With speed spans the OUTPUT length is not the program's own, but the
+ * engine hands ONE \`duration\` to both the clock and \`createTimeline\`. The
+ * composed config's \`duration\` is the output length (the clock, the fleet's
+ * render length); this wrapper hands the user's function the program's own
+ * length from \`data.programDuration\` — data, so a rate edit stays live.
+ */
+declare function wrapProgramLength(source: string): string;
+declare function lowerProgramDoc(doc: ProgramAnchorDoc, opts?: LowerProgramOptions): LoweredComposition;
+
+/**
+ * A destination is where a release's media goes — the output twin of the
+ * doors registry's "a door is what you bring". One row per channel asset,
+ * derived from the verified channel specs; `vos deliver` loops these and
+ * the kit manifest records them.
+ */
+interface Destination {
+    /** `${channel}-${asset}` — the id `vos deliver --to` and kit.json use. */
+    id: string;
+    channel: string;
+    asset: string;
+    label: string;
+    kind: 'video' | 'still' | 'still-set';
+    /** Reduced aspect ratio, the exportSizeFor convention. */
+    ratio: string;
+    px: {
+        w: number;
+        h: number;
+    };
+    /** still-set only: how many the channel takes. */
+    count?: {
+        min: number;
+        max: number;
+    };
+    /**
+     * Image genre: 'screenshot' = real UI from the take (store policy demands
+     * real UX); 'card' = a COMPOSED cover — rendered from the maker's poster
+     * program when `vos deliver --poster` has one.
+     */
+    genre?: 'screenshot' | 'card';
+    minSeconds?: number;
+    maxSeconds?: number;
+    maxBytes?: number;
+    /** The format the kit renders. */
+    format: 'mp4' | 'png';
+    /** What the channel accepts, in the spec's own words. */
+    accepts: string;
+    /** How footage meets an off-ratio frame (a still fills, a video letterboxes). */
+    fit: 'contain' | 'cover';
+    notes: string;
+}
+declare const CHANNEL_SPECS_VERIFIED = "2026-08-04";
+declare const CHANNEL_SPECS_HASH = "7a3ad4301f96507ec471a35fa37f367dcaf4bd405b008f551d0ac4cd395d61f7";
+declare const DESTINATIONS: Destination[];
+declare function destinationById(id: string): Destination | undefined;
+declare function destinationsForChannel(channel: string): Destination[];
+
+/**
+ * The studio's program: the SHARED layers (text/image/video overlay clips, the
+ * 3D prop pool) as ONE engine stack entry (`config.stack`, @vosjs/core ≥0.21)
+ * that runs after the anchor's program on the same ctx — same scene, camera,
+ * overlayScene, renderer, master clock — with its OWN `ctx.data` and its own
+ * error boundary. The same entry rides every anchor: a recording's card
+ * program and a user's own config alike.
+ *
+ * Everything here is CONSTANT text: a layer edit is `SET_DATA { target }` on
+ * this entry, never a program change (the liveEdit invariant). The paint code
+ * is the take editor's compositor, moved out of its main program unchanged;
+ * it reads only what an entry is given — the renderer size, the output
+ * clock (`ctx.time` on an entry IS the output time), the shared
+ * `window.__vos__` caches and `globalThis.__vosTimeline` — never the anchor's
+ * card geometry.
+ *
+ * The overlay layer mounts in `ctx.overlayScene` (the engine's 2D group,
+ * rendered after every 3D group under the ortho `overlayCamera`), sized to that
+ * camera's bounds, so it fills the frame on any anchor whatever its camera.
+ * Props mount in `ctx.scene` at renderOrder 1.5 (between a recording's card and
+ * its cam bubble) on the ANCHOR's camera: a perspective camera anywhere, or an
+ * orthographic one (a program's `fullscreen` preset), where the prop group
+ * carries the camera pose and a pixel-aspect squash. Lights: the entry adds
+ * its pair when its data says `lights` (the recording anchor), and lazily,
+ * once, when a program's scene turns out to have none (a shader program).
+ */
+declare const STUDIO_ENTRY_ID = "vosso.studio";
+interface StudioEntry {
+    id: string;
+    data: Record<string, unknown>;
+    setup: string;
+    createContent: string;
+    onFrame: string;
+}
+declare function studioEntry(data: Record<string, unknown>): StudioEntry;
+
+interface EnvelopePoint {
+    /** output-timeline seconds. */
+    t: number;
+    /** linear gain 0..1. */
+    g: number;
+}
+declare function clipEnvelope(clip: Pick<AudioClip, 'start' | 'in' | 'out' | 'gain' | 'fadeIn' | 'fadeOut' | 'loop' | 'loopLen'>): EnvelopePoint[];
+/** Envelope value at output time `t` (linear interpolation; 0 outside the clip). */
+declare function envelopeValueAt(env: EnvelopePoint[], t: number): number;
+
+/**
+ * The studio's audio clips as an ENGINE audio plan:
+ * the shape `@vosjs/core/audio`'s `mixAudio` renders. One builder for every
+ * export path (the device exporter, the fleet's audio page) from the same
+ * lowered data the preview scheduler plays, so what you hear is what exports.
+ *
+ * A clip is OUTPUT-anchored: it plays from `start` for `len` seconds, reading
+ * the source from `in` (looping over `[in, out]` when `loop`), at its gain
+ * envelope (`env`, absolute output seconds, fades included) times the duck
+ * curve when it ducks. The plan samples that at `step` (240/s, the engine's
+ * default); the mixer interpolates between points and treats the loop's
+ * wrap as a seek.
+ *
+ * Structurally typed: the lowered clip, not the doc — this runs on the fleet
+ * from stored config data as well as in the studio.
+ */
+interface LoweredAudioClip {
+    key: string;
+    start: number;
+    in: number;
+    out: number;
+    gain: number;
+    loop: boolean;
+    len: number;
+    duck: boolean;
+    env: EnvelopePoint[];
+}
+interface AudioPlanPoint {
+    t: number;
+    on: boolean;
+    pos: number;
+    gain: number;
+}
+interface AudioPlanTrack {
+    id: string;
+    src: string;
+    loop: boolean;
+    points: AudioPlanPoint[];
+}
+interface StudioAudioPlan {
+    duration: number;
+    step: number;
+    tracks: AudioPlanTrack[];
+}
+declare const AUDIO_PLAN_STEP: number;
+/** Linear interpolation over absolute-time envelope points; `def` outside an empty one. */
+declare function envelopeAt(env: readonly EnvelopePoint[], t: number, def: number): number;
+declare function studioAudioPlan(clips: readonly LoweredAudioClip[], duckEnv: readonly EnvelopePoint[], duration: number, step?: number): StudioAudioPlan;
+
+/**
+ * Compositor v2 — the layer stage geometry.
+ *
+ * The stage turns the studio's single fullscreen-ortho quad into a three-layer mesh stack
+ * under ONE perspective camera:
+ *
+ *   overlay quad     screen-space   cam bubble + text/image/video overlays
+ *   card mesh        world-space    the existing 2D card painting, on a plane
+ *                                   that can TILT (doc.tilt spans)
+ *   background quad   screen-space   CSS fill + vos background loop
+ *
+ * Every layer is a plane placed perpendicular to the camera axis and centered
+ * on it, sized to exactly fill the camera frustum at its depth. Perpendicular +
+ * centered + frustum-filling ⇒ it projects to the full viewport regardless of
+ * depth, so the background/overlay read as flat screen-space and the CARD, at
+ * `tilt = 0`, projects PIXEL-IDENTICALLY to today's ortho fullscreen quad. Only
+ * the card ever rotates; the perspective camera then gives it real
+ * foreshortening (an ortho camera would only skew it).
+ *
+ * These are pure helpers (no THREE dependency) so the host can mirror the exact
+ * projection the runtime draws with — the world-unit basis that
+ * on-canvas picking builds on (host picks / instance renders). `stage.test.ts`
+ * pins the math; the runtime (lowerToComposition CREATE_CONTENT/ON_FRAME) must
+ * use these SAME constants — change them together.
+ */
+/**
+ * Camera field of view (degrees). Deliberately gentle (telephoto-ish product
+ * shot) so a card tilt reads as a premium 3D lean, not a fisheye warp. Parity
+ * at tilt = 0 is INDEPENDENT of this value (every layer is sized to fill the
+ * frustum), so it is a pure aesthetic dial for how dramatic tilt looks.
+ */
+declare const CARD_FOV = 30;
+/**
+ * Layer depths (world units in front of a camera at the origin looking down
+ * −z). Absolute values are arbitrary — only the ORDER matters (painter's order
+ * is set by renderOrder, not depth) and that near/far bracket them. The card
+ * sits between the background (behind) and the overlay (in front).
+ */
+declare const OVERLAY_Z = -2;
+declare const CARD_Z = -4;
+declare const BACKGROUND_Z = -6;
+declare const CAMERA_NEAR = 0.1;
+declare const CAMERA_FAR = 100;
+interface PlaneSize {
+    width: number;
+    height: number;
+}
+/**
+ * The world-space size of a plane that exactly fills a perspective camera's
+ * frustum at `|distance|` in front of it. Height subtends the full vertical FOV;
+ * width follows the viewport aspect. This is the one sizing primitive the whole
+ * stack shares — every layer plane, and the host-side projection basis for
+ * picking, derive from it.
+ */
+declare function planeSizeAtDepth(distance: number, fovDeg: number, aspect: number): PlaneSize;
+/**
+ * Project a point on the (untilted) card plane, given in normalized card-canvas
+ * coordinates (u, v ∈ [0,1], v measured from the TOP like a canvas), to
+ * normalized screen coordinates (sx, sy ∈ [0,1], sy from the top). At tilt = 0
+ * this is the identity — the card fills the viewport — so it is exact for the
+ * common case and the basis the tilt/camera matrices extend for
+ * on-canvas picking. Kept here so host and runtime never disagree on
+ * where the card is.
+ */
+declare function cardPointToScreen(u: number, v: number): {
+    sx: number;
+    sy: number;
+};
+
+/** Baked pill geometry: design px at the clip's resolved font size. */
+interface ResolvedOverlayBox {
+    color: string;
+    opacity: number;
+    /** Paddings/radius in design px (em multiples × resolved size). */
+    padX: number;
+    padY: number;
+    radius: number;
+}
+/**
+ * Resolve a clip's background pill (null when absent). Mirrored by
+ * `overlayRect`'s inflation and ON_FRAME's pill draw — change together.
+ */
+declare function resolveOverlayBox(clip: TextOverlayClip): ResolvedOverlayBox | null;
+/** A preset's base values (the 5-field house style). */
+interface OverlayPresetStyle {
+    /** Full CSS font-family stack (primary + fallbacks). */
+    stack: string;
+    weight: number;
+    /** Font size in design px (H = 1080 space), before transform.scale. */
+    size: number;
+    color: string;
+    /** Legibility shadow strength 0..1 (0 = none). */
+    shadow: number;
+}
+/** Preset base + the full override surface, resolved to concrete values. */
+interface ResolvedOverlayStyle extends OverlayPresetStyle {
+    fontStyle: 'normal' | 'italic';
+    align: 'left' | 'center' | 'right';
+    /** Design px at the resolved size. */
+    letterSpacing: number;
+    /** Multiplier (default OVERLAY_LINE_HEIGHT). */
+    lineHeight: number;
+    stroke: TextOverlayStroke | null;
+}
+/** The house text styles. Sizes in design px; colors are ink-on-footage. */
+declare const TEXT_PRESETS: Record<TextOverlayPreset, OverlayPresetStyle>;
+/** Size override bounds (design px) — same range the inspector slider offers. */
+declare const OVERLAY_SIZE_MIN = 12;
+declare const OVERLAY_SIZE_MAX = 200;
+/**
+ * woff2 faces SETUP preloads when the doc has overlays (latin subset only —
+ * overlay text is product UI copy). URLs are the self-hosted catalog on
+ * assets.vos.so; studio-core stays dependency-free, so the three base faces
+ * are literals — keep them within the catalog `@vosjs/shared` hosts.
+ */
+declare const OVERLAY_FONT_FACES: {
+    family: string;
+    weight: number;
+    url: string;
+}[];
+/** Preset + per-clip overrides → the concrete style baked into ctx.data. */
+declare function resolveOverlayStyle(clip: TextOverlayClip): ResolvedOverlayStyle;
+interface OverlayFontFace {
+    family: string;
+    weight: number;
+    url: string;
+}
+/**
+ * The hosted face a clip's family/weight overrides resolve to, when it is
+ * NOT one of the three base preset faces (null otherwise — parity: preset
+ * clips carry nothing). Baked per-overlay so ON_FRAME can lazy-load it on a
+ * live style edit (SET_DATA never re-runs SETUP); SETUP awaits the full list
+ * from ctx.data on cold load, which is what export parity rides on.
+ */
+declare function overlayFaceFor(clip: TextOverlayClip): OverlayFontFace | null;
+/**
+ * Every woff2 face a doc's overlays need (SETUP await on cold load, and the
+ * host document for measurement): the three base preset faces — ALWAYS, byte
+ * parity for preset-only docs — plus one face per override.
+ */
+declare function overlayFontFaces(doc: Pick<ProjectDoc, 'overlays'>): OverlayFontFace[];
+declare function overlayLines(text: string): string[];
+/**
+ * The canvas font string at a given comp scale — MIRRORS ON_FRAME's
+ * `olW + ' ' + olPx + 'px ' + olStack` (pinned by test).
+ */
+declare function overlayFontString(style: ResolvedOverlayStyle, scale: number, s: number): string;
+interface OverlayRect {
+    /** Center-anchored box in DESIGN px (pre-rotation). */
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+    /** Rotation in degrees (the caller rotates points into local space to hit-test). */
+    rotation: number;
+}
+/**
+ * The drawn bounding box of a text overlay in DESIGN px — the picking
+ * geometry. `measure(text, font)` returns the text width in px for a font
+ * string (the host passes a scratch-canvas measureText; tests stub it).
+ * `frameW`/`frameH` are the design frame size (docCardLayout's W/H) — the
+ * clip's transform.x/y are FRACTIONS of the frame, so the anchor is
+ * x·frameW / y·frameH. Measured at s = 1 (design space), so the result maps
+ * to the canvas by ·s and to CSS by the player's display scale.
+ */
+declare function overlayRect(clip: OverlayClip, measure: (text: string, font: string, letterSpacingPx?: number) => number, frameW: number, frameH?: number, 
+/** Media kinds: natural aspect (w/h) once known — null/absent = assume 16:9. */
+mediaAspect?: number | null): OverlayRect;
+/** Point-in-overlay test (design px), rotation-aware (point → local space). */
+declare function overlayHit(rect: OverlayRect, px: number, py: number, padPx?: number): boolean;
+
+declare const TEXT3D_DEPTH_DEFAULT = 0.25;
+declare const TEXT3D_DEPTH_MIN = 0.02;
+declare const TEXT3D_DEPTH_MAX = 1;
+interface BakedText3dMaterial {
+    /** THREE constructor family: MeshStandardMaterial | MeshPhysicalMaterial. */
+    type: 'standard' | 'physical';
+    params: Record<string, unknown>;
+}
+interface BakedText3dAsset {
+    kind: 'text3d';
+    text: string;
+    /** Resolved typeface JSON URL (assets.vos.so — the fleet's one origin). */
+    url: string;
+    /** Extrusion depth as a fraction of the glyph height. */
+    depth: number;
+    bevel: boolean;
+    mat: BakedText3dMaterial;
+}
+/** Normalize a doc text3d asset into the baked payload (pure, deterministic). */
+declare function resolveText3dAsset(asset: Extract<ObjectAsset, {
+    kind: 'text3d';
+}>): BakedText3dAsset;
+
+/**
+ * Idle cursor fade — the dwell detector behind `CursorStyle.hideWhenIdle`.
+ *
+ * A parked cursor is the most common blemish in screen footage: the dot sits in
+ * frame through every scroll, every typing passage, every pause, drawing the eye
+ * to nothing. This bakes a sparse opacity curve so ON_FRAME can fade it out
+ * during dwells and bring it back the moment the cursor moves again.
+ *
+ * Pure and deterministic — seek must stay a pure function of `t`, so there are
+ * no springs and no state. Output is SOURCE-anchored (like the cursor samples
+ * themselves), which is what makes trims, cuts and speed spans inherit the fade
+ * from one seam.
+ *
+ * Detection runs on the RAW track, not the smoothed path. The smoothed path is
+ * resampled at a fixed cadence and linearly interpolates across gaps, so during
+ * a park it creeps toward wherever the cursor goes next — ground truth for "the
+ * user isn't moving" is the absence of raw events. The smoothing settle after
+ * the last real move is bounded and well under `CURSOR_IDLE_HOLD`, so the dot
+ * is always at rest before the fade begins.
+ *
+ * Two things deliberately do NOT count as movement:
+ *
+ * - **Scrolling.** `scroll` events re-emit the last known position, so a reading
+ *   pause looks "active" if you detect idleness from sample gaps. They carry no
+ *   real cursor motion and are ignored here, so a long scroll correctly fades
+ *   the cursor away — it isn't doing anything.
+ * - **Focus jumps and typing.** `focus`/`key` events synthesize a position at
+ *   the focused element's centre, which the cursor never visited — and during
+ *   typing the caret is the actor, so the parked dot SHOULD fade.
+ *
+ * Clicks DO break a dwell: a press is not idle. The window before a click ends
+ * `CURSOR_IDLE_FADE_IN` early so the dot is back at full opacity when the ring
+ * blooms under it, rather than ghosting in behind its own click effect.
+ */
+
+/** Seconds of stillness before the cursor starts fading out. */
+declare const CURSOR_IDLE_HOLD = 1;
+/** Fade-out ramp, seconds. */
+declare const CURSOR_IDLE_FADE_OUT = 0.35;
+/** Fade-in ramp, seconds. Snappier than the way out — motion draws the eye. */
+declare const CURSOR_IDLE_FADE_IN = 0.18;
+/**
+ * Movement epsilon as a fraction of the capture's short edge, floored at 2px
+ * (the recorder's own distance gate). Relative so a 4K take isn't held to a
+ * 1080p take's pixel budget.
+ */
+declare const CURSOR_IDLE_EPS_FRAC = 0.0025;
+interface CursorIdleOptions {
+    /** Capture space, for the movement epsilon. */
+    space: {
+        w: number;
+        h: number;
+    };
+    /** SOURCE seconds; the trailing dwell runs to here. */
+    sourceDuration: number;
+}
+/** One point on the baked opacity curve. SOURCE seconds → alpha 0..1. */
+interface CursorFadeKey {
+    t: number;
+    a: number;
+}
+/**
+ * Bake the opacity curve for a cursor track. Returns an empty array when
+ * nothing dwells long enough to be worth hiding — callers then emit no
+ * `cursorFade` key at all, so a take with a busy cursor lowers byte-identically
+ * to the pre-feature lowering.
+ */
+declare function cursorIdleFade(track: CursorTrack, o: CursorIdleOptions): CursorFadeKey[];
+
+/** Anticipation lead — effects start this many output seconds before the click. */
+declare const CLICK_FX_PRE = 0.06;
+/** Base effect durations in output seconds (× the intensity's `dur`). */
+declare const CLICK_RIPPLE_DUR = 0.45;
+declare const CLICK_PULSE_DUR = 0.35;
+declare const CLICK_HIGHLIGHT_FADE = 0.35;
+/** Synthetic press length when the matching `up` is missing (nav killed it). */
+declare const CLICK_SYNTH_RELEASE = 0.12;
+/** A down→up pair longer than this is treated as unmatched (lost `up`). */
+declare const CLICK_PAIR_MAX = 10;
+/** Highlight uses the element rect only when it covers ≤ this viewport fraction. */
+declare const CLICK_RECT_MAX_FRAC = 0.35;
+interface LoweredClick {
+    /** OUTPUT seconds of mousedown. */
+    ot: number;
+    /** OUTPUT seconds of release (real up, clamped into kept footage). */
+    up: number;
+    /** SOURCE seconds of mousedown — ON_FRAME's cross-cut proximity guard. */
+    st: number;
+    /** click point in cursorSpace px. */
+    x: number;
+    y: number;
+    /** pointer button (0=left). */
+    b: number;
+    /** element rect [x,y,w,h] in cursorSpace px — present only when the
+     * highlight style wants it AND it passed the size/containment gates
+     * (ON_FRAME stays branch-light: r present = draw highlight). */
+    r?: [number, number, number, number];
+}
+interface ExtractClickOptions {
+    /** attach gated element rects (highlight style). */
+    rects?: boolean;
+    /** cursorSpace dims — the rect-size gate's denominator. */
+    space: {
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Extract OUTPUT-anchored clicks from a raw cursor track. Downs in trimmed-away
+ * footage are dropped (they follow their footage, like every source-anchored
+ * feature); a press pairs with the next `up` of the same button unless another
+ * `down` of that button intervenes (a lost `up` must not chain two presses).
+ */
+declare function extractClicks(track: CursorTrack, segments: Segment[], opts: ExtractClickOptions): LoweredClick[];
+/** '#rgb'/'#rrggbb' → [r,g,b] for ctx.data (ON_FRAME composes rgba() per frame). */
+declare function hexToRgbTriplet(hex: string): [number, number, number] | null;
+
+/** The doc's segments in canonical explicit form (empty = one full-source span). */
+declare function effectiveSegments(doc: StudioDoc): Segment[];
+declare const videoLane: LaneAdapter<ProjectDoc>;
+/**
+ * Zoom lane — zoom regions as clips ("1.80×"). Spans are SOURCE-anchored
+ * (footage-anchored like speed spans and the cam window); the lane displays
+ * the output extent of each span's KEPT footage (spanOutputExtent — partial
+ * cuts snap the clip's edges, full cuts hide it until the trim is undone).
+ * Move/resize are pointer-true through the FULL rated map — zoom never alters
+ * rates, so no exclusion trick is needed (unlike speedLane). Spans never
+ * overlap: create no-ops inside an existing span, move pushes out of
+ * collisions (or no-ops), resize clamps against neighbors. Level/focus are
+ * edited in the toolbar/inspector, not by gesture. Any gesture promotes the
+ * span to source:'manual' — it survives an auto-zoom regenerate.
+ */
+declare const zoomLane: LaneAdapter<ProjectDoc>;
+/**
+ * Tilt lane — card-pose regions as clips (label = "rx°/ry°"). SOURCE-anchored
+ * like zoom spans (footage-anchored through trims and speed changes; the full
+ * rated map applies — tilt doesn't alter rates); non-overlapping. The pose
+ * itself is edited in the span editor (like zoom level), not by gesture. Any
+ * gesture promotes the span to source:'manual' — it survives a Dynamic-tilt
+ * regenerate (the auto-zoom wand contract).
+ */
+declare const tiltLane: LaneAdapter<ProjectDoc>;
+/**
+ * Cam-move lane — animated cam layout regions as clips (label = the
+ * pose size as a percent when set). SOURCE-anchored like tilt spans (the
+ * full rated map applies); non-overlapping. The pose itself is edited on the
+ * canvas or in the span editor, never by lane gesture. Structurally the tilt
+ * lane with a different payload; kept separate so neither lane's clamps can
+ * drift the other's.
+ */
+declare const camMoveLane: LaneAdapter<ProjectDoc>;
+/**
+ * Webcam lane — the Cam member row of the take group. Its clips are the
+ * visibility window INTERSECTED with each kept segment, at the video lane's
+ * exact output positions, so a split on the Video row visibly splits this row
+ * too. Gestures still edit only the WINDOW (`cam.window`, SOURCE time,
+ * footage-anchored): move slides it (dragging any of its clips moves the one
+ * window), resize lives on the window's REAL edges — the first clip's start
+ * and the last clip's end; the cut boundaries between them belong to the
+ * Video row. There is no remove — hide the bubble via its panel.
+ */
+declare const camLane: LaneAdapter<ProjectDoc>;
+/**
+ * Mic sub-row of the take group: mirrors the video lane's cut boundaries
+ * EXACTLY — one clip per kept segment at the same output positions — so the
+ * voice visibly cuts and splits with the footage. VIEW-ONLY by design: cutting
+ * happens on the Video row, because the take has ONE shared `segments` list
+ * (that is what makes sub-track desync structurally impossible; per-row
+ * segments would only buy bugs). Selecting a clip opens the Voice panel
+ * (level/mute); the waveform is the row's content, so items carry no label.
+ */
+declare const micLane: LaneAdapter<ProjectDoc>;
+/**
+ * Speed lane — rate spans as clips ("2×"). Spans are SOURCE-anchored (footage
+ * follows them through trims); the lane displays them at the output positions
+ * of the rated pieces they produce, so a span visually contracts as its rate
+ * grows. Spans never overlap: create no-ops inside an existing span, move
+ * pushes out of collisions (or no-ops), resize clamps against neighbors.
+ * The rate itself is edited in the toolbar (like zoom level), not by gesture.
+ * Move/resize are POINTER-TRUE: the dragged edge's resulting output position
+ * is exactly the pointer's (mapped through the rate map without this span),
+ * so edges never lag the pointer at 1/rate speed.
+ */
+declare const speedLane: LaneAdapter<ProjectDoc>;
+/**
+ * Music/SFX lane — clips are OUTPUT-anchored (`clip.start` is final-cut
+ * seconds; they do NOT follow footage through trims — see AudioClip). Move
+ * retimes `start`; resizing trims into the source file: the start edge shifts
+ * `in` and `start` together (content stays put under the untouched edge), the
+ * end edge adjusts `out`. Clips are created from the audio inspector, not by
+ * double-click (there is no meaningful "blank" audio clip).
+ */
+declare const audioLane: LaneAdapter<ProjectDoc>;
+declare function parsePoseId(id: string): {
+    clipId: string;
+    index: number;
+} | null;
+/**
+ * Text-overlay lane (compositor v2) — clips are OUTPUT-anchored like audio
+ * (`start` is final-cut seconds; a title never retimes with trims/speed).
+ * Overlaps are allowed (two titles can coexist — z-order is array order).
+ * Create adds a house 'title' clip at the playhead, centered, lower-third.
+ */
+declare const overlaysLane: LaneAdapter<ProjectDoc>;
+/**
+ * Object lane — world-space props. Clips show the span (objects with no
+ * span render as a full-length block and don't move — the span IS the lane's
+ * noun). Created from the toolbar; asset/transform edited in the inspector.
+ */
+declare const objectsLane: LaneAdapter<ProjectDoc>;
+
+/**
+ * Waveform peaks — pure downsampling for timeline clip rendering. The host
+ * decodes the file (Web Audio) and hands channel data here; the result is one
+ * max-|sample| value per bucket in [0..1], drawn as symmetric bars.
+ */
+declare function computePeaks(channels: Float32Array[], buckets: number): Float32Array;
+
+/** SOURCE-time loudness grid (RMS per window). */
+interface MicRms {
+    /** RMS value per window, linear 0..1. */
+    values: Float32Array;
+    /** windows per second. */
+    rate: number;
+}
+interface DuckOptions {
+    /** RMS above this counts as speech. */
+    threshold: number;
+    /** gain while ducked (≈ -12 dB). */
+    duckTo: number;
+    /** seconds to reach the ducked level once speech starts. */
+    attack: number;
+    /** seconds to recover after speech stops. */
+    release: number;
+    /** output grid resolution, points per second. */
+    gridHz: number;
+}
+declare const DEFAULT_DUCK: DuckOptions;
+/** RMS windows from raw PCM — the host runs this once per recording (cached). */
+declare function computeMicRms(channels: Float32Array[], sampleRate: number, windowSec?: number): MicRms;
+/**
+ * The OUTPUT-time duck multiplier curve: walk an output grid, look up the mic
+ * loudness at the mapped SOURCE moment, and smooth engage/recover with
+ * attack/release one-poles. Points are thinned (emitted on ≥1% change).
+ */
+declare function duckCurve(rms: MicRms, segments: Segment[], durationSec: number, opts?: DuckOptions): EnvelopePoint[];
+
+/** Rate-aware OUTPUT duration of a doc (what the viewer experiences). */
+/**
+ * The OUTPUT length of either document: a recording's kept footage
+ * through its speed spans, a program's own length (its `program.duration`,
+ * else the config's).
+ */
+declare function docOutputDuration(doc: StudioDoc): number;
+interface MusicBedInput {
+    id: string;
+    /** Durable URL of the track (assets.vos.so catalog or an owned asset). */
+    key: string;
+    name: string;
+    /** Full source-file length, seconds. */
+    trackDuration: number;
+    /** Current output duration of the doc, seconds. */
+    outputDuration: number;
+    /** Whether the recording carries a mic track (ducking default). */
+    hasMic: boolean;
+}
+/** A catalog track placed as the doc's background music bed. */
+declare function musicBedClip(input: MusicBedInput): AudioClip;
+/**
+ * Is this clip a music BED — background music covering the cut? Beds are
+ * what "add a track" replaces (one bed at a time; trying another vibe must
+ * not stack). A clip the user moved off 0 or shortened mid-cut stopped
+ * being a bed on purpose, so it is theirs to manage and never auto-replaced.
+ */
+declare function isMusicBed(clip: AudioClip, outputDuration: number): boolean;
+/**
+ * Re-fit clips that tracked the output end after the duration changed from
+ * `prevDuration` to `nextDuration` (both OUTPUT seconds). Mutates `doc`
+ * (an immer draft in practice); returns whether anything changed.
+ */
+declare function refillAudioBeds(doc: ProjectDoc, prevDuration: number, nextDuration: number): boolean;
+/**
+ * The take's VOICE source key, or null when it has none: the mic sidecar when
+ * the take was recorded split (AT), else the legacy mixed track (pre-split
+ * takes carried mic+system in the recording's own file). Ducking, the duck-RMS
+ * decode and every "has a voice?" UI gate share this one derivation.
+ */
+declare function voiceKey(doc: Pick<ProjectDoc, 'source'> | StudioDoc): string | null;
+
+/**
+ * The DEFAULT backdrop: the house loop every NEW take opens on
+ * once the flag below is on. A committed constant, not a live vos, the same
+ * way Home's door tiles are a deliberate asset push (decided 2026-08-17):
+ * changing it is a code change with a review, never something an autosave
+ * can re-skin.
+ *
+ * `ground` is the loop's average colour, written into `frame.background` so
+ * the frame before the first decoded frame, the reduced-motion still and
+ * the offline fail-open all land on the loop's own colour. The
+ * keys are the pre-registry bucket objects, which stay in the bucket
+ * forever; the registry's `backdrops/{slug}/…` keys replace them when the
+ * house loop is featured through the verb.
+ *
+ * BACKDROP_DEFAULT_ON is the flip. It stays OFF until the set has a signed-off
+ * seed and the fleet measurement has run: a switch, not a surprise.
+ * Docs already carrying a frame are never touched either way.
+ */
+
+declare const DEFAULT_BACKDROP: {
+    readonly slug: "soft-beams";
+    readonly title: "Soft Beams";
+    readonly key: "https://assets.vos.so/backgrounds/soft-beams-1080p.webm";
+    readonly key2k: "https://assets.vos.so/backgrounds/soft-beams-2k.webm";
+    readonly poster: "https://assets.vos.so/backgrounds/soft-beams-poster.jpg";
+    readonly duration: 10;
+    readonly ground: "#a7b2d1";
+};
+declare const BACKDROP_DEFAULT_ON: boolean;
+/** The default backdrop as a doc's `frame.backgroundMedia`. */
+declare function defaultBackdropMedia(): BackgroundMedia;
+/** A frame style opening on the default backdrop (media + its ground). */
+declare function withDefaultBackdrop(frame: FrameStyle): FrameStyle;
+
+export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type AspectRatioOption, type AudioClip, type AudioPlanPoint, type AudioPlanTrack, BACKDROP_DEFAULT_ON, BACKGROUND_Z, type BackgroundMedia, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CAMERA_FAR, CAMERA_NEAR, CAM_CHAIN_GAP, CAM_EASE, CAM_PAN, CAM_PAN_EASE, CAM_RAMP_IN, CAM_RAMP_OUT, CAM_SIZE_MAX, CAM_SIZE_MIN, CAM_SPAN_MIN, CAPTURE_COVERAGE_MIN, CARD_FOV, CARD_Z, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CROP_MAX_PX, CROP_MIN_FRAC, CROP_MIN_PX, CROP_PAD, CURSOR_IDLE_EPS_FRAC, CURSOR_IDLE_FADE_IN, CURSOR_IDLE_FADE_OUT, CURSOR_IDLE_HOLD, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CaptureNormalization, type CardLayout, type ClickFxStyle, type CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, DEFAULT_BACKDROP, DEFAULT_BROWSER_BAR, DEFAULT_CAM_POSE, DEFAULT_CAM_STYLE, DEFAULT_CLICK_FX, DEFAULT_CURSOR_STYLE, DEFAULT_DUCK, DEFAULT_FRAME_STYLE, DEFAULT_SPEED_PARAMS, DEFAULT_TILT_POSE, DEFAULT_ZOOM_LEVEL, DEFAULT_ZOOM_STYLE, DESTINATIONS, DIGEST_CROP_MAX, DIGEST_FULL_MAX, DIGEST_VERSION, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DuckOptions, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, type FocusBounds, type FollowEvent, type FollowOptions, type FrameGeometry, type FrameStyle, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type MediaOverlayClip, type MicRms, type MinimalBarTheme, type Moment, type MomentKind, type MomentsOptions, type MotionKey, type MotionPose, type MotionPose3D, type MusicBedInput, type NormRect, OBJECT_DEFAULT_SCALE, OVERLAY_FONT_FACES, OVERLAY_LINE_HEIGHT, OVERLAY_MEDIA_DEFAULT_RADIUS, OVERLAY_MEDIA_DEFAULT_WIDTH, OVERLAY_MIN_DURATION, OVERLAY_SCALE_MAX, OVERLAY_SIZE_MAX, OVERLAY_SIZE_MIN, OVERLAY_TRANSITION_DUR, OVERLAY_Z, type ObjectAnimation, type ObjectAsset, type ObjectClip, type ObjectPrimitiveShape, type OverlayClip, type OverlayFontFace, type OverlayKind, type OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PLAYBACK_ACTIVITY, PROGRAM_RETIME, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, type RecordingArtifact, type RecordingMeta, type Rect, type ResolvedOverlayBox, type ResolvedOverlayStyle, SCENE_MOTION, SCENE_QUIET, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STUDIO_ENTRY_ID, STYLE_FIELDS, type SmoothOptions, type SmoothPoint, type SpeedParams, type SpeedSpan, type StepAnchor, type StepSpan, type StudioAudioPlan, type StudioDoc, type StudioEntry, type StyleField, TEXT3D_DEPTH_DEFAULT, TEXT3D_DEPTH_MAX, TEXT3D_DEPTH_MIN, TEXT_PRESETS, TILT_AUTO_DEAD_ZONE, TILT_AUTO_MIN, TILT_CHAIN_GAP, TILT_DEG_MAX, TILT_EASE, TILT_INTENSITY_MAX, TILT_PAN, TILT_PAN_EASE, TILT_RAMP_IN, TILT_RAMP_OUT, TILT_SPAN_MIN, TILT_UI_DEG_MAX, TRANSITION_SPEED_MULT, type Text3dMaterial, type TextFxDirection, type TextFxKind, type TextFxSpec, type TextFxUnit, type TextOverlayBox, type TextOverlayClip, type TextOverlayPreset, type TextOverlayStroke, type TiltPersonality, type TiltSpan, type TiltStyleName, type TranscriptSegment, type TransitionSpeed, WINDOW_FOCUS_MIN, ZOOM_CHAIN_GAP, ZOOM_EASE, ZOOM_LEVELS, ZOOM_LEVEL_MAX, ZOOM_LEVEL_MIN, ZOOM_PAN, ZOOM_PAN_EASE, ZOOM_RAMP_IN, ZOOM_RAMP_IN_OVERLAP, ZOOM_RAMP_OUT, ZOOM_SPAN_MIN, ZOOM_STYLES, ZOOM_STYLE_OPTIONS, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomWindow, anchorKindOf, anchorSourceDuration, aspectRatioValue, audioLane, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cardPointToScreen, clampCamFrac, clampCamSize, clampFocus, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, computeCardLayout, computeMicRms, computePeaks, copyStyle, cropBox, cursorIdleFade, defaultBackdropMedia, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docOutputDuration, docToCropSpace, docToFullSpace, duckCurve, effectiveSegments, envelopeAt, envelopeValueAt, expectedFrameSize, exportSizeFor, extractClicks, focusBounds, followFocusEvents, frameGeometry, hexToRgbTriplet, idleGaps, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, levelForFocusFraction, lowerProgramDoc, lowerStudioDoc, lowerToComposition, micLane, migrateHostedDoc, momentsFromDoc, motionTrack, musicBedClip, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputRangeToSource, overlayFaceFor, overlayFontFaces, overlayFontString, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayRect, overlaysLane, pageDisplayUrl, parsePoseId, pickStyle, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolveText3dAsset, resolveZoomStyle, sceneChanges, scrollRuns, setSpeedInRange, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, videoLane, voiceKey, withDefaultBackdrop, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomWindow };