@tangle-network/agent-app 0.11.1 → 0.13.0

package/dist/sequences-react/index.d.ts

@@ -0,0 +1,752 @@
+import { c as SequenceOperation, b as SequenceApplyResult } from '../apply-Cp8c3K9D.js';
+import { o as SequenceTimeline, S as SequenceClip, p as SequenceTrack } from '../store-gckrNq-g.js';
+import * as react from 'react';
+import react__default from 'react';
+
+/**
+ * Seams between the timeline editor's engine, media pipeline, and components.
+ * Everything here is interface-only so the three layers build independently
+ * and products can substitute any layer (e.g. a different frame provider)
+ * without forking the editor.
+ *
+ * Persistence model: the command stack executes optimistically against local
+ * timeline state and emits the equivalent `SequenceOperation[]` through
+ * `TimelineEditorProps.onApplyOperations`. A rejected promise rolls the
+ * command back — the server stays the source of truth, the editor stays
+ * responsive.
+ */
+
+/** One undoable edit. `execute`/`undo` mutate ONLY local editor state; the
+ *  emitted operations are the durable form sent to the product. */
+interface TimelineCommand {
+    label: string;
+    execute(state: EditorTimelineState): EditorTimelineState;
+    undo(state: EditorTimelineState): EditorTimelineState;
+    /** Durable operations equivalent to `execute` (sent on commit). */
+    operations(): SequenceOperation[];
+    /** Durable operations equivalent to `undo` (sent when the user undoes a
+     *  committed command). */
+    inverseOperations(): SequenceOperation[];
+}
+/** Local editor state — the timeline plus volatile view state the server
+ *  never sees. */
+interface EditorTimelineState {
+    timeline: SequenceTimeline;
+    playheadFrame: number;
+    selectedClipIds: string[];
+    zoom: number;
+    scrollLeft: number;
+}
+interface CommandStack {
+    execute(command: TimelineCommand): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Subscribe to state changes; returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    getState(): EditorTimelineState;
+    /** Replace timeline state from a server refresh WITHOUT clearing history. */
+    reset(timeline: SequenceTimeline): void;
+}
+/** Exponential zoom mapping so the slider feels linear across a 10x+ range.
+ *  zoom = pixels per frame. */
+interface ZoomMath {
+    sliderToZoom(slider: number): number;
+    zoomToSlider(zoom: number): number;
+    minZoom: number;
+    maxZoom: number;
+}
+interface SnapPoint {
+    frame: number;
+    kind: 'clip-start' | 'clip-end' | 'playhead' | 'sequence-end';
+}
+interface SnapResult {
+    frame: number;
+    snapped: boolean;
+    point: SnapPoint | null;
+}
+/** rAF-driven playback clock. `performance.now()` deltas drive the playhead;
+ *  emits one callback per animation frame while playing. */
+interface PlaybackClock {
+    play(): void;
+    pause(): void;
+    seek(frame: number): void;
+    isPlaying(): boolean;
+    getFrame(): number;
+    subscribe(listener: (frame: number) => void): () => void;
+    dispose(): void;
+}
+/** Supplies decoded frames for preview rendering. The baseline implementation
+ *  seeks an off-DOM HTMLVideoElement (works everywhere); a WebCodecs
+ *  implementation can replace it behind the same seam. */
+interface VideoFrameProvider {
+    /** Draw the frame at `sourceSeconds` into `ctx` at the given rect. Resolves
+     *  when the frame is painted; rejects when the media cannot be decoded. */
+    drawFrame(mediaUrl: string, sourceSeconds: number, ctx: CanvasRenderingContext2D, rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /** Pre-warm a media URL so the first `drawFrame` doesn't stall. */
+    prefetch(mediaUrl: string): void;
+    dispose(): void;
+}
+/** min/max sample peaks per pixel bucket for waveform rendering. */
+interface WaveformData {
+    peaks: Float32Array;
+    /** Samples represented per peak pair. */
+    samplesPerBucket: number;
+    durationSeconds: number;
+}
+interface TranscriptionSegment {
+    text: string;
+    startSeconds: number;
+    endSeconds: number;
+}
+/** Whisper-in-a-worker contract. Implementations dynamically import the model
+ *  runtime; `available` is false when the optional peer is not installed. */
+interface TranscriptionProvider {
+    available: boolean;
+    transcribe(mediaUrl: string, opts?: {
+        language?: string;
+        onProgress?: (fraction: number) => void;
+    }): Promise<TranscriptionSegment[]>;
+}
+interface TimelineEditorProps {
+    timeline: SequenceTimeline;
+    canWrite: boolean;
+    /** Persist operations the user produced. Reject to roll the edit back.
+     *  Resolve with the per-operation `SequenceApplyResult[]` (what
+     *  `applySequenceOperations` returns, index-aligned with `operations`) so
+     *  the editor can reconcile its optimistic `local-…` clip ids to the
+     *  server-minted ids — without it, undoing a committed place/split/caption
+     *  after a timeline refresh emits operations the server cannot resolve.
+     *  Resolving void skips reconciliation. */
+    onApplyOperations(operations: SequenceOperation[]): Promise<SequenceApplyResult[] | void>;
+    /** Selection + playhead surface to the host (e.g. to attach agent context). */
+    onSelectionChange?(clips: SequenceClip[]): void;
+    onPlayheadChange?(frame: number): void;
+    /** Host-rendered side panel (agent chat) and shelf (draggable assets). */
+    renderSidePanel?(ctx: {
+        selectedClips: SequenceClip[];
+        playheadFrame: number;
+    }): React.ReactNode;
+    renderAssetShelf?(): React.ReactNode;
+    /** Frame provider override; omitted → the baseline HTMLVideoElement provider. */
+    frameProvider?: VideoFrameProvider;
+    className?: string;
+}
+
+/**
+ * Undo/redo command stack over immutable `EditorTimelineState`.
+ *
+ * Invariant that makes `reset()` safe: history entries hold COMMANDS — each a
+ * pair of state transforms plus the durable operations captured at
+ * construction — never state snapshots. Rebasing the timeline from a server
+ * refresh therefore cannot stale the history: a later undo re-applies the
+ * command's inverse transform to whatever timeline is current. If a rebase
+ * removed a clip a historical command targets, that command's transform throws
+ * (fail loud) rather than silently editing the wrong clip — the host decides
+ * whether to drop history at that point.
+ */
+
+/** Oldest entries are dropped past this bound; redo is cleared on execute. */
+declare const COMMAND_HISTORY_LIMIT = 200;
+declare function createCommandStack(initial: SequenceTimeline): CommandStack;
+
+/**
+ * Concrete `TimelineCommand` factories. Every factory captures the inverse
+ * from PRE-state at construction — undo is a value computed once, never a
+ * re-derivation from whatever state exists later. Local execute/undo update
+ * `EditorTimelineState` immutably; `operations()`/`inverseOperations()` return
+ * the durable `SequenceOperation[]` equivalent, built per call from captured
+ * primitives so callers can never alias command internals.
+ *
+ * Id boundary: `place_clip`, `add_caption`, and `split_clip` mint clip ids
+ * server-side, so factories that create local clips take a caller-minted id.
+ * Every factory also takes an optional `resolveClipId` — a LIVE local→server
+ * alias lookup the host feeds from `onApplyOperations` results. Resolution
+ * runs at execute/undo/emission time (never at construction), so a command
+ * captured against an optimistic `local-…` id keeps working after a server
+ * refresh replaced it with the minted id. Residual boundary: clips a durable
+ * undo recreates (e.g. the `place_clip` inverse of a delete) mint FRESH
+ * server ids that only the next refresh reconciles.
+ *
+ * Transforms re-resolve their target clip at execute/undo time and throw when
+ * it no longer exists (e.g. removed by a `reset()` rebase) — editing a wrong
+ * or absent clip silently would corrupt the durable op stream.
+ */
+
+/** Live local→server clip-id lookup (see module header). Must return its
+ *  argument when no alias exists. */
+type ClipIdResolver = (clipId: string) => string;
+interface MoveClipInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    startFrame: number;
+    /** Omitted → stays on its current track. */
+    trackId?: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** Drag-move. The target start clamps through the model's `clampClipStart`
+ *  so drags past either edge land at the boundary instead of throwing
+ *  mid-gesture; the emitted operation carries the clamped value. */
+declare function moveClipCommand(input: MoveClipInput): TimelineCommand;
+interface TrimClipInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    startFrame: number;
+    durationFrames: number;
+    /** New source in-point when trimming the head; omitted → unchanged. */
+    sourceInFrame?: number;
+    resolveClipId?: ClipIdResolver;
+}
+/** Trim is strict where move is forgiving: the caller (a trim handle) already
+ *  knows both edges, so out-of-bounds input is a bug, not a gesture. */
+declare function trimClipCommand(input: TrimClipInput): TimelineCommand;
+interface PlaceClipInput {
+    timeline: SequenceTimeline;
+    /** Caller-minted optimistic id for the local clip (see module header). */
+    clipId: string;
+    trackId: string;
+    label: string;
+    startFrame: number;
+    durationFrames: number;
+    /** Omitted → 0 (start of the source). */
+    sourceInFrame?: number;
+    media?: {
+        url: string;
+        kind: 'video' | 'image' | 'audio';
+    };
+    generationId?: string;
+    assetId?: string;
+    metadata?: Record<string, unknown>;
+    resolveClipId?: ClipIdResolver;
+}
+declare function placeClipCommand(input: PlaceClipInput): TimelineCommand;
+interface DeleteClipInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** Snapshots the full clip at construction so undo restores it exactly. The
+ *  durable inverse rebuilds within the closed operation union: caption clips
+ *  (caption track + text) invert through `add_caption` — `place_clip` cannot
+ *  carry text/language — everything else through `place_clip` with media,
+ *  product references, source window, and disabled state intact. Boundary:
+ *  the caption path cannot carry `disabled` or `metadata`, so a deleted
+ *  disabled caption resurrects ENABLED server-side and caption metadata is
+ *  lost — local undo stays exact (same class of loss as the `set_clip_text`
+ *  language-clear boundary). */
+declare function deleteClipCommand(input: DeleteClipInput): TimelineCommand;
+interface SplitClipInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    /** Sequence-frame to cut at; must fall strictly inside the clip. */
+    atFrame: number;
+    /** Caller-minted id for the second (tail) clip. */
+    newClipId: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** Source mapping is 1:1 frames (no rate ramps in the model), so the tail's
+ *  source in-point is the head's in-point advanced by the head duration. */
+declare function splitClipCommand(input: SplitClipInput): TimelineCommand;
+interface AddCaptionInput {
+    timeline: SequenceTimeline;
+    /** Caller-minted optimistic id for the local caption clip. */
+    clipId: string;
+    /** Editor commands are concrete: the caller resolves placement (e.g. via
+     *  `chooseCaptionPlacement`) and the target track before constructing. */
+    trackId: string;
+    text: string;
+    language?: string;
+    startFrame: number;
+    durationFrames: number;
+    resolveClipId?: ClipIdResolver;
+}
+declare function addCaptionCommand(input: AddCaptionInput): TimelineCommand;
+interface SetClipTextInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    text: string;
+    /** Omitted → language unchanged. */
+    language?: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** Requires the clip to already carry text: `set_clip_text` has no "create"
+ *  semantics in the union, and an inverse for a text-less clip would have to
+ *  invent an empty string. Boundary: when the clip had NO language and this
+ *  command sets one, local undo restores `undefined` exactly but the durable
+ *  inverse cannot clear language (the op has no clear form) — flagged to the
+ *  apply layer. */
+declare function setClipTextCommand(input: SetClipTextInput): TimelineCommand;
+interface ToggleClipDisabledInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** The target value is captured at construction (not flipped at execute time)
+ *  so redo after a rebase applies the same durable op the stack already
+ *  emitted. */
+declare function toggleClipDisabledCommand(input: ToggleClipDisabledInput): TimelineCommand;
+
+/**
+ * Zoom + viewport coordinate math. Zoom is PIXELS PER FRAME; the slider is a
+ * normalized [0, 1] control mapped exponentially (zoom = min·(max/min)^slider)
+ * so each slider step multiplies the scale by a constant factor — linear
+ * slider feel across a 10x+ range.
+ */
+
+interface ZoomMathConfig {
+    minZoom: number;
+    maxZoom: number;
+}
+declare function createZoomMath(config: ZoomMathConfig): ZoomMath;
+/** Horizontal viewport: zoom in pixels per frame, scrollLeft in pixels. */
+interface ViewportTransform {
+    zoom: number;
+    scrollLeft: number;
+}
+/** Frame → viewport-relative pixel x. Output is fractional; round through
+ *  `snapPixel` before drawing. */
+declare function frameToPixel(frame: number, view: ViewportTransform): number;
+/** Viewport-relative pixel x → integer frame. Frames are integer positions,
+ *  so the result rounds to the nearest frame and floors at 0 (a pointer left
+ *  of frame 0 resolves to 0). */
+declare function pixelToFrame(pixel: number, view: ViewportTransform): number;
+/** Snap a CSS-pixel value to the device pixel grid so 1px timeline rules
+ *  render crisp on fractional-DPR displays. */
+declare function snapPixel(value: number, devicePixelRatio: number): number;
+
+/**
+ * Drag snapping. Snap points come from the timeline's structure (clip edges,
+ * playhead, sequence end); the snap THRESHOLD is measured in screen pixels at
+ * the current zoom — what feels "close" is a screen distance, not a frame
+ * count — and converts to frames as thresholdPx / zoom.
+ */
+
+/** Snap point with its owning clip when it came from one, so a drag can
+ *  exclude the dragged clip's own edges. Structurally a `SnapPoint`. */
+interface TimelineSnapPoint extends SnapPoint {
+    clipId?: string;
+}
+/** Disabled clips still occupy timeline space visually, so their edges remain
+ *  snap targets. */
+declare function collectSnapPoints(timeline: SequenceTimeline, playheadFrame: number): TimelineSnapPoint[];
+interface ApplySnapOptions {
+    /** Pixels per frame — converts the pixel threshold into frames. */
+    zoom: number;
+    /** Screen-distance threshold; 10px matches the editor's hit-slop. */
+    thresholdPx?: number;
+    /** Return true to remove a point from consideration (e.g. the dragged
+     *  clip's own edges via `TimelineSnapPoint.clipId`). */
+    exclude?: (point: SnapPoint) => boolean;
+}
+/** Nearest candidate wins; ties keep the first candidate in `points` order
+ *  (sorted by frame from `collectSnapPoints`, so the lower frame). */
+declare function applySnap(frame: number, points: SnapPoint[], opts: ApplySnapOptions): SnapResult;
+
+/**
+ * rAF playback clock. The playhead is derived from a (start time, start
+ * frame) anchor and `performance.now()` deltas — never from per-tick
+ * increments — so dropped animation frames cannot accumulate drift.
+ *
+ * Browser-only at PLAY time, import-safe everywhere: `requestAnimationFrame`
+ * and `performance` are resolved off `globalThis` when playback starts, never
+ * at module load or construction, so server bundles that import the editor
+ * engine do not crash.
+ */
+
+interface PlaybackClockConfig {
+    fps: number;
+    durationFrames: number;
+}
+declare function createPlaybackClock(config: PlaybackClockConfig): PlaybackClock;
+
+/**
+ * Baseline frame pipeline behind the `VideoFrameProvider` seam: an off-DOM
+ * HTMLVideoElement pool for video URLs and an HTMLImageElement pool for
+ * stills, merged by a per-URL kind dispatcher so the editor canvas never
+ * cares which kind a clip's media is. A WebCodecs implementation can replace
+ * this wholesale behind the same seam.
+ *
+ * Server-safe at import time, browser-only at call time: nothing touches
+ * `document` or `fetch` until a provider method runs.
+ */
+
+declare const DEFAULT_MAX_MEDIA_ELEMENTS = 4;
+/** Half a frame at 30fps. Seeks closer than this repaint the decoder's
+ *  current frame instead of forcing a redundant seek. */
+declare const SEEK_TOLERANCE_SECONDS: number;
+/** A seek that hasn't fired `seeked` after this long is a decode failure —
+ *  the draw REJECTS rather than painting whatever frame happens to be up. */
+declare const SEEK_TIMEOUT_MS = 5000;
+interface FrameRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Object-fit 'contain' placement: preserve aspect ratio, fit entirely inside
+ *  `dest`, center the residual space. Callers own clearing the letterbox
+ *  margins — this paints only the fitted region. */
+declare function containFitRect(source: {
+    width: number;
+    height: number;
+}, dest: FrameRect): FrameRect;
+declare function needsSeek(currentTimeSeconds: number, targetSeconds: number): boolean;
+interface PooledElementLease<T> {
+    element: T;
+    /** Unpins the element; idle elements become LRU-evictable. Idempotent. */
+    release(): void;
+}
+interface MediaElementPool<T> {
+    acquire(url: string): PooledElementLease<T>;
+    has(url: string): boolean;
+    size(): number;
+    dispose(): void;
+}
+/** LRU pool of media elements keyed by URL. Entries pinned by an outstanding
+ *  lease are never evicted — a draw in flight must keep its element — so the
+ *  pool can temporarily exceed `maxElements` under concurrent draws and
+ *  shrinks back as leases release. */
+declare function createMediaElementPool<T>(opts: {
+    maxElements: number;
+    create(url: string): T;
+    destroy(element: T, url: string): void;
+}): MediaElementPool<T>;
+/** Extension-based kind classification; 'unknown' defers to a HEAD
+ *  content-type probe at draw time. */
+declare function classifyMediaUrl(url: string): 'video' | 'image' | 'unknown';
+/** Stills behind the same `VideoFrameProvider` seam — `sourceSeconds` is
+ *  validated for contract parity but does not affect the painted pixels. */
+declare function createImageFrameProvider(opts?: {
+    maxElements?: number;
+}): VideoFrameProvider;
+/** The baseline provider `TimelineEditorProps.frameProvider` defaults to.
+ *  Video and image pools each hold up to `maxElements` entries. */
+declare function createVideoElementFrameProvider(opts?: {
+    maxElements?: number;
+}): VideoFrameProvider;
+
+/**
+ * Waveform rendering for audio clips: bucketed max-abs peaks computed once
+ * per (media, zoom bucket count) and painted as mirrored bars around the
+ * track lane's midline. `computeWaveform` is pure so peak math is testable
+ * without Web Audio; `loadWaveform` is the browser edge that decodes real
+ * media into it.
+ */
+
+/** Structural slice of Web Audio's AudioBuffer so peak math runs on synthetic
+ *  fixtures in tests and on real decoded buffers in the browser. */
+interface AudioBufferLike {
+    numberOfChannels: number;
+    length: number;
+    sampleRate: number;
+    duration: number;
+    getChannelData(channel: number): Float32Array;
+}
+/** One max-abs peak per bucket, taken across all channels. `peaks[b]` is the
+ *  loudest absolute sample in bucket `b`; rendering mirrors it around the
+ *  midline, which is what the contract's "peak pair" denotes. Buckets past
+ *  the end of short audio hold 0. */
+declare function computeWaveform(buffer: AudioBufferLike, bucketCount: number): WaveformData;
+/** Fetch + decode `mediaUrl` and bucket it. Pass `ctx` to reuse a shared
+ *  AudioContext; otherwise one is created and closed around the decode. */
+declare function loadWaveform(mediaUrl: string, bucketCount: number, ctx?: AudioContext): Promise<WaveformData>;
+/** Paint mirrored peak bars centered on the rect's midline. Silent buckets
+ *  still paint a 1px hairline so the lane reads as audio, not as empty;
+ *  peaks beyond ±1.0 (hot masters) clip to the full lane height. */
+declare function drawWaveform(ctx: CanvasRenderingContext2D, data: WaveformData, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, color: string): void;
+
+/**
+ * Whisper transcription behind the `TranscriptionProvider` seam, powered by
+ * the OPTIONAL peer `@huggingface/transformers`. The peer is loaded with a
+ * dynamic variable-specifier import inside `transcribe()` so bundlers leave
+ * it external and apps that never transcribe never pay for it. `available`
+ * is the sync UI affordance signal; `transcribe()` re-verifies with the real
+ * import and is the source of truth.
+ */
+
+declare const DEFAULT_WHISPER_MODEL = "onnx-community/whisper-large-v3-turbo";
+interface WhisperChunk {
+    text: string;
+    timestamp: [number, number | null];
+}
+interface WhisperOutput {
+    text: string;
+    chunks?: WhisperChunk[];
+}
+/** Mean-mixdown to mono. Single-channel buffers return the live channel data
+ *  without copying — callers must treat the result as read-only. */
+declare function mixdownToMono(buffer: AudioBufferLike): Float32Array;
+/** Map whisper chunk output to contract segments. A `null` end timestamp is
+ *  whisper's "ran past the end of the audio" sentinel on the final chunk and
+ *  resolves to the audio duration. */
+declare function mapWhisperOutput(output: WhisperOutput | WhisperOutput[], durationSeconds: number, mediaUrl: string): TranscriptionSegment[];
+declare function createWhisperTranscriptionProvider(opts?: {
+    model?: string;
+}): TranscriptionProvider;
+
+declare const SEQUENCE_MEDIA_DRAG_TYPE = "application/x-sequence-media";
+declare function TimelineEditor(props: TimelineEditorProps): react.JSX.Element;
+
+interface PreviewCanvasProps {
+    timeline: SequenceTimeline;
+    clock: PlaybackClock;
+    frameProvider: VideoFrameProvider;
+    className?: string;
+}
+declare function PreviewCanvas({ timeline, clock, frameProvider, className }: PreviewCanvasProps): react.JSX.Element;
+
+/**
+ * Adaptive timecode ruler. Tick density follows zoom through
+ * `selectTickStepSeconds` (major ticks never closer than ~80px, minor ticks
+ * at a fifth of the major step when they'd sit at least 8px apart). Click or
+ * drag scrubs: the pointer is captured, every move quantizes to a whole frame,
+ * and the frame is committed through `onScrub` (the editor routes it to
+ * `PlaybackClock.seek`).
+ */
+interface TimelineRulerProps {
+    fps: number;
+    durationFrames: number;
+    /** Pixels per frame. */
+    zoom: number;
+    onScrub(frame: number): void;
+}
+declare function TimelineRuler({ fps, durationFrames, zoom, onScrub }: TimelineRulerProps): react.JSX.Element;
+
+interface ClipMoveCommit {
+    clipId: string;
+    startFrame: number;
+    trackId: string;
+}
+interface ClipTrimCommit {
+    clipId: string;
+    startFrame: number;
+    durationFrames: number;
+    sourceInFrame: number;
+}
+interface TimelineClipChipProps {
+    clip: SequenceClip;
+    track: SequenceTrack;
+    fps: number;
+    /** Pixels per frame. */
+    zoom: number;
+    sequenceDurationFrames: number;
+    selected: boolean;
+    canWrite: boolean;
+    frameProvider: VideoFrameProvider;
+    /** Snap a candidate move (both clip edges considered); editor closes over
+     *  the engine's snap points. */
+    snapMove(candidate: {
+        startFrame: number;
+        durationFrames: number;
+        clipId: string;
+    }): {
+        startFrame: number;
+        point: SnapPoint | null;
+    };
+    /** Snap a single trim edge. */
+    snapEdge(candidate: {
+        frame: number;
+        clipId: string;
+    }): {
+        frame: number;
+        point: SnapPoint | null;
+    };
+    onSnapPointChange(point: SnapPoint | null): void;
+    onSelect(clipId: string, additive: boolean): void;
+    onCommitMove(input: ClipMoveCommit): void;
+    onCommitTrim(input: ClipTrimCommit): void;
+    onCommitText(input: {
+        clipId: string;
+        text: string;
+    }): void;
+}
+declare function TimelineClipChip(props: TimelineClipChipProps): react.JSX.Element;
+
+interface TimelineTrackRowProps {
+    track: SequenceTrack;
+    clips: SequenceClip[];
+    fps: number;
+    zoom: number;
+    sequenceDurationFrames: number;
+    selectedClipIds: ReadonlySet<string>;
+    canWrite: boolean;
+    frameProvider: VideoFrameProvider;
+    snapMove(candidate: {
+        startFrame: number;
+        durationFrames: number;
+        clipId: string;
+    }): {
+        startFrame: number;
+        point: SnapPoint | null;
+    };
+    snapEdge(candidate: {
+        frame: number;
+        clipId: string;
+    }): {
+        frame: number;
+        point: SnapPoint | null;
+    };
+    onSnapPointChange(point: SnapPoint | null): void;
+    onSelectClip(clipId: string, additive: boolean): void;
+    onCommitMove(input: ClipMoveCommit): void;
+    onCommitTrim(input: ClipTrimCommit): void;
+    onCommitText(input: {
+        clipId: string;
+        text: string;
+    }): void;
+    onLaneSeek(frame: number): void;
+}
+declare function TimelineTrackRow(props: TimelineTrackRowProps): react.JSX.Element;
+
+/**
+ * Playhead overlay for the track area: a full-height line with a triangular
+ * cap. Positioned in timeline pixels (frame * zoom) inside the scrolled
+ * content, so it moves with horizontal scroll for free. Pointer-transparent —
+ * scrubbing belongs to the ruler.
+ */
+interface TimelinePlayheadProps {
+    frame: number;
+    zoom: number;
+}
+declare function TimelinePlayhead({ frame, zoom }: TimelinePlayheadProps): react.JSX.Element;
+
+interface SnapIndicatorLineProps {
+    point: SnapPoint | null;
+    zoom: number;
+}
+declare function SnapIndicatorLine({ point, zoom }: SnapIndicatorLineProps): react.JSX.Element | null;
+
+interface ZoomControlProps {
+    zoomMath: ZoomMath;
+    zoom: number;
+    onZoomChange(zoom: number): void;
+}
+declare function ZoomControl({ zoomMath, zoom, onZoomChange }: ZoomControlProps): react.JSX.Element;
+
+/**
+ * Fuses several `TimelineCommand`s into one undo step so a single gesture
+ * (multi-select delete, drop that creates a track and places a clip) never
+ * fragments the history. Execute runs in order; undo runs in strict reverse so
+ * intermediate states reconstruct exactly.
+ */
+
+declare function compositeCommand(label: string, commands: TimelineCommand[]): TimelineCommand;
+
+/**
+ * Pure pointer-gesture math for the timeline editor. Every drag/trim/scrub
+ * gesture quantizes through these functions so the interactive behavior is
+ * unit-testable without a DOM. All inputs/outputs are integer frames except
+ * pixel deltas and zoom (px per frame), which are the only float-valued edge.
+ */
+
+/** Quantize a horizontal pointer delta to whole frames at the current zoom. */
+declare function framesFromPixelDelta(deltaX: number, zoom: number): number;
+interface MoveDragInput {
+    originStartFrame: number;
+    durationFrames: number;
+    deltaFrames: number;
+    sequenceDurationFrames: number;
+}
+/** New start frame for a move drag, clamped so the clip stays fully inside
+ *  the sequence. */
+declare function moveDragStartFrame(input: MoveDragInput): number;
+interface TrimStartDragInput {
+    originStartFrame: number;
+    originDurationFrames: number;
+    originSourceInFrame: number;
+    deltaFrames: number;
+}
+interface TrimStartDragResult {
+    startFrame: number;
+    durationFrames: number;
+    sourceInFrame: number;
+}
+/**
+ * Head trim: the clip END is invariant; start slides between two hard walls —
+ * it cannot reveal media before source frame 0 (sourceInFrame >= 0) and cannot
+ * pass within MIN_SEQUENCE_CLIP_FRAMES of the end. sourceInFrame shifts by
+ * exactly the start delta so the visible content stays anchored.
+ */
+declare function trimStartDrag(input: TrimStartDragInput): TrimStartDragResult;
+interface TrimEndDragInput {
+    originStartFrame: number;
+    originDurationFrames: number;
+    sourceInFrame: number;
+    deltaFrames: number;
+    sequenceDurationFrames: number;
+    /** Natural source length in frames when known; bounds how far the tail can
+     *  extend. Omit for stills and media of unknown length. */
+    sourceDurationFrames?: number;
+}
+/** Tail trim: start is invariant; duration is bounded below by the minimum
+ *  clip length and above by both the sequence end and the remaining source
+ *  material past the in-point. */
+declare function trimEndDrag(input: TrimEndDragInput): {
+    durationFrames: number;
+};
+/**
+ * Smallest ruler step whose major ticks sit at least `minSpacingPx` apart at
+ * the current zoom; past the table it grows in whole minutes so labels never
+ * collide at extreme zoom-out.
+ */
+declare function selectTickStepSeconds(input: {
+    zoom: number;
+    fps: number;
+    minSpacingPx?: number;
+}): number;
+interface LetterboxRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Contain-fit a media aspect inside a container, centered with letterbox or
+ *  pillarbox bars. */
+declare function letterboxRect(input: {
+    containerWidth: number;
+    containerHeight: number;
+    mediaWidth: number;
+    mediaHeight: number;
+}): LetterboxRect;
+/** Caption type scales with the rendered frame, floored so captions stay
+ *  legible on small previews. */
+declare function captionFontPx(canvasCssHeight: number): number;
+/** Pixel geometry for a clip chip; width floors at 2px so 1-frame clips stay
+ *  grabbable. */
+declare function clipChipGeometry(input: {
+    startFrame: number;
+    durationFrames: number;
+    zoom: number;
+}): {
+    left: number;
+    width: number;
+};
+/**
+ * A move drag snaps whichever clip edge lands closest to a snap point: the
+ * start edge directly, or the end edge re-expressed as a start. An unsnapped
+ * candidate passes through unchanged.
+ */
+declare function chooseMoveSnap(input: {
+    candidateStartFrame: number;
+    durationFrames: number;
+    startSnap: SnapResult;
+    endSnap: SnapResult;
+}): {
+    startFrame: number;
+    point: SnapPoint | null;
+};
+
+declare const SequenceTimelineEditorLazy: react__default.LazyExoticComponent<typeof TimelineEditor>;
+
+export { type AddCaptionInput, type ApplySnapOptions, type AudioBufferLike, COMMAND_HISTORY_LIMIT, type ClipIdResolver, type ClipMoveCommit, type ClipTrimCommit, type CommandStack, DEFAULT_MAX_MEDIA_ELEMENTS, DEFAULT_WHISPER_MODEL, type DeleteClipInput, type EditorTimelineState, type FrameRect, type LetterboxRect, type MediaElementPool, type MoveClipInput, type MoveDragInput, type PlaceClipInput, type PlaybackClock, type PlaybackClockConfig, type PooledElementLease, PreviewCanvas, type PreviewCanvasProps, SEEK_TIMEOUT_MS, SEEK_TOLERANCE_SECONDS, SEQUENCE_MEDIA_DRAG_TYPE, SequenceTimelineEditorLazy, type SetClipTextInput, SnapIndicatorLine, type SnapIndicatorLineProps, type SnapPoint, type SnapResult, type SplitClipInput, TimelineClipChip, type TimelineClipChipProps, type TimelineCommand, TimelineEditor, type TimelineEditorProps, TimelinePlayhead, type TimelinePlayheadProps, TimelineRuler, type TimelineRulerProps, type TimelineSnapPoint, TimelineTrackRow, type TimelineTrackRowProps, type ToggleClipDisabledInput, type TranscriptionProvider, type TranscriptionSegment, type TrimClipInput, type TrimEndDragInput, type TrimStartDragInput, type TrimStartDragResult, type VideoFrameProvider, type ViewportTransform, type WaveformData, type WhisperOutput, ZoomControl, type ZoomControlProps, type ZoomMath, type ZoomMathConfig, addCaptionCommand, applySnap, captionFontPx, chooseMoveSnap, classifyMediaUrl, clipChipGeometry, collectSnapPoints, compositeCommand, computeWaveform, containFitRect, createCommandStack, createImageFrameProvider, createMediaElementPool, createPlaybackClock, createVideoElementFrameProvider, createWhisperTranscriptionProvider, createZoomMath, deleteClipCommand, drawWaveform, frameToPixel, framesFromPixelDelta, letterboxRect, loadWaveform, mapWhisperOutput, mixdownToMono, moveClipCommand, moveDragStartFrame, needsSeek, pixelToFrame, placeClipCommand, selectTickStepSeconds, setClipTextCommand, snapPixel, splitClipCommand, toggleClipDisabledCommand, trimClipCommand, trimEndDrag, trimStartDrag };