@hyperframes/studio 0.7.106 → 0.7.108

package/src/player/components/automationLaneData.ts

@@ -0,0 +1,258 @@
+/**
+ * Reading an element's automation, shared by the lane UI and the row layout.
+ *
+ * The attributes are carried on TimelineElement verbatim rather than parsed at
+ * the manifest boundary: the lane reads and writes them, and round-tripping
+ * through the attribute is what keeps the lane, the property panel and the
+ * running audio graph on one source of truth.
+ *
+ * Both parse the same two attributes: the layout needs the lane count to
+ * reserve height, the lanes need the lanes themselves. Parsing is cached by the
+ * attribute text so the identity only changes when the text does — the lane's
+ * drag draft compares against that identity, and a fresh object on every
+ * playhead tick would throw away the drag in progress.
+ */
+
+import {
+  parseAutomation,
+  parseAutomationTarget,
+  resolveAutomation,
+  resolveAutomationRange,
+  type HfAutomation,
+  type HfAutomationLane,
+} from "@hyperframes/core/audio-automation";
+import { parseAudioFxChain, type HfAudioFxChain } from "@hyperframes/core/audio-fx";
+import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import type { TimelineElement } from "../store/playerStore";
+
+const EMPTY: HfAutomation = { version: 1, lanes: [] };
+
+const chainCache = new Map<string, HfAudioFxChain | null>();
+const automationCache = new Map<string, HfAutomation>();
+const CACHE_LIMIT = 64;
+
+/**
+ * Parse once per distinct attribute text, keeping the same object until the text
+ * changes — the lane compares its drag draft against that identity.
+ *
+ * Eviction drops the oldest entry rather than clearing the map: clearing would
+ * change the identity of every lane's automation at once, and any lane mid-drag
+ * would release its draft and jump back to the stored value.
+ */
+function cached<T>(store: Map<string, T>, key: string, build: () => T): T {
+  const hit = store.get(key);
+  if (hit !== undefined) {
+    // Re-insert so the entry counts as recently used.
+    store.delete(key);
+    store.set(key, hit);
+    return hit;
+  }
+  const value = build();
+  if (store.size >= CACHE_LIMIT) {
+    const oldest = store.keys().next();
+    if (!oldest.done) store.delete(oldest.value);
+  }
+  store.set(key, value);
+  return value;
+}
+
+/** The element's FX chain, or null when it has none or it is unreadable. */
+export function elementFxChain(element: TimelineElement): HfAudioFxChain | null {
+  const raw = element.fxChain;
+  if (!raw) return null;
+  return cached(chainCache, raw, () => {
+    try {
+      return parseAudioFxChain(raw);
+    } catch {
+      return null;
+    }
+  });
+}
+
+/**
+ * The element's automation, bound to its chain the same way preview and the
+ * render bind it: a lane whose effect has been deleted is dropped rather than
+ * drawn on the wrong axis.
+ */
+export function elementAutomation(element: TimelineElement): HfAutomation {
+  const raw = element.automation;
+  if (!raw) return EMPTY;
+  const chain = elementFxChain(element);
+  // Both texts key the entry: the resolved lanes depend on the chain too. Joined
+  // through a separator no attribute can contain.
+  return cached(automationCache, `${raw}\u0000${element.fxChain ?? ""}`, () => {
+    try {
+      const resolved = resolveAutomation(parseAutomation(raw), chain ?? undefined);
+      return { ...resolved, lanes: orderLanes(resolved.lanes, chain) };
+    } catch {
+      // Unreadable automation draws no lanes rather than breaking the row.
+      return EMPTY;
+    }
+  });
+}
+
+/** Lanes in the order they are drawn, one row each. */
+export function elementAutomationLanes(element: TimelineElement): HfAutomationLane[] {
+  return elementAutomation(element).lanes;
+}
+
+/** The frequency the lane's effect sits at, when it has one. */
+function laneFrequency(target: string, chain: HfAudioFxChain | null): number | null {
+  const parsed = parseAutomationTarget(target);
+  if (!parsed || parsed.kind !== "fx") return null;
+  const node = chain?.nodes.find((n) => n.id === parsed.nodeId);
+  const freq = node?.params?.["frequency"];
+  return typeof freq === "number" ? freq : null;
+}
+
+/**
+ * Lane order: the audible spectrum, top down, then everything else.
+ *
+ * A stack of EQ bands is read as a spectrum, so it has to be laid out like one —
+ * high at the top, the way every analyser and every EQ curve is drawn. Attribute
+ * order is whatever minted the nodes, which for a carve is ascending: exactly
+ * upside down. Lanes with no frequency to place them — a level stage, the track's
+ * own volume — keep their written order and sit under the bands, like a fader
+ * below the EQ section of a channel strip.
+ *
+ * Sorted here, in the one function both the canvas lanes and the label column
+ * read, because a label whose row disagrees with the envelope it names is worse
+ * than either order.
+ */
+function orderLanes(lanes: HfAutomationLane[], chain: HfAudioFxChain | null): HfAutomationLane[] {
+  const withFreq: { lane: HfAutomationLane; freq: number }[] = [];
+  const rest: HfAutomationLane[] = [];
+  for (const lane of lanes) {
+    const freq = laneFrequency(lane.target, chain);
+    if (freq === null) rest.push(lane);
+    else withFreq.push({ lane, freq });
+  }
+  withFreq.sort((a, b) => b.freq - a.freq);
+  return [...withFreq.map((e) => e.lane), ...rest];
+}
+
+/** A frequency as an author reads it: 400 Hz, 1.6 kHz, 10 kHz. */
+export function formatHz(freq: number): string {
+  if (freq < 1000) return `${Math.round(freq)} Hz`;
+  const k = freq / 1000;
+  return `${k >= 10 ? Math.round(k) : Number(k.toFixed(1))} kHz`;
+}
+
+/**
+ * What a lane is called in the timeline, as its two lines.
+ *
+ * `name` is the effect and, when it has one, the frequency it sits at: "Peaking
+ * EQ 1.6 kHz". The frequency is what tells two bands apart — three lanes all
+ * reading "Peaking EQ" say nothing about which is which — and the effect still
+ * has to be named, since a chain mixes filter types and a bare frequency does not
+ * say whether it is a bell or a shelf.
+ *
+ * `param` is which knob the envelope drives, on its own line: a band can carry a
+ * gain lane and a Q lane, and stacking the two lines is what keeps a name legible
+ * in a column this narrow instead of truncating mid-word.
+ *
+ * Null when the target does not resolve against the chain — the same condition
+ * that stops the lane being drawn at all.
+ */
+export function automationLaneLabelParts(
+  target: string,
+  chain: HfAudioFxChain | null,
+): { name: string; param: string } | null {
+  const range = resolveAutomationRange(target, chain ?? undefined);
+  if (!range) return null;
+  // The registry's label is "<effect> · <param>", or just "<param>" for volume.
+  const parts = range.label.split(" · ");
+  const param = parts.at(-1) ?? range.label;
+  const effect = parts.length > 1 ? parts.slice(0, -1).join(" · ") : null;
+  const freq = laneFrequency(target, chain);
+  const name = [effect, freq === null ? null : formatHz(freq)].filter(Boolean).join(" ");
+  return { name: name || param, param: name ? param : "" };
+}
+
+/**
+ * What makes two lanes, on two different clips, the same lane row.
+ *
+ * A lane is a property over time, not a clip's private strip: four narration slices
+ * on one track that each automate a 1 kHz peaking Q belong in ONE row, each drawing
+ * its envelope over its own span.
+ *
+ * The key cannot be the lane target. Targets are `fx.<nodeId>.<param>` and node ids
+ * are minted per chain, so `fx.n1.q` on one clip and `fx.n1.q` on another may be
+ * different effects entirely — grouping by target would put unrelated envelopes in
+ * one row and split matching ones apart. So the key is what identifies the parameter
+ * to a reader: the effect, whatever distinguishes it from its siblings (a filter's
+ * frequency), and the parameter. Which is exactly what the label already says, so
+ * the row's identity and its name cannot drift apart.
+ *
+ * Null when the target does not resolve, the same condition that stops it drawing.
+ */
+export function laneGroupKey(target: string, chain: HfAudioFxChain | null): string | null {
+  return automationLaneLabel(target, chain);
+}
+
+/** One clip's envelope inside a shared row: the clip, and the lane it draws. */
+export interface AutomationLaneGroupEntry {
+  element: TimelineElement;
+  lane: HfAutomationLane;
+}
+
+/** A lane row on a track: one property, and every clip that automates it. */
+export interface AutomationLaneGroup {
+  /** {@link laneGroupKey} — the row's identity, and also its whole label. */
+  key: string;
+  /** The label's two lines, as {@link automationLaneLabelParts} splits them. */
+  name: string;
+  param: string;
+  /** In track order. A clip that does not automate this property is simply
+   *  absent, leaving its stretch of the row empty. */
+  entries: AutomationLaneGroupEntry[];
+}
+
+/**
+ * The lane rows a TRACK shows, unioned over the clips sharing it.
+ *
+ * Several clips on one row (four narration slices, say) each carry their own
+ * chain and their own envelopes. Drawing only the selected clip's made a per-clip
+ * lane read as governing the whole row, and swapped which envelopes were visible
+ * whenever the selection moved. So the row is keyed by the property — a clip
+ * draws into the row for `Peaking EQ 1 kHz · Q` over its own span, and clips that
+ * automate nothing there leave it empty.
+ *
+ * Row order is first-seen: each clip's lanes are already in draw order (the
+ * 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.
+ */
+export function groupAutomationLanes(elements: readonly TimelineElement[]): AutomationLaneGroup[] {
+  const groups = new Map<string, AutomationLaneGroup>();
+  for (const element of elements) {
+    if (!isAudioTimelineElement(element)) continue;
+    const chain = elementFxChain(element);
+    for (const lane of elementAutomationLanes(element)) {
+      const key = laneGroupKey(lane.target, chain);
+      const parts = automationLaneLabelParts(lane.target, chain);
+      // Null on both together: an unresolvable target draws no lane either.
+      if (!key || !parts) continue;
+      const group = groups.get(key);
+      if (group) group.entries.push({ element, lane });
+      else {
+        groups.set(key, {
+          key,
+          name: parts.name,
+          param: parts.param,
+          entries: [{ element, lane }],
+        });
+      }
+    }
+  }
+  return [...groups.values()];
+}
+
+/** The whole label on one line, for a tooltip or an accessible name. */
+export function automationLaneLabel(target: string, chain: HfAudioFxChain | null): string | null {
+  const parts = automationLaneLabelParts(target, chain);
+  if (!parts) return null;
+  return parts.param ? `${parts.name} · ${parts.param}` : parts.name;
+}

package/src/player/components/automationLaneDragMath.ts

@@ -0,0 +1,194 @@
+/**
+ * Pure position math for the two multi-point drags on an automation lane: a
+ * group move (dragging a whole box-selected set by one delta) and a single
+ * point's move (the modifiers and neighbour clamp one breakpoint honours).
+ *
+ * Split out of useAutomationLaneGestures.ts so the hook's own onPointerDown
+ * and movePoint stay orchestration — read the pointer, call one of these,
+ * apply the result — rather than carrying this branching themselves.
+ */
+
+import type { AutomationRange, HfAutomationLane } from "@hyperframes/core/audio-automation";
+import {
+  applyShiftConstraint,
+  dominantDragAxis,
+  MIN_POINT_GAP_SEC,
+  snapLaneTime,
+} from "./automationLaneGeometry";
+import { pointInSelection } from "./automationLaneSelection";
+
+/** Snap radius in clip seconds, shared with the single-point and group drags. */
+export const SNAP_SEC = 0.04;
+
+export type AutomationSelectionBox = { t0: number; t1: number; v0: number; v1: number };
+
+/** Which points a press on `pressed` should drag together: the whole box-selected
+ *  set if it contains more than one member, otherwise none (an ordinary
+ *  single-point drag, selection or no). */
+function resolveGroupDragIndices(
+  lane: HfAutomationLane,
+  pressed: HfAutomationLane["points"][number] | undefined,
+  rangeSelection: AutomationSelectionBox | null | undefined,
+): number[] {
+  if (!rangeSelection || !pressed || !pointInSelection(pressed, rangeSelection)) return [];
+  return lane.points.flatMap((p, i) => (pointInSelection(p, rangeSelection) ? [i] : []));
+}
+
+export interface GroupDragSnapshot {
+  points: HfAutomationLane["points"];
+  indices: number[];
+  anchor: { t: number; v: number };
+  selection: AutomationSelectionBox;
+}
+
+/** Snapshot to arm a group drag from a press on `pressed`, or null when the
+ *  press does not land on a multi-point selection — an ordinary single-point
+ *  drag, selection or no. */
+export function armGroupDrag(
+  lane: HfAutomationLane,
+  pressed: HfAutomationLane["points"][number] | undefined,
+  rangeSelection: AutomationSelectionBox | null | undefined,
+): GroupDragSnapshot | null {
+  const indices = resolveGroupDragIndices(lane, pressed, rangeSelection);
+  if (indices.length <= 1 || !pressed) return null;
+  return {
+    points: lane.points.map((p) => ({ ...p })),
+    indices,
+    anchor: { t: pressed.t, v: pressed.v },
+    selection: rangeSelection ? { ...rangeSelection } : { t0: 0, t1: 0, v0: 0, v1: 0 },
+  };
+}
+
+export interface GroupMoveResult {
+  points: HfAutomationLane["points"];
+  selection: AutomationSelectionBox;
+  hint: string;
+}
+
+/**
+ * Move a selected set by one delta, taken from the point under the pointer.
+ *
+ * The whole group has to stop when its first member reaches a boundary, not
+ * each point on its own: clamping individually squashes the shape flat against
+ * the edge, and the gesture is meant to preserve it. Deltas are in the
+ * parameter's own units, so on a logarithmic axis a group moves by Hz rather
+ * than by octaves — the same as dragging one point does.
+ */
+export function computeGroupMove(input: {
+  group: GroupDragSnapshot;
+  raw: { t: number; v: number };
+  shiftKey: boolean;
+  altKey: boolean;
+  range: AutomationRange;
+  duration: number;
+  snapTimes: readonly number[] | undefined;
+  xOf(t: number): number;
+  yOf(v: number): number;
+}): GroupMoveResult {
+  const { group, raw, shiftKey, altKey, range, duration, snapTimes, xOf, yOf } = input;
+  const moving = group.indices.map((i) => group.points[i]!);
+  let dt = raw.t - group.anchor.t;
+  let dv = raw.v - group.anchor.v;
+  if (shiftKey) {
+    // The axis lock, as a single-point drag has it: keep whichever the pointer
+    // has travelled further along and drop the other.
+    const alongTime = Math.abs(dt * (xOf(1) - xOf(0)));
+    const alongValue = Math.abs((dv * (yOf(range.min) - yOf(range.max))) / (range.max - range.min));
+    if (alongTime >= alongValue) dv = 0;
+    else dt = 0;
+  } else if (!altKey) {
+    // Snap the point under the pointer, and move the set by that same amount.
+    const others = group.points.filter((_, i) => !group.indices.includes(i)).map((p) => p.t);
+    dt =
+      snapLaneTime(group.anchor.t + dt, [...(snapTimes ?? []), ...others], SNAP_SEC) -
+      group.anchor.t;
+  }
+  const times = moving.map((p) => p.t);
+  const values = moving.map((p) => p.v);
+  // No member may cross a point that is staying put. Only stationary
+  // neighbours constrain: two selected points travel together, so the gap
+  // between them never changes. Per member rather than per end of the group,
+  // because a box can select a non-contiguous set — the peaks of an envelope
+  // and not the dip between them.
+  const gapTo = (step: 1 | -1): number[] =>
+    group.indices.flatMap((i) => {
+      const neighbour = group.points[i + step];
+      if (!neighbour || group.indices.includes(i + step)) return [];
+      // Short of the neighbour, not onto it — the lane collapses points that
+      // share a time, and a group drag must not consume what it runs into.
+      return [Math.max(0, Math.abs(neighbour.t - group.points[i]!.t) - MIN_POINT_GAP_SEC)];
+    });
+  dt = Math.min(
+    Math.max(dt, -Math.min(Math.min(...times), ...gapTo(-1))),
+    Math.min(duration - Math.max(...times), ...gapTo(1)),
+  );
+  dv = Math.min(Math.max(dv, range.min - Math.min(...values)), range.max - Math.max(...values));
+
+  // No re-sort: clamped to the neighbours, the lane's order cannot change
+  // under a drag, so the point under the pointer keeps its index.
+  const points = group.points.map((p, i) =>
+    group.indices.includes(i) ? { ...p, t: p.t + dt, v: p.v + dv } : p,
+  );
+  return {
+    points,
+    // The box travels with the points — both axes, or a vertical nudge would
+    // slide its own points out of the box that caught them and a second nudge
+    // would move fewer of them.
+    selection: {
+      t0: group.selection.t0 + dt,
+      t1: group.selection.t1 + dt,
+      v0: group.selection.v0 + dv,
+      v1: group.selection.v1 + dv,
+    },
+    hint: `${group.indices.length} points ${dt >= 0 ? "+" : ""}${dt.toFixed(2)}s`,
+  };
+}
+
+/** Where Shift last locked a single-point drag's axis. */
+export type ShiftAxis = "time" | "value" | null;
+
+/** The clip-local time and value a single dragged point should land on,
+ *  honouring the modifiers held with it and the neighbours it cannot cross. */
+export function computeSinglePointMove(input: {
+  raw: { t: number; v: number };
+  origin: { t: number; v: number } | null;
+  shiftKey: boolean;
+  altKey: boolean;
+  shiftAxis: ShiftAxis;
+  range: AutomationRange;
+  duration: number;
+  snapTimes: readonly number[] | undefined;
+  lane: HfAutomationLane;
+  dragIndex: number;
+  xOf(t: number): number;
+  yOf(v: number): number;
+}): { t: number; v: number; shiftAxis: ShiftAxis } {
+  const { raw, origin, shiftKey, altKey, range, duration, snapTimes, lane, dragIndex, xOf, yOf } =
+    input;
+  let shiftAxis = shiftKey ? input.shiftAxis : null;
+  let { t, v } = raw;
+  if (shiftKey && origin) {
+    shiftAxis ??= dominantDragAxis({ origin, raw, xOf, yOf });
+    ({ t, v } = applyShiftConstraint({ range, origin, raw, xOf, yOf, axis: shiftAxis }));
+  }
+  // Shift is a deliberate free-hand move as much as Alt is, so neither snaps.
+  if (!altKey && !shiftKey) {
+    const neighbours = lane.points.filter((_, i) => i !== dragIndex).map((p) => p.t);
+    t = snapLaneTime(t, [...(snapTimes ?? []), ...neighbours], SNAP_SEC);
+  }
+  // A breakpoint cannot cross another in time, and cannot land exactly on one
+  // either: the lane collapses points that share a `t`, so arriving on top of a
+  // neighbour deletes it. It stops a hair short instead, which reads as touching
+  // and keeps both points. Applied after the snap, which can itself put the
+  // point on a beat past a neighbour.
+  const floor = (lane.points[dragIndex - 1]?.t ?? -Infinity) + MIN_POINT_GAP_SEC;
+  const ceiling = (lane.points[dragIndex + 1]?.t ?? Infinity) - MIN_POINT_GAP_SEC;
+  const held = lane.points[dragIndex]?.t ?? t;
+  t =
+    ceiling >= floor
+      ? Math.min(ceiling, Math.max(floor, Math.min(duration, Math.max(0, t))))
+      : // Neighbours closer together than the gap leave nowhere to go, so the
+        // point stays where it is rather than being flung to one side.
+        held;
+  return { t, v, shiftAxis };
+}

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

@@ -0,0 +1,239 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import {
+  applyShiftConstraint,
+  automationTargets,
+  curveForDrag,
+  fromUnit,
+  snapLaneTime,
+  toUnit,
+} from "./automationLaneGeometry";
+import { applyCurve, sampleAutomationLane } from "@hyperframes/core/audio-automation";
+import { resolveAutomationRange, VOLUME_RANGE } from "@hyperframes/core/audio-automation";
+import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+
+const chain: HfAudioFxChain = {
+  version: 1,
+  nodes: [
+    { type: "lowpass", id: "n1", enabled: true, params: {} },
+    // No id: the panel has not touched it, so nothing can address it.
+    { type: "peaking", enabled: true, params: {} },
+    // Worklet-backed: no AudioParams to schedule.
+    { type: "compressor", id: "n3", enabled: true, params: {} },
+  ],
+};
+
+describe("automationTargets", () => {
+  it("offers volume plus every addressable automatable knob", () => {
+    const targets = automationTargets(chain).map((t) => t.target);
+    expect(targets[0]).toBe("volume");
+    expect(targets).toContain("fx.n1.frequency");
+    expect(targets).toContain("fx.n1.q");
+  });
+
+  it("skips a node with no id — a lane could not address it stably", () => {
+    expect(automationTargets(chain).some((t) => t.target.includes("peaking"))).toBe(false);
+  });
+
+  it("skips a worklet effect, which exposes no AudioParams", () => {
+    expect(automationTargets(chain).some((t) => t.target.startsWith("fx.n3."))).toBe(false);
+  });
+
+  it("offers just the fader for a track with no chain", () => {
+    expect(automationTargets(null).map((t) => t.target)).toEqual(["volume"]);
+  });
+
+  it("labels an fx target with its effect and knob", () => {
+    const found = automationTargets(chain).find((t) => t.target === "fx.n1.frequency");
+    expect(found?.label).toMatch(/Cutoff/);
+    expect(found?.range.scale).toBe("log");
+  });
+});
+
+describe("value ↔ lane position", () => {
+  it("maps a linear range straight onto the lane", () => {
+    expect(toUnit(VOLUME_RANGE, 0)).toBe(0);
+    expect(toUnit(VOLUME_RANGE, 1)).toBe(1);
+    expect(toUnit(VOLUME_RANGE, 0.25)).toBeCloseTo(0.25, 10);
+  });
+
+  it("maps a log-read knob on its own scale, so its middle is geometric", () => {
+    const range = resolveAutomationRange("fx.n1.frequency", chain)!;
+    const mid = fromUnit(range, 0.5);
+    expect(mid).toBeCloseTo(Math.sqrt(range.min * range.max), 4);
+    // Round trip: a value put in comes back out.
+    expect(fromUnit(range, toUnit(range, 900))).toBeCloseTo(900, 6);
+  });
+
+  it("clamps a pointer that has left the lane", () => {
+    expect(fromUnit(VOLUME_RANGE, -3)).toBe(0);
+    expect(fromUnit(VOLUME_RANGE, 4)).toBe(1);
+  });
+
+  it("reads a zero-width range as the bottom rather than dividing by zero", () => {
+    expect(toUnit({ ...VOLUME_RANGE, min: 1, max: 1 }, 1)).toBe(0);
+  });
+});
+
+describe("curveForDrag", () => {
+  const a = { t: 0, v: 1 };
+  const b = { t: 4, v: 0 };
+
+  /** The segment the drag describes, as the model would store it. */
+  const bentLane = (bend: { viaX: number; viaY: number } | null) => ({
+    target: "volume",
+    points: [{ ...a, ...(bend ?? {}) }, b],
+  });
+
+  it("puts the curved segment through the point that was dragged", () => {
+    // The whole contract: sampling the segment at the dragged time gives the dragged
+    // value back, so the line never runs away from the pointer. Anywhere in the
+    // segment, at any depth.
+    for (const [t, v] of [
+      [0.4, 0.75],
+      [1.6, 0.65],
+      [2, 0.6],
+      [2, 0.1],
+      [2.8, 0.4],
+      [3.6, 0.5],
+    ] as const) {
+      const bend = curveForDrag({ range: VOLUME_RANGE, a, b, t, v });
+      expect(bend).not.toBeNull();
+      expect(sampleAutomationLane(bentLane(bend), t, "linear")).toBeCloseTo(v, 2);
+    }
+  });
+
+  it("follows the pointer into the corner of a segment, as deep as it is dragged", () => {
+    // The extreme: 10% along, pulled almost to the floor of a falling ramp. The old
+    // exponent saturated a third of the segment away from the pointer, and a later
+    // slope cap stopped following it too. Reached exactly now, and the shape it draws
+    // stays one smooth arc — checked by sampling it, not by trusting it.
+    const bend = curveForDrag({ range: VOLUME_RANGE, a, b, t: 0.4, v: 0.05 });
+    expect(bend).not.toBeNull();
+    const drawn = bentLane(bend);
+    expect(sampleAutomationLane(drawn, 0.4, "linear")).toBeCloseTo(0.05, 2);
+
+    let previous: number | null = null;
+    let worst = 1;
+    for (let i = 1; i < 60; i += 1) {
+      const t = (4 * i) / 60;
+      const h = 0.01;
+      const slope =
+        (sampleAutomationLane(drawn, t + h, "linear") -
+          sampleAutomationLane(drawn, t - h, "linear")) /
+        (2 * h);
+      if (previous !== null && Math.abs(previous) > 1e-6) {
+        const ratio = Math.abs(slope) > Math.abs(previous) ? slope / previous : previous / slope;
+        worst = Math.max(worst, Math.abs(ratio));
+      }
+      previous = slope;
+    }
+    // Gradual: a crease would show up here as a step change in slope.
+    expect(worst).toBeLessThan(3);
+  });
+
+  it("biases the bend toward whichever point the pointer is nearer", () => {
+    // The behaviour a single exponent could not give: grabbing the line near the
+    // right-hand point has to bulge it on the RIGHT. Measured as where the curve
+    // deviates furthest from the straight line it replaced.
+    const apexOf = (bend: { viaX: number; viaY: number } | null): number => {
+      const lane = bentLane(bend);
+      let best = 0;
+      let at = 0;
+      for (let i = 1; i < 40; i++) {
+        const t = (4 * i) / 40;
+        const straight = 1 - t / 4;
+        const gap = Math.abs(sampleAutomationLane(lane, t, "linear") - straight);
+        if (gap > best) {
+          best = gap;
+          at = t;
+        }
+      }
+      return at;
+    };
+    const nearA = curveForDrag({ range: VOLUME_RANGE, a, b, t: 0.6, v: 0.55 });
+    const nearB = curveForDrag({ range: VOLUME_RANGE, a, b, t: 3.4, v: 0.45 });
+    expect(apexOf(nearA)).toBeLessThan(1.6);
+    expect(apexOf(nearB)).toBeGreaterThan(2.4);
+    // And the two sit on opposite sides of centre, which is the whole complaint:
+    // every bend used to land on the same side whatever the pointer did.
+    expect(apexOf(nearA)).toBeLessThan(apexOf(nearB));
+  });
+
+  it("stays inside the normalised segment the model will accept", () => {
+    // Both coordinates are clamped clear of the ends on parse, so a drag right up
+    // against a breakpoint has to describe an interior point, not the breakpoint.
+    const bend = curveForDrag({ range: VOLUME_RANGE, a, b, t: 0.05, v: 0.02 });
+    expect(bend).not.toBeNull();
+    expect(bend?.viaX).toBeGreaterThan(0);
+    expect(bend?.viaX).toBeLessThan(1);
+    expect(bend?.viaY).toBeGreaterThan(0);
+    expect(bend?.viaY).toBeLessThan(1);
+    expect(applyCurve(0.5, 0)).toBe(0.5);
+  });
+
+  it("declines a segment with no room to bend", () => {
+    // Flat: every curve draws the same line, so there is nothing to solve.
+    expect(curveForDrag({ range: VOLUME_RANGE, a, b: { t: 4, v: 1 }, t: 2, v: 0.5 })).toBeNull();
+    // At the very ends the exponent divides by zero.
+    expect(curveForDrag({ range: VOLUME_RANGE, a, b, t: 0, v: 1 })).toBeNull();
+    expect(curveForDrag({ range: VOLUME_RANGE, a, b, t: 4, v: 0 })).toBeNull();
+  });
+});
+
+describe("applyShiftConstraint", () => {
+  const origin = { t: 1, v: 0.5 };
+  const xOf = (t: number) => t * 100;
+  const yOf = (v: number) => (1 - v) * 40;
+
+  it("holds the value when the gesture is mostly sideways", () => {
+    const out = applyShiftConstraint({
+      range: VOLUME_RANGE,
+      origin,
+      raw: { t: 3, v: 0.55 },
+      xOf,
+      yOf,
+    });
+    expect(out).toEqual({ t: 3, v: 0.5 });
+  });
+
+  it("holds the time and fines the value when it is mostly vertical", () => {
+    const out = applyShiftConstraint({
+      range: VOLUME_RANGE,
+      origin,
+      raw: { t: 1.05, v: 0.9 },
+      xOf,
+      yOf,
+    });
+    expect(out.t).toBe(1);
+    // A quarter of the travel: 0.5 + (0.9 - 0.5) / 4.
+    expect(out.v).toBeCloseTo(0.6, 5);
+  });
+
+  it("decides which axis won in pixels, not in units", () => {
+    // 0.2 s against 0.2 of a fader are not comparable numbers; at this zoom the
+    // horizontal move is 20px and the vertical one is 8px.
+    const out = applyShiftConstraint({
+      range: VOLUME_RANGE,
+      origin,
+      raw: { t: 1.2, v: 0.7 },
+      xOf,
+      yOf,
+    });
+    expect(out.v).toBe(0.5);
+  });
+});
+
+describe("snapLaneTime", () => {
+  it("takes the nearest target inside the threshold", () => {
+    expect(snapLaneTime(2.02, [1, 2, 3], 0.04)).toBe(2);
+  });
+
+  it("leaves a time alone when nothing is close enough", () => {
+    expect(snapLaneTime(2.5, [1, 2, 3], 0.04)).toBe(2.5);
+  });
+
+  it("has nothing to snap to on an empty grid", () => {
+    expect(snapLaneTime(2.5, [], 0.04)).toBe(2.5);
+  });
+});