Data Model

type TimelineState = {
  readonly schemaVersion: number;
  readonly timeline: Timeline;
  readonly assetRegistry: ReadonlyMap<AssetId, Asset>;
};

import { createTimelineState, createTimeline, frameRate, toFrame } from '@timelinx/core';

const state = createTimelineState({
  timeline: createTimeline({
    id: 'tl-1',
    name: 'My Edit',
    fps: frameRate(30),
    duration: toFrame(9000), // 300 seconds at 30fps
  }),
});

type Timeline = {
  readonly id: string;
  readonly name: string;
  readonly fps: FrameRate;
  readonly duration: TimelineFrame;
  readonly version: number;
  readonly tracks: readonly Track[];
  readonly markers: readonly Marker[];
  readonly beatGrid?: BeatGrid;
  readonly inPoint?: TimelineFrame;
  readonly outPoint?: TimelineFrame;
  readonly trackGroups: readonly TrackGroup[];
  readonly linkGroups: readonly LinkGroup[];
  readonly sequenceSettings: SequenceSettings;
};

import { createTimeline, frameRate, toFrame } from '@timelinx/core';

const timeline = createTimeline({
  id: 'tl-1',
  name: 'Untitled Project',
  fps: frameRate(30),
  duration: toFrame(18000), // 10 minutes at 30fps
});
// tracks, markers, trackGroups, linkGroups default to []
// sequenceSettings defaults to 1920×1080, 48kHz, progressive

type Track = {
  readonly id: TrackId;
  readonly name: string;
  readonly type: TrackType;
  readonly locked: boolean;
  readonly muted: boolean;
  readonly solo: boolean;
  readonly height: number;
  readonly clips: readonly Clip[];
  readonly captions: readonly Caption[];
  readonly blendMode?: string;
  readonly opacity?: number;
  readonly groupId?: TrackGroupId;
};

type TrackType = 'video' | 'audio' | 'subtitle' | 'title';

import { createTrack } from '@timelinx/core';

const videoTrack = createTrack({
  id: 'v1',
  name: 'V1',
  type: 'video',
});

const audioTrack = createTrack({
  id: 'a1',
  name: 'A1',
  type: 'audio',
  height: 68,
});

Timeline:  |----[  clip  ]-----|
Asset:  [.......[mediaIn...mediaOut].......]

type Clip = {
  readonly id: ClipId;
  readonly assetId: AssetId;
  readonly trackId: TrackId;
  // Timeline bounds
  readonly timelineStart: TimelineFrame;
  readonly timelineEnd: TimelineFrame;
  // Media bounds
  readonly mediaIn: TimelineFrame;
  readonly mediaOut: TimelineFrame;
  // Playback
  readonly speed: number;
  readonly enabled: boolean;
  readonly reversed: boolean;
  // Label
  readonly name: string | null;
  readonly color: string | null;
  readonly metadata: Record<string, string>;
  // Phase 4
  readonly effects?: readonly Effect[];
  readonly transform?: ClipTransform;
  readonly audio?: AudioProperties;
  readonly transition?: Transition;
};

mediaOut - mediaIn === timelineEnd - timelineStart

import { createClip, toFrame } from '@timelinx/core';

const clip = createClip({
  id: 'clip-1',
  assetId: 'asset-interview',
  trackId: 'v1',
  timelineStart: toFrame(0),
  timelineEnd: toFrame(300),   // 10 seconds at 30fps
  mediaIn: toFrame(90),        // starts 3 seconds into the source
  mediaOut: toFrame(390),
});

type Asset = FileAsset | GeneratorAsset;

type FileAsset = {
  readonly kind: 'file';
  readonly id: AssetId;
  readonly name: string;
  readonly mediaType: TrackType;
  readonly filePath: string;
  readonly intrinsicDuration: TimelineFrame;
  readonly nativeFps: FrameRate;
  readonly sourceTimecodeOffset: TimelineFrame;
  readonly status: AssetStatus;
};

type GeneratorAsset = {
  readonly kind: 'generator';
  readonly id: AssetId;
  readonly name: string;
  readonly mediaType: TrackType;
  readonly intrinsicDuration: TimelineFrame;
  readonly nativeFps: FrameRate;
  readonly sourceTimecodeOffset: TimelineFrame;
  readonly status: AssetStatus;
  readonly generatorDef: Generator;
};

type AssetStatus = 'online' | 'offline' | 'proxy-only' | 'missing';

import { createAsset, createGeneratorAsset, frameRate, toFrame } from '@timelinx/core';

// File asset
const videoAsset = createAsset({
  id: 'asset-interview',
  name: 'interview.mp4',
  mediaType: 'video',
  filePath: '/media/interview.mp4',
  intrinsicDuration: toFrame(9000),  // 5 minutes at 30fps
  nativeFps: frameRate(30),
  sourceTimecodeOffset: toFrame(0),
});

// Generator asset (synthetic  - no file)
const colorBarAsset = createGeneratorAsset({
  id: 'asset-colorbars',
  name: 'Color Bars',
  mediaType: 'video',
  generatorDef: {
    type: 'color-bars',
    duration: toFrame(300),
  },
  nativeFps: frameRate(30),
});

import { dispatch } from '@timelinx/core';

const result = dispatch(state, {
  id: 'tx-setup',
  label: 'Register asset and add clip',
  timestamp: Date.now(),
  operations: [
    { type: 'REGISTER_ASSET', asset: videoAsset },  // ← must come before INSERT_CLIP
    { type: 'INSERT_CLIP', trackId: track.id, clip },
  ],
});

type AssetId  = string & { readonly __brand: 'AssetId' };
type ClipId   = string & { readonly __brand: 'ClipId' };
type TrackId  = string & { readonly __brand: 'TrackId' };
type MarkerId = string & { readonly __brand: 'MarkerId' };

import { toAssetId, toClipId, toTrackId, toMarkerId } from '@timelinx/core';

const assetId  = toAssetId('my-video');
const clipId   = toClipId('clip-1');
const trackId  = toTrackId('v1');
const markerId = toMarkerId('marker-chapter-1');