@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. The hook is collection-first: each named layer returns every matching active clip in stable track order. `primary` is only a convenience first match.

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.

Reads the transient edit-preview state for a clip. Use this for custom clip UIs that need to render live editing affordances, such as overwrite cut indicators, without depending on internal engine flags.

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. This is a focused live interaction hook intended for custom drag affordances.

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. The hook subscribes to geometry-affecting timeline events and intentionally does not subscribe to playhead-only updates.

Provides the canonical clip collection and editing actions 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 live edit impacts produced by active timeline interactions. This is a live interaction hook: it can update during drag and 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 previews. This is a focused live hook. It updates when command previews change and does not broaden provider state with drag-time edit consequences.

Subscribes to a typed TimelineEngine event with a React-safe latest handler. The hook keeps the event subscription stable while updating the callback ref every render, avoiding stale closures without resubscribing for handler-only changes.

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 Bezier curve handle drag behavior shared by package and custom timeline UIs.

Reads timeline keyframe curve geometry and exposes Bezier easing commands.

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

Reads timeline keyframe geometry and exposes canonical keyframe commands.

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. The hook is media-library agnostic. Apps provide a clock and a single layer sync callback while the hook advances the TimelineEngine playhead and decides when active layer clips need to be resynchronized.

High-level synchronization for external media surfaces. The hook remains media-library agnostic: apps provide an adapter for decoding, rendering, and audio scheduling, while the hook handles active layer lookup, first-content seeking, external-clock playback, rate changes, and pause state.

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 timeline state. This is a render-focused shortcut for components that need track, playhead, zoom, scroll, marker, or playback state without calling engine methods. The returned value updates when `TimelineProvider` receives engine state events.

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 lean 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. This is the preferred hook for custom DOM clip renderers and custom canvas layers that only need visible or near-visible clips.

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 Bezier curve handle double-click or double-tap callback.

Props for the delegated Bezier curve interaction layer.

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.

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.

Interface representing the context bundle of the timeline provider.

Options for `useTimelineEvent`.

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 Bezier curve handle drag.

Pointer data needed to begin a Bezier curve handle drag.

Successful Bezier curve handle drag update payload.

Input for updating one keyframe's Bezier easing.

Pointer data needed to update a keyframe drag.

Pointer data needed to begin a keyframe drag.

Successful keyframe 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 `useTimelineClips`.

Result returned by `useTimelineEditCommands`.

Result returned by `useTimelineEditImpacts`.

Result returned by `useTimelineEditMode`.

Result returned by `useTimelineEditPreview`.

Result returned by `useTimelineHistory`.

Result returned by `useTimelineKeyboard`.

Result returned by `useTimelineKeyframeCurveDrag`.

Options accepted by `useTimelineKeyframeCurves`.

Result returned by `useTimelineKeyframeCurves`.

Options accepted by `useTimelineKeyframeDrag`.

Result returned by `useTimelineKeyframeDrag`.

Options accepted by `useTimelineKeyframes`.

Result returned by `useTimelineKeyframes`.

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`.

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.

Frame rate accepted by frame-based `TimecodeInput` helpers. Use numbers for simple rates such as `24`, `25`, `30`, or `60`. Use rational objects for exact fractional media rates such as `{ numerator: 30000, denominator: 1001 }`.

Display shape used when formatting seconds for a `TimecodeInput`. `auto` keeps common decimal clock text unless a frame rate is provided. With a frame rate, `auto` formats frame timecode. `seconds`, `minutes`, and `hours` keep decimal centiseconds. `frames` formats `HH:MM:SS:FF`, and `drop-frame` formats `HH:MM:SS;FF`.

Options for formatting a seconds value into editable `TimecodeInput` text.

Options for parsing editable `TimecodeInput` text into seconds.

Rounding policy used when parsing editable `TimecodeInput` text. `none` preserves the decimal precision entered by the user, within normal JavaScript number limits. `centisecond` rounds parsed seconds to two decimal places for legacy or display-like workflows.

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.

Callback signature for a typed TimelineEngine event subscription.

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`.

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 `useTimelineKeyframeCurveDrag`.

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 `parseTimecodeInput` 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.

React context containing the global engine controller and its reactive state model.

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 seconds for editable `TimecodeInput` text. Decimal formats are rounded to centiseconds and clamped at zero. Frame formats round to the nearest frame for the supplied frame rate. Use this at UI boundaries after converting from `RationalTime` with `toSeconds`.

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.

Parses editable `TimecodeInput` text into seconds. Accepts plain seconds, decimal seconds, `m:ss`, `m:ss.cc`, `h:mm:ss`, `h:mm:ss.cc`, flexible single-digit colon segments such as `1:2`, and unit suffixes like `s` (seconds), `ms` (milliseconds), `m` (minutes), or `f` (frames, which requires a `frameRate` option). Invalid, negative, missing, or out-of-range user text returns `null`. Invalid developer options such as unsupported drop-frame rates throw `RangeError`.

Creates a failed timeline command result.

Creates a successful timeline command result.

Sets up a bridge between the central event-driven `TimelineEngine` model and standard React functional layouts. Subscribes to settled state, selection, playback, content, and clipboard changes, pushing lightweight state updates downwards into hooks.