js-game-zero 0.0.0-stage → 0.4.0

package/dist/rendering.d.ts

@@ -0,0 +1,216 @@
+import { type AssetLoader, type SurfaceLike } from "./assets.js";
+import { type Color } from "./color.js";
+import { ZRect, type Point, type RectLike } from "./geometry.js";
+export { normalizeColor } from "./color.js";
+export type { Color } from "./color.js";
+export type CanvasLike = {
+    readonly width: number;
+    readonly height: number;
+    getContext?: (contextId: "2d") => CanvasRenderingContext2D | null;
+};
+export type ScreenOptions = {
+    readonly imageLoader?: Pick<AssetLoader<SurfaceLike>, "load" | "get">;
+};
+export type TextAlignOption = "left" | "center" | "right";
+export type TextAnchor = "topLeft" | "topRight" | "bottomLeft" | "bottomRight" | "midTop" | "midLeft" | "midRight" | "midBottom" | "center" | readonly [number | HorizontalAnchor, number | VerticalAnchor];
+export type HorizontalAnchor = "left" | "center" | "middle" | "right";
+export type VerticalAnchor = "top" | "center" | "middle" | "bottom";
+export type TextOptions = {
+    readonly fontname?: string;
+    readonly sysfontname?: string;
+    readonly fontsize?: number;
+    /** Same as `fontsize`. */
+    readonly size?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly color?: Color;
+    readonly background?: Color;
+    readonly pos?: Point;
+    readonly topLeft?: Point;
+    readonly topRight?: Point;
+    readonly bottomLeft?: Point;
+    readonly bottomRight?: Point;
+    readonly midTop?: Point;
+    readonly midLeft?: Point;
+    readonly midRight?: Point;
+    readonly midBottom?: Point;
+    readonly center?: Point;
+    readonly top?: number;
+    readonly left?: number;
+    readonly bottom?: number;
+    readonly right?: number;
+    readonly centerX?: number;
+    readonly centerY?: number;
+    readonly width?: number;
+    readonly widthem?: number;
+    readonly lineheight?: number;
+    readonly align?: TextAlignOption;
+    readonly strip?: boolean;
+    readonly owidth?: number;
+    /** Same as `owidth`. */
+    readonly outline?: number;
+    readonly ocolor?: Color;
+    /** Same as `ocolor`. */
+    readonly outlineColor?: Color;
+    readonly shadow?: number | Point;
+    readonly scolor?: Color;
+    /** Same as `scolor`. */
+    readonly shadowColor?: Color;
+    readonly gcolor?: Color;
+    /** Same as `gcolor`. */
+    readonly gradientColor?: Color;
+    readonly alpha?: number;
+    readonly anchor?: TextAnchor;
+    readonly angle?: number;
+};
+export type TextboxOptions = Omit<TextOptions, TextPositionKey | "width" | "widthem" | "top" | "left" | "bottom" | "right" | "centerX" | "centerY"> & {
+    readonly minFontsize?: number;
+    /** Same as `minFontsize`. */
+    readonly minSize?: number;
+};
+/**
+ * `screen.draw.text` takes its options either third, after a position, or
+ * second, in place of one: `text("Hi", [10, 10], { size: 20 })` and
+ * `text("Hi", { center: [160, 90], size: 20 })` both work.
+ */
+export type DrawText = {
+    (text: string, options?: TextOptions): void;
+    (text: string, pos: Point | undefined, options?: TextOptions): void;
+};
+/** How big `screen.measureText` finds text, as `screen.draw.text` would draw it. */
+export type TextSize = {
+    /** Its widest line's width. */
+    readonly width: number;
+    /** Its lines' height together: as many lines as it has, each `lineheight` tall. */
+    readonly height: number;
+    /** The lines it breaks into: at each newline, and where a `width` wraps it. */
+    readonly lines: readonly string[];
+};
+export type TextLayout = {
+    readonly lines: readonly string[];
+    readonly font: string;
+    readonly fontSize: number;
+    readonly lineHeight: number;
+    readonly boxWidth: number;
+    readonly boxHeight: number;
+    readonly textWidth: number;
+    readonly align: TextAlignOption;
+    readonly topLeft: Point;
+    readonly anchorOffset: Point;
+    readonly alpha: number;
+};
+type TextPositionKey = "pos" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight" | "midTop" | "midLeft" | "midRight" | "midBottom" | "center";
+/**
+ * Sizes the screen to `width` × `height` logical pixels with `density`
+ * canvas pixels each, and scales the context so every drawing call keeps
+ * working in logical pixels. A density change keeps what's on the canvas,
+ * rescaled; a new size starts blank, as setting a canvas's size does.
+ */
+export declare function resizeScreen(screen: Screen, width: number, height: number, density?: number): void;
+/**
+ * Restores the density scale if something reset the canvas since the last
+ * frame. Code outside the runtime that sets `canvas.width`/`height` means
+ * a logical size, so the screen adopts it at the same density.
+ */
+export declare function syncScreen(screen: Screen): void;
+/** A value a drawn thing reports, as JSON. */
+type DrawnValue = string | number | boolean | readonly number[];
+/**
+ * One thing a frame drew, as a host reads it through the inspector's
+ * `$drawn`: its kind (`fill`, `image`, `actor`, `circle`, `rect`, `polygon`,
+ * `line`, `text`, `clear`), and what it is and where, as the game gave them.
+ */
+export type DrawnThing = {
+    readonly kind: string;
+    readonly [key: string]: DrawnValue;
+};
+/** Starts recording what `screen` draws, afresh: the runtime calls it before each `draw()`. */
+export declare function beginDrawn(screen: Screen): void;
+/** What `screen`'s last `draw()` drew, in order; empty before its first. */
+export declare function drawnOn(screen: Screen): readonly DrawnThing[];
+/** Records one thing drawn, when the screen is recording. */
+export declare function recordDrawn(screen: Screen, thing: DrawnThing): void;
+export declare class Screen {
+    readonly canvas: CanvasLike;
+    readonly context: CanvasRenderingContext2D;
+    readonly imageLoader: Pick<AssetLoader<SurfaceLike>, "load" | "get">;
+    readonly draw: {
+        line: (start: Point, end: Point, color: Color, width?: number) => void;
+        circle: (pos: Point, radius: number, color: Color, width?: number) => void;
+        filledCircle: (pos: Point, radius: number, color: Color) => void;
+        polygon: (points: Point[], color: Color, width?: number) => void;
+        filledPolygon: (points: Point[], color: Color) => void;
+        rect: (rect: RectLike, color: Color, width?: number) => void;
+        filledRect: (rect: RectLike, color: Color) => void;
+        /** Its corners are rounded `radius` round, at most half its shorter side. */
+        roundedRect: (rect: RectLike, radius: number, color: Color, width?: number) => void;
+        filledRoundedRect: (rect: RectLike, radius: number, color: Color) => void;
+        text: DrawText;
+        textbox: (text: string, rect: RectLike, options?: TextboxOptions) => void;
+        /** Same as `screen.blit`: draws an image with its top-left at `pos`. */
+        image: (image: string | SurfaceLike, pos: Point | RectLike) => Promise<void> | void;
+    };
+    constructor(canvas: CanvasLike, context?: CanvasRenderingContext2D | null, options?: ScreenOptions);
+    /** The screen's width in logical pixels: the game's `WIDTH`. */
+    get width(): number;
+    /** The screen's height in logical pixels: the game's `HEIGHT`. */
+    get height(): number;
+    /** Canvas pixels per logical pixel along each side. */
+    get density(): number;
+    bounds(): ZRect;
+    clear(): void;
+    fill(color: Color, gcolor?: Color): void;
+    blit(image: string | SurfaceLike, pos: Point | RectLike): Promise<void> | void;
+    /**
+     * The short forms take positions as separate numbers rather than `[x, y]`
+     * lists, fill their shapes, and default to white, so
+     * `screen.circle(200, 150, 25, "gold")` fits a phone-width line where
+     * `screen.draw.filledCircle([200, 150], 25, "gold")` doesn't. The
+     * outline versions stay under `screen.draw`.
+     */
+    circle(x: number, y: number, radius: number, color?: Color): void;
+    /** A filled rectangle whose top-left corner is at `x, y`. */
+    rect(x: number, y: number, width: number, height: number, color?: Color): void;
+    /**
+     * A filled rectangle like `screen.rect`'s, with its corners rounded
+     * `radius` round. The radius comes before the color, as a circle's does.
+     */
+    roundedRect(x: number, y: number, width: number, height: number, radius: number, color?: Color): void;
+    triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, color?: Color): void;
+    line(x1: number, y1: number, x2: number, y2: number, color?: Color, width?: number): void;
+    /**
+     * Text whose top-left corner is at `x, y`, `size` pixels tall, so a score
+     * fits one short line: `screen.text("Score: " + score, 20, 30)`. A number
+     * is drawn as it reads. Placing by its center or any other option stays
+     * under `screen.draw.text`.
+     */
+    text(text: string | number, x: number, y: number, color?: Color, size?: number): void;
+    /**
+     * How big `screen.draw.text` would draw `text`, measured the way it lays
+     * it out: its widest line's width, its lines' height together, and the
+     * lines. It takes what `screen.draw.text` takes, so a label is measured
+     * with the arguments it's drawn with; where it goes doesn't change its
+     * size. It draws nothing.
+     */
+    measureText(text: string | number, options?: TextOptions): TextSize;
+    measureText(text: string | number, pos: Point | undefined, options?: TextOptions): TextSize;
+    private drawSurface;
+    private drawLine;
+    private drawCircle;
+    private drawPolygon;
+    private drawRect;
+    /** `call` is how the method that drew it is called, for its errors. */
+    private drawRoundedRect;
+    private drawText;
+    private drawTextbox;
+}
+export declare function setScreen(screen: Screen | null): Screen | null;
+export declare function getScreen(): Screen;
+export declare const screen: Screen;
+export declare function layoutText(context: CanvasRenderingContext2D, text: string, pos: Point | undefined, options?: TextOptions): TextLayout;
+export declare function fitTextboxFontSize(context: CanvasRenderingContext2D, text: string, rectLike: RectLike, options?: TextboxOptions): {
+    fontSize: number;
+    lineHeight: number;
+    lines: readonly string[];
+};

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;