@hyperframes/studio 0.7.107 → 0.7.109

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

@@ -9,7 +9,8 @@ import { TimelineTrackHeader } from "./TimelineTrackHeader";
 import { defaultTimelineTheme } from "./timelineTheme";
 import type { TimelineElement } from "../store/playerStore";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
-import { LABEL_COL_W } from "./timelineLayout";
+import { getTimelineLaneTop, LABEL_COL_W } from "./timelineLayout";
+import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -61,6 +62,8 @@ const OPACITY = animation("opacity-tween", "visual", [
 
 interface RenderHeaderOptions {
   keyframeClip?: TimelineElement;
+  /** Every clip on the track; defaults to just the keyframe clip. */
+  trackElements?: readonly TimelineElement[];
   animations?: GsapAnimation[];
   clipCount?: number;
   currentTime?: number;
@@ -68,6 +71,7 @@ interface RenderHeaderOptions {
   onSeek?: (time: number) => void;
   onTogglePropertyGroupKeyframe?: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
   onToggleTrackHidden?: TimelineEditCallbacks["onToggleTrackHidden"];
+  onRemoveAutomationLane?: (target: string) => void;
 }
 
 function renderHeader(options: RenderHeaderOptions = {}): {
@@ -90,6 +94,7 @@ function renderHeader(options: RenderHeaderOptions = {}): {
           lanesId="timeline-lanes-track-0"
           contentOrigin={LABEL_COL_W}
           keyframeClip={next.keyframeClip ?? ELEMENT}
+          trackElements={next.trackElements ?? [next.keyframeClip ?? ELEMENT]}
           clipCount={next.clipCount ?? 1}
           isExpanded={next.expanded !== false}
           animations={next.animations ?? [POSITION, OPACITY]}
@@ -100,6 +105,7 @@ function renderHeader(options: RenderHeaderOptions = {}): {
           onToggleClipExpanded={vi.fn()}
           onToggleTrackHidden={next.onToggleTrackHidden ?? vi.fn()}
           onTogglePropertyGroupKeyframe={next.onTogglePropertyGroupKeyframe}
+          onRemoveAutomationLane={next.onRemoveAutomationLane}
           onSeek={next.onSeek}
         />,
       );
@@ -414,4 +420,209 @@ describe("TimelineTrackHeader", () => {
     assertAligned([POSITION, OPACITY]);
     act(() => view.root.unmount());
   });
+
+  /**
+   * Automation lanes are named in the label column, on the same tree as the
+   * keyframe rows — not painted inside the lane, where the name sat on top of
+   * the envelope it belonged to and scrolled away from its own row.
+   */
+  describe("audio automation rows", () => {
+    const BED: TimelineElement = {
+      id: "bed",
+      label: "Music Bed",
+      tag: "audio",
+      start: 0,
+      duration: 10,
+      track: 0,
+      fxChain: JSON.stringify({
+        version: 1,
+        nodes: [{ type: "peaking", id: "n1", params: { frequency: 1600, gain: -6, q: 1.4 } }],
+      }),
+      automation: JSON.stringify({
+        version: 1,
+        lanes: [
+          {
+            target: "volume",
+            points: [
+              { t: 0, v: 1 },
+              { t: 5, v: 0.4 },
+            ],
+          },
+          {
+            target: "fx.n1.gain",
+            points: [
+              { t: 0, v: 0 },
+              { t: 5, v: -6 },
+            ],
+          },
+        ],
+      }),
+    } as TimelineElement;
+
+    it("names every envelope in the label column", () => {
+      const { host, root } = renderHeader({ keyframeClip: BED, animations: [] });
+      const rows = Array.from(host.querySelectorAll<HTMLElement>("[data-automation-lane-label]"));
+      // The attribute is the ROW's identity, which is the label: a row can hold
+      // several clips' envelopes, whose lane targets differ from each other.
+      expect(rows.map((r) => r.getAttribute("data-automation-lane-label"))).toEqual([
+        "Peaking EQ 1.6 kHz · Gain",
+        "Volume",
+      ]);
+      // A band is named by its frequency: with several of them, "Peaking EQ" says
+      // nothing about which is which. Bands sit above the level lanes.
+      // Two lines per row: what the effect is, then which knob the envelope
+      // drives. One line truncated mid-word in a column this narrow.
+      expect(rows.map((r) => r.querySelector("[data-automation-lane-name]")?.textContent)).toEqual([
+        "Peaking EQ 1.6 kHz",
+        "Volume",
+      ]);
+      expect(rows.map((r) => r.querySelector("[data-automation-lane-param]")?.textContent)).toEqual(
+        [
+          "Gain",
+          // Volume has no effect behind it, so it has no second line at all.
+          undefined,
+        ],
+      );
+      act(() => root.unmount());
+    });
+
+    it("hides them when the track is collapsed", () => {
+      const { host, root } = renderHeader({
+        keyframeClip: BED,
+        animations: [],
+        expanded: false,
+      });
+      expect(host.querySelectorAll("[data-automation-lane-label]")).toHaveLength(0);
+      act(() => root.unmount());
+    });
+
+    it("removes just that envelope from the label column", () => {
+      // The panel's automate toggle can only reach a parameter it still shows; a
+      // carve's own lanes are not in it at all, so without this an envelope could
+      // be created and never deleted.
+      const onRemoveAutomationLane = vi.fn();
+      const { host, root } = renderHeader({
+        keyframeClip: BED,
+        animations: [],
+        onRemoveAutomationLane,
+      });
+      const button = host.querySelector<HTMLButtonElement>(
+        'button[aria-label="Remove Peaking EQ 1.6 kHz · Gain automation"]',
+      );
+      expect(button).not.toBeNull();
+      act(() => button?.click());
+      expect(onRemoveAutomationLane).toHaveBeenCalledWith("fx.n1.gain");
+      act(() => root.unmount());
+    });
+
+    it("offers no remove button when the lanes are read-only", () => {
+      const { host, root } = renderHeader({ keyframeClip: BED, animations: [] });
+      expect(host.querySelectorAll('button[aria-label$="automation"]')).toHaveLength(0);
+      act(() => root.unmount());
+    });
+
+    it("stacks each envelope's row where its lane is drawn", () => {
+      // Same rhythm the canvas uses: automation begins below the keyframe lanes
+      // and steps by its own taller row height.
+      const { host, root } = renderHeader({ keyframeClip: BED, animations: [OPACITY] });
+      const tops = Array.from(
+        host.querySelectorAll<HTMLElement>("[data-automation-lane-label]"),
+      ).map((r) => r.style.top);
+      const base = getTimelineLaneTop(1);
+      expect(tops).toEqual([`${base}px`, `${base + AUTOMATION_LANE_H}px`]);
+      act(() => root.unmount());
+    });
+  });
+
+  /**
+   * Several clips on one row share a lane row per property, so the label column
+   * has to name the row for the property and the header for the track — not for
+   * whichever clip happens to be selected.
+   */
+  describe("a track several clips share", () => {
+    const clip = (id: string, over: Partial<TimelineElement>): TimelineElement =>
+      ({
+        id,
+        key: id,
+        label: id,
+        tag: "audio",
+        start: 0,
+        duration: 4,
+        track: 0,
+        ...over,
+      }) as TimelineElement;
+    const PEAKING = (gain: number) =>
+      JSON.stringify({
+        version: 1,
+        nodes: [{ type: "peaking", id: "n1", params: { frequency: 1000, gain, q: 1.4 } }],
+      });
+    const NARRATION_1 = clip("narration-1", {
+      fxChain: PEAKING(-3),
+      automation: JSON.stringify({
+        version: 1,
+        lanes: [{ target: "fx.n1.gain", points: [{ t: 0, v: -3 }] }],
+      }),
+    });
+    const NARRATION_2 = clip("narration-2", {
+      start: 4,
+      fxChain: PEAKING(-6),
+      automation: JSON.stringify({
+        version: 1,
+        lanes: [
+          { target: "fx.n1.gain", points: [{ t: 0, v: -6 }] },
+          { target: "volume", points: [{ t: 0, v: 1 }] },
+        ],
+      }),
+    });
+    const ROW = { trackElements: [NARRATION_1, NARRATION_2], clipCount: 2, animations: [] };
+
+    it("lists every clip's envelopes, whichever clip is selected", () => {
+      const labels = (host: HTMLElement) =>
+        Array.from(host.querySelectorAll("[data-automation-lane-label]")).map((r) =>
+          r.getAttribute("data-automation-lane-label"),
+        );
+      const first = renderHeader({ ...ROW, keyframeClip: NARRATION_1 });
+      const second = renderHeader({ ...ROW, keyframeClip: NARRATION_2 });
+      // narration-1 has no volume envelope, but the row is still there — it is
+      // the track's, and it was its sibling's before the selection moved.
+      expect(labels(first.host)).toEqual(["Peaking EQ 1 kHz · Gain", "Volume"]);
+      expect(labels(second.host)).toEqual(labels(first.host));
+      act(() => first.root.unmount());
+      act(() => second.root.unmount());
+    });
+
+    it("removes only from the clip it is showing, and offers nothing where it has no lane", () => {
+      // A write can only reach the selected clip, so a button on a row that clip
+      // is absent from could only remove nothing, or somebody else's envelope.
+      const onRemoveAutomationLane = vi.fn();
+      const { host, root } = renderHeader({
+        ...ROW,
+        keyframeClip: NARRATION_1,
+        onRemoveAutomationLane,
+      });
+      expect(
+        Array.from(host.querySelectorAll('button[aria-label$="automation"]')).map((b) =>
+          b.getAttribute("aria-label"),
+        ),
+      ).toEqual(["Remove Peaking EQ 1 kHz · Gain automation"]);
+      act(() => host.querySelector<HTMLButtonElement>('button[aria-label$="automation"]')?.click());
+      expect(onRemoveAutomationLane).toHaveBeenCalledWith("fx.n1.gain");
+      act(() => root.unmount());
+    });
+
+    it("names the header for the track, not for one of the clips on it", () => {
+      const view = renderHeader({ ...ROW, keyframeClip: NARRATION_2 });
+      expect(view.host.textContent).not.toContain("narration-2");
+      expect(view.host.querySelector('[title="Track 1"]')?.textContent).toBe("Track 1");
+      // Alone on the track it is still named for itself.
+      view.rerender({
+        ...ROW,
+        keyframeClip: NARRATION_2,
+        trackElements: [NARRATION_2],
+        clipCount: 1,
+      });
+      expect(view.host.querySelector('[title="narration-2"]')?.textContent).toBe("narration-2");
+      act(() => view.root.unmount());
+    });
+  });
 });

package/src/player/components/TimelineTrackHeader.tsx

@@ -4,6 +4,8 @@ import { Music } from "../../icons/SystemIcons";
 import type { TimelineElement } from "../store/playerStore";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
+import { groupAutomationLanes } from "./automationLaneData";
+import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { clipTimingStart } from "../../hooks/gsapShared";
 import { LayerDisclosureRow } from "./LayerDisclosureRow";
 import { TrackClipCount } from "./TrackClipCount";
@@ -28,13 +30,19 @@ interface TimelineTrackHeaderProps {
    *  from the label rather than inventing one (see trackDisplayNumber). */
   trackDisplayNumber: number | null;
   trackLabel: string;
-  /** Id of the canvas-side lanes element the disclosure caret expands. Minted by
-   *  TimelineLanes, which is the one place that sees both subtrees. */
+  /** Ids of the canvas-side lane regions the disclosure caret expands, space
+   *  separated as `aria-controls` takes them: the active clip's keyframe lanes
+   *  and the track's automation lanes are separate elements, one owned by a
+   *  clip and one by the row. Minted by TimelineLanes, the one place that sees
+   *  every subtree. */
   lanesId: string;
   contentOrigin: number;
   /** The track's active keyframe clip (selected, else primary) — the one whose
    *  disclosure + property rows this header shows, whether expanded or not. */
   keyframeClip: TimelineElement | null;
+  /** Every clip on this track. Automation rows are the track's, unioned over
+   *  these, so they stop changing with the selection. */
+  trackElements: readonly TimelineElement[];
   /** Clips on this track, so the header can say how many the row holds. */
   clipCount: number;
   isExpanded: boolean;
@@ -47,6 +55,9 @@ interface TimelineTrackHeaderProps {
   onToggleClipExpanded: () => void;
   onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
   onTogglePropertyGroupKeyframe?: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+  /** Drop one envelope. Absent while the lanes are read-only, which is what
+   *  hides the control rather than offering a button that cannot act. */
+  onRemoveAutomationLane?: (target: string) => void;
   onSeek?: (time: number) => void;
 }
 
@@ -291,6 +302,110 @@ function PropertyGroupHeaderRow({
   );
 }
 
+/**
+ * One envelope's row in the label column.
+ *
+ * Named here rather than inside the lane, on the same tree connector the
+ * keyframe rows use: an automation lane is a child of its clip exactly as a
+ * property group is, and drawing its name over the envelope put the label on top
+ * of the curve it describes and scrolled it away from its own row.
+ */
+function AutomationLaneHeaderRow({
+  target,
+  label,
+  name,
+  param,
+  top,
+  isLastLane,
+  gutterBackground,
+  columnWidth,
+  onRemove,
+}: {
+  /** The lane the ACTIVE clip draws in this row, or null when it draws none —
+   *  the row belongs to the property, and a clip may be absent from it. */
+  target: string | null;
+  /** The whole thing on one line: the row's identity, its tooltip, and the
+   *  remove button's name. */
+  label: string;
+  /** What the effect is — "Peaking EQ 1.6 kHz". */
+  name: string;
+  /** Which knob the envelope drives. Empty when there is no second line to draw. */
+  param: string;
+  top: number;
+  isLastLane: boolean;
+  gutterBackground: string;
+  columnWidth: number;
+  onRemove?: (target: string) => void;
+}) {
+  return (
+    <div
+      data-automation-lane-label={label}
+      data-timeline-lane-top={top}
+      className="absolute left-0 flex items-center gap-1 overflow-hidden px-1.5 text-[10px] text-white/65"
+      style={{
+        top,
+        width: columnWidth,
+        height: AUTOMATION_LANE_H,
+        background: gutterBackground,
+      }}
+    >
+      {/* Tree connector, as the keyframe rows draw it: spine down the row, branch
+          tick at the name's own height. */}
+      <span className="relative h-full w-3 shrink-0" aria-hidden="true">
+        <span
+          className="absolute left-1.5 top-0 w-px bg-white/15"
+          style={{ height: isLastLane ? "50%" : "100%" }}
+        />
+        <span className="absolute left-1.5 top-1/2 h-px w-1.5 bg-white/15" />
+      </span>
+      {/* Two lines: what the effect is, then which knob the envelope drives. On
+          one line a band's own name was the first thing truncated in a column this
+          narrow — "Peaking EQ 1.6 k…" — losing exactly the part that tells two
+          bands apart. */}
+      <span className="flex min-w-0 flex-1 flex-col justify-center leading-tight" title={label}>
+        <span data-automation-lane-name="" className="truncate font-mono text-[9px] text-white/70">
+          {name}
+        </span>
+        {param ? (
+          <span
+            data-automation-lane-param=""
+            className="truncate font-mono text-[9px] text-white/40"
+          >
+            {param}
+          </span>
+        ) : null}
+      </span>
+      {/* Beside the name it labels, because that is the only place an envelope is
+          named at all: a carve writes its own lanes, and the FX panel's automate
+          toggle can only reach a parameter it still lists — so without this an
+          envelope could be created and never removed.
+
+          Only for the clip the header is showing, since that is the only one a
+          write can reach: a shared row's other envelopes belong to clips that
+          are not selected, and a button that silently removed one of them (or
+          none) would be worse than no button. */}
+      {onRemove && target !== null && (
+        <button
+          type="button"
+          aria-label={`Remove ${label} automation`}
+          title={`Remove ${label} automation`}
+          // h-6 w-6 is the 24x24 WCAG 2.2 target; the glyph stays small.
+          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-white/35 hover:text-white focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
+          onPointerDown={(event) => event.stopPropagation()}
+          onClick={(event) => {
+            // A control in the label column owns its click; it does not also hit
+            // the track row behind it and change the selection.
+            event.stopPropagation();
+            onRemove(target);
+          }}
+        >
+          ×
+        </button>
+      )}
+    </div>
+  );
+}
+
 export function TimelineTrackHeader({
   trackNumber,
   trackDisplayNumber,
@@ -298,6 +413,7 @@ export function TimelineTrackHeader({
   lanesId,
   contentOrigin,
   keyframeClip,
+  trackElements,
   clipCount,
   isExpanded,
   animations,
@@ -308,6 +424,7 @@ export function TimelineTrackHeader({
   onToggleClipExpanded,
   onToggleTrackHidden,
   onTogglePropertyGroupKeyframe,
+  onRemoveAutomationLane,
   onSeek,
   rovingTargetId = null,
 }: TimelineTrackHeaderProps) {
@@ -322,7 +439,24 @@ export function TimelineTrackHeader({
   // Label mode = keyframe view; the label column stays LABEL_COL_W (Timeline.tsx
   // owns the gutter past it, so a 0% diamond isn't clipped by this panel).
   const showTrackLabel = contentOrigin >= LABEL_COL_W;
-  const isKeyframeLayer = !!keyframeClip && lanes.length > 0;
+  // One row per automated property across the whole track, in the order the
+  // canvas draws them — a name beside the wrong envelope is worse than an awkward
+  // order. `target` is the ACTIVE clip's lane in that row, which is the only one
+  // the remove button can write to; null when the row belongs to its siblings.
+  const activeKey = keyframeClip ? (keyframeClip.key ?? keyframeClip.id) : null;
+  const automationRows = groupAutomationLanes(trackElements).map((group) => ({
+    key: group.key,
+    label: group.key,
+    name: group.name,
+    param: group.param,
+    target:
+      group.entries.find((entry) => (entry.element.key ?? entry.element.id) === activeKey)?.lane
+        .target ?? null,
+  }));
+  // Automation counts as something to disclose: gating the caret on tweens alone
+  // left an audio clip's envelopes unreachable, since the track could not expand.
+  const disclosable = lanes.length > 0 || automationRows.length > 0;
+  const isKeyframeLayer = !!keyframeClip && disclosable;
 
   return (
     <div
@@ -341,7 +475,7 @@ export function TimelineTrackHeader({
         borderRight: `1px solid ${theme.gutterBorder}`,
       }}
     >
-      {!keyframeClip || lanes.length === 0 ? (
+      {!keyframeClip || !disclosable ? (
         <PlainTrackHeader
           trackNumber={trackNumber}
           trackDisplayNumber={trackDisplayNumber}
@@ -355,7 +489,15 @@ export function TimelineTrackHeader({
       ) : (
         <>
           <LayerDisclosureRow
-            keyframeClip={keyframeClip}
+            name={
+              // A row holding several clips is named for the track, not for
+              // whichever of them is selected — the lanes below it are the
+              // track's, shared per property, and naming it "Narration 2" read
+              // as if they all belonged to that one slice.
+              clipCount > 1
+                ? `Track${trackDisplaySuffix(trackDisplayNumber)}`
+                : (keyframeClip.label ?? keyframeClip.domId ?? keyframeClip.id)
+            }
             clipCount={clipCount}
             isExpanded={isExpanded}
             gutterBackground={theme.gutterBackground}
@@ -391,7 +533,7 @@ export function TimelineTrackHeader({
                 lanesId={lanesId}
                 lane={lane}
                 laneIndex={laneIndex}
-                isLastLane={laneIndex === lanes.length - 1}
+                isLastLane={laneIndex === lanes.length - 1 && automationRows.length === 0}
                 expandedElement={keyframeClip}
                 currentTime={currentTime}
                 clipPercentage={clipPercentage}
@@ -402,6 +544,24 @@ export function TimelineTrackHeader({
                 rovingTargetId={rovingTargetId}
               />
             ))}
+          {/* Below the keyframe rows and stepping by its own height, which is how
+              TimelineAutomationLaneSlot lays the envelopes out on the canvas. The
+              two have to agree or a name labels the wrong curve. */}
+          {isExpanded &&
+            automationRows.map((row, index) => (
+              <AutomationLaneHeaderRow
+                key={row.key}
+                target={row.target}
+                label={row.label}
+                name={row.name}
+                param={row.param}
+                top={getTimelineLaneTop(lanes.length) + index * AUTOMATION_LANE_H}
+                isLastLane={index === automationRows.length - 1}
+                gutterBackground={theme.gutterBackground}
+                columnWidth={showTrackLabel ? LABEL_COL_W : contentOrigin}
+                onRemove={onRemoveAutomationLane}
+              />
+            ))}
         </>
       )}
     </div>

package/src/player/components/TimelineTrackRow.tsx

@@ -7,7 +7,13 @@ interface TimelineTrackRowProps {
   rowKey: number;
   logicalRow: TimelineLogicalRow;
   propertyRows: readonly TimelineLogicalRow[];
+  /** Names the canvas-side content cell — the active clip's own property lanes,
+   *  minted with this single id in TimelinePropertyLanes. */
   lanesId: string;
+  /** Names the header cell. Space-separated because the caret it lives under
+   *  expands two disjoint subtrees (the clip's keyframe lanes AND the track's
+   *  automation lanes) — see TimelineTrackHeader for why they cannot share one id. */
+  headerLanesId: string;
   top: number;
   height: number;
   virtualized: boolean;
@@ -24,6 +30,7 @@ export function TimelineTrackRow({
   logicalRow,
   propertyRows,
   lanesId,
+  headerLanesId,
   top,
   height,
   virtualized,
@@ -78,7 +85,7 @@ export function TimelineTrackRow({
             <div
               role="rowheader"
               aria-colindex={1}
-              aria-owns={timelineLogicalRowCellId(lanesId, row.id, "header")}
+              aria-owns={timelineLogicalRowCellId(headerLanesId, row.id, "header")}
             >
               {group}
             </div>

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

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  clearAutomationClipboard,
+  copyRange,
+  pastePoints,
+  readClipboard,
+} from "./automationClipboard";
+import { resolveAutomationRange, VOLUME_RANGE } from "@hyperframes/core/audio-automation";
+import type { HfAutomationLane } from "@hyperframes/core/audio-automation";
+
+const duck: HfAutomationLane = {
+  target: "volume",
+  points: [
+    { t: 2, v: 1, curve: -0.4 },
+    { t: 3, v: 0.25 },
+    { t: 4, v: 1 },
+  ],
+};
+
+beforeEach(clearAutomationClipboard);
+
+describe("automation clipboard", () => {
+  it("copies the range rebased to zero", () => {
+    copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+    const entry = readClipboard("project-a");
+    expect(entry?.span).toBe(2);
+    expect(entry?.points.map((p) => p.t)).toEqual([0, 1, 2]);
+    expect(entry?.points[0]?.curve).toBe(-0.4);
+  });
+
+  it("pastes at a new time on the same axis unchanged", () => {
+    copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+    const entry = readClipboard("project-a");
+    expect(entry).not.toBeNull();
+    if (!entry) return;
+    const pts = pastePoints(entry, VOLUME_RANGE, 10);
+    expect(pts.map((p) => p.t)).toEqual([10, 11, 12]);
+    expect(pts.map((p) => p.v)).toEqual([1, 0.25, 1]);
+  });
+
+  it("maps values through unit space onto a different parameter", () => {
+    // fx.n1.frequency (lowpass cutoff) is log-scaled (min:20, max:20000):
+    // linear unit math and a literal copy of the source value would both
+    // read as a passing test on a range that happens to be numerically
+    // identical to VOLUME_RANGE (e.g. fx.r.wet), so this target has to be
+    // genuinely log for the test to discriminate real unit-space mapping.
+    const frequency = resolveAutomationRange("fx.n1.frequency", {
+      version: 1,
+      nodes: [{ type: "lowpass", id: "n1", params: {} }],
+    });
+    expect(frequency).toBeTruthy();
+    if (!frequency) return;
+    expect(frequency.scale).toBe("log");
+    copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+    const entry = readClipboard("project-a");
+    if (!entry) return;
+    const pts = pastePoints(entry, frequency, 0);
+    // volume 1 (unit 1) → frequency max; volume 0.25 (unit 0.25) → a quarter
+    // up frequency's LOG axis, i.e. exp(ln(min) + 0.25*(ln(max)-ln(min))) —
+    // NOT the naive linear guess (min + 0.25*(max-min)) and nowhere near a
+    // literal copy of 0.25.
+    expect(pts[0]?.v).toBeCloseTo(frequency.max, 5);
+    const expectedLog = Math.exp(
+      Math.log(frequency.min) + 0.25 * (Math.log(frequency.max) - Math.log(frequency.min)),
+    );
+    const naiveLinear = frequency.min + 0.25 * (frequency.max - frequency.min);
+    expect(pts[1]?.v).toBeCloseTo(expectedLog, 5);
+    expect(pts[1]?.v).not.toBeCloseTo(naiveLinear, 0);
+    expect(pts[1]?.v).not.toBeCloseTo(0.25, 0);
+  });
+
+  it("reads null when nothing was copied", () => {
+    expect(readClipboard("project-a")).toBeNull();
+  });
+
+  it("does not hand a range copied in one project to another", () => {
+    copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+    expect(readClipboard("project-b")).toBeNull();
+  });
+
+  it("drops the entry for good once another project has read past it", () => {
+    copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+    readClipboard("project-b");
+    // Not merely hidden from B: switching back must not resurrect a shape whose
+    // source clip may have been edited or deleted while the project was closed.
+    expect(readClipboard("project-a")).toBeNull();
+  });
+
+  it("keeps serving the entry inside its own project", () => {
+    copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+    expect(readClipboard("project-a")?.span).toBe(2);
+    expect(readClipboard("project-a")?.span).toBe(2);
+  });
+});