@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/audio/synth.js

@@ -0,0 +1,197 @@
+/**
+ * Procedural synth: a declarative `SoundSpec` (layers of oscillators / noise / crackle, each
+ * with an envelope, optional glide, FM, vibrato, tremolo and filters) rendered once into an
+ * `AudioBuffer` with an `OfflineAudioContext`. Specs are plain data: easy to tweak, diff and test.
+ */
+import { fillCrackle, fillNoise, foldLoop, normalize } from './dsp.js';
+import { envelopeLength, scheduleEnvelope } from './envelope.js';
+function layerFilters(layer) {
+    if (!layer.filter)
+        return [];
+    return Array.isArray(layer.filter) ? layer.filter : [layer.filter];
+}
+/** Default gate: note-off early enough for the release to finish inside `duration`. */
+export function layerGate(layer, duration) {
+    if (layer.gate !== undefined)
+        return layer.gate;
+    return Math.max(0, duration - (layer.start ?? 0) - layer.env.release);
+}
+export function specChannels(spec) {
+    return spec.channels ?? (spec.layers.some((l) => l.pan) ? 2 : 1);
+}
+/** Problems with a spec, or an empty array. Used by tests and in dev before rendering. */
+export function validateSpec(spec) {
+    const errs = [];
+    const sr = spec.sampleRate ?? 44100;
+    const nyquist = sr / 2;
+    if (!(spec.duration > 0) || spec.duration > 60)
+        errs.push(`duration ${spec.duration} not in (0, 60]`);
+    if (spec.layers.length === 0)
+        errs.push('no layers');
+    if (spec.loop && !(spec.loop.crossfade >= 0 && spec.loop.crossfade < spec.duration))
+        errs.push('loop crossfade must be in [0, duration)');
+    spec.layers.forEach((l, i) => {
+        const at = `layer ${i}`;
+        const start = l.start ?? 0;
+        const gate = layerGate(l, spec.duration);
+        const end = start + envelopeLength(l.env, gate);
+        if (start < 0)
+            errs.push(`${at}: negative start`);
+        if (!spec.loop && end > spec.duration + 1e-6)
+            errs.push(`${at}: ends at ${end.toFixed(3)}s, after duration ${spec.duration}s`);
+        for (const k of ['attack', 'decay', 'release'])
+            if (!(l.env[k] >= 0))
+                errs.push(`${at}: env.${k} must be ≥ 0`);
+        if (!(l.env.sustain >= 0 && l.env.sustain <= 1))
+            errs.push(`${at}: env.sustain not in [0, 1]`);
+        if (l.pan !== undefined && Math.abs(l.pan) > 1)
+            errs.push(`${at}: pan not in [-1, 1]`);
+        if (l.source.type === 'osc') {
+            const { freq, freqEnd } = l.source;
+            if (!(freq > 0 && freq < nyquist))
+                errs.push(`${at}: freq ${freq} out of range`);
+            if (freqEnd !== undefined && !(freqEnd > 0 && freqEnd < nyquist))
+                errs.push(`${at}: freqEnd ${freqEnd} out of range`);
+        }
+        if (l.source.type === 'crackle' && !(l.source.density > 0))
+            errs.push(`${at}: density ≤ 0`);
+        for (const f of layerFilters(l)) {
+            if (!(f.freq > 0 && f.freq < nyquist))
+                errs.push(`${at}: filter freq ${f.freq} out of range`);
+            if (f.freqEnd !== undefined && !(f.freqEnd > 0 && f.freqEnd < nyquist))
+                errs.push(`${at}: filter freqEnd ${f.freqEnd} out of range`);
+        }
+    });
+    return errs;
+}
+const defaultOffline = (channels, length, sampleRate) => new OfflineAudioContext({ numberOfChannels: channels, length, sampleRate });
+function rampFreq(param, from, to, start, time, curve) {
+    param.setValueAtTime(from, start);
+    if (to === undefined || time <= 0)
+        return;
+    if (curve === 'exp')
+        param.exponentialRampToValueAtTime(Math.max(1e-3, to), start + time);
+    else
+        param.linearRampToValueAtTime(to, start + time);
+}
+function buildSource(ctx, layer, start, sweep, renderLen) {
+    const src = layer.source;
+    if (src.type === 'osc') {
+        const osc = ctx.createOscillator();
+        osc.type = src.wave;
+        const curve = src.glideCurve ?? 'exp';
+        const glide = src.glide ?? sweep;
+        rampFreq(osc.frequency, src.freq, src.freqEnd, start, glide, curve);
+        if (src.detune)
+            osc.detune.value = src.detune;
+        const extra = [];
+        if (src.vibrato) {
+            const lfo = ctx.createOscillator();
+            lfo.frequency.value = src.vibrato.rate;
+            const depth = ctx.createGain();
+            depth.gain.value = src.vibrato.depth;
+            lfo.connect(depth).connect(osc.detune);
+            extra.push(lfo);
+        }
+        if (src.fm) {
+            const mod = ctx.createOscillator();
+            const ratio = src.fm.ratio;
+            rampFreq(mod.frequency, src.freq * ratio, src.freqEnd !== undefined ? src.freqEnd * ratio : undefined, start, glide, curve);
+            const dev = ctx.createGain();
+            dev.gain.setValueAtTime(src.fm.index * src.freq, start);
+            if (src.fm.indexEnd !== undefined)
+                dev.gain.linearRampToValueAtTime(src.fm.indexEnd * (src.freqEnd ?? src.freq), start + sweep);
+            mod.connect(dev).connect(osc.frequency);
+            extra.push(mod);
+        }
+        return { node: osc, extra };
+    }
+    const sr = ctx.sampleRate;
+    const len = Math.max(1, Math.ceil((renderLen - start) * sr));
+    const data = new Float32Array(len);
+    if (src.type === 'noise')
+        fillNoise(data, src.color, src.seed ?? 1);
+    else
+        fillCrackle(data, sr, src.density, src.seed ?? 1, src.clickDecay);
+    const buf = ctx.createBuffer(1, len, sr);
+    buf.copyToChannel(data, 0);
+    const node = ctx.createBufferSource();
+    node.buffer = buf;
+    return { node, extra: [] };
+}
+/** Render a spec to an `AudioBuffer`. Rendering needs no user gesture. */
+export async function renderSound(spec, createOffline = defaultOffline) {
+    if (import.meta.env?.DEV) {
+        const errs = validateSpec(spec);
+        if (errs.length)
+            console.warn(`[audio] sound spec problems:\n  ${errs.join('\n  ')}`);
+    }
+    const sr = spec.sampleRate ?? 44100;
+    const channels = specChannels(spec);
+    const fade = spec.loop ? spec.loop.crossfade : 0;
+    const loopLen = Math.round(spec.duration * sr);
+    const fadeLen = Math.round(fade * sr);
+    const renderLen = (loopLen + fadeLen) / sr;
+    const ctx = createOffline(channels, loopLen + fadeLen, sr);
+    const master = ctx.createGain();
+    master.gain.value = spec.gain ?? 1;
+    master.connect(ctx.destination);
+    for (const layer of spec.layers) {
+        const start = layer.start ?? 0;
+        // In a loop, layers default to sounding through the crossfade tail too.
+        const gate = spec.loop && layer.gate === undefined ? renderLen - start : layerGate(layer, spec.duration);
+        const sweep = envelopeLength(layer.env, gate);
+        const { node, extra } = buildSource(ctx, layer, start, sweep, renderLen);
+        let out = node;
+        for (const f of layerFilters(layer)) {
+            const bq = ctx.createBiquadFilter();
+            bq.type = f.type;
+            rampFreq(bq.frequency, f.freq, f.freqEnd, start, sweep, 'exp');
+            if (f.q !== undefined)
+                bq.Q.value = f.q;
+            if (f.gain !== undefined)
+                bq.gain.value = f.gain;
+            out = out.connect(bq);
+        }
+        const amp = ctx.createGain();
+        scheduleEnvelope(amp.gain, layer.env, start, gate, layer.gain ?? 1);
+        out = out.connect(amp);
+        if (layer.tremolo) {
+            const trem = ctx.createGain();
+            trem.gain.value = 1 - layer.tremolo.depth / 2;
+            const lfo = ctx.createOscillator();
+            lfo.frequency.value = layer.tremolo.rate;
+            const depth = ctx.createGain();
+            depth.gain.value = layer.tremolo.depth / 2;
+            lfo.connect(depth).connect(trem.gain);
+            extra.push(lfo);
+            out = out.connect(trem);
+        }
+        if (channels === 2 && layer.pan) {
+            const pan = ctx.createStereoPanner();
+            pan.pan.value = layer.pan;
+            out = out.connect(pan);
+        }
+        out.connect(master);
+        const stopAt = Math.min(renderLen, start + sweep + 0.02);
+        for (const n of [node, ...extra]) {
+            n.start(start);
+            n.stop(stopAt);
+        }
+    }
+    const rendered = await ctx.startRendering();
+    let result = rendered;
+    if (spec.loop) {
+        result = ctx.createBuffer(channels, loopLen, sr);
+        for (let c = 0; c < channels; c++) {
+            result.copyToChannel(foldLoop(rendered.getChannelData(c), loopLen, fadeLen), c);
+        }
+    }
+    if (spec.normalize !== undefined) {
+        const chans = [];
+        for (let c = 0; c < result.numberOfChannels; c++)
+            chans.push(result.getChannelData(c));
+        normalize(chans, spec.normalize);
+    }
+    return result;
+}

package/dist/audio/variations.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Round-robin-ish one-shots: footsteps, impacts, hits. Picks one of several buffers at random,
+ * never the one just played, with a little pitch and gain jitter so repeats do not sound stamped.
+ */
+import type { AudioEngine, AudioPlayOptions, OutputBus, Voice } from './audio.js';
+export interface VariationsOptions {
+    /** Default `sfx`. */
+    bus?: OutputBus;
+    /** Random pitch offset in ± semitones (through `playbackRate`). Default 0. */
+    pitchJitter?: number;
+    /** Random level offset in ± dB. Default 0. */
+    gainJitter?: number;
+    /** Never play the same buffer twice in a row (with two or more buffers). Default true. */
+    noRepeat?: boolean;
+    /** Source of randomness in [0, 1). Default `Math.random`; tests pass their own. */
+    random?: () => number;
+}
+export interface Variations {
+    /** Play one variation. `opts.rate` and `opts.gain` are multiplied by the jitter. */
+    play(opts?: AudioPlayOptions): Voice;
+    /** Index of the buffer played last, -1 before the first play. */
+    readonly last: number;
+    readonly count: number;
+}
+export declare function createVariations(mixer: AudioEngine, buffers: readonly AudioBuffer[], opts?: VariationsOptions): Variations;

package/dist/audio/variations.js

@@ -0,0 +1,55 @@
+import { dbToGain } from './dsp.js';
+/** What `play` returns with no buffers: an inert voice, like the mixer's while locked. */
+const SILENT = {
+    stop() { },
+    setGain() { },
+    setRate() { },
+    setPosition() { },
+    setDirection() { },
+    follow() { },
+    sendTo() { },
+    filter() { },
+    position: new Float64Array(3),
+    playing: false,
+    sendCount: 0,
+    occlusion: 0,
+    doppler: 1,
+};
+export function createVariations(mixer, buffers, opts = {}) {
+    const bus = opts.bus ?? 'sfx';
+    const pitch = Math.abs(opts.pitchJitter ?? 0);
+    const gainDb = Math.abs(opts.gainJitter ?? 0);
+    const noRepeat = opts.noRepeat ?? true;
+    const random = opts.random ?? Math.random;
+    let last = -1;
+    function pick() {
+        const n = buffers.length;
+        if (n <= 1)
+            return 0;
+        if (!noRepeat || last < 0)
+            return Math.min(n - 1, Math.floor(random() * n));
+        // Uniform over the other n - 1 indices.
+        const r = Math.min(n - 2, Math.floor(random() * (n - 1)));
+        return r >= last ? r + 1 : r;
+    }
+    return {
+        play(o = {}) {
+            if (buffers.length === 0)
+                return SILENT;
+            const i = pick();
+            last = i;
+            const st = pitch > 0 ? (random() * 2 - 1) * pitch : 0;
+            const db = gainDb > 0 ? (random() * 2 - 1) * gainDb : 0;
+            return mixer.play(buffers[i], {
+                ...o,
+                bus: o.bus ?? bus,
+                rate: (o.rate ?? 1) * 2 ** (st / 12),
+                gain: (o.gain ?? 1) * dbToGain(db),
+            });
+        },
+        get last() {
+            return last;
+        },
+        count: buffers.length,
+    };
+}

package/dist/audio/zones.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Audio zones: regions of the world the listener can be in. Each zone weighs the listener
+ * (1 inside its shape, smoothstep to 0 across `feather` outside it) and the weights drive an
+ * ambient loop per zone and per-bus reverb sends. Pure bookkeeping over `AudioEngine`: no new
+ * graph nodes, nothing allocated per `update`.
+ */
+import type { AudioPlayOptions, OutputBus, Voice } from './audio.js';
+/** A sphere or an axis-aligned box in world units. */
+export type ZoneShape = {
+    sphere: {
+        center: ArrayLike<number>;
+        radius: number;
+    };
+} | {
+    box: {
+        center: ArrayLike<number>;
+        halfExtents: ArrayLike<number>;
+    };
+};
+export interface AudioZoneDesc {
+    shape: ZoneShape;
+    /** World units outside the shape over which the weight goes 1 → 0 (smoothstep). Default 1. */
+    feather?: number;
+    /**
+     * A loop played while the listener is in or near the zone: one `Voice` per zone, started the
+     * first time the weight rises above 0, gain = weight × `gain` (default 1) ramped over `fade`,
+     * stopped once the weight has stayed 0 for `fade` seconds.
+     */
+    ambient?: {
+        /** A registered sound to loop. Optional when `voice` is given. */
+        sound?: string;
+        bus?: OutputBus;
+        gain?: number;
+        /**
+         * Or a factory for the voice (ws/audio-4): any `Voice`, such as a `createVoiceAdapter` over a
+         * worklet or media source. Called when the zone first weighs in; the voice should start at
+         * gain 0 (the zone ramps it) and is stopped when the zone falls silent.
+         */
+        voice?: () => Voice;
+    };
+    /**
+     * Reverb send per bus while inside (linear). Across zones the largest `weight × send` wins,
+     * and the engine applies `max(base, zone)` where `base` is what `setReverbSend` set.
+     */
+    reverbSend?: Partial<Record<OutputBus, number>>;
+    /** Seconds the ambient gain takes to ramp fully, and the silence before its voice stops. Default 0.5. */
+    fade?: number;
+}
+/** A zone added to `audio.zones`; read-only bookkeeping, removed with `zones.remove(zone)`. */
+export interface AudioZone {
+    readonly desc: AudioZoneDesc;
+    /** The listener's weight at the last `update`: 1 inside, 0 beyond the feather. */
+    readonly weight: number;
+    /** The ambient voice's current gain (0 when none plays). */
+    readonly ambientGain: number;
+    /** The ambient voice while one plays. */
+    readonly voice: Voice | null;
+}
+/** What `AudioZones` needs from the engine (`AudioEngine` implements it). */
+export interface AudioZoneHost {
+    readonly listener: {
+        readonly position: ArrayLike<number>;
+    };
+    loop(sound: string, opts?: AudioPlayOptions): Voice;
+    /** The zones' contribution to one bus's reverb send (blended with the base by the host). */
+    setZoneReverbSend(bus: OutputBus, level: number): void;
+}
+/**
+ * The listener's weight for `desc` at `position`: 1 inside the shape, smoothstep down to 0 at
+ * `feather` world units outside it (a feather of 0 is a hard edge). Pure, allocation-free.
+ */
+export declare function zoneWeight(desc: AudioZoneDesc, position: ArrayLike<number>): number;
+/**
+ * The zones of one `AudioEngine` (`audio.zones`). `update(dt)` weighs the listener against
+ * every zone, ramps the ambient voices and resolves the reverb sends; `AudioEngine.update`
+ * calls it, and `createGame`'s loop calls that.
+ */
+export declare class AudioZones {
+    private readonly host;
+    private readonly list;
+    private readonly _weights;
+    private readonly sendMax;
+    private readonly sendApplied;
+    constructor(host: AudioZoneHost);
+    /** Add a zone. Its weight is 0 until the next `update`. */
+    add(desc: AudioZoneDesc): AudioZone;
+    /** Remove a zone, stopping its ambient voice over the zone's `fade`. Unknown zones are ignored. */
+    remove(zone: AudioZone): void;
+    /** The zones, in the order added. */
+    get size(): number;
+    /** The weight of every zone at the last `update`, in the order added (the same array each call). */
+    weights(): ReadonlyArray<number>;
+    /**
+     * Weigh the listener (default `host.listener.position`) against every zone, ramp the ambient
+     * voices and apply the reverb sends. Allocates nothing; the only graph writes are `setGain`
+     * on a voice whose gain changed and a send whose level changed by more than 1e-3.
+     */
+    update(dt: number, listenerPosition?: ArrayLike<number>): void;
+    private updateAmbient;
+}

package/dist/audio/zones.js

@@ -0,0 +1,167 @@
+const DEFAULT_FEATHER = 1;
+const DEFAULT_FADE = 0.5;
+const ZONE_BUSES = ['music', 'sfx', 'ui'];
+/** Gain changes below this are not written to the voice. */
+const GAIN_EPSILON = 1e-3;
+/**
+ * The listener's weight for `desc` at `position`: 1 inside the shape, smoothstep down to 0 at
+ * `feather` world units outside it (a feather of 0 is a hard edge). Pure, allocation-free.
+ */
+export function zoneWeight(desc, position) {
+    const px = position[0] ?? 0;
+    const py = position[1] ?? 0;
+    const pz = position[2] ?? 0;
+    let outside;
+    const s = desc.shape;
+    if ('sphere' in s) {
+        const c = s.sphere.center;
+        const dx = px - (c[0] ?? 0);
+        const dy = py - (c[1] ?? 0);
+        const dz = pz - (c[2] ?? 0);
+        outside = Math.sqrt(dx * dx + dy * dy + dz * dz) - s.sphere.radius;
+    }
+    else {
+        const c = s.box.center;
+        const h = s.box.halfExtents;
+        const dx = Math.max(0, Math.abs(px - (c[0] ?? 0)) - (h[0] ?? 0));
+        const dy = Math.max(0, Math.abs(py - (c[1] ?? 0)) - (h[1] ?? 0));
+        const dz = Math.max(0, Math.abs(pz - (c[2] ?? 0)) - (h[2] ?? 0));
+        outside = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    if (outside <= 0)
+        return 1;
+    const feather = desc.feather ?? DEFAULT_FEATHER;
+    if (outside >= feather)
+        return 0;
+    const t = outside / feather;
+    return 1 - t * t * (3 - 2 * t);
+}
+class ZoneImpl {
+    desc;
+    weight = 0;
+    ambientGain = 0;
+    voice = null;
+    /** Seconds the weight has been 0 while a voice plays. */
+    silentFor = 0;
+    constructor(desc) {
+        this.desc = desc;
+    }
+}
+/**
+ * The zones of one `AudioEngine` (`audio.zones`). `update(dt)` weighs the listener against
+ * every zone, ramps the ambient voices and resolves the reverb sends; `AudioEngine.update`
+ * calls it, and `createGame`'s loop calls that.
+ */
+export class AudioZones {
+    host;
+    list = [];
+    _weights = [];
+    sendMax = { music: 0, sfx: 0, ui: 0 };
+    sendApplied = { music: 0, sfx: 0, ui: 0 };
+    constructor(host) {
+        this.host = host;
+    }
+    /** Add a zone. Its weight is 0 until the next `update`. */
+    add(desc) {
+        const z = new ZoneImpl(desc);
+        this.list.push(z);
+        this._weights.push(0);
+        return z;
+    }
+    /** Remove a zone, stopping its ambient voice over the zone's `fade`. Unknown zones are ignored. */
+    remove(zone) {
+        const i = this.list.indexOf(zone);
+        if (i < 0)
+            return;
+        const z = this.list[i];
+        z.voice?.stop(z.desc.fade ?? DEFAULT_FADE);
+        z.voice = null;
+        z.weight = 0;
+        z.ambientGain = 0;
+        this.list.splice(i, 1);
+        this._weights.splice(i, 1);
+    }
+    /** The zones, in the order added. */
+    get size() {
+        return this.list.length;
+    }
+    /** The weight of every zone at the last `update`, in the order added (the same array each call). */
+    weights() {
+        return this._weights;
+    }
+    /**
+     * Weigh the listener (default `host.listener.position`) against every zone, ramp the ambient
+     * voices and apply the reverb sends. Allocates nothing; the only graph writes are `setGain`
+     * on a voice whose gain changed and a send whose level changed by more than 1e-3.
+     */
+    update(dt, listenerPosition = this.host.listener.position) {
+        const sends = this.sendMax;
+        sends.music = 0;
+        sends.sfx = 0;
+        sends.ui = 0;
+        const list = this.list;
+        for (let i = 0; i < list.length; i++) {
+            const z = list[i];
+            const d = z.desc;
+            const w = zoneWeight(d, listenerPosition);
+            z.weight = w;
+            this._weights[i] = w;
+            const rs = d.reverbSend;
+            if (rs && w > 0) {
+                for (let b = 0; b < ZONE_BUSES.length; b++) {
+                    const bus = ZONE_BUSES[b];
+                    const s = rs[bus];
+                    if (s !== undefined && w * s > sends[bus])
+                        sends[bus] = w * s;
+                }
+            }
+            if (d.ambient)
+                this.updateAmbient(z, w, dt);
+        }
+        for (let b = 0; b < ZONE_BUSES.length; b++) {
+            const bus = ZONE_BUSES[b];
+            if (Math.abs(sends[bus] - this.sendApplied[bus]) > GAIN_EPSILON) {
+                this.sendApplied[bus] = sends[bus];
+                this.host.setZoneReverbSend(bus, sends[bus]);
+            }
+        }
+    }
+    updateAmbient(z, w, dt) {
+        const a = z.desc.ambient;
+        const fade = z.desc.fade ?? DEFAULT_FADE;
+        const peak = a.gain ?? 1;
+        const target = w * peak;
+        if (!z.voice) {
+            if (target <= 0)
+                return;
+            if (a.voice)
+                z.voice = a.voice();
+            else if (a.sound !== undefined) {
+                z.voice = this.host.loop(a.sound, { bus: a.bus ?? 'sfx', gain: 0, fadeIn: 0 });
+            }
+            else
+                return;
+            z.ambientGain = 0;
+            z.silentFor = 0;
+        }
+        // Linear ramp: the full peak takes `fade` seconds.
+        const step = fade > 0 ? (peak * dt) / fade : Math.abs(target - z.ambientGain);
+        const diff = target - z.ambientGain;
+        const next = Math.abs(diff) <= step ? target : z.ambientGain + Math.sign(diff) * step;
+        if (Math.abs(next - z.ambientGain) > GAIN_EPSILON || (next === 0 && z.ambientGain !== 0)) {
+            z.ambientGain = next;
+            z.voice.setGain(next);
+        }
+        if (w <= 0) {
+            z.silentFor += dt;
+            if (z.silentFor >= fade && z.ambientGain <= GAIN_EPSILON) {
+                z.voice.stop();
+                z.voice = null;
+                z.ambientGain = 0;
+            }
+        }
+        else {
+            z.silentFor = 0;
+        }
+    }
+}

package/dist/core/detached-surface.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The surface behind `createGame({ overlay: false })` (ws/core-9): the letterbox maths of
+ * `Surface` on a virtual container, with no canvas, no root element and no DOM listener. The
+ * container is the design size until `resizeContainer` changes it, at a pixel ratio of 1, so
+ * client px are design px by default. Internal: it implements the `Surface` interface with no
+ * cast (ws/platform-surface), and `ctx.surface` is typed `Surface`; reading its `root` or
+ * `canvas` throws.
+ */
+import { type BackbufferSize, type Letterbox, type Surface, type SurfaceOptions, type SurfaceSize, type Vec2 } from '../platform/index.js';
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare class DetachedSurface implements Surface {
+    readonly logicalWidth: number;
+    readonly logicalHeight: number;
+    rect: Letterbox;
+    fitRect: Letterbox;
+    backbuffer: BackbufferSize;
+    private containerW;
+    private containerH;
+    private frame;
+    private readonly maxDpr;
+    private readonly maxPixels;
+    private readonly listeners;
+    constructor(opts?: SurfaceOptions);
+    get root(): HTMLElement;
+    get canvas(): HTMLCanvasElement;
+    /** The virtual container's size in CSS px (a test's viewport); lays out again at once. */
+    resizeContainer(width: number, height: number): void;
+    onResize(fn: (size: SurfaceSize) => void): () => void;
+    /** The container sits at the client origin, so client coordinates are container ones. */
+    clientToLogical(clientX: number, clientY: number, out?: Vec2): Vec2;
+    logicalToClient(x: number, y: number, out?: Vec2): Vec2;
+    containsLogical(p: Vec2): boolean;
+    setFrame(frame: Rect | null): void;
+    layout(): void;
+    destroy(): void;
+}
+/** The error a DOM-only member throws with `overlay: false`. */
+export declare const NO_DOM: (what: string) => string;
+export {};