@webpacked-timeline/core 1.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to `@webpacked-timeline/core` are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [1.0.0-beta.1] - 2026-03-07
+
+### Added
+- Core state model: `Timeline`, `Track`, `Clip`, `Asset` with branded IDs (`ClipId`, `TrackId`, `AssetId`, `TimelineFrame`, `FrameRate`)
+- Factory functions: `createTimeline`, `createTrack`, `createClip`, `createAsset`, `createTimelineState`
+- Frame utilities: `toFrame`, `frameRate`, `framesToTimecode`, `framesToSeconds`, `secondsToFrames`, `FrameRates`, drop-frame support
+- Atomic dispatcher with rolling-state validation (`dispatch`)
+- 40+ operation primitives: `MOVE_CLIP`, `RESIZE_CLIP`, `SLICE_CLIP`, `DELETE_CLIP`, `INSERT_CLIP`, `SET_MEDIA_BOUNDS`, `SET_CLIP_ENABLED`, `SET_CLIP_SPEED`, `ADD_TRACK`, `DELETE_TRACK`, `REORDER_TRACK`, `REGISTER_ASSET`, `ADD_MARKER`, `MOVE_MARKER`, `DELETE_MARKER`, `SET_IN_POINT`, `SET_OUT_POINT`, `ADD_BEAT_GRID`, `INSERT_GENERATOR`, `ADD_CAPTION`, `EDIT_CAPTION`, `DELETE_CAPTION`, `ADD_EFFECT`, `REMOVE_EFFECT`, `ADD_KEYFRAME`, `MOVE_KEYFRAME`, `DELETE_KEYFRAME`, `SET_CLIP_TRANSFORM`, `SET_AUDIO_PROPERTIES`, `ADD_TRANSITION`, `DELETE_TRANSITION`, `LINK_CLIPS`, `UNLINK_CLIPS`, and more
+- Invariant checker with 9 validation rules (`checkInvariants`)
+- `HistoryStack` with undo/redo and configurable limit
+- `TransactionCompressor` for merging rapid sequential edits
+- Tool system: `ITool` interface, `ToolRegistry`, `ProvisionalManager` for drag previews
+- 12 built-in tools: `SelectionTool`, `RazorTool`, `RippleTrimTool`, `RollTrimTool`, `SlipTool`, `SlideTool`, `RippleDeleteTool`, `RippleInsertTool`, `HandTool`, `TransitionTool`, `KeyframeTool`, `ZoomTool`
+- Snap system: `SnapIndexManager`, `buildSnapIndex`, `nearest`
+- `PlayheadController` with play/pause/seek and J/K/L shuttle
+- `PlaybackEngine` with pipeline contracts (`VideoDecoder`, `AudioDecoder`, `Compositor`)
+- `KeyboardHandler` with configurable key bindings
+- Versioned JSON serialization: `serializeTimeline`, `deserializeTimeline` with automatic migration
+- Export: `exportToOTIO`, `importFromOTIO`, `exportToEDL`, `exportToAAF`, `exportToFCPXML`
+- SRT/VTT subtitle import: `parseSRT`, `parseVTT`, `subtitleImportToOps`
+- Project model: `Project`, `Bin` with `addTimeline`, `addBin`, `serializeProject`, `deserializeProject`
+- `IntervalTree` for O(log n) clip lookup
+- `TrackIndex` for fast track-level queries
+- `ThumbnailCache` (LRU) and `ThumbnailQueue` (priority)
+- Virtual windowing: `getVisibleClips`, `getVisibleFrameRange`
+- `diffStates` for efficient state change detection
+- Effects, keyframes, easing curves, clip transforms, audio properties
+- Transitions with alignment and duration controls
+- Track groups and link groups
+- Clock abstraction: `browserClock`, `nodeClock`, `createTestClock`
+- 852 tests passing

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timeline Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @webpacked-timeline/core
+
+Headless TypeScript engine for professional NLE timeline editing. Framework-agnostic, fully tested, zero dependencies.
+
+## Install
+
+```bash
+npm install @webpacked-timeline/core
+```
+
+## Features
+
+- **40+ atomic operations** — `MOVE_CLIP`, `RESIZE_CLIP`, `SLICE_CLIP`, `INSERT_CLIP`, `DELETE_CLIP`, `SET_MEDIA_BOUNDS`, `ADD_TRACK`, `DELETE_TRACK`, `ADD_MARKER`, `ADD_EFFECT`, `ADD_KEYFRAME`, `ADD_TRANSITION`, `LINK_CLIPS`, and more
+- **Tool system** — Selection, Razor, Ripple Trim, Roll Trim, Slip, Slide, Ripple Delete, Ripple Insert, Hand, Transition, Keyframe, Zoom
+- **Undo/redo** with transaction compression
+- **Playback engine** with J/K/L shuttle control via `KeyboardHandler`
+- **Snap system** — `SnapIndexManager` with configurable snap points
+- **Virtual windowing** — `getVisibleClips()` / `getVisibleFrameRange()` for large timelines
+- **Export** — OTIO, EDL (CMX 3600), AAF, FCP XML
+- **Serialization** — versioned JSON with `serializeTimeline` / `deserializeTimeline`
+- **Import** — SRT and VTT subtitle import
+- **Project model** — multi-timeline container with bin/folder hierarchy
+- **Interval tree** — O(log n) clip lookup via `IntervalTree` / `TrackIndex`
+- **Branded types** — `TimelineFrame`, `ClipId`, `TrackId`, `FrameRate` are distinct at compile time
+- **Zero dependencies**
+
+## Quick Start
+
+```typescript
+import {
+  createTimelineState,
+  createTimeline,
+  createTrack,
+  createClip,
+  dispatch,
+  checkInvariants,
+  toFrame,
+  toTrackId,
+  toClipId,
+  toAssetId,
+  frameRate,
+} from '@webpacked-timeline/core';
+
+// 1. Build initial state
+const state = createTimelineState({
+  timeline: createTimeline({
+    id: 'tl-1',
+    name: 'My Timeline',
+    fps: frameRate(30),
+    duration: toFrame(9000),
+    tracks: [
+      createTrack({ id: toTrackId('v1'), name: 'Video 1', type: 'video' }),
+    ],
+  }),
+});
+
+// 2. Dispatch an operation
+const result = dispatch(state, {
+  id: 'tx-1',
+  label: 'Insert clip',
+  timestamp: Date.now(),
+  operations: [{
+    type: 'INSERT_CLIP',
+    trackId: toTrackId('v1'),
+    clip: createClip({
+      id: toClipId('clip-1'),
+      assetId: toAssetId('asset-1'),
+      trackId: toTrackId('v1'),
+      timelineStart: toFrame(0),
+      timelineEnd: toFrame(90),
+      mediaIn: toFrame(0),
+      mediaOut: toFrame(90),
+      name: 'Intro',
+    }),
+  }],
+});
+
+// 3. Validate
+if (result.ok) {
+  const violations = checkInvariants(result.state);
+  console.log(violations); // []
+}
+```
+
+## Playback
+
+```typescript
+import { PlaybackEngine, browserClock } from '@webpacked-timeline/core';
+
+const playback = new PlaybackEngine(
+  state,
+  { videoDecoder, compositor }, // PipelineConfig
+  { width: 1920, height: 1080 },
+  browserClock,
+);
+
+playback.play();
+```
+
+## Serialization
+
+```typescript
+import {
+  serializeTimeline,
+  deserializeTimeline,
+  exportToOTIO,
+  exportToEDL,
+  exportToAAF,
+  exportToFCPXML,
+} from '@webpacked-timeline/core';
+
+// JSON round-trip
+const json = serializeTimeline(state);
+const restored = deserializeTimeline(json);
+
+// Industry formats
+const otio = exportToOTIO(state);
+const edl = exportToEDL(state);
+const aaf = exportToAAF(state);
+const fcpxml = exportToFCPXML(state);
+```
+
+## Architecture
+
+- **Immutable state** — every operation returns a new object; unchanged clips keep their reference identity
+- **Rolling-state validation** — each op in a compound transaction is validated against the result of the previous op
+- **Branded types** — `TimelineFrame`, `ClipId`, `TrackId` are distinct types at compile time
+- **No DOM, no React** — safe to use in Workers, Node.js, or Electron main process
+
+## API Reference
+
+### Factories
+`createTimeline`, `createTrack`, `createClip`, `createAsset`, `createTimelineState`
+
+### Frame Utilities
+`toFrame`, `frameRate`, `framesToTimecode`, `framesToSeconds`, `secondsToFrames`, `FrameRates`
+
+### State Management
+`dispatch`, `checkInvariants`, `HistoryStack`, `TransactionCompressor`
+
+### Tools
+`SelectionTool`, `RazorTool`, `RippleTrimTool`, `RollTrimTool`, `SlipTool`, `SlideTool`, `RippleDeleteTool`, `RippleInsertTool`, `HandTool`, `TransitionTool`, `KeyframeTool`, `ZoomTool`
+
+### Playback
+`PlaybackEngine`, `PlayheadController`, `KeyboardHandler`, `browserClock`, `nodeClock`
+
+### Serialization & Export
+`serializeTimeline`, `deserializeTimeline`, `exportToOTIO`, `importFromOTIO`, `exportToEDL`, `exportToAAF`, `exportToFCPXML`
+
+### Performance
+`IntervalTree`, `TrackIndex`, `SnapIndexManager`, `ThumbnailCache`, `ThumbnailQueue`, `getVisibleClips`
+
+## Tests
+
+```bash
+pnpm --filter @webpacked-timeline/core test
+# 852 tests, 0 TypeScript errors
+```
+
+## License
+
+MIT