dewdrop-sdk 0.4.0 → 0.5.0

package/README.md

@@ -20,15 +20,16 @@ export default { plugins: [dew()] };
 
 `npx dewctl init` sets up a new game this way, with the Dewdrop CLI beside it.
 To update a project, run `npm install -D dewdrop-sdk@latest`; saves need 0.4.0
-or later.
+or later, voice 0.5.0.
 
 ## Saves locally
 
 On Dewdrop, `localStorage` and IndexedDB aren't local: nothing your game
 writes to them is stored in the player's browser or on their device, and they
 start empty each time a player opens your game. `saves.save()` keeps what they
-hold in Dewdrop's storage for that player, and `saves.load()` puts it back;
-each upload of your game starts with none.
+hold in Dewdrop's storage for that player, and `saves.load()` puts it back,
+in later uploads of your game too. A game with a `backend.js` keeps no saves:
+its state is its rooms', and both calls refuse with `NotSupportedError`.
 `npm run dev` does the same in your browser: every page load starts with
 `localStorage` and IndexedDB empty, and saves are kept in the browser, in a
 database named `dewdrop-saves` your game doesn't see, for the game
@@ -36,6 +37,72 @@ database named `dewdrop-saves` your game doesn't see, for the game
 of one dev server share the browser's storage, so loading one empties the
 others'.
 
+## Rooms locally
+
+`npm run dev` runs your `backend.js` for each room the tabs join: `?room=`
+names the room, `?player=` the player, and `?players=` how many players a
+room the tab opens seats, 100 unless it says 1 to 100, as Dewdrop's rooms
+do; `?players=1` is singleplayer. A player is counted once however many tabs
+they play from, and a tab past a full room is refused, with the reason in
+the console. In the backend, `clients.capacity` is the room's size.
+
+## Sessions that end
+
+On Dewdrop a session can end ahead of time: for maintenance, or a newer
+version of your game published. Its player sees a countdown and reconnects
+on their own, and your game hears of it first, up to fifteen minutes
+before: `session.ending` from `dewdrop-sdk` is `{at, reason}`, `at` in
+milliseconds as `Date.now()` counts and `reason` `'restart'` or `'update'`,
+and an `ending` event fires each time it changes, its withdrawal to `null`
+included. Call `saves.save()` then to keep what the player has done. `npm
+run dev` ends no session ahead of time, so `session.ending` stays `null`
+there.
+
+## Voice
+
+```js
+import { backend, voice } from 'dewdrop-sdk';
+
+// This player's microphone, a chunk at a time, sent to the backend each frame.
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+const capture = voice.capture(stream);                 // capture.stop() to go quiet
+function frame() {
+  for (const chunk of capture.read()) backend.send(chunk);  // Int16Array, 800 samples at 48 kHz
+  requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+
+// Another player's voice, as the backend sends it on: from their figure,
+// loud up close, fading with distance.
+const source = voice.source(listener.context);
+const sound = new PositionalAudio(listener);           // on their avatar
+sound.setNodeSource(source.node);                      // or source.node.connect(anywhere)
+backend.onmessage = ({ data }) => source.write(new Int16Array(data, 4));  // behind the backend's own header
+```
+
+Dewdrop carries no voice between players itself: your `backend.js`
+decides who hears whom — those within earshot, a team, everyone — and
+sends each chunk on through its ordinary messages, so a game can mix,
+mute, record or transcribe as it sees fit. `voice.capture(stream)` takes
+the live microphone stream from `getUserMedia` and hands back the
+capture: `read()` returns the chunks that arrived since the last read,
+each an `Int16Array` of 800 samples, mono, at `voice.SAMPLE_RATE`
+(48 kHz), and `stop()` ends it; one capture at a time, a second throws
+an `InvalidStateError`. A read is at most eight chunks of 1,600 bytes,
+which a client's frame sends to its backend whole within its 16 KiB
+with room beside, so a game may send every chunk it reads; a backend's
+frame sends some 160 copies on within its 256 KiB, so a crowd all
+speaking at once is more than one frame carries and a backend sheds the
+rest — voice is late or nothing — or compresses first. `voice.source(context)`
+is plain Web Audio: `node` is a node of `context` for `connect` or a
+three.js `PositionalAudio`'s `setNodeSource`, `write(samples)` plays an
+`Int16Array` or `Float32Array` right after those written before it —
+the first two chunks ahead of the clock, so a chunk a little early or
+late plays without a gap — dropping what runs eight chunks ahead, and
+`close()` leaves the graph. `npm run dev` reads your browser's
+microphone through an audio worklet and hands your game the same chunks,
+so voice works between tabs locally as it does on Dewdrop.
+
 ## Docs
 
 How to build your game, from the look to model calls, multiplayer, saves and

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dewdrop-sdk",
-  "version": "0.4.0",
-  "description": "Build a three.js game for Dewdrop: the Vite plugin, model calls, multiplayer and saves.",
+  "version": "0.5.0",
+  "description": "Build a three.js game for Dewdrop: the Vite plugin, model calls, multiplayer, saves and voice.",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/backend-host.js

@@ -11,7 +11,7 @@ import { pathToFileURL } from 'node:url';
 import { attachClients } from './clients.js';
 
 process.env.DEW_DEV_ORIGIN = workerData.origin;
-const start = attachClients(parentPort);
+const start = attachClients(parentPort, { capacity: workerData.capacity });
 await import(pathToFileURL(workerData.entry).href);
 process.on('uncaughtException', (error) => console.error(`uncaught ${error?.stack ?? error}`));
 start();

package/src/backend.js

@@ -7,7 +7,7 @@
 // past its cap. The page's URL says which room the tab joins and under
 // what name; on Dewdrop the game's page says which room, and the name is
 // the player's username.
-import { MAX_NET_CLIENT_FRAME_BYTES, createInbox, createOutbox, defineHandlers, label, side, unpack } from './net.js';
+import { MAX_NET_CLIENTS, MAX_NET_CLIENT_FRAME_BYTES, createInbox, createOutbox, defineHandlers, label, side, unpack } from './net.js';
 import { NO_CHANNEL } from './route.js';
 
 let channel = null;
@@ -58,20 +58,35 @@ function name(text) {
   return label(text.replace(/\p{Cc}/gu, '').trim());
 }
 
-// Where a page's URL joins its tab: the room `?room=` names and the name
-// `?player=` names, each held to Dewdrop's rule — the empty room without
+// The players a room seats as `?players=` names them: a whole number from
+// 1 to MAX_NET_CLIENTS, or the most without one or with any other.
+function players(text) {
+  return /^[0-9]{1,3}$/.test(text) && Number(text) >= 1 && Number(text) <= MAX_NET_CLIENTS ? Number(text) : MAX_NET_CLIENTS;
+}
+
+// Where a page's URL joins its tab: the room `?room=` names, the name
+// `?player=` names, and the players `?players=` says the room seats should
+// the tab make it, each held to Dewdrop's rule — the empty room without
 // one, or with one that names no room; unnamed without a name, or with one
 // that is nothing but space and control characters.
 export function joining(search) {
   const params = new URLSearchParams(search);
-  return { room: room(params.get('room') ?? ''), player: name(params.get('player') ?? '') };
+  return { room: room(params.get('room') ?? ''), player: name(params.get('player') ?? ''), players: players(params.get('players') ?? '') };
+}
+
+// Whether the page's game has a backend, as the plugin said; false until
+// it has.
+export function gameHasBackend() {
+  return hasBackend;
 }
 
 // Joins the backend of `room` under `player`'s name over `hot`, the page's
-// hot context, once the plugin has said whether the game has one:
-// `present` is that, `schedule` runs a function at the next animation
-// frame. Without a plugin there is no channel, and `send` says so.
-export function attachBackend(hot, { channel: routed, hasBackend: present, frame: schedule, room = '', player = '' }) {
+// hot context, once the plugin has said whether the game has one, a room
+// it makes seating `players`: `present` is that, `schedule` runs a
+// function at the next animation frame. Without a plugin there is no
+// channel, and `send` says so. A room that seats no more says so in the
+// console, as Dewdrop refuses the connect, and the tab's sends reach no one.
+export function attachBackend(hot, { channel: routed, hasBackend: present, frame: schedule, room = '', player = '', players = MAX_NET_CLIENTS }) {
   if (!routed) return;
   channel = hot;
   hasBackend = present;
@@ -83,5 +98,6 @@ export function attachBackend(hot, { channel: routed, hasBackend: present, frame
     draining = true;
     frame(deliver);
   });
-  hot.send('dew:join', { room, player });
+  hot.on('dew:full', ({ capacity }) => console.error(`[dewdrop] this room is full: it seats ${capacity === 1 ? '1 player' : `${capacity} players`}`));
+  hot.send('dew:join', { room, player, players });
 }

package/src/clients.js

@@ -1,15 +1,16 @@
 // `clients` on a developer's machine: the backend's side of the messages a
-// game exchanges with its clients, run by the plugin in a thread of the
-// dev server with a port to the plugin, which carries each message over
-// the socket to the tab it names. The thread ticks sixty times a second:
+// game exchanges with its clients, and the most players its room seats,
+// run by the plugin in a thread of the dev server with a port to the
+// plugin, which carries each message over the socket to the tab it names. The thread ticks sixty times a second:
 // each tick delivers what the clients sent as `join`, `leave`, `message`,
 // and `gap` events — a join naming the player's label — runs the
 // animation-frame callbacks, and sends the frame's messages.
-import { MAX_NET_BACKEND_FRAME_BYTES, NET_TICK_MS, ClientEvent, createInbox, createOutbox, defineHandlers, side, unpack } from './net.js';
+import { MAX_NET_BACKEND_FRAME_BYTES, MAX_NET_CLIENTS, NET_TICK_MS, ClientEvent, createInbox, createOutbox, defineHandlers, side, unpack } from './net.js';
 
 const outbox = createOutbox(MAX_NET_BACKEND_FRAME_BYTES);
 const inbox = createInbox();
 let port = null;
+let seats = 0;
 
 // A client number as the backend was told it: a whole number from one.
 function number(op, value) {
@@ -28,6 +29,12 @@ class Clients extends EventTarget {
     if (port === null) throw new DOMException('clients is unavailable in a client', 'NotSupportedError');
     outbox.push('clients.broadcast', 0, data);
   }
+  // The most players the room seats, as it was made: 1 for a room of one,
+  // a player counted once however many clients they play from.
+  get capacity() {
+    if (port === null) throw new DOMException('clients is unavailable in a client', 'NotSupportedError');
+    return seats;
+  }
 }
 defineHandlers(Clients.prototype, ['join', 'leave', 'message', 'gap']);
 
@@ -76,9 +83,11 @@ function frame() {
 // held until the returned function starts the ticks, which the host calls
 // once the backend has evaluated, so the first tick delivers what arrived
 // meanwhile, the first join included, to the handlers the module
-// registered. `tick` runs the frame once per tick from then on.
-export function attachClients(channel, { tick = (fn) => setInterval(fn, NET_TICK_MS) } = {}) {
+// registered. `tick` runs the frame once per tick from then on, and
+// `capacity` is the most players the room seats.
+export function attachClients(channel, { tick = (fn) => setInterval(fn, NET_TICK_MS), capacity = MAX_NET_CLIENTS } = {}) {
   port = channel;
+  seats = capacity;
   side.backend = true;
   if (typeof globalThis.requestAnimationFrame !== 'function') {
     globalThis.requestAnimationFrame = requestAnimationFrame;

package/src/index.js

@@ -4,10 +4,14 @@
 // over its route, `backend` over its socket to the backend the plugin
 // runs, `clients`, in that backend, over its port back, and `saves` into
 // the browser's own storage, which the plugin's script empties as each
-// page loads.
+// page loads; `session` says when a session ends ahead of time, which here
+// none does; and `voice` reads the microphone through the browser's own
+// audio worklet, the chunks Dewdrop's server would decode.
 export { llm } from './llm.js';
 export { backend } from './backend.js';
 export { clients } from './clients.js';
+export { session } from './session.js';
+export { voice } from './voice.js';
 import { attachBackend, joining } from './backend.js';
 import { load, save } from './saves.js';
 
@@ -30,5 +34,6 @@ if (typeof document !== 'undefined' && import.meta.hot) {
     frame: (fn) => requestAnimationFrame(fn),
     room: joined.room,
     player: joined.player,
+    players: joined.players,
   });
 }

package/src/net.js

@@ -15,6 +15,9 @@ export const NET_RECORD_HEADER_BYTES = 16;
 // The most bytes a player's label takes: the name the player joined
 // under, which the backend hears on the join.
 export const MAX_NET_PLAYER_BYTES = 64;
+// The most players a room seats, and the most clients it holds: a room's
+// size is 1 to this.
+export const MAX_NET_CLIENTS = 100;
 // How often the local backend ticks: sixty times a second.
 export const NET_TICK_MS = 1000 / 60;
 

package/src/saves.js

@@ -6,7 +6,7 @@
 // names and the player the page's URL names, and `load` puts it back.
 // Calls run in the order they are made, and the checks and their messages
 // are Dewdrop's, so a call that fails here fails there the same way.
-import { joining } from './backend.js';
+import { gameHasBackend, joining } from './backend.js';
 import { SAVES_STATE } from './fresh.js';
 import { side } from './net.js';
 import { NO_SAVES } from './route.js';
@@ -24,10 +24,11 @@ let last = Promise.resolve();
 let loads = 0;
 
 // Runs `run` once every call made before has settled and the page's
-// storage has started empty; refused at once in a backend, and in a page
-// without the plugin's script.
+// storage has started empty; refused at once in a game with a backend —
+// its backend and its tabs alike, as on Dewdrop, where such a game keeps
+// no saves — and in a page without the plugin's script.
 function inOrder(op, run) {
-  if (side.backend) return Promise.reject(new DOMException('saves is unavailable in a backend', 'NotSupportedError'));
+  if (side.backend || gameHasBackend()) return Promise.reject(new DOMException('saves is unavailable in a game with a backend', 'NotSupportedError'));
   const state = globalThis[Symbol.for(SAVES_STATE)];
   if (state === undefined) return Promise.reject(new TypeError(`${op}: ${NO_SAVES}`));
   const call = last.then(() => state.ready).then(() => run(state));

package/src/serve.js

@@ -1,7 +1,10 @@
 // The dev server's backend host, its stand-in for Dewdrop. A thread runs
 // the project's backend.js for each room the tabs join, from the room's
 // first tab's join until five minutes after its last tab's leave, as on
-// Dewdrop, so a tab that comes back in that time rejoins it; the tabs are
+// Dewdrop, so a tab that comes back in that time rejoins it; a room seats
+// the players its first tab's page said, a player counted once however
+// many tabs they play from and an unnamed tab as one each, and refuses a
+// tab past them as Dewdrop refuses its connect; the tabs are
 // numbered from one per room, never twice while its thread runs; each
 // tab's frame of sends reaches its room's thread over the port
 // with the tab's number, and each of the thread's sends reaches the tab it
@@ -14,7 +17,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { Worker } from 'node:worker_threads';
-import { label } from './net.js';
+import { MAX_NET_CLIENTS, label } from './net.js';
 
 // How long a room's backend runs on after its last tab's leave, as on
 // Dewdrop.
@@ -47,12 +50,14 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
   const rooms = new Map();
   const tabs = new Map();
 
-  // One room's backend: its thread from the room's first tab's join until
-  // EMPTY_ROOM_MS after its last tab's leave with none joining since, its
-  // tabs by number from one.
-  function createRoom(key) {
+  // One room's backend, seating `capacity` players: its thread from the
+  // room's first tab's join until EMPTY_ROOM_MS after its last tab's leave
+  // with none joining since, its tabs by number from one with their
+  // players' names.
+  function createRoom(key, capacity) {
     const name = key === '' ? 'the backend' : `the backend of room ${JSON.stringify(key)}`;
     const members = new Map();
+    const names = new Map();
     let worker = null;
     let next = 1;
     let broken = false;
@@ -68,7 +73,7 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
 
     function start() {
       files = backendFiles(entry);
-      worker = new Worker(new URL('./backend-host.js', import.meta.url), { workerData: { entry, origin: origin() } });
+      worker = new Worker(new URL('./backend-host.js', import.meta.url), { workerData: { entry, origin: origin(), capacity } });
       const started = worker;
       started.on('message', (message) => {
         if (message.kind === 'send' && worker === started) deliver(message.sends);
@@ -89,6 +94,7 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
       idle = null;
       for (const client of members.keys()) tabs.delete(client);
       members.clear();
+      names.clear();
       next = 1;
       if (ended !== null) ended.terminate();
     }
@@ -101,13 +107,26 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
       broken = true;
     }
 
+    // The room's players, each once: its tabs' names, and each unnamed tab.
+    function seated() {
+      const players = [...names.values()];
+      return players.filter((player, at) => player === '' || players.indexOf(player) === at).length;
+    }
+
     const room = {
       join(client, player) {
         if (broken) return;
+        const returning = player !== '' && [...names.values()].includes(player);
+        if (members.size >= MAX_NET_CLIENTS || (!returning && seated() >= capacity)) {
+          log.error(`[dewdrop] a tab is refused ${name}: it seats ${capacity === 1 ? '1 player' : `${capacity} players`}`);
+          client.send('dew:full', { capacity });
+          return;
+        }
         clearTimeout(idle);
         idle = null;
         const number = next++;
         members.set(client, number);
+        names.set(client, player);
         tabs.set(client, room);
         if (worker === null) start();
         worker.postMessage([{ kind: 'join', client: number, player }]);
@@ -117,6 +136,7 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
         const number = members.get(client);
         if (number === undefined) return;
         members.delete(client);
+        names.delete(client);
         tabs.delete(client);
         worker.postMessage([{ kind: 'leave', client: number }]);
         if (members.size === 0) {
@@ -151,14 +171,17 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
   }
 
   const host = {
-    // A tab joins the room its page named under the name it gave; a page
-    // that named neither joins the empty room unnamed.
-    join(client, { room = '', player = '' } = {}) {
+    // A tab joins the room its page named under the name it gave, a room
+    // it makes seating the players its page said; a page that named
+    // neither joins the empty room unnamed, and one that named no size a
+    // room seating the most.
+    join(client, { room = '', player = '', players = MAX_NET_CLIENTS } = {}) {
       if (tabs.has(client)) return;
       const key = typeof room === 'string' ? room : '';
       let it = rooms.get(key);
       if (it === undefined) {
-        it = createRoom(key);
+        const capacity = Number.isInteger(players) && players >= 1 && players <= MAX_NET_CLIENTS ? players : MAX_NET_CLIENTS;
+        it = createRoom(key, capacity);
         rooms.set(key, it);
       }
       it.join(client, label(player));
@@ -171,7 +194,7 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
     },
     close,
   };
-  ws.on('dew:join', (data, client) => host.join(client, { room: data?.room, player: data?.player }));
+  ws.on('dew:join', (data, client) => host.join(client, { room: data?.room, player: data?.player, players: data?.players }));
   ws.on('dew:send', (data, client) => host.receive(client, data.items ?? []));
   watcher.on('change', (file) => {
     if (files.has(resolve(file))) restart(`${file} changed`);

package/src/session.js

@@ -0,0 +1,17 @@
+// `session` on a developer's machine. On Dewdrop a session can end ahead of
+// time — for maintenance, or a newer version of its game published — and
+// hears of it first, up to fifteen minutes before: `session.ending` is
+// `{at, reason}`, `at` in milliseconds since the epoch as `Date.now()` counts
+// and `reason` `'restart'` or `'update'`, and an `ending` event fires each
+// time it changes, its withdrawal to null included, so a game can save and
+// say so. `npm run dev` ends no session ahead of time, so here `ending`
+// stays null and the event never fires; a game tries its handler by calling
+// it.
+import { defineHandlers } from './net.js';
+
+class Session extends EventTarget {
+  get ending() { return null; }
+}
+defineHandlers(Session.prototype, ['ending']);
+
+export const session = new Session();

package/src/voice.js

@@ -0,0 +1,192 @@
+// `voice` on a developer's machine: the runtime's surface — the player's
+// microphone a chunk at a time, and a source that plays such chunks
+// through the game's own audio graph — where Dewdrop carries no voice
+// between players itself: a game sends what it captures to its backend
+// through its messages, and the backend sends it on to the players it
+// chooses. On Dewdrop the server decodes the microphone the browser
+// streams onto the game's voice stream; here the browser's own audio
+// worklet reads the microphone and hands the game the same chunks, so a
+// game captures in `npm run dev` as it captures on Dewdrop. `source` is
+// plain Web Audio, the same function as Dewdrop's, and plays here as
+// there.
+
+// Hand-copied from the runtime, which tests/sync.test.mjs pins: the rate
+// of the samples a capture reads and a source plays, the samples in one
+// of a capture's chunks, 1/60 s, and the chunks that wait for a game that
+// reads late, the newest kept.
+export const SAMPLE_RATE = 48000;
+export const VOICE_CHUNK_SAMPLES = 800;
+export const VOICE_CHUNKS_HELD = 8;
+// How far ahead of the context's clock a source begins what is written
+// to it — the first chunk, and the first after it ran dry — in seconds:
+// two chunks, which a later chunk may come late by and still follow the
+// last without a gap; and how far ahead writes may run before the newest
+// is dropped instead, so a voice falls no further behind.
+const SOURCE_LEAD = 2 * VOICE_CHUNK_SAMPLES / SAMPLE_RATE;
+const MAX_SOURCE_LEAD = 8 * VOICE_CHUNK_SAMPLES / SAMPLE_RATE;
+
+// The processor that reads the microphone in the browser's audio thread:
+// it takes the microphone's frames at the context's rate, steps through
+// them at SAMPLE_RATE, and posts each VOICE_CHUNK_SAMPLES of them as 16-bit
+// samples, the buffer handed over rather than copied. Its output is
+// silence, so it can hang off the destination, which is what has it run.
+export const CAPTURE_PROCESSOR = 'dew-voice-capture';
+export const CAPTURE_WORKLET = `
+class DewVoiceCapture extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.chunk = new Int16Array(${VOICE_CHUNK_SAMPLES});
+    this.at = 0;
+    // The microphone's frames per sample, and where in the block the next
+    // sample falls.
+    this.step = sampleRate / ${SAMPLE_RATE};
+    this.phase = 0;
+  }
+  process(inputs) {
+    const frames = inputs[0][0];
+    if (frames === undefined) return true;
+    while (this.phase < frames.length) {
+      const i = Math.floor(this.phase);
+      const next = i + 1 < frames.length ? frames[i + 1] : frames[i];
+      const sample = frames[i] + (next - frames[i]) * (this.phase - i);
+      const clamped = sample < -1 ? -1 : sample > 1 ? 1 : sample;
+      this.chunk[this.at++] = Math.round(clamped * 32767);
+      if (this.at === this.chunk.length) {
+        this.port.postMessage(this.chunk, [this.chunk.buffer]);
+        this.chunk = new Int16Array(${VOICE_CHUNK_SAMPLES});
+        this.at = 0;
+      }
+      this.phase += this.step;
+    }
+    this.phase -= frames.length;
+    return true;
+  }
+}
+registerProcessor('${CAPTURE_PROCESSOR}', DewVoiceCapture);
+`;
+
+// The capture under way, if any.
+let capturing = null;
+
+// A stream with a live audio track, as `getUserMedia` resolves one.
+function liveMicrophone(stream) {
+  return stream !== null && typeof stream === 'object' && typeof stream.getAudioTracks === 'function'
+    && stream.getAudioTracks().some((track) => track.readyState === 'live');
+}
+
+// The player's microphone, a chunk at a time: given the stream
+// `getUserMedia` resolved, while its track is live, hands back the
+// capture, whose `read()` returns the chunks that arrived since the last
+// read — each an Int16Array of VOICE_CHUNK_SAMPLES samples, mono, at
+// SAMPLE_RATE, in order, the newest VOICE_CHUNKS_HELD kept when the game
+// reads late — and whose `stop()` ends it, closing the context at once.
+// One at a time. The browser's own graph reads the stream: a context at
+// the sample rate where the browser allows one, the worklet between the
+// stream and the destination.
+function capture(stream) {
+  if (!liveMicrophone(stream)) {
+    throw new TypeError('voice.capture: stream is not a live microphone stream from navigator.mediaDevices.getUserMedia');
+  }
+  if (capturing !== null) throw new DOMException('voice.capture: the microphone is captured already; stop that first', 'InvalidStateError');
+  if (typeof AudioContext === 'undefined' || typeof AudioWorkletNode === 'undefined') {
+    throw new DOMException('voice.capture is unavailable here: the browser has no AudioWorklet', 'NotSupportedError');
+  }
+  let context;
+  try {
+    context = new AudioContext({ sampleRate: SAMPLE_RATE });
+  } catch {
+    context = new AudioContext();
+  }
+  let chunks = [];
+  let live = true;
+  const worklet = URL.createObjectURL(new Blob([CAPTURE_WORKLET], { type: 'text/javascript' }));
+  const ready = context.audioWorklet.addModule(worklet).then(() => {
+    URL.revokeObjectURL(worklet);
+    if (!live) return undefined;
+    const node = new AudioWorkletNode(context, CAPTURE_PROCESSOR, {
+      numberOfInputs: 1, numberOfOutputs: 1, outputChannelCount: [1], channelCount: 1, channelCountMode: 'explicit',
+    });
+    node.port.onmessage = ({ data }) => {
+      if (!live) return;
+      chunks.push(data);
+      if (chunks.length > VOICE_CHUNKS_HELD) chunks.splice(0, chunks.length - VOICE_CHUNKS_HELD);
+    };
+    context.createMediaStreamSource(stream).connect(node).connect(context.destination);
+    // A context the browser keeps suspended until the player's next
+    // gesture starts then; nothing here waits on it.
+    context.resume().catch(() => {});
+  });
+  // A worklet the browser refuses leaves the capture silent; the reason
+  // goes to the console, where the developer is.
+  ready.catch((error) => console.error('voice.capture: the microphone could not be read: ' + error.message));
+  const mine = Object.freeze({
+    read() {
+      if (capturing !== mine || chunks.length === 0) return [];
+      const read = chunks;
+      chunks = [];
+      return read;
+    },
+    stop() {
+      if (capturing !== mine) return;
+      capturing = null;
+      live = false;
+      chunks = [];
+      // Closed at once, whether or not the worklet has loaded or the
+      // context ever ran: a setup still to come finds `live` false and
+      // makes nothing.
+      context.close().catch(() => {});
+    },
+  });
+  capturing = mine;
+  return mine;
+}
+
+function isObjectLike(value) { return value !== null && (typeof value === 'object' || typeof value === 'function'); }
+
+// A source for `context`'s graph that plays the chunks written to it as
+// they come — Int16Array or Float32Array samples at SAMPLE_RATE, mono,
+// as `capture` reads them or as another player's reached this game —
+// each right after the last: `node` is the source, for `connect`
+// or a three.js PositionalAudio's `setNodeSource`; `write` plays a chunk
+// after those before it; `close` leaves the graph. Plain Web Audio — a
+// buffer source a write, begun SOURCE_LEAD ahead of the context's clock
+// and following the last, and nothing of Dewdrop's — so a game may play a
+// voice its own way instead. The runtime's web/voice.js carries this same
+// function, which tests/sync.test.mjs pins line for line.
+function source(context) {
+  if (!isObjectLike(context) || typeof context.createBufferSource !== 'function') {
+    throw new TypeError('voice.source: context is not an AudioContext');
+  }
+  const node = context.createGain();
+  // When the next chunk written plays, on the context's clock.
+  let at = 0;
+  return Object.freeze({
+    node,
+    write(samples) {
+      const tag = Object.prototype.toString.call(samples);
+      if (tag !== '[object Int16Array]' && tag !== '[object Float32Array]') {
+        throw new TypeError('voice.source: write takes an Int16Array or a Float32Array of samples');
+      }
+      if (samples.length === 0) return;
+      const now = context.currentTime;
+      // The first write, or one after the chunks before it played out:
+      // SOURCE_LEAD ahead of the clock. While they still play, right
+      // after them, however early or late this one came, which is what
+      // rides out the jitter; too far ahead of the clock: dropped.
+      if (at <= now) at = now + SOURCE_LEAD;
+      else if (at > now + MAX_SOURCE_LEAD) return;
+      const buffer = context.createBuffer(1, samples.length, SAMPLE_RATE);
+      const channel = buffer.getChannelData(0);
+      if (tag === '[object Float32Array]') channel.set(samples);
+      else for (let i = 0; i < samples.length; i++) channel[i] = samples[i] / 32768;
+      const player = context.createBufferSource();
+      player.buffer = buffer;
+      player.connect(node);
+      player.start(at);
+      at += buffer.duration;
+    },
+    close() { node.disconnect(); },
+  });
+}
+
+export const voice = Object.freeze({ capture, source, SAMPLE_RATE });