Wrap pitch mod 256 to match BBC byte register

The BBC's per-channel pitch is a single 8-bit byte and the OS uses
the 6502 ADC for envelope PI updates, so adding a negative PI to a
low pitch wraps up to a high pitch (e.g. 1 + -26 = 0xE7 = 231), not
to a clamped low value.

pitchToHz was clamping to 0..255 and the visualiser was plotting the
unwrapped basePitch + offset directly, so any envelope that drove the
pitch negative came out flat at the lowest BBC note instead of
producing the wrapping pitch effect heard on real hardware. The BBC
User Guide reference envelope 1,1,-26,-36,-45,255,255,255,127,0,0,0,
126,0 exposed this.

Fix is centralised in pitchToHz (clamp -> & 0xff) so any caller can
pass a signed integer; the visualiser now also computes wrapped
pitches for its plot and auto-scale, so what's drawn matches what's
audible.

Author: kieranhj

src/envelope.ts

@@ -286,9 +286,13 @@ const PITCH_HIGH = [0xE7, 0xD7, 0xCB, 0xC3, 0xB7, 0xAA, 0xA2, 0x9A, 0x92, 0x8A,
  * right-shifts of the 10-bit divider, which causes the BBC's tuning to drift
  * slightly sharp of equal temperament in higher octaves — that quirk is
  * what we want to reproduce so playback matches the real machine.
+ *
+ * The input is wrapped mod 256 because the BBC's pitch register is a single
+ * byte and the OS adds PI to it with the 6502's natural byte wrap. Negative
+ * envelope offsets must wrap up to high pitches, not clamp at 0.
  */
 export function pitchToHz(pitch: number): number {
-  const p = clamp(pitch, 0, 255) | 0;
+  const p = (pitch | 0) & 0xff;
   const fractional = p & 3;
   let count = p >> 2;
   let octave = 0;

src/visualizer.ts

@@ -111,12 +111,14 @@ export function render(
   ctx.textBaseline = "alphabetic";
   ctx.font = "12px system-ui, sans-serif";
 
-  // Pitch plot: absolute BBC pitch (basePitch + envelope offset). Auto-scale
-  // around the base pitch with at least one semitone of headroom each side
-  // and snap to semitone boundaries so gridlines land cleanly.
+  // Pitch plot: absolute BBC pitch (basePitch + envelope offset, wrapped
+  // mod 256 to match the BBC's single-byte pitch register). Auto-scale
+  // around the actual pitches used with at least one semitone of headroom
+  // each side, snapping to semitone boundaries.
+  const wrappedPitch = (offset: number): number => (basePitch + offset) & 0xff;
   let minP = basePitch, maxP = basePitch;
   for (const s of samples) {
-    const p = basePitch + s.pitchOffset;
+    const p = wrappedPitch(s.pitchOffset);
     if (p < minP) minP = p;
     if (p > maxP) maxP = p;
   }
@@ -157,7 +159,7 @@ export function render(
   ctx.lineWidth = 2;
   for (let i = 0; i < samples.length; i++) {
     const x = xFor(i);
-    const y = pitchY(basePitch + samples[i]!.pitchOffset);
+    const y = pitchY(wrappedPitch(samples[i]!.pitchOffset));
     if (i === 0) ctx.moveTo(x, y);
     else ctx.lineTo(x, y);
   }