@hyperframes/studio 0.7.54 → 0.7.55

package/src/utils/canvasNudgeGate.test.ts

@@ -0,0 +1,31 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { __resetForTests, acquireCanvasNudgeKeys, canvasNudgeKeysClaimed } from "./canvasNudgeGate";
+
+describe("canvasNudgeGate", () => {
+  // The claim counter is module-level state; reset it so an unbalanced claim in one
+  // test can't leak into the next.
+  beforeEach(() => {
+    __resetForTests();
+  });
+
+  it("reports claimed while at least one claim is held", () => {
+    expect(canvasNudgeKeysClaimed()).toBe(false);
+    const releaseA = acquireCanvasNudgeKeys();
+    const releaseB = acquireCanvasNudgeKeys();
+    expect(canvasNudgeKeysClaimed()).toBe(true);
+    releaseA();
+    expect(canvasNudgeKeysClaimed()).toBe(true);
+    releaseB();
+    expect(canvasNudgeKeysClaimed()).toBe(false);
+  });
+
+  it("makes release idempotent so an effect re-run cannot underflow", () => {
+    const release = acquireCanvasNudgeKeys();
+    release();
+    release();
+    expect(canvasNudgeKeysClaimed()).toBe(false);
+    const releaseNext = acquireCanvasNudgeKeys();
+    expect(canvasNudgeKeysClaimed()).toBe(true);
+    releaseNext();
+  });
+});

package/src/utils/canvasNudgeGate.ts

@@ -0,0 +1,32 @@
+/**
+ * Arrow-key ownership gate between the canvas nudge (DomEditOverlay) and the
+ * playback frame-step shortcuts (usePlaybackKeyboard). Both listen for arrow
+ * keys with window capture listeners, and their relative order depends on
+ * mount order (DomEditOverlay remounts when caption edit mode toggles), so
+ * `event.defaultPrevented` alone can't arbitrate. While a nudgeable canvas
+ * selection holds a claim, the playback handler skips ArrowLeft/ArrowRight.
+ */
+
+let claims = 0;
+
+/** Claim the arrow keys for canvas nudging. Returns an idempotent release. */
+export function acquireCanvasNudgeKeys(): () => void {
+  claims += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    claims -= 1;
+  };
+}
+
+/** True while a nudgeable canvas selection owns the arrow keys. */
+export function canvasNudgeKeysClaimed(): boolean {
+  return claims > 0;
+}
+
+/** Test-only: reset the module-level claim counter so leaked claims from one test
+ *  can't bleed into the next (call in a `beforeEach`). */
+export function __resetForTests(): void {
+  claims = 0;
+}

package/src/utils/studioUiPreferences.test.ts

@@ -50,3 +50,41 @@ describe("studio UI preferences", () => {
     });
   });
 });
+
+describe("timelineSnapEnabled preference", () => {
+  it("round-trips through storage", () => {
+    const storage = createStorage();
+    writeStudioUiPreferences({ timelineSnapEnabled: false }, storage);
+    expect(readStudioUiPreferences(storage).timelineSnapEnabled).toBe(false);
+  });
+
+  it("ignores non-boolean values", () => {
+    const storage = createStorage();
+    storage.setItem("hf-studio-ui-preferences", JSON.stringify({ timelineSnapEnabled: "yes" }));
+    expect(readStudioUiPreferences(storage).timelineSnapEnabled).toBeUndefined();
+  });
+});
+
+describe("timeline zoom pin persistence", () => {
+  it("round-trips a pinned manual zoom (survives the post-edit reload)", () => {
+    const storage = createStorage();
+    writeStudioUiPreferences(
+      { timelineZoomMode: "manual", timelineManualZoomPercent: 250 },
+      storage,
+    );
+    const prefs = readStudioUiPreferences(storage);
+    expect(prefs.timelineZoomMode).toBe("manual");
+    expect(prefs.timelineManualZoomPercent).toBe(250);
+  });
+
+  it("ignores an invalid zoom mode and a non-finite percent", () => {
+    const storage = createStorage();
+    storage.setItem(
+      "hf-studio-ui-preferences",
+      JSON.stringify({ timelineZoomMode: "zoomy", timelineManualZoomPercent: "big" }),
+    );
+    const prefs = readStudioUiPreferences(storage);
+    expect(prefs.timelineZoomMode).toBeUndefined();
+    expect(prefs.timelineManualZoomPercent).toBeUndefined();
+  });
+});

package/src/utils/studioUiPreferences.ts

@@ -16,6 +16,18 @@ export interface StudioUiPreferences {
   gridVisible?: boolean;
   gridSpacing?: number;
   snapToGrid?: boolean;
+  /** Timeline magnet: snap clip drags/trims/drops to playhead, clip edges, and beats. */
+  timelineSnapEnabled?: boolean;
+  /** Transport + ruler readout mode: timecode or frame number. */
+  timeDisplayMode?: "time" | "frame";
+  /**
+   * Timeline zoom mode. Persisted so a zoom PINNED on the first edit survives the
+   * post-edit iframe reload — otherwise the store reset to "fit" and the duration
+   * change rescaled every clip (the blink-fix's rescale symptom).
+   */
+  timelineZoomMode?: "fit" | "manual";
+  /** Manual timeline zoom percent, paired with `timelineZoomMode: "manual"`. */
+  timelineManualZoomPercent?: number;
 }
 
 const STUDIO_UI_PREFERENCES_KEY = "hf-studio-ui-preferences";
@@ -88,6 +100,21 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.snapToGrid === "boolean") {
       preferences.snapToGrid = parsed.snapToGrid;
     }
+    if (typeof parsed.timelineSnapEnabled === "boolean") {
+      preferences.timelineSnapEnabled = parsed.timelineSnapEnabled;
+    }
+    if (parsed.timeDisplayMode === "time" || parsed.timeDisplayMode === "frame") {
+      preferences.timeDisplayMode = parsed.timeDisplayMode;
+    }
+    if (parsed.timelineZoomMode === "fit" || parsed.timelineZoomMode === "manual") {
+      preferences.timelineZoomMode = parsed.timelineZoomMode;
+    }
+    if (
+      typeof parsed.timelineManualZoomPercent === "number" &&
+      Number.isFinite(parsed.timelineManualZoomPercent)
+    ) {
+      preferences.timelineManualZoomPercent = parsed.timelineManualZoomPercent;
+    }
     return preferences;
   } catch {
     return {};

package/src/utils/timelineInspector.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { isAudioTimelineElement, isMusicTrack, resolveBeatSourceTrack } from "./timelineInspector";
+import type { TimelineElement } from "../player";
+
+// Minimal element factory for tests
+function el(
+  overrides: Partial<
+    Pick<TimelineElement, "tag" | "src" | "id" | "domId" | "timelineRole" | "duration">
+  >,
+): Pick<TimelineElement, "tag" | "src" | "id" | "domId" | "timelineRole" | "duration"> {
+  return {
+    tag: "audio",
+    src: "assets/track.mp3",
+    id: "el-1",
+    domId: "el-1",
+    timelineRole: undefined,
+    duration: 10,
+    ...overrides,
+  };
+}
+
+describe("isAudioTimelineElement", () => {
+  it("is true for audio tag", () => {
+    expect(isAudioTimelineElement(el({ tag: "audio" }))).toBe(true);
+  });
+
+  it("is true for music/sfx/narration semantic tags", () => {
+    expect(isAudioTimelineElement(el({ tag: "music" }))).toBe(true);
+    expect(isAudioTimelineElement(el({ tag: "sfx" }))).toBe(true);
+    expect(isAudioTimelineElement(el({ tag: "narration" }))).toBe(true);
+  });
+
+  it("is true for img/div with an audio src extension", () => {
+    expect(isAudioTimelineElement(el({ tag: "div", src: "assets/bg.mp3" }))).toBe(true);
+    expect(isAudioTimelineElement(el({ tag: "div", src: "assets/fx.wav" }))).toBe(true);
+  });
+
+  it("is false for video and image elements", () => {
+    expect(isAudioTimelineElement(el({ tag: "video", src: "assets/clip.mp4" }))).toBe(false);
+    expect(isAudioTimelineElement(el({ tag: "img", src: "assets/logo.svg" }))).toBe(false);
+  });
+
+  it("returns false for null/undefined", () => {
+    expect(isAudioTimelineElement(null)).toBe(false);
+    expect(isAudioTimelineElement(undefined)).toBe(false);
+  });
+});
+
+describe("isMusicTrack", () => {
+  it("is true when timelineRole is 'music'", () => {
+    expect(isMusicTrack(el({ timelineRole: "music" }))).toBe(true);
+  });
+
+  it("is false for explicit non-music roles", () => {
+    expect(isMusicTrack(el({ timelineRole: "sfx" }))).toBe(false);
+    expect(isMusicTrack(el({ timelineRole: "voiceover" }))).toBe(false);
+  });
+
+  it("matches music-like ids when no role is set", () => {
+    expect(isMusicTrack(el({ domId: "bgm", timelineRole: undefined }))).toBe(true);
+    expect(isMusicTrack(el({ domId: "background_music", timelineRole: undefined }))).toBe(true);
+    expect(isMusicTrack(el({ domId: "soundtrack", timelineRole: undefined }))).toBe(true);
+  });
+
+  it("is false for generic ids with no role", () => {
+    expect(isMusicTrack(el({ domId: "my_audio_file", timelineRole: undefined }))).toBe(false);
+    expect(isMusicTrack(el({ domId: "drop_1", timelineRole: undefined }))).toBe(false);
+  });
+
+  it("is false for non-audio elements even with a music-like id", () => {
+    expect(isMusicTrack(el({ tag: "img", src: "assets/logo.svg", domId: "bgm" }))).toBe(false);
+  });
+});
+
+describe("resolveBeatSourceTrack", () => {
+  it("returns null when there are no elements", () => {
+    expect(resolveBeatSourceTrack([])).toBeNull();
+  });
+
+  it("returns null when there are no audio elements", () => {
+    const elements = [el({ tag: "img", src: "assets/logo.png" })];
+    expect(resolveBeatSourceTrack(elements)).toBeNull();
+  });
+
+  it("returns isFallback=false for an explicitly tagged music track", () => {
+    const music = el({ timelineRole: "music" });
+    const result = resolveBeatSourceTrack([music]);
+    expect(result).not.toBeNull();
+    expect(result!.isFallback).toBe(false);
+    expect(result!.element).toBe(music);
+  });
+
+  it("prefers the explicit music track over a longer untagged clip", () => {
+    const music = el({ timelineRole: "music", duration: 30 });
+    const other = el({ id: "drop_1", domId: "drop_1", timelineRole: undefined, duration: 120 });
+    const result = resolveBeatSourceTrack([music, other]);
+    expect(result!.element).toBe(music);
+    expect(result!.isFallback).toBe(false);
+  });
+
+  it("falls back to the longest untagged audio clip when no music track exists", () => {
+    const short = el({ id: "drop_1", domId: "drop_1", duration: 5, timelineRole: undefined });
+    const long = el({ id: "drop_2", domId: "drop_2", duration: 60, timelineRole: undefined });
+    const result = resolveBeatSourceTrack([short, long]);
+    expect(result).not.toBeNull();
+    expect(result!.isFallback).toBe(true);
+    expect(result!.element).toBe(long);
+  });
+
+  it("excludes explicitly non-music roles (sfx, voiceover) from the fallback", () => {
+    const sfx = el({ id: "sfx_1", domId: "sfx_1", timelineRole: "sfx", duration: 30 });
+    const vo = el({ id: "vo_1", domId: "vo_1", timelineRole: "voiceover", duration: 20 });
+    expect(resolveBeatSourceTrack([sfx, vo])).toBeNull();
+  });
+
+  it("returns isFallback=true for an untagged clip with a non-music id", () => {
+    const clip = el({ id: "my_audio_file", domId: "my_audio_file", timelineRole: undefined });
+    const result = resolveBeatSourceTrack([clip]);
+    expect(result!.isFallback).toBe(true);
+  });
+});

package/src/utils/timelineInspector.ts

@@ -4,7 +4,7 @@ const AUDIO_TIMELINE_TAGS = new Set(["audio", "music", "sfx", "sound", "narratio
 const AUDIO_SOURCE_EXT_RE = /\.(aac|flac|m4a|mp3|ogg|opus|wav)(?:[?#].*)?$/i;
 const MUSIC_ID_RE = /\b(music|bgm|soundtrack|background[-_]?music)\b/i;
 
-function isAudioTimelineElement(
+export function isAudioTimelineElement(
   element: Pick<TimelineElement, "tag" | "src"> | null | undefined,
 ): boolean {
   if (!element) return false;
@@ -29,3 +29,34 @@ export function isMusicTrack(
   const id = element.domId ?? element.id ?? "";
   return MUSIC_ID_RE.test(id);
 }
+
+/**
+ * Resolve the best audio source for beat analysis. An explicitly tagged or
+ * named music track wins; when none is present (e.g. an audio file dropped
+ * from Finder with a generic id), the LONGEST untagged audio clip is used as a
+ * fallback. Ties on duration resolve to the FIRST such clip encountered (the loop
+ * keeps the current best on `>` only), i.e. discovery/DOM order wins.
+ * Returns the element and whether it was found via the fallback path.
+ *
+ * The `isMusicTrack` predicate is unchanged so beat-snap and drag-exclusion
+ * logic remain unaffected by this fallback.
+ */
+export function resolveBeatSourceTrack(
+  elements: readonly Pick<
+    TimelineElement,
+    "tag" | "src" | "id" | "domId" | "timelineRole" | "duration"
+  >[],
+): { element: (typeof elements)[number]; isFallback: boolean } | null {
+  const explicit = elements.find(isMusicTrack);
+  if (explicit) return { element: explicit, isFallback: false };
+
+  // Fallback: pick the longest audio clip (skipping explicitly non-music roles
+  // like "sfx" or "voiceover" to avoid triggering beat analysis on those).
+  let best: (typeof elements)[number] | null = null;
+  for (const el of elements) {
+    if (!isAudioTimelineElement(el)) continue;
+    if (el.timelineRole && el.timelineRole !== "music") continue;
+    if (!best || el.duration > best.duration) best = el;
+  }
+  return best ? { element: best, isFallback: true } : null;
+}