Canvas Timeline
Package

React Timeline Editor Core Engine

UI-agnostic state, editing, snapping, playback, and markers.

Use the core package when your integration needs the timeline model and editing operations without React or canvas rendering concerns.

Installation

pnpm
pnpm add @techsquidtv/canvas-timeline-core

When to use it

You are building a timeline in a non-React environment (e.g., Vue, Svelte, or native platforms) and need to own rendering yourself.
You want a clean, framework-agnostic engine to manage track models, edit history, snapping, and clipboard operations.
You need to write fast, isolated unit tests around timeline business logic without loading browser DOM elements or UI chrome.

Common imports

Engine and state types
import {
  TimelineEngine,
  type TimelineEditCommand,
  type TimelineState,
  type Track,
} from '@techsquidtv/canvas-timeline-core';
Typed edit commands
import { fromSeconds } from '@techsquidtv/canvas-timeline-utils';


const preview = engine.previewEdit({
  type: 'move',
  clipId: 'clip-intro',
  startTime: fromSeconds(4),
});


if (preview.valid) {
  engine.commitEdit(preview.command);
}
Snapping helpers
import { SnapIndex } from '@techsquidtv/canvas-timeline-core/snapping';

Usage notes

  • •Manages the serializable `TimelineState` source of truth, encapsulating tracks, clips, playback cursor, markers, and range selection.
  • •Encapsulates typed edit commands (`validateEdit`, `previewEdit`, `commitEdit`, and `cancelEdit`), playback loops, history stacks (undo/redo), and typed snapping logic in a UI-agnostic environment.
  • •Ideal for headless testing or custom platform integrations (such as Node.js or alternative rendering engines) due to zero DOM or UI dependencies.

API Surface

Explore the key components, hooks, and classes exported by this package. Click any symbol to view its full TSDoc parameter signatures.

Key Entry Points

ClassTimelineEngine

The central orchestrator and coordinator for the high-performance timeline editor. Maintains state (tracks, clips, markers, playhead position, zoom scale, scrolls, snaps), builds dynamic snap indexes for magnetic snap guidance, handles split and edit actions, and publishes state events to trigger low-latency canvas renderings and lightweight React layouts.

InterfaceTimelineState

Represents the complete, serialized state model of the high performance timeline.

InterfaceTrack

A horizontal timeline lane containing clips and editing state. Tracks are app-owned rows in the timeline model. The engine uses each track's stable id for editing operations, reads the ordered clip list for rendering and hit testing, and honors view/editing flags such as visible, collapsed, locked, and muted.

InterfaceClip

Represents an individual media clip node positioned at a specific timeline interval.

Subpath Imports

Import specific files or modules directly to reduce bundle size or target specialized package layers.

Import PathDescription
@techsquidtv/canvas-timeline-coreTypes, engine, and snapping utilities.
@techsquidtv/canvas-timeline-core/engineTimelineEngine entrypoint.
@techsquidtv/canvas-timeline-core/typesTrack, Clip, Marker, and TimelineState types.
@techsquidtv/canvas-timeline-core/snappingSnapIndex helpers for snapping and lookups.