js-game-zero 0.0.0-stage → 0.4.0

package/dist/node.d.ts

@@ -0,0 +1,14 @@
+import { type StorageAdapter } from "./storage.js";
+export type SandboxFileStorageAdapterOptions = {
+    readonly projectRoot: string;
+    readonly path?: string;
+    readonly readText?: (path: string) => Promise<string | null> | string | null;
+    readonly writeText?: (path: string, text: string) => Promise<void> | void;
+};
+/**
+ * Creates a Node.js filesystem-backed adapter for a sandbox project.
+ *
+ * This lives behind the `js-game-zero/node` entry point so browser
+ * consumers never load or bundle Node built-ins.
+ */
+export declare function createSandboxFileStorageAdapter(options: SandboxFileStorageAdapterOptions): StorageAdapter;

package/dist/node.js

@@ -0,0 +1,145 @@
+/*!
+ * js-game-zero 0.4.0
+ * https://github.com/Leaf-Learning/js-game-zero
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Taha Rafiq
+ * Copyright (c) 2001 Robert Penner (easing equations)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// packages/js-game-zero/src/storage-path.ts
+function normalizeStoragePath(path) {
+  if (path.length === 0 || path.includes("\\") || path.startsWith("/")) {
+    throw new TypeError("storage path must be a relative forward-slash path.");
+  }
+  const segments = path.split("/");
+  if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+    throw new TypeError("storage path cannot include empty or traversal segments.");
+  }
+  return segments.join("/");
+}
+function normalizeSandboxStoragePath(path) {
+  if (/^(\/|[a-z]:[\\/])/i.test(path)) {
+    throw new TypeError("sandbox storage path must be relative.");
+  }
+  return normalizeStoragePath(path);
+}
+function sandboxStoragePath(projectRoot, safePath) {
+  if (!projectRoot || projectRoot.includes("\x00")) {
+    throw new TypeError("projectRoot must be a non-empty filesystem path.");
+  }
+  return `${projectRoot.replace(/[\\/]+$/, "")}/${safePath}`;
+}
+
+// packages/js-game-zero/src/node.ts
+function createSandboxFileStorageAdapter(options) {
+  const safePath = normalizeSandboxStoragePath(options.path ?? "storage.json");
+  const path = sandboxStoragePath(options.projectRoot, safePath);
+  return {
+    path,
+    async load() {
+      if (options.readText)
+        return options.readText(path);
+      return readSandboxText(options.projectRoot, safePath);
+    },
+    async save(text) {
+      if (options.writeText) {
+        await options.writeText(path, text);
+        return;
+      }
+      await writeSandboxText(options.projectRoot, safePath, text);
+    }
+  };
+}
+async function readSandboxText(projectRoot, safePath) {
+  const resolved = await resolveSandboxFilePath(projectRoot, safePath, false);
+  if (!resolved)
+    return null;
+  try {
+    return await resolved.fs.readFile(resolved.targetPath, "utf8");
+  } catch (error) {
+    if (isMissingFileError(error))
+      return null;
+    throw error;
+  }
+}
+async function writeSandboxText(projectRoot, safePath, text) {
+  const resolved = await resolveSandboxFilePath(projectRoot, safePath, true);
+  if (!resolved)
+    return;
+  const tempPath = resolved.path.join(resolved.parentPath, `.jgz-storage-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`);
+  try {
+    await resolved.fs.writeFile(tempPath, text, "utf8");
+    await resolved.fs.rename(tempPath, resolved.targetPath);
+  } catch (error) {
+    await resolved.fs.rm(tempPath, { force: true });
+    throw error;
+  }
+}
+async function resolveSandboxFilePath(projectRoot, safePath, createParent) {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  const rootPath = path.resolve(projectRoot);
+  const realRoot = await fs.realpath(rootPath);
+  const lexicalTarget = path.join(realRoot, safePath);
+  const lexicalParent = path.dirname(lexicalTarget);
+  if (createParent) {
+    await fs.mkdir(lexicalParent, { recursive: true });
+  }
+  let parentPath;
+  try {
+    parentPath = await fs.realpath(lexicalParent);
+  } catch (error) {
+    if (!createParent && isMissingFileError(error))
+      return null;
+    throw error;
+  }
+  if (!isPathInside(parentPath, realRoot, path)) {
+    throw new TypeError("sandbox storage path must stay inside project root.");
+  }
+  const targetPath = path.join(parentPath, path.basename(lexicalTarget));
+  if (!isPathInside(targetPath, realRoot, path)) {
+    throw new TypeError("sandbox storage path must stay inside project root.");
+  }
+  try {
+    const stat = await fs.lstat(targetPath);
+    if (stat.isSymbolicLink()) {
+      throw new TypeError("sandbox storage path must not be a symbolic link.");
+    }
+  } catch (error) {
+    if (!isMissingFileError(error))
+      throw error;
+  }
+  return { fs, path, parentPath, targetPath };
+}
+function isPathInside(targetPath, rootPath, path) {
+  const relative = path.relative(rootPath, targetPath);
+  return relative === "" || relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+export {
+  createSandboxFileStorageAdapter
+};

package/dist/pixel-density.d.ts

@@ -0,0 +1,23 @@
+import type { RuntimeDiagnostic } from "./runtime-contracts.js";
+/** The highest density the device's pixel ratio picks by itself. */
+export declare const MAX_AUTO_PIXEL_DENSITY = 3;
+/**
+ * The most pixels a canvas may hold. iOS Safari leaves a bigger canvas
+ * blank, so density comes down until the canvas fits.
+ */
+export declare const MAX_CANVAS_PIXELS: number;
+type DensityCanvas = {
+    readonly ownerDocument?: {
+        readonly defaultView?: Window | null;
+    } | null;
+};
+/** The device's pixel ratio where the canvas is shown, or 1 outside a browser. */
+export declare function devicePixelRatioOf(canvas: DensityCanvas): number;
+/**
+ * Canvas pixels per logical pixel. With no `PIXEL_DENSITY`, it's the
+ * device's pixel ratio, between 1 and `MAX_AUTO_PIXEL_DENSITY`. Any density
+ * comes down so the canvas stays within `MAX_CANVAS_PIXELS`, but never below
+ * 1 unless the game asked for less.
+ */
+export declare function resolvePixelDensity(value: unknown, width: number, height: number, deviceRatio: number, emit: (diagnostic: RuntimeDiagnostic) => void): number;
+export {};

package/dist/random.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Repeatable randomness for a run that asks for it (`run(source, { seed })`),
+ * and the random source the helpers read while a run is active. The CLI's
+ * `--seed` passes its seed to the same `run()` option, so one seed gives the
+ * same sequence in the CLI and in a host page.
+ */
+export type RandomSource = () => number;
+/** A seed a host can pass: a string, or a number read as its digits. */
+export type RandomSeed = string | number;
+/**
+ * The 32-bit state for a seed. Up to nine plain digits are used as the number
+ * they spell, so a seed chosen for one harness reproduces the same sequence in
+ * another; anything else is hashed (FNV-1a). A number is read as `String(n)`,
+ * so `42` and `"42"` are the same seed.
+ */
+export declare function hashSeed(seed: RandomSeed): number;
+/**
+ * A repeatable stand-in for `Math.random`: numbers from 0 up to 1, the same
+ * sequence for the same seed (Mulberry32 over `hashSeed(seed)`).
+ */
+export declare function createSeededRandom(seed: RandomSeed): RandomSource;
+/**
+ * A `Math` for one game's scope whose `random` is that game's source. Every
+ * other member is the real `Math`'s, so `Math.floor` and `Math.PI` read as
+ * usual, and the page's own `Math.random` is untouched.
+ */
+export declare function mathWithRandom(random: RandomSource): Math;
+/** Installs the running game's random source; returns the previous one. */
+export declare function setActiveRandom(random: RandomSource | null): RandomSource | null;
+/** The active run's random source, or `Math.random` outside a run. */
+export declare function random(): number;

package/dist/reference/actor.md

@@ -0,0 +1,197 @@
+# Actor
+
+`Actor` bundles an image, a position, and a hitbox rectangle into one object
+you can move, rotate, fade, and collide-test. It's the class you'll use for
+players, enemies, bullets — anything that moves around the screen.
+
+```ts
+new Actor(image: string, pos?: [number, number] | ActorOptions, options?: ActorOptions): Actor
+```
+
+```js
+let player = new Actor("player.svg", { center: [160, 90] });
+
+function draw() {
+  screen.fill("#111827");
+  player.draw();
+}
+```
+
+`image` is an asset name resolved under `images/` (see
+[`docs/reference/loaders.md`](loaders.md)). In `jgz`, the sandbox, and a page
+that decodes its images first with
+[`loadImages`](loaders.md#assets-without-a-server), the image is ready
+before your code runs, so `player.width` and an edge position like
+`midBottom` are right from the first line. Anywhere else, loading starts
+when the Actor is made: until it finishes, the Actor has no size and `draw()`
+is a no-op, and the runtime holds the first frame until images touched while
+your script starts up have loaded. `player.ready()` returns a promise for
+the image; the top level of a zero-boilerplate game can't `await`, so use
+`player.ready().then(() => …)` there.
+
+## Positioning
+
+Give **at most one** position source — either the second constructor
+argument as a `[x, y]` point, or exactly one of these option keys:
+`pos`, `topLeft`, `topRight`, `bottomLeft`, `bottomRight`, `midTop`,
+`midLeft`, `midRight`, `midBottom`, `center`. Passing more than one throws a
+`TypeError`. With no position at all, the actor starts at `topLeft: [0, 0]`.
+
+```js
+new Actor("player.svg", [100, 50]); // shorthand for { pos: [100, 50] }
+new Actor("player.svg", { midBottom: [160, 180] }); // stands on the floor at y=180
+```
+
+`anchor` controls which point of the image maps to the position — it
+defaults to `["center", "center"]`, so by default `player.x`/`player.y` (and
+`pos`) refer to the image's center, matching pgzero. Each axis accepts
+`"left"`/`"center"`/`"right"` (horizontal) or `"top"`/`"center"`/`"bottom"`
+(vertical), or a literal pixel offset number.
+
+```js
+new Actor("player.svg", { topLeft: [0, 0], anchor: ["left", "top"] });
+```
+
+## Properties
+
+| Property                                                                                                   | Type           | Notes                                                                                                                   |
+| ---------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `image`                                                                                                    | `string`       | Reassigning starts loading the new image.                                                                               |
+| `pos`, `x`, `y`                                                                                            | point / number | The anchor point's position.                                                                                            |
+| `angle`                                                                                                    | `number`       | Degrees, counterclockwise, around the anchor.                                                                           |
+| `opacity`                                                                                                  | `number`       | `0`–`1`; out-of-range values are clamped, not rejected.                                                                 |
+| `anchor`                                                                                                   | `[h, v]`       | See above.                                                                                                              |
+| `scale`                                                                                                    | `number`       | Drawn size as a multiple of the image's native size; default `1`.                                                       |
+| `width`, `height`                                                                                          | `number`       | The current (possibly rotated) bounding box size. Setting one resizes the sprite to that size, keeping its proportions. |
+| `topLeft`, `topRight`, `bottomLeft`, `bottomRight`, `midTop`, `midLeft`, `midRight`, `midBottom`, `center` | point          | Read or move the actor by any edge/corner of its bounding box.                                                          |
+| `left`, `top`, `right`, `bottom`                                                                           | `number`       | Same idea, one axis at a time.                                                                                          |
+
+Setting `angle` rotates the sprite around its anchor and changes the
+axis-aligned bounding box returned by `rect()`/`width`/`height` — useful when
+you collide-test a rotated actor, since the hitbox grows to cover the
+rotated silhouette. The edge and corner properties read and move that same
+box, so `ship.left = 0` puts a rotated ship's leftmost point at the left of
+the screen.
+
+```js
+function update(dt) {
+  if (keyboard.right) player.x += 120 * dt;
+  player.angle += 90 * dt; // spin
+}
+```
+
+## Sizing
+
+Sprites draw at their native pixel size by default. To fit a picture to
+your game, give it a `scale`, or a `width` or `height` (at most one of the
+three; the other axis follows so the picture keeps its proportions):
+
+```js
+let cow = new Actor("cow.png", { midBottom: [240, 620], width: 80 }); // 80px wide
+let car = new Actor("car.png", { scale: 3 }); // three times its native size
+cow.height = 60; // resize later; the midBottom stays on the floor
+```
+
+The hitbox, `rect()`, and every edge/corner property follow the drawn size,
+and the position you gave (a `midBottom` on the floor, a `center`) stays
+put when the size changes. A size set before the image has loaded is
+applied as soon as it arrives. `inflateIp` still grows only the hitbox,
+never the picture.
+
+## Methods
+
+- `rect(): Rect` — the actor's current bounding rectangle (see
+  [`docs/reference/rect.md`](rect.md)); useful for custom drawing or manual
+  collision math.
+- `draw(screen?)` — draws the actor at its current position, angle, and
+  opacity. Normally called with no arguments inside `draw()`.
+- `ready(): Promise<SurfaceLike>` — resolves once the current image has
+  loaded.
+- `unloadImage()` — releases the cached image (advanced; rarely needed).
+- `angleTo(target)` / `distanceTo(target)` — `target` is another `Actor`
+  or a `[x, y]` point. `angleTo` returns degrees, `distanceTo` returns
+  pixels.
+- `move(x, y)` / `moveIp(x, y)` — like `Rect.move`/`moveIp`; `move` returns
+  a new `Rect`, `moveIp` moves the actor itself.
+- `inflate(x, y)` / `inflateIp(x, y)` — grow/shrink the hitbox around its
+  center; the picture keeps its size and place.
+- `touches(target)` — `true` when the actor overlaps `target`, which can be
+  another `Actor`, a `Rect`, a `[left, top, width, height]` tuple, or an
+  `[x, y]` point such as a click position.
+- `collidePoint(point)`, `collideRect(other)`, `collideList(others)`,
+  `collideListAll(others)`, `contains(other)` — Pygame Zero's collision
+  tests, delegating to the actor's `rect()`. `other` can be a `Rect`, a
+  plain `[left, top, width, height]` tuple, or another `Actor`.
+- `clampIp(area)` — moves the actor (without resizing it) so its bounding
+  box fits inside `area`. `player.clampIp(screen.bounds())` keeps the
+  player on screen.
+- `clamp(other)`, `clip(other)`, `union(other)`, `unionAll(others)`,
+  `fit(other)` — geometry helpers, same semantics as the matching `Rect`
+  methods, again accepting `Actor`s directly. They return a new `Rect` and
+  leave the actor where it is.
+
+```js
+function update(dt) {
+  if (keyboard.right) player.x += 120 * dt;
+  player.clampIp(screen.bounds()); // stop at the edges of the screen
+}
+
+function onMouseDown(pos) {
+  if (player.touches(pos)) console.log("clicked the player");
+}
+
+if (player.touches(enemy)) loseLife();
+```
+
+## Animating an Actor
+
+`Actor` is a plain object as far as `animate()` is concerned — any numeric
+property (`x`, `y`, `angle`, `opacity`, ...) can be animated:
+
+```js
+animate(player, { x: 300, duration: 0.6, tween: "bounceEnd" });
+```
+
+See [`docs/reference/clock.md`](clock.md#animation) for the full tween list.
+
+## Flip-book animation: `images` and `fps`
+
+Give an actor a list of pictures and it flips through them by itself, like a
+flip book — for walking legs, spinning coins, or explosions:
+
+```js
+let coin = new Actor("coin_0", {
+  center: [200, 120],
+  images: ["coin_0", "coin_1", "coin_2", "coin_3"],
+  fps: 8, // pictures per second
+});
+
+function draw() {
+  coin.draw();
+}
+```
+
+| Property   | Meaning                                                                               |
+| ---------- | ------------------------------------------------------------------------------------- |
+| `images`   | The pictures to show, in order. Setting it starts again from the first; `null` stops. |
+| `fps`      | Pictures per second (default `10`). Changing it keeps the current picture.            |
+| `loop`     | Start over after the last picture (default `true`). `false` stops on the last.        |
+| `frame`    | Which picture is showing: `0` for the first.                                          |
+| `finished` | `true` once a `loop: false` animation has shown its last picture.                     |
+
+The pictures change on the game's own clock, so they pause when the game
+does and keep the same speed at any frame rate. All of them start loading
+as soon as you set `images`. For a one-shot effect, remove the actor once
+it's `finished`:
+
+```js
+explosions.push(
+  new Actor("boom_0", {
+    center: pos,
+    images: ["boom_0", "boom_1", "boom_2"],
+    fps: 16,
+    loop: false,
+  }),
+);
+explosions = explosions.filter((explosion) => !explosion.finished);
+```

package/dist/reference/audio.md

@@ -0,0 +1,128 @@
+# Sounds, Music, And Tone
+
+Browsers block audio from playing until the page has seen a user gesture
+(a click or key press). Every audio API below works fine technically before
+that gesture, but nothing will actually be _audible_ until the player has
+interacted with the page at least once — trigger your first sound from an
+`onMouseDown` or `onKeyDown` handler, not from top-level code or the
+first `draw()` frame.
+
+## Sound effects: `sounds`
+
+`sounds.<name>` resolves an asset under `sounds/` (see
+[`docs/reference/loaders.md`](loaders.md)) the first time you touch it.
+
+```js
+function onMouseDown() {
+  sounds.tap.play();
+}
+```
+
+### `.play(loops = 0)`
+
+Plays the sound. `loops` follows pygame's convention: it counts the
+_extra_ plays after the first. `0` (the default) plays it once, `2` plays it
+three times in total, and `-1` loops forever until `.stop()` is called.
+
+Calling `.play()` again while a previous playback is still going **does not
+cut it off** — sounds overlap, just like pygame's channel mixing, so rapid
+repeated triggers (e.g. a machine-gun sound effect) layer instead of
+stuttering.
+
+### `.loop()`
+
+Plays the sound over and over until `.stop()` — the same as `.play(-1)`.
+Handy for engine hums and background ambience:
+
+```js
+sounds.engine.loop();
+// later
+sounds.engine.stop();
+```
+
+### `.stop()`
+
+Stops every currently-overlapping playback of this sound.
+
+### `.getLength()`
+
+Duration in seconds (`0` if not yet known).
+
+### `.setVolume(volume)` / `.getVolume()`
+
+Per-sound volume, `0`–`1`.
+
+## Music: `music`
+
+Unlike `sounds`, `music` plays **one track at a time** — starting a new
+track always stops whatever was playing.
+
+```js
+music.play("theme.ogg"); // loops forever
+```
+
+| Method                                          | Behavior                                                                                                                                 |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `music.play(name)`                              | Stops the current track, plays `name` on a loop.                                                                                         |
+| `music.playOnce(name)`                          | Stops the current track, plays `name` once.                                                                                              |
+| `music.queue(name)`                             | Appends `name` to the queue; starts immediately (as a one-shot) if nothing is currently playing. Queued tracks play in order, each once. |
+| `music.stop()`                                  | Stops playback and clears the queue.                                                                                                     |
+| `music.pause()` / `music.unpause()`             | Pause and resume without losing position.                                                                                                |
+| `music.rewind()`                                | Restarts the current track from the beginning without stopping it.                                                                       |
+| `music.fadeOut(seconds)`                        | Fades the volume to zero over `seconds`, then stops. `0` stops immediately.                                                              |
+| `music.setVolume(volume)` / `music.getVolume()` | `0`–`1`.                                                                                                                                 |
+| `music.position`                                | Seconds into the current track (`0` if nothing is loaded). Set it to jump: `music.position = 30`.                                        |
+| `music.getPos()`                                | **Milliseconds** the current track has been playing, or `-1` if nothing is loaded (Pygame's unit).                                       |
+| `music.setPos(seconds)`                         | Seeks the current track to a position, in **seconds**. To save and restore a spot, use `music.position` for both.                        |
+| `music.isPlaying()`                             | `true` if a track is currently playing and not paused.                                                                                   |
+
+`onMusicEnd()` (or a callback given to `music.setOnMusicEnd(callback)`)
+fires once the queue is exhausted and nothing is left to play.
+
+## Generated tones: `tone`
+
+`tone` synthesizes a short beep with the Web Audio API — no sound asset file
+needed, useful for quick feedback sounds (menu blips, jumps, coin pickups).
+
+```js
+function onMouseDown() {
+  tone.play("A4", 0.2);
+}
+```
+
+### `tone.play(noteOrFrequency, duration = 1, options?)`
+
+- `noteOrFrequency` — either a note name like `"A4"`, `"C#5"`, or `"Bb3"`
+  (letter, optional `#`/`b`, octave number, using standard scientific pitch
+  notation with A4 = 440Hz), or a positive number of Hz.
+- `duration` — seconds, **must be greater than `0` and at most `4`**; longer
+  values throw a `RangeError`. Generated tones are meant for short blips,
+  not background music — use `music` for that.
+- `options.waveform` — `"sine"` (default), `"square"`, `"sawtooth"`,
+  `"triangle"`, or the pgzero-style short aliases `"sin"` (→ `"sine"`) and
+  `"saw"` (→ `"sawtooth"`).
+- `options.volume` — `0`–`1`, defaults to `0.8` (matching pgzero's `tone`
+  module default, which is louder than most other defaults in this API).
+
+Returns a `Promise` that resolves once the tone has been scheduled.
+
+### `tone.create(noteOrFrequency, duration = 1, options?)`
+
+Builds a reusable tone spec without playing it yet — call `.play(options?)`
+on the result whenever you want to trigger it, optionally overriding
+`waveform`/`volume` for that one playback.
+
+```js
+const jumpTone = tone.create("E5", 0.12, { waveform: "square" });
+
+function onKeyDown(key) {
+  if (key === keys.SPACE) jumpTone.play();
+}
+```
+
+### `tone.isUnlocked()`
+
+Returns whether the browser has granted audio playback yet — it flips to
+`true` the first time a sound or tone actually plays after a user gesture.
+This unlock state is shared across `sounds` and `tone`, so a single tap
+un-gates both.