@hyperframes/studio 0.7.107 → 0.7.109

package/src/player/components/automationClipboard.ts

@@ -0,0 +1,136 @@
+/**
+ * Internal clipboard for automation ranges. Module-level, not the OS
+ * clipboard — points are not text, and useClipboard is already the DOM-element
+ * channel. Values cross parameters through unit space, so a volume duck
+ * pasted onto a log-scaled wet knob lands proportionally, not literally.
+ *
+ * Project-scoped by itself rather than by a caller, because the failure is
+ * destructive and silent: a range copied in project A pasted into B is remapped
+ * through A's captured `sourceRange` for an FX node B may not even have, and the
+ * keystroke is consumed so clip paste never runs. Every entry point carries the
+ * project it is speaking for and a mismatch empties the module, so no future
+ * caller can forget the guard — the same shape `keyframeSlice` uses to discard a
+ * request from a previous session.
+ */
+import {
+  sampleAutomationLane,
+  type AutomationRange,
+  type HfAutomationLane,
+  type HfAutomationPoint,
+} from "@hyperframes/core/audio-automation";
+import { fromUnit, toUnit } from "./automationLaneGeometry";
+import { pointsIn } from "./automationLaneSelection";
+
+export interface AutomationClipboardEntry {
+  sourceRange: AutomationRange;
+  span: number;
+  points: HfAutomationPoint[];
+}
+
+/** The span one paste covered, in the same shape as the selection it left. */
+export interface AutomationPasteMark {
+  elementKey: string;
+  target: string;
+  t0: number;
+  t1: number;
+}
+
+let ownerProjectId: string | null = null;
+let entry: AutomationClipboardEntry | null = null;
+let lastPaste: AutomationPasteMark | null = null;
+
+/**
+ * Rebind the module to `projectId`, discarding anything captured under a
+ * different one. Called by both entry points, so the mark is scoped
+ * transitively: `isLastPasteSpan` can only ever see a mark left by a paste in
+ * the project that most recently read the clipboard.
+ *
+ * `null` (no timeline session yet) is a project id like any other — it can hold
+ * an entry, and the first real session id evicts it.
+ */
+function useProject(projectId: string | null): void {
+  if (projectId === ownerProjectId) return;
+  ownerProjectId = projectId;
+  entry = null;
+  lastPaste = null;
+}
+
+/**
+ * Capture `[t0, t1]` rebased to zero. Returns false — leaving the clipboard as
+ * it was — when the lane has nothing to capture.
+ *
+ * `pointsIn` reports only explicit breakpoints, so a range drawn over a smooth
+ * stretch of envelope has none. Storing that as `points: []` would arm a
+ * clipboard whose paste is byte-identical to the Delete write, so every later
+ * Cmd+V would erase its destination instead of reproducing the copied shape.
+ * Over a lane that HAS an envelope the range is a real flat or sloped segment,
+ * captured by sampling both edges (what `replaceRange`'s own anchors do). Over
+ * an entirely empty lane there is no shape at all, so nothing is stored — a
+ * failed copy leaves an earlier clipboard alone rather than destroying it.
+ */
+export function copyRange(
+  projectId: string | null,
+  lane: HfAutomationLane,
+  range: AutomationRange,
+  t0: number,
+  t1: number,
+): boolean {
+  const inner = pointsIn(lane, t0, t1).map((p) => ({ ...p, t: p.t - t0 }));
+  if (inner.length === 0 && lane.points.length === 0) return false;
+  useProject(projectId);
+  entry = {
+    sourceRange: range,
+    span: t1 - t0,
+    points:
+      inner.length > 0
+        ? inner
+        : [
+            { t: 0, v: sampleAutomationLane(lane, t0, range.scale) },
+            { t: t1 - t0, v: sampleAutomationLane(lane, t1, range.scale) },
+          ],
+  };
+  return true;
+}
+
+export function readClipboard(projectId: string | null): AutomationClipboardEntry | null {
+  useProject(projectId);
+  return entry;
+}
+
+export function pastePoints(
+  from: AutomationClipboardEntry,
+  target: AutomationRange,
+  atT: number,
+): HfAutomationPoint[] {
+  return from.points.map((p) => ({
+    ...p,
+    t: atT + p.t,
+    v: fromUnit(target, toUnit(from.sourceRange, p.v)),
+  }));
+}
+
+/**
+ * Remember the span a paste just covered and left selected, so the next Cmd+V
+ * can tell that selection apart from one the user drew and chain after it
+ * instead of overwriting it.
+ */
+export function markLastPaste(mark: AutomationPasteMark): void {
+  lastPaste = { ...mark };
+}
+
+/** True when `mark` is exactly the span the last paste left selected. */
+export function isLastPasteSpan(mark: AutomationPasteMark): boolean {
+  if (!lastPaste) return false;
+  return (
+    lastPaste.elementKey === mark.elementKey &&
+    lastPaste.target === mark.target &&
+    lastPaste.t0 === mark.t0 &&
+    lastPaste.t1 === mark.t1
+  );
+}
+
+export function clearAutomationClipboard(): void {
+  ownerProjectId = null;
+  entry = null;
+  lastPaste = null;
+}

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

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { createAutomationGestureKeys } from "./automationGestureKeys";
+
+const keys = () => {
+  let n = 0;
+  return createAutomationGestureKeys(() => `g${++n}`);
+};
+
+describe("createAutomationGestureKeys", () => {
+  it("holds one key across every move of a drag", () => {
+    // Each move persists; history merges same-key entries inside 300ms. Separate
+    // keys, or a window that can expire mid-drag, is what made undo take back a
+    // fragment of the move instead of the move.
+    const g = keys();
+    expect([g.live().key, g.live().key, g.live().key]).toEqual(["g1", "g1", "g1"]);
+  });
+
+  it("never lets the window expire", () => {
+    expect(keys().live().ms).toBe(Number.POSITIVE_INFINITY);
+    expect(keys().commit().ms).toBe(Number.POSITIVE_INFINITY);
+  });
+
+  it("ends the gesture on the release, under the same key", () => {
+    const g = keys();
+    g.live();
+    expect(g.commit().key).toBe("g1");
+  });
+
+  it("starts a fresh key for the next drag", () => {
+    const g = keys();
+    g.live();
+    g.commit();
+    expect(g.live().key).toBe("g2");
+  });
+
+  it("gives a standalone commit its own key", () => {
+    // Deleting a range, pasting one, typing a value: one write, one step each.
+    const g = keys();
+    expect(g.commit().key).toBe("g1");
+    expect(g.commit().key).toBe("g2");
+  });
+
+  it("does not join a commit to a gesture that already ended", () => {
+    const g = keys();
+    g.live();
+    g.commit();
+    expect(g.commit().key).toBe("g2");
+  });
+});

package/src/player/components/automationGestureKeys.ts

@@ -0,0 +1,49 @@
+/**
+ * Undo grouping for a lane gesture.
+ *
+ * Dragging a point persists on every move and once more on release. History
+ * coalesces entries that share a key and land within 300ms of each other, and
+ * these writes did neither: the moves and the release used different keys, and a
+ * drag slower than the window split into several entries. Undo then took back
+ * whatever fragment happened to be last, leaving the point near where the drag
+ * had dropped it — which reads as undo not working at all.
+ *
+ * So a gesture mints one key and holds it: every move and the release that ends
+ * it record under that key with no window to expire, and the next gesture gets a
+ * fresh one so two drags never collapse into a single step.
+ */
+
+export interface CoalesceHint {
+  key: string;
+  /** No expiry: a gesture is one step however long the pointer is held. */
+  ms: number;
+}
+
+export interface AutomationGestureKeys {
+  /** A continuous write. Opens a gesture if one is not already open. */
+  live(): CoalesceHint;
+  /** The persisting write that ends a gesture — or a standalone edit. */
+  commit(): CoalesceHint;
+}
+
+export function createAutomationGestureKeys(
+  mint: () => string = () => `automation-gesture:${++counter}`,
+): AutomationGestureKeys {
+  let open: string | null = null;
+  const hint = (key: string): CoalesceHint => ({ key, ms: Number.POSITIVE_INFINITY });
+  return {
+    live: () => {
+      open ??= mint();
+      return hint(open);
+    },
+    commit: () => {
+      // A commit with no drag before it — a Delete, a paste, a typed value — is
+      // its own step, so it mints rather than joining anything.
+      const key = open ?? mint();
+      open = null;
+      return hint(key);
+    },
+  };
+}
+
+let counter = 0;

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

@@ -0,0 +1,270 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import {
+  automationLaneLabel,
+  automationLaneLabelParts,
+  elementAutomation,
+  groupAutomationLanes,
+  laneGroupKey,
+  elementFxChain,
+} from "./automationLaneData";
+import type { TimelineElement } from "../store/timelineElement";
+
+const el = (over: Partial<TimelineElement> = {}): TimelineElement => ({
+  id: "bgm",
+  key: "bgm",
+  tag: "audio",
+  start: 0,
+  duration: 10,
+  track: 10,
+  ...over,
+});
+
+/** The chain as the lane code sees it: parsed, not the attribute text. */
+const parseChain = (chain: unknown) => elementFxChain(el({ fxChain: JSON.stringify(chain) }))!;
+
+const CHAIN = JSON.stringify({
+  version: 1,
+  nodes: [{ type: "lowpass", id: "n1", params: { frequency: 400, q: 0.9, poles: "2" } }],
+});
+const LANE = JSON.stringify({
+  version: 1,
+  lanes: [{ target: "fx.n1.frequency", points: [{ t: 0, v: 400 }] }],
+});
+
+describe("automationLaneData", () => {
+  it("returns the same object for the same attributes", () => {
+    // The lane compares its drag draft against this identity; a fresh object per
+    // playhead tick would drop the drag.
+    const a = elementAutomation(el({ automation: LANE, fxChain: CHAIN }));
+    const b = elementAutomation(el({ automation: LANE, fxChain: CHAIN }));
+    expect(a).toBe(b);
+    expect(elementFxChain(el({ fxChain: CHAIN }))).toBe(elementFxChain(el({ fxChain: CHAIN })));
+  });
+
+  it("re-parses when the chain changes even though the automation text did not", () => {
+    const withChain = elementAutomation(el({ automation: LANE, fxChain: CHAIN }));
+    const withoutChain = elementAutomation(el({ automation: LANE }));
+    expect(withChain.lanes.map((l) => l.target)).toEqual(["fx.n1.frequency"]);
+    // No chain to resolve against, so the fx lane is dropped rather than drawn.
+    expect(withoutChain.lanes).toEqual([]);
+  });
+
+  it("keeps a hot entry alive when other elements push the cache past its limit", () => {
+    // Eviction used to clear the whole map, which changed every lane's identity
+    // at once and released any drag in progress.
+    const hot = el({ automation: LANE, fxChain: CHAIN });
+    const first = elementAutomation(hot);
+    for (let i = 0; i < 40; i += 1) {
+      elementAutomation(
+        el({
+          automation: JSON.stringify({
+            version: 1,
+            lanes: [{ target: "volume", points: [{ t: i, v: 0.5 }] }],
+          }),
+        }),
+      );
+      elementAutomation(hot);
+    }
+    expect(elementAutomation(hot)).toBe(first);
+  });
+
+  it("reads an unreadable attribute as nothing rather than throwing", () => {
+    expect(elementAutomation(el({ automation: "{nope" })).lanes).toEqual([]);
+    expect(elementFxChain(el({ fxChain: "{nope" }))).toBeNull();
+  });
+
+  describe("lane order", () => {
+    // A stack of EQ bands reads as a spectrum, so it has to be laid out like one:
+    // the top of the stack is the top of the audible range. Attribute order is
+    // whatever the carve happened to mint, which is the opposite — bands come out
+    // ascending.
+    const bandChain = JSON.stringify({
+      version: 1,
+      nodes: [
+        { type: "peaking", id: "n1", params: { frequency: 400, gain: -6, q: 1.4 } },
+        { type: "peaking", id: "n2", params: { frequency: 1600, gain: -9, q: 1.4 } },
+        { type: "peaking", id: "n3", params: { frequency: 1000, gain: -3, q: 1.4 } },
+        { type: "gain", id: "n4", params: { gain: -6 } },
+      ],
+    });
+    const bandLanes = JSON.stringify({
+      version: 1,
+      lanes: [
+        { target: "volume", points: [{ t: 0, v: 1 }] },
+        { target: "fx.n1.gain", points: [{ t: 0, v: -6 }] },
+        { target: "fx.n2.gain", points: [{ t: 0, v: -9 }] },
+        { target: "fx.n3.gain", points: [{ t: 0, v: -3 }] },
+        { target: "fx.n4.gain", points: [{ t: 0, v: -6 }] },
+      ],
+    });
+
+    it("puts the highest frequency at the top", () => {
+      const lanes = elementAutomation(el({ automation: bandLanes, fxChain: bandChain })).lanes;
+      expect(lanes.map((l) => l.target)).toEqual([
+        "fx.n2.gain", // 1.6 kHz
+        "fx.n3.gain", // 1 kHz
+        "fx.n1.gain", // 400 Hz
+        // Neither of these is a band, so they sit under the spectrum in the order
+        // they were written.
+        "volume",
+        "fx.n4.gain",
+      ]);
+    });
+
+    it("keeps the same object identity, so a drag survives the sort", () => {
+      const a = elementAutomation(el({ automation: bandLanes, fxChain: bandChain }));
+      const b = elementAutomation(el({ automation: bandLanes, fxChain: bandChain }));
+      expect(a).toBe(b);
+    });
+  });
+
+  describe("automationLaneLabel", () => {
+    const chain = parseChain({
+      version: 1,
+      nodes: [
+        { type: "peaking", id: "n1", params: { frequency: 1600, gain: -9, q: 1.4 } },
+        { type: "peaking", id: "n2", params: { frequency: 400, gain: -6, q: 1.4 } },
+        { type: "gain", id: "n3", params: { gain: -6 } },
+      ],
+    });
+
+    it("names the effect and the band it sits at", () => {
+      // Three lanes all reading "Peaking EQ · Gain" say nothing about which band
+      // each one is; a bare frequency does not say whether it is a bell or a
+      // shelf. Both, then the parameter.
+      expect(automationLaneLabel("fx.n1.gain", chain)).toBe("Peaking EQ 1.6 kHz · Gain");
+      expect(automationLaneLabel("fx.n2.gain", chain)).toBe("Peaking EQ 400 Hz · Gain");
+    });
+
+    it("falls back to the effect's name when it has no frequency", () => {
+      expect(automationLaneLabel("fx.n3.gain", chain)).toBe("Gain · Gain");
+      expect(automationLaneLabel("volume", chain)).toBe("Volume");
+    });
+
+    it("has nothing to say about a target that does not resolve", () => {
+      expect(automationLaneLabel("fx.gone.gain", chain)).toBeNull();
+      expect(automationLaneLabelParts("fx.gone.gain", chain)).toBeNull();
+    });
+
+    it("splits the name from the parameter, which the column stacks", () => {
+      expect(automationLaneLabelParts("fx.n1.gain", chain)).toEqual({
+        name: "Peaking EQ 1.6 kHz",
+        param: "Gain",
+      });
+      expect(automationLaneLabelParts("fx.n3.gain", chain)).toEqual({
+        name: "Gain",
+        param: "Gain",
+      });
+      // Volume is one word with no effect behind it, so there is no second line.
+      expect(automationLaneLabelParts("volume", chain)).toEqual({ name: "Volume", param: "" });
+    });
+  });
+});
+
+describe("laneGroupKey", () => {
+  // Two clips, each with their OWN chain, both automating a 1 kHz peaking Q. Node
+  // ids are minted per chain, so the ids collide across clips while meaning
+  // different things — and match across clips while meaning the same thing.
+  const clipA = parseChain({
+    version: 1,
+    nodes: [
+      { type: "lowpass", id: "n1", params: { frequency: 8000, q: 0.7, poles: "2" } },
+      { type: "peaking", id: "n2", params: { frequency: 1000, gain: -3, q: 1.4 } },
+    ],
+  });
+  const clipB = parseChain({
+    version: 1,
+    nodes: [{ type: "peaking", id: "n1", params: { frequency: 1000, gain: -6, q: 1.4 } }],
+  });
+
+  it("groups the same property of the same effect across clips", () => {
+    // The whole point: one row for "Peaking EQ 1 kHz · Q", whichever clip it is on.
+    expect(laneGroupKey("fx.n2.q", clipA)).toBe(laneGroupKey("fx.n1.q", clipB));
+  });
+
+  it("does not group by lane target, which collides across chains", () => {
+    // `fx.n1.q` is a low-pass on one clip and a peaking EQ on the other. Grouping by
+    // target would put those two envelopes in one row.
+    expect(laneGroupKey("fx.n1.q", clipA)).not.toBe(laneGroupKey("fx.n1.q", clipB));
+  });
+
+  it("separates parameters, and the same parameter on different bands", () => {
+    expect(laneGroupKey("fx.n2.q", clipA)).not.toBe(laneGroupKey("fx.n2.gain", clipA));
+    const twoBands = parseChain({
+      version: 1,
+      nodes: [
+        { type: "peaking", id: "n1", params: { frequency: 400, gain: -6, q: 1.4 } },
+        { type: "peaking", id: "n2", params: { frequency: 1600, gain: -6, q: 1.4 } },
+      ],
+    });
+    expect(laneGroupKey("fx.n1.gain", twoBands)).not.toBe(laneGroupKey("fx.n2.gain", twoBands));
+  });
+
+  it("groups volume with volume, and nothing with an unresolvable target", () => {
+    expect(laneGroupKey("volume", clipA)).toBe(laneGroupKey("volume", clipB));
+    expect(laneGroupKey("fx.gone.gain", clipA)).toBeNull();
+  });
+});
+
+describe("groupAutomationLanes", () => {
+  const chainOf = (nodes: unknown[]) => JSON.stringify({ version: 1, nodes });
+  const lanesOf = (...targets: string[]) =>
+    JSON.stringify({
+      version: 1,
+      lanes: targets.map((target) => ({ target, points: [{ t: 0, v: 1 }] })),
+    });
+
+  // Two narration slices sharing a row. Each mints its own chain, so the node ids
+  // collide across them while meaning different things.
+  const narration1 = el({
+    id: "narration-1",
+    key: "narration-1",
+    fxChain: chainOf([
+      { type: "lowpass", id: "n1", params: { frequency: 8000, q: 0.7, poles: "2" } },
+      { type: "peaking", id: "n2", params: { frequency: 1000, gain: -3, q: 1.4 } },
+    ]),
+    automation: lanesOf("fx.n2.q"),
+  });
+  const narration2 = el({
+    id: "narration-2",
+    key: "narration-2",
+    fxChain: chainOf([
+      { type: "peaking", id: "n1", params: { frequency: 1000, gain: -6, q: 1.4 } },
+    ]),
+    automation: lanesOf("fx.n1.q", "volume"),
+  });
+
+  it("puts the same property of the same effect in one row, one entry per clip", () => {
+    const groups = groupAutomationLanes([narration1, narration2]);
+    expect(groups.map((g) => g.key)).toEqual(["Peaking EQ 1 kHz · Q", "Volume"]);
+    expect(groups[0]?.entries.map((e) => e.element.id)).toEqual(["narration-1", "narration-2"]);
+    expect(groups[0]).toMatchObject({ name: "Peaking EQ 1 kHz", param: "Q" });
+  });
+
+  it("leaves a clip out of a row it does not automate", () => {
+    // The empty stretch is the point: narration-1 has no volume envelope, so it
+    // contributes nothing to that row rather than a flat line claiming one exists.
+    const groups = groupAutomationLanes([narration1, narration2]);
+    expect(groups[1]?.entries.map((e) => e.element.id)).toEqual(["narration-2"]);
+  });
+
+  it("does not merge lanes whose targets collide across chains", () => {
+    // `fx.n1.*` is a low-pass on one clip and a peaking EQ on the other.
+    const lowpass = el({ ...narration1, automation: lanesOf("fx.n1.q") });
+    const peaking = el({ ...narration2, automation: lanesOf("fx.n1.q") });
+    const groups = groupAutomationLanes([lowpass, peaking]);
+    expect(groups.map((g) => g.key)).toEqual(["Low-pass 8 kHz · Q", "Peaking EQ 1 kHz · Q"]);
+    expect(groups.map((g) => g.entries.length)).toEqual([1, 1]);
+  });
+
+  it("ignores clips that are not audio, the way the reserved height does", () => {
+    const video = el({ id: "titles", key: "titles", tag: "div", automation: lanesOf("volume") });
+    expect(groupAutomationLanes([video])).toEqual([]);
+  });
+
+  it("skips a target that does not resolve against its clip's chain", () => {
+    const stale = el({ ...narration2, automation: lanesOf("fx.gone.q", "volume") });
+    expect(groupAutomationLanes([stale]).map((g) => g.key)).toEqual(["Volume"]);
+  });
+});