@hyperframes/studio 0.7.57 → 0.7.58

package/src/player/components/timelineZMirror.ts

@@ -0,0 +1,393 @@
+import type { TimelineElement } from "../store/playerStore";
+import { classifyZone } from "./timelineZones";
+import { isLaneFree, timeRangesOverlap } from "./timelineCollision";
+import { authoredTrackForLane, sameSourceFile } from "./timelineClipDragCommit";
+import { samePaintScope } from "./timelineStackingSync";
+
+/**
+ * Mirror a canvas z-order action (Bring to Front / Bring Forward / Send Backward /
+ * Send to Back) into a timeline LANE move — the pure resolver, no UI wiring.
+ *
+ * ── The model ────────────────────────────────────────────────────────────────
+ * Track order is the DEFAULT paint order; authored z is the ADVANCED override.
+ * Render truth stays z — the renderer never reads track index — and the studio
+ * maintains z ↔ track consistency at EDIT time: a deliberate vertical lane move
+ * syncs z (timelineStackingSync), and a z-order menu action calls THIS resolver
+ * to compute the accompanying lane move. When the user authors z that diverges
+ * from track order, the mirror never fights the authored override — it only
+ * keeps the default in step.
+ *
+ * ── Locked rules (agreed design — do not re-litigate here) ───────────────────
+ * - The mirror computes a lane move to ACCOMPANY a z action on a timeline clip;
+ *   it never replaces the z patch.
+ * - ONE-ELEMENT STEP (bring-forward / send-backward): the z action stepped past
+ *   exactly ONE element — the reference neighbor — so the lane move must too.
+ *   Target = the free lane (whole-span, file-agnostic occupancy, same zone)
+ *   closest to the reference, searched STRICTLY BETWEEN the reference's lane
+ *   and the next temporally-overlapping same-file visual element's lane in the
+ *   direction (exclusive bound). No free lane in that open interval (the common
+ *   back-to-back case) → CREATE one at the boundary immediately beyond the
+ *   reference neighbor (commitTrackInsert semantics) — never scan past the
+ *   second element to a farther free lane, which would overshoot the paint
+ *   order. With no second overlapping element
+ *   beyond the reference, the bound is the zone edge: closest free lane beyond
+ *   the neighbor, else insert immediately beyond it.
+ * - bring-to-front / send-to-back move past the WHOLE overlap set: closest free
+ *   lane beyond the extreme overlap in the direction, else insert adjacent to
+ *   the extreme.
+ * - Direction: bring-forward/front = toward LOWER display lanes (up = above);
+ *   send-backward/back = toward HIGHER lanes, but only within the visual zone —
+ *   the audio zone is untouched and never crossed (a bottom-of-zone insert lands
+ *   AT the visual/audio boundary, i.e. still a visual lane).
+ * - Reference scope: same source file AND same stacking context (see
+ *   samePaintScope — a file can contain several stacking contexts, and leaf z
+ *   is only comparable within one). Lane FREENESS stays file-agnostic (any
+ *   clip in the zone occupies its lane for everyone).
+ * - Non-clip decorations (no timeline presence) are out of scope — callers keep
+ *   z-only behavior for them. Audio elements never mirror (z on audio is
+ *   meaningless); the resolver returns null.
+ *
+ * ── OPEN product question ────────────────────────────────────────────────────
+ * send-to-back / bring-to-front scope: below/above EVERYTHING visual, or only
+ * the clips that temporally overlap the moved clip? The default implemented
+ * here is TEMPORAL-OVERLAP scope (the extreme is computed over same-file clips
+ * that overlap the moved clip in time), pending M/Bin sign-off. A clip with no
+ * temporal overlaps in the direction is "already at the extreme" → null.
+ *
+ * Deterministic: a pure function of its inputs — no Date, no randomness, no DOM.
+ */
+
+export type ZMirrorAction = "bring-to-front" | "bring-forward" | "send-backward" | "send-to-back";
+
+export interface ZMirrorInput {
+  action: ZMirrorAction;
+  /** The clip acted on — store/display space (post-normalizeToZones lanes),
+   *  carrying `authoredTrack` when the display lane diverges from the file. */
+  element: TimelineElement;
+  /** The expanded display element set (same set the drag commit reasons on). */
+  elements: TimelineElement[];
+  /** Timeline key of the neighbor the z action stepped over (forward/backward),
+   *  when known — see resolveCrossedNeighbor in canvasContextMenuZOrder. */
+  crossedKey?: string | null;
+}
+
+export type ZMirrorLaneMove =
+  | {
+      /** Land on an existing display lane. */
+      kind: "move";
+      /** Display lane to move to (store space). */
+      displayTrack: number;
+      /** Authored-space value to write (authoredTrackForLane translation). */
+      persistTrack: number;
+    }
+  | {
+      /** Create a new lane: boundary row compatible with commitTrackInsert's
+       *  insertRow (index into the ascending display trackOrder; 0 = above the
+       *  top lane, length = below the bottom). */
+      kind: "insert";
+      insertRow: number;
+    }
+  | null;
+
+const keyOf = (el: TimelineElement): string => el.key ?? el.id;
+
+/**
+ * Lane candidates for an EXPANDED sub-comp child: only its own siblings' lanes
+ * (same file). An expanded child's display row is synthetic host-space — landing
+ * it on an arbitrary host lane has no same-file occupant to translate the
+ * authored track from, and a track INSERT would renumber host space from a
+ * child origin. Ordinary top-level clips return null (no restriction).
+ */
+function expandedChildAllowedLanes(
+  element: TimelineElement,
+  elements: TimelineElement[],
+): ReadonlySet<number> | null {
+  if (element.expandedParentStart == null) return null;
+  const selfKey = keyOf(element);
+  return new Set(
+    elements
+      .filter((el) => keyOf(el) !== selfKey && sameSourceFile(el, element))
+      .map((el) => el.track),
+  );
+}
+
+/** Ascending unique display lanes of `elements` — identical to how Timeline.tsx
+ *  builds `trackOrder`, so `insertRow` indexes the same boundary space. Exported
+ *  so the mirror wiring can hand commitZMirrorLaneMove the matching trackOrder. */
+export function displayTrackOrder(elements: TimelineElement[]): number[] {
+  return [...new Set(elements.map((el) => el.track))].sort((a, b) => a - b);
+}
+
+/**
+ * Resolve the timeline lane move that mirrors a z-order action on `element`.
+ * Returns null when no timeline mirror applies: audio / zero-length clips, no
+ * reference neighbor in the action's direction (the menu action was likely
+ * disabled or a no-op), or the clip is already laned where the action puts it.
+ */
+export function resolveZMirrorLaneMove(input: ZMirrorInput): ZMirrorLaneMove {
+  const { action, element, elements } = input;
+  if (classifyZone(element) === "audio") return null;
+  if (!(element.duration > 0)) return null;
+
+  const selfKey = keyOf(element);
+  const start = element.start;
+  const end = element.start + element.duration;
+  const up = action === "bring-forward" || action === "bring-to-front";
+
+  // Same paint scope (source file + stacking context), visual, temporally overlapping.
+  const overlapSet = elements.filter(
+    (el) =>
+      keyOf(el) !== selfKey &&
+      classifyZone(el) === "visual" &&
+      samePaintScope(el, element) &&
+      timeRangesOverlap(start, end, el.start, el.start + el.duration),
+  );
+
+  const referenceLane = resolveReferenceLane(input, overlapSet, up);
+  if (referenceLane == null) return null;
+
+  const order = displayTrackOrder(elements);
+  const visualLanes = displayTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));
+  const refIdx = visualLanes.indexOf(referenceLane);
+  if (refIdx === -1) return null; // reference is not a visual lane — no mirror
+
+  const boundLane = stepBoundLane(action, overlapSet, referenceLane, up);
+  const allowedLanes = expandedChildAllowedLanes(element, elements);
+  const lane = closestFreeLane({
+    elements,
+    visualLanes,
+    refIdx,
+    up,
+    boundLane,
+    start,
+    end,
+    selfKey,
+    allowedLanes,
+  });
+  if (lane != null) {
+    // The closest free lane is the clip's OWN lane (possible only when z and
+    // track had diverged): the clip already sits where the action puts it.
+    if (lane === element.track) return null;
+    return {
+      kind: "move",
+      displayTrack: lane,
+      persistTrack: authoredTrackForLane(lane, elements, element),
+    };
+  }
+
+  // Expanded children never INSERT: a new lane is a host-lane-space renumber,
+  // meaningless in the child's own file (buildTrackInsertEdits refuses too).
+  if (allowedLanes) return null;
+  // No free lane before the bound (or the zone edge) → create one adjacent to
+  // the reference: the boundary between its lane and the next in direction.
+  return { kind: "insert", insertRow: order.indexOf(referenceLane) + (up ? 0 : 1) };
+}
+
+export interface ZRepositionInput {
+  /** The clip the Layers-panel drag moved — store/display space. */
+  element: TimelineElement;
+  /** The expanded display element set (same set the drag commit reasons on). */
+  elements: TimelineElement[];
+  /**
+   * Timeline keys of the reordered sibling set in DESIRED render order,
+   * bottom→top, the moved element's own key included at its new slot. Siblings
+   * with no timeline presence carry null — they are skipped when resolving the
+   * nearest clip neighbors.
+   */
+  desiredOrderKeys: ReadonlyArray<string | null>;
+}
+
+/**
+ * Mirror an ARBITRARY z repositioning (a Layers-panel drag, which can jump
+ * several siblings in one drop) into a timeline lane move — the "equal jump"
+ * generalization of {@link resolveZMirrorLaneMove}'s one-step rule: the clip
+ * lands between its NEW paint neighbors' lanes.
+ *
+ * The reference lanes are the nearest siblings in the desired render order
+ * that are visual, same-file timeline clips: `above` = the first such sibling
+ * that now paints above the moved clip, `below` = the first that paints below.
+ * Target lane = the free lane (whole-span, same zone) strictly between the
+ * above-neighbor's lane and the below-neighbor's lane, closest to the above
+ * neighbor; when only one neighbor exists the zone edge bounds the search on
+ * the open side. No free lane in the interval → INSERT a new lane immediately
+ * beyond the above neighbor (below it), or immediately above the below
+ * neighbor when dropped on top — commitTrackInsert semantics, exactly like the
+ * menu mirror's insert fallback.
+ *
+ * Null when no mirror applies: audio / zero-length clips, no clip neighbor in
+ * the set (a z-only decoration shuffle), or the clip already sits where the
+ * drop puts it.
+ */
+// fallow-ignore-next-line complexity
+export function resolveRepositionLaneMove(input: ZRepositionInput): ZMirrorLaneMove {
+  const { element, elements, desiredOrderKeys } = input;
+  if (classifyZone(element) === "audio") return null;
+  if (!(element.duration > 0)) return null;
+
+  const selfKey = keyOf(element);
+  const selfIdx = desiredOrderKeys.indexOf(selfKey);
+  if (selfIdx === -1) return null;
+
+  const clipLaneForKey = (key: string | null): number | null => {
+    if (key == null) return null;
+    const el = elements.find((candidate) => keyOf(candidate) === key);
+    return el &&
+      classifyZone(el) === "visual" &&
+      el.duration > 0 &&
+      samePaintScope(el, element) &&
+      keyOf(el) !== selfKey
+      ? el.track
+      : null;
+  };
+
+  // Nearest clip neighbor painting ABOVE (later in bottom→top order) / BELOW.
+  let aboveLane: number | null = null;
+  for (let i = selfIdx + 1; i < desiredOrderKeys.length && aboveLane == null; i++) {
+    aboveLane = clipLaneForKey(desiredOrderKeys[i]);
+  }
+  let belowLane: number | null = null;
+  for (let i = selfIdx - 1; i >= 0 && belowLane == null; i--) {
+    belowLane = clipLaneForKey(desiredOrderKeys[i]);
+  }
+  if (aboveLane == null && belowLane == null) return null;
+
+  const order = displayTrackOrder(elements);
+  const visualLanes = displayTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));
+  const allowedLanes = expandedChildAllowedLanes(element, elements);
+  const args = {
+    elements,
+    visualLanes,
+    start: element.start,
+    end: element.start + element.duration,
+    selfKey,
+    allowedLanes,
+  };
+
+  let lane: number | null;
+  let insertRow: number;
+  if (aboveLane != null) {
+    // Paints above = LOWER display lane: search DOWNWARD from the above
+    // neighbor (closest lane under it first), bounded by the below neighbor
+    // (exclusive) when one exists, else by the zone edge.
+    const refIdx = visualLanes.indexOf(aboveLane);
+    if (refIdx === -1) return null;
+    lane = closestFreeLane({ ...args, refIdx, up: false, boundLane: belowLane });
+    insertRow = order.indexOf(aboveLane) + 1;
+  } else {
+    // Dropped above everything that remains: search UPWARD from the below
+    // neighbor toward the zone top.
+    const refIdx = visualLanes.indexOf(belowLane!);
+    if (refIdx === -1) return null;
+    lane = closestFreeLane({ ...args, refIdx, up: true, boundLane: null });
+    insertRow = order.indexOf(belowLane!);
+  }
+
+  if (lane != null) {
+    if (lane === element.track) return null;
+    return {
+      kind: "move",
+      displayTrack: lane,
+      persistTrack: authoredTrackForLane(lane, elements, element),
+    };
+  }
+  // Expanded children never INSERT (host-lane-space renumber from a child
+  // origin) — see expandedChildAllowedLanes.
+  if (allowedLanes) return null;
+  return { kind: "insert", insertRow };
+}
+
+/**
+ * ONE-ELEMENT-STEP bound (bring-forward / send-backward only): the lane of the
+ * NEXT temporally-overlapping same-file visual element strictly beyond the
+ * reference in the direction — the free-lane search may not reach it
+ * (exclusive). Front/back have no bound (they step past the whole overlap
+ * set), and neither does a step with no second overlapping element beyond the
+ * reference (the zone edge bounds instead).
+ */
+function stepBoundLane(
+  action: ZMirrorAction,
+  overlapSet: TimelineElement[],
+  referenceLane: number,
+  up: boolean,
+): number | null {
+  if (action !== "bring-forward" && action !== "send-backward") return null;
+  const beyond = overlapSet
+    .map((el) => el.track)
+    .filter((lane) => (up ? lane < referenceLane : lane > referenceLane));
+  if (beyond.length === 0) return null;
+  return (up ? Math.max : Math.min)(...beyond);
+}
+
+/**
+ * Closest free lane strictly beyond the reference, lane-by-lane in direction,
+ * whole-span freeness, same zone (visual lanes only — never into audio),
+ * stopping at the exclusive bound when one applies. Null → no free lane in
+ * the open interval.
+ */
+function closestFreeLane(args: {
+  elements: TimelineElement[];
+  visualLanes: number[];
+  refIdx: number;
+  up: boolean;
+  boundLane: number | null;
+  start: number;
+  end: number;
+  selfKey: string;
+  /** When set, only these lanes are candidates (expanded-child scoping). */
+  allowedLanes?: ReadonlySet<number> | null;
+}): number | null {
+  const { elements, visualLanes, refIdx, up, boundLane, start, end, selfKey, allowedLanes } = args;
+  const step = up ? -1 : 1;
+  for (let i = refIdx + step; i >= 0 && i < visualLanes.length; i += step) {
+    const lane = visualLanes[i];
+    if (pastSearchBound(lane, boundLane, up)) break;
+    if (allowedLanes && !allowedLanes.has(lane)) continue;
+    if (isLaneFree(elements, lane, start, end, selfKey)) return lane;
+  }
+  return null;
+}
+
+/** The exclusive one-element-step bound: stop at (never on/past) `boundLane`. */
+function pastSearchBound(lane: number, boundLane: number | null, up: boolean): boolean {
+  if (boundLane == null) return false;
+  return up ? lane <= boundLane : lane >= boundLane;
+}
+
+/**
+ * The lane the search starts from (the "reference neighbor"):
+ * - forward/backward: the crossed neighbor when provided and valid (a visual
+ *   clip in the set); otherwise the closest temporally-overlapping same-file
+ *   clip in the direction. None → null (the menu was probably disabled).
+ * - front/back: the extreme of the temporal-overlap set — topmost (lowest lane)
+ *   for front, bottommost (highest lane) for back — restricted to overlaps
+ *   strictly beyond the clip's own lane. None → already at the extreme → null.
+ */
+function resolveReferenceLane(
+  input: ZMirrorInput,
+  overlapSet: TimelineElement[],
+  up: boolean,
+): number | null {
+  const stepAction = input.action === "bring-forward" || input.action === "send-backward";
+  if (stepAction) {
+    const crossedLane = crossedNeighborLane(input);
+    // Unknown / absent / non-visual crossed key → the temporal neighbor below.
+    if (crossedLane != null) return crossedLane;
+  }
+
+  // Overlapping same-file lanes strictly beyond the moved clip's lane, in direction.
+  const lanes = overlapSet
+    .map((el) => el.track)
+    .filter((lane) => (up ? lane < input.element.track : lane > input.element.track));
+  if (lanes.length === 0) return null;
+
+  // Step actions want the CLOSEST lane in direction (max when up, min when
+  // down); front/back want the EXTREME of the set (min when up, max when down).
+  return (stepAction === up ? Math.max : Math.min)(...lanes);
+}
+
+/** The crossed neighbor's display lane, when the key names a visual clip in the set. */
+function crossedNeighborLane({ elements, crossedKey }: ZMirrorInput): number | null {
+  if (crossedKey == null) return null;
+  const crossed = elements.find((el) => keyOf(el) === crossedKey);
+  return crossed && classifyZone(crossed) === "visual" ? crossed.track : null;
+}

package/src/player/components/timelineZoom.test.ts

@@ -45,11 +45,11 @@ describe("getTimelinePixelsPerSecond", () => {
 
 describe("getNextTimelineZoomPercent", () => {
   it("zooms out from fit relative to 100 percent", () => {
-    expect(getNextTimelineZoomPercent("out", "fit", 375)).toBe(80);
+    expect(getNextTimelineZoomPercent("out", "fit", 375)).toBe(50);
   });
 
   it("zooms in from fit relative to 100 percent", () => {
-    expect(getNextTimelineZoomPercent("in", "fit", 375)).toBe(125);
+    expect(getNextTimelineZoomPercent("in", "fit", 375)).toBe(200);
   });
 
   it("clamps the lower bound", () => {

package/src/player/components/timelineZoom.ts

@@ -2,9 +2,13 @@ import type { ZoomMode } from "../store/playerStore";
 
 export const MIN_TIMELINE_ZOOM_PERCENT = 10;
 export const MAX_TIMELINE_ZOOM_PERCENT = 2000;
-const ZOOM_OUT_FACTOR = 0.8;
-const ZOOM_IN_FACTOR = 1.25;
-const PINCH_ZOOM_SENSITIVITY = 0.0035;
+// CapCut-strength steps: one button press / pinch gesture moves the zoom
+// meaningfully (user feedback, twice-doubled: 1.25×/0.8× + 0.0035 felt like
+// "zooming several times to get anywhere", then 1.5× + 0.007 still too soft).
+// Kept reciprocal (2 × 0.5 = 1) so in+out round-trips.
+const ZOOM_OUT_FACTOR = 0.5;
+const ZOOM_IN_FACTOR = 2;
+const PINCH_ZOOM_SENSITIVITY = 0.014;
 
 export function clampTimelineZoomPercent(percent: number): number {
   if (!Number.isFinite(percent)) return 100;

package/src/player/components/useTimelineClipDrag.ts

@@ -76,7 +76,7 @@ interface UseTimelineClipDragInput {
    * commitDraggedClipMove. Both optional → absent = no-op (backward compatible).
    */
   readZIndex?: (element: TimelineElement) => number;
-  onStackingPatches?: (patches: StackingPatch[]) => void;
+  onStackingPatches?: (patches: StackingPatch[]) => Promise<unknown> | void;
 }
 
 export function useTimelineClipDrag({

package/src/player/components/useTimelineGapHighlights.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { buildTimelineGapStrips } from "./useTimelineGapHighlights";
+
+function el(id: string, track: number, start: number, duration: number): TimelineElement {
+  return { id, key: id, tag: "video", start, duration, track, domId: id };
+}
+
+const laneA = [el("a1", 0, 1, 2), el("a2", 0, 5, 2)]; // gaps: [0,1), [3,5)
+const laneB = [el("b1", 1, 0, 2), el("b2", 1, 2, 3)]; // contiguous
+const tracks: [number, TimelineElement[]][] = [
+  [0, laneA],
+  [1, laneB],
+];
+const expandedElements = [...laneA, ...laneB];
+
+const base = {
+  gapHighlight: null,
+  tracks,
+  selectedElementId: null,
+  selectedElementIds: new Set<string>(),
+  expandedElements,
+  dragActive: false,
+  displayDuration: 60,
+};
+
+describe("buildTimelineGapStrips", () => {
+  it("emits a loud hover strip set from the gap-menu highlight", () => {
+    const strips = buildTimelineGapStrips({
+      ...base,
+      gapHighlight: { track: 0, intervals: [{ start: 3, end: 5 }] },
+    });
+    expect(strips).toEqual([{ track: 0, intervals: [{ start: 3, end: 5 }], kind: "hover" }]);
+  });
+
+  it("click-selection lights the WHOLE lane minus clips, trailing space included", () => {
+    const strips = buildTimelineGapStrips({ ...base, selectedElementId: "a1" });
+    expect(strips).toEqual([
+      {
+        track: 0,
+        intervals: [
+          { start: 0, end: 1 },
+          { start: 3, end: 5 },
+          { start: 7, end: 60 },
+        ],
+        kind: "selected",
+      },
+    ]);
+  });
+
+  it("a contiguous lane still lights its trailing open space", () => {
+    expect(buildTimelineGapStrips({ ...base, selectedElementId: "b1" })).toEqual([
+      { track: 1, intervals: [{ start: 5, end: 60 }], kind: "selected" },
+    ]);
+  });
+
+  it("a lane filling the whole rendered extent emits nothing", () => {
+    const laneFull = [el("f1", 5, 0, 60)];
+    const strips = buildTimelineGapStrips({
+      ...base,
+      tracks: [...tracks, [5, laneFull]],
+      expandedElements: [...expandedElements, ...laneFull],
+      selectedElementId: "f1",
+    });
+    expect(strips).toEqual([]);
+  });
+
+  it("a one-member selectedElementIds mirror of the click still counts as single", () => {
+    // The store mirrors a plain click into selectedElementIds = {clicked}.
+    const strips = buildTimelineGapStrips({
+      ...base,
+      selectedElementId: "a1",
+      selectedElementIds: new Set(["a1"]),
+    });
+    expect(strips).toHaveLength(1);
+    expect(strips[0].kind).toBe("selected");
+  });
+
+  it("marquee multi-selection never emits the selected hint", () => {
+    const strips = buildTimelineGapStrips({
+      ...base,
+      selectedElementId: "a1",
+      selectedElementIds: new Set(["a1", "b1"]),
+    });
+    expect(strips).toEqual([]);
+  });
+
+  it("hover wins on its own lane — no doubled strips for the same track", () => {
+    const strips = buildTimelineGapStrips({
+      ...base,
+      gapHighlight: { track: 0, intervals: [{ start: 3, end: 5 }] },
+      selectedElementId: "a1",
+    });
+    expect(strips).toHaveLength(1);
+    expect(strips[0].kind).toBe("hover");
+  });
+
+  it("hover and selection on DIFFERENT lanes coexist", () => {
+    const laneC = [el("c1", 2, 4, 2)];
+    const strips = buildTimelineGapStrips({
+      ...base,
+      tracks: [...tracks, [2, laneC]],
+      expandedElements: [...expandedElements, ...laneC],
+      gapHighlight: { track: 2, intervals: [{ start: 0, end: 4 }] },
+      selectedElementId: "a1",
+    });
+    expect(strips.map((s) => s.kind)).toEqual(["hover", "selected"]);
+  });
+
+  it("a live drag suppresses every strip", () => {
+    const strips = buildTimelineGapStrips({
+      ...base,
+      dragActive: true,
+      gapHighlight: { track: 0, intervals: [{ start: 3, end: 5 }] },
+      selectedElementId: "a1",
+    });
+    expect(strips).toEqual([]);
+  });
+});

package/src/player/components/useTimelineGapHighlights.ts

@@ -0,0 +1,110 @@
+import { useMemo } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import { laneGapFloor, resolveLaneEmptyIntervals, type TrackGapInterval } from "./timelineGaps";
+import type { TrackGapHighlight } from "./useTrackGapMenu";
+
+/**
+ * One lane's gap strips for the TimelineCanvas overlay.
+ *
+ * kind "hover"    — the gap(s) a hovered "Close gap" / "Close all gaps" menu
+ *                   row would collapse: the loud affordance.
+ * kind "selected" — every empty interval on a click-selected clip's lane: the
+ *                   quiet always-on hint (single click-selection only — a
+ *                   marquee multi-select spans lanes and would paint noise).
+ */
+export interface TimelineLaneGapStrips {
+  track: number;
+  intervals: TrackGapInterval[];
+  kind: "hover" | "selected";
+}
+
+/**
+ * Derive the gap strips TimelineCanvas paints. The menu-hover highlight wins
+ * on its lane (painting both would just double the same strips); the
+ * selected-clip hint renders on the selection's lane otherwise. Suppressed
+ * entirely during a live drag — the drop placeholder / insert line own that
+ * moment, and the lane set is in flux.
+ */
+interface GapHighlightInput {
+  gapHighlight: TrackGapHighlight | null;
+  tracks: [number, TimelineElement[]][];
+  selectedElementId: string | null;
+  selectedElementIds: ReadonlySet<string>;
+  expandedElements: TimelineElement[];
+  dragActive: boolean;
+  /** Rendered timeline extent (seconds) — the selected-lane highlight spans the
+   *  WHOLE lane minus its clips, trailing open space included. */
+  displayDuration: number;
+}
+
+/**
+ * Single selection only: the store mirrors a plain click into a one-member
+ * selectedElementIds set (setSelectedElementId collapses the multi-select),
+ * so "single" means empty OR exactly the selected clip itself. A marquee
+ * multi-select spans lanes and stays hint-free.
+ */
+function isSingleSelection(selectedElementId: string, ids: ReadonlySet<string>): boolean {
+  return ids.size === 0 || (ids.size === 1 && ids.has(selectedElementId));
+}
+
+/** The subtle strips for a single click-selected clip's lane, or null. */
+function selectedLaneStrips(input: GapHighlightInput): TimelineLaneGapStrips | null {
+  const { selectedElementId, selectedElementIds, expandedElements, tracks, gapHighlight } = input;
+  if (!selectedElementId || !isSingleSelection(selectedElementId, selectedElementIds)) return null;
+  const selected = expandedElements.find((el) => (el.key ?? el.id) === selectedElementId);
+  if (!selected || selected.track === gapHighlight?.track) return null;
+  const laneElements = tracks.find(([t]) => t === selected.track)?.[1] ?? [];
+  const intervals = resolveLaneEmptyIntervals(
+    laneElements,
+    input.displayDuration,
+    undefined,
+    laneGapFloor(laneElements),
+  );
+  return intervals.length > 0 ? { track: selected.track, intervals, kind: "selected" } : null;
+}
+
+/** Pure strip derivation — exported for direct unit testing. */
+export function buildTimelineGapStrips(input: GapHighlightInput): TimelineLaneGapStrips[] {
+  if (input.dragActive) return [];
+  const strips: TimelineLaneGapStrips[] = [];
+  if (input.gapHighlight && input.gapHighlight.intervals.length > 0) {
+    strips.push({ ...input.gapHighlight, kind: "hover" });
+  }
+  // Single click-selection → subtle gap hint on that clip's lane.
+  const selected = selectedLaneStrips(input);
+  if (selected) strips.push(selected);
+  return strips;
+}
+
+export function useTimelineGapHighlights(input: GapHighlightInput): TimelineLaneGapStrips[] {
+  const {
+    gapHighlight,
+    tracks,
+    selectedElementId,
+    selectedElementIds,
+    expandedElements,
+    dragActive,
+    displayDuration,
+  } = input;
+  return useMemo(
+    () =>
+      buildTimelineGapStrips({
+        gapHighlight,
+        tracks,
+        selectedElementId,
+        selectedElementIds,
+        expandedElements,
+        dragActive,
+        displayDuration,
+      }),
+    [
+      gapHighlight,
+      tracks,
+      selectedElementId,
+      selectedElementIds,
+      expandedElements,
+      dragActive,
+      displayDuration,
+    ],
+  );
+}