@hyperframes/studio 0.7.107 → 0.7.109

package/src/player/components/automationLaneGeometry.ts

@@ -0,0 +1,287 @@
+/**
+ * The maths behind an automation lane: which parameters it can offer, how a
+ * value maps to a position in the lane, and how a lane is edited.
+ *
+ * Pure — no React, no DOM. Split from the lane component so the geometry can be
+ * tested on its own, and so the component is left with the parts that genuinely
+ * need a pointer and a render.
+ */
+
+import {
+  fxAutomationTarget,
+  resolveAutomationRange,
+  sampleAutomationLane,
+  steadyViaPoint,
+  VOLUME_RANGE,
+  VOLUME_TARGET,
+  type AutomationRange,
+  type HfAutomation,
+  type HfAutomationLane,
+} from "@hyperframes/core/audio-automation";
+import { getAudioFxDef, type HfAudioFxChain } from "@hyperframes/core/audio-fx";
+
+/** Points nearer than this in clip seconds are the same point, not two. */
+export const POINT_MERGE_SEC = 0.02;
+
+/**
+ * Closest two breakpoints may sit in clip seconds while still being two points.
+ *
+ * A drag clamps to this short of its neighbour rather than onto it. Landing on the
+ * exact same time is not a step, it is a deletion: the lane's own normalisation
+ * collapses points that share a `t`, keeping the later one — so dragging a point
+ * fully into its neighbour used to consume that neighbour. A millisecond is under a
+ * pixel at any zoom the lane offers, so the two still read as touching.
+ */
+export const MIN_POINT_GAP_SEC = 0.001;
+/** Hit radius for grabbing a point, in px. */
+export const GRAB_PX = 7;
+/** Samples used to draw a segment the eye should see as curved. */
+export const DRAW_SAMPLES = 64;
+/**
+ * Slack on each side of the envelope, so a point sitting exactly at the clip's
+ * start or end is drawn whole instead of half outside the lane. Wide enough for
+ * the grab circle plus its stroke.
+ */
+export const PAD_X = GRAB_PX + 2;
+
+export interface AutomationTargetOption {
+  target: string;
+  label: string;
+  range: AutomationRange;
+}
+
+/**
+ * Everything this clip could automate: its fader, then each automatable knob of
+ * each effect in its chain. Effects with no chain node id are skipped — a lane
+ * has nothing stable to address them by (the panel mints ids as it adds nodes).
+ */
+export function automationTargets(chain: HfAudioFxChain | null): AutomationTargetOption[] {
+  const out: AutomationTargetOption[] = [
+    { target: VOLUME_TARGET, label: "Volume", range: VOLUME_RANGE },
+  ];
+  for (const node of chain?.nodes ?? []) {
+    out.push(...nodeTargets(node, chain));
+  }
+  return out;
+}
+
+/** One effect's automatable knobs. Empty for a node no lane could address. */
+function nodeTargets(
+  node: HfAudioFxChain["nodes"][number],
+  chain: HfAudioFxChain | null,
+): AutomationTargetOption[] {
+  const nodeId = node.id;
+  const def = nodeId ? getAudioFxDef(node.type) : undefined;
+  if (!nodeId || !def) return [];
+  const out: AutomationTargetOption[] = [];
+  for (const param of def.params) {
+    if (param.kind !== "number" || !param.automatable) continue;
+    const target = fxAutomationTarget(nodeId, param.key);
+    const range = resolveAutomationRange(target, chain ?? undefined);
+    if (range) out.push({ target, label: range.label, range });
+  }
+  return out;
+}
+
+/** Value → 0..1 up the lane, honouring a log-read knob's own scale. */
+export function toUnit(range: AutomationRange, value: number): number {
+  const { min, max } = range;
+  if (max <= min) return 0;
+  if (range.scale === "log" && min > 0 && value > 0) {
+    return (Math.log(value) - Math.log(min)) / (Math.log(max) - Math.log(min));
+  }
+  return (value - min) / (max - min);
+}
+
+export function fromUnit(range: AutomationRange, unit: number): number {
+  const t = Math.min(1, Math.max(0, unit));
+  const { min, max } = range;
+  if (range.scale === "log" && min > 0) {
+    return Math.exp(Math.log(min) + t * (Math.log(max) - Math.log(min)));
+  }
+  return min + t * (max - min);
+}
+
+export function formatValue(range: AutomationRange, value: number): string {
+  const decimals = range.step >= 1 ? 0 : range.step >= 0.1 ? 1 : 2;
+  const shown =
+    range.unit === "" && range.max === 1 ? `${Math.round(value * 100)}%` : value.toFixed(decimals);
+  return range.unit ? `${shown} ${range.unit}` : shown;
+}
+
+/**
+ * The via point that bends a segment through a dragged pointer: the pointer's own
+ * position in the segment's normalised space, which is all the model needs.
+ *
+ * There is nothing to solve any more, and that is the point. This used to fit an
+ * exponent — `x^e = f`, so `curve = log2(ln f / ln x) / 2` — and an exponent is
+ * one knob for two questions. It spent it on the wrong one: every upward bend it
+ * could draw deviated most inside the first fifth of the segment, so grabbing the
+ * line near its right-hand breakpoint still bulged it on the left. And reaching a
+ * pointer near either end needed an exponent the model refuses — `e` runs past 15
+ * at `x = 0.9`, clamped to 4 — so the line stopped following the pointer
+ * altogether, missing it by up to a third of the segment's height. Naming the
+ * point the curve passes through says both things at once, exactly, anywhere.
+ *
+ * Null when the segment cannot take a bend: a flat segment draws the same line
+ * whatever the shape, and a pointer at the very ends is the ends.
+ */
+export function curveForDrag(input: {
+  range: AutomationRange;
+  a: { t: number; v: number };
+  b: { t: number; v: number };
+  t: number;
+  v: number;
+}): { viaX: number; viaY: number } | null {
+  const { range, a, b, t, v } = input;
+  const span = b.t - a.t;
+  if (span <= 0) return null;
+  const x = (t - a.t) / span;
+  if (x <= 0.001 || x >= 0.999) return null;
+  const ua = toUnit(range, a.v);
+  const ub = toUnit(range, b.v);
+  if (Math.abs(ub - ua) < 0.001) return null;
+  const f = (toUnit(range, v) - ua) / (ub - ua);
+  if (f <= 0.001 || f >= 0.999) return null;
+  // Reported as the model will honour it, not as the pointer asked. A bend is held
+  // to a steady curve, so a pointer dragged past that stops being followed — and
+  // the write, the preview and the readout all have to say the same thing about
+  // where the line actually went.
+  return steadyViaPoint(x, f);
+}
+
+/**
+ * A point drag with Shift held: one axis at a time, whichever the gesture
+ * committed to, and a quarter of the vertical travel for a value that has to
+ * land on a number.
+ *
+ * Which axis "won" is decided in pixels, not in seconds and dB — those are
+ * different units and comparing them would make the lock depend on the zoom.
+ */
+/** Which way a gesture is going, in pixels — the only comparable unit. */
+export function dominantDragAxis(input: {
+  origin: { t: number; v: number };
+  raw: { t: number; v: number };
+  xOf(t: number): number;
+  yOf(v: number): number;
+}): "time" | "value" {
+  const { origin, raw, xOf, yOf } = input;
+  return Math.abs(xOf(raw.t) - xOf(origin.t)) > Math.abs(yOf(raw.v) - yOf(origin.v))
+    ? "time"
+    : "value";
+}
+
+/**
+ * The pointer, constrained to one axis.
+ *
+ * The axis is handed in rather than worked out here, because it has to be decided
+ * once for the gesture and held. Recomputed per event it followed whichever way
+ * the last move happened to lean, so a hand drifting sideways during a vertical
+ * drag flipped the lock and the point moved in both — which is indistinguishable
+ * from no lock at all.
+ *
+ * Locking to time holds the value exactly. Locking to value holds the time and
+ * moves the value at a quarter speed: the same gesture is the fine adjustment,
+ * because a fader spanning 60px of lane has no other way to be set precisely.
+ */
+export function applyShiftConstraint(input: {
+  range: AutomationRange;
+  origin: { t: number; v: number };
+  raw: { t: number; v: number };
+  /** Same projections the lane draws with, so the comparison is on screen. */
+  xOf(t: number): number;
+  yOf(v: number): number;
+  /** Decided on the gesture's first travel; worked out here when absent. */
+  axis?: "time" | "value";
+}): { t: number; v: number } {
+  const { range, origin, raw } = input;
+  const axis = input.axis ?? dominantDragAxis(input);
+  if (axis === "time") return { t: raw.t, v: origin.v };
+  const from = toUnit(range, origin.v);
+  return { t: origin.t, v: fromUnit(range, from + (toUnit(range, raw.v) - from) * 0.25) };
+}
+
+/**
+ * Nearest snap target within the threshold, else the time unchanged.
+ *
+ * A breakpoint is placed by eye, and by eye "on the beat" and "three
+ * milliseconds off the beat" look identical — so the lane snaps to the beat grid
+ * and to its own neighbouring points, the two things an envelope is usually
+ * aligned against.
+ */
+export function snapLaneTime(t: number, targets: readonly number[], thresholdSec: number): number {
+  let best = t;
+  let bestDist = thresholdSec;
+  for (const target of targets) {
+    const d = Math.abs(target - t);
+    if (d < bestDist) {
+      bestDist = d;
+      best = target;
+    }
+  }
+  return best;
+}
+
+/**
+ * The svg path for one lane's envelope.
+ *
+ * A flat line at the parameter's own default stands in for a lane with no
+ * points, so the first double-click has something to land on. Straight segments
+ * are drawn as one line each; a curved or log-read segment is sampled, because
+ * drawing it straight would lie about the envelope the audio thread is going to
+ * play.
+ */
+export function envelopePath(input: {
+  lane: HfAutomationLane;
+  range: AutomationRange;
+  widthPx: number;
+  xOf(t: number): number;
+  yOf(v: number): number;
+}): string {
+  const { lane, range, widthPx, xOf, yOf } = input;
+  const first = lane.points[0];
+  const last = lane.points[lane.points.length - 1];
+  if (!first || !last) {
+    const y = yOf(range.default ?? (range.min + range.max) / 2);
+    return `M ${PAD_X} ${y} L ${PAD_X + widthPx} ${y}`;
+  }
+  const pts = [`M ${PAD_X} ${yOf(first.v)}`, `L ${xOf(first.t)} ${yOf(first.v)}`];
+  for (let i = 0; i + 1 < lane.points.length; i += 1) {
+    const a = lane.points[i];
+    const b = lane.points[i + 1];
+    if (!a || !b) continue;
+    // A via point bends the segment with no `curve` of its own, so the
+    // straight-line shortcut has to rule out both.
+    if (!a.curve && a.viaX === undefined && range.scale === "linear") {
+      pts.push(`L ${xOf(b.t)} ${yOf(b.v)}`);
+      continue;
+    }
+    for (let k = 1; k <= DRAW_SAMPLES; k += 1) {
+      const t = a.t + ((b.t - a.t) * k) / DRAW_SAMPLES;
+      pts.push(`L ${xOf(t)} ${yOf(sampleAutomationLane(lane, t, range.scale))}`);
+    }
+  }
+  pts.push(`L ${PAD_X + widthPx} ${yOf(last.v)}`);
+  return pts.join(" ");
+}
+
+export function laneFor(automation: HfAutomation, target: string): HfAutomationLane {
+  return automation.lanes.find((l) => l.target === target) ?? { target, points: [] };
+}
+
+/**
+ * Replace one lane in place, dropping it when it has no points left.
+ *
+ * Order is preserved deliberately. A lane with no explicitly chosen parameter
+ * shows whichever comes first, so moving the edited one to the end would switch
+ * the lane out from under the pointer on the first edit.
+ */
+export function withLane(automation: HfAutomation, lane: HfAutomationLane): HfAutomation {
+  const empty = lane.points.length === 0;
+  const exists = automation.lanes.some((l) => l.target === lane.target);
+  const lanes = automation.lanes
+    .map((l) => (l.target === lane.target ? lane : l))
+    .filter((l) => l.points.length > 0);
+  if (!exists && !empty) lanes.push(lane);
+  return { version: 1, lanes };
+}

package/src/player/components/automationLaneHeight.ts

@@ -0,0 +1,15 @@
+/**
+ * Height of one audio automation lane.
+ *
+ * Its own module because both the row layout and the lane itself need it, and
+ * putting it in either would have the layout importing a component or the
+ * component's constant living somewhere it is not used.
+ *
+ * Taller than a keyframe lane because it carries a value axis rather than a row
+ * of diamonds: a fader envelope drawn 28px high cannot be aimed. 48 was still
+ * too tight in use — the drawing area is the height minus 6px of padding either
+ * side, so 48 left 36px for the whole 0..1 fader and a breakpoint's 11px grab
+ * disc covered a third of the axis. 72 leaves 60px, which is what makes a value
+ * aimable and two points at similar values separately grabbable.
+ */
+export const AUTOMATION_LANE_H = 72;

package/src/player/components/automationLanePointer.ts

@@ -0,0 +1,20 @@
+/**
+ * Pointer capture for a lane gesture. Its own module only because both gesture
+ * hooks need it and `automationLaneGeometry` is deliberately DOM-free.
+ */
+
+/**
+ * Keep the rest of a gesture even if the pointer leaves the lane. Without it a
+ * drag that strays outside the svg stops sending moves and the point sticks.
+ *
+ * Captured on the svg the handler is bound to, NOT on `e.target`: the target is
+ * whatever child the press happened to land on — a breakpoint circle, a
+ * selection line — and a child that unmounts mid-drag takes the capture with it,
+ * silently and with no `pointercancel` to notice it by. The svg outlives every
+ * gesture on it.
+ *
+ * Structurally typed so this stays testable without React's event types.
+ */
+export function capturePointer(e: { currentTarget: Element; pointerId: number }): void {
+  e.currentTarget.setPointerCapture?.(e.pointerId);
+}

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

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import { pointsIn, replaceRange, retimeRange } from "./automationLaneSelection";
+import { sampleAutomationLane, VOLUME_RANGE } from "@hyperframes/core/audio-automation";
+import type { HfAutomationLane } from "@hyperframes/core/audio-automation";
+
+const ramp: HfAutomationLane = {
+  target: "volume",
+  points: [
+    { t: 0, v: 1 },
+    { t: 2, v: 0.6 },
+    { t: 3, v: 0.4 },
+    { t: 6, v: 0 },
+  ],
+};
+
+describe("pointsIn", () => {
+  it("returns only the points inside the range, endpoints inclusive", () => {
+    expect(pointsIn(ramp, 2, 3).map((p) => p.t)).toEqual([2, 3]);
+    expect(pointsIn(ramp, 2.1, 2.9)).toEqual([]);
+  });
+});
+
+describe("replaceRange", () => {
+  it("never moves the envelope outside the selection", () => {
+    // THE invariant. Deleting the middle of a ramp must not reshape the rest.
+    const next: HfAutomationLane = {
+      target: "volume",
+      points: replaceRange({ lane: ramp, range: VOLUME_RANGE, t0: 1.5, t1: 3.5, inner: [] }),
+    };
+    for (const t of [0, 0.5, 1.0, 1.5, 3.5, 4, 5, 6]) {
+      expect(sampleAutomationLane(next, t, "linear")).toBeCloseTo(
+        sampleAutomationLane(ramp, t, "linear"),
+        5,
+      );
+    }
+  });
+
+  it("pins anchors at both edges when the interior empties", () => {
+    const pts = replaceRange({ lane: ramp, range: VOLUME_RANGE, t0: 1.5, t1: 3.5, inner: [] });
+    const times = pts.map((p) => p.t);
+    expect(times).toContain(1.5);
+    expect(times).toContain(3.5);
+    expect(times).not.toContain(2);
+    expect(times).not.toContain(3);
+  });
+
+  it("lets inner points at the edges stand in for the anchors", () => {
+    // A ramp generator emits its own boundary points; pinning a second anchor
+    // at the same time would fight it.
+    const pts = replaceRange({
+      lane: ramp,
+      range: VOLUME_RANGE,
+      t0: 2,
+      t1: 3,
+      inner: [
+        { t: 2, v: 0 },
+        { t: 3, v: 1 },
+      ],
+    });
+    expect(pts.filter((p) => p.t === 2)).toHaveLength(1);
+    expect(pts.find((p) => p.t === 2)?.v).toBe(0);
+  });
+
+  it("sorts and respects the point cap", () => {
+    const dense = Array.from({ length: 600 }, (_, i) => ({ t: 1.5 + i * 0.001, v: 0.5 }));
+    const pts = replaceRange({ lane: ramp, range: VOLUME_RANGE, t0: 1.5, t1: 3.5, inner: dense });
+    expect(pts.length).toBeLessThanOrEqual(512);
+    expect([...pts].sort((a, b) => a.t - b.t)).toEqual(pts);
+  });
+
+  it("keeps a constant flat when the lane has no points", () => {
+    const empty: HfAutomationLane = { target: "volume", points: [] };
+    const pts = replaceRange({ lane: empty, range: VOLUME_RANGE, t0: 1, t1: 2, inner: [] });
+    // Nothing to preserve, nothing to pin: an empty lane stays empty.
+    expect(pts).toEqual([]);
+  });
+
+  it("keeps the far anchor and every outside point when inner would overflow the cap", () => {
+    const dense = Array.from({ length: 600 }, (_, i) => ({ t: 1.5 + i * 0.001, v: 0.5 }));
+    const pts = replaceRange({ lane: ramp, range: VOLUME_RANGE, t0: 1.5, t1: 3.5, inner: dense });
+    const times = pts.map((p) => p.t);
+    expect(times).toContain(1.5); // near anchor
+    expect(times).toContain(3.5); // far anchor — this is what the bug dropped
+    expect(times).toContain(0); // outside point before the range
+    expect(times).toContain(6); // outside point after the range
+    expect(pts.length).toBeLessThanOrEqual(512);
+  });
+
+  it("thins the interior evenly rather than dropping its tail", () => {
+    const dense = Array.from({ length: 2001 }, (_, i) => ({ t: 1.5 + i * 0.001, v: 0.5 }));
+    const pts = replaceRange({ lane: ramp, range: VOLUME_RANGE, t0: 1.5, t1: 3.5, inner: dense });
+    const innerTimes = pts.map((p) => p.t).filter((t) => t > 1.5 && t < 3.5);
+    // Evenly spread across the range, not clustered at the start.
+    expect(Math.max(...innerTimes)).toBeGreaterThan(3.0);
+  });
+});
+
+describe("retimeRange", () => {
+  it("scales interior points proportionally into the new span", () => {
+    const pts = retimeRange({ lane: ramp, range: VOLUME_RANGE, t0: 2, t1: 3, newT0: 2, newT1: 5 });
+    const moved = pts.find((p) => p.v === 0.4); // the t=3 point
+    expect(moved?.t).toBe(5);
+  });
+
+  it("preserves the envelope outside the union of old and new spans", () => {
+    const before: HfAutomationLane = { target: "volume", points: ramp.points };
+    const after: HfAutomationLane = {
+      target: "volume",
+      points: retimeRange({ lane: ramp, range: VOLUME_RANGE, t0: 2, t1: 3, newT0: 2, newT1: 5 }),
+    };
+    // Nothing to the left of t0=2 moved (newT0 === t0 here), so sampled
+    // continuity holds all the way up to the edited region.
+    for (const t of [0, 1, 1.9]) {
+      expect(sampleAutomationLane(after, t, "linear")).toBeCloseTo(
+        sampleAutomationLane(before, t, "linear"),
+        5,
+      );
+    }
+    // The next real breakpoint past the edited region keeps its own exact value.
+    const farPoint = after.points.find((p) => p.t === 6);
+    expect(farPoint).toEqual({ t: 6, v: 0 });
+  });
+
+  it("preserves the envelope on BOTH sides when no breakpoint sits on the moved edge", () => {
+    // The right side is where the invariant is worth asserting — `newT0 === t0`
+    // makes the left side of the test above trivially true, and an earlier
+    // right-side probe at t=5.1 was DELETED as inherent when it was reporting
+    // the real behaviour below. With the selection's edges off any breakpoint,
+    // the guarantee holds exactly, in both directions.
+    const before: HfAutomationLane = { target: "volume", points: ramp.points };
+    const after: HfAutomationLane = {
+      target: "volume",
+      points: retimeRange({
+        lane: ramp,
+        range: VOLUME_RANGE,
+        t0: 2.2,
+        t1: 2.9,
+        newT0: 2.2,
+        newT1: 4,
+      }),
+    };
+    for (const t of [0, 1, 2, 4.5, 5, 5.5, 6]) {
+      expect(sampleAutomationLane(after, t, "linear")).toBeCloseTo(
+        sampleAutomationLane(before, t, "linear"),
+        5,
+      );
+    }
+  });
+
+  it("moves a breakpoint sitting exactly on the dragged edge, reshaping the segment past it", () => {
+    // The design decision this pins, because it is not free either way.
+    // `pointsIn` is endpoint-inclusive, so a breakpoint ON the edge is interior
+    // and travels with the stretch. It has to: every range operation leaves a
+    // breakpoint exactly on the edge it created, so treating that point as an
+    // anchor instead would make the commonest stretch — grabbing the edge to
+    // drag that very point outward — delete it and flatten the span.
+    //
+    // The cost is that the retimed point lands ON the union's boundary, where a
+    // preservation anchor would also go, and `anchor()` stands down within a
+    // merge radius. Two different values cannot occupy one time; the segment
+    // leaving the union reshapes, which is the "envelope outside the selection
+    // never moves" invariant bending exactly here and nowhere else.
+    const pts = retimeRange({ lane: ramp, range: VOLUME_RANGE, t0: 2, t1: 3, newT0: 2, newT1: 5 });
+    expect(pts).toEqual([
+      { t: 0, v: 1 },
+      { t: 2, v: 0.6 },
+      { t: 5, v: 0.4 }, // the t=3 point, retimed onto the new edge
+      { t: 6, v: 0 },
+    ]);
+    // The old 3→6 segment sloped -0.133/s; the new 5→6 slopes -0.4/s, so the
+    // envelope past the union genuinely moves. Asserted, not tolerated: if this
+    // number changes, the decision above changed with it.
+    const after: HfAutomationLane = { target: "volume", points: pts };
+    expect(sampleAutomationLane(after, 5.5, "linear")).toBeCloseTo(0.2, 5);
+    expect(sampleAutomationLane(ramp, 5.5, "linear")).toBeCloseTo(0.0667, 4);
+  });
+
+  it("rejects a degenerate span", () => {
+    expect(
+      retimeRange({ lane: ramp, range: VOLUME_RANGE, t0: 2, t1: 3, newT0: 4, newT1: 4 }),
+    ).toEqual(ramp.points);
+  });
+});

package/src/player/components/automationLaneSelection.ts

@@ -0,0 +1,135 @@
+/**
+ * Range operations over one automation lane.
+ *
+ * `replaceRange` is the only mutator every range feature (delete, shapes,
+ * paste) composes, and it carries the invariant that makes them safe:
+ * the envelope OUTSIDE the selection never moves. It samples the lane at both
+ * edges first and pins anchor points there, so cutting the middle out of a
+ * ramp cannot reshape the rest of the clip.
+ *
+ * Exact for linear segments. A curved segment straddling an edge keeps its
+ * edge VALUE but reshapes slightly between its own start and the anchor — the
+ * curve exponent now runs over a shorter span. Accepted: the alternative is
+ * splitting curves analytically for a difference the ear cannot place.
+ */
+
+import {
+  MAX_AUTOMATION_POINTS,
+  sampleAutomationLane,
+  type AutomationRange,
+  type HfAutomationLane,
+  type HfAutomationPoint,
+} from "@hyperframes/core/audio-automation";
+import { POINT_MERGE_SEC } from "./automationLaneGeometry";
+
+/** Points inside [t0, t1], endpoints inclusive. */
+export function pointsIn(lane: HfAutomationLane, t0: number, t1: number): HfAutomationPoint[] {
+  return lane.points.filter((p) => p.t >= t0 && p.t <= t1);
+}
+
+/** An anchor, unless `inner` already provides the edge within the merge radius. */
+function anchor(
+  lane: HfAutomationLane,
+  range: AutomationRange,
+  t: number,
+  inner: readonly HfAutomationPoint[],
+): HfAutomationPoint[] {
+  if (inner.some((p) => Math.abs(p.t - t) <= POINT_MERGE_SEC)) return [];
+  return [{ t, v: sampleAutomationLane(lane, t, range.scale) }];
+}
+
+/** Evenly subsample items to a budget, preserving first and last. */
+function decimateEvenly<T>(items: readonly T[], budget: number): T[] {
+  if (budget <= 0) return [];
+  if (items.length <= budget) return [...items];
+  if (budget === 1) {
+    const item = items[0];
+    return item ? [item] : [];
+  }
+  const out: T[] = [];
+  const step = (items.length - 1) / (budget - 1);
+  for (let i = 0; i < budget; i += 1) {
+    const item = items[Math.round(i * step)];
+    if (item) out.push(item);
+  }
+  return out;
+}
+
+export function replaceRange(input: {
+  lane: HfAutomationLane;
+  range: AutomationRange;
+  t0: number;
+  t1: number;
+  inner: HfAutomationPoint[];
+}): HfAutomationPoint[] {
+  const { lane, range, t0, t1, inner } = input;
+  // An empty lane draws a flat default; there is nothing to preserve, and
+  // pinning anchors would turn "no automation" into a constant lane.
+  if (lane.points.length === 0 && inner.length === 0) return [];
+  const outside = lane.points.filter((p) => p.t < t0 || p.t > t1);
+  const edges =
+    lane.points.length === 0
+      ? []
+      : [...anchor(lane, range, t0, inner), ...anchor(lane, range, t1, inner)];
+  const budget = Math.max(0, MAX_AUTOMATION_POINTS - outside.length - edges.length);
+  const cappedInner = inner.length <= budget ? inner : decimateEvenly(inner, budget);
+  return [...outside, ...edges, ...cappedInner].sort((a, b) => a.t - b.t);
+}
+
+/**
+ * Whether a breakpoint falls inside the selection box, edges included.
+ *
+ * The one rule three places need: what Delete removes, what the lane rings, and
+ * what a group drag moves. They have to agree — a point drawn as caught but left
+ * behind by the drag is worse than either answer.
+ *
+ * Both axes, which is what makes a selection a box: a point at the right time but
+ * the wrong value is not in it. Values compare in the parameter's own units, and
+ * that is correct on a logarithmic axis too — the mapping to screen is monotonic,
+ * so a box drawn around some pixels holds exactly the values it looks like it does.
+ */
+export function pointInSelection(
+  point: { t: number; v: number },
+  box: { t0: number; t1: number; v0: number; v1: number },
+): boolean {
+  return point.t >= box.t0 && point.t <= box.t1 && point.v >= box.v0 && point.v <= box.v1;
+}
+/**
+ * Retime a selection: interior points scale proportionally into the new span,
+ * then replaceRange runs over the UNION of old and new spans — growing eats
+ * whatever it covers, shrinking pins anchors where the envelope re-enters.
+ *
+ * Interior is `pointsIn`, so a breakpoint sitting exactly ON an edge travels
+ * with the stretch. Deliberate: every range operation leaves a breakpoint on the
+ * edge it created, so treating that point as a fixed anchor would make the
+ * commonest stretch of all — grabbing the edge to drag that point outward —
+ * delete it instead. The price is that such a point lands on the union's own
+ * boundary, where `anchor` then stands down (one time cannot hold two values),
+ * so the segment leaving the union reshapes. That is the ONE place
+ * `replaceRange`'s outside-never-moves invariant bends, and it is pinned by name
+ * in automationLaneSelection.test.ts.
+ */
+export function retimeRange(input: {
+  lane: HfAutomationLane;
+  range: AutomationRange;
+  t0: number;
+  t1: number;
+  newT0: number;
+  newT1: number;
+}): HfAutomationPoint[] {
+  const { lane, range, t0, t1, newT0, newT1 } = input;
+  const oldSpan = t1 - t0;
+  const newSpan = newT1 - newT0;
+  if (oldSpan <= 0 || newSpan <= 0) return lane.points;
+  const inner = pointsIn(lane, t0, t1).map((p) => ({
+    ...p,
+    t: newT0 + ((p.t - t0) * newSpan) / oldSpan,
+  }));
+  return replaceRange({
+    lane,
+    range,
+    t0: Math.min(t0, newT0),
+    t1: Math.max(t1, newT1),
+    inner,
+  });
+}