@hyperframes/studio 0.5.0-alpha.1 → 0.5.0-alpha.10

package/src/player/components/PlayerControls.tsx

@@ -4,11 +4,18 @@ import {
   TIMELINE_TOGGLE_SHORTCUT_LABEL,
   getTimelineToggleTitle,
 } from "../../utils/timelineDiscovery";
-import { formatTime } from "../lib/time";
+import { formatFrameTime, frameToSeconds, formatTime } from "../lib/time";
 import { usePlayerStore, liveTime } from "../store/playerStore";
 
 const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
 const SEEK_EDGE_SNAP_PX = 8;
+type TimeDisplayMode = "time" | "frame";
+const SHORTCUT_HINTS = [
+  { key: "J", label: "Play backward" },
+  { key: "K", label: "Stop playback" },
+  { key: "L", label: "Play forward" },
+  { key: "←/→", label: "Step one frame backward or forward" },
+] as const;
 
 export function resolveSeekPercent(clientX: number, rectLeft: number, rectWidth: number): number {
   if (!Number.isFinite(rectWidth) || rectWidth <= 0) return 0;
@@ -38,8 +45,12 @@ export const PlayerControls = memo(function PlayerControls({
   const duration = usePlayerStore((s) => s.duration);
   const timelineReady = usePlayerStore((s) => s.timelineReady);
   const playbackRate = usePlayerStore((s) => s.playbackRate);
+  const loopEnabled = usePlayerStore((s) => s.loopEnabled);
   const setPlaybackRate = usePlayerStore.getState().setPlaybackRate;
+  const setLoopEnabled = usePlayerStore.getState().setLoopEnabled;
   const [showSpeedMenu, setShowSpeedMenu] = useState(false);
+  const [timeDisplayMode, setTimeDisplayMode] = useState<TimeDisplayMode>("time");
+  const [jumpFrame, setJumpFrame] = useState("");
 
   const progressFillRef = useRef<HTMLDivElement>(null);
   const progressThumbRef = useRef<HTMLDivElement>(null);
@@ -49,6 +60,8 @@ export const PlayerControls = memo(function PlayerControls({
   const speedMenuContainerRef = useRef<HTMLDivElement>(null);
   const isDraggingRef = useRef(false);
   const currentTimeRef = useRef(0);
+  const timeDisplayModeRef = useRef(timeDisplayMode);
+  timeDisplayModeRef.current = timeDisplayMode;
 
   const durationRef = useRef(duration);
   durationRef.current = duration;
@@ -59,7 +72,10 @@ export const PlayerControls = memo(function PlayerControls({
       const pct = dur > 0 ? Math.min(100, (t / dur) * 100) : 0;
       if (progressFillRef.current) progressFillRef.current.style.width = `${pct}%`;
       if (progressThumbRef.current) progressThumbRef.current.style.left = `${pct}%`;
-      if (timeDisplayRef.current) timeDisplayRef.current.textContent = formatTime(t);
+      if (timeDisplayRef.current) {
+        timeDisplayRef.current.textContent =
+          timeDisplayModeRef.current === "frame" ? formatFrameTime(t, dur) : formatTime(t);
+      }
       if (sliderRef.current) sliderRef.current.setAttribute("aria-valuenow", String(Math.round(t)));
     };
     const unsub = liveTime.subscribe(updateProgress);
@@ -82,6 +98,13 @@ export const PlayerControls = memo(function PlayerControls({
     };
   });
 
+  useEffect(() => {
+    if (!timeDisplayRef.current) return;
+    const t = currentTimeRef.current;
+    timeDisplayRef.current.textContent =
+      timeDisplayMode === "frame" ? formatFrameTime(t, duration) : formatTime(t);
+  }, [duration, timeDisplayMode]);
+
   useEffect(() => {
     if (!showSpeedMenu) return;
     const handleMouseDown = (e: MouseEvent) => {
@@ -190,21 +213,44 @@ export const PlayerControls = memo(function PlayerControls({
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
       if (!timelineReady || duration <= 0) return;
-      const step = e.shiftKey ? 5 : 1;
+      const step = e.shiftKey ? 10 : 1;
       if (e.key === "ArrowLeft") {
         e.preventDefault();
-        onSeek(Math.max(0, currentTimeRef.current - step));
+        onSeek(Math.max(0, currentTimeRef.current - frameToSeconds(step)));
       } else if (e.key === "ArrowRight") {
         e.preventDefault();
-        onSeek(Math.min(duration, currentTimeRef.current + step));
+        onSeek(Math.min(duration, currentTimeRef.current + frameToSeconds(step)));
       }
     },
     [timelineReady, duration, onSeek],
   );
 
+  const commitJumpFrame = useCallback(() => {
+    const frame = Number.parseInt(jumpFrame, 10);
+    if (!Number.isFinite(frame) || duration <= 0) return;
+    onSeek(Math.min(duration, frameToSeconds(Math.max(0, frame))));
+  }, [duration, jumpFrame, onSeek]);
+
+  const handleJumpSubmit = useCallback(
+    (e: React.FormEvent) => {
+      e.preventDefault();
+      commitJumpFrame();
+    },
+    [commitJumpFrame],
+  );
+
+  const handleJumpKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (e.key !== "Enter") return;
+      e.preventDefault();
+      commitJumpFrame();
+    },
+    [commitJumpFrame],
+  );
+
   return (
     <div
-      className="px-4 py-2 flex items-center gap-3"
+      className="px-4 py-2 flex flex-wrap items-center gap-x-2 gap-y-1"
       style={{
         borderTop: "1px solid rgba(255,255,255,0.04)",
         // Add iOS safe-area inset so Safari's bottom URL bar doesn't occlude
@@ -236,12 +282,16 @@ export const PlayerControls = memo(function PlayerControls({
 
       {/* Time display */}
       <span
-        className="font-mono text-[11px] tabular-nums flex-shrink-0 min-w-[72px]"
+        className="font-mono text-[11px] tabular-nums flex-shrink-0 w-[118px]"
         style={{ color: "#A1A1AA" }}
       >
         <span ref={timeDisplayRef}>{formatTime(0)}</span>
-        <span style={{ color: "#3F3F46", margin: "0 2px" }}>/</span>
-        <span style={{ color: "#52525B" }}>{formatTime(duration)}</span>
+        {timeDisplayMode === "time" ? (
+          <>
+            <span style={{ color: "#3F3F46", margin: "0 2px" }}>/</span>
+            <span style={{ color: "#52525B" }}>{formatTime(duration)}</span>
+          </>
+        ) : null}
       </span>
 
       {/* Seek bar — teal progress fill */}
@@ -256,7 +306,7 @@ export const PlayerControls = memo(function PlayerControls({
         aria-valuemin={0}
         aria-valuemax={Math.round(duration)}
         aria-valuenow={0}
-        className="flex-1 h-6 flex items-center cursor-pointer group"
+        className="min-w-[96px] flex-1 h-6 flex items-center cursor-pointer group"
         // `touch-action: none` tells the browser we're handling every
         // pointer gesture on this element ourselves. Without it, iOS
         // Safari consumes horizontal swipes for its own swipe-back-to-
@@ -292,7 +342,7 @@ export const PlayerControls = memo(function PlayerControls({
         <button
           type="button"
           onClick={() => setShowSpeedMenu((v) => !v)}
-          className="px-2 py-1 rounded-md text-[10px] font-mono tabular-nums transition-colors"
+          className="w-10 px-2 py-1 rounded-md text-[10px] font-mono tabular-nums transition-colors"
           style={{ color: "#71717A", background: "rgba(255,255,255,0.04)" }}
         >
           {playbackRate === 1 ? "1x" : `${playbackRate}x`}
@@ -329,6 +379,65 @@ export const PlayerControls = memo(function PlayerControls({
         )}
       </div>
 
+      <button
+        type="button"
+        onClick={() => setLoopEnabled(!loopEnabled)}
+        className={`h-7 w-14 rounded-md border px-2 text-[10px] font-medium transition-colors ${
+          loopEnabled
+            ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
+            : "border-neutral-700 text-neutral-400 hover:border-neutral-500 hover:bg-neutral-800"
+        }`}
+        title="Loop playback"
+        aria-label={loopEnabled ? "Disable loop playback" : "Enable loop playback"}
+        aria-pressed={loopEnabled}
+      >
+        Loop
+      </button>
+
+      <button
+        type="button"
+        onClick={() => setTimeDisplayMode((mode) => (mode === "time" ? "frame" : "time"))}
+        className="h-7 w-14 rounded-md border border-neutral-700 px-2 text-[10px] font-mono text-neutral-300 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
+        title="Toggle time/frame display"
+        aria-label="Toggle time and frame display"
+      >
+        {timeDisplayMode === "time" ? "m:ss" : "frames"}
+      </button>
+
+      <form
+        onSubmit={handleJumpSubmit}
+        className="hidden sm:flex flex-shrink-0 w-[58px] items-center"
+      >
+        <input
+          value={jumpFrame}
+          onChange={(e) => setJumpFrame(e.target.value)}
+          inputMode="numeric"
+          pattern="[0-9]*"
+          aria-label="Jump to frame"
+          placeholder="frame"
+          className="h-7 w-[58px] rounded-md border border-neutral-700 bg-neutral-900 px-2 text-[10px] font-mono tabular-nums text-neutral-200 outline-none transition-colors placeholder:text-neutral-600 focus:border-studio-accent/60"
+          onKeyDown={handleJumpKeyDown}
+          onBlur={commitJumpFrame}
+        />
+      </form>
+
+      <div
+        className="hidden lg:flex items-center gap-1 text-[9px] font-mono text-neutral-500"
+        aria-label="Playback shortcuts: J backward, K stop, L forward, arrows step one frame"
+      >
+        {SHORTCUT_HINTS.map((shortcut) => (
+          <span
+            key={shortcut.key}
+            className="group relative rounded border border-neutral-800 px-1 py-0.5"
+          >
+            {shortcut.key}
+            <span className="pointer-events-none absolute bottom-full left-1/2 z-50 mb-1.5 hidden -translate-x-1/2 whitespace-nowrap rounded-md border border-neutral-700 bg-neutral-950 px-2 py-1 font-sans text-[10px] text-neutral-200 shadow-lg group-hover:block">
+              {shortcut.label}
+            </span>
+          </span>
+        ))}
+      </div>
+
       {/* Timeline toggle */}
       {onToggleTimeline !== undefined && (
         <button

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

@@ -1,11 +1,14 @@
 import { describe, it, expect } from "vitest";
 import {
+  formatTimelineTickLabel,
   generateTicks,
   getDefaultDroppedTrack,
   getTimelineCanvasHeight,
   resolveTimelineAssetDrop,
   getTimelinePlayheadLeft,
+  getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
+  shouldShowTimelineShortcutHint,
   shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
 } from "./Timeline";
@@ -78,6 +81,20 @@ describe("generateTicks", () => {
       expect(major[0]).toBe(0);
     }
   });
+
+  it("uses denser major labels as timeline zoom increases", () => {
+    const fitTicks = generateTicks(180, 10);
+    const zoomedTicks = generateTicks(180, 48);
+    expect(fitTicks.major[1] - fitTicks.major[0]).toBe(15);
+    expect(zoomedTicks.major[1] - zoomedTicks.major[0]).toBe(5);
+    expect(zoomedTicks.minor).toContain(1);
+    expect(zoomedTicks.minor).toContain(4);
+  });
+
+  it("keeps labels readable instead of placing one at every tiny tick", () => {
+    const { major } = generateTicks(180, 80);
+    expect(major[1] - major[0]).toBe(2);
+  });
 });
 
 describe("formatTime", () => {
@@ -118,6 +135,20 @@ describe("formatTime", () => {
   });
 });
 
+describe("formatTimelineTickLabel", () => {
+  it("uses minute-second labels for normal timeline intervals", () => {
+    expect(formatTimelineTickLabel(90, 180, 5)).toBe("1:30");
+  });
+
+  it("uses hour labels for long timelines", () => {
+    expect(formatTimelineTickLabel(3661, 4000, 60)).toBe("1:01:01");
+  });
+
+  it("shows subsecond labels when the major ruler interval is below one second", () => {
+    expect(formatTimelineTickLabel(1.5, 3, 0.5)).toBe("0:01.5");
+  });
+});
+
 describe("shouldAutoScrollTimeline", () => {
   it("never auto-scrolls in fit mode", () => {
     expect(shouldAutoScrollTimeline("fit", 1200, 800)).toBe(false);
@@ -144,6 +175,48 @@ describe("getTimelineScrollLeftForZoomTransition", () => {
     expect(getTimelineScrollLeftForZoomTransition("manual", "manual", 480)).toBe(480);
   });
 });
+
+describe("getTimelineScrollLeftForZoomAnchor", () => {
+  it("preserves the time under the pointer when zooming in", () => {
+    expect(
+      getTimelineScrollLeftForZoomAnchor({
+        pointerX: 300,
+        currentScrollLeft: 200,
+        gutter: 32,
+        currentPixelsPerSecond: 10,
+        nextPixelsPerSecond: 20,
+        duration: 120,
+      }),
+    ).toBe(668);
+  });
+
+  it("clamps negative scroll targets", () => {
+    expect(
+      getTimelineScrollLeftForZoomAnchor({
+        pointerX: 300,
+        currentScrollLeft: 0,
+        gutter: 32,
+        currentPixelsPerSecond: 20,
+        nextPixelsPerSecond: 5,
+        duration: 120,
+      }),
+    ).toBe(0);
+  });
+
+  it("preserves current scroll when inputs are invalid", () => {
+    expect(
+      getTimelineScrollLeftForZoomAnchor({
+        pointerX: 300,
+        currentScrollLeft: 120,
+        gutter: 32,
+        currentPixelsPerSecond: 0,
+        nextPixelsPerSecond: 20,
+        duration: 120,
+      }),
+    ).toBe(120);
+  });
+});
+
 describe("getTimelinePlayheadLeft", () => {
   it("converts time to a pixel offset from the gutter", () => {
     expect(getTimelinePlayheadLeft(4, 20)).toBe(112);
@@ -165,6 +238,17 @@ describe("getTimelineCanvasHeight", () => {
   });
 });
 
+describe("shouldShowTimelineShortcutHint", () => {
+  it("shows the hint when the timeline does not vertically overflow", () => {
+    expect(shouldShowTimelineShortcutHint(220, 220)).toBe(true);
+    expect(shouldShowTimelineShortcutHint(220.5, 220)).toBe(true);
+  });
+
+  it("hides the hint when timeline tracks need vertical scrolling", () => {
+    expect(shouldShowTimelineShortcutHint(221.5, 220)).toBe(false);
+  });
+});
+
 describe("shouldHandleTimelineDeleteKey", () => {
   it("handles Delete and Backspace when focus is not in an editor", () => {
     expect(shouldHandleTimelineDeleteKey({ key: "Delete" })).toBe(true);

package/src/player/components/Timeline.tsx

@@ -26,7 +26,7 @@ import {
   type TimelineTrackStyle,
   type TimelineTheme,
 } from "./timelineTheme";
-import { getTimelinePixelsPerSecond } from "./timelineZoom";
+import { getPinchTimelineZoomPercent, getTimelinePixelsPerSecond } from "./timelineZoom";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
 
 /* ── Layout ─────────────────────────────────────────────────────── */
@@ -35,7 +35,7 @@ const TRACK_H = 72;
 const RULER_H = 24;
 const CLIP_Y = 3; // vertical inset inside track
 const CLIP_HANDLE_W = 18;
-const TIMELINE_SCROLL_BUFFER = 24;
+const TIMELINE_SCROLL_BUFFER = 20;
 
 interface TrackVisualStyle extends TimelineTrackStyle {
   icon: ReactNode;
@@ -88,16 +88,47 @@ function getStyle(tag: string): TrackVisualStyle {
 }
 
 /* ── Tick Generation ────────────────────────────────────────────── */
-export function generateTicks(duration: number): { major: number[]; minor: number[] } {
+function getMajorTickInterval(duration: number, pixelsPerSecond?: number): number {
+  const zoomIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600];
+  if (Number.isFinite(pixelsPerSecond) && (pixelsPerSecond ?? 0) > 0) {
+    const targetMajorPx = 128;
+    return (
+      zoomIntervals.find((interval) => interval * (pixelsPerSecond ?? 0) >= targetMajorPx) ?? 600
+    );
+  }
+  const durationIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
+  const target = duration / 6;
+  return durationIntervals.find((interval) => interval >= target) ?? 60;
+}
+
+function getMinorTickInterval(majorInterval: number, pixelsPerSecond?: number): number {
+  let interval = majorInterval / 2;
+  if (majorInterval >= 30) interval = majorInterval / 6;
+  else if (majorInterval >= 15) interval = majorInterval / 3;
+  else if (majorInterval >= 5) interval = majorInterval / 5;
+  else if (majorInterval >= 1) interval = majorInterval / 4;
+
+  if (
+    Number.isFinite(pixelsPerSecond) &&
+    (pixelsPerSecond ?? 0) > 0 &&
+    interval * (pixelsPerSecond ?? 0) < 20
+  ) {
+    return Math.max(0.25, majorInterval / 2);
+  }
+  return Math.max(0.25, interval);
+}
+
+export function generateTicks(
+  duration: number,
+  pixelsPerSecond?: number,
+): { major: number[]; minor: number[] } {
   if (duration <= 0 || !Number.isFinite(duration) || duration > 7200)
     return { major: [], minor: [] };
-  const intervals = [0.5, 1, 2, 5, 10, 15, 30, 60];
-  const target = duration / 6;
-  const majorInterval = intervals.find((i) => i >= target) ?? 60;
-  const minorInterval = Math.max(0.25, majorInterval / 2);
+  const majorInterval = getMajorTickInterval(duration, pixelsPerSecond);
+  const minorInterval = getMinorTickInterval(majorInterval, pixelsPerSecond);
   const major: number[] = [];
   const minor: number[] = [];
-  const maxTicks = 500; // Safety cap to prevent infinite loop
+  const maxTicks = 2000; // Safety cap to prevent runaway tick generation
   for (
     let t = 0;
     t <= duration + 0.001 && major.length + minor.length < maxTicks;
@@ -113,6 +144,25 @@ export function generateTicks(duration: number): { major: number[]; minor: numbe
   return { major, minor };
 }
 
+export function formatTimelineTickLabel(time: number, duration: number, majorInterval: number) {
+  if (!Number.isFinite(time)) return "0:00";
+  const safeTime = Math.max(0, time);
+  if (majorInterval < 1) {
+    const totalTenths = Math.round(safeTime * 10);
+    const wholeSeconds = Math.floor(totalTenths / 10);
+    const tenth = totalTenths % 10;
+    return `${formatTime(wholeSeconds)}.${tenth}`;
+  }
+  if (duration >= 3600 || safeTime >= 3600) {
+    const totalSeconds = Math.floor(safeTime);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
+  }
+  return formatTime(safeTime);
+}
+
 export function shouldAutoScrollTimeline(
   zoomMode: ZoomMode,
   scrollWidth: number,
@@ -131,6 +181,32 @@ export function getTimelineScrollLeftForZoomTransition(
   if (previousZoomMode === "manual" && nextZoomMode === "fit") return 0;
   return currentScrollLeft;
 }
+
+export function getTimelineScrollLeftForZoomAnchor(input: {
+  pointerX: number;
+  currentScrollLeft: number;
+  gutter: number;
+  currentPixelsPerSecond: number;
+  nextPixelsPerSecond: number;
+  duration: number;
+}): number {
+  const currentPps = Math.max(0, input.currentPixelsPerSecond);
+  const nextPps = Math.max(0, input.nextPixelsPerSecond);
+  if (
+    !Number.isFinite(input.pointerX) ||
+    !Number.isFinite(input.currentScrollLeft) ||
+    !Number.isFinite(input.duration) ||
+    input.duration <= 0 ||
+    currentPps <= 0 ||
+    nextPps <= 0
+  ) {
+    return Math.max(0, input.currentScrollLeft);
+  }
+  const timelineX = Math.max(0, input.currentScrollLeft + input.pointerX - input.gutter);
+  const timeAtPointer = Math.max(0, Math.min(input.duration, timelineX / currentPps));
+  return Math.max(0, input.gutter + timeAtPointer * nextPps - input.pointerX);
+}
+
 export function getTimelinePlayheadLeft(time: number, pixelsPerSecond: number): number {
   if (!Number.isFinite(time) || !Number.isFinite(pixelsPerSecond)) return GUTTER;
   return GUTTER + Math.max(0, time) * Math.max(0, pixelsPerSecond);
@@ -140,6 +216,14 @@ export function getTimelineCanvasHeight(trackCount: number): number {
   return RULER_H + Math.max(0, trackCount) * TRACK_H + TIMELINE_SCROLL_BUFFER;
 }
 
+export function shouldShowTimelineShortcutHint(
+  scrollHeight: number,
+  clientHeight: number,
+): boolean {
+  if (!Number.isFinite(scrollHeight) || !Number.isFinite(clientHeight)) return true;
+  return scrollHeight - clientHeight <= 1;
+}
+
 export function shouldHandleTimelineDeleteKey(input: {
   key: string;
   metaKey?: boolean;
@@ -304,6 +388,8 @@ export const Timeline = memo(function Timeline({
   const currentTime = usePlayerStore((s) => s.currentTime);
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
+  const setZoomMode = usePlayerStore((s) => s.setZoomMode);
+  const setManualZoomPercent = usePlayerStore((s) => s.setManualZoomPercent);
   const playheadRef = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
@@ -348,30 +434,51 @@ export const Timeline = memo(function Timeline({
   onDeleteElementRef.current = onDeleteElement;
   const suppressClickRef = useRef(false);
   const [showPopover, setShowPopover] = useState(false);
+  const [showShortcutHint, setShowShortcutHint] = useState(true);
   const [viewportWidth, setViewportWidth] = useState(0);
   const roRef = useRef<ResizeObserver | null>(null);
+  const shortcutHintRafRef = useRef(0);
+  const syncShortcutHintVisibility = useCallback(() => {
+    const scroll = scrollRef.current;
+    setShowShortcutHint(
+      scroll ? shouldShowTimelineShortcutHint(scroll.scrollHeight, scroll.clientHeight) : true,
+    );
+  }, []);
+  const scheduleShortcutHintVisibilitySync = useCallback(() => {
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+    shortcutHintRafRef.current = requestAnimationFrame(() => {
+      shortcutHintRafRef.current = 0;
+      syncShortcutHintVisibility();
+    });
+  }, [syncShortcutHintVisibility]);
 
   // Callback ref: sets up ResizeObserver when the DOM element actually mounts.
   // useMountEffect can't work here because the component returns null on first
   // render (timelineReady=false), so containerRef.current is null when the
   // effect fires and the ResizeObserver is never created.
-  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
-    if (roRef.current) {
-      roRef.current.disconnect();
-      roRef.current = null;
-    }
-    containerRef.current = el;
-    if (!el) return;
-    setViewportWidth(el.clientWidth);
-    roRef.current = new ResizeObserver(([entry]) => {
-      setViewportWidth(entry.contentRect.width);
-    });
-    roRef.current.observe(el);
-  }, []);
+  const setContainerRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+      containerRef.current = el;
+      if (!el) return;
+      setViewportWidth(el.clientWidth);
+      scheduleShortcutHintVisibilitySync();
+      roRef.current = new ResizeObserver(([entry]) => {
+        setViewportWidth(entry.contentRect.width);
+        scheduleShortcutHintVisibilitySync();
+      });
+      roRef.current.observe(el);
+    },
+    [scheduleShortcutHintVisibilitySync],
+  );
 
   // Clean up ResizeObserver on unmount
   useMountEffect(() => () => {
     roRef.current?.disconnect();
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
   });
 
   // Effective duration: max of store duration and the furthest element end.
@@ -416,6 +523,7 @@ export const Timeline = memo(function Timeline({
     }
     return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
   }, [draggedClip, trackOrder]);
+  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const selectedElement = useMemo(
     () => elements.find((element) => (element.key ?? element.id) === selectedElementId) ?? null,
     [elements, selectedElementId],
@@ -433,7 +541,11 @@ export const Timeline = memo(function Timeline({
   const trackContentWidth = Math.max(0, effectiveDuration * pps);
   const zoomModeRef = useRef(zoomMode);
   zoomModeRef.current = zoomMode;
+  const manualZoomPercentRef = useRef(manualZoomPercent);
+  manualZoomPercentRef.current = manualZoomPercent;
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
+  const fitPpsRef = useRef(fitPps);
+  fitPpsRef.current = fitPps;
 
   const durationRef = useRef(effectiveDuration);
   durationRef.current = effectiveDuration;
@@ -922,7 +1034,16 @@ export const Timeline = memo(function Timeline({
     cancelAnimationFrame(dragScrollRaf.current);
   }, []);
 
-  const { major, minor } = useMemo(() => generateTicks(effectiveDuration), [effectiveDuration]);
+  const { major, minor } = useMemo(
+    () => generateTicks(effectiveDuration, pps),
+    [effectiveDuration, pps],
+  );
+  const majorTickInterval =
+    major.length >= 2 ? Math.max(0.25, major[1] - major[0]) : effectiveDuration;
+  useEffect(() => {
+    syncShortcutHintVisibility();
+  }, [syncShortcutHintVisibility, timelineReady, elements.length, totalH]);
+
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => {
       if (resizingClip?.element.id === element.id) {
@@ -1008,6 +1129,57 @@ export const Timeline = memo(function Timeline({
     [onAssetDrop, onFileDrop],
   );
 
+  const handlePinchWheel = useCallback(
+    (e: WheelEvent) => {
+      if (!e.ctrlKey) return;
+      const scroll = scrollRef.current;
+      if (!scroll || durationRef.current <= 0 || fitPpsRef.current <= 0 || ppsRef.current <= 0) {
+        return;
+      }
+
+      e.preventDefault();
+      e.stopPropagation();
+
+      const rect = scroll.getBoundingClientRect();
+      const pointerX = e.clientX - rect.left;
+      const nextZoomPercent = getPinchTimelineZoomPercent(
+        e.deltaY,
+        zoomModeRef.current,
+        manualZoomPercentRef.current,
+      );
+      if (nextZoomPercent === manualZoomPercentRef.current && zoomModeRef.current === "manual") {
+        return;
+      }
+
+      const nextPps = fitPpsRef.current * (nextZoomPercent / 100);
+      const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
+        pointerX,
+        currentScrollLeft: scroll.scrollLeft,
+        gutter: GUTTER,
+        currentPixelsPerSecond: ppsRef.current,
+        nextPixelsPerSecond: nextPps,
+        duration: durationRef.current,
+      });
+
+      setZoomMode("manual");
+      setManualZoomPercent(nextZoomPercent);
+      requestAnimationFrame(() => {
+        const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+        scroll.scrollLeft = Math.min(maxScrollLeft, nextScrollLeft);
+      });
+    },
+    [setManualZoomPercent, setZoomMode],
+  );
+
+  useEffect(() => {
+    const scroll = scrollRef.current;
+    if (!scroll) return;
+    scroll.addEventListener("wheel", handlePinchWheel, { passive: false, capture: true });
+    return () => {
+      scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
+    };
+  }, [handlePinchWheel, timelineReady, elements.length]);
+
   if (!timelineReady || elements.length === 0) {
     return (
       <div
@@ -1096,7 +1268,6 @@ export const Timeline = memo(function Timeline({
     );
   }
 
-  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const draggedElement = draggedClip?.element ?? null;
   const activeDraggedElement =
     draggedClip?.started === true && draggedElement
@@ -1170,7 +1341,7 @@ export const Timeline = memo(function Timeline({
     <div
       ref={setContainerRef}
       aria-label="Timeline"
-      className={`border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
+      className={`relative border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
       style={{
         touchAction: "pan-x pan-y",
         background: theme.shellBackground,
@@ -1239,7 +1410,7 @@ export const Timeline = memo(function Timeline({
                   className="text-[9px] font-mono tabular-nums leading-none mb-0.5"
                   style={{ color: theme.tickText }}
                 >
-                  {formatTime(t)}
+                  {formatTimelineTickLabel(t, effectiveDuration, majorTickInterval)}
                 </span>
                 <div className="w-px h-[5px]" style={{ background: theme.tickMajor }} />
               </div>
@@ -1509,8 +1680,8 @@ export const Timeline = memo(function Timeline({
         </div>
       </div>
 
-      {/* Keyboard shortcut hint — always visible */}
-      {!showPopover && !rangeSelection && (
+      {/* Keyboard shortcut hint */}
+      {showShortcutHint && !showPopover && !rangeSelection && (
         <div className="absolute bottom-2 right-3 pointer-events-none z-20">
           <div
             className="flex items-center gap-1.5 px-2 py-1 rounded-md border"