@bycrux/editor 1.1.0 → 1.2.0

package/src/video/timeline/canvas/__tests__/draw.test.ts

@@ -26,8 +26,10 @@ import {
   LIGHT_TRACK_PALETTE,
   timelinePalette,
   drawCursorLine,
+  drawMarkers,
   drawMarquee,
   drawRuler,
+  MARKER_STRIP_HEIGHT_PX,
   type TimelinePalette,
   CLIP_HANDLE_WIDTH_PX,
   FADE_GRIP_SIZE_PX,
@@ -2196,3 +2198,74 @@ describe('drawTimelineContent / drawTimelineOverlay — mode', () => {
     expect(styles).not.toContain(LIGHT_TIMELINE_COLORS.marqueeFill)
   })
 })
+
+describe('marker strip layout', () => {
+  it('is absent, and the ruler still starts at 0, when the project has no markers', () => {
+    // A marker-less project must lay out byte-identically to before the feature.
+    const layout = computeTimelineLayout(project({ tracks: [{ id: 'trk-0', items: [] }] }))
+    expect(layout.markers).toBeUndefined()
+    expect(layout.ruler).toEqual({ y: 0, height: RULER_HEIGHT_PX })
+  })
+
+  it('claims the top strip and pushes the ruler down once markers exist', () => {
+    const layout = computeTimelineLayout(project({
+      tracks: [{ id: 'trk-0', items: [] }],
+      markers: [{ id: 'a', t: 1, label: '1' }],
+    }))
+    expect(layout.markers).toEqual({ y: 0, height: MARKER_STRIP_HEIGHT_PX })
+    expect(layout.ruler).toEqual({ y: MARKER_STRIP_HEIGHT_PX, height: RULER_HEIGHT_PX })
+  })
+
+  it('pushes every row down by exactly the strip height', () => {
+    const withOut = computeTimelineLayout(project({ tracks: [{ id: 'trk-0', items: [clip()] }] }))
+    const withIn = computeTimelineLayout(project({
+      tracks: [{ id: 'trk-0', items: [clip()] }],
+      markers: [{ id: 'a', t: 1, label: '1' }],
+    }))
+    expect(withIn.rows[0].y - withOut.rows[0].y).toBe(MARKER_STRIP_HEIGHT_PX)
+    expect(withIn.height - withOut.height).toBe(MARKER_STRIP_HEIGHT_PX)
+  })
+})
+
+describe('drawMarkers', () => {
+  const strip = { y: 0, height: MARKER_STRIP_HEIGHT_PX }
+
+  it('draws nothing at all for an empty list', () => {
+    const r = recordingContext()
+    drawMarkers(r.ctx, [], viewport(), strip, 800, [])
+    expect(r.calls).toHaveLength(0)   // not even a background fill
+  })
+
+  it('draws a flag and its label at the marker time', () => {
+    const r = recordingContext()
+    const vp = viewport({ pxPerSecond: 10, scrollSeconds: 0 })
+    drawMarkers(r.ctx, [{ id: 'a', t: 5, label: 'intro' }], vp, strip, 800, [])
+    const text = r.of('fillText')
+    expect(text).toHaveLength(1)
+    expect(text[0].args[0]).toBe('intro')
+    // Label sits just right of the flag, which stands at timeToX(5) = 50.
+    expect(text[0].args[1]).toBeGreaterThanOrEqual(50)
+    expect(r.of('fillRect').length).toBeGreaterThan(0)
+  })
+
+  it('skips a marker scrolled out of view', () => {
+    const r = recordingContext()
+    drawMarkers(r.ctx, [{ id: 'a', t: 500, label: '1' }], viewport({ pxPerSecond: 10, scrollSeconds: 0 }), strip, 800, [])
+    expect(r.of('fillText')).toHaveLength(0)
+  })
+
+  it('paints a selected marker in the selected colour', () => {
+    const base = recordingContext()
+    drawMarkers(base.ctx, [{ id: 'a', t: 5, label: '1' }], viewport({ pxPerSecond: 10 }), strip, 800, [])
+    const sel = recordingContext()
+    drawMarkers(sel.ctx, [{ id: 'a', t: 5, label: '1' }], viewport({ pxPerSecond: 10 }), strip, 800, ['a'])
+    const fills = (r: typeof base) => r.calls.filter(c => c.method === 'set:fillStyle').map(c => c.args[0])
+    expect(fills(sel)).not.toEqual(fills(base))
+  })
+
+  it('truncates a long label instead of letting it run across the strip', () => {
+    const r = recordingContext()
+    drawMarkers(r.ctx, [{ id: 'a', t: 0, label: 'a'.repeat(400) }], viewport({ pxPerSecond: 10 }), strip, 800, [])
+    expect((r.of('fillText')[0].args[0] as string).length).toBeLessThan(400)
+  })
+})

package/src/video/timeline/canvas/__tests__/hit-test.test.ts

@@ -18,6 +18,7 @@ import { AUDIO_ITEM_INSET_PX, RULER_HEIGHT_PX, computeTimelineLayout } from '../
 import {
   AUDIO_EDGE_TOLERANCE_PX,
   FADE_GRIP_ZONE_HEIGHT_PX,
+  MARKER_HIT_WIDTH_PX,
   VISUAL_EDGE_TOLERANCE_PX,
   hitTest,
   isCaptionHit,
@@ -474,6 +475,81 @@ describe('hitTest — outside the rows', () => {
   })
 })
 
+describe('marker hit region', () => {
+  // A marker-bearing twin of the module fixture. Local, because adding markers
+  // to the shared `project` would shift every other probe's Y by the strip
+  // height and rewrite this whole file's expectations.
+  const markers = [{ id: 'm1', t: 5, label: 'intro' }]
+  const markerProject = { ...project, markers } as unknown as Project
+  const markerLayout = () => computeTimelineLayout(markerProject)
+  // x === t * 100 at this viewport, so the flag stands at 500.
+  const FLAG_X = 500
+
+  it('hits the marker when the pointer is on its flag in the strip', () => {
+    const hit = hitTest({ x: FLAG_X, y: 8 }, markerLayout(), VIEWPORT, { markers })
+    expect(hit.kind).toBe('marker')
+    expect(hit.markerId).toBe('m1')
+  })
+
+  it('claims the whole label box, not just the flag stem', () => {
+    // The label is what the operator aims at — a 2px stem is not a target.
+    const hit = hitTest({ x: FLAG_X + 40, y: 8 }, markerLayout(), VIEWPORT, { markers })
+    expect(hit.kind).toBe('marker')
+  })
+
+  it('does not claim strip for a marker scrolled off the LEFT edge', () => {
+    // `drawMarkers` culls a marker whose flag has scrolled left of x=0 — the
+    // whole marker, label included. Without the same cull here, the hit region
+    // outlives the picture: the marker is invisible but its 72px claim still
+    // covers the left of the strip, so a click on apparently-empty strip
+    // selects (and can then DRAG) a marker nobody can see. Painting and hitting
+    // have to cull on the same rule or one of them is lying.
+    const scrolled = { ...VIEWPORT, scrollSeconds: 5.05 }   // marker t=5 → x = -5
+    const hit = hitTest({ x: 10, y: 8 }, markerLayout(), scrolled, { markers })
+    expect(hit.kind).toBe('background')
+  })
+
+  it('still claims a marker whose flag is just INSIDE the left edge', () => {
+    // The boundary the cull sits on, from the visible side — proves the fix
+    // culls off-screen markers rather than simply narrowing the hit region.
+    const scrolled = { ...VIEWPORT, scrollSeconds: 4.99 }   // marker t=5 → x = +1
+    const hit = hitTest({ x: 10, y: 8 }, markerLayout(), scrolled, { markers })
+    expect(hit.kind).toBe('marker')
+    expect(hit.markerId).toBe('m1')
+  })
+
+  it('stops claiming past the label box', () => {
+    const hit = hitTest({ x: FLAG_X + MARKER_HIT_WIDTH_PX + 10, y: 8 }, markerLayout(), VIEWPORT, { markers })
+    expect(hit.kind).not.toBe('marker')
+  })
+
+  it('is background, NOT ruler, on empty strip — a click there must not seek', () => {
+    const hit = hitTest({ x: 20, y: 8 }, markerLayout(), VIEWPORT, { markers })
+    expect(hit.kind).toBe('background')
+  })
+
+  it('never returns a marker for a point in the RULER band', () => {
+    // The ruler keeps its band and its scrub behaviour, untouched.
+    const layout = markerLayout()
+    const hit = hitTest({ x: FLAG_X, y: layout.ruler.y + 4 }, layout, VIEWPORT, { markers })
+    expect(hit.kind).toBe('ruler')
+  })
+
+  it('catches a pointer that has run off the TOP of the surface', () => {
+    // The ruler's own early return used to be what caught this; the strip now
+    // sits above it and must inherit the same duty.
+    const hit = hitTest({ x: FLAG_X, y: -20 }, markerLayout(), VIEWPORT, { markers })
+    expect(hit.kind).toBe('marker')
+  })
+
+  it('returns ruler in the top band when the project has no markers', () => {
+    // No strip exists, so y=8 is inside the ruler exactly as it was before —
+    // this is the guard that every existing probe in this file still holds.
+    const layout = computeTimelineLayout(project as unknown as Project)
+    expect(hitTest({ x: 50, y: 8 }, layout, VIEWPORT).kind).toBe('ruler')
+  })
+})
+
 describe('hitTest — time', () => {
   it('always reports the time under x, whatever was hit', () => {
     expect(at(250, BASE_Y).t).toBeCloseTo(2.5)

package/src/video/timeline/canvas/__tests__/pointer-machine.test.ts

@@ -38,7 +38,7 @@ import {
 } from '../pointer-machine'
 import { FADE_GRIP_ZONE_HEIGHT_PX, hitTest } from '../hit-test'
 import type { SnapConfig } from '../snap'
-import { xToTime, type Viewport } from '../viewport'
+import { timeToX, xToTime, type Viewport } from '../viewport'
 
 const VIEWPORT: Viewport = { pxPerSecond: 100, scrollSeconds: 0, widthPx: 1000 }
 
@@ -3472,3 +3472,102 @@ describe('caption lanes — hole collapse at commit', () => {
     expect(lanes(committed[0].project)).toEqual({ low: 0, mid: 1, top: 2 })
   })
 })
+
+describe('marker drag', () => {
+  const MARKERS = [{ id: 'm1', t: 5, label: '1' }]
+  /** The module fixture plus markers, so the strip exists in the layout. */
+  function markerCtx(over: Partial<PointerContext> = {}): PointerContext {
+    return makeContext({ project: { ...baseProject(), markers: MARKERS }, ...over })
+  }
+  /** x of the flag, and a y inside the strip. */
+  const flagX = (ctx: PointerContext) => timeToX(5, ctx.viewport)
+  const STRIP_Y = 8
+
+  it('pressing a marker does NOT scrub — the ruler branch must not claim it', () => {
+    // The whole risk of this feature: pointerDown scrubs on sight for the ruler
+    // and for the playhead grab band, with no drag threshold.
+    const ctx = markerCtx()
+    const m = createPointerMachine()
+    const effects = m.dispatch({ type: 'pointerDown', point: { x: flagX(ctx), y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    expect(effects.some(e => e.type === 'seek')).toBe(false)
+    expect(m.state.kind).toBe('pressed')
+  })
+
+  it('still scrubs on the ruler band itself', () => {
+    const ctx = markerCtx()
+    const m = createPointerMachine()
+    const y = ctx.layout.ruler.y + 4
+    const effects = m.dispatch({ type: 'pointerDown', point: { x: 200, y }, modifiers: NO_MODIFIERS, ctx })
+    expect(effects.some(e => e.type === 'seek')).toBe(true)
+  })
+
+  it('a marker sitting under the playhead is still grabbable', () => {
+    // grabsPlayhead is not y-gated, so without an explicit exclusion the
+    // playhead swallows any marker that happens to line up with it — and a
+    // marker dropped with M lands exactly on the playhead, so that is the
+    // COMMONEST marker, not an edge case.
+    const ctx = markerCtx({ playheadTime: 5 })
+    const m = createPointerMachine()
+    const effects = m.dispatch({ type: 'pointerDown', point: { x: flagX(ctx), y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    expect(effects.some(e => e.type === 'seek')).toBe(false)
+  })
+
+  it('dragging past the threshold retimes the marker', () => {
+    const ctx = markerCtx()
+    const m = createPointerMachine()
+    const x0 = flagX(ctx)
+    m.dispatch({ type: 'pointerDown', point: { x: x0, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    const effects = m.dispatch({ type: 'pointerMove', point: { x: x0 + 100, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    const changes = of(effects, 'projectChange')
+    expect(changes).toHaveLength(1)
+    const moved = changes[0].project.markers![0]
+    expect(moved.t).toBeGreaterThan(5)
+    expect(moved.id).toBe('m1')
+  })
+
+  it('drags grab-relative — pressing the label does not teleport the marker to the cursor', () => {
+    // The 40px press offset is the entire point of this test. The hit region is
+    // a flat MARKER_HIT_WIDTH_PX (72) wide, so a press 40px right of the flag
+    // lands on the LABEL — the common case, not a contrived one — and the two
+    // candidate behaviours diverge there by exactly that offset. At 100px/s a
+    // 100px drag is 1s: grab-relative lands the marker at 6, absolute lands it
+    // at 6.4, the cursor's own time. Only one of those can pass, which is what
+    // the `> 5` assertion in the test above cannot distinguish.
+    const ctx = markerCtx()
+    const m = createPointerMachine()
+    const x0 = flagX(ctx) + 40
+    m.dispatch({ type: 'pointerDown', point: { x: x0, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    const effects = m.dispatch({ type: 'pointerMove', point: { x: x0 + 100, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    const changes = of(effects, 'projectChange')
+    expect(changes).toHaveLength(1)
+    const moved = changes[0].project.markers![0]
+    expect(moved.t).toBeCloseTo(6, 6)
+    expect(moved.t).not.toBeCloseTo(xToTime(x0 + 100, ctx.viewport), 6)
+  })
+
+  it('commits once on release', () => {
+    const ctx = markerCtx()
+    const m = createPointerMachine()
+    const x0 = flagX(ctx)
+    m.dispatch({ type: 'pointerDown', point: { x: x0, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    m.dispatch({ type: 'pointerMove', point: { x: x0 + 100, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    const up = m.dispatch({ type: 'pointerUp', point: { x: x0 + 100, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    expect(up.filter(e => e.type === 'commit')).toHaveLength(1)
+  })
+
+  it('a press with no drag selects the marker instead of moving it', () => {
+    const ctx = markerCtx()
+    const m = createPointerMachine()
+    const x0 = flagX(ctx)
+    m.dispatch({ type: 'pointerDown', point: { x: x0, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    const up = m.dispatch({ type: 'pointerUp', point: { x: x0, y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    expect(up).toContainEqual(expect.objectContaining({ type: 'select', id: 'm1' }))
+  })
+
+  it('double-clicking a marker asks the host to edit it', () => {
+    const ctx = markerCtx()
+    const m = createPointerMachine()
+    const effects = m.dispatch({ type: 'doubleClick', point: { x: flagX(ctx), y: STRIP_Y }, modifiers: NO_MODIFIERS, ctx })
+    expect(effects).toContainEqual({ type: 'editMarker', id: 'm1' })
+  })
+})

package/src/video/timeline/canvas/draw.ts

@@ -15,7 +15,7 @@
  * design.
  */
 
-import type { AudioTrack, CaptionSegment, VisualItem } from '../../../schema'
+import type { AudioTrack, CaptionSegment, Marker, VisualItem } from '../../../schema'
 import type { Project } from '../../../types'
 import { groupCaptionLanes } from '../../captionLanes'
 import {
@@ -305,6 +305,14 @@ export const TIMELINE_COLORS = {
   rulerTick: 'rgba(148,163,184,0.55)',
   rulerTickMinor: 'rgba(148,163,184,0.25)',
   rulerText: 'rgba(148,163,184,0.9)',
+  /** A marker's flag stem, in the strip above the ruler. Sky-400 — every
+   *  saturated hue below it is spoken for (red is playback, yellow the
+   *  preview axis, cyan the snap guide, amber a keyframe, emerald audio), and
+   *  a marker is none of those: it is a bookmark, not a state of the edit. */
+  markerFlag: '#38bdf8',
+  /** The one marker in the current selection. White, the same selection
+   *  vocabulary `clipSelectedOutline`/`handleFill` already use. */
+  markerFlagSelected: '#f8fafc',
   /** The marquee (rubber-band) selection box. Same white as the selection
    *  vocabulary, since what it is doing IS selecting. */
   marqueeFill: 'rgba(255,255,255,0.08)',
@@ -462,6 +470,13 @@ export const LIGHT_TIMELINE_COLORS: TimelineColors = {
   rulerTick: 'rgba(71,85,105,0.55)',
   rulerTickMinor: 'rgba(71,85,105,0.3)',
   rulerText: 'rgba(51,65,85,0.85)',
+  /** Still sky, stepped from sky-400 to sky-600 for the same reason
+   *  `snapGuide` steps cyan-400 to cyan-600: the lighter tone doesn't clear a
+   *  light row. */
+  markerFlag: '#0284c7',
+  /** The selected marker. Near-black, following `clipSelectedOutline` into
+   *  the same "white becomes near-black here" rule. */
+  markerFlagSelected: '#0f172a',
   /** The marquee. Selection vocabulary again, so it follows the outline and
    *  the handles into near-black — at the dark set's own alphas, which were
    *  already tuned to "a wash you can see through and a border you can't miss". */
@@ -503,6 +518,35 @@ export const RULER_STEPS_SECONDS = [
   60, 120, 300, 600, 900, 1800, 3600,
 ] as const
 
+/**
+ * The marker strip: a thin band ABOVE the ruler.
+ *
+ * Markers do NOT share the ruler's 18px. Two reasons, and the second is the
+ * load-bearing one:
+ *
+ *   1. The ruler already spends that band on tick labels. A marker name would
+ *      overprint them at any useful zoom.
+ *   2. `hitTest` returns `'ruler'` for the WHOLE ruler band before it tests
+ *      anything else, and the pointer machine scrubs on pointerDown the instant
+ *      it sees that — no drag threshold, no deferral. A marker sharing the band
+ *      would have to fight that branch for precedence. Its own band means the
+ *      ruler's behaviour is untouched and a marker hit is simply a different
+ *      rectangle.
+ *
+ * Present ONLY when the project has markers, the same discipline
+ * `TimelineLayout.captions` follows: a marker-less project lays out exactly as
+ * it did before this existed, so no existing layout expectation moves.
+ */
+export const MARKER_STRIP_HEIGHT_PX = 16
+/** Width of a marker's flag stem, and the gap before its label. */
+export const MARKER_FLAG_WIDTH_PX = 2
+export const MARKER_LABEL_GAP_PX = 4
+/** Baseline for a marker label, measured from the top of the strip. */
+export const MARKER_LABEL_BASELINE_PX = 11
+/** Longest label drawn, in characters. Past this the name is clipped with an
+ *  ellipsis — a marker is a flag, not a notes field. */
+export const MARKER_LABEL_MAX_CHARS = 24
+
 export const ROW_RADIUS_PX = 4           // Tailwind `rounded`
 /** Horizontal inset per side between a clip's time span and its drawn body —
  *  two touching clips therefore show twice this as a dark gutter. */
@@ -673,10 +717,14 @@ export interface CaptionRowLayout {
 }
 
 export interface TimelineLayout {
-  /** The time ruler strip across the top. Always present and always at y=0;
-   *  carried in the layout rather than assumed so hit-testing and painting
-   *  read the same rectangle, the same contract the rows have. */
+  /** The time ruler strip. Always present; carried in the layout rather than
+   *  assumed so hit-testing and painting read the same rectangle, the same
+   *  contract the rows have. Sits at y=0 when the project has no markers, and
+   *  below the marker strip (see `MARKER_STRIP_HEIGHT_PX`) when it does. */
   ruler: { y: number; height: number }
+  /** The marker strip above the ruler. Absent — not a zero-height rect — when
+   *  the project has no markers; see `MARKER_STRIP_HEIGHT_PX`. */
+  markers?: { y: number; height: number }
   /** Visual rows in DRAW order (top of the surface first). */
   rows: VisualRowLayout[]
   lanes: AudioLaneLayout[]
@@ -717,9 +765,13 @@ export function computeTimelineLayout(project: Project): TimelineLayout {
   // legacy-shaped project has no settings, so every row is enabled.
   const trackSettings = normalizeTracks(project).tracks ?? []
   const rows: VisualRowLayout[] = []
-  // The ruler owns the top strip; everything else starts below it.
-  const ruler = { y: 0, height: RULER_HEIGHT_PX }
-  let y = RULER_HEIGHT_PX + ROW_GAP_PX
+  // The marker strip owns the very top when there is anything to put in it;
+  // the ruler starts below it, and every row below that.
+  const hasMarkers = (project.markers?.length ?? 0) > 0
+  const markers = hasMarkers ? { y: 0, height: MARKER_STRIP_HEIGHT_PX } : undefined
+  const stripHeight = hasMarkers ? MARKER_STRIP_HEIGHT_PX : 0
+  const ruler = { y: stripHeight, height: RULER_HEIGHT_PX }
+  let y = stripHeight + RULER_HEIGHT_PX + ROW_GAP_PX
 
   // Only stored when there is something to show — an empty `segments` (or no
   // `project.captions` at all) means no bands at all, not an empty array, so a
@@ -811,6 +863,7 @@ export function computeTimelineLayout(project: Project): TimelineLayout {
   })
 
   const layout: TimelineLayout = { ruler, rows, lanes, height: Math.max(0, y - ROW_GAP_PX) }
+  if (markers) layout.markers = markers
   if (captions.length > 0) layout.captions = captions
   return layout
 }
@@ -1752,6 +1805,47 @@ export function drawRuler(
   ctx.restore()
 }
 
+/**
+ * The operator's markers, as small flags along the top strip.
+ *
+ * Content-layer, not overlay: markers are project data that changes on an edit,
+ * not per frame. A drag repaints the content layer per move exactly the way a
+ * clip drag already does (`applyMove` emits `projectChange`, the host redraws
+ * content) — there is no ghost, because there is no ghost for clips either.
+ *
+ * `markers` is expected sorted by `t` (the model guarantees it), so this walks
+ * in draw order and a later marker's label overprints an earlier one's when
+ * they crowd. That is the correct z-order: the one further right is the one
+ * whose flag you can still see.
+ */
+export function drawMarkers(
+  ctx: DrawContext,
+  markers: readonly Marker[],
+  viewport: Viewport,
+  rect: { y: number; height: number },
+  surfaceWidth: number,
+  selectedIds: readonly string[],
+  palette: TimelinePalette = DARK_TIMELINE_PALETTE,
+): void {
+  if (markers.length === 0) return
+  ctx.save()
+  ctx.font = LABEL_FONT
+  ctx.textBaseline = 'alphabetic'
+  for (const m of markers) {
+    const x = Math.round(timeToX(m.t, viewport)) + 0.5
+    if (x < 0 || x > surfaceWidth) continue
+    const selected = selectedIds.includes(m.id)
+    ctx.fillStyle = selected ? palette.colors.markerFlagSelected : palette.colors.markerFlag
+    ctx.fillRect(x, rect.y + 2, MARKER_FLAG_WIDTH_PX, rect.height - 4)
+    ctx.fillStyle = selected ? palette.colors.markerFlagSelected : palette.colors.rulerText
+    const label = m.label.length > MARKER_LABEL_MAX_CHARS
+      ? `${m.label.slice(0, MARKER_LABEL_MAX_CHARS - 1)}…`
+      : m.label
+    ctx.fillText(label, x + MARKER_FLAG_WIDTH_PX + MARKER_LABEL_GAP_PX, rect.y + MARKER_LABEL_BASELINE_PX)
+  }
+  ctx.restore()
+}
+
 // ── Pending-drop ghost ───────────────────────────────────────────────────
 
 /** Corner radius of a ghost band. The same 4px a clip uses — the band stands
@@ -1886,6 +1980,9 @@ export function drawTimelineContent(ctx: DrawContext, scene: TimelineScene): Dra
 
   ctx.clearRect(0, 0, surfaceWidth, surfaceHeight)
 
+  if (layout.markers) {
+    drawMarkers(ctx, scene.project.markers ?? [], viewport, layout.markers, surfaceWidth, selectedIds, themePalette)
+  }
   drawRuler(ctx, viewport, layout.ruler, surfaceWidth, themePalette)
 
 

package/src/video/timeline/canvas/hit-test.ts

@@ -22,7 +22,7 @@
  * which is why captions hit-test at the audio tolerance.
  */
 
-import type { AudioTrack, CaptionSegment, VisualItem } from '../../../schema'
+import type { AudioTrack, CaptionSegment, Marker, VisualItem } from '../../../schema'
 import { canKeyframe, isKeyframed } from '../../keyframeOps'
 import { AUDIO_ITEM_INSET_PX, type TimelineLayout } from './draw'
 import { KEYFRAME_HIT_HALF_WIDTH_PX, KEYFRAME_STRIP_ZONE_HEIGHT_PX, keyframeDiamondX, keyframeUnionTimes } from './keyframe-strip'
@@ -58,6 +58,10 @@ export const FADE_GRIP_HALF_WIDTH_PX = 5
  *  this. */
 export const FADE_GRIP_ZONE_HEIGHT_PX = 10
 
+/** How far right of a marker's flag the label claims as a target. Wide enough
+ *  that the LABEL is clickable, not just the 2px stem. */
+export const MARKER_HIT_WIDTH_PX = 72
+
 export interface HitTestOptions {
   visualEdgeTolerancePx?: number
   audioEdgeTolerancePx?: number
@@ -68,9 +72,18 @@ export interface HitTestOptions {
    *  is also what every caller that predates T3.3 gets — this option is
    *  purely additive. */
   selectedIds?: readonly string[]
+  /** The project's markers, threaded the same way `selectedIds` is: the layout
+   *  carries the strip's RECTANGLE but not what sits in it, so the flags have
+   *  to arrive here to be hit-testable. Absent means no marker hits are
+   *  possible, which is what every caller that predates this gets. */
+  markers?: readonly Marker[]
 }
 
 export type HitKind =
+  /** On a marker's flag or its label, in the strip ABOVE the ruler. Only ever
+   *  produced when the project HAS markers (the strip is absent otherwise) and
+   *  the caller passed them through `HitTestOptions.markers`. */
+  | 'marker'
   /** The time ruler strip along the top. Scrubbing lives here, and only here:
    *  the track area's empty space belongs to the marquee now. */
   | 'ruler'
@@ -111,6 +124,10 @@ export interface HitResult {
    *  point outside the rows is still a point in time. */
   t: number
   itemId?: string
+  /** The hit marker's id, on a `'marker'` hit. A field of its own rather than a
+   *  reuse of `itemId`: a marker is not an item, and every caller that reads
+   *  `itemId` means "a thing on a track" by it. */
+  markerId?: string
   /** Which trim handle, on the two `*-edge` kinds. `in` is the left/start
    *  handle, `out` the right/end one — the vocabulary `cuts.ts` uses for source
    *  windows, rather than the DOM hook's `start`/`end`. */
@@ -144,6 +161,10 @@ export interface HitResult {
    *  press time by the pointer machine and used as the gesture's origin. */
   item?: VisualItem
   track?: AudioTrack
+  /** The hit marker itself, for the same reason `item`/`track` are here: the
+   *  pointer machine captures it at press time and reads its `t` for the whole
+   *  gesture rather than re-scanning `project.markers` per move. */
+  marker?: Marker
   /** The hit caption segment, for the same reason `item`/`track` are here: the
    *  pointer machine captures it at press time and reads its `start`/`end` for
    *  the whole gesture, rather than re-scanning `project.captions` per move. */
@@ -307,6 +328,51 @@ export function hitTest(
   const visualTolerance = opts.visualEdgeTolerancePx ?? VISUAL_EDGE_TOLERANCE_PX
   const audioTolerance = opts.audioEdgeTolerancePx ?? AUDIO_EDGE_TOLERANCE_PX
 
+  // The marker strip sits ABOVE the ruler and is tested first, because the
+  // ruler's own check below claims its whole band unconditionally. Ordering is
+  // the entire mechanism here: reverse these two and every marker click scrubs.
+  //
+  // NO LOWER BOUND on the band, deliberately. The ruler's check below is
+  // written the same way, and its comment says why: a pointer that has run off
+  // the TOP of the surface is still aiming at the topmost strip. With a marker
+  // strip present that strip is the topmost one, so it inherits that duty —
+  // adding a `point.y >= strip.y` guard would drop those points through to the
+  // ruler and scrub instead.
+  const strip = layout.markers
+  if (strip && point.y < strip.y + strip.height) {
+    const markers = opts.markers ?? []
+    // Right-to-left, matching draw order: a later marker paints OVER an earlier
+    // one, so it must also win the click.
+    for (let i = markers.length - 1; i >= 0; i--) {
+      const m = markers[i]
+      const x = timeToX(m.t, viewport)
+      // Cull exactly where `drawMarkers` culls, so the hit region cannot
+      // outlive the picture. A marker scrolled off the LEFT is not drawn at
+      // all — label included — but its claim reaches MARKER_HIT_WIDTH_PX to
+      // the RIGHT of the flag, so without this a click on apparently-empty
+      // strip near the left edge grabs a marker nobody can see, and can then
+      // drag it.
+      //
+      // The predicate is copied from the painter (`Math.round(x) + 0.5 < 0`)
+      // but the hit region is measured from the TRUE `x`. That asymmetry is
+      // deliberate: the painter's `+ 0.5` is a half-pixel crispness offset for
+      // drawing a sharp 1px stem, not a position. Folding it into the hit
+      // region shifts every marker's target half a pixel right of its own
+      // flag, so a click landing exactly on the flag misses.
+      //
+      // `drawMarkers` also culls `x > surfaceWidth`; that needs no counterpart
+      // here, since a hit requires `point.x >= x` and `point.x` never exceeds
+      // the surface.
+      if (Math.round(x) + 0.5 < 0) continue
+      if (point.x >= x && point.x <= x + MARKER_HIT_WIDTH_PX) {
+        return { kind: 'marker', t, markerId: m.id, marker: m }
+      }
+    }
+    // Bare strip: not a marker, and deliberately NOT the ruler either — a click
+    // on empty strip should do nothing, not seek.
+    return { kind: 'background', t }
+  }
+
   // Before the rows, and including everything above the strip: a pointer that
   // has run off the top of the surface is still aiming at the ruler, and
   // clamping it there keeps a scrub alive when the hand drifts upward
@@ -490,6 +556,11 @@ export function isItemHit(hit: HitResult): boolean {
     || hit.kind === 'audio-body' || hit.kind === 'audio-edge'
 }
 
+/** Is this a hit on a marker's flag or label in the strip? */
+export function isMarkerHit(hit: HitResult): boolean {
+  return hit.kind === 'marker'
+}
+
 /** Is this a hit on a caption block (either body or edge)? */
 export function isCaptionHit(hit: HitResult): boolean {
   return hit.kind === 'caption-body' || hit.kind === 'caption-edge'