@hyperframes/studio 0.8.46 → 0.8.48

package/src/player/components/automationLaneData.ts

@@ -22,7 +22,7 @@ import {
   type HfAutomationLane,
 } from "@hyperframes/core/audio-automation";
 import { parseAudioFxChain, type HfAudioFxChain } from "@hyperframes/core/audio-fx";
-import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { isAudioOrVideoTimelineElement } from "../../utils/timelineInspector";
 import type { TimelineElement } from "../store/playerStore";
 
 const EMPTY: HfAutomation = { version: 1, lanes: [] };
@@ -245,13 +245,14 @@ export interface AutomationLaneGroup {
  * spectrum, top down), so the first clip to carry a property fixes its row and
  * later clips only append properties nobody has shown yet.
  *
- * Non-audio elements contribute nothing, matching `automationLaneCountOf` — the
- * row's reserved height and its drawn lanes have to count the same clips.
+ * Gated on `isAudioOrVideoTimelineElement`, the same predicate `automationLaneCountOf`
+ * and `TimelineAutomationLaneSlot`'s clip filter use — the row's reserved height
+ * and its drawn lanes have to count the same clips.
  */
 export function groupAutomationLanes(elements: readonly TimelineElement[]): AutomationLaneGroup[] {
   const groups = new Map<string, AutomationLaneGroup>();
   for (const element of elements) {
-    if (!isAudioTimelineElement(element)) continue;
+    if (!isAudioOrVideoTimelineElement(element)) continue;
     const chain = elementFxChain(element);
     for (const lane of elementAutomationLanes(element)) {
       const key = laneGroupKey(lane.target, chain);

package/src/player/components/automationLaneGeometry.ts

@@ -23,6 +23,21 @@ import { getAudioFxDef, type HfAudioFxChain } from "@hyperframes/core/audio-fx";
 /** Points nearer than this in clip seconds are the same point, not two. */
 export const POINT_MERGE_SEC = 0.02;
 
+/** Insert or replace the point nearest `t` — the one merge/seed rule every
+ * hand-editing gesture on a lane uses (timeline double-click, panel control). */
+export function mergeInsertPoint(
+  points: readonly HfAutomationLane["points"][number][],
+  t: number,
+  v: number,
+): HfAutomationLane["points"] {
+  const kept = points.filter((p) => Math.abs(p.t - t) > POINT_MERGE_SEC);
+  // A lane's first point alone would be a constant, which is not what
+  // committing to an empty lane means: seed the far end at the same value so
+  // the envelope has somewhere to go.
+  const seeded = points.length === 0 && t > POINT_MERGE_SEC ? [{ t: 0, v }] : [];
+  return [...seeded, ...kept, { t, v }].sort((a, b) => a.t - b.t);
+}
+
 /**
  * Closest two breakpoints may sit in clip seconds while still being two points.
  *

package/src/player/components/timelineDragDrop.test.tsx

@@ -56,7 +56,6 @@ function renderHarness(
     api = useTimelineAssetDrop({
       scrollRef: { current: scroll },
       ppsRef: { current: 40 },
-      durationRef: { current: 120 },
       trackOrderRef: { current: tracks },
       rowGeometryRef: { current: geometry },
       contentOrigin: 0,
@@ -138,7 +137,6 @@ describe("useTimelineAssetDrop", () => {
   it("drops once on a model row outside the mounted window and appends below the last row", () => {
     const onAssetDrop = vi.fn();
     const view = renderHarness(onAssetDrop);
-    usePlayerStore.getState().setCurrentTime(12.5);
     view.scroll.scrollTop = view.scroll.scrollHeight - view.scroll.clientHeight;
     const transfer = assetTransfer(JSON.stringify({ path: "/media/hero.mp4" }));
 
@@ -148,11 +146,29 @@ describe("useTimelineAssetDrop", () => {
     });
 
     expect(onAssetDrop).toHaveBeenCalledTimes(1);
-    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 12.5, track: 100 });
+    // pps=40, clientX=400 -> 10s at the pointer, not the playhead.
+    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 10, track: 100 });
     expect(view.api.isDragOver).toBe(false);
     act(() => view.root.unmount());
   });
 
+  it("places the drop at the pointer x, ignoring the playhead", () => {
+    const onAssetDrop = vi.fn();
+    const view = renderHarness(onAssetDrop);
+    usePlayerStore.getState().setCurrentTime(50);
+    const transfer = assetTransfer(JSON.stringify({ path: "/media/hero.mp4" }));
+
+    act(() => {
+      view.api.handleAssetDragOver(dragEvent(transfer, 80, 100));
+      view.api.handleAssetDrop(dragEvent(transfer, 80, 100));
+    });
+
+    // pps=40, clientX=80 -> 2s, far from the 50s playhead: proves start tracks
+    // the drop position, not usePlayerStore.currentTime.
+    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 2, track: 0 });
+    act(() => view.root.unmount());
+  });
+
   it("ignores malformed payloads and clears the actor on project reset", () => {
     const onAssetDrop = vi.fn();
     const view = renderHarness(onAssetDrop, 1);
@@ -190,7 +206,8 @@ describe("useTimelineAssetDrop", () => {
     });
 
     expect(onAssetDrop).not.toHaveBeenCalled();
-    expect(onBlockDrop).toHaveBeenCalledExactlyOnceWith("title-card", { start: 0, track: 0 });
+    // pps=40, clientX=400 -> 10s at the pointer.
+    expect(onBlockDrop).toHaveBeenCalledExactlyOnceWith("title-card", { start: 10, track: 0 });
     act(() => view.root.unmount());
   });
 

package/src/player/components/timelineDragDrop.ts

@@ -4,7 +4,6 @@ import {
   parseTimelineCompositionPayload,
   TIMELINE_COMPOSITION_MIME,
 } from "../../utils/timelineCompositionDrop";
-import { usePlayerStore } from "../store/playerStore";
 import { resolveTimelineAssetDrop, type TimelineRowGeometry } from "./timelineLayout";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
 import {
@@ -15,7 +14,6 @@ import {
 interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
   scrollRef: RefObject<HTMLDivElement | null>;
   ppsRef: RefObject<number>;
-  durationRef: RefObject<number>;
   trackOrderRef: RefObject<number[]>;
   rowGeometryRef: RefObject<TimelineRowGeometry>;
   contentOrigin: number;
@@ -53,11 +51,6 @@ function invokeDropCallback(callback: () => Promise<void> | void): void {
   }
 }
 
-function resolveDropStart(usePointerStart: boolean, pointerStart: number): number {
-  if (usePointerStart) return pointerStart;
-  return Math.max(0, usePlayerStore.getState().currentTime);
-}
-
 function applyFileDrop(
   transfer: DataTransfer,
   onFileDrop: TimelineDropCallbacks["onFileDrop"],
@@ -87,17 +80,14 @@ function applyTypedJsonDrop(
 }
 
 /**
- * Dropping an asset/file/block onto the timeline places it at the PLAYHEAD —
- * start is the current playhead time, only the track comes from the drop y.
- * Deliberate product choice (user preference, 2026-07-09): every add lands at
- * the playhead regardless of drop x, like CapCut's add-to-timeline. External
- * OS file drops and internal asset drops share this same placement path, so
- * both land identically.
+ * Dropping an asset/file/block/composition onto the timeline places it at the
+ * exact time and track it was dropped on, like CapCut (pointer placement on
+ * every track but the magnetic main track). Supersedes the prior playhead
+ * decision (#2291); playhead adds stay available, see useAddAssetAtPlayhead.
  */
 export function useTimelineAssetDrop({
   scrollRef,
   ppsRef,
-  durationRef,
   trackOrderRef,
   rowGeometryRef,
   contentOrigin,
@@ -185,10 +175,10 @@ export function useTimelineAssetDrop({
   );
 
   const resolveDropPlacement = useCallback(
-    (clientX: number, clientY: number, usePointerStart = false): TimelinePlacement => {
+    (clientX: number, clientY: number): TimelinePlacement => {
       const scroll = scrollRef.current;
       const rect = scroll?.getBoundingClientRect();
-      const pointer = resolveTimelineAssetDrop(
+      return resolveTimelineAssetDrop(
         {
           rectLeft: rect?.left ?? 0,
           rectTop: rect?.top ?? 0,
@@ -196,20 +186,14 @@ export function useTimelineAssetDrop({
           scrollTop: scroll?.scrollTop ?? 0,
           contentOrigin,
           pixelsPerSecond: ppsRef.current,
-          duration: durationRef.current,
-          clampStartToDuration: !usePointerStart,
           rowHeights: rowGeometryRef.current.rowHeights,
           trackOrder: trackOrderRef.current,
         },
         clientX,
         clientY,
       );
-      return {
-        start: resolveDropStart(usePointerStart, pointer.start),
-        track: pointer.track,
-      };
     },
-    [scrollRef, ppsRef, durationRef, trackOrderRef, rowGeometryRef, contentOrigin],
+    [scrollRef, ppsRef, trackOrderRef, rowGeometryRef, contentOrigin],
   );
 
   const handleAssetDrop = useCallback(
@@ -218,15 +202,15 @@ export function useTimelineAssetDrop({
       const canCommit = activeDropEpochRef.current === sessionEpoch;
       clearDropPreview();
       if (!canCommit) return;
+      const placement = resolveDropPlacement(e.clientX, e.clientY);
+
       const compositionPayload = parseTimelineCompositionPayload(
         e.dataTransfer.getData(TIMELINE_COMPOSITION_MIME),
       );
       if (compositionPayload && onCompositionDrop) {
-        const placement = resolveDropPlacement(e.clientX, e.clientY, true);
         invokeDropCallback(() => onCompositionDrop(compositionPayload.sourcePath, placement));
         return;
       }
-      const placement = resolveDropPlacement(e.clientX, e.clientY);
 
       if (applyFileDrop(e.dataTransfer, onFileDrop, placement)) return;
       if (applyTypedJsonDrop(e.dataTransfer, TIMELINE_ASSET_MIME, "path", onAssetDrop, placement)) {

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

@@ -5,6 +5,8 @@ import {
   canShiftTrackGapClips,
   commitCloseAllTrackGaps,
   commitCloseTrackGap,
+  resolveMainTrackDeleteRippleShifts,
+  resolveShiftedElements,
 } from "./timelineGapCommit";
 import { resolveAllTrackGaps } from "./timelineGaps";
 
@@ -150,6 +152,25 @@ describe("commitCloseAllTrackGaps", () => {
   });
 });
 
+describe("resolveShiftedElements", () => {
+  it("maps each shift to its element and new start", () => {
+    const elements = [el("a", 0, 2), el("c", 8, 1)];
+    const resolved = resolveShiftedElements(elements, [{ key: "c", newStart: 2 }]);
+    expect(resolved).toEqual([{ element: elements[1], start: 2 }]);
+  });
+
+  it("resolves by key when present, falling back to id", () => {
+    const withKey: TimelineElement = { ...el("a", 0, 2), key: "a-key" };
+    const resolved = resolveShiftedElements([withKey], [{ key: "a-key", newStart: 5 }]);
+    expect(resolved).toEqual([{ element: withKey, start: 5 }]);
+  });
+
+  it("drops a shift whose key matches no element", () => {
+    const elements = [el("a", 0, 2)];
+    expect(resolveShiftedElements(elements, [{ key: "ghost", newStart: 0 }])).toEqual([]);
+  });
+});
+
 describe("canShiftTrackGapClips", () => {
   it("is true only when every named clip is movable", () => {
     const lane = [el("a", 1, 2), lockedEl("b", 5, 3)];
@@ -161,3 +182,78 @@ describe("canShiftTrackGapClips", () => {
     expect(canShiftTrackGapClips([el("a", 0, 1)], [{ key: "ghost", newStart: 0 }])).toBe(false);
   });
 });
+
+describe("resolveMainTrackDeleteRippleShifts", () => {
+  it("closes the gap left by a deleted main-track clip", () => {
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), el("c", 8, 1)]; // "b" already removed from this set
+    // "c" shifts left by exactly "b"'s 2s duration (8 -> 6), not all the way
+    // to 2: the 4-6..8 span was already an open gap before the delete, and
+    // ripple must not also swallow it.
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toEqual([
+      { key: "c", newStart: 6 },
+    ]);
+  });
+
+  it("does not also close a pre-existing gap the delete never touched", () => {
+    // a(0-2), b(2-4)[deleted], GAP(4-6), c(6-7): deleting b should slide c
+    // left by b's 2s only, landing at 4 — flush against a, the pre-existing
+    // gap collapsed only because it's now adjacent, not doubly-counted.
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), el("c", 6, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toEqual([
+      { key: "c", newStart: 4 },
+    ]);
+  });
+
+  it("leaves an untouched clip before the delete point exactly where it was", () => {
+    // a(0-2), GAP(2-5), b(5-7)[deleted]: nothing follows b, so nothing
+    // shifts — a keeps its own leading position, ripple included.
+    const deleted = [el("b", 5, 2)];
+    const survivors = [el("a", 0, 2)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toBeNull();
+  });
+
+  it("returns null when ripple is off", () => {
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), el("c", 8, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, false)).toBeNull();
+  });
+
+  it("returns null when nothing deleted was on the main track", () => {
+    const deletedOverlay = [el("o", 2, 2, 1)]; // track 1, not main
+    const survivors = [el("a", 0, 2), el("c", 8, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deletedOverlay, true)).toBeNull();
+  });
+
+  it("returns null when the survivors are already gapless", () => {
+    const deleted = [el("b", 100, 1)]; // deleted from far off the end
+    const survivors = [el("a", 0, 2), el("c", 2, 1)]; // already contiguous
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toBeNull();
+  });
+
+  it("refuses the whole ripple (not a partial one) when a shifting survivor is locked", () => {
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), lockedEl("c", 8, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toBeNull();
+  });
+
+  it("ignores audio and non-main-track survivors even when a main-track clip was deleted", () => {
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), el("c", 8, 1), el("overlay", 3, 1, 1)];
+    const shifts = resolveMainTrackDeleteRippleShifts(survivors, deleted, true);
+    expect(shifts).toEqual([{ key: "c", newStart: 6 }]); // "overlay" (track 1) untouched
+  });
+
+  it("sums only the deleted spans that precede each survivor, for a multi-select delete", () => {
+    // a(0-2), b(2-4)[deleted], c(4-6), d(6-8)[deleted], e(8-9): a marquee
+    // delete of b and d in one batch. "c" sits before d, so it shifts by
+    // b's 2s alone; "e" sits after both, so it shifts by their 4s combined.
+    const deleted = [el("b", 2, 2), el("d", 6, 2)];
+    const survivors = [el("a", 0, 2), el("c", 4, 2), el("e", 8, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toEqual([
+      { key: "c", newStart: 2 },
+      { key: "e", newStart: 4 },
+    ]);
+  });
+});

package/src/player/components/timelineGapCommit.ts

@@ -10,8 +10,11 @@ import {
   resolveAllTrackGaps,
   resolveCloseGapShifts,
   resolveTrackGapAt,
+  round3,
+  TRACK_GAP_EPSILON_S,
   type TrackGapShift,
 } from "./timelineGaps";
+import { isMainTrackElement } from "./timelineZones";
 
 /**
  * Commit layer for the track-gap context menu ("Close gap" / "Close all gaps").
@@ -35,16 +38,29 @@ const keyOf = (e: TimelineElement) => e.key ?? e.id;
 // timelineClipDragCommit.ts.
 let gapCloseGestureSeq = 0;
 
-/** True when every clip named in `shifts` may be time-moved. */
+/** Resolve each shift to its named element, dropping any shift whose key
+ *  matches nothing — the type stays honest without a non-null assertion. */
+export function resolveShiftedElements(
+  elements: readonly TimelineElement[],
+  shifts: readonly TrackGapShift[],
+): Array<{ element: TimelineElement; start: number }> {
+  const byKey = new Map(elements.map((e) => [keyOf(e), e]));
+  return shifts.flatMap((s) => {
+    const element = byKey.get(s.key);
+    return element ? [{ element, start: s.newStart }] : [];
+  });
+}
+
+/** True when every shift names a real clip that may be time-moved. */
 export function canShiftTrackGapClips(
   laneElements: readonly TimelineElement[],
   shifts: readonly TrackGapShift[],
 ): boolean {
-  const byKey = new Map(laneElements.map((e) => [keyOf(e), e]));
-  return shifts.every((s) => {
-    const element = byKey.get(s.key);
-    return element != null && getTimelineEditCapabilities(element).canMove;
-  });
+  const resolved = resolveShiftedElements(laneElements, shifts);
+  return (
+    resolved.length === shifts.length &&
+    resolved.every((r) => getTimelineEditCapabilities(r.element).canMove)
+  );
 }
 
 function buildShiftEdits(
@@ -52,11 +68,10 @@ function buildShiftEdits(
   shifts: readonly TrackGapShift[],
 ): TimelineMoveEdit[] | null {
   if (shifts.length === 0 || !canShiftTrackGapClips(laneElements, shifts)) return null;
-  const byKey = new Map(laneElements.map((e) => [keyOf(e), e]));
-  return shifts.map((s) => {
-    const element = byKey.get(s.key)!;
-    return { element, updates: { start: s.newStart, track: element.track } };
-  });
+  return resolveShiftedElements(laneElements, shifts).map(({ element, start }) => ({
+    element,
+    updates: { start, track: element.track },
+  }));
 }
 
 function commitShifts(
@@ -101,3 +116,33 @@ export function commitCloseAllTrackGaps(
     deps,
   );
 }
+
+/** What a ripple-edit delete must additionally shift on the main track. Pure
+ *  — no IO; the caller persists the shifts itself. Null means nothing to
+ *  ripple: off, nothing deleted was on the main track, already gapless, or a
+ *  shifting clip is locked (same whole-action refusal as the gap-close menu). */
+export function resolveMainTrackDeleteRippleShifts(
+  survivingElements: readonly TimelineElement[],
+  deletedElements: readonly TimelineElement[],
+  rippleEnabled: boolean,
+): TrackGapShift[] | null {
+  const deletedMainTrack = deletedElements.filter(isMainTrackElement);
+  if (!rippleEnabled || deletedMainTrack.length === 0) return null;
+  const survivors = survivingElements.filter(isMainTrackElement);
+  // Shift each survivor left by the duration of the deleted clips before it —
+  // the removed span itself, not a gap re-resolved on the survivors, which
+  // can't tell an untouched adjacent gap from the one just opened.
+  const shifts: TrackGapShift[] = [];
+  for (const survivor of survivors) {
+    const width = deletedMainTrack
+      .filter((d) => d.start < survivor.start)
+      .reduce((sum, d) => sum + d.duration, 0);
+    if (width <= 0) continue;
+    const newStart = round3(Math.max(laneGapFloor(survivors), survivor.start - width));
+    if (Math.abs(newStart - survivor.start) > TRACK_GAP_EPSILON_S) {
+      shifts.push({ key: keyOf(survivor), newStart });
+    }
+  }
+  if (shifts.length === 0 || !canShiftTrackGapClips(survivors, shifts)) return null;
+  return shifts;
+}

package/src/player/components/timelineGaps.ts

@@ -13,7 +13,7 @@ import type { TimelineElement } from "../store/playerStore";
  * - Computed starts are rounded to millisecond precision, matching the drag
  *   commit's `round3`.
  */
-const TRACK_GAP_EPSILON_S = 1e-3;
+export const TRACK_GAP_EPSILON_S = 1e-3;
 
 const keyOf = (e: TimelineElement) => e.key ?? e.id;
 
@@ -28,7 +28,7 @@ const keyOf = (e: TimelineElement) => e.key ?? e.id;
 export function laneGapFloor(elements: readonly TimelineElement[]): number {
   return Math.max(0, ...elements.map((e) => e.expandedParentStart ?? 0));
 }
-const round3 = (v: number) => Math.round(v * 1000) / 1000;
+export const round3 = (v: number) => Math.round(v * 1000) / 1000;
 const endOf = (e: TimelineElement) => e.start + e.duration;
 
 /** Lane clips sorted by start (key as a deterministic tie-break). */

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

@@ -217,7 +217,6 @@ describe("track-area breathing pad y-math", () => {
       scrollTop: 0,
       contentOrigin: GUTTER,
       pixelsPerSecond: 100,
-      duration: 60,
       rowHeights: baseRows(3),
       trackOrder: [0, 1, 2],
     };

package/src/player/components/timelineLayout.ts

@@ -568,8 +568,6 @@ export function resolveTimelineAssetDrop(
     scrollTop: number;
     contentOrigin: number;
     pixelsPerSecond: number;
-    duration: number;
-    clampStartToDuration?: boolean;
     rowHeights?: readonly number[];
     trackOrder: number[];
   },
@@ -584,10 +582,7 @@ export function resolveTimelineAssetDrop(
   });
   const contentY = clientY - input.rectTop + input.scrollTop;
   const pointerStart = Math.round((x / Math.max(input.pixelsPerSecond, 1)) * 100) / 100;
-  const start = Math.max(
-    0,
-    input.clampStartToDuration === false ? pointerStart : Math.min(input.duration, pointerStart),
-  );
+  const start = Math.max(0, pointerStart);
   // Row from the shared row→y inverse so the top pad is honoured; a drop in the
   // pad above the first lane floors to row 0, a drop in the bottom pad rounds
   // past the last lane (getDefaultDroppedTrack then appends a new track).

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
-import { classifyZone, normalizeToZones } from "./timelineZones";
+import { classifyZone, isMainTrackElement, normalizeToZones } from "./timelineZones";
 
 function el(id: string, tag: string, track: number, duration = 2): TimelineElement {
   return { id, tag, start: 0, duration, track };
@@ -55,6 +55,25 @@ describe("classifyZone", () => {
   });
 });
 
+describe("isMainTrackElement", () => {
+  it("is true for a visual clip on display track 0", () => {
+    expect(isMainTrackElement(el("v", "video", 0))).toBe(true);
+  });
+
+  it("is false for a visual clip on any other track", () => {
+    expect(isMainTrackElement(el("v", "video", 1))).toBe(false);
+  });
+
+  it("is false for an audio clip even on track 0 (audio-only project has no main track)", () => {
+    expect(isMainTrackElement(el("m", "audio", 0))).toBe(false);
+  });
+
+  it("is false for an inline-expanded sub-composition child on track 0", () => {
+    const child: TimelineElement = { ...el("c", "video", 0), expandedParentStart: 4 };
+    expect(isMainTrackElement(child)).toBe(false);
+  });
+});
+
 describe("normalizeToZones — CapCut-stable lanes follow the track-index (never z)", () => {
   it("orders visual lanes by authored track-index (ascending), audio at the bottom", () => {
     // img (track 0), vid (track 2), mus (audio, track 5). Lanes follow the track

package/src/player/components/timelineZones.ts

@@ -2,9 +2,9 @@ import type { TimelineElement } from "../store/playerStore";
 import { isAudioTimelineElement } from "../../utils/timelineInspector";
 
 /**
- * Free-form vertical zones, top → bottom: visual, audio. There is no "main track"
- * — canvas layering is CSS z-index (the renderer ignores track index), so the
- * timeline's only job is to keep visual clips grouped above audio clips.
+ * Free-form vertical zones, top → bottom: visual, audio. Canvas layering is
+ * CSS z-index (the renderer ignores track index), so a track's only structural
+ * job is to keep visual clips grouped above audio clips.
  */
 export type TrackZone = "visual" | "audio";
 
@@ -14,6 +14,13 @@ export function classifyZone(el: TimelineElement): TrackZone {
   return isAudioTimelineElement(el) ? "audio" : "visual";
 }
 
+/** The "main track" is a convention, not a schema field: the first
+ *  visual-zone display lane, matched only when it actually holds a visual
+ *  clip and isn't an inline-expanded sub-composition child. */
+export function isMainTrackElement(el: TimelineElement): boolean {
+  return el.track === 0 && classifyZone(el) === "visual" && el.expandedParentStart == null;
+}
+
 const keyOf = (el: TimelineElement) => el.key ?? el.id;
 
 const EPS = 1e-6;

package/src/player/components/useAutomationLaneGestures.ts

@@ -13,7 +13,7 @@
 
 import { useCallback, useRef, useState, type PointerEvent as ReactPointerEvent } from "react";
 import type { AutomationRange, HfAutomationLane } from "@hyperframes/core/audio-automation";
-import { curveForDrag, formatValue, GRAB_PX, POINT_MERGE_SEC } from "./automationLaneGeometry";
+import { curveForDrag, formatValue, GRAB_PX, mergeInsertPoint } from "./automationLaneGeometry";
 import { pointInSelection } from "./automationLaneSelection";
 import { capturePointer } from "./automationLanePointer";
 import { useAutomationEdgeStretch } from "./useAutomationEdgeStretch";
@@ -548,15 +548,7 @@ export function useAutomationLaneGestures({
         return;
       }
       const { t, v } = pointAt(e.clientX, e.clientY);
-      const kept = lane.points.filter((p) => Math.abs(p.t - t) > POINT_MERGE_SEC);
-      // A lane's first point alone would be a constant, which is not what
-      // clicking an empty lane means: seed the far end at the same value so the
-      // envelope has somewhere to go.
-      const seeded = lane.points.length === 0 && t > POINT_MERGE_SEC ? [{ t: 0, v }] : [];
-      commitPoints(
-        [...seeded, ...kept, { t, v }].sort((a, b) => a.t - b.t),
-        true,
-      );
+      commitPoints(mergeInsertPoint(lane.points, t, v), true);
     },
     [lane, pointAt, commitPoints, readOnly, hitIndex, segmentIndex],
   );

package/src/player/components/useTimelineTrackLayout.ts

@@ -1,7 +1,7 @@
 import { useMemo, useRef } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { animationLaneGroups } from "./TimelinePropertyLanes";
-import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { isAudioOrVideoTimelineElement } from "../../utils/timelineInspector";
 import { elementAutomationLanes, groupAutomationLanes } from "./automationLaneData";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { DraggedClipState } from "./timelineClipDragTypes";
@@ -44,14 +44,15 @@ export function trackShowsBeatStrip(
 }
 
 /**
- * Automation lanes on one clip, or 0 for anything that is not audio.
+ * Automation lanes on one clip.
  *
- * An audio clip can be worth expanding without carrying a single tween, so this
- * counts toward whether a track has anything to disclose. A function rather than
- * a map so every caller reads the same cached parse and none can drift.
+ * A clip can be worth expanding without carrying a single tween, so this counts
+ * toward whether a track has anything to disclose. Gated on
+ * `isAudioOrVideoTimelineElement`, matching `groupAutomationLanes`. A function
+ * rather than a map so every caller reads the same cached parse and none can drift.
  */
 function automationLaneCountOf(element: TimelineElement): number {
-  return isAudioTimelineElement(element) ? elementAutomationLanes(element).length : 0;
+  return isAudioOrVideoTimelineElement(element) ? elementAutomationLanes(element).length : 0;
 }
 
 /**

package/src/player/hooks/usePlaybackKeyboard.test.ts

@@ -1,4 +1,5 @@
 // @vitest-environment happy-dom
+// fallow-ignore-file code-duplication
 
 import React, { act, useEffect } from "react";
 import { createRoot } from "react-dom/client";
@@ -171,6 +172,39 @@ describe("usePlaybackKeyboard — keyboard layout independence (#834)", () => {
 
     expect(spies.play).toHaveBeenCalledTimes(1);
   });
+
+  it("'A' does not seek to the in-point while the razor tool is armed, so it's free for the razor's own return-to-select binding", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 1.5, activeTool: "razor" });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyA", key: "a" }));
+    });
+
+    expect(spies.seek).not.toHaveBeenCalled();
+  });
+
+  it("'A' still seeks to the in-point when the razor tool isn't armed", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 1.5, activeTool: "select" });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyA", key: "a" }));
+    });
+
+    expect(spies.seek).toHaveBeenCalledWith(1.5, { keepPlaying: true });
+  });
+
+  it("Shift+A still seeks to the in-point while the razor is armed, since only plain A exits the razor", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 1.5, activeTool: "razor" });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyA", key: "a", shiftKey: true }));
+    });
+
+    expect(spies.seek).toHaveBeenCalledWith(1.5, { keepPlaying: true });
+  });
 });
 
 describe("usePlaybackKeyboard — mute & loop shortcuts (#905)", () => {