js-game-zero 0.0.0-stage → 0.3.0

package/dist/runtime-contracts.d.ts

@@ -0,0 +1,117 @@
+import type { AssetLoaders, AssetUrls, FontAsset, MusicAsset, SoundAsset, SurfaceLike } from "./assets.js";
+import type { InputHooks, MappedKeyboardEvent, MappedMouseEvent } from "./events.js";
+import type { Storage, StorageAdapter } from "./storage.js";
+import type { TouchControlsConfig } from "./touch-controls.js";
+export type GameModule = InputHooks & {
+    readonly WIDTH?: number;
+    readonly HEIGHT?: number;
+    /**
+     * Canvas pixels per logical pixel. Defaults to the device's pixel ratio,
+     * at most 3, so the game is sharp on high-density screens.
+     */
+    readonly PIXEL_DENSITY?: number;
+    readonly TITLE?: string;
+    readonly ICON?: string | null;
+    readonly TOUCH_CONTROLS?: TouchControlsConfig;
+    readonly draw?: () => void;
+    /** Called every frame with the seconds since the last one. */
+    readonly update?: (dt: number) => void;
+};
+export type RuntimeMode = "global" | "import";
+export type RuntimeDiagnostic = {
+    readonly code: "asset-name" | "constant-typo" | "duplicate-config" | "hook-arity" | "hook-parameter" | "hook-typo" | "invalid-config" | "runtime-error";
+    readonly severity: "warning" | "error";
+    readonly message: string;
+    readonly name?: string;
+    readonly suggestion?: string;
+    readonly phase?: RuntimeFailurePhase;
+    /**
+     * The 1-based line in the game source the diagnostic is about, when known:
+     * where a `runtime-error` was thrown, or where a misspelled hook or
+     * setting is declared.
+     */
+    readonly line?: number;
+    readonly recoverable?: boolean;
+};
+export type RuntimeFailurePhase = "startup" | "input" | "clock" | "update" | "draw" | "asset" | "storage" | "audio";
+export type RuntimeFailure = {
+    readonly phase: RuntimeFailurePhase;
+    readonly message: string;
+    readonly cause: unknown;
+    /** 1-based line in the game source where the error was thrown, when the engine reports one. */
+    readonly line?: number;
+};
+export type GameHandleState = "starting" | "running" | "paused" | "failed" | "stopped";
+export type RuntimeScheduler = {
+    requestAnimationFrame(callback: (timestamp: number) => void): unknown;
+    cancelAnimationFrame(handle: unknown): void;
+    now?(): number;
+};
+export type RuntimeCanvas = HTMLCanvasElement & {
+    getBoundingClientRect?: () => {
+        left: number;
+        top: number;
+        width?: number;
+        height?: number;
+    };
+};
+export type RunOptions = Partial<GameModule> & {
+    readonly assetBaseUrl?: string;
+    /**
+     * The game's assets by path (`images/cat.svg`), each with its URL, such as
+     * a data URL. When set, assets load only from here, never from
+     * `assetBaseUrl`, so a page can run a game with no server.
+     */
+    readonly assetUrls?: AssetUrls;
+    readonly autostart?: boolean;
+    readonly canvas?: RuntimeCanvas;
+    readonly container?: HTMLElement;
+    readonly diagnostics?: (diagnostic: RuntimeDiagnostic) => void;
+    readonly keyboardTarget?: EventTarget;
+    /**
+     * Where mouse releases (`mouseup`) are heard. Defaults to `window`, so a
+     * drag released outside the canvas still ends; a host running a game it
+     * drives itself passes the canvas, so its synthetic releases reach no
+     * other game on the page.
+     */
+    readonly mouseReleaseTarget?: EventTarget;
+    readonly preload?: readonly string[];
+    readonly preloadedAssets?: PreloadedAssets;
+    readonly projectId?: string;
+    readonly scheduler?: RuntimeScheduler;
+    /**
+     * Makes the game's randomness repeatable: `Math.random` as a zero-boilerplate
+     * game sees it, and `randomInt` and `randomChoice`, follow one sequence for
+     * this seed, the same one `jgz test --seed` uses. Only this game's: the
+     * page's `Math.random` and other games are untouched. Up to nine plain
+     * digits are the number they spell; anything else is hashed.
+     */
+    readonly seed?: string | number;
+    readonly storage?: Storage | StorageAdapter;
+    /** Context-owned loader overrides for embedding hosts and deterministic tests. */
+    readonly loaders?: Partial<AssetLoaders>;
+};
+export type PreloadedAssets = {
+    readonly images?: Record<string, SurfaceLike>;
+    readonly sounds?: Record<string, SoundAsset>;
+    readonly music?: Record<string, MusicAsset>;
+    readonly fonts?: Record<string, FontAsset>;
+};
+export type GameKeyEvent = Readonly<MappedKeyboardEvent>;
+export type GameMouseEvent = Readonly<MappedMouseEvent>;
+export type DefinedGameModule = {
+    readonly WIDTH?: number;
+    readonly HEIGHT?: number;
+    readonly PIXEL_DENSITY?: number;
+    readonly TITLE?: string;
+    readonly ICON?: string | null;
+    readonly TOUCH_CONTROLS?: TouchControlsConfig;
+    readonly draw?: () => void;
+    readonly update?: (dt: number) => void;
+    readonly onKeyDown?: (event: GameKeyEvent) => void;
+    readonly onKeyUp?: (event: GameKeyEvent) => void;
+    readonly onMouseDown?: (event: GameMouseEvent) => void;
+    readonly onMouseUp?: (event: GameMouseEvent) => void;
+    readonly onMouseMove?: (event: GameMouseEvent) => void;
+    readonly onMusicEnd?: () => void;
+};

package/dist/runtime-diagnostics.d.ts

@@ -0,0 +1,37 @@
+import type { GameModule, RunOptions, RuntimeDiagnostic, RuntimeMode } from "./runtime-contracts.js";
+export declare const RUNTIME_CONFIGURATION_NAMES: readonly ["WIDTH", "HEIGHT", "PIXEL_DENSITY", "TITLE", "ICON", "TOUCH_CONTROLS"];
+/** Every hook a zero-boilerplate script can define. */
+export declare const RUNTIME_SOURCE_HOOK_NAMES: readonly ["draw", "update", "onMouseDown", "onMouseUp", "onMouseMove", "onKeyDown", "onKeyUp", "onMusicEnd"];
+export declare const RUNTIME_MODULE_OPTION_NAMES: readonly ["WIDTH", "HEIGHT", "PIXEL_DENSITY", "TITLE", "ICON", "TOUCH_CONTROLS", "draw", "update", "onMouseDown", "onMouseUp", "onMouseMove", "onKeyDown", "onKeyUp", "onMusicEnd"];
+export declare function collectRuntimeDiagnostics(moduleOrSource: GameModule | string, options?: RunOptions): RuntimeDiagnostic[];
+export declare function diagnoseGameModule(module: GameModule, options: RunOptions, emit: (diagnostic: RuntimeDiagnostic) => void, mode: RuntimeMode, 
+/** run() stops a game whose draw() takes parameters, and says so: a
+ * warning as well would be the same mistake twice. */
+drawArityIsFatal?: boolean): void;
+/**
+ * Static checks on zero-boilerplate source. Typo checks only look at what the
+ * script defines at top level — a top-level function whose name is nearly a
+ * hook name, or a top-level assignment whose name is nearly a configuration
+ * constant — never at identifiers the script merely uses (`row`, `col`,
+ * `rows[y]`), and never when the real name is also defined (`draw` plus a
+ * `drawn` helper is not a typo). Asset-name checks scan every quoted string.
+ */
+export declare function diagnoseSource(source: string, emit: (diagnostic: RuntimeDiagnostic) => void): void;
+/**
+ * The 1-based line where a game's source declares `name` at the start of a
+ * line: `function name(`, `name = ` or `let name = `.
+ */
+export declare function declarationLine(source: string, name: string): number | undefined;
+export declare function createDiagnosticEmitter(diagnostics: RuntimeDiagnostic[], callback?: (diagnostic: RuntimeDiagnostic) => void): (diagnostic: RuntimeDiagnostic) => void;
+/**
+ * Ambient diagnostic sink for whichever run is active at call time, mirroring
+ * the active-service pattern used for loaders/storage/clock. Only valid for
+ * the duration of the synchronous call that reads it — callers whose work
+ * continues asynchronously (e.g. a loader promise that may reject later)
+ * must capture the returned function and close over it rather than reading
+ * the ambient value again once the run may have moved on.
+ */
+export declare function setActiveDiagnosticEmit(emit: ((diagnostic: RuntimeDiagnostic) => void) | null): ((diagnostic: RuntimeDiagnostic) => void) | null;
+export declare function getActiveDiagnosticEmit(): ((diagnostic: RuntimeDiagnostic) => void) | null;
+export declare function describeRuntimeError(error: unknown): string;
+export declare function isValidRuntimeDimension(value: unknown): value is number;

package/dist/runtime-persistence.d.ts

@@ -0,0 +1,32 @@
+import { Storage } from "./storage.js";
+type PersistenceDiagnostic = {
+    readonly code: "runtime-error";
+    readonly severity: "warning";
+    readonly phase: "storage";
+    readonly recoverable: true;
+    readonly message: string;
+};
+type PersistenceDiagnosticEmitter = (diagnostic: PersistenceDiagnostic) => void;
+export type Autosave = {
+    /**
+     * Cancels any pending debounce timer and saves immediately, if anything
+     * changed since the last save or load, inside stored objects and lists too.
+     */
+    flush(): Promise<void>;
+    /** Unsubscribes from storage changes and browser lifecycle events. */
+    detach(): void;
+};
+/**
+ * Coordinates debounced and lifecycle-triggered persistence for one runtime.
+ * Writes are serialized and mutations that arrive while a save is active are
+ * folded into a subsequent write.
+ */
+export declare function attachAutosave(storage: Storage, emit: PersistenceDiagnosticEmitter): Autosave;
+/** Loads exactly once, preferring an adapter's truly synchronous path. */
+export declare function primeStorage(storage: Storage, emit: PersistenceDiagnosticEmitter): {
+    state: {
+        current: boolean;
+    };
+    promise: Promise<void>;
+};
+export {};

package/dist/runtime-source.d.ts

@@ -0,0 +1,82 @@
+import type { AssetLoaders } from "./assets.js";
+import type { MusicPlayer } from "./audio.js";
+import { Clock } from "./clock.js";
+import { type KeyboardState, type MouseState } from "./input.js";
+import { type RandomSource } from "./random.js";
+import { Screen } from "./rendering.js";
+import type { GameModule, RuntimeDiagnostic } from "./runtime-contracts.js";
+import { Storage } from "./storage.js";
+import type { ToneGenerator } from "./tone.js";
+export type SourceEvaluationContext = {
+    readonly screen: Screen;
+    readonly clock: Clock;
+    readonly keyboard: KeyboardState;
+    readonly mouseState: MouseState;
+    readonly loaders: AssetLoaders;
+    readonly music: MusicPlayer;
+    readonly storage: Storage;
+    readonly tone: ToneGenerator;
+    /** The run's seeded random source, or null to leave `Math` as it is. */
+    readonly random: RandomSource | null;
+    stop: (() => void) | null;
+};
+export type SourceInspector = {
+    /** Non-function top-level declarations and assignments. */
+    bindings(): readonly string[];
+    /** Top-level function declarations and function-valued bindings. */
+    functions(): readonly string[];
+    read(name: string): unknown;
+};
+type SourceEvaluation = {
+    readonly module: GameModule;
+    readonly inspector: SourceInspector;
+};
+/** Evaluates one zero-boilerplate script inside its run-owned service scope. */
+export declare function executeZeroBoilerplateSource(source: string, context: SourceEvaluationContext, emit: (diagnostic: RuntimeDiagnostic) => void): SourceEvaluation;
+/**
+ * The one line of `source` that reads `name` (outside strings and comments,
+ * and not as a property after a dot), or undefined when it's on none or on
+ * more than one.
+ */
+export declare function onlyLineOf(name: string, source: string): number | undefined;
+/**
+ * How this engine numbers lines in `new Function` code: from the place of a
+ * stack frame (V8, SpiderMonkey), or, where a frame there has no location
+ * (JavaScriptCore), from the error's own `line`.
+ */
+export type FrameCalibration = {
+    readonly kind: "stack";
+    readonly marker: string;
+    readonly offset: number;
+} | {
+    readonly kind: "line";
+    readonly offset: number;
+    /** The `sourceURL` errors from game code carry: none, on JavaScriptCore. */
+    readonly url: string | undefined;
+};
+/**
+ * The calibration a throw from the first line of game source gives. The
+ * throwing frame is the stack's first frame, after V8's `Error: message` line:
+ * when it has a location, its place marks game frames; when it has none
+ * (JavaScriptCore's `anonymous@`), the error's own `line` is used instead.
+ */
+export declare function readCalibration(error: unknown): FrameCalibration | null;
+/** The game source's line for `error` under `calibration`, or undefined when it wasn't thrown there. */
+export declare function lineWith(calibration: FrameCalibration, error: unknown): number | undefined;
+/**
+ * The 1-based line of the syntax error `message` in `source`, for engines that
+ * give none: the first line whose prefix of the source fails with the same
+ * message. An error at the end of the source (something left open) is placed
+ * on the line after the last prefix that compiles, where the open part starts.
+ */
+export declare function syntaxErrorLine(source: string, message: string): number | undefined;
+/** Records the source line of a mistake the runtime itself finds in a
+ * game, which no stack trace could place. */
+export declare function noteSourceLine(error: object, line: number): void;
+/**
+ * The 1-based line in the game source where `error` was thrown, or undefined
+ * when it wasn't thrown in game code (the error came from the library, or the
+ * engine gives no usable position).
+ */
+export declare function sourceLineOf(error: unknown): number | undefined;
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,81 @@
+import { Actor } from "./actor.js";
+import { Animation, animate } from "./animation.js";
+import { type AssetLoaders } from "./assets.js";
+import { Clock } from "./clock.js";
+import { Rect, ZRect } from "./geometry.js";
+import { KeyboardState, keymods, keys, type LiveMouse } from "./input.js";
+import { createMusicPlayer } from "./audio.js";
+import { Screen } from "./rendering.js";
+import { Storage } from "./storage.js";
+import { createToneGenerator } from "./tone.js";
+import { type SourceInspector } from "./runtime-source.js";
+import type { DefinedGameModule, GameHandleState, GameModule, RunOptions, RuntimeCanvas, RuntimeDiagnostic, RuntimeFailure, RuntimeMode } from "./runtime-contracts.js";
+export type { DefinedGameModule, GameHandleState, GameKeyEvent, GameModule, GameMouseEvent, PreloadedAssets, RunOptions, RuntimeCanvas, RuntimeDiagnostic, RuntimeFailure, RuntimeFailurePhase, RuntimeMode, RuntimeScheduler, } from "./runtime-contracts.js";
+export { collectRuntimeDiagnostics } from "./runtime-diagnostics.js";
+export type GameContext = {
+    readonly Actor: typeof Actor;
+    readonly Animation: typeof Animation;
+    readonly Rect: typeof Rect;
+    readonly ZRect: typeof ZRect;
+    readonly Screen: typeof Screen;
+    readonly Storage: typeof Storage;
+    readonly screen: Screen;
+    readonly clock: Clock;
+    readonly keyboard: KeyboardState;
+    readonly keymods: typeof keymods;
+    readonly keys: typeof keys;
+    readonly mouse: LiveMouse;
+    readonly images: AssetLoaders["images"];
+    readonly sounds: AssetLoaders["sounds"];
+    readonly music: ReturnType<typeof createMusicPlayer>;
+    readonly fonts: AssetLoaders["fonts"];
+    readonly storage: Storage;
+    readonly tone: ReturnType<typeof createToneGenerator>;
+    readonly animate: typeof animate;
+    readonly exit: typeof exit;
+};
+declare const definedGameBrand: unique symbol;
+export type DefinedGame = {
+    readonly [definedGameBrand]: true;
+    readonly create: (context: GameContext) => DefinedGameModule;
+};
+export declare function defineGame(factory: (context: GameContext) => DefinedGameModule): DefinedGame;
+export type GameHandle = {
+    readonly mode: RuntimeMode;
+    readonly canvas: RuntimeCanvas;
+    readonly screen: Screen;
+    readonly clock: Clock;
+    readonly keyboard: KeyboardState;
+    readonly loaders: AssetLoaders;
+    readonly storage: Storage;
+    readonly diagnostics: readonly RuntimeDiagnostic[];
+    readonly module: GameModule;
+    readonly state: GameHandleState;
+    readonly failure: RuntimeFailure | null;
+    /**
+     * Resolves once the "preload gate" is satisfied: storage has been
+     * loaded and every asset requested while the game module was
+     * evaluated (Actor constructions, `images.x` touches, etc.) has
+     * settled. The runtime itself already holds frames until this is
+     * true; this is exposed for tests and host integrations that want to
+     * await readiness explicitly instead of polling `step()`.
+     */
+    readonly ready: Promise<void>;
+    readonly done: Promise<void>;
+    pause(): void;
+    resume(): void;
+    step(dt: number): void;
+    stop(): void;
+    dispose(): Promise<void>;
+    restart(source?: GameModule | string | DefinedGame): Promise<GameHandle>;
+    /** @deprecated Prefer restart(), which awaits cleanup before starting again. */
+    reload(source?: GameModule | string | DefinedGame): GameHandle;
+};
+/**
+ * The source bindings of a live zero-boilerplate game, or null. Hosts use
+ * `getGameInspector` from `js-game-zero/host`, which reads paths and
+ * serialises values on top of this.
+ */
+export declare function getSourceInspector(handle: GameHandle): SourceInspector | null;
+export declare function run(moduleOrSource: GameModule | string | DefinedGame, options?: RunOptions): GameHandle;
+export declare function exit(): void;

package/dist/source-scan.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A small lexical scan of zero-boilerplate game source, used by the typo
+ * diagnostics to find the names a script actually *defines* at top level
+ * (as opposed to every identifier it merely mentions). It is deliberately
+ * not a parser: it tokenizes comments, strings, template literals (with
+ * nested substitutions), regex literals, identifiers and punctuators while
+ * tracking brace depth, and pattern-matches definitions on the token stream.
+ *
+ * On anything it cannot make sense of (an unterminated string, comment,
+ * template or regex, or unbalanced braces/parens) the scan reports itself
+ * incomplete and callers emit nothing: no diagnostic beats a wrong one.
+ */
+export type SourceTokenType = "identifier" | "punctuator" | "literal";
+export type SourceToken = {
+    readonly type: SourceTokenType;
+    readonly value: string;
+    /** Brace depth at the token: 0 means outside every `{…}` and `${…}`. */
+    readonly depth: number;
+    /** Parenthesis depth at the token: 0 means outside every `(…)`. */
+    readonly parens: number;
+    /** Square-bracket depth at the token: 0 means outside every `[…]`. */
+    readonly brackets: number;
+};
+export type SourceScan = {
+    /** False when the tokenizer gave up; the name lists are then empty. */
+    readonly complete: boolean;
+    /**
+     * Names given a function value at depth 0: `function NAME(`, and
+     * `NAME = function…`, `NAME = async …`, `NAME = (…) =>`, `NAME = x =>`
+     * (with or without `const`/`let`/`var`).
+     */
+    readonly topLevelFunctions: readonly string[];
+    /** Depth-0 assignment and declaration targets (`NAME = …`, `let NAME`). */
+    readonly topLevelAssignments: readonly string[];
+};
+/**
+ * Splits `source` into tokens, or returns null when it cannot be tokenized
+ * confidently. Comments vanish; strings, templates, regexes and numbers
+ * become `literal` tokens (the code inside template substitutions is
+ * tokenized normally, one brace deeper than the template).
+ */
+export declare function tokenizeSource(source: string, 
+/** Return the tokens of source that leaves a bracket open at the end,
+ * rather than null, to find out what's open. */
+{ allowUnclosed }?: {
+    readonly allowUnclosed?: boolean;
+}): SourceToken[] | null;
+/** Finds the names `source` defines at top level; see {@link SourceScan}. */
+export declare function scanSource(source: string): SourceScan;

package/dist/storage-path.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeStoragePath(path: string): string;
+export declare function normalizeSandboxStoragePath(path: string): string;
+export declare function sandboxStoragePath(projectRoot: string, safePath: string): string;

package/dist/storage.d.ts

@@ -0,0 +1,88 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type StorageAdapter = {
+    readonly path: string;
+    load(): Promise<string | null>;
+    loadSync?(): string | null;
+    save(text: string): Promise<void> | void;
+};
+export type BrowserStorageLike = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+};
+export type LocalStorageAdapterOptions = {
+    readonly projectId?: string;
+    readonly path?: string;
+    readonly localStorage?: BrowserStorageLike;
+};
+export type StorageOptions = {
+    readonly adapter?: StorageAdapter;
+    readonly projectId?: string;
+    readonly path?: string;
+};
+export declare class JsonStorageError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+/** Keyed by a symbol so no storage key can collide with it. */
+declare const savedText: unique symbol;
+export declare class Storage {
+    private readonly adapter;
+    private readonly values;
+    private readonly listeners;
+    /** A load() that loadSync() started and found to be asynchronous. */
+    private pendingLoad;
+    /** The JSON last saved or loaded: what the adapter holds, as far as this storage knows. */
+    [savedText]: string;
+    constructor(options?: StorageOptions);
+    get path(): string;
+    get(key: string, defaultValue?: unknown): unknown;
+    set(key: string, value: unknown): void;
+    setDefault(key: string, defaultValue: unknown): unknown;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    keys(): string[];
+    toJSON(): Record<string, JsonValue>;
+    /**
+     * Subscribes to any mutation (set/delete/clear/setDefault-insert),
+     * including mutations made through the PGZero-style proxy (e.g.
+     * `storage.score = 5`). Returns an unsubscribe function. Used by the
+     * runtime to drive debounced auto-save; loading does not notify.
+     */
+    onChange(listener: () => void): () => void;
+    save(): Promise<void>;
+    load(): Promise<void>;
+    /**
+     * Loads synchronously when the adapter can: with its `loadSync()`, or
+     * with a `load()` that returns its text rather than a Promise. A `load()`
+     * that turns out to be asynchronous is kept for `load()` to finish, so
+     * falling back to it still reads the store only once.
+     */
+    loadSync(): boolean;
+    private applyLoadedText;
+    private notify;
+    private jsonObject;
+}
+/**
+ * Whether `storage` holds anything its last save or load didn't, including a
+ * change inside a stored object or list (`storage.highScores.push(...)`),
+ * which no set() announces. Throws a JsonStorageError, naming the key, when
+ * a stored value has since become one JSON can't hold.
+ */
+export declare function hasUnsavedChanges(storage: Storage): boolean;
+export declare function createStorage(options?: StorageOptions): Storage;
+export declare function createLocalStorageAdapter(options?: LocalStorageAdapterOptions): StorageAdapter;
+export declare function validateJsonValue(value: unknown, path?: string): void;
+/** Default backing instance used when no runtime-scoped storage is active. */
+export declare const defaultStorage: Storage;
+export declare function setActiveStorage(nextStorage: Storage | null): Storage | null;
+export declare function getActiveStorage(): Storage;
+/**
+ * PGZero-style process-level convenience proxy. Runtime callbacks scope this
+ * proxy to their own Storage instance; outside a runtime it uses a default
+ * local-storage-backed instance.
+ */
+export declare const storage: Storage;
+export {};

package/dist/tone.d.ts

@@ -0,0 +1,81 @@
+import { type AudioUnlockState } from "./audio.js";
+export type Waveform = OscillatorType;
+/** pgzero's tone.Waveform names that don't match the Web Audio OscillatorType spelling. */
+export type WaveformAlias = "sin" | "saw";
+export type WaveformInput = Waveform | WaveformAlias;
+export type AudioParamLike = {
+    value: number;
+    setValueAtTime?: (value: number, startTime: number) => void;
+};
+export type OscillatorNodeLike = {
+    type: Waveform;
+    frequency: AudioParamLike;
+    connect(destination: unknown): unknown;
+    start(when?: number): void;
+    stop(when?: number): void;
+};
+export type GainNodeLike = {
+    gain: AudioParamLike;
+    connect(destination: unknown): unknown;
+};
+export type AudioContextLike = {
+    readonly destination: unknown;
+    currentTime: number;
+    state?: string;
+    resume?: () => Promise<void>;
+    createOscillator(): OscillatorNodeLike;
+    createGain(): GainNodeLike;
+};
+export type ToneOptions = {
+    readonly audioContext?: AudioContextLike;
+    readonly unlockState?: AudioUnlockState;
+    readonly waveform?: WaveformInput;
+    readonly volume?: number;
+};
+export type TonePlayOptions = Omit<ToneOptions, "audioContext" | "unlockState">;
+/** pgzero's tone module defaults to volume 0.8 (see pgzero.tone._convert_args). */
+export declare const DEFAULT_TONE_VOLUME = 0.8;
+export type ToneSpec = {
+    readonly frequency: number;
+    readonly duration: number;
+    readonly waveform: Waveform;
+    readonly volume: number;
+};
+export type TonePlayback = ToneSpec & {
+    readonly startedAt: number;
+    readonly stoppedAt: number;
+};
+export type ToneDebugState = {
+    readonly unlocked: boolean;
+    readonly contextState: string | null;
+    readonly scheduled: readonly TonePlayback[];
+};
+export declare class CreatedTone implements ToneSpec {
+    readonly frequency: number;
+    readonly duration: number;
+    readonly waveform: Waveform;
+    readonly volume: number;
+    private readonly generator;
+    constructor(generator: ToneGenerator, spec: ToneSpec);
+    play(options?: TonePlayOptions): Promise<TonePlayback>;
+}
+export declare class ToneGenerator {
+    private contextValue;
+    private readonly unlockState;
+    private readonly scheduledTones;
+    constructor(options?: ToneOptions);
+    create(noteOrFrequency: string | number, duration?: number, options?: TonePlayOptions): CreatedTone;
+    play(noteOrFrequency: string | number, duration?: number, options?: TonePlayOptions): Promise<TonePlayback>;
+    private start;
+    unlock(): Promise<boolean>;
+    isUnlocked(): boolean;
+    debugState(): ToneDebugState;
+    private createSpec;
+    private getContext;
+}
+export declare function createToneGenerator(options?: ToneOptions): ToneGenerator;
+export declare const tone: ToneGenerator;
+export declare function parseToneFrequency(noteOrFrequency: string | number): number;
+export declare function noteToFrequency(noteName: string): number;
+export declare function requireToneDuration(duration: number): number;
+export declare function normalizeWaveform(waveform: WaveformInput): Waveform;

package/dist/touch-controls.d.ts

@@ -0,0 +1,24 @@
+import type { InputDispatcher } from "./events.js";
+export type TouchButton = "up" | "down" | "left" | "right" | "a" | "b" | "start" | "select";
+export type TouchControlsOptions = Partial<Record<TouchButton, number>> & {
+    /** Auto shows controls on devices with touch input; always also shows them on desktop. */
+    readonly show?: "auto" | "always";
+};
+export type TouchControlsConfig = boolean | TouchControlsOptions;
+export type TouchControlsSettings = {
+    readonly show: "auto" | "always";
+    readonly buttons: ReadonlyArray<readonly [TouchButton, number]>;
+};
+export declare function normalizeTouchControls(value: unknown): TouchControlsSettings | null;
+/**
+ * Mount a responsive control dock at the bottom of the game's available
+ * space. The canvas is fitted by its logical `screen` size, since density
+ * multiplies its pixel size.
+ */
+export declare function mountTouchControls(canvas: HTMLCanvasElement, settings: TouchControlsSettings | null, dispatcher: InputDispatcher, invoke: (callback: () => void) => void, screen?: {
+    readonly width: number;
+    readonly height: number;
+}): {
+    reset(): void;
+    detach(): void;
+};

package/dist/touch-pointer.d.ts

@@ -0,0 +1,11 @@
+import type { InputDispatcher } from "./events.js";
+type PointerTarget = Parameters<InputDispatcher["handleMouseDown"]>[1];
+/**
+ * Touch and pen use the existing mouse hooks, with one canvas pointer at a
+ * time. Positions map onto `target`, which reports the logical screen size.
+ */
+export declare function attachTouchPointer(canvas: HTMLCanvasElement, dispatcher: InputDispatcher, invoke: (callback: () => void) => void, target?: PointerTarget): {
+    reset(): void;
+    detach(): void;
+};
+export {};