@bycrux/editor 1.0.2 → 1.2.0

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'

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)
 }
 
 /**
@@ -637,6 +663,23 @@ function adjacentOnTrack(project: Project, item: VisualItem): { prev?: VisualIte
   }
 }
 
+/** `adjacentOnTrack`'s twin for trim's containment guard — the nearest item
+ *  in either direction on `item`'s own track, WHETHER OR NOT it touches.
+ *  Roll needs a shared boundary to move (that's what it's rolling); a trim's
+ *  containment guard needs the nearest neighbour regardless, because the
+ *  overlap it is bounding is exactly the case where the two are no longer
+ *  touching. */
+function neighboursOnTrack(project: Project, item: VisualItem): { prev?: VisualItem; next?: VisualItem } {
+  const track = trackItems(project).find(t => t.some(other => other.id === item.id))
+  if (!track) return {}
+  const sorted = [...track].sort((a, b) => a.start - b.start)
+  const pos = sorted.findIndex(other => other.id === item.id)
+  return {
+    prev: pos > 0 ? sorted[pos - 1] : undefined,
+    next: pos >= 0 && pos < sorted.length - 1 ? sorted[pos + 1] : undefined,
+  }
+}
+
 /** Where a guide line goes, and how hard the magnet holding it pulls. */
 export interface SnapGuide {
   time: number
@@ -854,7 +897,48 @@ function applyTrim(ctx: PointerContext, press: Press, point: Point, snap: SnapSt
     itemSnapPoints(ctx, press, [fixedEdge, ...originGuard(escaped, [initTime])]),
     ctx.viewport, snap, ctx.snapConfig,
   )
-  const resized = computeResizedItem(item as Draggable, edge, snapped.time)
+
+  // Overlay tracks (anything but tracks[0]) may trim an edge PAST a
+  // neighbour's near boundary — see transitions.js's header: a partial
+  // overlap is a transition, containment is not — but not far enough to
+  // contain the neighbour outright, which `engine/validate.py` rejects.
+  // tracks[0] gets none of this: its own overlap is never checked at all
+  // (primary clips render in `itsoffset` order), so its trim stays exactly
+  // as it was — bounded only by `computeResizedItem`'s own floor below.
+  // Clamped on the TARGET time, before `computeResizedItem` runs, so a
+  // clamp that lands short of the drag still produces a consistent
+  // inPoint/outPoint for video items via `resizeWindowedItem`, rather than
+  // trimming the span after the fact and leaving the source window stale.
+  let targetTime = snapped.time
+  if ((press.hit.trackIdx ?? 0) !== 0) {
+    const { prev, next } = neighboursOnTrack(press.baseProject, item)
+    if (edge === 'end' && next) {
+      targetTime = Math.min(targetTime, next.end - EPSILON)
+      // `next` may ALREADY overlap its own next neighbour (a transition that
+      // predates this drag). The clamp above only keeps this item from
+      // containing `next` outright — it says nothing about that second
+      // overlap, so extending into `next` can still land inside next∩afterNext
+      // and put three items live at the same instant, a shape the two-item
+      // containment guard allows but `engine/validate.py` rejects. Clamp
+      // short of that second neighbour's start whenever the overlap exists.
+      const { next: afterNext } = neighboursOnTrack(press.baseProject, next)
+      if (afterNext && afterNext.start < next.end) {
+        targetTime = Math.min(targetTime, afterNext.start - EPSILON)
+      }
+    }
+    if (edge === 'start' && prev) {
+      targetTime = Math.max(targetTime, prev.start + EPSILON)
+      // Mirror of the `end`-edge guard above: `prev` may already overlap ITS
+      // own previous neighbour, and shrinking this item's start into `prev`
+      // can land inside beforePrev∩prev, making three items live at once.
+      const { prev: beforePrev } = neighboursOnTrack(press.baseProject, prev)
+      if (beforePrev && beforePrev.end > prev.start) {
+        targetTime = Math.max(targetTime, beforePrev.end + EPSILON)
+      }
+    }
+  }
+
+  const resized = computeResizedItem(item as Draggable, edge, targetTime)
 
   // Trims always rebuild from the pressed-at project, never from the running
   // preview — otherwise ripple's gap collapse would compound move by move.
@@ -1066,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).
  *
@@ -1422,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)
@@ -1513,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': {
@@ -1524,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)
@@ -1625,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;
@@ -1744,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.

package/src/video/timeline/markers.ts

@@ -0,0 +1,109 @@
+/**
+ * The marker model — every mutation markers can undergo, as pure functions.
+ *
+ * Same contract as the rest of the timeline model: a function returns the SAME
+ * project reference when it would change nothing, so callers can use `next ===
+ * base` as their no-op guard and never push an empty undo entry or queue a
+ * pointless save (the convention `splitAtTime`, `computeAutoCrossfade` and
+ * `normalizeCaptionLanes` all follow).
+ *
+ * Markers are stored SORTED BY TIME. Nothing downstream re-sorts: the painter
+ * walks the array in order, and `serve/context.py` hands it to the agent as-is.
+ * Sorting on write rather than on read means one rule in one place.
+ */
+import type { EditorProject, Marker } from '../../schema'
+
+/** Fallback frame rate when a project's settings omit one — matches the fps
+ *  default `serve/context.py` and the renderer both use. */
+const DEFAULT_FPS = 30
+
+/** Fresh marker ids. Same shape as `cuts.ts`'s `uniqueId`: a time base plus
+ *  randomness, so two markers dropped in the same millisecond still differ. */
+function markerId(): string {
+  return `mk-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`
+}
+
+/**
+ * The label a new marker gets: one past the highest PURELY NUMERIC label in
+ * use.
+ *
+ * Reading the max rather than counting the array is what stops a delete from
+ * handing out a number twice — delete "2" of 1/2/3 and the next marker must be
+ * "4", not "3". A renamed marker ("cut this") contributes nothing, so renaming
+ * never stalls or rewinds the counter.
+ */
+export function nextMarkerLabel(markers: readonly Marker[]): string {
+  let max = 0
+  for (const m of markers) {
+    // `Number('')` is 0 and `Number('3px')` is NaN — require an all-digits
+    // label so neither can be mistaken for a counter value.
+    if (!/^\d+$/.test(m.label)) continue
+    const n = Number(m.label)
+    if (n > max) max = n
+  }
+  return String(max + 1)
+}
+
+const byTime = (a: Marker, b: Marker) => a.t - b.t
+
+/** Write a marker list back, dropping the key entirely when it empties. */
+function withMarkers(project: EditorProject, markers: Marker[]): EditorProject {
+  if (markers.length === 0) {
+    const { markers: _dropped, ...rest } = project
+    return rest as EditorProject
+  }
+  return { ...project, markers }
+}
+
+/**
+ * Drop a marker at `t`.
+ *
+ * Returns the same project when one already sits within HALF A FRAME: holding
+ * `M` down fires key repeat at the OS's repeat rate, and without this a held
+ * key buries the strip in stacked markers that then have to be deleted one by
+ * one. Half a frame is below the resolution the timeline can even distinguish,
+ * so nothing an operator could deliberately place is refused.
+ */
+export function addMarker(project: EditorProject, t: number, fps = project.settings?.fps ?? DEFAULT_FPS): EditorProject {
+  const at = Math.max(0, t)
+  const existing = project.markers ?? []
+  const halfFrame = 0.5 / (fps > 0 ? fps : DEFAULT_FPS)
+  if (existing.some(m => Math.abs(m.t - at) < halfFrame)) return project
+  const next = [...existing, { id: markerId(), t: at, label: nextMarkerLabel(existing) }].sort(byTime)
+  return { ...project, markers: next }
+}
+
+/** Retime a marker. Same reference for an unknown id or an unchanged time. */
+export function moveMarker(project: EditorProject, id: string, t: number): EditorProject {
+  const existing = project.markers
+  if (!existing) return project
+  const at = Math.max(0, t)
+  const found = existing.find(m => m.id === id)
+  if (!found || found.t === at) return project
+  return withMarkers(project, existing.map(m => (m.id === id ? { ...m, t: at } : m)).sort(byTime))
+}
+
+/**
+ * Rename a marker. The label is trimmed, and an all-whitespace one is refused
+ * rather than committed — a blank marker draws as an empty box and tells the
+ * agent nothing, so a cleared rename box means "leave it alone", not "erase the
+ * name". Deleting the marker is the way to get rid of it.
+ */
+export function renameMarker(project: EditorProject, id: string, label: string): EditorProject {
+  const existing = project.markers
+  if (!existing) return project
+  const next = label.trim()
+  if (!next) return project
+  const found = existing.find(m => m.id === id)
+  if (!found || found.label === next) return project
+  return withMarkers(project, existing.map(m => (m.id === id ? { ...m, label: next } : m)))
+}
+
+/** Remove every marker whose id is in `ids`. Same reference when none matched. */
+export function removeMarkers(project: EditorProject, ids: ReadonlySet<string>): EditorProject {
+  const existing = project.markers
+  if (!existing || existing.length === 0) return project
+  const kept = existing.filter(m => !ids.has(m.id))
+  if (kept.length === existing.length) return project
+  return withMarkers(project, kept)
+}