castle-web-cli 0.4.114 → 0.4.116

package/kits/physics-2d/engine/pxartSmooth.js

@@ -7,71 +7,38 @@
 // the normal 1px/cell `renderSpriteFrame`.
 //
 // This is a LOCAL, per-pixel kernel filter — the same shape of algorithm as
-// Animal Crossing's actual smoothing (xBRZ-style template matching), not the
-// global boundary-trace-and-round approach this file used to implement. That
-// approach traced each region's FULL pixel-boundary loop and could detect
-// long straight/staircase runs across the whole loop; it looked fine on
-// blocky shapes but flattened organic curves it decided were "too regular",
-// which isn't fixable by tuning since the run detection itself is the
-// problem. This version never looks past a pixel's immediate 3x3
-// neighborhood, so there is no run/regularity detection to mis-fire — it
-// physically cannot flatten a curve, because it has no notion of a curve at
-// all, only of each corner in isolation.
-//
-// Approach, per source pixel P:
-//   1. Composite the frame normally (`renderSpriteFrame` — this already
-//      handles layer visibility/opacity/blend), then read back the native
-//      resolution raster. Regions are exact-RGBA-equality color runs, same as
-//      before.
-//   2. Supersample: P gets its own `scale` x `scale` block of the output
-//      canvas (plain grid subdivision — every output pixel belongs to
-//      exactly one source pixel's block, so there is no possibility of a
-//      gap or overlap between neighboring pixels' rendering).
-//   3. Fill P's whole block with its own color, then independently classify
-//      each of P's 4 corners against ONLY the 3 pixels touching that corner
-//      (2 edge-adjacent neighbors + 1 diagonal) and, for genuine convex
-//      corners, paint a `cornerRadius`-sized quarter-circle "cut" over that
-//      corner revealing the relevant neighbor's color (see `cornerFill`).
-// Because every pixel only ever paints within its OWN block, this recoloring
-// can never create a gap: it's the same guarantee a supersampled nearest-
-// neighbor render already has, just with a softened corner instead of a hard
-// one.
-//
-// Kept as a sibling of pxart.js (rather than inside it) so the format
-// parser/serializer stays focused on the on-disk shape.
+// Animal Crossing's actual smoothing (xBRZ-style template matching), not a
+// global vectorization pass. Under `renderer: "vector"`,
+// `renderSmoothCompositeFrame` paints each path layer's shape stack
+// analytically into the supersampled canvas (even-odd fills + 1-cell-wide
+// round-cap strokes) in painter's order.
 // ============================================================================
 
-import { MAX_CORNER_RADIUS, renderSpriteFrame } from './pxart';
+import {
+  MAX_CORNER_RADIUS,
+  colorForKeyV2,
+  isVectorRenderer,
+  paletteLookup,
+  renderSpriteFrame,
+  resolveCell,
+} from './pxart';
+import { absoluteSegment, normalizeSubpath } from './pxartPath.js';
 
 export const DEFAULT_SMOOTH_SCALE = 8;
 
-// Fallback only for a caller that omits `cornerRadius` entirely; every real
-// caller passes the sprite's own file-level `cornerRadius` value (see
-// docs/pxart-format.md and Sprite.jsx/PxArtEditor.jsx), which is how the
-// corner radius ends up being a portable, per-sprite part of the format
-// rather than a fixed constant every smooth sprite is stuck with.
 const FALLBACK_CORNER_RADIUS = 0.25;
 
-/** Render one frame of a Sprite with locally corner-rounded fills,
- *  supersampled into `canvas` (sized to width*scale x height*scale). Reuses
- *  `renderSpriteFrame` for compositing (layers, opacity, visibility, blend),
- *  so those keep working unchanged. `cornerRadius` is in native-pixel units,
- *  clamped to `MAX_CORNER_RADIUS` (two cuts on the same edge must not
- *  overlap). */
+/** Render one frame with locally corner-rounded fills. */
 export function renderSmoothSpriteFrame(
   sprite,
   frameIndex,
   canvas,
-  { scale = DEFAULT_SMOOTH_SCALE, cornerRadius = FALLBACK_CORNER_RADIUS } = {}
+  { scale = DEFAULT_SMOOTH_SCALE, cornerRadius = FALLBACK_CORNER_RADIUS } = {},
 ) {
   const clampedRadius = Math.min(MAX_CORNER_RADIUS, Math.max(0, cornerRadius));
-  const { width, height } = sprite.resolution;
-  canvas.width = Math.max(1, Math.round(width * scale));
-  canvas.height = Math.max(1, Math.round(height * scale));
-  const ctx = canvas.getContext('2d');
-  if (!ctx) return;
-  ctx.clearRect(0, 0, canvas.width, canvas.height);
-  if (width <= 0 || height <= 0) return;
+  const target = setupScaledCanvas(canvas, sprite.resolution, scale);
+  if (!target) return;
+  const { ctx, width, height } = target;
 
   const native = document.createElement('canvas');
   renderSpriteFrame(sprite, frameIndex, native);
@@ -79,9 +46,6 @@ export function renderSmoothSpriteFrame(
   const data = nctx?.getImageData(0, 0, width, height).data;
   if (!data) return;
 
-  // null = out of canvas OR fully transparent; both read as "not this pixel's
-  // color" to every classification below, same as the old mask's treatment
-  // of out-of-canvas/transparent as background.
   const colorAt = (x, y) => {
     if (x < 0 || x >= width || y < 0 || y >= height) return null;
     const i = (y * width + x) * 4;
@@ -90,31 +54,215 @@ export function renderSmoothSpriteFrame(
   };
 
   ctx.save();
-  ctx.scale(scale, scale);
-  // Every pixel is processed, including transparent ones: a fully-enclosed
-  // transparent "hole" is, from its own corners' point of view, exactly the
-  // same kind of convex corner as an opaque pixel poking out of a
-  // background — it needs to cut (and round) its OWN corners the same way,
-  // or an enclosed 1px hole would stay a hard square forever (its opaque
-  // neighbors never round toward it, by the same-neighbor rule below).
+  ctx.imageSmoothingEnabled = false;
   for (let y = 0; y < height; y++) {
-    for (let x = 0; x < width; x++) drawPixelBlock(ctx, colorAt, x, y, colorAt(x, y), clampedRadius);
+    for (let x = 0; x < width; x++) {
+      drawPixelBlock(ctx, colorAt, x, y, scale, colorAt(x, y), clampedRadius);
+    }
   }
   ctx.restore();
 }
 
+// Render the "smooth" finish one layer at a time. Path layers paint their
+// shape stack analytically at supersample; pixel layers use maximum corner
+// smoothing. Layer visibility and opacity remain authoritative.
+export function renderSmoothCompositeFrame(
+  sprite,
+  frameIndex,
+  canvas,
+  { scale = DEFAULT_SMOOTH_SCALE } = {},
+) {
+  const target = setupScaledCanvas(canvas, sprite.resolution, scale);
+  if (!target) return;
+  const { ctx, width, height } = target;
+
+  const lookup = paletteLookup(sprite.palette);
+  const prevAlpha = ctx.globalAlpha;
+  for (const layer of sprite.layers) {
+    if (!layer.visible || layer.opacity <= 0) continue;
+    const resolved = resolveCell(layer, frameIndex);
+    if (!resolved) continue;
+    ctx.globalAlpha = Math.min(1, Math.max(0, layer.opacity));
+    drawScaledLayer(ctx, sprite, layer, resolved, frameIndex, {
+      scale,
+      width,
+      height,
+      lookup,
+      analyticPath: true,
+      cornerRadius: MAX_CORNER_RADIUS,
+    });
+  }
+  ctx.globalAlpha = prevAlpha;
+}
+
+/**
+ * Draw one resolved layer into `ctx` at `scale`. A path layer renders
+ * analytically from its shape stack when `analyticPath`; everything else goes
+ * through the corner kernel at `cornerRadius`.
+ */
+function drawScaledLayer(
+  ctx,
+  sprite,
+  layer,
+  resolved,
+  frameIndex,
+  { scale, width, height, lookup, analyticPath, cornerRadius },
+) {
+  if (analyticPath && layer.kind === 'path' && resolved.path) {
+    const layerCanvas = renderScaledPathCell(resolved.path, width, height, scale, lookup);
+    ctx.drawImage(layerCanvas, Math.round(resolved.x * scale), Math.round(resolved.y * scale));
+    return;
+  }
+  const layerCanvas = document.createElement('canvas');
+  const single = { ...sprite, layers: [{ ...layer, visible: true, opacity: 1 }] };
+  renderSmoothSpriteFrame(single, frameIndex, layerCanvas, { scale, cornerRadius });
+  ctx.drawImage(layerCanvas, 0, 0);
+}
+
+/** Finish render of one (layer, frame) cell — path layers analytic under the
+ *  vector renderer, else baked grid + corner kernel. */
+export function renderSmoothLayerCell(
+  sprite,
+  layerIndex,
+  frameIndex,
+  canvas,
+  { scale = DEFAULT_SMOOTH_SCALE } = {},
+) {
+  const layer = sprite.layers[layerIndex];
+  if (!layer) return;
+  const resolved = resolveCell(layer, frameIndex);
+  if (!resolved) return;
+  const vector = isVectorRenderer(sprite.renderer);
+  const radius = sprite.cornerRadius ?? 0;
+  // Nothing to add over the plain nearest-neighbor blit.
+  if (!vector && radius === 0) return;
+
+  const { width, height } = sprite.resolution;
+  const lookup = paletteLookup(sprite.palette);
+  const target = setupScaledCanvas(canvas, sprite.resolution, scale);
+  if (!target) return;
+  const { ctx } = target;
+
+  const prevAlpha = ctx.globalAlpha;
+  ctx.globalAlpha = Math.min(1, Math.max(0, layer.opacity ?? 1));
+  drawScaledLayer(ctx, sprite, layer, resolved, frameIndex, {
+    scale,
+    width,
+    height,
+    lookup,
+    analyticPath: vector,
+    cornerRadius: vector ? MAX_CORNER_RADIUS : radius,
+  });
+  ctx.globalAlpha = prevAlpha;
+}
+
+function setupScaledCanvas(canvas, resolution, scale) {
+  const { width, height } = resolution;
+  canvas.width = Math.max(1, Math.round(width * scale));
+  canvas.height = Math.max(1, Math.round(height * scale));
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return null;
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  return width > 0 && height > 0 ? { ctx, width, height } : null;
+}
+
+/**
+ * Analytic smooth render of a stacked path: fills as even-odd canvas paths,
+ * strokes as 1-cell-wide analytic strokes with round caps/joins along the
+ * true curves, shapes in stack order.
+ */
+function renderScaledPathCell(path, width, height, scale, lookup) {
+  const w = Math.max(1, Math.round(width * scale));
+  const h = Math.max(1, Math.round(height * scale));
+  const off = document.createElement('canvas');
+  off.width = w;
+  off.height = h;
+  const octx = off.getContext('2d');
+  if (!octx) return off;
+
+  for (const shape of path?.shapes ?? []) {
+    if (shape.fill) {
+      const color = colorForKeyV2(lookup, shape.fill);
+      if (color) {
+        const geometry = buildFillPath2D(shape, scale);
+        if (geometry) {
+          octx.fillStyle = color;
+          octx.fill(geometry, 'evenodd');
+        }
+      }
+    }
+    if (shape.stroke) {
+      const color = colorForKeyV2(lookup, shape.stroke);
+      if (color) {
+        octx.save();
+        octx.strokeStyle = color;
+        octx.lineWidth = scale; // 1 native cell
+        octx.lineCap = 'round';
+        octx.lineJoin = 'round';
+        for (const sub of shape.subpaths ?? []) {
+          const strokePath = buildSubpathPath2D(sub, scale);
+          if (strokePath) octx.stroke(strokePath);
+        }
+        octx.restore();
+      }
+    }
+  }
+  return off;
+}
+
+function buildFillPath2D(shape, scale) {
+  const geometry = new Path2D();
+  let any = false;
+  for (const sub of shape.subpaths ?? []) {
+    if (!sub.closed) continue;
+    if (appendSubpath(geometry, sub, scale)) any = true;
+  }
+  return any ? geometry : null;
+}
+
+function buildSubpathPath2D(sub, scale) {
+  const geometry = new Path2D();
+  if (!appendSubpath(geometry, sub, scale)) return null;
+  return geometry;
+}
+
+function appendSubpath(geometry, raw, scale) {
+  // Read through the same funnel as the bake does. A subpath still stored in
+  // the pre-segment form has no `start`, so reading it raw drew nothing at all
+  // — art that baked correctly at Pixel vanished at the smooth finishes.
+  const sub = normalizeSubpath(raw);
+  if (!sub?.start) return false;
+  geometry.moveTo(sub.start[0] * scale, sub.start[1] * scale);
+  let from = sub.start;
+  for (const seg of sub.segs ?? []) {
+    if (!seg.c1 && !seg.c2) {
+      geometry.lineTo(seg.to[0] * scale, seg.to[1] * scale);
+    } else {
+      const { c1, c2, to } = absoluteSegment(from, seg);
+      geometry.bezierCurveTo(
+        c1[0] * scale,
+        c1[1] * scale,
+        c2[0] * scale,
+        c2[1] * scale,
+        to[0] * scale,
+        to[1] * scale
+      );
+    }
+    from = seg.to;
+  }
+  if (sub.closed) geometry.closePath();
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // per-pixel local corner kernel
 // ---------------------------------------------------------------------------
 
 const NO_CUT = undefined;
 
-// Fill pixel (x, y)'s own unit square [x, x+1] x [y, y+1] with `color` (a
-// no-op when `color` is null — transparent, nothing to fill), then paint a
-// small rounded cut over each of its 4 corners that qualifies (see
-// `cornerFill`). Uses ONLY the 3x3 neighborhood of (x, y) — genuinely local,
-// unlike the old global loop trace.
-function drawPixelBlock(ctx, colorAt, x, y, color, cornerRadius) {
+function drawPixelBlock(ctx, colorAt, x, y, scale, color, cornerRadius) {
+  const px = x * scale;
+  const py = y * scale;
   const north = colorAt(x, y - 1);
   const south = colorAt(x, y + 1);
   const west = colorAt(x - 1, y);
@@ -129,20 +277,19 @@ function drawPixelBlock(ctx, colorAt, x, y, color, cornerRadius) {
 
   if (color) {
     ctx.fillStyle = rgbaFillStyle(color);
-    ctx.fillRect(x, y, 1, 1);
+    ctx.fillRect(px, py, scale, scale);
   }
 
   if (cornerRadius <= 0) return;
+  const r = cornerRadius * scale;
   for (const [corner, reveal] of cuts) {
     if (reveal === NO_CUT) continue;
     ctx.beginPath();
-    tracePixelWedge(ctx, corner, x, y, cornerRadius);
+    tracePixelWedge(ctx, corner, px, py, scale, r);
     if (reveal === null) {
-      // Revealing transparency: clip to the wedge and clear it, rather than
-      // fill it, since there's no color to paint.
       ctx.save();
       ctx.clip();
-      ctx.clearRect(x, y, 1, 1);
+      ctx.clearRect(px, py, scale, scale);
       ctx.restore();
     } else {
       ctx.fillStyle = rgbaFillStyle(reveal);
@@ -151,72 +298,76 @@ function drawPixelBlock(ctx, colorAt, x, y, color, cornerRadius) {
   }
 }
 
-// Classify one corner of pixel `color`, given its two edge-adjacent
-// neighbors (`a`, `b`) and its diagonal neighbor (`g`). Returns the neighbor
-// color to reveal at that corner's rounded cut, or `NO_CUT` to leave the
-// corner sharp:
-//   - `a` or `b` matches `color`: either a flat/interior corner, or (when
-//     they don't BOTH match) a straight edge passing by rather than a real
-//     corner. Either way, nothing to round from P's side — a matching
-//     neighbor's OWN corner classification (evaluated independently, when
-//     IT is P) is what rounds the opposite case; the physical wedge that
-//     gets cut always lives entirely inside whichever pixel's corner is
-//     convex, so there's no double-handling.
-//   - neither `a` nor `b` matches, but `g` DOES: a diagonal touch between
-//     two same-colored pixels (the "checkerboard" case). Left uncut, so a
-//     smoothed diagonal stroke doesn't get visually pinched off at every
-//     step.
-//   - neither `a`, `b`, nor `g` matches, and `a` and `b` are THE SAME color:
-//     a genuine, unambiguous convex corner of P's own region touching one
-//     other region. Cut it, revealing that color.
-//   - neither `a`, `b`, nor `g` matches, and `a` and `b` DIFFER: three (or
-//     four, counting `g`) distinct colors meet at this exact point — e.g. a
-//     "T" where one region's straight edge is crossed by the boundary
-//     between two others. Left uncut. Rounding here would have to guess
-//     which of `a`/`b` "wins", and since the pixel on the OTHER side of
-//     that guess is classifying this same point independently — and would
-//     guess differently — a pair of pixels each revealing the OTHER's
-//     color produces a little criss-crossed notch instead of one clean
-//     curve. Leaving every pixel at a 3+-way point sharp keeps it a single
-//     consistent (if unrounded) vertex.
 function cornerFill(color, a, b, g) {
   if (a === color || b === color) return NO_CUT;
   if (g === color) return NO_CUT;
   return a === b ? a : NO_CUT;
 }
 
-// `color` is always a `"r,g,b,a"` string (0-255 channels, alpha 0-255) —
-// see `colorAt` — never the transparent sentinel (only opaque colors ever
-// reach this function as `color`, only ever as `reveal`).
 function rgbaFillStyle(color) {
   const [r, g, b, a] = color.split(',').map(Number);
   return `rgba(${r}, ${g}, ${b}, ${a / 255})`;
 }
 
-// Trace the small corner wedge that gets cut from pixel (x, y)'s unit square
-// at `corner` (one of 'TL' | 'TR' | 'BL' | 'BR'): the sliver between the
-// exact corner point and the quarter-circle of radius `r` tangent to both
-// adjacent edges at distance `r` from the corner — i.e. exactly the piece a
-// standard rounded-rect corner removes from a sharp one. `ctx.arcTo`'s
-// corner-point-as-control-point form draws that same tangent arc without
-// hand-computed sweep angles.
-function tracePixelWedge(ctx, corner, x, y, r) {
+/** Display-resolution ghost of native cells using the same corner kernel as placed pixels. */
+export function renderSmoothCellsPreview(
+  ctx,
+  cells,
+  color,
+  { scale, cornerRadius, alpha = 1 } = {},
+) {
+  if (!cells?.length || !scale || cornerRadius <= 0) return;
+  const clampedRadius = Math.min(MAX_CORNER_RADIUS, Math.max(0, cornerRadius));
+  const cellSet = new Set(cells.map((c) => `${c.x},${c.y}`));
+  const rgba = cssColorToRgbaString(color, alpha);
+  const colorAt = (x, y) => (cellSet.has(`${x},${y}`) ? rgba : null);
+
+  ctx.save();
+  ctx.imageSmoothingEnabled = false;
+  ctx.globalAlpha = 1;
+  for (const { x, y } of cells) {
+    drawPixelBlock(ctx, colorAt, x, y, scale, rgba, clampedRadius);
+  }
+  ctx.restore();
+}
+
+function cssColorToRgbaString(color, alpha = 1) {
+  let r = 255;
+  let g = 255;
+  let b = 255;
+  if (typeof color === 'string' && color.startsWith('#')) {
+    const h = color.slice(1);
+    if (h.length === 3) {
+      r = parseInt(h[0] + h[0], 16);
+      g = parseInt(h[1] + h[1], 16);
+      b = parseInt(h[2] + h[2], 16);
+    } else if (h.length >= 6) {
+      r = parseInt(h.slice(0, 2), 16);
+      g = parseInt(h.slice(2, 4), 16);
+      b = parseInt(h.slice(4, 6), 16);
+    }
+  }
+  const a = Math.round(Math.min(1, Math.max(0, alpha)) * 255);
+  return `${r},${g},${b},${a}`;
+}
+
+function tracePixelWedge(ctx, corner, px, py, cell, r) {
   if (corner === 'TL') {
-    ctx.moveTo(x, y);
-    ctx.lineTo(x + r, y);
-    ctx.arcTo(x, y, x, y + r, r);
+    ctx.moveTo(px, py);
+    ctx.lineTo(px + r, py);
+    ctx.arcTo(px, py, px, py + r, r);
   } else if (corner === 'TR') {
-    ctx.moveTo(x + 1, y);
-    ctx.lineTo(x + 1, y + r);
-    ctx.arcTo(x + 1, y, x + 1 - r, y, r);
+    ctx.moveTo(px + cell, py);
+    ctx.lineTo(px + cell, py + r);
+    ctx.arcTo(px + cell, py, px + cell - r, py, r);
   } else if (corner === 'BL') {
-    ctx.moveTo(x, y + 1);
-    ctx.lineTo(x, y + 1 - r);
-    ctx.arcTo(x, y + 1, x + r, y + 1, r);
+    ctx.moveTo(px, py + cell);
+    ctx.lineTo(px, py + cell - r);
+    ctx.arcTo(px, py + cell, px + r, py + cell, r);
   } else {
-    ctx.moveTo(x + 1, y + 1);
-    ctx.lineTo(x + 1 - r, y + 1);
-    ctx.arcTo(x + 1, y + 1, x + 1, y + 1 - r, r);
+    ctx.moveTo(px + cell, py + cell);
+    ctx.lineTo(px + cell - r, py + cell);
+    ctx.arcTo(px + cell, py + cell, px + cell, py + cell - r, r);
   }
   ctx.closePath();
 }

package/kits/physics-2d/engine/scene.js

@@ -61,6 +61,15 @@ export class SceneRuntime {
     return system;
   }
 
+  // Tear this runtime down for good: the player is unmounting, or the editor
+  // left play mode. `reset` is for "start this scene over" and runs on every
+  // load; this is "nothing of this runtime should still be happening", which is
+  // the difference that matters to a system holding something the browser keeps
+  // doing on its own -- a playing sound outlives its scene otherwise.
+  dispose() {
+    for (const system of this.systems) system.dispose?.(this);
+  }
+
   load(sceneData) {
     // Reset registered systems (e.g. physics) so a reload/restart/scene
     // transition starts from the authored layout -- otherwise a system holding
@@ -611,6 +620,9 @@ function drawDotGrid(ctx, gridSize = 25, viewport = DEFAULT_VIEWPORT, camera = {
 // represented separately by the DOM SelectionOverlay's solid white box, so a
 // Sprite-backed actor never shows this box, selected or not.
 function shouldDrawEditPlaceholder(actor, sprites) {
+  // A Video draws its own picture into the box, so the actor is not sprite-less
+  // in the sense this box is for.
+  if (actor?.components?.Video?.file) return false;
   const sprite = actor?.components?.Sprite;
   if (!sprite || !sprite.file) return true;
   const resolved = sprites?.[sprite.file];

package/kits/physics-2d/engine/tone.js

@@ -0,0 +1,112 @@
+// A synthesized note: one oscillator through an attack/release envelope. This
+// is the sound a deck can make with no audio file at all -- a blip on a pickup,
+// a beep on a wrong answer -- and it costs nothing to ship.
+//
+// Deliberately one voice and two envelope stages, matching what the classic
+// Castle editor's "tone" sample offers. Anything richer is an instrument, and an
+// instrument belongs in a music system, not here.
+
+import { getAudioContext, resumeAudioContext } from './audioContext';
+
+export const WAVEFORMS = ['square', 'sawtooth', 'sine', 'triangle', 'noise'];
+
+// Voices currently sounding, so play mode can be silenced on Stop.
+const voices = new Set();
+
+// MIDI note number to Hz. 69 is A440, 12 notes to the octave.
+export function noteToFrequency(note) {
+  const midi = Number.isFinite(note) ? note : 60;
+  return 440 * Math.pow(2, (midi - 69) / 12);
+}
+
+// A short burst of white noise, made once and reused. Noise is the one waveform
+// an oscillator can't produce, and it's what a percussive hit wants.
+let noiseBuffer = null;
+function getNoiseBuffer(ctx) {
+  if (noiseBuffer && noiseBuffer.sampleRate === ctx.sampleRate) return noiseBuffer;
+  const frames = Math.floor(ctx.sampleRate * 2);
+  const buffer = ctx.createBuffer(1, frames, ctx.sampleRate);
+  const data = buffer.getChannelData(0);
+  for (let i = 0; i < frames; i++) data[i] = Math.random() * 2 - 1;
+  noiseBuffer = buffer;
+  return buffer;
+}
+
+function makeSource(ctx, waveform, frequency) {
+  if (waveform === 'noise') {
+    const source = ctx.createBufferSource();
+    source.buffer = getNoiseBuffer(ctx);
+    source.loop = true;
+    return source;
+  }
+  const osc = ctx.createOscillator();
+  osc.type = WAVEFORMS.includes(waveform) ? waveform : 'square';
+  osc.frequency.value = frequency;
+  return osc;
+}
+
+// Play one note. Returns `{ stop, finished }` -- `finished` resolves when the
+// release has run out, so a caller can wait for it the way a Sound can.
+export function playTone({ note = 60, waveform = 'square', attack = 0, release = 0.4, volume = 1, pan = 0 } = {}) {
+  const ctx = getAudioContext();
+  if (!ctx) return { stop() {}, finished: Promise.resolve() };
+  resumeAudioContext();
+
+  const level = Number.isFinite(volume) ? Math.min(1, Math.max(0, volume)) : 1;
+  const rise = Math.max(0, Number.isFinite(attack) ? attack : 0);
+  // A note with no release at all clicks; give it a floor short enough to still
+  // read as instant.
+  const fall = Math.max(0.01, Number.isFinite(release) ? release : 0.4);
+  const start = ctx.currentTime;
+  const end = start + rise + fall;
+
+  const source = makeSource(ctx, waveform, noteToFrequency(note));
+  const gain = ctx.createGain();
+  gain.gain.setValueAtTime(0, start);
+  gain.gain.linearRampToValueAtTime(level, start + rise);
+  gain.gain.linearRampToValueAtTime(0, end);
+
+  let tail = gain;
+  if (pan && ctx.createStereoPanner) {
+    const panner = ctx.createStereoPanner();
+    panner.pan.value = Math.min(1, Math.max(-1, pan));
+    gain.connect(panner);
+    tail = panner;
+  }
+  source.connect(gain);
+  tail.connect(ctx.destination);
+  source.start(start);
+  source.stop(end);
+
+  const voice = { source, gain };
+  voices.add(voice);
+  const finished = new Promise((resolve) => {
+    source.addEventListener('ended', () => {
+      voices.delete(voice);
+      resolve();
+    });
+  });
+  return {
+    stop() {
+      voices.delete(voice);
+      try {
+        source.stop();
+      } catch {
+        // Already stopped -- nothing to do.
+      }
+    },
+    finished,
+  };
+}
+
+// Silence every sounding note. Play mode ending must not leave one ringing.
+export function stopAllTones() {
+  for (const voice of voices) {
+    try {
+      voice.source.stop();
+    } catch {
+      // Already stopped.
+    }
+  }
+  voices.clear();
+}