entangled-worlds-orbiters-shared 2.11.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/dist/notes/index.d.ts

@@ -0,0 +1,72 @@
+export type NoteEventType = 'on' | 'off';
+export interface NoteEvent {
+    type: NoteEventType;
+    /** Unique per sounding note; an `off` carries the id of the `on` it ends. */
+    id: string;
+    /** MIDI note number, 0 … 127 (integers today; the field allows fractions later). */
+    pitch: number;
+    /** 0 … 1. An `off` may carry a release velocity; nothing reads it yet. */
+    velocity: number;
+    /** Audio-context seconds when it should sound; at or before now means now. */
+    time: number;
+    /** Who sent it: a device, the keyboard, a MIDI effect's slot, a room client. */
+    source: string;
+}
+export declare const NOTE_PITCH_MIN = 0;
+export declare const NOTE_PITCH_MAX = 127;
+/** Whether `value` is a well-formed note event (the shape a room peer or an agent must send). */
+export declare function isNoteEvent(value: unknown): value is NoteEvent;
+/** What a channel message means to a note player. Channels are 0 … 15, as on the wire. */
+export type MidiNoteMessage = {
+    kind: 'on';
+    channel: number;
+    pitch: number;
+    velocity: number;
+} | {
+    kind: 'off';
+    channel: number;
+    pitch: number;
+    velocity: number;
+}
+/** Pitch bend, −1 … 1 (0 is the centre). */
+ | {
+    kind: 'bend';
+    channel: number;
+    value: number;
+}
+/** A control change, its value 0 … 1. */
+ | {
+    kind: 'cc';
+    channel: number;
+    controller: number;
+    value: number;
+};
+/** The mod wheel. */
+export declare const MIDI_CC_MOD_WHEEL = 1;
+/**
+ * Decode a channel message's bytes. A note-on with velocity 0 is a note-off (running status sends
+ * them that way). Anything a note player has no use for (aftertouch, program change, system) is null.
+ */
+export declare function decodeMidiMessage(status: number, data1?: number, data2?: number): MidiNoteMessage | null;
+/**
+ * A MIDI note-off names only a channel and a pitch. This gives each held key its note id, so the
+ * off pairs with its on by id like every other source.
+ *
+ * - `on` mints a fresh id. If that key was already held (a device that sends two ons without an off)
+ *   the old note's id comes back as `replaced`, so the caller can end it first: nothing sticks.
+ * - `off` returns the id the key was playing, or null when it was never down (an off arriving after
+ *   a panic, or from before the page listened).
+ * - `releaseDevice` hands back every id a device holds: it went away, and they all end.
+ */
+export interface MidiNoteIds {
+    on(device: string, channel: number, pitch: number): {
+        id: string;
+        replaced: string | null;
+    };
+    off(device: string, channel: number, pitch: number): string | null;
+    releaseDevice(device: string): string[];
+    releaseAll(): string[];
+    /** How many keys are down, across devices. */
+    readonly size: number;
+}
+export declare function createMidiNoteIds(prefix?: string): MidiNoteIds;

package/dist/notes/index.js

@@ -0,0 +1,94 @@
+// Notes as events, shared by every note source (MIDI in, the on-screen keyboard, a capability call, a
+// MIDI effect, a room peer) and everything that routes or sounds them.
+//
+// On and off are separate events with no duration: a live key has no known length when it goes
+// down. They pair by `id`, never by pitch, since two sources can hold the same pitch at once and a
+// chord or an echo plays the same pitch more than once. Pairing by pitch alone gives stuck notes.
+//
+// App-agnostic: nothing here knows about Orbiters, dimensions or the audio graph.
+export const NOTE_PITCH_MIN = 0;
+export const NOTE_PITCH_MAX = 127;
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+/** Whether `value` is a well-formed note event (the shape a room peer or an agent must send). */
+export function isNoteEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const event = value;
+    return ((event.type === 'on' || event.type === 'off') &&
+        typeof event.id === 'string' &&
+        event.id.length > 0 &&
+        isFiniteNumber(event.pitch) &&
+        event.pitch >= NOTE_PITCH_MIN &&
+        event.pitch <= NOTE_PITCH_MAX &&
+        isFiniteNumber(event.velocity) &&
+        event.velocity >= 0 &&
+        event.velocity <= 1 &&
+        isFiniteNumber(event.time) &&
+        typeof event.source === 'string');
+}
+/** The mod wheel. */
+export const MIDI_CC_MOD_WHEEL = 1;
+const BEND_CENTRE = 8192;
+/**
+ * Decode a channel message's bytes. A note-on with velocity 0 is a note-off (running status sends
+ * them that way). Anything a note player has no use for (aftertouch, program change, system) is null.
+ */
+export function decodeMidiMessage(status, data1 = 0, data2 = 0) {
+    const channel = status & 0x0f;
+    switch (status & 0xf0) {
+        case 0x90:
+            return data2 > 0
+                ? { kind: 'on', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 }
+                : { kind: 'off', channel, pitch: data1 & 0x7f, velocity: 0 };
+        case 0x80:
+            return { kind: 'off', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 };
+        case 0xe0: {
+            // 14 bits, least significant first. The top is 8191 above the centre and the bottom 8192 below
+            // it, so each side is scaled on its own and both ends reach ±1.
+            const raw = ((data2 & 0x7f) << 7) | (data1 & 0x7f);
+            const offset = raw - BEND_CENTRE;
+            return { kind: 'bend', channel, value: offset >= 0 ? offset / (BEND_CENTRE - 1) : offset / BEND_CENTRE };
+        }
+        case 0xb0:
+            return { kind: 'cc', channel, controller: data1 & 0x7f, value: (data2 & 0x7f) / 127 };
+        default:
+            return null;
+    }
+}
+export function createMidiNoteIds(prefix = 'midi') {
+    const held = new Map();
+    let next = 0;
+    const keyOf = (device, channel, pitch) => `${device}\u0000${channel}\u0000${pitch}`;
+    const deviceOf = (key) => key.slice(0, key.indexOf('\u0000'));
+    const take = (predicate) => {
+        const ids = [];
+        for (const [key, id] of held) {
+            if (!predicate(key))
+                continue;
+            ids.push(id);
+            held.delete(key);
+        }
+        return ids;
+    };
+    return {
+        on(device, channel, pitch) {
+            const key = keyOf(device, channel, pitch);
+            const replaced = held.get(key) ?? null;
+            next += 1;
+            const id = `${prefix}:${next}`;
+            held.set(key, id);
+            return { id, replaced };
+        },
+        off(device, channel, pitch) {
+            const key = keyOf(device, channel, pitch);
+            const id = held.get(key) ?? null;
+            held.delete(key);
+            return id;
+        },
+        releaseDevice: (device) => take((key) => deviceOf(key) === device),
+        releaseAll: () => take(() => true),
+        get size() {
+            return held.size;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.11.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",
@@ -42,6 +42,10 @@
       "types": "./dist/capabilities/index.d.ts",
       "import": "./dist/capabilities/index.js"
     },
+    "./notes": {
+      "types": "./dist/notes/index.d.ts",
+      "import": "./dist/notes/index.js"
+    },
     "./studio": {
       "types": "./dist/studio/index.d.ts",
       "import": "./dist/studio/index.js"
@@ -109,10 +113,11 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:clock": "node --test --import tsx src/clock/*.test.ts",
     "test:capabilities": "node --test --import tsx src/capabilities/*.test.js",
+    "test:notes": "node --test --import tsx src/notes/*.test.ts",
     "test:studio": "node --test --import tsx src/studio/*.test.js",
     "test:uploads": "node --test --import tsx src/uploads/*.test.js",
     "test:render": "node --test src/render/*.test.js",
-    "test": "npm run test:clock && npm run test:capabilities && npm run test:studio && npm run test:uploads && npm run test:render && npm run test:moons && npm run test:star",
+    "test": "npm run test:clock && npm run test:capabilities && npm run test:notes && npm run test:studio && npm run test:uploads && npm run test:render && npm run test:moons && npm run test:star",
     "test:moons": "node --test src/moons/*.test.js",
     "test:star": "node --test --import tsx src/star/*.test.ts",
     "bench:star:build": "esbuild bench/star/main.ts --bundle --format=esm --target=es2022 --outfile=bench/star/build/main.js --log-level=warning",

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 });
   }
 }
 

package/src/notes/index.ts

@@ -0,0 +1,146 @@
+// Notes as events, shared by every note source (MIDI in, the on-screen keyboard, a capability call, a
+// MIDI effect, a room peer) and everything that routes or sounds them.
+//
+// On and off are separate events with no duration: a live key has no known length when it goes
+// down. They pair by `id`, never by pitch, since two sources can hold the same pitch at once and a
+// chord or an echo plays the same pitch more than once. Pairing by pitch alone gives stuck notes.
+//
+// App-agnostic: nothing here knows about Orbiters, dimensions or the audio graph.
+
+export type NoteEventType = 'on' | 'off'
+
+export interface NoteEvent {
+  type: NoteEventType
+  /** Unique per sounding note; an `off` carries the id of the `on` it ends. */
+  id: string
+  /** MIDI note number, 0 … 127 (integers today; the field allows fractions later). */
+  pitch: number
+  /** 0 … 1. An `off` may carry a release velocity; nothing reads it yet. */
+  velocity: number
+  /** Audio-context seconds when it should sound; at or before now means now. */
+  time: number
+  /** Who sent it: a device, the keyboard, a MIDI effect's slot, a room client. */
+  source: string
+}
+
+export const NOTE_PITCH_MIN = 0
+export const NOTE_PITCH_MAX = 127
+
+const isFiniteNumber = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
+
+/** Whether `value` is a well-formed note event (the shape a room peer or an agent must send). */
+export function isNoteEvent(value: unknown): value is NoteEvent {
+  if (!value || typeof value !== 'object') return false
+  const event = value as Record<string, unknown>
+  return (
+    (event.type === 'on' || event.type === 'off') &&
+    typeof event.id === 'string' &&
+    event.id.length > 0 &&
+    isFiniteNumber(event.pitch) &&
+    event.pitch >= NOTE_PITCH_MIN &&
+    event.pitch <= NOTE_PITCH_MAX &&
+    isFiniteNumber(event.velocity) &&
+    event.velocity >= 0 &&
+    event.velocity <= 1 &&
+    isFiniteNumber(event.time) &&
+    typeof event.source === 'string'
+  )
+}
+
+// ── MIDI ────────────────────────────────────────────────────────────────────
+
+/** What a channel message means to a note player. Channels are 0 … 15, as on the wire. */
+export type MidiNoteMessage =
+  | { kind: 'on'; channel: number; pitch: number; velocity: number }
+  | { kind: 'off'; channel: number; pitch: number; velocity: number }
+  /** Pitch bend, −1 … 1 (0 is the centre). */
+  | { kind: 'bend'; channel: number; value: number }
+  /** A control change, its value 0 … 1. */
+  | { kind: 'cc'; channel: number; controller: number; value: number }
+
+/** The mod wheel. */
+export const MIDI_CC_MOD_WHEEL = 1
+const BEND_CENTRE = 8192
+
+/**
+ * Decode a channel message's bytes. A note-on with velocity 0 is a note-off (running status sends
+ * them that way). Anything a note player has no use for (aftertouch, program change, system) is null.
+ */
+export function decodeMidiMessage(status: number, data1 = 0, data2 = 0): MidiNoteMessage | null {
+  const channel = status & 0x0f
+  switch (status & 0xf0) {
+    case 0x90:
+      return data2 > 0
+        ? { kind: 'on', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 }
+        : { kind: 'off', channel, pitch: data1 & 0x7f, velocity: 0 }
+    case 0x80:
+      return { kind: 'off', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 }
+    case 0xe0: {
+      // 14 bits, least significant first. The top is 8191 above the centre and the bottom 8192 below
+      // it, so each side is scaled on its own and both ends reach ±1.
+      const raw = ((data2 & 0x7f) << 7) | (data1 & 0x7f)
+      const offset = raw - BEND_CENTRE
+      return { kind: 'bend', channel, value: offset >= 0 ? offset / (BEND_CENTRE - 1) : offset / BEND_CENTRE }
+    }
+    case 0xb0:
+      return { kind: 'cc', channel, controller: data1 & 0x7f, value: (data2 & 0x7f) / 127 }
+    default:
+      return null
+  }
+}
+
+/**
+ * A MIDI note-off names only a channel and a pitch. This gives each held key its note id, so the
+ * off pairs with its on by id like every other source.
+ *
+ * - `on` mints a fresh id. If that key was already held (a device that sends two ons without an off)
+ *   the old note's id comes back as `replaced`, so the caller can end it first: nothing sticks.
+ * - `off` returns the id the key was playing, or null when it was never down (an off arriving after
+ *   a panic, or from before the page listened).
+ * - `releaseDevice` hands back every id a device holds: it went away, and they all end.
+ */
+export interface MidiNoteIds {
+  on(device: string, channel: number, pitch: number): { id: string; replaced: string | null }
+  off(device: string, channel: number, pitch: number): string | null
+  releaseDevice(device: string): string[]
+  releaseAll(): string[]
+  /** How many keys are down, across devices. */
+  readonly size: number
+}
+
+export function createMidiNoteIds(prefix = 'midi'): MidiNoteIds {
+  const held = new Map<string, string>()
+  let next = 0
+  const keyOf = (device: string, channel: number, pitch: number) => `${device}\u0000${channel}\u0000${pitch}`
+  const deviceOf = (key: string) => key.slice(0, key.indexOf('\u0000'))
+  const take = (predicate: (key: string) => boolean) => {
+    const ids: string[] = []
+    for (const [key, id] of held) {
+      if (!predicate(key)) continue
+      ids.push(id)
+      held.delete(key)
+    }
+    return ids
+  }
+  return {
+    on(device, channel, pitch) {
+      const key = keyOf(device, channel, pitch)
+      const replaced = held.get(key) ?? null
+      next += 1
+      const id = `${prefix}:${next}`
+      held.set(key, id)
+      return { id, replaced }
+    },
+    off(device, channel, pitch) {
+      const key = keyOf(device, channel, pitch)
+      const id = held.get(key) ?? null
+      held.delete(key)
+      return id
+    },
+    releaseDevice: (device) => take((key) => deviceOf(key) === device),
+    releaseAll: () => take(() => true),
+    get size() {
+      return held.size
+    },
+  }
+}