@bycrux/editor 1.0.2 → 1.2.0

package/src/video/timeline/__tests__/markers.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest'
+import { addMarker, moveMarker, removeMarkers, renameMarker, nextMarkerLabel } from '../markers'
+import type { EditorProject, Marker } from '../../../schema'
+
+function proj(markers?: Marker[]): EditorProject {
+  return {
+    id: 'p1', status: 'draft', settings: { resolution: [1920, 1080], fps: 30 },
+    tracks: [{ id: 'trk-0', items: [] }],
+    ...(markers ? { markers } : {}),
+  } as EditorProject
+}
+const mk = (id: string, t: number, label: string): Marker => ({ id, t, label })
+
+describe('nextMarkerLabel', () => {
+  it('starts at 1 on a project with no markers', () => {
+    expect(nextMarkerLabel([])).toBe('1')
+  })
+
+  it('continues past the highest NUMERIC label, ignoring renamed ones', () => {
+    // A renamed marker must not stall the counter, and must not be parsed as 0.
+    expect(nextMarkerLabel([mk('a', 1, '1'), mk('b', 2, 'cut this'), mk('c', 3, '7')])).toBe('8')
+  })
+
+  it('does not reuse a number after a delete', () => {
+    // Counting markers instead of reading the max would hand out '2' twice here.
+    expect(nextMarkerLabel([mk('a', 1, '1'), mk('c', 3, '3')])).toBe('4')
+  })
+})
+
+describe('addMarker', () => {
+  it('creates the markers array on a project that has none', () => {
+    const out = addMarker(proj(), 4.25)
+    expect(out.markers).toHaveLength(1)
+    expect(out.markers![0]).toMatchObject({ t: 4.25, label: '1' })
+    expect(typeof out.markers![0].id).toBe('string')
+    expect(out.markers![0].id.length).toBeGreaterThan(0)
+  })
+
+  it('keeps markers sorted by time whatever order they are added in', () => {
+    let p = addMarker(proj(), 10)
+    p = addMarker(p, 2)
+    p = addMarker(p, 6)
+    expect(p.markers!.map(m => m.t)).toEqual([2, 6, 10])
+    // Labels record creation order, not position.
+    expect(p.markers!.map(m => m.label)).toEqual(['2', '3', '1'])
+  })
+
+  it('returns the SAME reference when a marker already sits within half a frame', () => {
+    // Key repeat: holding M must not spray a pile of stacked markers.
+    const p = addMarker(proj(), 5)
+    const again = addMarker(p, 5 + (1 / 30) * 0.4, 30)
+    expect(again).toBe(p)
+  })
+
+  it('does allow a second marker just outside the half-frame window', () => {
+    const p = addMarker(proj(), 5)
+    const again = addMarker(p, 5 + (1 / 30) * 0.6, 30)
+    expect(again).not.toBe(p)
+    expect(again.markers).toHaveLength(2)
+  })
+
+  it('clamps a negative time to 0', () => {
+    expect(addMarker(proj(), -3).markers![0].t).toBe(0)
+  })
+
+  it('never mutates the project it was given', () => {
+    const p = proj([mk('a', 1, '1')])
+    const before = JSON.stringify(p)
+    addMarker(p, 9)
+    expect(JSON.stringify(p)).toBe(before)
+  })
+})
+
+describe('moveMarker', () => {
+  it('retimes and re-sorts', () => {
+    const p = proj([mk('a', 1, '1'), mk('b', 2, '2'), mk('c', 3, '3')])
+    const out = moveMarker(p, 'a', 2.5)
+    expect(out.markers!.map(m => m.id)).toEqual(['b', 'a', 'c'])
+    expect(out.markers!.find(m => m.id === 'a')!.t).toBe(2.5)
+  })
+
+  it('clamps to 0 and returns the same reference for an unknown id or an unchanged time', () => {
+    const p = proj([mk('a', 1, '1')])
+    expect(moveMarker(p, 'a', -5).markers![0].t).toBe(0)
+    expect(moveMarker(p, 'nope', 4)).toBe(p)
+    expect(moveMarker(p, 'a', 1)).toBe(p)
+  })
+})
+
+describe('renameMarker', () => {
+  it('replaces the label', () => {
+    const out = renameMarker(proj([mk('a', 1, '1')]), 'a', 'intro')
+    expect(out.markers![0].label).toBe('intro')
+  })
+
+  it('trims, and rejects an empty label by returning the same reference', () => {
+    const p = proj([mk('a', 1, '1')])
+    expect(renameMarker(p, 'a', '  hi  ').markers![0].label).toBe('hi')
+    expect(renameMarker(p, 'a', '   ')).toBe(p)
+    expect(renameMarker(p, 'a', '1')).toBe(p)   // unchanged label, no commit
+  })
+})
+
+describe('removeMarkers', () => {
+  it('drops every id in the set and leaves the rest', () => {
+    const p = proj([mk('a', 1, '1'), mk('b', 2, '2'), mk('c', 3, '3')])
+    expect(removeMarkers(p, new Set(['a', 'c'])).markers!.map(m => m.id)).toEqual(['b'])
+  })
+
+  it('drops the markers key entirely when the last one goes', () => {
+    // Keeps a marker-less project byte-identical to one that never had markers.
+    const out = removeMarkers(proj([mk('a', 1, '1')]), new Set(['a']))
+    expect(out).not.toHaveProperty('markers')
+  })
+
+  it('returns the same reference when nothing matched', () => {
+    const p = proj([mk('a', 1, '1')])
+    expect(removeMarkers(p, new Set(['zzz']))).toBe(p)
+  })
+
+  it('returns the same reference when the project has no markers at all', () => {
+    const p = proj()
+    expect(removeMarkers(p, new Set(['a']))).toBe(p)
+  })
+})

package/src/video/timeline/__tests__/timeline-model.test.ts

@@ -6,11 +6,14 @@ import {
   resolveAudioWindow,
   computeAutoCrossfade,
   computeDerivedTiming,
+  computeVisualCrossfade,
   groupAudioLanes,
   mapTrackItems,
+  normalizeAudioTracks,
   normalizeTrackOrder,
   normalizeTracks,
   trackItems,
+  updateAudioTrack,
 } from '../timeline-model'
 
 function track(overrides: Partial<AudioTrack> = {}): AudioTrack {
@@ -165,6 +168,36 @@ describe('computeAutoCrossfade', () => {
     expect(next!.audio!.tracks.map(t => t.id)).toEqual(['solo', 'a', 'b'])
     expect(next!.audio!.tracks.find(t => t.id === 'solo')!.fadeOut).toBeUndefined()
   })
+
+  // Regression test for the sharpest edge of the id-less-audio-track defect.
+  // `trackMap = new Map(updated.map(t => [t.id, t]))` keys on `t.id`; with two
+  // id-less tracks, both keys are the same `undefined`, so the map collapses
+  // to ONE entry (the last one processed) and `audioTracks.map(t =>
+  // trackMap.get(t.id) ?? t)` hands that SAME entry back for every original
+  // track — every track in the project becomes a byte-identical copy of it,
+  // `src` included. This runs unconditionally on any project with two
+  // overlapping audio tracks, no user edit required, which is why it's the
+  // sharpest edge: it doesn't wait for a gesture like `updateAudioTrack` does.
+  it('does not collapse two overlapping id-less audio tracks into copies of each other', () => {
+    const p = project({
+      audio: {
+        tracks: [
+          { src: 'music-a.mp3', start: 0, end: 3 } as AudioTrack,
+          { src: 'music-b.mp3', start: 2, end: 5 } as AudioTrack,
+        ],
+      },
+    })
+    const next = computeAutoCrossfade(p)
+    expect(next).not.toBeNull()
+    const tracks = next!.audio!.tracks
+    expect(tracks).toHaveLength(2)
+    expect(new Set(tracks.map(t => t.id)).size).toBe(2)
+    // Each track keeps its OWN src — neither becomes a copy of the other.
+    expect(tracks.find(t => t.start === 0)!.src).toBe('music-a.mp3')
+    expect(tracks.find(t => t.start === 2)!.src).toBe('music-b.mp3')
+    expect(tracks.find(t => t.start === 0)!.fadeOut).toBe(1)
+    expect(tracks.find(t => t.start === 2)!.fadeIn).toBe(1)
+  })
 })
 
 describe('groupAudioLanes', () => {
@@ -574,3 +607,277 @@ describe('mapTrackItems', () => {
     expect(mapTrackItems({ id: 'p1', tracks: 'nope' } as Proj, items => items)).toEqual([])
   })
 })
+
+// ── Audio track id policy ────────────────────────────────────────────────
+//
+// Same load-bearing properties as `normalizeTracks` above: normalization
+// never mutates its input, is idempotent, and returns the SAME OBJECT when
+// every audio track already has a usable id (the lazy on-open migration
+// reads that identity as "no write needed").
+
+describe('normalizeAudioTracks', () => {
+  /** Deliberately loose, like the function itself. */
+  type Proj = { id: string; audio?: unknown }
+  interface NormTrack { id: string; src: string; [k: string]: unknown }
+
+  const raw = (id: unknown, src: string, extra: Record<string, unknown> = {}) =>
+    (id === undefined ? { src, ...extra } : { id, src, ...extra })
+
+  /** The normalized audio tracks, typed. */
+  const tracksOf = (p: Proj): NormTrack[] => (normalizeAudioTracks(p).audio as { tracks: NormTrack[] }).tracks
+
+  it('fills in distinct ids for tracks with no id at all', () => {
+    const out = tracksOf({ id: 'p1', audio: { tracks: [raw(undefined, 'a.mp3'), raw(undefined, 'b.mp3')] } })
+    expect(out.map(t => t.id)).toEqual(['aud-0', 'aud-1'])
+    expect(new Set(out.map(t => t.id)).size).toBe(2)
+  })
+
+  it('fills in a missing, empty, or non-string id', () => {
+    const out = tracksOf({
+      id: 'p1',
+      audio: { tracks: [raw(undefined, 'a.mp3'), raw('', 'b.mp3'), raw(7, 'c.mp3')] },
+    })
+    expect(out.map(t => t.id)).toEqual(['aud-0', 'aud-1', 'aud-2'])
+  })
+
+  it('lets the first holder of a duplicate id keep it', () => {
+    const out = tracksOf({
+      id: 'p1',
+      audio: { tracks: [raw('dup', 'a.mp3'), raw('dup', 'b.mp3')] },
+    })
+    expect(out.map(t => t.id)).toEqual(['dup', 'aud-1'])
+    // The first holder keeps ITS OWN src, not the second track's.
+    expect(out[0].src).toBe('a.mp3')
+    expect(out[1].src).toBe('b.mp3')
+  })
+
+  it('steps a generated id aside when an explicit id already claims the name', () => {
+    const out = tracksOf({
+      id: 'p1',
+      audio: { tracks: [raw(undefined, 'a.mp3'), raw('aud-0', 'b.mp3')] },
+    })
+    expect(out.map(t => t.id)).toEqual(['aud-0-2', 'aud-0'])
+  })
+
+  it('keeps generated ids unique under repeated collision', () => {
+    const out = tracksOf({
+      id: 'p1',
+      audio: { tracks: [raw(undefined, 'a.mp3'), raw('aud-0', 'b.mp3'), raw('aud-0-2', 'c.mp3')] },
+    })
+    expect(out.map(t => t.id)).toEqual(['aud-0-3', 'aud-0', 'aud-0-2'])
+    expect(new Set(out.map(t => t.id)).size).toBe(3)
+  })
+
+  it('preserves existing valid ids (e.g. init.py-style `vo-01`) untouched', () => {
+    const p: Proj = { id: 'p1', audio: { tracks: [raw('vo-01', 'voice.wav'), raw('music-bed', 'bed.mp3')] } }
+    expect(normalizeAudioTracks(p)).toBe(p)
+  })
+
+  it('returns the SAME OBJECT when every track already has a usable id', () => {
+    const p: Proj = { id: 'p1', audio: { tracks: [raw('aud-0', 'a.mp3'), raw('aud-1', 'b.mp3')] } }
+    expect(normalizeAudioTracks(p)).toBe(p)
+  })
+
+  it('is idempotent and converges, so a second pass needs no write', () => {
+    const once = normalizeAudioTracks({ id: 'p1', audio: { tracks: [raw(undefined, 'a.mp3'), raw(undefined, 'b.mp3')] } })
+    const twice = normalizeAudioTracks(once)
+    expect(twice).toBe(once)
+  })
+
+  it('carries volume / muted / fadeIn / ducking and unknown keys through untouched', () => {
+    const out = tracksOf({
+      id: 'p1',
+      audio: {
+        tracks: [raw(undefined, 'a.mp3', {
+          volume: 0.15, muted: true, fadeIn: 1.5, ducking: { enabled: true, depth: -12 }, somethingNew: { a: 1 },
+        })],
+      },
+    })
+    expect(out[0]).toEqual({
+      id: 'aud-0', src: 'a.mp3', volume: 0.15, muted: true, fadeIn: 1.5,
+      ducking: { enabled: true, depth: -12 }, somethingNew: { a: 1 },
+    })
+  })
+
+  it('does not mutate its input', () => {
+    const p: Proj = { id: 'p1', audio: { tracks: [raw(undefined, 'a.mp3')] } }
+    const before = structuredClone(p)
+    tracksOf(p)
+    expect(p).toEqual(before)
+  })
+
+  it('is tolerant of a project with no audio, or a malformed audio/tracks, and never throws', () => {
+    const missing: Proj = { id: 'p1' }
+    expect(normalizeAudioTracks(missing)).toBe(missing)
+    expect('audio' in normalizeAudioTracks(missing)).toBe(false)
+
+    for (const audio of [null, 'nope', 7, []]) {
+      const p: Proj = { id: 'p1', audio }
+      expect(() => normalizeAudioTracks(p)).not.toThrow()
+      expect(normalizeAudioTracks(p)).toBe(p)
+    }
+
+    for (const tracks of [undefined, null, 'nope', {}]) {
+      const p: Proj = { id: 'p1', audio: { tracks } }
+      expect(() => normalizeAudioTracks(p)).not.toThrow()
+      expect(normalizeAudioTracks(p)).toBe(p)
+    }
+
+    const empty: Proj = { id: 'p1', audio: { tracks: [] } }
+    expect(normalizeAudioTracks(empty)).toBe(empty)
+  })
+})
+
+describe('updateAudioTrack', () => {
+  it('patches only the matching track when ids are already real', () => {
+    const p = project({
+      audio: { tracks: [track({ id: 'a', src: 'a.mp3', volume: 1 }), track({ id: 'b', src: 'b.mp3', volume: 1 })] },
+    })
+    const out = updateAudioTrack(p, 'a', { volume: 0.4 })
+    expect(out.audio?.tracks.find(t => t.id === 'a')?.volume).toBe(0.4)
+    expect(out.audio?.tracks.find(t => t.id === 'b')).toEqual(track({ id: 'b', src: 'b.mp3', volume: 1 }))
+  })
+
+  // Regression test for the actual defect: `docs/schemas/project.md` never
+  // required `id` on an audio track, but every editor mutation (this
+  // function included) used to key a track by `id` with `===`. Two id-less
+  // tracks both read `id` as the same `undefined`, so `t.id === trackId`
+  // matched BOTH of them at once — dragging one fade handle on a 2-track
+  // music bed fanned the edit out and clobbered the sibling. Reproduced here
+  // exactly as the live app hits it: the ids passed in are the ones
+  // `normalizeAudioTracks` (VideoEditor's on-open backfill) would hand out —
+  // `aud-0`/`aud-1` — but `updateAudioTrack` itself is called with the
+  // ORIGINAL, still id-less project, proving it is safe even when a caller
+  // hasn't normalized first.
+  it('edits exactly one id-less audio track, leaving its sibling byte-for-byte untouched', () => {
+    const original: Project = project({
+      audio: {
+        tracks: [
+          { src: 'music-a.mp3', start: 0, end: 10, volume: 1 } as AudioTrack,
+          { src: 'music-b.mp3', start: 10, end: 20, volume: 1 } as AudioTrack,
+        ],
+      },
+    })
+    const untouchedSibling = original.audio!.tracks[1]
+    const targetId = normalizeAudioTracks(original).audio!.tracks[0].id
+
+    const out = updateAudioTrack(original, targetId, { volume: 0.4 })
+
+    expect(out.audio?.tracks).toHaveLength(2)
+    expect(out.audio?.tracks[0].volume).toBe(0.4)
+    expect(out.audio?.tracks[0].src).toBe('music-a.mp3')
+    // The defect this guards against: the sibling's `src` (and every other
+    // field) must be exactly what it started as — not silently fanned into
+    // the edited track's values.
+    expect(out.audio?.tracks[1]).toEqual({ ...untouchedSibling, id: out.audio?.tracks[1].id })
+    expect(out.audio?.tracks[1].src).toBe('music-b.mp3')
+    expect(out.audio?.tracks[1].volume).toBe(1)
+  })
+})
+
+// ── Visual crossfade (overlays) ──────────────────────────────────────────
+
+/** An overlay item. `extra` carries whatever the case under test needs —
+ *  `opaque`, a hand-authored `keyframes` array — without a helper per shape. */
+const ov = (id: string, start: number, end: number, extra: Record<string, unknown> = {}) =>
+  ({ id, type: 'overlay' as const, src: 'Card.jsx', start, end, ...extra })
+
+/** Two-track project in the OBJECT form: `tracks[0]` is the (empty) primary
+ *  footage row `computeVisualCrossfade` skips wholesale, `tracks[1]` is the
+ *  overlay row under test. */
+const proj = (items: unknown[]) => ({
+  version: '0.2',
+  tracks: [{ id: 'trk-0', items: [] }, { id: 'trk-1', items }],
+}) as never
+
+const opacityTrack = (p: Project, trackIdx: number, itemIdx: number) =>
+  (p as unknown as { tracks: { items: { keyframes?: { prop: string; points: unknown[] }[] }[] }[] })
+    .tracks[trackIdx].items[itemIdx].keyframes?.find(k => k.prop === 'opacity')
+
+describe('computeVisualCrossfade', () => {
+  it('writes complementary opacity curves onto a transparent overlapping pair', () => {
+    const out = computeVisualCrossfade(proj([ov('a', 0, 4), ov('b', 3, 8)]))!
+    expect(out).not.toBeNull()
+    // 'a' fades 1 -> 0 over its LAST second (item-relative t = 3 .. 4)
+    expect(opacityTrack(out, 1, 0)!.points).toEqual([
+      { t: 3, value: 1 }, { t: 4, value: 0 },
+    ])
+    // 'b' fades 0 -> 1 over its FIRST second (item-relative t = 0 .. 1)
+    expect(opacityTrack(out, 1, 1)!.points).toEqual([
+      { t: 0, value: 0 }, { t: 1, value: 1 },
+    ])
+  })
+
+  it('holds the outgoing side when it is opaque', () => {
+    const out = computeVisualCrossfade(
+      proj([ov('a', 0, 4, { opaque: true }), ov('b', 3, 8, { opaque: true })]),
+    )!
+    expect(opacityTrack(out, 1, 0)).toBeUndefined()          // 'a' holds — no track written
+    expect(opacityTrack(out, 1, 1)!.points).toEqual([
+      { t: 0, value: 0 }, { t: 1, value: 1 },
+    ])
+  })
+
+  it('is idempotent — a converged project reports no change', () => {
+    const once = computeVisualCrossfade(proj([ov('a', 0, 4), ov('b', 3, 8)]))!
+    expect(computeVisualCrossfade(once as never)).toBeNull()
+  })
+
+  it('returns null when nothing overlaps', () => {
+    expect(computeVisualCrossfade(proj([ov('a', 0, 4), ov('b', 4, 8)]))).toBeNull()
+  })
+
+  it('never touches an item whose opacity was keyframed by hand', () => {
+    const authored = ov('b', 3, 8, {
+      keyframes: [{ prop: 'opacity', points: [{ t: 0, value: 0.5 }] }],
+    })
+    expect(computeVisualCrossfade(proj([ov('a', 0, 4), authored]))).toBeNull()
+  })
+
+  it('leaves clips alone — a video pair gets no keyframes', () => {
+    const clip = (id: string, s: number, e: number) =>
+      ({ id, type: 'video' as const, src: 'a.mov', start: s, end: e, inPoint: 0, outPoint: e - s })
+    expect(computeVisualCrossfade(proj([clip('a', 0, 4), clip('b', 3, 8)]))).toBeNull()
+  })
+
+  it('preserves a non-opacity keyframe track already on the item', () => {
+    const moving = ov('b', 3, 8, {
+      keyframes: [{ prop: 'offsetX', points: [{ t: 0, value: -20 }, { t: 1, value: 0 }] }],
+    })
+    const out = computeVisualCrossfade(proj([ov('a', 0, 4), moving]))!
+    const kf = (out as unknown as { tracks: { items: { keyframes: { prop: string }[] }[] }[] })
+      .tracks[1].items[1].keyframes
+    expect(kf.map(k => k.prop).sort()).toEqual(['offsetX', 'opacity'])
+  })
+
+  it('scales the derived curve by each side\'s own base opacity', () => {
+    // Both sides authored at 0.5 opacity (not via a keyframe track — that
+    // would be "hand-authored" and skip derivation entirely per the test
+    // above). The derived fade must ride on top of that base level, not
+    // silently replace it with a full 1<->0 fade for the pair's whole
+    // pre/post-overlap life.
+    const out = computeVisualCrossfade(
+      proj([ov('a', 0, 4, { opacity: 0.5 }), ov('b', 3, 8, { opacity: 0.5 })]),
+    )!
+    expect(out).not.toBeNull()
+    // 'a' fades 0.5 -> 0 over its LAST second
+    expect(opacityTrack(out, 1, 0)!.points).toEqual([
+      { t: 3, value: 0.5 }, { t: 4, value: 0 },
+    ])
+    // 'b' fades 0 -> 0.5 over its FIRST second
+    expect(opacityTrack(out, 1, 1)!.points).toEqual([
+      { t: 0, value: 0 }, { t: 1, value: 0.5 },
+    ])
+  })
+
+  it('removes a derived curve when the overlap is removed', () => {
+    const faded = computeVisualCrossfade(proj([ov('a', 0, 4), ov('b', 3, 8)]))!
+    const pulled = structuredClone(faded) as unknown as
+      { tracks: { items: { start: number; end: number }[] }[] }
+    pulled.tracks[1].items[1].start = 4
+    const out = computeVisualCrossfade(pulled as never)!
+    expect(out).not.toBeNull()
+    expect(opacityTrack(out, 1, 0)).toBeUndefined()
+    expect(opacityTrack(out, 1, 1)).toBeUndefined()
+  })
+})

package/src/video/timeline/canvas/TimelineCanvas.tsx

@@ -36,13 +36,14 @@
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import type { GetFilmstripArgs, GetWaveformPeaksArgs, FilmstripIndex, PeaksData, PendingDrop, Project, FootageDropPayload, ResolveFilePath, TimelineDropPlacement } from '../../../types'
 import { FOOTAGE_DND_MIME } from '../../../types'
-import type { KeyframeProp } from '../../../schema'
+import type { KeyframeProp, Marker } from '../../../schema'
 import type { PlaybackClock } from '../../playback-clock'
 import { BASE_VISUAL_ROW_RENDER_HEIGHT_PX, ROW_GAP_PX, VISUAL_ROW_RENDER_HEIGHT_PX } from '../timeline-model'
 import { placeDroppedClip, resolveDropPoint } from '../placement'
-import { computeTimelineLayout, drawTimelineContent, drawTimelineOverlay, type PendingDropBand, type TimelineLayout, type TimelineMode, type VisualRowLayout } from './draw'
+import { computeTimelineLayout, drawTimelineContent, drawTimelineOverlay, MARKER_FLAG_WIDTH_PX, MARKER_LABEL_GAP_PX, type PendingDropBand, type TimelineLayout, type TimelineMode, type VisualRowLayout } from './draw'
 import { hitTest, isEdgeHit, type Point, type SurfaceRect } from './hit-test'
 import { keyframeUnionTimes } from './keyframe-strip'
+import { renameMarker } from '../markers'
 import {
   createPointerMachine,
   type KeyframeSelection,
@@ -67,6 +68,7 @@ import {
   reclampForDuration,
   scaleContextToDpr,
   syncCanvasBackingStore,
+  timeToX,
   useViewportValue,
   wheelIntent,
   withSurfaceWidth,
@@ -183,6 +185,53 @@ export interface TimelineCanvasProps {
   pendingDrops?: readonly PendingDrop[]
 }
 
+/**
+ * The marker rename box, isolated into its own component for the same reason
+ * `CanvasZoomBadge` (bottom of this file) is: it owns the viewport
+ * subscription itself, so a zoom or scroll while the box is open moves it
+ * without making `TimelineCanvas`'s own render body subscribe to the
+ * viewport — which would re-render the whole surface on every wheel-zoom
+ * tick and pan frame, the exact thing this file's header doc says never
+ * happens. The subscription only exists for as long as this component is
+ * mounted, i.e. only while a rename is actually open.
+ */
+function MarkerRenameBox({
+  marker,
+  store,
+  top,
+  onCommit,
+  onCancel,
+}: {
+  marker: Marker
+  store: ViewportStore
+  top: number
+  onCommit: (value: string) => void
+  onCancel: () => void
+}) {
+  const viewport = useViewportValue(store)
+  return (
+    <input
+      aria-label="Rename marker"
+      autoFocus
+      defaultValue={marker.label}
+      className="absolute z-10 h-4 rounded-sm border border-sky-400 bg-slate-900 px-1 text-[11px] text-slate-50 outline-none"
+      style={{
+        left: Math.round(timeToX(marker.t, viewport)) + MARKER_FLAG_WIDTH_PX + MARKER_LABEL_GAP_PX,
+        top,
+        width: 120,
+      }}
+      onKeyDown={e => {
+        // Stop Escape/Enter reaching the document keymap: this box owns
+        // them while it is open.
+        e.stopPropagation()
+        if (e.key === 'Enter') onCommit((e.target as HTMLInputElement).value)
+        if (e.key === 'Escape') onCancel()
+      }}
+      onBlur={e => onCommit(e.target.value)}
+    />
+  )
+}
+
 /**
  * Which video row a drop at surface-y `y` landed on, as an index into the
  * NORMALIZED track order `placeDroppedClip` measures in — or `-1` for "no
@@ -418,6 +467,13 @@ export default function TimelineCanvas({
   const [paneFill, setPaneFill] = useState(0)
   const surfaceHeight = Math.max(layout.height, VISUAL_ROW_RENDER_HEIGHT_PX, paneFill)
 
+  // Which marker's rename box is open, or null for none. The box itself is a
+  // real DOM `<input>` (rendered below, as a third child of the wrapper div)
+  // rather than a canvas-drawn fake — `editCaption` has no equivalent here
+  // because it routes to the transcript sidebar instead, so this is the one
+  // inline text editor this canvas hosts directly.
+  const [editingMarkerId, setEditingMarkerId] = useState<string | null>(null)
+
   // Latest draw inputs, readable from the imperative paint without making the
   // paint a dependency of every effect (the ref-to-latest pattern
   // `useTimelineZoom` uses for its wheel handler).
@@ -785,6 +841,7 @@ export default function TimelineCanvas({
         case 'commit':        p.onOverlayEdit?.(effect.project); break
         case 'inspect':       (effect.target === 'visual' ? p.onInspectClip : p.onInspectAudio)?.(effect.id); break
         case 'editCaption':   p.onEditCaption?.(effect.id); break
+        case 'editMarker':    setEditingMarkerId(effect.id); break
         // Cursor is written straight to the node: an affordance that changes on
         // every hover must not cost a React render.
         case 'cursor':        if (containerRef.current) containerRef.current.style.cursor = effect.cursor; break
@@ -888,7 +945,7 @@ export default function TimelineCanvas({
     // precedence here, same as it does in the machine's own hit-test — a
     // trim handle must not light up underneath a diamond that would win the
     // actual press.
-    const hit = hitTest(point, p.layout, store.get(), { selectedIds: p.selectedIds })
+    const hit = hitTest(point, p.layout, store.get(), { selectedIds: p.selectedIds, markers: p.project.markers })
     if (!isEdgeHit(hit) || hit.itemId === undefined || hit.edge === undefined) return null
     return p.selectedIds.includes(hit.itemId) ? { itemId: hit.itemId, edge: hit.edge } : null
   }
@@ -1137,7 +1194,7 @@ export default function TimelineCanvas({
       if (!p.onFadeCurveMenu && !p.onKeyframeMenu) return
       const point = surfacePoint(e)
       if (!point) return
-      const hit = hitTest(point, p.layout, store.get(), { selectedIds: p.selectedIds })
+      const hit = hitTest(point, p.layout, store.get(), { selectedIds: p.selectedIds, markers: p.project.markers })
       if (p.onFadeCurveMenu && hit.kind === 'audio-fade' && hit.itemId !== undefined && hit.side) {
         e.preventDefault()
         p.onFadeCurveMenu({ trackId: hit.itemId, side: hit.side, x: e.clientX, y: e.clientY })
@@ -1368,6 +1425,36 @@ export default function TimelineCanvas({
     }
   }, [])
 
+  // ── Marker rename box ──
+  //
+  // Unlike the imperative paint (which reads `store.get()` fresh per frame),
+  // the box's `left` is a React-owned DOM style, so it needs a subscription to
+  // follow a zoom or scroll that happens while it's open. That subscription
+  // lives on `MarkerRenameBox` itself, below, rather than here — the same
+  // reason `CanvasZoomBadge` is its own component: TimelineCanvas must not
+  // subscribe to the viewport in its own render body, or every wheel-zoom
+  // tick and pan frame re-renders this whole surface, which is exactly what
+  // this file's header doc promises never happens.
+  const editingMarker = editingMarkerId
+    ? (project.markers ?? []).find(m => m.id === editingMarkerId) ?? null
+    : null
+
+  const commitRename = (value: string) => {
+    // The id is captured and null-checked here because this same function is
+    // also the input's blur handler, and it must be safe to call when there
+    // is nothing being edited. Escape does not route through here at all —
+    // its handler clears `editingMarkerId` directly (see `MarkerRenameBox`
+    // below) — so the null check is for blur-with-nothing-open, not for
+    // "Escape already cleared it before blur could commit."
+    const id = editingMarkerId
+    setEditingMarkerId(null)
+    if (!id) return
+    const next = renameMarker(project, id, value)
+    if (next === project) return          // blank or unchanged — no undo entry
+    onProjectChange?.(next)
+    onOverlayEdit?.(next)                  // one commit, one undo step
+  }
+
   return (
     <div
       ref={containerRef}
@@ -1399,6 +1486,15 @@ export default function TimelineCanvas({
     >
       <canvas ref={contentCanvasRef} className="absolute inset-0 w-full h-full" />
       <canvas ref={overlayCanvasRef} className="absolute inset-0 w-full h-full pointer-events-none" />
+      {editingMarker && (
+        <MarkerRenameBox
+          marker={editingMarker}
+          store={store}
+          top={layout.markers?.y ?? 0}
+          onCommit={commitRename}
+          onCancel={() => setEditingMarkerId(null)}
+        />
+      )}
     </div>
   )
 }