@bycrux/editor 1.1.0 → 1.2.1

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. */
@@ -559,6 +603,17 @@ export const LABEL_FONT = '10px ui-sans-serif, system-ui, sans-serif'
 export const LABEL_PAD_PX = 6
 /** Below this width a label is more smear than information, so it is skipped. */
 export const MIN_LABEL_WIDTH_PX = 28
+/** Muted-speaker glyph drawn at the head of a muted audio bar. Mute used to be
+ *  carried by fill alone (`audioMutedFill` plus a dropped border), which reads
+ *  as "a slightly different colour" rather than "this is off" — operators asked
+ *  why a lane was silent while looking straight at the thing telling them. */
+export const MUTED_ICON_SIZE_PX = 9
+/** Gap between the glyph and the label that follows it. */
+export const MUTED_ICON_GAP_PX = 4
+/** Below this bar width even the glyph is dropped. Lower than
+ *  `MIN_LABEL_WIDTH_PX` on purpose: on a bar too narrow to name, "is it muted"
+ *  is the more valuable of the two answers, so the glyph outlives the label. */
+export const MIN_MUTED_ICON_WIDTH_PX = 14
 /** Middle-baseline offset from a clip's top edge — half the font's 10px plus a
  *  4px margin, so the label rides just inside the clip's top border. */
 export const LABEL_TOP_OFFSET_PX = 9
@@ -673,10 +728,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 +776,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 +874,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
 }
@@ -1322,6 +1386,57 @@ export interface AudioItemDrawArgs {
   hoveredFadeSide?: 'in' | 'out' | null
 }
 
+/**
+ * A speaker with a cross beside it, drawn in a `size`×`size` box anchored at
+ * (x, y). Filled for the speaker body and stroked for the cross, so it holds
+ * up both against the washed-out muted fill and over whatever waveform the
+ * content layer painted underneath.
+ *
+ * Deliberately geometry rather than a font glyph or an inline SVG: this runs
+ * inside the timeline's canvas painter, where the only other text is drawn with
+ * `LABEL_FONT`, and a missing icon font would fail as a blank box with no
+ * fallback path to notice it.
+ */
+function drawMutedGlyph(
+  ctx: DrawContext,
+  x: number,
+  y: number,
+  size: number,
+  color: string,
+): void {
+  const s = size
+  ctx.save()
+  ctx.strokeStyle = color
+  ctx.fillStyle = color
+  // `DrawContext` is the painter's narrowed surface and carries no
+  // `lineJoin`/`lineCap`; at 9px neither is visible anyway.
+  ctx.lineWidth = 1
+
+  // Speaker: a small back plate, then the cone flaring out of it.
+  const bodyW = s * 0.26
+  const bodyH = s * 0.34
+  const bodyX = x + s * 0.04
+  const bodyY = y + (s - bodyH) / 2
+  ctx.beginPath()
+  ctx.moveTo(bodyX, bodyY)
+  ctx.lineTo(bodyX + bodyW, bodyY)
+  ctx.lineTo(x + s * 0.48, y + s * 0.14)
+  ctx.lineTo(x + s * 0.48, y + s * 0.86)
+  ctx.lineTo(bodyX + bodyW, bodyY + bodyH)
+  ctx.lineTo(bodyX, bodyY + bodyH)
+  ctx.closePath()
+  ctx.fill()
+
+  // The cross — what actually says "off" at a glance.
+  ctx.beginPath()
+  ctx.moveTo(x + s * 0.62, y + s * 0.3)
+  ctx.lineTo(x + s * 0.96, y + s * 0.7)
+  ctx.moveTo(x + s * 0.96, y + s * 0.3)
+  ctx.lineTo(x + s * 0.62, y + s * 0.7)
+  ctx.stroke()
+  ctx.restore()
+}
+
 export function drawAudioItem(
   ctx: DrawContext,
   args: AudioItemDrawArgs,
@@ -1359,11 +1474,26 @@ export function drawAudioItem(
   if (fadeInPx > 0) drawFadeEnvelope(ctx, rect, 'in', fadeInPx, fadeSpanX, fadeSpanWidth, fadeInCurve, palette)
   if (fadeOutPx > 0) drawFadeEnvelope(ctx, rect, 'out', fadeOutPx, fadeSpanX, fadeSpanWidth, fadeOutCurve, palette)
 
+  // Mute glyph leads, and the label starts after it, so the two can never
+  // overlap on a narrow bar.
+  const headX = rect.x + LABEL_PAD_PX + handleWidth
+  let labelX = headX
+  if (muted && rect.width >= MIN_MUTED_ICON_WIDTH_PX) {
+    drawMutedGlyph(
+      ctx,
+      headX,
+      rect.y + (rect.height - MUTED_ICON_SIZE_PX) / 2,
+      MUTED_ICON_SIZE_PX,
+      palette.colors.audioText,
+    )
+    labelX = headX + MUTED_ICON_SIZE_PX + MUTED_ICON_GAP_PX
+  }
+
   if (rect.width >= MIN_LABEL_WIDTH_PX) {
     ctx.fillStyle = palette.colors.audioText
     ctx.font = LABEL_FONT
     ctx.textBaseline = 'middle'
-    ctx.fillText(label, rect.x + LABEL_PAD_PX + handleWidth, rect.y + rect.height / 2)
+    ctx.fillText(label, labelX, rect.y + rect.height / 2)
   }
   ctx.restore()
 
@@ -1752,6 +1882,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 +2057,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'

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

@@ -60,6 +60,7 @@ import { reflowMagneticLanes } from '../../audioMagnet'
 import { laneOf, normalizeCaptionLanes, resolveDropLane, sameLaneNeighbours } from '../../captionLanes'
 import { collapseGaps, rollEdit, slideItem, slipItem } from '../../cuts'
 import { canKeyframe, enableKeyframing, moveKeyframe, setKeyframe, transformProps, valueAt } from '../../keyframeOps'
+import { moveMarker } from '../markers'
 import { applyMoveDeltaToSelection, applyResizeDeltaToSelection } from '../multiSelectOps'
 import { AUDIO_LANE_HEIGHT_PX, CAPTION_ROW_HEIGHT_PX, computeDerivedTiming, groupAudioLanes, mapTrackItems, moveItemAcrossTracks, normalizeTracks, resolveTargetTrackIdx, trackItems, updateAudioTrack } from '../timeline-model'
 import { DRAG_THRESHOLD_PX, computeResizedItem, resizeWindowedItem, type Draggable } from '../useItemDragDrop'
@@ -167,6 +168,10 @@ export type PointerEffect =
    *  sidebar, which is where caption text is edited now that the inline
    *  contentEditable row is gone. */
   | { type: 'editCaption'; id: string }
+  /** Double-click on a marker: the host opens its inline rename box. Named
+   *  separately from `editCaption` because it routes somewhere else entirely —
+   *  an overlay input on the canvas, not the transcript sidebar. */
+  | { type: 'editMarker'; id: string }
   /** The surface's CSS cursor. Emitted only when it changes. */
   | { type: 'cursor'; cursor: Cursor }
   /** Where to draw the snap guide and how hard it is holding, or nulls to take
@@ -214,6 +219,8 @@ export type GestureKind =
   /** Dragging one caption block's in/out edge. Single-segment: multi-caption
    *  trim is out of scope for v1. */
   | 'caption-trim'
+  /** Re-timing a marker in the strip above the ruler. See `applyMarkerMove`. */
+  | 'marker-move'
   /** Dragging the playhead. Lives on the ruler strip only. */
   | 'scrub'
   /** Dragging a rubber-band box across empty track area to select. */
@@ -330,6 +337,10 @@ export function cursorForHit(hit: HitResult): Cursor {
     // retime-in-place gesture a trim edge does, so it gets the same cursor.
     case 'keyframe':
       return 'ew-resize'
+    // A marker only ever moves horizontally along the strip — same
+    // retime-in-place gesture, same cursor.
+    case 'marker':
+      return 'ew-resize'
     case 'item-edge':
     case 'audio-edge':
     case 'caption-edge':
@@ -355,6 +366,7 @@ function cursorForGesture(gesture: GestureKind): Cursor {
     case 'caption-trim':
     case 'scrub':
     case 'keyframe-move':
+    case 'marker-move':
       return 'ew-resize'
     case 'marquee':
       return 'crosshair'
@@ -384,6 +396,10 @@ export function resolveGesture(hit: HitResult, modifiers: Modifiers): GestureKin
     // A keyframe diamond does exactly one thing too — retime.
     case 'keyframe':
       return 'keyframe-move'
+    // So does a marker: there is nothing to trim and no second dimension to
+    // drag it in, so no modifiers of its own either.
+    case 'marker':
+      return 'marker-move'
     // Captions have no roll/slip/slide either — there is no source window to
     // slip and no neighbour to roll against — so modifiers fall through here
     // exactly as they do for audio.
@@ -567,9 +583,19 @@ function isOverPlayhead(point: Point, ctx: PointerContext): boolean {
  *  into `isEdgeHit` (whose contract is specifically "describes a trim grab",
  *  read via `hit.edge`; a fade grip has no `edge`, only `side`). Keyframe
  *  diamonds win for the identical reason — same size class as a fade grip,
- *  same "smaller and more deliberate than a trim edge" case for the grab. */
+ *  same "smaller and more deliberate than a trim edge" case for the grab.
+ *
+ *  MARKERS win too, and for a stronger reason than any of the above (decision
+ *  D3). A flag is a small target the operator aimed at deliberately, so the D1
+ *  reasoning already covers it — but a marker is also routinely dropped AT the
+ *  playhead: `M` places one at the current time, which puts it exactly on the
+ *  line. Without this exclusion the freshest marker is always the one under the
+ *  playhead, so the COMMONEST marker on the strip would be the one you can
+ *  never pick up. */
 function grabsPlayhead(hit: HitResult, point: Point, ctx: PointerContext): boolean {
-  return !isEdgeHit(hit) && hit.kind !== 'audio-fade' && hit.kind !== 'keyframe' && isOverPlayhead(point, ctx)
+  return !isEdgeHit(hit) && hit.kind !== 'audio-fade' && hit.kind !== 'keyframe'
+    && hit.kind !== 'marker'
+    && isOverPlayhead(point, ctx)
 }
 
 /**
@@ -1124,6 +1150,36 @@ function applyAudioFade(ctx: PointerContext, press: Press, point: Point, snap: S
   return { effects: [{ type: 'projectChange', project: next }], snap, lastProject: next, guide: null }
 }
 
+/**
+ * Retime a marker under the pointer.
+ *
+ * Snapping is deliberately NOT applied: a marker is a free annotation, and the
+ * snap boundaries are clip and audio edges — the moments a marker most often
+ * needs to sit slightly OFF. Nothing else in the strip has edges to snap to.
+ *
+ * GRAB-RELATIVE, not absolute. The hit region is a flat `MARKER_HIT_WIDTH_PX`
+ * wide (hit-test.ts) so that the LABEL is clickable and not just the 2px flag
+ * stem — which means a press very often lands well right of the flag itself.
+ * Retiming to the raw pointer time would teleport the marker up to that full
+ * width to meet the cursor on the first move past threshold. Every other drag
+ * on this surface preserves its grab offset through `dragDeltaSeconds`, and so
+ * does this one. `applyScrub` is absolute and is NOT a precedent for it: when
+ * you scrub, the playhead IS the cursor, so there is no offset to preserve.
+ */
+function applyMarkerMove(ctx: PointerContext, press: Press, point: Point, snap: SnapState, lastProject: Project): Applied {
+  const id = press.hit.markerId
+  const from = press.hit.marker
+  if (!id || !from) return noChange(snap, lastProject)
+  // Anchor on the marker the HIT captured, the way `applyAudioFade` reads
+  // `press.hit.track` — `hitTest` took it from the same project `baseProject`
+  // holds, at the same instant, so it is that project's own marker and needs no
+  // per-move lookup. `HitResult.marker` exists for exactly this.
+  const t = Math.max(0, from.t + dragDeltaSeconds(ctx, press, point))
+  const next = moveMarker(press.baseProject, id, t)
+  if (next === press.baseProject && lastProject === press.baseProject) return noChange(snap, lastProject)
+  return { effects: [{ type: 'projectChange', project: next }], snap, lastProject: next, guide: null }
+}
+
 /**
  * Drag a keyframe-strip diamond to retime it (plan decision 5).
  *
@@ -1480,6 +1536,7 @@ function applyGesture(
     case 'audio-trim':  return applyAudioTrim(ctx, press, point, snap, lastProject, escaped)
     case 'audio-fade':  return applyAudioFade(ctx, press, point, snap, lastProject)
     case 'keyframe-move': return applyKeyframeMove(ctx, press, point, snap, lastProject, escaped)
+    case 'marker-move': return applyMarkerMove(ctx, press, point, snap, lastProject)
     case 'caption-move': return applyCaptionMove(ctx, press, point, snap, lastProject, escaped)
     case 'caption-trim': return applyCaptionTrim(ctx, press, point, snap, lastProject, escaped)
     case 'scrub':       return applyScrub(ctx, point, snap, lastProject)
@@ -1571,7 +1628,9 @@ export function pointerReducer(state: MachineState, event: PointerMachineEvent):
   // gets keyframe hit-testing for free the moment it has a selection —
   // exactly like `ctx.selectedIds` itself is already required on the context,
   // not an opt-in.
-  const hit = hitTest(point, ctx.layout, ctx.viewport, { ...ctx.hitTestOptions, selectedIds: ctx.selectedIds })
+  const hit = hitTest(point, ctx.layout, ctx.viewport, {
+    ...ctx.hitTestOptions, selectedIds: ctx.selectedIds, markers: ctx.project.markers,
+  })
 
   switch (event.type) {
     case 'pointerDown': {
@@ -1582,6 +1641,12 @@ export function pointerReducer(state: MachineState, event: PointerMachineEvent):
       // the full-height red bar anywhere it is reachable does the same thing
       // (`grabsPlayhead`). Landing the seek on mousedown rather than mouseup is
       // what makes the drag continuous.
+      //
+      // A MARKER hit must never reach this branch: it presses like an item, not
+      // like the ruler. Two things keep it out, and both have to hold — `hitTest`
+      // returns 'marker' (never 'ruler') for a point in the strip, and
+      // `grabsPlayhead` excludes 'marker' explicitly. Change either and every
+      // marker press starts scrubbing again.
       const onRuler = hit.kind === 'ruler'
       if (onRuler || grabsPlayhead(hit, point, ctx)) {
         const applied = applyScrub(ctx, point, createSnapState(), ctx.project)
@@ -1683,7 +1748,15 @@ export function pointerReducer(state: MachineState, event: PointerMachineEvent):
       if (state.kind === 'pressed') {
         const { hit: pressed, wasSelected } = state.press
         const effects: PointerEffect[] = []
-        if (pressed.itemId !== undefined) {
+        if (pressed.kind === 'marker' && pressed.markerId !== undefined) {
+          // A marker click selects it, exactly as a clip click does — same
+          // `select` effect, same host selection, which is what lets Delete
+          // reach it. Its id lives in `markerId` rather than `itemId` (a marker
+          // is not an item), so it needs its own branch rather than falling
+          // into the one below. No seek: the playhead belongs to the ruler,
+          // and a marker press is aimed at the flag, not at the time under it.
+          effects.push({ type: 'select', id: pressed.markerId, additive: isAdditive(modifiers) })
+        } else if (pressed.itemId !== undefined) {
           const additive = isAdditive(modifiers)
           effects.push({ type: 'select', id: pressed.itemId, additive })
           // VisualTrackRow seeks on a plain click that changes the selection;
@@ -1802,6 +1875,12 @@ export function pointerReducer(state: MachineState, event: PointerMachineEvent):
       if (hit.kind === 'keyframe' && hit.itemId !== undefined && hit.kfT !== undefined) {
         return { state, effects: [{ type: 'selectKeyframe', itemId: hit.itemId, t: hit.kfT }] }
       }
+      // A marker opens its rename box. Checked up here with the diamond for the
+      // same reason: it carries no `itemId`, so the generic branches below
+      // would drop it on the floor rather than swallow it.
+      if (hit.kind === 'marker' && hit.markerId !== undefined) {
+        return { state, effects: [{ type: 'editMarker', id: hit.markerId }] }
+      }
       // Key the SELECTED element, and only when the click landed ON it. Checked
       // against `ctx.selectedIds` rather than "is there a selection" so a
       // double-click on a different clip never keys the selected one.