entangled-worlds-orbiters-shared 2.12.0 → 2.13.0

package/dist/clock/curves.d.ts

@@ -4,11 +4,87 @@ export declare const Ease: {
     linear: EaseFn;
     smooth: EaseFn;
 };
-/** A single curve keyframe: a time key `t` (seconds or beats) and its value. */
+/**
+ * A single curve keyframe: a time key `t` (seconds or beats) and its value. `curve` bends the segment
+ * to the next keyframe (see {@link bend}); absent or 0 falls back to the track's `ease`.
+ */
 export interface Keyframe {
     t: number;
     value: number;
+    curve?: number;
+}
+/**
+ * How a curve moves between keyframes: `line` ramps (bent by each keyframe's `curve`), `step` holds
+ * each value until the next keyframe.
+ */
+export type CurveShape = 'line' | 'step';
+/** The range of a keyframe's `curve`: −2 … 2, 0 linear. */
+export declare const CURVE_BEND_LIMIT = 2;
+/**
+ * The bend of one segment: maps the fraction `u` in [0, 1] through `curve` c. 0 is linear; c > 0 starts
+ * slow and ends fast (exponential), c < 0 starts fast (logarithmic). The automation editor and every
+ * player read the same function, so what is drawn is what plays.
+ */
+export declare function bend(u: number, curve?: number): number;
+/**
+ * The `curve` that puts a segment's midpoint at `mid`, a share of the way from its first value to its
+ * last (0 … 1, exclusive): the inverse of {@link bend} at u = ½, for a bend handle dragged up or down.
+ */
+export declare function curveForMidpoint(mid: number): number;
+/** What {@link sampleKeyframes} needs besides the keyframes. */
+export interface SampleOptions {
+    shape?: CurveShape;
+    /** For a segment whose keyframe has no `curve` (default linear). */
+    ease?: EaseFn;
+}
+/**
+ * The value of sorted keyframes at time key `key`: held before the first and after the last, ramped
+ * (or stepped) between. NaN when there are none: an empty lane writes nothing.
+ */
+export declare function sampleKeyframes(keyframes: readonly Keyframe[], key: number, { shape, ease }?: SampleOptions): number;
+/**
+ * A loop over a curve's time key: the curve plays from 0 up to `start + length`, then repeats
+ * `start` … `start + length` (a clip's loop). `start` 0 is a curve that loops on its own length.
+ */
+export interface CurveLoop {
+    start: number;
+    length: number;
+}
+/** The curve's own time key for a running key: before the loop's end as is, then wrapped into the loop. */
+export declare function loopKey(key: number, loop: CurveLoop | null | undefined): number;
+/** One of the shapes {@link insertShape} draws: points as [u, value, curve?] over one cycle, u in [0, 1). */
+export interface CurveShapeDef {
+    id: string;
+    label: string;
+    points: ReadonlyArray<readonly [number, number, number?]>;
+    /** A closing point at the range's end, for shapes that come back to where they started. */
+    end?: number;
 }
+/** The ten shapes of the automation editor's Insert shape menu. */
+export declare const CURVE_SHAPES: readonly CurveShapeDef[];
+/** The keyframes with every one inside [from, to] replaced by `insert` (sorted). */
+export declare function replaceRange(keyframes: readonly Keyframe[], from: number, to: number, insert: readonly Keyframe[]): Keyframe[];
+/**
+ * Draws a shape over [from, to], `cycles` times, replacing only the keyframes inside the range. Null
+ * when the shape is unknown or the range is too short to draw (under 1/16 of a key unit).
+ */
+export declare function insertShape(keyframes: readonly Keyframe[], shapeId: string, from: number, to: number, cycles?: number): Keyframe[] | null;
+/** Freehand draw: one keyframe at the start of the cell [cellStart, cellStart + cellLength), replacing the cell. */
+export declare function paintCell(keyframes: readonly Keyframe[], cellStart: number, cellLength: number, value: number): Keyframe[];
+/**
+ * Recording: the keyframes after the time key moved from `prevKey` to `key` while `value` was live.
+ * What was recorded over in that span is replaced (a wrap from a loop end back to its start clears both
+ * ends of the loop). A new keyframe is written only once `spacing` has passed since `lastWritten` (null: write now),
+ * so a recording is one point per grid step, not one per frame.
+ */
+export declare function recordSpan(keyframes: readonly Keyframe[], prevKey: number, key: number, value: number, { spacing, lastWritten, loop }: {
+    spacing: number;
+    lastWritten: number | null;
+    loop?: CurveLoop | null;
+}): {
+    keyframes: Keyframe[];
+    written: number | null;
+};
 export type TimeMode = 'absolute-seconds' | 'beat-locked';
 /**
  * Structural shape of a musical projection — typed here so `./clock/curves` never imports
@@ -22,6 +98,10 @@ export interface CurveTrackSpec {
     timeMode?: TimeMode;
     projection?: ProjectionLike | null;
     ease?: EaseFn;
+    /** Line (default) or step. */
+    shape?: CurveShape;
+    /** Loops the curve's time key (a clip loop, or its own length). Absent: plays once, then holds. */
+    loop?: CurveLoop | null;
     outputIntent?: unknown;
 }
 export declare class CurveTrack {
@@ -29,11 +109,16 @@ export declare class CurveTrack {
     timeMode: TimeMode;
     projection: ProjectionLike | null;
     ease: EaseFn;
+    shape: CurveShape;
+    loop: CurveLoop | null;
     outputIntent: unknown;
     constructor(spec: CurveTrackSpec);
-    /** The track's own time key for a given clock position. */
+    /** The track's own time key for a given clock position (looped when the track loops). */
     _key(positionSec: number): number;
+    /** The value at a clock position; NaN for a track with no keyframes. */
     sample(positionSec: number): number;
+    /** The value at the track's own time key (beats for a beat-locked track), with no loop applied. */
+    sampleKey(key: number): number;
 }
 /**
  * Structural shape of the transport a GestureRecorder/Orchestrator subscribes to — typed here so

package/dist/clock/curves.js

@@ -13,40 +13,164 @@ export const Ease = {
 function lerp(a, b, t) {
     return a + (b - a) * t;
 }
+/** The range of a keyframe's `curve`: −2 … 2, 0 linear. */
+export const CURVE_BEND_LIMIT = 2;
+/**
+ * The bend of one segment: maps the fraction `u` in [0, 1] through `curve` c. 0 is linear; c > 0 starts
+ * slow and ends fast (exponential), c < 0 starts fast (logarithmic). The automation editor and every
+ * player read the same function, so what is drawn is what plays.
+ */
+export function bend(u, curve = 0) {
+    if (!curve)
+        return u;
+    return curve > 0 ? Math.pow(u, 1 + curve * 3) : 1 - Math.pow(1 - u, 1 - curve * 3);
+}
+/**
+ * The `curve` that puts a segment's midpoint at `mid`, a share of the way from its first value to its
+ * last (0 … 1, exclusive): the inverse of {@link bend} at u = ½, for a bend handle dragged up or down.
+ */
+export function curveForMidpoint(mid) {
+    const m = Math.max(0.03, Math.min(0.97, mid));
+    const c = m <= 0.5 ? (Math.log(m) / Math.log(0.5) - 1) / 3 : -(Math.log(1 - m) / Math.log(0.5) - 1) / 3;
+    return Math.max(-CURVE_BEND_LIMIT, Math.min(CURVE_BEND_LIMIT, c));
+}
+/**
+ * The value of sorted keyframes at time key `key`: held before the first and after the last, ramped
+ * (or stepped) between. NaN when there are none: an empty lane writes nothing.
+ */
+export function sampleKeyframes(keyframes, key, { shape = 'line', ease = Ease.linear } = {}) {
+    const kf = keyframes;
+    if (!kf.length)
+        return NaN;
+    if (key <= kf[0].t)
+        return kf[0].value;
+    const last = kf[kf.length - 1];
+    if (key >= last.t)
+        return last.value;
+    // Binary search: the last keyframe at or before key.
+    let lo = 0;
+    let hi = kf.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (kf[mid].t <= key)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = kf[lo];
+    const b = kf[lo + 1];
+    if (shape === 'step')
+        return a.value;
+    const frac = b.t > a.t ? (key - a.t) / (b.t - a.t) : 1;
+    return lerp(a.value, b.value, a.curve ? bend(frac, a.curve) : ease(frac));
+}
+/** The curve's own time key for a running key: before the loop's end as is, then wrapped into the loop. */
+export function loopKey(key, loop) {
+    if (!loop || !(loop.length > 0))
+        return key;
+    const end = loop.start + loop.length;
+    if (key < end)
+        return key;
+    return loop.start + ((key - end) % loop.length);
+}
+/** The ten shapes of the automation editor's Insert shape menu. */
+export const CURVE_SHAPES = [
+    { id: 'sine', label: 'Sine', points: [[0, 0.5, -0.2], [0.25, 1, 0.2], [0.5, 0.5, -0.2], [0.75, 0, 0.2]], end: 0.5 },
+    { id: 'triangle', label: 'Triangle', points: [[0, 0], [0.5, 1]], end: 0 },
+    { id: 'sawDown', label: 'Saw down', points: [[0, 1], [0.999, 0]] },
+    { id: 'sawUp', label: 'Saw up', points: [[0, 0], [0.999, 1]] },
+    { id: 'square', label: 'Square', points: [[0, 1], [0.5 - 1e-3, 1], [0.5, 0], [0.999, 0]] },
+    { id: 'curveUp', label: 'Curve up', points: [[0, 0, 1.2], [0.999, 1]] },
+    { id: 'curveDown', label: 'Curve down', points: [[0, 1, -1.2], [0.999, 0]] },
+    { id: 'sCurveUp', label: 'S-curve up', points: [[0, 0, 0.8], [0.5, 0.5, -0.8], [0.999, 1]] },
+    { id: 'sCurveDown', label: 'S-curve down', points: [[0, 1, 0.8], [0.5, 0.5, -0.8], [0.999, 0]] },
+    { id: 'attackDecay', label: 'Attack / decay', points: [[0, 0, -0.6], [0.15, 1, -1], [0.999, 0]] },
+];
+const byKey = (a, b) => a.t - b.t;
+/** The keyframes with every one inside [from, to] replaced by `insert` (sorted). */
+export function replaceRange(keyframes, from, to, insert) {
+    const eps = 1e-6;
+    return keyframes.filter((k) => k.t < from - eps || k.t > to + eps).concat(insert).sort(byKey);
+}
+/**
+ * Draws a shape over [from, to], `cycles` times, replacing only the keyframes inside the range. Null
+ * when the shape is unknown or the range is too short to draw (under 1/16 of a key unit).
+ */
+export function insertShape(keyframes, shapeId, from, to, cycles = 1) {
+    const def = CURVE_SHAPES.find((s) => s.id === shapeId);
+    if (!def || to - from < 0.0625)
+        return null;
+    const n = Math.max(1, Math.floor(cycles));
+    const len = (to - from) / n;
+    const eps = Math.min(1 / 64, len / 8);
+    const made = [];
+    for (let k = 0; k < n; k++) {
+        for (const [u, value, curve] of def.points) {
+            const t = u >= 0.999 ? from + (k + 1) * len - eps : from + (k + u) * len;
+            made.push(curve ? { t, value, curve } : { t, value });
+        }
+    }
+    if (def.end != null)
+        made.push({ t: to, value: def.end });
+    return replaceRange(keyframes, from, to, made);
+}
+/** Freehand draw: one keyframe at the start of the cell [cellStart, cellStart + cellLength), replacing the cell. */
+export function paintCell(keyframes, cellStart, cellLength, value) {
+    const eps = 1e-6;
+    return keyframes
+        .filter((k) => k.t < cellStart - eps || k.t >= cellStart + cellLength - eps)
+        .concat({ t: cellStart, value })
+        .sort(byKey);
+}
+/**
+ * Recording: the keyframes after the time key moved from `prevKey` to `key` while `value` was live.
+ * What was recorded over in that span is replaced (a wrap from a loop end back to its start clears both
+ * ends of the loop). A new keyframe is written only once `spacing` has passed since `lastWritten` (null: write now),
+ * so a recording is one point per grid step, not one per frame.
+ */
+export function recordSpan(keyframes, prevKey, key, value, { spacing, lastWritten, loop }) {
+    const wrapped = key < prevKey;
+    const start = loop ? loop.start : 0;
+    const end = loop ? loop.start + loop.length : Infinity;
+    const over = (t) => (wrapped ? (t > prevKey && t < end) || (t >= start && t <= key) : t > prevKey && t <= key);
+    const kept = keyframes.filter((k) => !over(k.t));
+    const last = lastWritten == null || wrapped ? -Infinity : lastWritten;
+    if (key - last < spacing)
+        return { keyframes: kept, written: lastWritten };
+    return { keyframes: kept.concat({ t: key, value }).sort(byKey), written: key };
+}
 export class CurveTrack {
     keyframes;
     timeMode;
     projection;
     ease;
+    shape;
+    loop;
     outputIntent;
     constructor(spec) {
-        this.keyframes = spec.keyframes.slice().sort((a, b) => a.t - b.t);
+        this.keyframes = spec.keyframes.slice().sort(byKey);
         this.timeMode = spec.timeMode ?? 'absolute-seconds';
         this.projection = spec.projection ?? null;
         this.ease = spec.ease ?? Ease.linear;
+        this.shape = spec.shape ?? 'line';
+        this.loop = spec.loop ?? null;
         this.outputIntent = spec.outputIntent ?? null;
         if (this.timeMode === 'beat-locked' && !this.projection) {
             throw new Error('beat-locked CurveTrack needs a MusicalProjection');
         }
     }
-    /** The track's own time key for a given clock position. */
+    /** The track's own time key for a given clock position (looped when the track loops). */
     _key(positionSec) {
-        return this.timeMode === 'beat-locked' ? this.projection.secondsToBeats(positionSec) : positionSec;
+        const key = this.timeMode === 'beat-locked' ? this.projection.secondsToBeats(positionSec) : positionSec;
+        return loopKey(key, this.loop);
     }
+    /** The value at a clock position; NaN for a track with no keyframes. */
     sample(positionSec) {
-        const k = this._key(positionSec);
-        const kf = this.keyframes;
-        if (k <= kf[0].t)
-            return kf[0].value;
-        if (k >= kf[kf.length - 1].t)
-            return kf[kf.length - 1].value;
-        let i = 0;
-        while (i < kf.length - 1 && kf[i + 1].t <= k)
-            i++;
-        const a = kf[i];
-        const b = kf[i + 1];
-        const frac = (k - a.t) / (b.t - a.t);
-        return lerp(a.value, b.value, this.ease(frac));
+        return this.sampleKey(this._key(positionSec));
+    }
+    /** The value at the track's own time key (beats for a beat-locked track), with no loop applied. */
+    sampleKey(key) {
+        return sampleKeyframes(this.keyframes, key, { shape: this.shape, ease: this.ease });
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",

package/src/clock/curves.ts

@@ -19,10 +19,175 @@ function lerp(a: number, b: number, t: number): number {
   return a + (b - a) * t;
 }
 
-/** A single curve keyframe: a time key `t` (seconds or beats) and its value. */
+/**
+ * A single curve keyframe: a time key `t` (seconds or beats) and its value. `curve` bends the segment
+ * to the next keyframe (see {@link bend}); absent or 0 falls back to the track's `ease`.
+ */
 export interface Keyframe {
   t: number;
   value: number;
+  curve?: number;
+}
+
+/**
+ * How a curve moves between keyframes: `line` ramps (bent by each keyframe's `curve`), `step` holds
+ * each value until the next keyframe.
+ */
+export type CurveShape = 'line' | 'step';
+
+/** The range of a keyframe's `curve`: −2 … 2, 0 linear. */
+export const CURVE_BEND_LIMIT = 2;
+
+/**
+ * The bend of one segment: maps the fraction `u` in [0, 1] through `curve` c. 0 is linear; c > 0 starts
+ * slow and ends fast (exponential), c < 0 starts fast (logarithmic). The automation editor and every
+ * player read the same function, so what is drawn is what plays.
+ */
+export function bend(u: number, curve = 0): number {
+  if (!curve) return u;
+  return curve > 0 ? Math.pow(u, 1 + curve * 3) : 1 - Math.pow(1 - u, 1 - curve * 3);
+}
+
+/**
+ * The `curve` that puts a segment's midpoint at `mid`, a share of the way from its first value to its
+ * last (0 … 1, exclusive): the inverse of {@link bend} at u = ½, for a bend handle dragged up or down.
+ */
+export function curveForMidpoint(mid: number): number {
+  const m = Math.max(0.03, Math.min(0.97, mid));
+  const c = m <= 0.5 ? (Math.log(m) / Math.log(0.5) - 1) / 3 : -(Math.log(1 - m) / Math.log(0.5) - 1) / 3;
+  return Math.max(-CURVE_BEND_LIMIT, Math.min(CURVE_BEND_LIMIT, c));
+}
+
+/** What {@link sampleKeyframes} needs besides the keyframes. */
+export interface SampleOptions {
+  shape?: CurveShape;
+  /** For a segment whose keyframe has no `curve` (default linear). */
+  ease?: EaseFn;
+}
+
+/**
+ * The value of sorted keyframes at time key `key`: held before the first and after the last, ramped
+ * (or stepped) between. NaN when there are none: an empty lane writes nothing.
+ */
+export function sampleKeyframes(keyframes: readonly Keyframe[], key: number, { shape = 'line', ease = Ease.linear }: SampleOptions = {}): number {
+  const kf = keyframes;
+  if (!kf.length) return NaN;
+  if (key <= kf[0].t) return kf[0].value;
+  const last = kf[kf.length - 1];
+  if (key >= last.t) return last.value;
+  // Binary search: the last keyframe at or before key.
+  let lo = 0;
+  let hi = kf.length - 1;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if (kf[mid].t <= key) lo = mid; else hi = mid;
+  }
+  const a = kf[lo];
+  const b = kf[lo + 1];
+  if (shape === 'step') return a.value;
+  const frac = b.t > a.t ? (key - a.t) / (b.t - a.t) : 1;
+  return lerp(a.value, b.value, a.curve ? bend(frac, a.curve) : ease(frac));
+}
+
+/**
+ * A loop over a curve's time key: the curve plays from 0 up to `start + length`, then repeats
+ * `start` … `start + length` (a clip's loop). `start` 0 is a curve that loops on its own length.
+ */
+export interface CurveLoop {
+  start: number;
+  length: number;
+}
+
+/** The curve's own time key for a running key: before the loop's end as is, then wrapped into the loop. */
+export function loopKey(key: number, loop: CurveLoop | null | undefined): number {
+  if (!loop || !(loop.length > 0)) return key;
+  const end = loop.start + loop.length;
+  if (key < end) return key;
+  return loop.start + ((key - end) % loop.length);
+}
+
+/** One of the shapes {@link insertShape} draws: points as [u, value, curve?] over one cycle, u in [0, 1). */
+export interface CurveShapeDef {
+  id: string;
+  label: string;
+  points: ReadonlyArray<readonly [number, number, number?]>;
+  /** A closing point at the range's end, for shapes that come back to where they started. */
+  end?: number;
+}
+
+/** The ten shapes of the automation editor's Insert shape menu. */
+export const CURVE_SHAPES: readonly CurveShapeDef[] = [
+  { id: 'sine', label: 'Sine', points: [[0, 0.5, -0.2], [0.25, 1, 0.2], [0.5, 0.5, -0.2], [0.75, 0, 0.2]], end: 0.5 },
+  { id: 'triangle', label: 'Triangle', points: [[0, 0], [0.5, 1]], end: 0 },
+  { id: 'sawDown', label: 'Saw down', points: [[0, 1], [0.999, 0]] },
+  { id: 'sawUp', label: 'Saw up', points: [[0, 0], [0.999, 1]] },
+  { id: 'square', label: 'Square', points: [[0, 1], [0.5 - 1e-3, 1], [0.5, 0], [0.999, 0]] },
+  { id: 'curveUp', label: 'Curve up', points: [[0, 0, 1.2], [0.999, 1]] },
+  { id: 'curveDown', label: 'Curve down', points: [[0, 1, -1.2], [0.999, 0]] },
+  { id: 'sCurveUp', label: 'S-curve up', points: [[0, 0, 0.8], [0.5, 0.5, -0.8], [0.999, 1]] },
+  { id: 'sCurveDown', label: 'S-curve down', points: [[0, 1, 0.8], [0.5, 0.5, -0.8], [0.999, 0]] },
+  { id: 'attackDecay', label: 'Attack / decay', points: [[0, 0, -0.6], [0.15, 1, -1], [0.999, 0]] },
+];
+
+const byKey = (a: Keyframe, b: Keyframe) => a.t - b.t;
+
+/** The keyframes with every one inside [from, to] replaced by `insert` (sorted). */
+export function replaceRange(keyframes: readonly Keyframe[], from: number, to: number, insert: readonly Keyframe[]): Keyframe[] {
+  const eps = 1e-6;
+  return keyframes.filter((k) => k.t < from - eps || k.t > to + eps).concat(insert).sort(byKey);
+}
+
+/**
+ * Draws a shape over [from, to], `cycles` times, replacing only the keyframes inside the range. Null
+ * when the shape is unknown or the range is too short to draw (under 1/16 of a key unit).
+ */
+export function insertShape(keyframes: readonly Keyframe[], shapeId: string, from: number, to: number, cycles = 1): Keyframe[] | null {
+  const def = CURVE_SHAPES.find((s) => s.id === shapeId);
+  if (!def || to - from < 0.0625) return null;
+  const n = Math.max(1, Math.floor(cycles));
+  const len = (to - from) / n;
+  const eps = Math.min(1 / 64, len / 8);
+  const made: Keyframe[] = [];
+  for (let k = 0; k < n; k++) {
+    for (const [u, value, curve] of def.points) {
+      const t = u >= 0.999 ? from + (k + 1) * len - eps : from + (k + u) * len;
+      made.push(curve ? { t, value, curve } : { t, value });
+    }
+  }
+  if (def.end != null) made.push({ t: to, value: def.end });
+  return replaceRange(keyframes, from, to, made);
+}
+
+/** Freehand draw: one keyframe at the start of the cell [cellStart, cellStart + cellLength), replacing the cell. */
+export function paintCell(keyframes: readonly Keyframe[], cellStart: number, cellLength: number, value: number): Keyframe[] {
+  const eps = 1e-6;
+  return keyframes
+    .filter((k) => k.t < cellStart - eps || k.t >= cellStart + cellLength - eps)
+    .concat({ t: cellStart, value })
+    .sort(byKey);
+}
+
+/**
+ * Recording: the keyframes after the time key moved from `prevKey` to `key` while `value` was live.
+ * What was recorded over in that span is replaced (a wrap from a loop end back to its start clears both
+ * ends of the loop). A new keyframe is written only once `spacing` has passed since `lastWritten` (null: write now),
+ * so a recording is one point per grid step, not one per frame.
+ */
+export function recordSpan(
+  keyframes: readonly Keyframe[],
+  prevKey: number,
+  key: number,
+  value: number,
+  { spacing, lastWritten, loop }: { spacing: number; lastWritten: number | null; loop?: CurveLoop | null },
+): { keyframes: Keyframe[]; written: number | null } {
+  const wrapped = key < prevKey;
+  const start = loop ? loop.start : 0;
+  const end = loop ? loop.start + loop.length : Infinity;
+  const over = (t: number) => (wrapped ? (t > prevKey && t < end) || (t >= start && t <= key) : t > prevKey && t <= key);
+  const kept = keyframes.filter((k) => !over(k.t));
+  const last = lastWritten == null || wrapped ? -Infinity : lastWritten;
+  if (key - last < spacing) return { keyframes: kept, written: lastWritten };
+  return { keyframes: kept.concat({ t: key, value }).sort(byKey), written: key };
 }
 
 export type TimeMode = 'absolute-seconds' | 'beat-locked';
@@ -40,6 +205,10 @@ export interface CurveTrackSpec {
   timeMode?: TimeMode;
   projection?: ProjectionLike | null;
   ease?: EaseFn;
+  /** Line (default) or step. */
+  shape?: CurveShape;
+  /** Loops the curve's time key (a clip loop, or its own length). Absent: plays once, then holds. */
+  loop?: CurveLoop | null;
   outputIntent?: unknown;
 }
 
@@ -48,35 +217,37 @@ export class CurveTrack {
   timeMode: TimeMode;
   projection: ProjectionLike | null;
   ease: EaseFn;
+  shape: CurveShape;
+  loop: CurveLoop | null;
   outputIntent: unknown;
 
   constructor(spec: CurveTrackSpec) {
-    this.keyframes = spec.keyframes.slice().sort((a, b) => a.t - b.t);
+    this.keyframes = spec.keyframes.slice().sort(byKey);
     this.timeMode = spec.timeMode ?? 'absolute-seconds';
     this.projection = spec.projection ?? null;
     this.ease = spec.ease ?? Ease.linear;
+    this.shape = spec.shape ?? 'line';
+    this.loop = spec.loop ?? null;
     this.outputIntent = spec.outputIntent ?? null;
     if (this.timeMode === 'beat-locked' && !this.projection) {
       throw new Error('beat-locked CurveTrack needs a MusicalProjection');
     }
   }
 
-  /** The track's own time key for a given clock position. */
+  /** The track's own time key for a given clock position (looped when the track loops). */
   _key(positionSec: number): number {
-    return this.timeMode === 'beat-locked' ? this.projection!.secondsToBeats(positionSec) : positionSec;
+    const key = this.timeMode === 'beat-locked' ? this.projection!.secondsToBeats(positionSec) : positionSec;
+    return loopKey(key, this.loop);
   }
 
+  /** The value at a clock position; NaN for a track with no keyframes. */
   sample(positionSec: number): number {
-    const k = this._key(positionSec);
-    const kf = this.keyframes;
-    if (k <= kf[0].t) return kf[0].value;
-    if (k >= kf[kf.length - 1].t) return kf[kf.length - 1].value;
-    let i = 0;
-    while (i < kf.length - 1 && kf[i + 1].t <= k) i++;
-    const a = kf[i];
-    const b = kf[i + 1];
-    const frac = (k - a.t) / (b.t - a.t);
-    return lerp(a.value, b.value, this.ease(frac));
+    return this.sampleKey(this._key(positionSec));
+  }
+
+  /** The value at the track's own time key (beats for a beat-locked track), with no loop applied. */
+  sampleKey(key: number): number {
+    return sampleKeyframes(this.keyframes, key, { shape: this.shape, ease: this.ease });
   }
 }