js-game-zero 0.0.0-stage → 0.4.0

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 {};

package/dist/util.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Internal cross-cutting utilities shared between core modules. This module
+ * is intentionally NOT re-exported from `index.ts`, so none of these helpers
+ * become part of the public package API. The only geometry dependency is a
+ * type-only import, so there is no runtime import cycle.
+ */
+import type { Point } from "./geometry.js";
+/** Standard Levenshtein edit distance between two strings. */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Optimal string alignment distance: Levenshtein where swapping two adjacent
+ * characters (`widht` for `width`) costs one edit instead of two.
+ */
+export declare function editDistance(a: string, b: string): number;
+/** Case- and underscore-insensitive form, so `filled_circle` meets `filledCircle`. */
+export declare function looseName(name: string): string;
+/**
+ * The candidate `name` most plausibly misspells, if any. Capitals and
+ * underscores don't count, so another spelling of a name (`filled_circle`,
+ * `on_key_down`, `Screen`) is always matched. Short names get one edit of
+ * slack and longer ones two (so `drow` and `onKeyDwon` match while `row` and
+ * `dow` do not), a transposition counts as one edit, and a name that
+ * contains a candidate whole (`redraw`, `updates`) is taken as deliberately
+ * derived from it rather than mistyped.
+ */
+export declare function closestName(name: string, candidates: Iterable<string>): string | undefined;
+/**
+ * A value as an error message should show it: strings quoted, lists as
+ * lists, and numbers as written (`NaN`, not JSON's `null`).
+ */
+export declare function describeValue(value: unknown): string;
+/** ` Did you mean NAME?` for a likely misspelling, or an empty string. */
+export declare function didYouMean(name: string, candidates: Iterable<string>): string;
+/**
+ * Throws a TypeError naming the first key of `options` that `allowed` does
+ * not contain, with a suggestion when the key looks like a typo — so a
+ * misspelled option fails loudly instead of being silently ignored.
+ */
+export declare function rejectUnknownOptions(options: object, allowed: ReadonlySet<string>, label: string): void;
+/** True when `value` is a thenable (a Promise or Promise-like object). */
+export declare function isPromiseLike<T>(value: unknown): value is PromiseLike<T>;
+export declare function clamp(value: number, minimum: number, maximum: number): number;
+export declare function isFiniteNumber(value: unknown): value is number;
+export declare function requireFiniteNumber(value: unknown, label: string): number;
+export declare function isPair(value: unknown): value is readonly [number, number];
+/**
+ * Validates that `value` is a `[number, number]` tuple of finite numbers,
+ * returning a fresh mutable `Point`. Shared by geometry/actor/assets/
+ * rendering, which each used to define an identical private copy.
+ */
+export declare function requirePoint(value: unknown, label: string): Point;
+export declare function horizontalAnchorOffset(value: number | "left" | "center" | "middle" | "right", width: number): number;
+export declare function verticalAnchorOffset(value: number | "top" | "center" | "middle" | "bottom", height: number): number;
+/**
+ * The compound Rect-anchor position keys (`topLeft`…`center`), shared by the
+ * actor, assets, and rendering modules for validating position keywords.
+ */
+export declare const rectPositionKeys: readonly ["topLeft", "topRight", "bottomLeft", "bottomRight", "midTop", "midLeft", "midRight", "midBottom", "center"];
+/** Recognized image asset file extensions. */
+export declare const imageExtensions: string[];
+/** Recognized sound asset file extensions. */
+export declare const soundExtensions: string[];

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "js-game-zero",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "A beginner-friendly framework for browser games in the spirit of Pygame Zero: set WIDTH and HEIGHT, write draw(), and play. Actors, drawing, input, sound, animation and storage, with a script-tag build.",
+  "keywords": [
+    "game",
+    "gamedev",
+    "canvas",
+    "education",
+    "beginner",
+    "pygame-zero"
+  ],
+  "author": "Taha Rafiq",
+  "homepage": "https://github.com/Leaf-Learning/js-game-zero#readme",
+  "bugs": {
+    "url": "https://github.com/Leaf-Learning/js-game-zero/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Leaf-Learning/js-game-zero.git",
+    "directory": "packages/js-game-zero"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "jsdelivr": "./dist/jgz.js",
+  "unpkg": "./dist/jgz.js",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./dist/jgz.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "import": "./dist/host.js",
+      "default": "./dist/host.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "default": "./dist/node.js"
+    },
+    "./reference": {
+      "types": "./dist/reference/index.d.ts",
+      "import": "./dist/reference/index.js",
+      "default": "./dist/reference/index.js"
+    },
+    "./reference/*.md": "./dist/reference/*.md",
+    "./iife": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/jgz.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "bun ../../scripts/build.ts js-game-zero",
+    "test": "bun test"
+  }
+}