game-koi 0.1.2 → 0.3.0

package/dist/index.js

@@ -9,6 +9,10 @@
  */
 import init, { Emulator } from "../wasm/game_koi_web.js";
 import { WORKLET_SOURCE } from "./worklet.js";
+import { DEFAULT_GAMEPAD_MAP, GamepadInput } from "./gamepad.js";
+import { Emitter } from "./events.js";
+import { FrameStats } from "./stats.js";
+import { StatsOverlay } from "./overlay.js";
 const DEFAULT_KEYMAP = {
     ArrowRight: "right",
     ArrowLeft: "left",
@@ -35,29 +39,46 @@ export class GameKoi {
     wasmMemory;
     imageData;
     keymap;
+    gamepad;
     targetBuffer;
     maxFramesPerWake;
+    stats;
+    emitter = new Emitter();
+    /** What the joypad currently has down, whichever device put it there. */
+    held = new Set();
     emulator;
     buffered = 0;
+    /** Cumulative worklet counters, as last reported. See `worklet.ts`. */
+    underruns = 0;
+    dropped = 0;
+    /** Built on first toggle, so a page that never opens it gets no element. */
+    overlay = null;
     running = false;
     rafHandle = 0;
     keydownListener;
     keyupListener;
-    constructor(emulator, wasmMemory, ctx, audioContext, worklet, keymap, targetBuffer, maxFramesPerWake) {
+    overlayListener;
+    constructor(emulator, wasmMemory, ctx, audioContext, worklet, keymap, gamepadMap, overlayKey, targetBuffer, maxFramesPerWake) {
         this.emulator = emulator;
         this.wasmMemory = wasmMemory;
         this.ctx = ctx;
         this.audioContext = audioContext;
         this.worklet = worklet;
         this.keymap = keymap;
+        this.gamepad = gamepadMap ? new GamepadInput(gamepadMap) : null;
         this.targetBuffer = targetBuffer;
         this.maxFramesPerWake = maxFramesPerWake;
         this.imageData = ctx.createImageData(Emulator.width(), Emulator.height());
+        this.stats = new FrameStats(performance.now());
         this.worklet.port.onmessage = (event) => {
             this.buffered = event.data.buffered;
+            this.underruns = event.data.underruns;
+            this.dropped = event.data.dropped;
         };
         if (keymap)
             this.attachKeyboard();
+        if (overlayKey !== null)
+            this.attachOverlayKey(overlayKey);
     }
     /**
      * Builds and starts a running emulator.
@@ -87,25 +108,105 @@ export class GameKoi {
         worklet.connect(audioContext.destination);
         const emulator = new Emulator(options.rom, audioContext.sampleRate);
         const keymap = options.keymap === null ? null : options.keymap ?? DEFAULT_KEYMAP;
-        const koi = new GameKoi(emulator, wasm.memory, ctx, audioContext, worklet, keymap, options.targetBuffer ?? 1600, options.maxFramesPerWake ?? 4);
+        const gamepadMap = options.gamepadMap === null ? null : options.gamepadMap ?? DEFAULT_GAMEPAD_MAP;
+        const koi = new GameKoi(emulator, wasm.memory, ctx, audioContext, worklet, keymap, gamepadMap, options.overlayKey === null ? null : options.overlayKey ?? "Backquote", options.targetBuffer ?? 1600, options.maxFramesPerWake ?? 4);
         koi.running = true;
         koi.loop();
         return koi;
     }
     /** Swaps in a new ROM, keeping the same canvas and audio graph. */
     loadRom(rom) {
+        // The new machine's joypad starts with nothing held, so what this side believes is
+        // held has to start over too — both the gamepad's snapshot (or the first poll would
+        // emit no press for a direction that was already down) and the set the events are
+        // edges against (or a button "already held" would never be pressed on the new
+        // machine, and a display would show it stuck down).
+        this.gamepad?.releaseAll();
+        this.releaseAll();
         this.emulator.free();
         this.emulator = new Emulator(rom, this.audioContext.sampleRate);
     }
     press(button) {
-        this.emulator.press(button);
+        this.setButton(button, true, "api");
     }
     release(button) {
-        this.emulator.release(button);
+        this.setButton(button, false, "api");
+    }
+    /** Everything the joypad has down right now — a snapshot, safe to keep. */
+    get pressed() {
+        return new Set(this.held);
+    }
+    /**
+     * Listens for button edges, from any input path — the built-in keyboard and gamepad
+     * handling as well as `press`/`release` calls.
+     *
+     * Returns a function that removes the listener again:
+     *
+     * ```ts
+     * const stop = koi.on("press", ({ button, pressed }) => render(pressed));
+     * koi.on("release", ({ button, pressed }) => render(pressed));
+     * ```
+     *
+     * Only *changes* are reported: a key held down with autorepeat, a stick resting past
+     * the threshold, or `press("a")` twice in a row each produce one `press` event and no
+     * `release` until the button actually comes up.
+     */
+    on(type, listener) {
+        return this.emitter.on(type, listener);
+    }
+    /** Removes a listener registered with {@link on}. */
+    off(type, listener) {
+        this.emitter.off(type, listener);
+    }
+    /**
+     * The one path to the emulated joypad, so every device's edges are counted once.
+     *
+     * A repeat is dropped here rather than forwarded: `Joypad::press` is idempotent, so
+     * skipping it changes nothing for the machine, and it is what makes the events edges
+     * instead of a restatement of whatever the browser felt like repeating.
+     */
+    setButton(button, pressed, source) {
+        if (this.held.has(button) === pressed)
+            return;
+        if (pressed) {
+            this.held.add(button);
+            this.emulator.press(button);
+        }
+        else {
+            this.held.delete(button);
+            this.emulator.release(button);
+        }
+        this.emitter.emit(pressed ? "press" : "release", {
+            button,
+            source,
+            pressed: new Set(this.held),
+        });
+    }
+    /** Lets go of everything held, emitting the releases. */
+    releaseAll() {
+        for (const button of [...this.held])
+            this.setButton(button, false, "api");
+    }
+    /**
+     * Shows or hides the debug stats panel — the same thing the ` key does.
+     *
+     * The panel is built the first time this is called, so a page that never opens it
+     * never gets an extra element in its DOM.
+     */
+    toggleOverlay() {
+        this.overlay ??= new StatsOverlay(this.ctx.canvas);
+        this.overlay.toggle();
+    }
+    /** Whether the stats panel is currently showing. */
+    get overlayVisible() {
+        return this.overlay?.visible ?? false;
     }
     pause() {
         this.running = false;
         cancelAnimationFrame(this.rafHandle);
+        // A direction held at the moment of the pause has no poll coming to release it,
+        // so it would still be down when the machine resumes.
+        this.applyGamepadActions(this.gamepad?.releaseAll());
         void this.audioContext.suspend();
     }
     resume() {
@@ -120,6 +221,10 @@ export class GameKoi {
         this.running = false;
         cancelAnimationFrame(this.rafHandle);
         this.detachKeyboard();
+        if (this.overlayListener)
+            removeEventListener("keydown", this.overlayListener);
+        this.emitter.clear();
+        this.overlay?.dispose();
         this.emulator.free();
         this.worklet.disconnect();
         void this.audioContext.close();
@@ -127,6 +232,11 @@ export class GameKoi {
     loop = () => {
         if (!this.running)
             return;
+        const wokeAt = performance.now();
+        this.pollGamepads();
+        // Measured from after the input poll: reading a gamepad snapshot is neither
+        // emulation nor drawing, and it costs a fraction of a microsecond.
+        const emulateStart = performance.now();
         // Emulate however many frames the audio buffer is short by, capped. Audio wins
         // when the display's refresh rate and the Game Boy's 59.73Hz disagree, since a
         // dry buffer is audible and a repeated frame is not.
@@ -148,10 +258,39 @@ export class GameKoi {
             }
             frames++;
         }
+        const drawStart = performance.now();
         if (frames > 0)
             this.drawFrame();
+        const drawEnd = performance.now();
+        this.recordWake(wokeAt, emulateStart, drawStart, drawEnd, frames);
         this.rafHandle = requestAnimationFrame(this.loop);
     };
+    /**
+     * Feeds the counters and refreshes the panel.
+     *
+     * Always run, not just while the panel is open: the averages are computed over half a
+     * second, so a panel that only started counting when it opened would show nothing for
+     * its first window. The cost is four `performance.now()` reads per wake.
+     */
+    recordWake(wokeAt, emulateStart, drawStart, drawEnd, frames) {
+        this.stats.wake({
+            emulate: drawStart - emulateStart,
+            draw: frames > 0 ? drawEnd - drawStart : 0,
+            frames,
+            // The catch-up was clamped and the buffer is still short, so a deficit is
+            // being carried into the next wake.
+            capped: frames >= this.maxFramesPerWake && this.buffered < this.targetBuffer,
+        }, wokeAt);
+        this.stats.setAudio({
+            buffered: this.buffered,
+            target: this.targetBuffer,
+            underruns: this.underruns,
+            dropped: this.dropped,
+            sampleRate: this.audioContext.sampleRate,
+            state: this.audioContext.state,
+        });
+        this.overlay?.update(this.stats.snapshot(), wokeAt);
+    }
     drawFrame() {
         // Read `wasmMemory.buffer` fresh rather than caching it: any wasm allocation can
         // grow linear memory, which allocates a new ArrayBuffer and silently detaches
@@ -161,18 +300,41 @@ export class GameKoi {
         this.imageData.data.set(bytes);
         this.ctx.putImageData(this.imageData, 0, 0);
     }
+    /**
+     * Reads every connected pad and applies whatever changed since the last wake.
+     *
+     * Done here rather than from a listener because the Gamepad API fires no event for a
+     * button: `getGamepads()` is a snapshot and polling it is the only way to see one.
+     */
+    pollGamepads() {
+        if (!this.gamepad)
+            return;
+        // Guarded because the API is absent outside a secure context, and in a few
+        // embedded webviews that still have no gamepad support at all.
+        const pads = navigator.getGamepads?.();
+        if (!pads)
+            return;
+        this.applyGamepadActions(this.gamepad.poll(pads));
+    }
+    applyGamepadActions(actions) {
+        for (const action of actions ?? []) {
+            this.setButton(action.button, action.type === "press", "gamepad");
+        }
+    }
     attachKeyboard() {
         this.keydownListener = (event) => {
             const button = this.keymap?.[event.code];
             if (button) {
-                this.press(button);
+                // Autorepeat still arrives here: `preventDefault` has to run on every repeat,
+                // and `setButton` is what collapses them into the one press edge.
+                this.setButton(button, true, "keyboard");
                 event.preventDefault();
             }
         };
         this.keyupListener = (event) => {
             const button = this.keymap?.[event.code];
             if (button) {
-                this.release(button);
+                this.setButton(button, false, "keyboard");
                 event.preventDefault();
             }
         };
@@ -185,4 +347,20 @@ export class GameKoi {
         if (this.keyupListener)
             removeEventListener("keyup", this.keyupListener);
     }
+    /**
+     * Binds the panel's toggle key.
+     *
+     * Its own listener rather than a case inside the keymap one, because the two are
+     * independent: a page that drives the joypad itself (`keymap: null`) can still want
+     * the panel, and the panel key is not a Game Boy button.
+     */
+    attachOverlayKey(code) {
+        this.overlayListener = (event) => {
+            if (event.code !== code || event.repeat)
+                return;
+            this.toggleOverlay();
+            event.preventDefault();
+        };
+        addEventListener("keydown", this.overlayListener);
+    }
 }

package/dist/overlay.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The debug stats panel.
+ *
+ * This is the browser counterpart of `game-koi-desktop`'s `overlay.rs`, and the split is
+ * the same on both sides: `stats.ts` counts, this draws. What differs is the medium.
+ * The desktop panel is egui, rendered into the same wgpu pass as the game; egui here
+ * would mean bringing wgpu or WebGL into a package whose whole rendering path is one
+ * `putImageData` call, and roughly 2 MB of wasm paid by every consumer whether or not
+ * they ever press the key. So this is a plain DOM panel with the same content.
+ *
+ * Three consequences of that choice, all deliberate:
+ *
+ * - **It is a sibling of the canvas, not a wrapper around it.** The element is appended
+ *   to `document.body` and positioned over the canvas from its bounding rect. Wrapping
+ *   the consumer's canvas in a new element would be the tidier CSS, but it would move
+ *   their node in the document and break any selector or layout rule that depended on
+ *   where it was.
+ * - **`pointer-events: none`.** The panel is read-only, so it must never swallow a click
+ *   meant for the page underneath. The desktop panel does have widgets, but the two it
+ *   has — vsync and the CRT mode — are host-render settings that do not exist here.
+ * - **Styles are inline.** Nothing to serve, nothing for a bundler to find, and no
+ *   chance of a page's stylesheet reaching in; the same reasoning that keeps the audio
+ *   worklet a Blob rather than a file.
+ */
+import type { StatsSnapshot } from "./stats.js";
+/** A read-only panel of counters, floating over the emulator's canvas. */
+export declare class StatsOverlay {
+    private readonly canvas;
+    private readonly element;
+    private readonly grid;
+    private readonly values;
+    private shown;
+    private lastRefresh;
+    constructor(canvas: HTMLCanvasElement);
+    get visible(): boolean;
+    toggle(): void;
+    /**
+     * Rewrites the panel, at most every {@link REFRESH_MS}.
+     *
+     * Cheap to call every frame — while hidden it does nothing at all, which is what keeps
+     * a switched-off feature costing a branch rather than a layout.
+     */
+    update(snapshot: StatsSnapshot, now: number): void;
+    dispose(): void;
+    /**
+     * Anchors the panel to the canvas's current position.
+     *
+     * Re-read rather than cached because a page can scroll, resize or reflow under us with
+     * no event this module sees. `getBoundingClientRect` forces layout, which is why it
+     * happens on the refresh tick and only while the panel is open.
+     */
+    private position;
+    private addRow;
+    /**
+     * A rule across both columns.
+     *
+     * `grid-column: 1 / -1` rather than one cell per column: two cells would be broken in
+     * the middle by the column gap, which reads as two dashes rather than the single line
+     * egui draws.
+     */
+    private addSeparator;
+    private set;
+}
+/**
+ * A duration in milliseconds at a fixed width, so the column does not jitter.
+ *
+ * The desktop formats these as `{:>6.2} ms` for exactly the same reason.
+ */
+export declare function formatMs(ms: number): string;
+export declare function formatPercent(percent: number): string;
+/** A plain count, right-aligned to the same width as the percentages above it. */
+export declare function count(value: number): string;
+/**
+ * Green through to red as a figure approaches and passes its budget.
+ *
+ * Only worth colouring near the limit: a number that matters at 100% is easy to miss if
+ * it spends most of its time at 12%.
+ */
+export declare function loadColour(fraction: number): string;
+/**
+ * How alarming the audio buffer's depth is.
+ *
+ * Zero is not a warning but a failure that was audible: the worklet emitted silence.
+ * Below half the target is the warning, because that is the buffer draining rather than
+ * sitting where the pacing loop means to hold it.
+ */
+export declare function bufferColour(bufferedMs: number, targetMs: number): string;

package/dist/overlay.js

@@ -0,0 +1,245 @@
+/**
+ * The debug stats panel.
+ *
+ * This is the browser counterpart of `game-koi-desktop`'s `overlay.rs`, and the split is
+ * the same on both sides: `stats.ts` counts, this draws. What differs is the medium.
+ * The desktop panel is egui, rendered into the same wgpu pass as the game; egui here
+ * would mean bringing wgpu or WebGL into a package whose whole rendering path is one
+ * `putImageData` call, and roughly 2 MB of wasm paid by every consumer whether or not
+ * they ever press the key. So this is a plain DOM panel with the same content.
+ *
+ * Three consequences of that choice, all deliberate:
+ *
+ * - **It is a sibling of the canvas, not a wrapper around it.** The element is appended
+ *   to `document.body` and positioned over the canvas from its bounding rect. Wrapping
+ *   the consumer's canvas in a new element would be the tidier CSS, but it would move
+ *   their node in the document and break any selector or layout rule that depended on
+ *   where it was.
+ * - **`pointer-events: none`.** The panel is read-only, so it must never swallow a click
+ *   meant for the page underneath. The desktop panel does have widgets, but the two it
+ *   has — vsync and the CRT mode — are host-render settings that do not exist here.
+ * - **Styles are inline.** Nothing to serve, nothing for a bundler to find, and no
+ *   chance of a page's stylesheet reaching in; the same reasoning that keeps the audio
+ *   worklet a Blob rather than a file.
+ */
+/**
+ * How often the text is rewritten.
+ *
+ * Deliberately slower than the frame rate: the underlying averages only change when a
+ * sampling window closes, and text that changes 60 times a second is unreadable anyway.
+ * The DOM writes are what this throttle is really for — the measurements carry on every
+ * wake regardless.
+ */
+const REFRESH_MS = 250;
+/** Distance from the canvas's top-left corner, matching the desktop panel's [8, 8]. */
+const INSET_PX = 8;
+const TEXT = "#c8d0d8";
+const DIM = "#8896a0";
+const WARN = "#e8c060";
+const BAD = "#e05050";
+const PANEL_STYLE = {
+    position: "fixed",
+    // Above anything a page is plausibly stacking, since a debug panel hidden behind the
+    // page's own chrome would be useless.
+    zIndex: "2147483647",
+    pointerEvents: "none",
+    font: "12px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+    color: TEXT,
+    background: "rgba(8, 24, 32, 0.86)",
+    border: "1px solid rgba(136, 192, 112, 0.4)",
+    borderRadius: "4px",
+    padding: "6px 8px",
+    display: "none",
+};
+/** A read-only panel of counters, floating over the emulator's canvas. */
+export class StatsOverlay {
+    canvas;
+    element;
+    grid;
+    values = new Map();
+    shown = false;
+    lastRefresh = 0;
+    constructor(canvas) {
+        this.canvas = canvas;
+        this.element = document.createElement("div");
+        Object.assign(this.element.style, PANEL_STYLE);
+        const title = document.createElement("div");
+        title.textContent = "Stats";
+        title.style.marginBottom = "4px";
+        title.style.color = DIM;
+        this.element.appendChild(title);
+        this.grid = document.createElement("div");
+        this.grid.style.display = "grid";
+        this.grid.style.gridTemplateColumns = "auto auto";
+        this.grid.style.columnGap = "14px";
+        this.element.appendChild(this.grid);
+        // The same grouping as the desktop panel: how fast, what it cost, how the two
+        // clocks relate, and what the audio device is doing.
+        this.addRow("FPS");
+        this.addRow("Speed");
+        this.addSeparator();
+        this.addRow("  emulate");
+        this.addRow("  draw");
+        this.addRow("Work");
+        this.addSeparator();
+        this.addRow("Frames/wake");
+        this.addRow("Refresh");
+        this.addRow("Capped");
+        this.addSeparator();
+        this.addRow("Buffer");
+        this.addRow("Underruns");
+        this.addRow("Dropped");
+        this.addRow("Output");
+        document.body.appendChild(this.element);
+    }
+    get visible() {
+        return this.shown;
+    }
+    toggle() {
+        this.shown = !this.shown;
+        this.element.style.display = this.shown ? "block" : "none";
+        // Force the next update through: the panel should not open showing whatever was
+        // last written up to a refresh interval ago.
+        this.lastRefresh = 0;
+    }
+    /**
+     * Rewrites the panel, at most every {@link REFRESH_MS}.
+     *
+     * Cheap to call every frame — while hidden it does nothing at all, which is what keeps
+     * a switched-off feature costing a branch rather than a layout.
+     */
+    update(snapshot, now) {
+        if (!this.shown)
+            return;
+        if (now - this.lastRefresh < REFRESH_MS)
+            return;
+        this.lastRefresh = now;
+        this.position();
+        this.set("FPS", snapshot.fps.toFixed(1));
+        this.set("Speed", formatPercent(snapshot.speedPercent));
+        this.set("  emulate", formatMs(snapshot.emulate));
+        this.set("  draw", formatMs(snapshot.draw));
+        // The headline cost figure, coloured the same way the desktop colours its budget:
+        // worth noticing near the limit, noise the rest of the time.
+        this.set("Work", formatPercent(snapshot.workFraction * 100), loadColour(snapshot.workFraction));
+        this.set("Frames/wake", snapshot.framesPerWake.toFixed(2));
+        this.set("Refresh", `${snapshot.wakeRate.toFixed(1)} Hz`);
+        // A capped wake means the catch-up was clamped and a deficit was left behind —
+        // usually a backgrounded tab, occasionally a machine that cannot keep up.
+        this.set("Capped", count(snapshot.cappedWakes), snapshot.cappedWakes > 0 ? WARN : TEXT);
+        const audio = snapshot.audio;
+        if (!audio) {
+            // Only reachable in the first moments, before the worklet's first report.
+            this.set("Buffer", "—");
+            this.set("Underruns", "—");
+            this.set("Dropped", "—");
+            this.set("Output", "—");
+            return;
+        }
+        const targetMs = (audio.target / audio.sampleRate) * 1000;
+        this.set("Buffer", `${audio.bufferedMs.toFixed(1)} ms`, bufferColour(audio.bufferedMs, targetMs));
+        // Cumulative, and the closest thing here to the desktop's late-frame count: an
+        // underrun is a moment of silence that was actually heard.
+        this.set("Underruns", count(audio.underruns), audio.underruns > 0 ? WARN : TEXT);
+        // The opposite failure — the page ran ahead of the sound card and the ring threw
+        // samples away. Normal in small numbers after a tab comes back to the foreground.
+        this.set("Dropped", count(audio.dropped), audio.dropped > 0 ? WARN : TEXT);
+        this.set("Output", `${(audio.sampleRate / 1000).toFixed(1)}k ${audio.state}`, 
+        // A suspended context is the first thing to check when there is no sound, and
+        // nothing else on the panel would say so.
+        audio.state === "running" ? TEXT : WARN);
+    }
+    dispose() {
+        this.element.remove();
+    }
+    /**
+     * Anchors the panel to the canvas's current position.
+     *
+     * Re-read rather than cached because a page can scroll, resize or reflow under us with
+     * no event this module sees. `getBoundingClientRect` forces layout, which is why it
+     * happens on the refresh tick and only while the panel is open.
+     */
+    position() {
+        const rect = this.canvas.getBoundingClientRect();
+        this.element.style.left = `${rect.left + INSET_PX}px`;
+        this.element.style.top = `${rect.top + INSET_PX}px`;
+    }
+    addRow(label) {
+        const labelCell = document.createElement("span");
+        labelCell.textContent = label;
+        labelCell.style.color = DIM;
+        // Leading spaces mark the sub-rows of the work breakdown, as they do on the
+        // desktop; without this the browser collapses them.
+        labelCell.style.whiteSpace = "pre";
+        const valueCell = document.createElement("span");
+        valueCell.textContent = "—";
+        valueCell.style.textAlign = "right";
+        valueCell.style.whiteSpace = "pre";
+        this.grid.appendChild(labelCell);
+        this.grid.appendChild(valueCell);
+        this.values.set(label, valueCell);
+    }
+    /**
+     * A rule across both columns.
+     *
+     * `grid-column: 1 / -1` rather than one cell per column: two cells would be broken in
+     * the middle by the column gap, which reads as two dashes rather than the single line
+     * egui draws.
+     */
+    addSeparator() {
+        const rule = document.createElement("div");
+        rule.style.gridColumn = "1 / -1";
+        rule.style.borderTop = "1px solid rgba(200, 208, 216, 0.15)";
+        rule.style.margin = "3px 0";
+        this.grid.appendChild(rule);
+    }
+    set(label, text, colour = TEXT) {
+        const cell = this.values.get(label);
+        if (!cell)
+            return;
+        cell.textContent = text;
+        cell.style.color = colour;
+    }
+}
+/**
+ * A duration in milliseconds at a fixed width, so the column does not jitter.
+ *
+ * The desktop formats these as `{:>6.2} ms` for exactly the same reason.
+ */
+export function formatMs(ms) {
+    return `${ms.toFixed(2).padStart(6)} ms`;
+}
+export function formatPercent(percent) {
+    return `${percent.toFixed(0).padStart(4)}%`;
+}
+/** A plain count, right-aligned to the same width as the percentages above it. */
+export function count(value) {
+    return value.toString().padStart(5);
+}
+/**
+ * Green through to red as a figure approaches and passes its budget.
+ *
+ * Only worth colouring near the limit: a number that matters at 100% is easy to miss if
+ * it spends most of its time at 12%.
+ */
+export function loadColour(fraction) {
+    if (fraction > 1)
+        return BAD;
+    if (fraction > 0.8)
+        return WARN;
+    return TEXT;
+}
+/**
+ * How alarming the audio buffer's depth is.
+ *
+ * Zero is not a warning but a failure that was audible: the worklet emitted silence.
+ * Below half the target is the warning, because that is the buffer draining rather than
+ * sitting where the pacing loop means to hold it.
+ */
+export function bufferColour(bufferedMs, targetMs) {
+    if (bufferedMs <= 0)
+        return BAD;
+    if (bufferedMs < targetMs / 2)
+        return WARN;
+    return TEXT;
+}