@techsquidtv/canvas-timeline-react

Returns clips that intersect the current playhead time. A clip is active when the playhead is at or after `timelineStart` and before `timelineEnd`. Clips on hidden tracks, muted tracks, and clips marked `disabled` are omitted. The returned array contains clips only; read the timeline state when you also need the containing track id.

Returns active timeline layers at a timeline time.

Subscribes to live marker proximity derived from the current playhead. Use this focused live hook for readouts and marker navigation UI that should update during playback or scrubbing. Use `useTimelineMarkers` for ordinary marker lists and marker editing commands.

Subscribes to real-time playback events (enter, update, leave) for a specific clip as the global playhead crosses the clip's boundary timestamps.

Reads the timeline engine and synchronized state from React context. Use this hook inside components wrapped by `TimelineProvider` when you need to call imperative engine commands and read the latest React-rendered state in the same component. Prefer narrower hooks such as `useTimelineState`, `useTimelinePlayback`, or `useTimelineClips` when a component only needs one slice of timeline behavior.

Provides access to clipboard operations for copying, cutting, and pasting clips.

Headless clip body drag behavior shared by canvas and custom timeline UIs.

Subscribes to live cross-track clip drop feedback.

Exposes clip group state and commands for editor chrome.

Provides constant-DOM keyboard navigation and commands for canvas clips. The hook flattens canvas-rendered clips into a navigable model without mounting one DOM element per clip. Consumers can use the returned `focusTargetProps` on a single focused element, or wire the navigation and edit commands into their own shortcut system and selected-clip inspector.

Returns viewport-space geometry for every timeline clip.

Provides the canonical clip collection and clip metadata for React editor UI.

Exposes command-layer edit APIs for React product chrome. The hook is a thin adapter over `TimelineEngine` command methods; it does not implement edit math or range mutation rules in React.

Subscribes to affected-clip consequences produced by command previews and active timeline interactions. This is a focused live hook: it can update when command previews change and during drag or trim gestures. Use it for custom headless UI affordances that show which clips are trimmed, split, or removed by the active edit.

Owns local edit-mode state for product toolbar chrome. The selected mode does not mutate engine state by itself. Compose it with `useTimelineEditCommands` to build and preview typed edit commands.

Subscribes to live command-layer edit preview state. This is a focused live hook for preview validity and command state. Compose with `useTimelineEditImpacts` when UI also needs affected-clip consequences.

Subscribes to a typed TimelineEngine event with a React-safe latest handler.

Adds native browser drag-and-drop support for app-owned clip data.

Provides canonical undo/redo history access for timeline editor chrome.

Adapts timeline In/Out points to a Base UI-compatible range slider. The hook keeps loop or export boundaries in sync with `TimelineEngine` `inPoint` and `outPoint` values while returning semantic labels and `aria-valuetext` strings for each thumb. `Timeline.RangeSelector.Root` uses this hook internally; consumers can call it directly when composing their own Base UI slider surface.

Provides focus-scoped timeline keyboard shortcuts. The hook never installs global listeners. It handles shortcuts only from the element that spreads `scopeProps` or one of that element's descendants.

Headless keyframe drag behavior shared by canvas and custom timeline UIs.

Reads timeline keyframe geometry and exposes canonical keyframe commands.

Reads timeline keyframe segment geometry and exposes side-aware tangent commands.

Headless Bezier tangent drag behavior shared by package and custom timeline UIs.

Accesses and manages bookmark/annotation pins (markers). This canonical marker hook does not subscribe to live playhead ticks. Compose it with `useActiveMarkers` when UI needs marker proximity at the current playhead.

Coordinates timeline playback with an external media clock.

High-level synchronization for external media surfaces.

Adapts horizontal timeline scroll to a Base UI-compatible scalar slider. Use this hook when an application wants a semantic pan control for `TimelineEngine.scrollLeft`. It overlaps with `useTimelineViewport` only at the engine command layer; this hook adds slider props, bounds, and formatted ARIA value text for custom UI primitives.

Provides canonical transport, playhead command, and in/out range commands. Compose this with `useTimelinePlayheadTime` when a component also needs a live clock readout.

Adapts the timeline playhead to a Base UI-compatible scalar slider. Use this hook when an application wants its own playhead scrubber, time field, or transport control while preserving the shared `TimelineEngine` state. It composes with `useTimelinePlayback`, which exposes imperative transport commands without subscribing to live playhead ticks.

Hook to subscribe directly to playhead scrubbing changes. Bypasses root-level context state updates to keep scrubbing high-performance.

Adapts timeline In/Out points to command-layer range selection. The hook treats a complete In/Out pair as the selected edit range and delegates range mutations to `useTimelineEditCommands`.

Returns shared viewport-space ruler ticks for DOM and custom timeline chrome. The hook subscribes to geometry-affecting timeline events and intentionally does not subscribe to playhead-only updates.

Hook to subscribe directly to scroll left position changes. Bypasses root-level context state updates for smooth scroll navigation.

Hook to subscribe directly to scroll top position changes. Bypasses root-level context state updates for smooth vertical navigation.

Provides the canonical selected clip/track model for timeline editor chrome.

Provides the canonical snapping state and commands for editor UI.

Reads the current synchronized TimelineState snapshot.

Imperatively positions a low-count DOM affordance at a timeline time. The returned transform is viewport-space: `seconds * zoomScale - scrollLeft`. Use it for standalone affordances such as the playhead grabber. Range controls that already live inside a transformed timeline overlay should use their local control primitive positioning instead.

Accesses one timeline track with canvas-aligned row geometry and commands.

Builds headless track drop targets for cross-track clip movement.

Adapts one timeline track into DOM-ready track header state.

Adapts one timeline track into a semantic lock toggle button.

Accesses and manages the list of timeline tracks.

Adds formatted accessibility values to the vertical timeline scrollbar adapter.

Adapts generic range scrollbar state to the timeline's vertical track viewport. The hook derives a controlled `{ start, end }` value from `scrollTop`, `viewportHeight`, and track-stack bounds. Thumb changes pan the engine-owned vertical scroll position so canvas rows and external DOM chrome can stay in sync. Handle changes scale expanded track heights, giving the range handles a vertical zoom behavior that matches the horizontal viewport scrollbar's shape.

Provides canonical viewport metrics and setters for custom timeline chrome.

Adds formatted accessibility values to the timeline viewport range adapter. This hook builds on `useTimelineViewportScrollbar`, preserving the same lightweight viewport scrollbar geometry and keyboard behavior while adding `aria-valuetext` formatting for the thumb and resize handles. Use it with the generic `RangeScrollbar` primitive when composing a custom viewport control.

Adapts generic range scrollbar state to the current timeline viewport. The hook derives a controlled `{ start, end }` value from timeline `scrollLeft`, `zoomScale`, `viewportWidth`, and content duration. Thumb changes pan the engine, while handle changes update zoom and then restore the requested range start.

Returns viewport-intersecting timeline clips with clipped time/source ranges.

Adapts timeline zoom scale to a Base UI-compatible scalar slider. Use this hook when a product toolbar needs a focused, semantic zoom control rather than broad viewport commands from `useTimelineViewport`. The returned root props mutate `TimelineEngine.zoomScale`; thumb props provide the default label and formatted `aria-valuetext`.

Hook to subscribe directly to zoom changes. Bypasses root-level context state updates for low-latency zoom interaction.

Derives geometry and controlled update helpers for a generic range scrollbar.

Details passed to a clip double-click or double-tap callback.

Props for the delegated clip interaction layer.

Props for the focus-scoped timeline keyboard shortcut wrapper.

Details passed to a keyframe keyboard delete callback.

Details passed to a keyframe double-click or double-tap callback.

Props for the delegated keyframe interaction layer.

Details passed to a Bezier tangent handle double-click or double-tap callback.

Props for the delegated Bezier tangent interaction layer.

Props for the interactive playhead scrub area.

Props for the draggable playhead handle.

Change metadata emitted by Base UI range slider interactions.

Context passed to a range scrollbar `aria-valuetext` formatter.

Props for a range scrollbar resize handle.

Props for the controlled range scrollbar root.

Props for the draggable range scrollbar thumb.

Controlled numeric range represented by a range scrollbar. `start` and `end` use the caller's domain units. For a timeline adapter those units might be seconds; for a chart they might be indexes, prices, or pixels.

Details passed with a controlled range scrollbar value change.

Render-prop payload for custom range selector grabber children.

Props for the high-level timeline range selector overlay.

Props for the RangeSelector Root component.

Details passed when a `TimecodeField` commits a valid value.

Props for the temporary typed timecode editor.

Props for the compact inline timecode editing root.

Props for the compact displayed timecode value.

Props for the timecode text input primitive. Extends Base UI `Input` props, so controlled and uncontrolled React input patterns both work. Use `onValueChange` for the current text value as the user types, or `onChange` when composing with native form handlers. By default it renders as a plain text input, disables browser autocomplete, and disables spellcheck so punctuation-heavy values such as `1:02:03.04` stay visually stable. Pass explicit native input props when a form needs different behavior.

Render-prop payload for custom draggable time grabber children.

Pointer data needed to update a clip body drag.

Pointer data needed to begin a clip body drag.

Flattened clip metadata shared by core geometry APIs, React hooks, and custom renderers.

Options for constant-DOM canvas clip navigation.

Consistent result returned by React hook command APIs.

Options for `useTimelineEvent`.

Context passed to external clip drop callbacks.

Metadata applied when an external drop creates a multi-clip group.

Result of an app-owned external drop guard.

Props spread onto the timeline element that receives native external drops.

Options for adapting timeline In/Out points to a range control.

Single keyboard chord mapped to a timeline command.

Options for creating preset timeline keyboard bindings.

Keyboard-event fields used by the pure shortcut matcher.

Options for `useTimelineKeyboard`.

Pointer data needed to update a keyframe drag.

Pointer data needed to begin a keyframe drag.

Successful keyframe drag update payload.

Input for updating one keyframe tangent side.

Pointer data needed to begin a Bezier tangent handle drag from hit-test geometry.

Pointer data needed to begin a Bezier tangent handle drag by ids.

Pointer data needed to update a Bezier tangent handle drag.

Successful Bezier tangent handle drag update payload.

Details passed to external media sync callbacks.

Adapter callbacks used to connect timeline playback to an external media clock.

Metadata for one canvas-rendered clip exposed through clip navigation.

Options for adapting horizontal timeline scroll to a scalar control.

Options for adapting the timeline playhead to a scalar control.

Props for wiring a TimelineEngine into React context.

Timeline range selected for range edit commands.

Options for formatting a timeline start/end range for assistive technology.

Selected clip and track state derived from the current timeline snapshot.

Options for formatting a single timeline time value for assistive technology.

Context passed to custom clip track-drop guards.

Result of resolving whether a clip may drop on a track.

Options for viewport scrollbar accessibility formatting.

Options for adapting timeline zoom to a scalar control.

Props for the track header list column.

Props for one timeline track header row.

Props for the track header resize handle.

Props for a timeline track row bound to a track id.

Result returned by `useActiveMarkers`.

Options for deriving generic range scrollbar state and update helpers.

Generic range scrollbar geometry and mutation helpers.

Result returned by `useTimelineClipboard`.

Options accepted by `useTimelineClipDrag`.

Result returned by `useTimelineClipDrag`.

Result returned by `useTimelineClipDropFeedback`.

Result returned by `useTimelineClipGroups`.

Result returned by `useTimelineClips`.

Result returned by `useTimelineEditCommands`.

Result returned by `useTimelineEditImpacts`.

Result returned by `useTimelineEditMode`.

Result returned by `useTimelineEditPreview`.

Options accepted by `useTimelineExternalClipDrop`.

Result returned by `useTimelineExternalClipDrop`.

Result returned by `useTimelineHistory`.

Result returned by `useTimelineKeyboard`.

Options accepted by `useTimelineKeyframeDrag`.

Result returned by `useTimelineKeyframeDrag`.

Options accepted by `useTimelineKeyframeSegments`.

Result returned by `useTimelineKeyframeSegments`.

Options accepted by `useTimelineKeyframes`.

Result returned by `useTimelineKeyframes`.

Options accepted by `useTimelineKeyframeTangentDrag`.

Result returned by `useTimelineKeyframeTangentDrag`.

Result returned by `useTimelineMarkers`.

Options for coordinating timeline playback with an external media clock.

Result returned by `useTimelineMediaPlayback`.

Options for high-level timeline media synchronization.

Result returned by `useTimelineMediaSync`.

Result returned by `useTimelinePlayback`.

Result returned by `useTimelineRangeSelection`.

Engine and synchronized state returned by useTimeline.

Result returned by `useTimelineSelection`.

Result returned by `useTimelineSnapping`.

Options for `useTimelineTimePosition`.

Result returned by `useTimelineTimePosition`.

Options accepted by `useTimelineTrackDropTargets`.

Result returned by `useTimelineTrackDropTargets`.

Result returned by `useTimelineTrackHeader`.

Result returned by `useTimelineTrackLockControl`.

Result returned by `useTimelineTrack`.

Result returned by `useTimelineTracks`.

State and formatted accessibility props for a vertical timeline scrollbar.

State and control props for rendering a vertical timeline scrollbar.

Result returned by `useTimelineViewport`.

Options for adapting a generic range scrollbar to the timeline viewport.

State and control props for rendering a timeline viewport scrollbar.

Props for the timeline viewport scrollbar root.

Timeline range boundary controlled by an In/Out grabber.

Reason a range scrollbar requested a controlled value change.

Side of the range scrollbar thumb controlled by a resize handle.

Visual and interaction axis used by a range scrollbar.

Custom node or render prop used inside an In/Out range selector grabber.

Reason a `TimecodeField` committed the current draft text.

Custom node or render prop used inside a draggable time grabber.

Editable presentation fields accepted by `useTimelineClips().updateClip`.

Machine-readable reason a timeline command could not be applied.

Status emitted by the timeline media playback hook.

Opaque interaction metadata forwarded by third-party scalar and range controls.

Callback signature for a typed TimelineEngine event subscription.

External-drop edit operation selected by app chrome or drop context.

Custom policy for accepting or rejecting an external drop target.

Command-to-bindings map accepted by `useTimelineKeyboard`.

Timeline command names supported by the keyboard scope.

Platform bucket used for platform-specific professional editor bindings.

Named shortcut presets for `useTimelineKeyboard`.

Pointer data needed to begin a Bezier tangent handle drag.

Editable marker fields accepted by `useTimelineMarkers().updateMarker`.

Reason high-level media-synchronized playback could not begin.

Result returned from a media-synchronized timeline play request. This high-level media adapter result is intentionally richer than `TimelineCommandResult` because failures include user-facing adapter messages in addition to machine-readable reasons.

Reason an external media callback is being synchronized.

Engine events that should refresh an imperatively positioned timeline element.

Custom policy for accepting or rejecting track drop targets.

DOM props returned for a track header row.

Props returned for a track lock button.

Controlled props required by `RangeScrollbar.Root` for vertical timeline scrolling.

Controlled props required by `RangeScrollbar.Root` for a timeline viewport.

Render prop accepted by `Timeline.TrackHeader`.

Options accepted by `useTimelineClipRects`.

Options accepted by `useTimelineRulerTicks`.

Options accepted by `useTimelineVisibleClips`.

Props for a timeline vertical scrollbar resize handle.

Props for the timeline vertical scrollbar root.

Props for the timeline vertical scrollbar thumb.

Props for a timeline viewport scrollbar resize handle.

Props for the timeline viewport scrollbar thumb.

Minimal keyboard preset: playback only.

Professional editor preset bindings that do not depend on frame rate or platform.

Namespace of generic controlled range scrollbar primitives.

Resize handle for moving one side of the visible range.

Root element for a controlled generic range scrollbar.

Draggable thumb representing the visible range within a larger domain.

Compact timecode field parts. `TimecodeField.Root` owns editing state. `TimecodeField.Trigger` renders the compact displayed value, and `TimecodeField.Input` renders the temporary `TimecodeInput` used for typed edits.

Text input for entering timeline positions as timecode. Use `TimecodeInput` when a toolbar, inspector, or properties panel needs a native text input for clip starts, clip ends, playhead positions, or range boundaries. It keeps flexible entry open to the user (`90`, `1:30.25`, `1:02:03.4567`, and `00:01:30:12` can all represent timeline positions) while the companion helpers parse precise input and format display text consistently. This component renders only the input. Pair it with `parseTimecode` to validate the current text, pass `invalid` when parsing returns `null`, and convert valid seconds back to `RationalTime` with `fromSeconds(parsed, rate)` at your timeline boundary. The rendered input receives `data-slot="timecode-input"` and a `timecode-input` class before consumer classes, which keeps it compatible with shadcn-style slot selectors and Canvas Timeline's semantic stylesheet approach. It forwards refs to the underlying native input element.

Namespace of timeline UI components for composing an editor surface.

Creates the built-in keyboard binding map for a preset.

Derives selected clip and track metadata from timeline tracks.

Flattens timeline tracks into stable clip entries.

Formats a start/end timeline range for assistive technology.

Formats a timeline time for assistive technology. The result intentionally avoids timecode punctuation and raw floating point artifacts so controls can use it as `aria-valuetext`.

Returns a richer clip description without requiring one DOM node per clip.

Returns a concise clip name suitable for labels or active-item summaries.

Resolves a keyboard event to the first matching command in stable command order.

Creates a failed timeline command result.

Creates a failed command result for malformed public command input.

Creates a successful timeline command result.

Provides a TimelineEngine to React timeline hooks and components.