@bycrux/editor 0.11.2 → 1.0.1

package/src/engine/time-stretch.ts

@@ -0,0 +1,224 @@
+/**
+ * Pitch-preserving audio time-stretch — the shared primitive behind every
+ * variable-rate playback path (the fast-forward shuttle's audible scrub and
+ * per-clip speed).
+ *
+ * Runs on the MAIN thread, NOT in the AudioWorklet: it is called from the
+ * WebCodecs `AudioDecoder`'s `output` callback (which fires on main), so the
+ * stretch happens once, inline, as the PCM is produced, and the already-
+ * stretched buffer is what gets posted into the ring — the same seam
+ * `audio-clock.ts` already resamples at. Keeping the DSP here (and out of the
+ * worklet, which stays "thin by architecture" — see `audio-worklet-source.ts`)
+ * is what lets it be a pure function under vitest instead of untestable code
+ * inlined in a string.
+ *
+ * The algorithm is WSOLA (Waveform-Similarity Overlap-Add). Cut the input into
+ * overlapping Hann-windowed frames and overlap-add them back at a DIFFERENT
+ * hop: advance the read head slower than the write head and the signal grows
+ * longer; faster and it shrinks. Because each frame keeps its own local
+ * waveform, the pitch is untouched — this is the whole reason it is not a
+ * resample (`resampleInterleaved` in `audio-clock.ts`), which changes length by
+ * changing pitch. The "waveform-similarity" part is a small cross-correlation
+ * search that nudges each frame a few samples so successive frames stay phase-
+ * aligned across their overlap; that is what stops periodic sounds from beating
+ * or clicking and is the difference between WSOLA and plain OLA.
+ *
+ * This is PREVIEW quality: clearly intelligible, cheap enough to run inline in
+ * a decode callback. The final render stretches with ffmpeg's `atempo`
+ * elsewhere, not this code, so broadcast-grade transient handling is out of
+ * scope here on purpose.
+ */
+
+// ── Tuning constants ─────────────────────────────────────────────────────────
+
+/**
+ * Analysis/synthesis frame length in samples. ~21ms at 48kHz, ~23ms at 44.1kHz
+ * — long enough to hold a couple of periods of a low speech/music fundamental
+ * (down to ~90Hz), short enough that the local-stationarity assumption OLA
+ * rests on holds. Sample-count fixed (the function isn't handed a rate); the
+ * 8% span difference between the two target rates is immaterial.
+ */
+const FRAME = 1024
+
+/**
+ * Synthesis hop — the fixed output advance per frame. FRAME/2 (50% overlap) is
+ * the COLA sweet spot for a periodic Hann window: two half-overlapped Hann
+ * windows sum to exactly 1.0, so the overlap-add has unity gain in the interior
+ * with no per-sample renormalization needed there. The realized stretch factor
+ * is `SYNTH_HOP / analysisHop`.
+ */
+const SYNTH_HOP = FRAME / 2
+
+/** Overlap region length (= FRAME − SYNTH_HOP). The span the similarity search matches over. */
+const OVERLAP = FRAME - SYNTH_HOP
+
+/**
+ * How far, in samples, a frame may be nudged from its ideal read position to
+ * find the best waveform continuation. ±128 covers more than one full period of
+ * anything above ~190Hz and comfortably locks onto a 440Hz test tone (period
+ * ~109 samples), while keeping the correlation search — the hot loop — bounded.
+ */
+const SEARCH = 128
+
+/**
+ * Upper bound on the stretch factor actually applied. Guards against a
+ * pathological allocation (a caller passing 1e9 would otherwise ask for a
+ * multi-terabyte output); 32× is far beyond any real variable-rate use, where
+ * factors live in ~0.25–4.0. The low end needs no clamp — a tiny factor only
+ * ever produces a tiny (or empty) output.
+ */
+const MAX_STRETCH = 32
+
+/** Below this accumulated window weight an output sample got no real coverage → force it to silence. */
+const WEIGHT_EPSILON = 1e-6
+
+/** Below this candidate-window energy the correlation is meaningless (silence) → score 0, keep offset 0. */
+const ENERGY_EPSILON = 1e-9
+
+/**
+ * Time-stretch interleaved PCM by `factor` with pitch preserved.
+ * factor = output_duration / input_duration:
+ *   factor > 1 → longer/slower (e.g. 2.0 doubles length, half speed playback)
+ *   factor < 1 → shorter/faster (e.g. 0.5 halves length, double speed playback)
+ *   factor === 1 → identity (return input unchanged or a faithful copy)
+ * `input` is interleaved (L,R,L,R,... for stereo) Float32 at any sample rate.
+ * Returns a new interleaved Float32Array with ~ (input.length * factor) samples.
+ */
+export function timeStretch(input: Float32Array, channels: number, factor: number): Float32Array {
+  if (!Number.isFinite(factor) || factor <= 0) {
+    throw new Error(`timeStretch: factor must be a finite positive number, got ${factor}`)
+  }
+  if (!Number.isInteger(channels) || channels < 1) {
+    throw new Error(`timeStretch: channels must be a positive integer, got ${channels}`)
+  }
+  if (input.length === 0) return new Float32Array(0)
+  if (factor === 1) return input.slice() // faithful copy — never alias the caller's buffer
+
+  const f = Math.min(factor, MAX_STRETCH)
+  const inFrames = Math.floor(input.length / channels)
+  if (inFrames === 0) return new Float32Array(0)
+
+  // Read head advance per frame. `round` keeps the realized factor
+  // (SYNTH_HOP/analysisHop) as close to requested as integer hops allow;
+  // `max(1, …)` stops a large factor from rounding the hop to 0 (infinite loop).
+  const analysisHop = Math.max(1, Math.round(SYNTH_HOP / f))
+  const numFrames = Math.max(1, Math.round(inFrames / analysisHop))
+
+  // The mono mix drives the ONE similarity decision every channel shares, so L
+  // and R are nudged by the same offset and the stereo image is preserved.
+  const mono = channels === 1 ? input : downmix(input, channels, inFrames)
+  const win = hann(FRAME)
+
+  // Size for the full overlap-add span, then slice to the exact target length.
+  // Normalization (below) makes the slice clean — there is no fade at the cut.
+  const outFrames = Math.round(inFrames * f)
+  const spanFrames = (numFrames - 1) * SYNTH_HOP + FRAME
+  const totalFrames = Math.max(spanFrames, outFrames)
+  const out = new Float32Array(totalFrames * channels)
+  const weight = new Float32Array(totalFrames)
+
+  // `target` holds the previous frame's natural continuation (from the mono
+  // mix): the waveform the next frame's leading OVERLAP samples should match.
+  const target = new Float32Array(OVERLAP)
+  let hasTarget = false
+
+  for (let m = 0; m < numFrames; m++) {
+    const idealPos = m * analysisHop
+    // First frame is placed as-is; each later one is nudged within ±SEARCH to
+    // best continue the previous frame's tail across the overlap region.
+    const readPos = hasTarget ? idealPos + bestOffset(mono, inFrames, idealPos, target) : idealPos
+    const synthPos = m * SYNTH_HOP
+
+    for (let ch = 0; ch < channels; ch++) {
+      for (let i = 0; i < FRAME; i++) {
+        const src = readPos + i
+        if (src < 0 || src >= inFrames) continue // reads outside the input are silence
+        out[(synthPos + i) * channels + ch] += input[src * channels + ch] * win[i]
+      }
+    }
+    // Window weights are identical for every channel; accumulate once. Out-of-
+    // input samples still count (their signal is a real 0), which crossfades the
+    // buffer's very edges to silence rather than cutting them hard.
+    for (let i = 0; i < FRAME; i++) weight[synthPos + i] += win[i]
+
+    // The natural continuation of the frame just placed: what a match should
+    // look like SYNTH_HOP samples on. Read from the mono mix, zero-padded.
+    for (let i = 0; i < OVERLAP; i++) {
+      const p = readPos + SYNTH_HOP + i
+      target[i] = p >= 0 && p < inFrames ? mono[p] : 0
+    }
+    hasTarget = true
+  }
+
+  // Normalize by accumulated window weight → unity gain everywhere the windows
+  // covered (COLA already gives 1.0 in the interior; this also recovers the
+  // first/last samples and absorbs any drift from integer hops). Zero where
+  // nothing was written, so silence stays silence and the tail never divides
+  // by ~0.
+  for (let fr = 0; fr < totalFrames; fr++) {
+    const w = weight[fr]
+    for (let ch = 0; ch < channels; ch++) {
+      out[fr * channels + ch] = w > WEIGHT_EPSILON ? out[fr * channels + ch] / w : 0
+    }
+  }
+
+  return out.length === outFrames * channels ? out : out.slice(0, outFrames * channels)
+}
+
+// ── Internals ────────────────────────────────────────────────────────────────
+
+/** Periodic Hann window (÷N, not ÷(N−1)) — the form whose 50%-overlap copies sum to exactly 1.0. */
+function hann(n: number): Float32Array {
+  const w = new Float32Array(n)
+  for (let i = 0; i < n; i++) w[i] = 0.5 * (1 - Math.cos((2 * Math.PI * i) / n))
+  return w
+}
+
+/** Average all channels into one mono track for the shared similarity decision. */
+function downmix(input: Float32Array, channels: number, inFrames: number): Float32Array {
+  const mono = new Float32Array(inFrames)
+  for (let fr = 0; fr < inFrames; fr++) {
+    let s = 0
+    for (let ch = 0; ch < channels; ch++) s += input[fr * channels + ch]
+    mono[fr] = s / channels
+  }
+  return mono
+}
+
+/**
+ * Offset within ±SEARCH of `idealPos` whose OVERLAP-sample window best continues
+ * `target`. Ties (and total silence) resolve to 0, so a silent or aperiodic
+ * signal degrades gracefully to plain OLA at the ideal hop.
+ */
+function bestOffset(mono: Float32Array, inFrames: number, idealPos: number, target: Float32Array): number {
+  let bestOff = 0
+  let bestScore = correlate(mono, inFrames, idealPos, target)
+  for (let off = -SEARCH; off <= SEARCH; off++) {
+    if (off === 0) continue
+    const score = correlate(mono, inFrames, idealPos + off, target)
+    if (score > bestScore) {
+      bestScore = score
+      bestOff = off
+    }
+  }
+  return bestOff
+}
+
+/**
+ * Cross-correlation of `mono[pos … pos+OVERLAP)` against `target`, normalized by
+ * the candidate window's energy. The target's energy is constant across all
+ * offsets in one search, so dropping it from the denominator leaves the argmax
+ * unchanged while halving the work; normalizing by the candidate energy is what
+ * removes the bias toward louder windows. Out-of-input samples read as 0.
+ */
+function correlate(mono: Float32Array, inFrames: number, pos: number, target: Float32Array): number {
+  let dot = 0
+  let energy = 0
+  for (let i = 0; i < OVERLAP; i++) {
+    const p = pos + i
+    const c = p >= 0 && p < inFrames ? mono[p] : 0
+    dot += c * target[i]
+    energy += c * c
+  }
+  return energy <= ENERGY_EPSILON ? 0 : dot / Math.sqrt(energy)
+}

package/src/index.ts

@@ -12,6 +12,7 @@ export type {
   CaptionSegment,
   Captions,
   VisualItem,
+  VisualTrack,
   Asset,
   ImageElement,
   OverlayElement,
@@ -29,6 +30,8 @@ export type {
   OverlayFactory,
   RenderEvent,
   RenderOptions,
+  RenderExport,
+  SampleFrameOptions,
   RenderStatus,
   RenderPhase,
   CaptionEvent,
@@ -39,12 +42,27 @@ export type {
   GlobalOverlayProp,
   VersionEntry,
   WaveformChunk,
+  PeaksData,
+  PeaksResolution,
+  GetWaveformPeaksArgs,
+  FilmstripSheet,
+  FilmstripIndex,
+  GetFilmstripArgs,
+  AnalyzeAudioPolishArgs,
+  AudioPolishAnalysis,
+  FootageDropPayload,
+  PendingDrop,
+  TimelineDropPlacement,
   EditorAdapter,
+  EditorContext,
   EditorTheme,
   EditorSlots,
   CarouselEditorProps,
   VideoEditorProps,
 } from './types'
+// `FOOTAGE_DND_MIME` is a value (const), not a type — exported separately so
+// hosts can compare against it when reading a drag event's MIME data.
+export { FOOTAGE_DND_MIME } from './types'
 
 // ── Video editor pure helpers ─────────────────────────────────────────────────
 export {
@@ -52,12 +70,61 @@ export {
   applyCutToItem,
   collapseGaps,
   splitAtTime,
+  rippleDelete,
+  rollEdit,
+  slipItem,
+  slideItem,
+  setClipSpeed,
+  insertClipAt,
+  newClipId,
 } from './video/cuts'
 export type { Cut } from './video/cuts'
 export { getOverlayDesignCanvas } from './video/design-canvas'
+// Track-shape tolerance: `project.tracks` may be on disk as the legacy
+// `VisualItem[][]` or as `VisualTrack[]`. Read through `trackItems`; normalize
+// on open with `normalizeTracks` (same object back when already converged).
+export {
+  effectiveItemAudio,
+  enabledTrackItems,
+  enabledTracks,
+  mapTrackItems,
+  normalizeTracks,
+  trackItems,
+  withEnabledItemTracks,
+  withItemTracks,
+} from './video/timeline/timeline-model'
+// The one placement rule shared by both new-clip drop entry points (the
+// footage-bin drag today, a filesystem drop in a later task) — public so the
+// host can route either drop through it rather than each reimplementing
+// "land where you dropped it, without stomping existing footage".
+export { placeDroppedClip, resolveDropTrackIndex } from './video/timeline/placement'
+export type { DroppedClipPlacement, PlacedClipResult } from './video/timeline/placement'
+
+// ── Image tone (HDR image color mapping) ─────────────────────────────────────
+// The picker component is exported so hosts using `onProvideImageTone` can
+// render the same control (variant="header") in their own chrome.
+export { default as ImageToneMenu } from './video/ImageToneMenu'
+export type { ImageToneMenuProps } from './video/ImageToneMenu'
+
+// ── Speed control (slider + preset chips) ────────────────────────────────────
+// Shared by the per-clip inspect modal (host `montaj_assets/ui`) and the
+// track-wide settings popover (TrackSettingsPopover.tsx).
+export { default as SpeedControl } from './video/timeline/SpeedControl'
+export type { SpeedControlProps } from './video/timeline/SpeedControl'
+export { default as VolumeControl } from './video/timeline/VolumeControl'
+export type { VolumeControlProps } from './video/timeline/VolumeControl'
+export { IMAGE_TONES, DEFAULT_IMAGE_TONE } from './video/imageTone'
+export type { ImageTone, ImageToneInfo } from './video/imageTone'
+
+// ── SDR tone curves (HDR→SDR export look) ────────────────────────────────────
+// Descriptors + the modal's honesty copy. Exported so a host can label its own
+// chrome with the same curve names it sends as `RenderOptions.sdrCurve`.
+export { SDR_CURVES, DEFAULT_SDR_CURVE, sdrCurveInfo, honestyLine } from './video/sdrCurves'
+export type { SdrCurve, SdrCurveInfo } from './video/sdrCurves'
+export type { PreRenderOptions } from './video/RenderModal'
 
 // ── Theme ─────────────────────────────────────────────────────────────────────
-export { defaultMontajTheme, applyTheme } from './theme'
+export { defaultMontajTheme, lightMontajTheme, applyTheme, isLightTheme } from './theme'
 
 // ── State ───────────────────────────────────────────────────────────────────
 export { useProjectState } from './state/use-project-state'
@@ -116,11 +183,20 @@ export type { OverlayPreviewProps } from './preview/OverlayPreview'
 export { createPlaybackClock, usePlaybackTime } from './video/playback-clock'
 export type { PlaybackClock } from './video/playback-clock'
 
+// ── Source preview (footage-bin → main preview scrub, opt-in) ─────────────────
+// External store a host's footage bin sets to drive a source-scrub overlay on
+// the main preview. Pass the store to both the bin card and VideoEditor's
+// `sourcePreview` prop; absent → the main preview is unchanged. See
+// `video/source-preview.ts`.
+export { createSourcePreviewStore, useSourcePreview } from './video/source-preview'
+export type { SourcePreviewStore, SourcePreviewValue } from './video/source-preview'
+
 // ── Video preview ─────────────────────────────────────────────────────────────
 export { default as PreviewPlayer } from './video/preview/PreviewPlayer'
 export { default as CarouselPreview } from './video/preview/CarouselPreview'
 export { default as OverlayItemsLayer } from './video/preview/OverlayItemsLayer'
 export { useVideoPlayback } from './video/preview/useVideoPlayback'
+export { useReportContext, REPORT_INTERVAL_MS } from './video/use-report-context'
 export { useDragOverlay } from './video/preview/useDragOverlay'
 export type { Corner, DragType } from './video/preview/useDragOverlay'
 
@@ -142,3 +218,9 @@ export { default as SlideCanvas, resolveAsset } from './carousel/SlideCanvas'
 export { default as OverlayErrorBoundary } from './carousel/OverlayErrorBoundary'
 export { default as ReadOnlySlide } from './carousel/ReadOnlySlide'
 export type { ReadOnlySlideProps } from './carousel/ReadOnlySlide'
+
+// ── Footage bin (media panel) ─────────────────────────────────────────────────
+// A host's Footage/B-Roll panel drops this in per source card for the
+// hover-scrub thumbnail (docs/plans/footage-bin-media-panel.md, Phase 2/3).
+export { default as FilmstripScrubber } from './components/FilmstripScrubber'
+export type { FilmstripScrubberProps } from './components/FilmstripScrubber'

package/src/preview/OverlayPreview.tsx

@@ -14,44 +14,22 @@
 
 import React, { useEffect, useState } from 'react'
 import type { OverlayFactory } from '../types'
+import { Loader } from '../ui/Loader'
 
 // ── Defaults ─────────────────────────────────────────────────────────────────
 
 function DefaultSpinner(): React.ReactElement {
   return (
     <div
-      role="status"
-      aria-label="Loading overlay"
       style={{
         position: 'absolute',
         inset: 0,
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'center',
-        color: 'rgba(255, 255, 255, 0.65)',
       }}
     >
-      <svg
-        width="36"
-        height="36"
-        viewBox="0 0 24 24"
-        fill="none"
-        stroke="currentColor"
-        strokeWidth="2"
-        strokeLinecap="round"
-      >
-        <g>
-          <path d="M21 12a9 9 0 1 1-6.219-8.56" />
-          <animateTransform
-            attributeName="transform"
-            type="rotate"
-            from="0 12 12"
-            to="360 12 12"
-            dur="0.9s"
-            repeatCount="indefinite"
-          />
-        </g>
-      </svg>
+      <Loader size="sm" />
     </div>
   )
 }

package/src/schema.ts

@@ -30,8 +30,14 @@ export interface AudioTrack {
   }
   fadeIn?: number          // fade-in duration in seconds (0 = no fade)
   fadeOut?: number         // fade-out duration in seconds (0 = no fade)
+  // Envelope shape for each fade — see video/timeline/canvas/fade-curve.ts.
+  // Absent ⇒ DEFAULT_FADE_CURVE ('exp'), which is also the shape every fade
+  // rendered before curves existed, so an un-set project looks unchanged.
+  fadeInCurve?: 'linear' | 'log' | 'exp'
+  fadeOutCurve?: 'linear' | 'log' | 'exp'
   sourceDuration?: number  // intrinsic duration of the source file in seconds
   lane?: number            // visual grouping — tracks sharing a lane render in the same row
+  magnetic?: boolean       // when set, this clip's LANE is kept gapless (no gaps/overlaps). Fanned out across the lane like `muted`.
 }
 
 export interface CaptionSegment {
@@ -53,6 +59,24 @@ export interface CaptionSegment {
   // ffmpeg `drawtext` render branch has no per-segment concept and keeps
   // reading only the track-level `color`.
   color?: string
+  // Vertical row this segment renders in. Captions in different lanes may be
+  // simultaneous and all render, each getting its own row in the timeline and
+  // preview. Absent ⇒ lane 0, and NOT auto-incremented.
+  //
+  // This deliberately diverges from `AudioTrack.lane` / `groupAudioLanes`
+  // (timeline/timeline-model.ts), which mint a fresh lane for every lane-less
+  // track: every caption segment written before lanes existed is lane-less,
+  // so applying that same rule here would explode every existing project's
+  // captions into one row per caption on first open, instead of the single
+  // row they've always rendered as.
+  //
+  // Invariant: lanes are dense from 0 (no holes). Read and write this field
+  // through `video/captionLanes.ts` rather than touching it directly, so that
+  // invariant holds everywhere. Lane is z-order only — a higher lane paints
+  // on top; it carries no styling of its own. `Captions.style` and the
+  // track-level theme fields (color, fontsize, accentColor, …) stay
+  // track-global and do not vary per lane.
+  lane?: number
 }
 
 export interface Captions {
@@ -67,12 +91,69 @@ export interface Captions {
   fontsize?: number
   bgColor?: string
   // Per-style accent color fields, each read by the matching JSX caption template.
-  // A single UI control writes whichever one the active style uses (see TranscriptPanel).
+  // A single UI control writes whichever one the active style uses (see CaptionListPanel).
   accentColor?: string    // active-word/box accent — highlight-box, outline
   highlightColor?: string // active word — karaoke
   activeColor?: string    // active word — pop
   backgroundColor?: string// text box background — subtitle
   googleFonts?: string[]  // Google Fonts family specs for the caption template (e.g. ["Figtree:wght@700"])
+  // Text-styling fields, honoured by the JSX caption templates only (NOT the ffmpeg
+  // drawtext render branch). `fontFamily` and `googleFonts` travel together: a family
+  // whose font file isn't also fetched via `googleFonts` renders as the fallback face,
+  // in both the editor preview and the export.
+  fontFamily?: string      // CSS font-family stack (e.g. '"Baloo 2", system-ui, sans-serif')
+  fontWeight?: number | string // default is per style: clean/karaoke 700, subtitle 600,
+                                // pop/word-by-word 800, highlight-box/outline 900 — so an
+                                // existing project with no fontWeight renders unchanged.
+  textTransform?: string   // 'uppercase' | 'lowercase' | 'capitalize' | 'none'
+  letterSpacing?: string   // CSS length, e.g. '0.02em'
+  lineHeight?: number | string
+  textAlign?: string       // 'left' | 'center' | 'right'
+}
+
+/** Easing applied across the segment LEAVING a keyframe. `hold` is step-end:
+ *  the value is held until the next keyframe's `t`, then jumps. */
+export type EasingName = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'hold'
+
+/** The transform properties that can be keyframed. Which item KINDS support
+ *  which of them is decided by `canKeyframe` / `canKeyframeProp`
+ *  (`montaj_assets/editor/src/video/keyframeOps.ts`) — the runtime source of
+ *  truth, not this type.
+ *
+ *  `keyframes` is NO LONGER overlay-only (SP9d). Overlays, `image` and
+ *  `video` items all animate their geometry, in the preview and in the
+ *  export alike: the renderer compiles each curve into a time-varying ffmpeg
+ *  filter expression (`render/encode-segment.js`, `animatedGeometry`), which
+ *  is the per-frame hook the ffmpeg path used to lack.
+ *
+ *  OPACITY ANIMATION is what stayed overlay-only, and that one IS a hard
+ *  render constraint: ffmpeg applies alpha through `colorchannelmixer`,
+ *  whose `aa` option is a `<double>` and accepts no expression at all, so a
+ *  clip cannot be faded through that path in any form. Overlays escape it by
+ *  being captured frame-by-frame in a browser, where opacity is just CSS.
+ *  See `canKeyframeProp` for the full reasoning and `docs/RENDER.md` for the
+ *  measured cost of the alternative. */
+export type KeyframeProp = 'offsetX' | 'offsetY' | 'scale' | 'scaleX' | 'scaleY' | 'rotation' | 'opacity'
+
+export interface Keyframe {
+  t: number               // ITEM-relative seconds — 0 is the item's own `start`, not timeline zero
+  value: number
+  easing?: EasingName     // governs the segment from THIS keyframe to the next; absent = 'linear'
+}
+
+/** One animated property. `points` must be ascending by `t` with no duplicates:
+ *  the read path (`sampleTrack`) assumes it and deliberately does not sort, so
+ *  the editor normalizes on write.
+ *
+ *  These four types intentionally mirror the canonical definitions in
+ *  `@bycrux/timeline-core` (`src/curves.js`, declared in its `index.d.ts`),
+ *  which is where the interpolation actually happens for BOTH the preview and
+ *  the render. They are re-declared rather than imported because this file is
+ *  deliberately self-contained (see the header). Keep the two in sync — the
+ *  shapes are structurally compatible by design. */
+export interface KeyframeTrack {
+  prop: KeyframeProp
+  points: Keyframe[]
 }
 
 export interface VisualItem {
@@ -82,6 +163,7 @@ export interface VisualItem {
   start: number
   end: number
   sourceDuration?: number     // video type only — used for right-edge drag guard
+  sourceCreatedAt?: string    // video type only — container recording timestamp (ISO 8601); footage-bin "Date created" sort. Absent when the source carried no creation_time tag.
   inPoint?: number            // video type only
   outPoint?: number           // video type only
   loop?: boolean              // video type only — loop source clip within project window
@@ -89,10 +171,17 @@ export interface VisualItem {
   offsetX?: number
   offsetY?: number
   scale?: number
+  scaleX?: number          // absent = fall back to `scale` (the resolver does `scaleX ?? scale ?? 1`)
+  scaleY?: number          // absent = fall back to `scale` (the resolver does `scaleY ?? scale ?? 1`)
   opacity?: number        // 0.0–1.0
   fit?: 'cover' | 'contain' | 'fill'  // image type only — how the source fills its box. Default 'cover' (AR-preserving fill+crop). 'contain' letterboxes; 'fill' is legacy stretch (no AR).
   volume?: number         // video audio level 0.0–2.0, default 1.0 (ignored for images)
   rotation?: number       // degrees, clockwise
+  /** Which item kinds support this is decided by `canKeyframe`
+   *  (video/keyframeOps.ts), the runtime source of truth — see `KeyframeProp`
+   *  above for why it's overlay-only today (a render constraint, not a UI
+   *  preference). */
+  keyframes?: KeyframeTrack[]  // animates the transform props over the item's own lifetime. Overlays, images and video clips all honour it; `opacity` animates on overlays ONLY (see KeyframeProp). Absent = a static item, which renders on the unchanged ffmpeg-positioned path.
   opaque?: boolean        // legacy boolean kept for old overlay items
   props?: Record<string, unknown>  // overlay type only
   googleFonts?: string[]  // overlay type only — Google Fonts family specs (e.g. ["Syne:wght@800"])
@@ -102,7 +191,15 @@ export interface VisualItem {
   normalizedSrc?: string    // derived per-window normalized cache; render/preview prefer it; src stays original
   /** Source-time (original coords) the normalizedSrc cache starts at; the cache covers [normalizedInPoint, normalizedInPoint + duration]. Absent ⇒ assume it starts at the clip's inPoint (legacy rebase-to-0). */
   normalizedInPoint?: number
+  /** Full-source, all-intra 720p H.264+Opus editing proxy for instant-scrub preview (SP3). Never windowed —
+   * no `proxyInPoint` — so one proxy can serve every clip sharing a lazy source. Preview-only: render never
+   * reads this field. Preview's src precedence, alpha-safe, is
+   * `nobg_preview_src ?? proxySrc ?? normalizedSrc ?? src`. Filename carries a look-version tag
+   * (`<stem>_proxy_<PROXY_LOOK>.mp4`); bumping `PROXY_LOOK` (e.g. when Montaj Vivid ships) invalidates every
+   * existing proxy by construction — the freshness check sees a different filename and regenerates lazily. */
+  proxySrc?: string         // video type only
   muted?: boolean         // video type only — suppress audio in preview and render
+  speed?: number          // video type only — playback speed, default 1.0, range 0.25–4
   sourceCrop?: { x: number; y: number; w: number; h: number }  // video type only — non-destructive crop of the source clip (0–1 fractions)
   sourceWidth?: number    // video type only — intrinsic width of the source clip in pixels
   sourceHeight?: number   // video type only — intrinsic height of the source clip in pixels
@@ -141,6 +238,32 @@ export interface VisualItem {
   text?: string
 }
 
+/**
+ * One visual track: its items plus the properties that belong to the TRACK
+ * rather than to any one clip. Track ORDER is meaningful — index 0 is the
+ * primary footage track, higher indices render on top.
+ *
+ * `volume`, `muted` and `enabled` are optional and ABSENT by default; a track
+ * carrying none of them behaves exactly as it did before tracks became
+ * objects, so nothing needs to write a default in.
+ *
+ * A project may still be on disk in the legacy `VisualItem[][]` shape (a bare
+ * array of item arrays, with nowhere to put the fields above). Readers tolerate
+ * both shapes by going through `trackItems()` (video/timeline/timeline-model)
+ * rather than touching `project.tracks` directly; `normalizeTracks()` converts
+ * legacy → this shape when a project is opened.
+ */
+export interface VisualTrack {
+  id: string
+  items: VisualItem[]
+  /** Gain applied to every item's audio on this track. Absent = unity (1.0). */
+  volume?: number
+  /** Absent or false = audible. */
+  muted?: boolean
+  /** Absent or true = the track renders. */
+  enabled?: boolean
+}
+
 export interface Asset {
   id: string
   src: string
@@ -215,11 +338,31 @@ export interface Slide {
 export interface EditorProject {
   id: string
   status: 'pending' | 'storyboard_ready' | 'draft' | 'final'
-  settings: { resolution: [number, number]; fps?: number; brandKit?: string; normalize?: 'eager' | 'lazy' }
+  settings: {
+    resolution: [number, number]
+    fps?: number
+    brandKit?: string
+    normalize?: 'eager' | 'lazy'
+    /** Project working color space (e.g. 'sdr_bt709', 'hdr_hlg'). Written by
+     *  the render pipeline's smart-detect; read here to gate HDR-only UI. */
+    colorSpace?: string
+    /** Color mapping for overlay images in HDR renders — see video/imageTone.ts.
+     *  Absent → the render default ('vivid'). No effect on SDR projects. */
+    imageTone?: 'vivid' | 'broadcast' | 'punchy' | 'raw'
+    /** Which platform's chrome the preview overlays on top of the video — see
+     *  video/preview/SocialSafeZoneOverlay.tsx. A viewing aid only; never read
+     *  by render. Absent = no chrome shown (the "None" picker option, and the
+     *  default for every project until the operator picks a platform). */
+    socialPreview?: 'tiktok' | 'youtube' | 'instagram'
+    /** Whether dragging the playhead plays audible scrub grains (tape
+     *  jog-wheel feel) — see engine/scrub-source.ts. Default false (opt-in);
+     *  an explicit `true` persists the operator's opt-in. */
+    audibleScrub?: boolean
+  }
   name?: string | null
   editingPrompt?: string
   slides?: Slide[]
-  tracks?: VisualItem[][]
+  tracks?: VisualTrack[]
   captions?: Captions
   audio?: { tracks: AudioTrack[] }
   assets?: Asset[]