first commit

docs/media/audio/audio-transport/src/signal/signal.md

@@ -0,0 +1,63 @@
+# Signal
+
+The `Signal` class implements a piecewise automation curve for scalar parameters such as BPM. It stores automation points and evaluates the curve at any audio time, supporting step, linear, and exponential ramps.
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Musical performances often require smooth tempo changes. `Signal` provides the mathematical foundation for these changes by scheduling automation points and interpolating between them. The `TickSource` reads the BPM curve through this `Signal` so that tempo ramps produce a continuously varying tick rate.
+
+## Features
+
+- `setValueAtTime` for step changes
+- `linearRampToValueAtTime` for linear interpolation
+- `exponentialRampToValueAtTime` for exponential curves
+- `getValueAtTime` for curve evaluation at arbitrary times
+- `cancelScheduledValues` for clearing future points
+- Rejects non-positive and non-finite values with `AUDIO_TRANSPORT_INVALID_BPM`
+
+## Usage: Basic
+
+```ts
+import { Signal } from "@suaveplan/audio-transport";
+
+const bpm = new Signal({ initialValue: 120 });
+bpm.linearRampToValueAtTime(240, 1);
+console.log(bpm.getValueAtTime(0.5)); // 180
+```
+
+## Usage: Advanced
+
+```ts
+const bpm = new Signal({ initialValue: 100 });
+bpm.setValueAtTime(120, 0.5);
+bpm.exponentialRampToValueAtTime(240, 1.5);
+console.log(bpm.getValueAtTime(1)); // ~169.7
+```
+
+## API Reference
+
+### Constructor
+
+`new Signal(options?)`
+
+### Properties
+
+- `initialValue` — value before any points
+- `value` — convenience getter returning value at time 0
+- `points` — readonly array of automation points
+
+### Methods
+
+- `setValueAtTime(value, time)` — step change
+- `linearRampToValueAtTime(value, time)` — linear ramp
+- `exponentialRampToValueAtTime(value, time)` — exponential ramp
+- `getValueAtTime(time)` — evaluate curve
+- `cancelScheduledValues(time)` — remove points at or after time
+
+## Implementation Notes
+
+Points are stored sorted by time. Exponential ramps require strictly positive start and target values; otherwise `AUDIO_TRANSPORT_INVALID_BPM` is thrown. The curve evaluation handles interpolation before the first point, between points, and after the last point.

docs/media/audio/audio-transport/src/signal/signal.schemas.md

@@ -0,0 +1,27 @@
+# SignalOptionsSchema
+
+Zod boundary schema for `Signal` construction options.
+
+## Purpose
+
+Validates the options passed when constructing a `Signal`.
+
+## Features
+
+- Optional `initialValue` as positive number
+
+## Usage
+
+```ts
+import { SignalOptionsSchema } from "@suaveplan/audio-transport";
+
+const parsed = SignalOptionsSchema.safeParse({ initialValue: 130 });
+```
+
+## API Reference
+
+- `SignalOptionsSchema` — `z.object({ initialValue })`
+
+## Implementation Notes
+
+The schema is minimal because `Signal` only needs an initial value. All other behavior is controlled via method calls after construction.