@cosmoledo/gleam 1.0.1 → 1.0.2

package/dist/gleam.js

@@ -37,6 +37,8 @@ var Gleam = (() => {
     Gameloop: () => Gameloop,
     KEYBOARD_KEYS: () => KEYBOARD_KEYS,
     Keyboard: () => Keyboard,
+    MAX_DT_SECONDS: () => MAX_DT_SECONDS,
+    MAX_STEPS_PER_FRAME: () => MAX_STEPS_PER_FRAME,
     Music: () => Music,
     POINTER_KEYS: () => POINTER_KEYS,
     Particle: () => Particle,
@@ -207,6 +209,9 @@ var Gleam = (() => {
 
   // src/core/EventSystem.ts
   var _EventSystem = class _EventSystem {
+    /**
+     * Register a listener for `eventName`. Returns a dispose function — the primary teardown path. Multiple disposers (returned, `once`, `signal.abort`) are idempotent. Use {@link EventSystemOptions} for `once` and `signal` behavior.
+     */
     static addEventListener(eventName, callback, options = {}) {
       if (options.signal?.aborted) {
         return function dispose2() {
@@ -241,6 +246,7 @@ var Gleam = (() => {
       }
       return dispose;
     }
+    /** Synchronously fire `eventName` with the typed payload. Listeners are invoked in registration order; nested dispatches and self-disposing listeners are handled safely. */
     static dispatchEvent(eventName, ...params) {
       const bucket = this.eventListener[eventName];
       if (!bucket) {
@@ -288,21 +294,25 @@ var Gleam = (() => {
   };
   var AudioBase = class {
     constructor(enabled = true) {
+      /** Registered audio elements keyed by name. Subclasses read this; mutate via {@link register}. */
       __publicField(this, "songs", /* @__PURE__ */ new Map());
       __publicField(this, "_enabled");
       __publicField(this, "registered", false);
       this._enabled = enabled;
       EventSystem.addEventListener("gameloopStopped", () => this.stop());
     }
+    /** Whether playback is permitted. Setting to `false` invokes {@link stop} immediately. */
     get enabled() {
       return this._enabled;
     }
+    /** Setting to `false` invokes {@link stop} immediately; subclasses (notably {@link Music}) may re-start playback when flipped back to `true`. */
     set enabled(value) {
       this._enabled = value;
       if (!value) {
         this.stop();
       }
     }
+    /** Load and register one or more audio files. Each entry may be a bare URL string (the file's basename becomes the name) or a {@link RegisterData} object. Per-song volume falls back to `defaultVolume`. **Call once per instance** — throws on a second invocation, on non-finite volume, or on volume outside `[0, 1]`. Load failures are logged to `console.error` but don't throw. */
     register(defaultVolume = 1, ...songs) {
       this.throwOnBadVolume(defaultVolume, "defaultVolume");
       if (this.registered) {
@@ -331,6 +341,7 @@ var Gleam = (() => {
         this.songs.set(song.name, audio);
       });
     }
+    /** Base hook called when {@link enabled} flips to `false` and on `"gameloopStopped"`. The default is a no-op; {@link Sound} and {@link Music} override it to cut playback. Subclass overrides should call `super.stop()`. */
     stop() {
     }
     throwOnBadVolume(volume, name) {
@@ -409,7 +420,7 @@ var Gleam = (() => {
     "ease-in": easeIn,
     "ease-in-out": easeInOut,
     "ease-out": easeOut,
-    "linear": linear
+    linear
   };
 
   // src/utilities/Array.ts
@@ -460,18 +471,24 @@ var Gleam = (() => {
       __publicField(this, "next", null);
       __publicField(this, "fadeCancel", null);
     }
+    /** `true` while a fade is in progress OR the current track is actively playing. */
     get isPlaying() {
       return !!this.fadeCancel || this.current instanceof window.Audio && !this.current.paused;
     }
+    /** Whether music playback is permitted (inherited from {@link AudioBase}). */
     get enabled() {
       return super.enabled;
     }
+    /** Flipping from `false` to `true` while no music is playing auto-starts a fade-in to a random track. */
     set enabled(value) {
       super.enabled = value;
       if (value && !this.isPlaying) {
         this.fade();
       }
     }
+    /**
+     * Cross-fade to `name` (or a random unplayed track when `null`) over `fadeTime` ms. `easing.cur` controls the outgoing track's volume curve, `easing.next` the incoming one. Cancels any in-progress fade. No-op when disabled. Throws on `fadeTime <= 0`, an empty registry, or an unknown `name`. When the new track ends, the next fade fires automatically — call {@link stop} to break the cycle.
+     */
     fade(name = null, fadeTime = 1e3, easing = {
       cur: "ease-in",
       next: "ease-out"
@@ -548,6 +565,7 @@ var Gleam = (() => {
         }
       });
     }
+    /** Stop everything immediately: cancels any in-flight fade, halts current and next tracks, and breaks the auto-cycle chain. Restart via {@link fade} or by flipping {@link enabled}. */
     stop() {
       super.stop();
       this.fadeCancel?.();
@@ -579,6 +597,7 @@ var Gleam = (() => {
       super(...arguments);
       __publicField(this, "currentSounds", []);
     }
+    /** Play the registered sound `name` once. Returns a promise that resolves when playback starts (or immediately if `enabled` is `false`) and rejects on autoplay/permission errors. Throws synchronously if no sounds are registered or `name` is unknown. Each call allocates a clone, so concurrent plays of the same name overlap. */
     play(name) {
       if (this.songs.size === 0) {
         throw new Error("No sounds registered!");
@@ -604,6 +623,7 @@ var Gleam = (() => {
         throw err;
       });
     }
+    /** Stop and forget every currently-playing clone. Also calls the base-class teardown. */
     stop() {
       super.stop();
       this.currentSounds.forEach((audio) => audio.stop());
@@ -763,6 +783,7 @@ var Gleam = (() => {
       __publicField(this, "_alpha", 1);
       this.set(r, g, b, a);
     }
+    /** Parse `#rgb`, `#rgba`, `#rrggbb`, or `#rrggbbaa` (case-insensitive, `#` optional). Throws on any other shape or on non-hex characters. */
     static fromHex(hex) {
       let cleanHex = hex.replace("#", "").toUpperCase();
       if (!/^[0-9A-F]+$/.test(cleanHex)) {
@@ -783,6 +804,7 @@ var Gleam = (() => {
       }
       return new _Color(r, g, b);
     }
+    /** Build from HSL(A). `h` in **degrees** (wraps mod 360), `s`/`l` in percent `[0, 100]`, `a` in `[0, 1]`. The degree convention matches CSS — note that {@link hueRotate} uses radians instead. */
     static fromHSL(h, s, l, a = 1) {
       const hNorm = wrapValue(h, 0, 360) / 360;
       const sNorm = s / 100;
@@ -799,18 +821,23 @@ var Gleam = (() => {
       }
       return new _Color(r * 255, g * 255, b * 255, a);
     }
+    /** Red channel, `[0, 255]`. Read-only; mutate via {@link set} or any chainable transform. */
     get r() {
       return this._r;
     }
+    /** Green channel, `[0, 255]`. Read-only; mutate via {@link set} or any chainable transform. */
     get g() {
       return this._g;
     }
+    /** Blue channel, `[0, 255]`. Read-only; mutate via {@link set} or any chainable transform. */
     get b() {
       return this._b;
     }
+    /** Alpha channel, `[0, 1]`. Read-only; mutate via {@link set} (pass the fourth arg). */
     get alpha() {
       return this._alpha;
     }
+    /** Primary mutator — every other transform on this class routes through it. Clamps `r`/`g`/`b` to `[0, 255]` and `a` to `[0, 1]`; alpha is snapped to exact `0` or `1` when within `approxEqual` tolerance so equality checks stay clean. Returns `this` for chaining. */
     set(r, g, b, a) {
       this._r = clamp(r, 0, 255);
       this._g = clamp(g, 0, 255);
@@ -821,6 +848,7 @@ var Gleam = (() => {
       }
       return this;
     }
+    /** Apply a 3×3 RGB color matrix in row-major order (`m1..m9`). Alpha is unchanged. Used by {@link grayscale}, {@link hueRotate}, {@link saturate}, {@link sepia}. Mutates and returns `this`. */
     applyMatrix(m1, m2, m3, m4, m5, m6, m7, m8, m9) {
       return this.set(
         this.r * m1 + this.g * m2 + this.b * m3,
@@ -828,9 +856,11 @@ var Gleam = (() => {
         this.r * m7 + this.g * m8 + this.b * m9
       );
     }
+    /** Multiply each channel by `factor`. `factor < 1` darkens, `factor > 1` brightens (clamped at 255). Mutates and returns `this`. */
     brightness(factor) {
       return this.set(this.r * factor, this.g * factor, this.b * factor);
     }
+    /** Push each channel away from `127.5` (the midtone) by `factor`. `factor < 1` flattens contrast, `> 1` increases it, `0` collapses every channel to gray. Mutates and returns `this`. */
     contrast(factor) {
       const midtone = 127.5;
       return this.set(
@@ -839,6 +869,7 @@ var Gleam = (() => {
         midtone + (this.b - midtone) * factor
       );
     }
+    /** Desaturate via the standard luminance-preserving matrix. `value` in `[0, 1]`: `0` is a no-op, `1` is full grayscale. Mutates and returns `this`. */
     grayscale(value = 1) {
       const m1 = 0.2126 + 0.7874 * (1 - value);
       const m2 = 0.7152 - 0.7152 * (1 - value);
@@ -851,6 +882,7 @@ var Gleam = (() => {
       const m9 = 0.0722 + 0.9278 * (1 - value);
       return this.applyMatrix(m1, m2, m3, m4, m5, m6, m7, m8, m9);
     }
+    /** Rotate hue by `radians` (use `Math.PI / 2` etc.). Unlike {@link fromHSL}, this takes radians, not degrees. Mutates and returns `this`. */
     hueRotate(radians) {
       const cos = Math.cos(radians);
       const sin = Math.sin(radians);
@@ -865,6 +897,7 @@ var Gleam = (() => {
       const m9 = 0.072 + cos * 0.928 + sin * 0.072;
       return this.applyMatrix(m1, m2, m3, m4, m5, m6, m7, m8, m9);
     }
+    /** Interpolate each channel toward its inverse (`255 - c`). `factor` in `[0, 1]`: `0` is unchanged, `1` is fully inverted. Mutates and returns `this`. */
     invert(factor = 1) {
       return this.set(
         this.r * (1 - factor) + (255 - this.r) * factor,
@@ -872,6 +905,7 @@ var Gleam = (() => {
         this.b * (1 - factor) + (255 - this.b) * factor
       );
     }
+    /** Linear blend toward `other`. `amount` in `[0, 1]`: `0` keeps `this`, `1` becomes `other`. Mixes alpha too. Mutates and returns `this`. */
     mix(other, amount) {
       const inv = 1 - amount;
       return this.set(
@@ -881,6 +915,7 @@ var Gleam = (() => {
         this.alpha * inv + other.alpha * amount
       );
     }
+    /** Round each RGB channel to the nearest integer. Alpha is untouched. Mutates and returns `this`. */
     round() {
       return this.set(
         Math.round(this.r),
@@ -888,6 +923,7 @@ var Gleam = (() => {
         Math.round(this.b)
       );
     }
+    /** Saturation matrix. `value` typically in `[0, 2]`: `0` desaturates to grayscale (same as `grayscale(1)`), `1` is a no-op, `> 1` oversaturates. Mutates and returns `this`. */
     saturate(value = 1) {
       const m1 = 0.213 + 0.787 * value;
       const m2 = 0.715 - 0.715 * value;
@@ -900,6 +936,7 @@ var Gleam = (() => {
       const m9 = 0.072 + 0.928 * value;
       return this.applyMatrix(m1, m2, m3, m4, m5, m6, m7, m8, m9);
     }
+    /** Sepia matrix. `value` in `[0, 1]`: `0` is unchanged, `1` is full sepia. Mutates and returns `this`. */
     sepia(value = 1) {
       const m1 = 0.393 + 0.607 * (1 - value);
       const m2 = 0.769 - 0.769 * (1 - value);
@@ -912,6 +949,7 @@ var Gleam = (() => {
       const m9 = 0.131 + 0.869 * (1 - value);
       return this.applyMatrix(m1, m2, m3, m4, m5, m6, m7, m8, m9);
     }
+    /** Tint or shade. `percent` in `[-1, 1]`: negative shades toward black, positive tints toward white, magnitude is the amount. Mutates and returns `this`. */
     shade(percent) {
       const target = percent < 0 ? 0 : 255;
       const p = Math.abs(percent);
@@ -921,6 +959,7 @@ var Gleam = (() => {
         this.b + (target - this.b) * p
       );
     }
+    /** CSS hex string. `#rrggbb` when alpha is exactly `1`, `#rrggbbaa` otherwise. Channels are rounded. */
     toHex() {
       const r = Math.round(this.r).toString(16).padStart(2, "0");
       const g = Math.round(this.g).toString(16).padStart(2, "0");
@@ -932,6 +971,7 @@ var Gleam = (() => {
       const a = Math.round(this.alpha * 255);
       return `${rgb}${a.toString(16).padStart(2, "0")}`;
     }
+    /** CSS HSL string. `hsl(h, s%, l%)` when alpha is exactly `1`, `hsla(...)` otherwise. Hue is in degrees. */
     toHSL() {
       const { h, s, l } = this.toHSLObject();
       const cssH = Math.round(h);
@@ -939,6 +979,7 @@ var Gleam = (() => {
       const cssL = Math.round(l);
       return this.alpha === 1 ? `hsl(${cssH}, ${cssS}%, ${cssL}%)` : `hsla(${cssH}, ${cssS}%, ${cssL}%, ${this.alpha.toFixed(2)})`;
     }
+    /** HSL(A) components as numbers — see {@link HSLObject}. Use when you need to compute against the values rather than render them as a string. */
     toHSLObject() {
       const r = this.r / 255;
       const g = this.g / 255;
@@ -966,15 +1007,18 @@ var Gleam = (() => {
       }
       return { h: h * 360, s: s * 100, l: l * 100, a: this.alpha };
     }
+    /** CSS RGB string. `rgb(r, g, b)` when alpha is exactly `1`, `rgba(r, g, b, a)` otherwise. Channels are rounded. */
     toRGB() {
       const r = Math.round(this.r);
       const g = Math.round(this.g);
       const b = Math.round(this.b);
       return this.alpha === 1 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${this.alpha.toFixed(2)})`;
     }
+    /** New `Color` with the same channels. */
     clone() {
       return new _Color(this.r, this.g, this.b, this.alpha);
     }
+    /** Approximate equality (within `approxEqual` tolerance). Pass `compareAlpha: false` to ignore the alpha channel. */
     equals(other, compareAlpha = true) {
       return approxEqual(this.r, other.r) && approxEqual(this.g, other.g) && approxEqual(this.b, other.b) && (!compareAlpha || approxEqual(this.alpha, other.alpha));
     }
@@ -1116,12 +1160,14 @@ var Gleam = (() => {
       __publicField(this, "sideIsDirty", true);
       this.set(x, y, w, h);
     }
+    /** Build from an `HTMLElement` (via `getBoundingClientRect`) or a `DOMRect`. */
     static fromBoundingClientRect(rect) {
       if (rect instanceof HTMLElement) {
         rect = rect.getBoundingClientRect();
       }
       return new _Rect(rect.left, rect.top, rect.width, rect.height);
     }
+    /** Axis-aligned bounding box of a polygon's points. Throws if the polygon has no points. */
     static fromPolygon(polygon) {
       if (polygon.points.length === 0) {
         throw new Error("Supplied polygon has no points!");
@@ -1146,34 +1192,43 @@ var Gleam = (() => {
       });
       return new _Rect(minX, minY, maxX - minX, maxY - minY);
     }
+    /** Height. */
     get h() {
       return this._h;
     }
+    /** Height. */
     set h(value) {
       this._h = value;
       this.sideIsDirty = true;
     }
+    /** Width. */
     get w() {
       return this._w;
     }
+    /** Width. */
     set w(value) {
       this._w = value;
       this.sideIsDirty = true;
     }
+    /** Top-left x. */
     get x() {
       return this._x;
     }
+    /** Top-left x. */
     set x(value) {
       this._x = value;
       this.sideIsDirty = true;
     }
+    /** Top-left y. */
     get y() {
       return this._y;
     }
+    /** Top-left y. */
     set y(value) {
       this._y = value;
       this.sideIsDirty = true;
     }
+    /** Derived sides/center/halfSize. Lazily recomputed after any `x`/`y`/`w`/`h` change. */
     get sides() {
       if (this.sideIsDirty) {
         this._sides = {
@@ -1189,6 +1244,7 @@ var Gleam = (() => {
       }
       return this._sides;
     }
+    /** Grow on every side by `delta` (`x`/`y` shift in, `w`/`h` grow by `2*delta`). Pass a negative value to shrink. Mutates and returns `this`. */
     inflate(delta) {
       this.x -= delta;
       this.y -= delta;
@@ -1197,12 +1253,16 @@ var Gleam = (() => {
       this.sideIsDirty = true;
       return this;
     }
+    /** Round `x` and `y` to the nearest integer. `w`/`h` are unchanged. Mutates and returns `this`. */
     round() {
       this.x = Math.round(this.x);
       this.y = Math.round(this.y);
       this.sideIsDirty = true;
       return this;
     }
+    /**
+     * Replace fields. The first arg may be a `Vector4` (sets all four), a `Vector2` (sets `x`/`y` only, unless explicit `w`/`h` follow), or `x` as a number with separate `y`/`w`/`h`. Mutates and returns `this`.
+     */
     set(x = 0, y = 0, w, h) {
       if (typeof x === "number") {
         this.x = x;
@@ -1224,15 +1284,19 @@ var Gleam = (() => {
       this.sideIsDirty = true;
       return this;
     }
+    /** AABB-vs-AABB overlap test (inclusive of touching edges). */
     collide(rect) {
       return this.x <= rect.x + rect.w && this.x + this.w >= rect.x && this.y <= rect.y + rect.h && this.y + this.h >= rect.y;
     }
+    /** `true` when `rect` is fully inside `this`. */
     collideFull(rect) {
       return rect.x + rect.w <= this.x + this.w && rect.x >= this.x && rect.y >= this.y && rect.y + rect.h <= this.y + this.h;
     }
+    /** `true` when `vec` lies inside `this` (inclusive of edges). */
     collidePoint(vec) {
       return this.x <= vec.x && vec.x <= this.x + this.w && this.y <= vec.y && vec.y <= this.y + this.h;
     }
+    /** Side of `this` that `rect` overlaps from, or `"none"` if disjoint. Useful for picking a bounce axis. */
     collideSide(rect) {
       const dx = this.x + this.w * 0.5 - (rect.x + rect.w * 0.5);
       const dy = this.y + this.h * 0.5 - (rect.y + rect.h * 0.5);
@@ -1250,18 +1314,23 @@ var Gleam = (() => {
       }
       return collision;
     }
+    /** Top-left corner as a new `Vec2`. */
     pos() {
       return new Vec2(this.x, this.y);
     }
+    /** Width and height as a new `Vec2`. */
     size() {
       return new Vec2(this.w, this.h);
     }
+    /** Debug string like `"Rect [x: 0, y: 0, w: 10, h: 20]"`. */
     toString() {
       return `Rect [x: ${this.x}, y: ${this.y}, w: ${this.w}, h: ${this.h}]`;
     }
+    /** New `Rect` with the same values. */
     clone() {
       return new _Rect(this.x, this.y, this.w, this.h);
     }
+    /** Approximate equality. Pass `withSize: false` to compare position only. */
     equals(other, withSize = true) {
       let output = approxEqual(this.x, other.x) && approxEqual(this.y, other.y);
       if (output && withSize) {
@@ -1293,25 +1362,31 @@ var Gleam = (() => {
   );
   var Vec2 = class _Vec2 {
     constructor(x = 0, y) {
+      /** Horizontal component. */
       __publicField(this, "x", 0);
+      /** Vertical component. */
       __publicField(this, "y", 0);
       this.calculate(Operation.Equal, x, y);
     }
+    /** Unit vector at angle `rad` (radians), scaled per-axis. `scaleY` defaults to `scaleX`. */
     static fromAngle(rad, scaleX = 1, scaleY = scaleX) {
       return new _Vec2(Math.cos(rad) * scaleX, Math.sin(rad) * scaleY);
     }
     set(x, y) {
       return this.calculate(Operation.Equal, x, y);
     }
+    /** Set each component to its absolute value. Mutates and returns `this`. */
     abs() {
       return this.map(Math.abs);
     }
     add(x, y) {
       return this.calculate(Operation.Add, x, y);
     }
+    /** Round each component up. Mutates and returns `this`. */
     ceil() {
       return this.map(Math.ceil);
     }
+    /** Clamp each axis to its `[min, max]` range. `y` defaults to `x`. Mutates and returns `this`. */
     clamp(x, y = x) {
       this.x = clamp(this.x, x[0], x[1]);
       this.y = clamp(this.y, y[0], y[1]);
@@ -1320,9 +1395,19 @@ var Gleam = (() => {
     div(x, y) {
       return this.calculate(Operation.Div, x, y);
     }
+    /** Round each component down. Mutates and returns `this`. */
     floor() {
       return this.map(Math.floor);
     }
+    /**
+     * Apply `callback` to each component (`index` is `0` for x, `1` for y). Mutates and returns `this`.
+     *
+     * @example
+     * ```ts
+     * new Vec2(3.6, -2.1).map(Math.trunc);   // Vec2 { x: 3, y: -2 }
+     * new Vec2(2, 5).map((v, i) => v * (i + 1)); // Vec2 { x: 2, y: 10 }
+     * ```
+     */
     map(callback) {
       this.x = callback(this.x, 0);
       this.y = callback(this.y, 1);
@@ -1334,9 +1419,11 @@ var Gleam = (() => {
     mult(x, y) {
       return this.calculate(Operation.Mult, x, y);
     }
+    /** Flip the sign of both components (same as `mult(-1)`). Mutates and returns `this`. */
     negate() {
       return this.mult(-1);
     }
+    /** Scale to unit length. Zero-length vectors are left untouched and warn (throttled). Mutates and returns `this`. */
     normalize() {
       const length = this.length();
       if (approxEqual(length, 0)) {
@@ -1345,6 +1432,7 @@ var Gleam = (() => {
       }
       return this.map((value) => value / length);
     }
+    /** Scale so `|x| + |y| === 1`. Zero-length vectors are left untouched. Mutates and returns `this`. */
     normalizeManhattan() {
       const length = this.lengthManhattan();
       if (approxEqual(length, 0)) {
@@ -1355,6 +1443,7 @@ var Gleam = (() => {
     rem(x, y) {
       return this.calculate(Operation.Rem, x, y);
     }
+    /** Round each component to the nearest integer. Mutates and returns `this`. */
     round() {
       this.x = Math.round(this.x);
       this.y = Math.round(this.y);
@@ -1363,38 +1452,48 @@ var Gleam = (() => {
     sub(x, y) {
       return this.calculate(Operation.Sub, x, y);
     }
+    /** Angle in radians. No arg: angle of `this` from origin. With `other`: angle from `this` toward `other`. */
     angle(other) {
       if (!other) {
         return Math.atan2(this.y, this.x);
       }
       return Math.atan2(other.y - this.y, other.x - this.x);
     }
+    /** Euclidean distance to `other`. */
     distance(other) {
       return Math.sqrt(
         Math.pow(other.x - this.x, 2) + Math.pow(other.y - this.y, 2)
       );
     }
+    /** Manhattan distance (`|dx| + |dy|`) to `other`. */
     distanceManhattan(other) {
       return Math.abs(other.x - this.x) + Math.abs(other.y - this.y);
     }
+    /** Dot product with `other`. */
     dotProduct(other) {
       return this.x * other.x + this.y * other.y;
     }
+    /** `true` when both components are finite (rules out `NaN` and `±Infinity`). */
     isValid() {
       return Number.isFinite(this.x) && Number.isFinite(this.y);
     }
+    /** Euclidean magnitude (`sqrt(x² + y²)`). */
     length() {
       return Math.sqrt(this.x * this.x + this.y * this.y);
     }
+    /** Manhattan magnitude (`|x| + |y|`). */
     lengthManhattan() {
       return Math.abs(this.x) + Math.abs(this.y);
     }
+    /** Larger of the two components. */
     max() {
       return Math.max(this.x, this.y);
     }
+    /** Smaller of the two components. */
     min() {
       return Math.min(this.x, this.y);
     }
+    /** Tuple `[x, y]`. */
     toArray() {
       return [this.x, this.y];
     }
@@ -1404,9 +1503,11 @@ var Gleam = (() => {
     toRectAddSize(width, height) {
       return this.concat(false, width, height);
     }
+    /** Debug string like `"Vec2 [x: 1, y: 2]"`. */
     toString() {
       return `Vec2 [x: ${this.x}, y: ${this.y}]`;
     }
+    /** New `Vec2` with the same components. */
     clone() {
       return new _Vec2(this.x, this.y);
     }
@@ -1486,9 +1587,11 @@ var Gleam = (() => {
   // src/core/Settings.ts
   var LOCAL_STORAGE_KEY = "gleam";
   var Settings = class {
+    /** Read-only view of the persisted localStorage blob. Writes go through {@link setLocalStorage}. */
     static get localStorage() {
       return this._localStorage;
     }
+    /** One-time setup — called by `Game`'s constructor with the overrides passed to `super()`. Validates {@link fps}, loads the persisted localStorage blob, derives `language` from `navigator.language`, and wires the close-warning handler if {@link warnBeforeClose}. Throws if called twice or if `fps` isn't a finite positive number. */
     static init(overrides, game) {
       if (this.initialized) {
         throw new Error("Settings.init called twice");
@@ -1528,6 +1631,7 @@ var Gleam = (() => {
       }
       this.initialized = true;
     }
+    /** Typed setter for the persisted localStorage blob. Writes both in-memory and to actual `localStorage` (under a single JSON key — `"gleam"`). The only supported way to mutate persisted state. */
     static setLocalStorage(key, value) {
       this._localStorage[key] = value;
       localStorage.setItem(
@@ -1536,16 +1640,27 @@ var Gleam = (() => {
       );
     }
   };
+  /** Enable smoothing on the main canvas context. Default `false` for crisp pixel art. */
   __publicField(Settings, "antialias", false);
+  /** Start the gameloop automatically after `init()` resolves. Disable to drive `gameloop.startLoop()` manually. Default `true`. */
   __publicField(Settings, "autoloop", true);
+  /** CSS color used when {@link useClearRect} is `false`. Default `"#444"`. */
   __publicField(Settings, "backgroundColor", "#444");
+  /** Debug mode: assigns the `Game` instance to `window.game` and lets {@link Keyboard} Escape stop the loop. Default `false`. */
   __publicField(Settings, "debug", false);
+  /** Skip the per-frame canvas clear. Use for trail/decay effects where you manage clearing yourself. Default `false`. */
   __publicField(Settings, "doNotClear", false);
+  /** Stretch the main canvas to fill the window on resize while preserving its aspect ratio. Default `true`. */
   __publicField(Settings, "enableResize", true);
+  /** Default font family for `canman.setFontSize`. Default `"Arial"`. */
   __publicField(Settings, "font", "Arial");
+  /** **Seconds per fixed step**, not frames per second — `1 / 60` = 60 Hz, `1 / 30` = 30 Hz. Must be finite and `> 0` or {@link init} throws. */
   __publicField(Settings, "fps", 1 / 60);
+  /** Callback invoked from the `beforeunload` handler when {@link warnBeforeClose} is `true`. Useful for "are you sure?" autosave logic. */
   __publicField(Settings, "triedToClose");
+  /** Clear the canvas with `clearRect` (transparent) when `true`, or `fillRect` with {@link backgroundColor} when `false`. Default `true`. */
   __publicField(Settings, "useClearRect", true);
+  /** Show a browser "are you sure?" dialog on tab close. Required for {@link triedToClose} to fire. Default `false`. */
   __publicField(Settings, "warnBeforeClose", false);
   __publicField(Settings, "initialized", false);
   // Only mutated via `setLocalStorage` (typed) and via the localStorage
@@ -2138,19 +2253,20 @@ var Gleam = (() => {
   // src/content/Animator.ts
   var _Animator = class _Animator {
     /**
-     * We store rendered images in a cache.
-     * So if you have the same entity multiple times, the images get computed once and then shared.
-     * This reduces overhead and frees time up for other important computations.
-     *
-     * `namespace` is the cache key prefix for these rendered images.
-     * So pass a different key for different Animators; otherwise, you will see wrong images.
+     * Bind to `entity` and stamp `namespace` as the prefix for cache keys (`${namespace}.${animationName}`). **Use distinct namespaces for animators whose sprite sets differ** — sharing a namespace across mismatched sprite sets serves the wrong cached frames.
      */
     constructor(entity, namespace) {
+      /** When `false`, {@link update} is a no-op. Set automatically to `false` after a single-frame animation finishes and via {@link reset} when no default animation exists. */
       __publicField(this, "active", true);
+      /** Current rendered frame (after flip processing). Pulled from the cache by {@link setImage} every time the frame advances. */
       __publicField(this, "image");
+      /** Index of the current frame within the current animation's `sprites` array. */
       __publicField(this, "imageId", 0);
+      /** Flip the rendered sprite horizontally. Caches a separate "flipped" bucket so toggling is cheap. */
       __publicField(this, "lookLeft", false);
+      /** One-shot callback that fires when the current animation's last frame finishes. Cleared after firing. */
       __publicField(this, "onEnd");
+      /** Current sprite's `(width, height)`. Updated by {@link setImage}. */
       __publicField(this, "size", new Vec2());
       __publicField(this, "animations", []);
       __publicField(this, "currentAnimation", 0);
@@ -2178,9 +2294,11 @@ var Gleam = (() => {
         }
       });
     }
+    /** The currently-playing animation. `undefined` if no animations have been added yet. */
     get current() {
       return this.animations[this.currentAnimation];
     }
+    /** Blit the current cached frame at `entity.pos + offset`, shifted left by `size.x` to compensate for the 2×-wide cache canvas. */
     draw(context, offset = new Vec2()) {
       context.drawImage(
         this.image,
@@ -2188,6 +2306,7 @@ var Gleam = (() => {
         this.entity.pos.y + offset.y
       );
     }
+    /** Advance the timer; when it crosses `current.timing`, step to the next frame, fire any `onFrame[index]` callback, and on rollover fire `onEnd` and queue `lastPlayed` (set by {@link playOnce}). No-op when {@link active} is `false`. */
     update(dt) {
       if (!this.active) {
         return;
@@ -2231,6 +2350,7 @@ var Gleam = (() => {
         this.setImage();
       }
     }
+    /** Register a new animation. Logs an error (but still registers) if `defaultAnim` is true while another default already exists, or if `name` collides with an existing animation. Auto-plays the new animation when `defaultAnim` is `true`. */
     add(name, sprites, timing, defaultAnim = false) {
       if (defaultAnim && this.animations.some((anim) => anim.default)) {
         console.error("Only one default animation allowed!");
@@ -2248,6 +2368,7 @@ var Gleam = (() => {
         this.play(name);
       }
     }
+    /** Convenience wrapper around {@link add} that takes a packed {@link SpriteAnimation}. `defaultAnim` is OR'd with `anim.default`. */
     addAnimation(anim, defaultAnim = false) {
       this.add(
         anim.name,
@@ -2256,6 +2377,7 @@ var Gleam = (() => {
         anim.default || defaultAnim
       );
     }
+    /** Draw the current frame rotated by `angle` radians around a sprite-relative pivot (75% width, 50% height). Uses `setTransform` and resets the transform on exit. */
     drawRotated(context, angle, offset = new Vec2()) {
       const x = this.entity.pos.x + offset.x;
       const y = this.entity.pos.y + offset.y;
@@ -2266,6 +2388,7 @@ var Gleam = (() => {
       context.drawImage(this.image, -w, -h);
       context.setTransform(1, 0, 0, 1, 0, 0);
     }
+    /** Switch to the named animation, rewinding timer and frame index. Optionally register `onEnd` (fires after the last frame) and `onFrame` (frame-indexed callbacks). Any previous {@link Animator.onEnd} fires before the new one is set. Throws if `name` isn't registered. */
     play(name, onEnd, onFrame) {
       const index = this.animations.findIndex(
         (anim) => anim.name === name
@@ -2288,6 +2411,7 @@ var Gleam = (() => {
       }
       this.active = true;
     }
+    /** {@link play} only if `name` isn't already the current animation. Returns `true` if it started a new playback, `false` if it was already playing. */
     playIfNot(name, onEnd, onFrame) {
       if (!this.isPlaying(name)) {
         this.play(name, onEnd, onFrame);
@@ -2295,6 +2419,7 @@ var Gleam = (() => {
       }
       return false;
     }
+    /** Queue an animation to play once the current one finishes. Pass `undefined` to cancel the queue. Used internally by {@link playOnce}. */
     playNextOnce(name) {
       this.lastPlayed = name;
     }
@@ -2305,9 +2430,11 @@ var Gleam = (() => {
       this.lastPlayed = this.current?.name;
       this.play(name, onEnd, onFrame);
     }
+    /** Randomize the frame timer to a value in `[0, current.timing)`. Useful when spawning many instances of the same animation to break phase lockstep. */
     randomTimer() {
       this.timer = randomBetweenFloat(0, this.current.timing);
     }
+    /** Drop every registered animation and clear this instance's cached frames. {@link active} resets to `true`; pending callbacks are cleared. */
     removeAllAnimations() {
       this.animations.length = 0;
       this.active = true;
@@ -2315,6 +2442,7 @@ var Gleam = (() => {
       this.onFrame = void 0;
       _Animator.clearSpriteCache(this.namespace);
     }
+    /** Switch back to the default animation if one was registered (marked via `defaultAnim`); otherwise just stop animating ({@link active} = `false`). */
     reset() {
       const defaultAnim = this.animations.find(
         (anim) => anim.default
@@ -2326,6 +2454,7 @@ var Gleam = (() => {
         this.active = false;
       }
     }
+    /** `true` when `name` matches the currently-playing animation. */
     isPlaying(name) {
       return this.current && this.current.name === name;
     }
@@ -2364,15 +2493,63 @@ var Gleam = (() => {
   __publicField(_Animator, "spriteCache", /* @__PURE__ */ new Map());
   var Animator = _Animator;
 
+  // src/content/ControllerCursor.ts
+  var ControllerCursor = class {
+    /**
+     * @param controller Gamepad input source.
+     * @param crosshair Drawn at each cursor position via `CanvasRenderingContext2D.drawImage`. The image's top-left is the draw origin — center the visible reticle inside the image, or offset the anchors to compensate.
+     * @param sticks Anchor positions, one per stick to track. Cloned at construction so caller mutation is harmless.
+     * @param range Max pixel deflection from anchor at full stick. Default `80`.
+     */
+    constructor(controller, crosshair, sticks, range = 80) {
+      __publicField(this, "controller");
+      __publicField(this, "crosshair");
+      __publicField(this, "range");
+      __publicField(this, "sticks", []);
+      this.controller = controller;
+      this.crosshair = crosshair;
+      this.range = range;
+      sticks.forEach(
+        (stick) => this.sticks.push({ pos: stick.clone(), offset: new Vec2() })
+      );
+    }
+    /** Draw a crosshair at `anchor + offset` for each tracked stick. */
+    draw(context) {
+      this.sticks.forEach((stick) => {
+        context.drawImage(
+          this.crosshair,
+          stick.pos.x + stick.offset.x,
+          stick.pos.y + stick.offset.y
+        );
+      });
+    }
+    /** Pull fresh stick state via {@link Controller.poll} and smooth each crosshair's offset toward `stickAxis * range`. Frame-rate independent — 50 ms to cover half the remaining distance. */
+    update(dt) {
+      const alpha = 1 - Math.pow(0.5, dt / 0.05);
+      this.controller.poll().forEach((axi, index) => {
+        const offset = this.sticks[index].offset;
+        offset.x += (axi.x * this.range - offset.x) * alpha;
+        offset.y += (axi.y * this.range - offset.y) * alpha;
+      });
+    }
+  };
+
   // src/content/Particle.ts
   var Particle = class {
     constructor(pos, color, size = 2) {
+      /** CSS color string passed to `context.fillStyle` in {@link draw}. */
       __publicField(this, "color");
+      /** Accumulated time (seconds) since spawn or last {@link resetLifetime}. */
       __publicField(this, "lifetime", 0);
+      /** Lifetime cap in seconds, randomized to `[0.5, 1.5]` at construction. */
       __publicField(this, "maxLifeTime");
+      /** Top-left position. Cloned from the constructor arg so the caller's `Vec2` isn't aliased. */
       __publicField(this, "pos");
+      /** Circle radius (pixels). */
       __publicField(this, "size");
+      /** Velocity in px/s. Seeded randomly by the constructor (random angle, random magnitude per axis). */
       __publicField(this, "vel");
+      /** Backing storage for the {@link rect} getter. Subclasses can read it; the public-facing accessor is {@link rect}. */
       __publicField(this, "_rect");
       this.pos = pos.clone();
       this.color = color;
@@ -2385,12 +2562,15 @@ var Gleam = (() => {
       );
       this.maxLifeTime = 0.5 + Math.random();
     }
+    /** `false` once {@link lifetime} reaches {@link maxLifeTime}. Owners typically filter dead particles out of their list each frame, or call {@link resetLifetime} to recycle. */
     get alive() {
       return this.lifetime < this.maxLifeTime;
     }
+    /** Read-only AABB tracking `pos` and the particle's `size`. Recomputed each {@link update}. */
     get rect() {
       return this._rect;
     }
+    /** Fill a circle at `pos + offset` using {@link color}. `offset` is useful for shifting by a camera/world transform without mutating `pos`. */
     draw(context, offset = new Vec2()) {
       context.fillStyle = this.color;
       context.drawCircle(
@@ -2402,12 +2582,14 @@ var Gleam = (() => {
         "fill"
       );
     }
+    /** Integrate lifetime, position, and bounding rect. */
     update(dt) {
       this.lifetime += dt;
       this.pos.x += this.vel.x * dt;
       this.pos.y += this.vel.y * dt;
       this._rect.set(this.pos.x, this.pos.y);
     }
+    /** Recycle a dead particle by subtracting `maxLifeTime` from `lifetime` — preserves any overshoot so a pool of pre-allocated particles can stay phase-stable across loops. Note this doesn't re-randomize `vel` or `pos`; mutate those externally if you want a fresh trajectory. */
     resetLifetime() {
       this.lifetime -= this.maxLifeTime;
     }
@@ -2416,14 +2598,23 @@ var Gleam = (() => {
   // src/content/Projectile.ts
   var Projectile = class {
     constructor(pos, image, vel = new Vec2()) {
+      /** Seconds after which {@link alive} flips to `false`. Defaults to `Infinity` — no natural expiry. */
       __publicField(this, "maxLifetime", Infinity);
+      /** Caller-supplied data. Typed via the class generic so consumers can read `projectile.payload` without casting. */
       __publicField(this, "payload");
+      /** Magnitude multiplier applied to `vel` each update: `pos += vel * speed * dt`. Pass a unit-length `vel` to make this read as "pixels per second". */
       __publicField(this, "speed", 1200);
+      /** Current pre-rotated sprite. Re-baked by {@link rebuildRotation} from the un-rotated `originalImage`. */
       __publicField(this, "image");
+      /** Accumulated time (seconds). Drives the {@link alive} check against {@link maxLifetime}. */
       __publicField(this, "lifetime", 0);
+      /** Top-left position. Cloned from the constructor arg so the caller's `Vec2` isn't aliased. */
       __publicField(this, "pos");
+      /** Current sprite rotation in radians, kept in sync with `vel` by {@link rebuildRotation}. */
       __publicField(this, "rotation", 0);
+      /** Velocity direction vector. Multiplied by {@link speed} each update — pass a unit vector for `speed`-as-px-per-second semantics. Cloned from the constructor arg. */
       __publicField(this, "vel");
+      /** Backing storage for the {@link rect} getter. Subclasses can read it; mutate via `pos`/{@link rebuildRotation} instead of touching it directly. */
       __publicField(this, "_rect");
       __publicField(this, "originalImage");
       this.pos = pos.clone();
@@ -2432,12 +2623,15 @@ var Gleam = (() => {
       this._rect = pos.toRectAddSize(image.width, image.height);
       this.rebuildRotation();
     }
+    /** `false` once {@link lifetime} reaches {@link maxLifetime}. Owners typically filter dead projectiles out of their list each frame. */
     get alive() {
       return this.lifetime < this.maxLifetime;
     }
+    /** Read-only AABB tracking `pos` and the (rotated) image size. Recomputed in {@link update} and {@link rebuildRotation}. */
     get rect() {
       return this._rect;
     }
+    /** Blit the pre-rotated image at `pos + offset`. `offset` is useful for shifting by a camera/world transform without mutating `pos`. */
     draw(context, offset = new Vec2()) {
       context.drawImage(
         this.image,
@@ -2445,6 +2639,7 @@ var Gleam = (() => {
         this.pos.y + offset.y
       );
     }
+    /** Integrate motion and advance lifetime. Doesn't re-bake the rotation — call {@link rebuildRotation} after mutating `vel`. */
     update(dt) {
       this.lifetime += dt;
       this.pos.x += this.vel.x * this.speed * dt;
@@ -2452,8 +2647,7 @@ var Gleam = (() => {
       this._rect.set(this.pos.x, this.pos.y);
     }
     /**
-     * Allocates a fresh rotated canvas on each call — no internal cache.
-     * Caching by quantized rotation could be a feature when projectiles need to re-aim every tick (homing/seeking).
+     * Re-bake the sprite to match the current `vel` direction (rotation = `atan2(vel.y, vel.x)`) and update `rect` to the new bounds. Allocates a fresh rotated canvas every call — no internal cache, so heavy re-aiming (homing/seeking) is a candidate for adding quantized caching.
      */
     rebuildRotation() {
       this.rotation = Math.atan2(this.vel.y, this.vel.x);
@@ -2461,6 +2655,7 @@ var Gleam = (() => {
       this._rect.w = this.image.width;
       this._rect.h = this.image.height;
     }
+    /** Force {@link alive} to `false` immediately (sets `lifetime` past `maxLifetime`). Use when the projectile should die on collision/impact, not from natural expiry. */
     remove() {
       this.lifetime = this.maxLifetime * 2;
     }
@@ -2468,40 +2663,56 @@ var Gleam = (() => {
 
   // src/core/CanvasManager.ts
   var CANVAS_TYPES = {
+    /** Catch-all tag for canvases without a specific role. */
     ANY: /* @__PURE__ */ Symbol("any"),
+    /** Generic placeholder tag — distinct from `ANY` so consumers can differentiate. */
     DEFAULT: /* @__PURE__ */ Symbol("default"),
+    /** Background canvas (drawn behind the main one). */
     BACKGROUND: /* @__PURE__ */ Symbol("background"),
+    /** Primary render target. Exactly one canvas must be registered with this type before {@link CanvasManager.finishSetup}. */
     MAIN: /* @__PURE__ */ Symbol("main")
   };
   var CanvasManager = class {
     constructor() {
+      /** Cached `getBoundingClientRect()` of the main canvas. Refreshed in {@link resize}. Used to map pointer client coords into canvas space. */
       __publicField(this, "canvasBoundingClientRect");
+      /** Registry of every {@link setupCanvas}-registered canvas, keyed by selector. */
       __publicField(this, "canvasHolder", {});
+      /** Display-to-buffer scale factor after the last {@link resize} (`displayWidth / bufferWidth`). `1` until the first resize. */
       __publicField(this, "ratio", 1);
+      /** Display (CSS-pixel) size of the main canvas after the last {@link resize}. Independent of the buffer dimensions in {@link width}/{@link height}. */
       __publicField(this, "resizedSize", new Vec2());
       __publicField(this, "mainHolder");
     }
+    /** Main canvas element (the one registered with `CANVAS_TYPES.MAIN`). */
     get canvas() {
       return this.mainHolder.canvas;
     }
+    /** Main canvas 2D rendering context. */
     get canvasContext() {
       return this.mainHolder.context;
     }
+    /** Main canvas **buffer** height (the drawing surface, not the CSS display size). */
     get height() {
       return this.canvas.height;
     }
+    /** Main canvas **buffer** height (the drawing surface, not the CSS display size). */
     set height(height) {
       this.canvas.height = height;
     }
+    /** Main canvas buffer dimensions as a new `Vec2`. */
     get size() {
       return new Vec2(this.width, this.height);
     }
+    /** Main canvas **buffer** width (the drawing surface, not the CSS display size). */
     get width() {
       return this.canvas.width;
     }
+    /** Main canvas **buffer** width (the drawing surface, not the CSS display size). */
     set width(width) {
       this.canvas.width = width;
     }
+    /** Finalize the canvas registry. Called once by `Game.preInit()`. Validates that exactly one `CANVAS_TYPES.MAIN` canvas is registered and that its buffer is non-zero, caches its bounding rect, and wires the `"resized"` listener if `Settings.enableResize`. Throws on duplicate calls or invalid registry state. */
     finishSetup() {
       if (this.mainHolder) {
         throw new Error("Already set up.");
@@ -2524,6 +2735,7 @@ var Gleam = (() => {
         EventSystem.addEventListener("resized", () => this.resize());
       }
     }
+    /** Rescale every opt-in canvas (`holder.resize === true`) to fit the window while preserving its buffer aspect ratio. Updates `style.width`/`style.height` only — buffer dimensions don't change. Refreshes {@link canvasBoundingClientRect}, {@link resizedSize}, and {@link ratio} from the main canvas. */
     resize() {
       const windowRatio = window.innerHeight / window.innerWidth;
       Object.values(this.canvasHolder).forEach((ch) => {
@@ -2549,10 +2761,12 @@ var Gleam = (() => {
       });
       this.canvasBoundingClientRect = this.canvas.getBoundingClientRect();
     }
+    /** Set the main context's `font` to `${size}px "${font}"`. Defaults the family to `Settings.font`. */
     setFontSize(size, font = Settings.font) {
       this.canvasContext.font = `${size}px "${font}"`;
     }
-    setupCanvas(canvasType, selector, resize = true) {
+    /** Register a canvas at `selector` with the given role tag. Initializes its context (`fillStyle`/`strokeStyle` = white, font = `12px Arial`) and returns the {@link CanvasHolder}. `resize` defaults to `Settings.enableResize`. Throws if the selector doesn't match an element or has already been registered. */
+    setupCanvas(canvasType, selector, resize = Settings.enableResize) {
       if (!document.querySelector(selector)) {
         throw new Error("Canvas '" + selector + "' does not exist!");
       }
@@ -2581,6 +2795,7 @@ var Gleam = (() => {
   var MAX_STEPS_PER_FRAME = 5;
   var Gameloop = class {
     constructor(game) {
+      /** Simulation time in milliseconds. Advances by `Settings.fps * 1000` per update step, so it reflects simulated time, not wall-clock — paused/dropped frames don't add. Use this for time-driven spawning, animations, etc. */
       __publicField(this, "levelTime", 0);
       __publicField(this, "_isLooping", false);
       __publicField(this, "accumulator", 0);
@@ -2588,9 +2803,11 @@ var Gleam = (() => {
       __publicField(this, "stop", false);
       this.game = game;
     }
+    /** `true` while the rAF callback is registered. Goes `false` only after the final frame fires the `"gameloopStopped"` event. */
     get isLooping() {
       return this._isLooping;
     }
+    /** Begin the rAF loop. Throws if {@link stopLoop} was called but teardown hasn't completed yet — wait for the `"gameloopStopped"` event before restarting. */
     startLoop() {
       if (this._isLooping && this.stop) {
         throw new Error(
@@ -2600,6 +2817,7 @@ var Gleam = (() => {
       this.stop = false;
       this.looper();
     }
+    /** Request that the loop stop on its next tick. Asynchronous — the loop tears down on the following frame and dispatches `"gameloopStopped"` when done. */
     stopLoop() {
       this.stop = true;
     }
@@ -2657,53 +2875,98 @@ var Gleam = (() => {
 
   // src/input/Keyboard.ts
   var KEYBOARD_KEYS = {
+    /** Digit row `0`. */
     KEY_0: "Digit0",
+    /** Digit row `1`. */
     KEY_1: "Digit1",
+    /** Digit row `2`. */
     KEY_2: "Digit2",
+    /** Digit row `3`. */
     KEY_3: "Digit3",
+    /** Digit row `4`. */
     KEY_4: "Digit4",
+    /** Digit row `5`. */
     KEY_5: "Digit5",
+    /** Digit row `6`. */
     KEY_6: "Digit6",
+    /** Digit row `7`. */
     KEY_7: "Digit7",
+    /** Digit row `8`. */
     KEY_8: "Digit8",
+    /** Digit row `9`. */
     KEY_9: "Digit9",
+    /** Letter `A`. */
     KEY_A: "KeyA",
+    /** Letter `B`. */
     KEY_B: "KeyB",
+    /** Letter `C`. */
     KEY_C: "KeyC",
+    /** Letter `D`. */
     KEY_D: "KeyD",
+    /** Down arrow. */
     KEY_DOWN: "ArrowDown",
+    /** Letter `E`. */
     KEY_E: "KeyE",
+    /** Enter / Return. */
     KEY_ENTER: "Enter",
+    /** Escape. Note: in `Settings.debug` mode this stops the gameloop. */
     KEY_ESCAPE: "Escape",
+    /** Letter `F`. */
     KEY_F: "KeyF",
+    /** Letter `G`. */
     KEY_G: "KeyG",
+    /** Letter `H`. */
     KEY_H: "KeyH",
+    /** Letter `I`. */
     KEY_I: "KeyI",
+    /** Letter `J`. */
     KEY_J: "KeyJ",
+    /** Letter `K`. */
     KEY_K: "KeyK",
+    /** Letter `L`. */
     KEY_L: "KeyL",
+    /** Left arrow. */
     KEY_LEFT: "ArrowLeft",
+    /** Letter `M`. */
     KEY_M: "KeyM",
+    /** Letter `N`. */
     KEY_N: "KeyN",
+    /** Letter `O`. */
     KEY_O: "KeyO",
+    /** Letter `P`. */
     KEY_P: "KeyP",
+    /** Letter `Q`. */
     KEY_Q: "KeyQ",
+    /** Letter `R`. */
     KEY_R: "KeyR",
+    /** Right arrow. */
     KEY_RIGHT: "ArrowRight",
+    /** Letter `S`. */
     KEY_S: "KeyS",
+    /** Space bar. */
     KEY_SPACE: "Space",
+    /** Letter `T`. */
     KEY_T: "KeyT",
+    /** Tab. */
     KEY_TAB: "Tab",
+    /** Letter `U`. */
     KEY_U: "KeyU",
+    /** Up arrow. */
     KEY_UP: "ArrowUp",
+    /** Letter `V`. */
     KEY_V: "KeyV",
+    /** Letter `W`. */
     KEY_W: "KeyW",
+    /** Letter `X`. */
     KEY_X: "KeyX",
+    /** Letter `Y`. */
     KEY_Y: "KeyY",
+    /** Letter `Z`. */
     KEY_Z: "KeyZ"
   };
   var Keyboard = class {
     constructor(game) {
+      /** Live map of `KeyboardEvent.code` → pressed state. Codes only appear after the key has been touched at least once; missing codes read as `undefined` (use {@link isPressed} for a safe `boolean`). */
       __publicField(this, "keys", {});
       const keyEvent = (event) => {
         const code = event.code;
@@ -2724,14 +2987,17 @@ var Gleam = (() => {
       window.addEventListener("blur", () => this.reset(), false);
       EventSystem.addEventListener("gameloopStopped", () => this.reset());
     }
+    /** Mark every tracked key as released. Called automatically on `window` blur and on `gameloopStopped`. */
     reset() {
       for (const key in this.keys) {
         this.keys[key] = false;
       }
     }
+    /** Mark a single key as released — used to consume a press so subsequent ticks don't re-trigger one-shot actions while the key is still held. */
     stopPress(code) {
       this.keys[code] = false;
     }
+    /** `true` when `code` is currently held. Safe for untouched keys (returns `false` rather than `undefined`). */
     isPressed(code) {
       return !!this.keys[code];
     }
@@ -2739,20 +3005,32 @@ var Gleam = (() => {
 
   // src/input/Pointer.ts
   var POINTER_KEYS = {
+    /** Primary button (left for right-handers). */
     LEFT: 0,
+    /** Middle button / wheel click. */
     MIDDLE: 1,
+    /** Secondary button (right for right-handers). */
     RIGHT: 2,
+    /** "Back" side button (browser back). */
     PREV: 3,
+    /** "Forward" side button. */
     FORWARD: 4
   };
   var Pointer = class {
     constructor(game) {
+      /** Dirty bit set to `true` on every move and never cleared by the engine — flip it back to `false` after reading to detect "moved since last check". */
       __publicField(this, "hasMoved", false);
+      /** Last raw `PointerEvent` received. `null` until any pointer event fires. Use for properties not surfaced as Vec2/booleans (pressure, pointerType, etc.). */
       __publicField(this, "lastEvent", null);
+      /** Viewport-space coordinates (`event.clientX/Y` — CSS pixels relative to the page). */
       __publicField(this, "posReal", new Vec2());
+      /** Previous tick's {@link posReal}. Subtract for a per-frame delta. */
       __publicField(this, "posRealLast", new Vec2());
+      /** Canvas-space coordinates, mapped from the bounding rect into the main canvas's pixel buffer and clamped to its size. This is the position to use for in-game logic. */
       __publicField(this, "posScaled", new Vec2());
+      /** Previous tick's {@link posScaled}. */
       __publicField(this, "posScaledLast", new Vec2());
+      /** Per-button pressed state. Index with {@link POINTER_KEYS} (e.g. `pressed[POINTER_KEYS.LEFT]`). Sparse — unindexed entries are `undefined`, not `false`. */
       __publicField(this, "pressed", []);
       __publicField(this, "game");
       this.game = game;
@@ -2785,6 +3063,7 @@ var Gleam = (() => {
         false
       );
     }
+    /** Clear all pressed-button state. Called automatically on `window` blur so held buttons don't stay "pressed" forever when focus is lost. */
     reset() {
       this.pressed.length = 0;
     }
@@ -3125,9 +3404,13 @@ var Gleam = (() => {
   // src/core/Game.ts
   var Game = class {
     constructor(settingOverrides = {}) {
+      /** Canvas registry + 2D context exposure. Register canvases here from the constructor (`canman.setupCanvas(CANVAS_TYPES.MAIN, "#game")`) before calling {@link preInit}. */
       __publicField(this, "canman", new CanvasManager());
+      /** The fixed-step driver. Started automatically by `preInit` when `Settings.autoloop` is `true`. */
       __publicField(this, "gameloop");
+      /** Live keyboard state. See {@link Keyboard}. */
       __publicField(this, "keyboard");
+      /** Live pointer (mouse / pen / touch) state. See {@link Pointer}. */
       __publicField(this, "pointer");
       __publicField(this, "initialized", false);
       Settings.init(settingOverrides, this);
@@ -3136,17 +3419,21 @@ var Gleam = (() => {
       this.keyboard = new Keyboard(this);
       this.pointer = new Pointer(this);
     }
+    /** Render the current frame. Called by {@link Gameloop} after the canvas is cleared. Subclasses must override — the default throws. */
     draw(_context) {
       throw new Error("Override draw function!");
     }
+    /** Advance the simulation by `dt` seconds (= `Settings.fps`). Called by {@link Gameloop} zero-or-more times per frame depending on real-time accumulation. Subclasses must override — the default throws. */
     update(_dt) {
       throw new Error("Override update function!");
     }
+    /** One-time setup hook (assets, world build) invoked by {@link preInit}. Can be `async`; the loop waits for it to resolve before starting. **Do not call directly** — kick off via {@link preInit} from the constructor. Subclasses must override — the default throws. */
     async init() {
       throw new Error(
         "Override init() and start the game via preInit() \u2014 do not call init() directly."
       );
     }
+    /** Finalise engine wiring and start the loop. Call once from the subclass constructor *after* registering canvases. Steps: `canman.finishSetup()` → install debounced `window.resize` → reset `gameloop.levelTime` → `await this.init()` (if `doInit`) → dispatch `"resized"` → start the loop if `Settings.autoloop`. Throws if called twice. Pass `doInit: false` to skip the `init()` await (useful for tests). */
     async preInit(doInit = true) {
       if (this.initialized) {
         throw new Error(
@@ -3173,8 +3460,11 @@ var Gleam = (() => {
 
   // src/effects/Screenshake.ts
   var SHAKE_TYPES = {
+    /** ~0.33 s wobble combining a small random rotation with a blur fall-off. */
     NORMAL: {
+      /** Decay rate — see {@link ShakeType.step}. */
       step: 3,
+      /** Per-frame mutator — see {@link ShakeType.update}. */
       update(updateCss, time) {
         const tr = `rotate(${randomBetweenFloat(-2, 2) * time}deg)`;
         updateCss("transform", tr);
@@ -3182,8 +3472,11 @@ var Gleam = (() => {
         updateCss("filter", `blur(${time * 5}px)`);
       }
     },
+    /** ~0.07 s impact: blur-only fall-off, no rotation. */
     FAST: {
+      /** Decay rate — see {@link ShakeType.step}. */
       step: 15,
+      /** Per-frame mutator — see {@link ShakeType.update}. */
       update(updateCss, time) {
         updateCss("filter", `blur(${time * 3}px)`);
       }
@@ -3196,7 +3489,7 @@ var Gleam = (() => {
       __publicField(this, "style");
       this.style = element.style;
     }
-    /** Best-effort style restore: each key the shake writes is snapshotted on first write and rewritten when the shake ends or is disposed. */
+    /** Start a shake of the given `shakeType`. Returns a dispose function that stops the shake early and restores every CSS key it touched, or `null` if a shake is already active on this instance. Auto-stops and restores when the timer reaches zero. */
     shake(shakeType = SHAKE_TYPES.NORMAL) {
       if (this.isShaking) {
         return null;
@@ -3234,72 +3527,48 @@ var Gleam = (() => {
     }
   };
 
-  // src/input/ControllerCursor.ts
-  var SPEED = 600;
-  var CROSSHAIR;
-  (async () => CROSSHAIR = await loadImage(
-    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAMAAAD04JH5AAAAilBMVEUAAAAaGhoZGRkZGRkbGxsZGRkaGhoWFhYgICAZGRkZGRkZGRkZGRkZGRkZGRkYGBgZGRkZGRkbGxsaGhoZGRkZGRkZGRkZGRkZGRkaGhoZGRkZGRkaGhoZGRkZGRkZGRkYGBgZGRkZGRkbGxsZGRkYGBgZGRkYGBgaGhoYGBgYGBgYGBgZGRkaGhqj+rsBAAAALXRSTlMA9fvsBINBCwfhZTnS2sByMcUZE8oe1TUqubeppJOLhlDyeiPOrp57X19dSkdeSFeiAAAELElEQVR42sSY2XaqQBBFD20jozKJI3E2Tun//72bKgmXZBmjLbT7KQ9J2HSdrqoFtMiCw2I2SUKvI0THC5PJbHEIMhjBOc/7HXWVTn9+dtAmbtdOhLqJSOyui3YYvXXUXXTeRmicfN9TNaxtYUf+shtbVtxd+pFdbC1Vo7fPm335Xe3Z0/VyI1FiWSiRm+V6WrPYNXcMwbSq8KCqcCXwMyWDKiXTAE3Q7auSMEpB/C7ApFGoSvpdPEs6q5IVA/hbgImrvM5SPIOMVorxfBe4U4BxfU8xq0hCmyAsM+1L4BEBlvd7ZeV0oyBtoQjvJIEHBRh58hQhbKlV/Uv4xNwBNAQYZy4uYdRIwsclRkkMaAowcXKJ8AceQy4UYfmApkCFbyli8VAZ3EIRwzGeF8B4qIjCxd04E0W8O2hCAM67IiYO7iQb8PEfgQYEmCOXYZDhLvIexyZAcwIIONK9/K735+d7YzQpgLHHBtkdBRtw/HI0K4B8yFVw/sz/pKxWswJVsiYubiILfv8MzQsg4zMoJG6x4PrnaEMAOedgcbP/cv7HaEcAY74LN7pySr9gBWhLAIFFL5j+GgCef0e0J4Ajz8bfYmBz/0WbAuCubOMqgaAL4LQr4NBVEMHVAoQUgDHaFcCYYhBeK0KkPvHRtgB8ek505QbQ/pugfQEktCun+MmMahObEIgpazP8oKs+mcOEAOb0rC6+Qy3Ac8wIOB41A3wjIKkTzAjgRE8LUGdK24I0JSBp55mixuhyBY0IVFdxhP/sKAHSnICkFOxQkeseAAtoH0GOL/Y0JF2TAi4N/j2+oEy8waQA3ij13yIYmxWIOYY1mxBmBRDSqdfqEZkWiDh31RgQqWmBVNBAqDaxAUwLYFDtZgn9ZF7A/to/HD4L8wJceQfAmVZB17yAS8vhuVwPpjAvwBN4Xq4i61cIrMu1hLrA8hUCS+oEQKY+2bxCYENPzhBQBuUrBKTFi9lBKbXFKwSwVUod+JNE8RqBgj9XzKgPGheoeuEMEx6FuoyEGAFPDMQJTwIfeuR9/t6QQw+fp0Go3wbcoWKGrn4jCOHpj6K1WtmWZa/UWn8ceejo74OhiCmEsQj198IOBDUiPZSwLPpjof0PlBL/mrd3GwiBIAiiAgRYCOcMfOzNP70TpNBCr4kAaX8zPVX+B6IluJ4luKIlSDbhOpZzms5lrMEmTI7hfoz3O/bgGEYX0f17s/07uYjCq3ib5y27iv1jxJ9jXpDwkowXpbws940Jb814c8rbcx5Q+IiGh1Q8puNBpY9qeVjt43o+sOAjGz+04mM7P7jko1s/vObjew8wcITDQywc4/Egk0e5OMzmcT4PNHqkk0OtHuv1YLNHuz3c7vF+Lzh4xcNLLgWajxedvOpVILt53a9AeCxQPguk1wLtt0B8blC/C+T3L/T/P3gDDpik2UVvAAAAAElFTkSuQmCC"
-  ))();
-  var ControllerCursor = class {
-    constructor(controller, game, axisId) {
-      __publicField(this, "axisId");
-      __publicField(this, "controller");
-      __publicField(this, "game");
-      __publicField(this, "pos");
-      this.controller = controller;
-      this.game = game;
-      this.axisId = axisId;
-      this.pos = game.canman.size.mult(0.5);
-    }
-    get centerPos() {
-      return this.pos.clone().add(CROSSHAIR.width * 0.5, CROSSHAIR.height * 0.5);
-    }
-    draw(context) {
-      context.drawImage(CROSSHAIR, this.pos.x, this.pos.y);
-    }
-    update(dt) {
-      const step = this.controller.stick(this.axisId).mult(SPEED * dt);
-      if (step.length() === 0) {
-        return;
-      }
-      this.pos.x = clamp(
-        this.pos.x + step.x,
-        0,
-        this.game.canman.width - CROSSHAIR.width
-      );
-      this.pos.y = clamp(
-        this.pos.y + step.y,
-        0,
-        this.game.canman.height - CROSSHAIR.height
-      );
-    }
-  };
-
   // src/input/Controller.ts
   var CONTROLLER_KEYS = {
+    /** Bottom face button — `A` on Xbox, `×` on PlayStation. */
     A: 0,
+    /** Right face button — `B` on Xbox, `○` on PlayStation. */
     B: 1,
+    /** Left face button — `X` on Xbox, `□` on PlayStation. */
     X: 2,
+    /** Top face button — `Y` on Xbox, `△` on PlayStation. */
     Y: 3,
+    /** Left bumper / shoulder. */
     LB: 4,
+    /** Right bumper / shoulder. */
     RB: 5,
+    /** Left trigger. The digital pressed-state lives here; the analog value is on the underlying `Gamepad.buttons[6].value`. */
     LT: 6,
+    /** Right trigger. The digital pressed-state lives here; the analog value is on the underlying `Gamepad.buttons[7].value`. */
     RT: 7,
+    /** Back / Select / Share. */
     SELECT: 8,
+    /** Start / Options / Menu. */
     START: 9,
+    /** Left stick click (L3). */
     LEFT_STICK: 10,
+    /** Right stick click (R3). */
     RIGHT_STICK: 11,
+    /** D-pad up. */
     UP: 12,
+    /** D-pad down. */
     DOWN: 13,
+    /** D-pad left. */
     LEFT: 14,
+    /** D-pad right. */
     RIGHT: 15,
+    /** Guide / Home / PS button. Not exposed by all browsers. */
     GUIDE: 16
   };
-  var AXIS_THRESHOLD = 0.3;
+  var DEADZONE = 0.25;
   var Controller = class {
-    constructor(game) {
+    constructor() {
+      /** Pressed-state per button, indexed in the same order as the underlying `Gamepad.buttons`. Index with {@link CONTROLLER_KEYS}. Updated by {@link poll}; empty until the first non-cached poll. */
       __publicField(this, "buttons", []);
-      __publicField(this, "cursors", []);
       __publicField(this, "axes", []);
       __publicField(this, "index", -1);
       __publicField(this, "lastTime", 0);
@@ -3307,11 +3576,11 @@ var Gleam = (() => {
         console.error("Controller not supported!");
         return;
       }
-      for (let i = 0; i < 2; i++) {
-        this.cursors.push(new ControllerCursor(this, game, i));
-      }
       window.addEventListener("gamepadconnected", (event) => {
         this.index = event.gamepad.index;
+        for (let i = 0; i < event.gamepad.axes.length / 2; i++) {
+          this.axes.push(new Vec2());
+        }
         console.log("Gamepad connected:", event.gamepad.id);
         EventSystem.dispatchEvent(
           "inputControllerConnected",
@@ -3328,6 +3597,7 @@ var Gleam = (() => {
               "Our Gamepad was disconnected:",
               event.gamepad.index
             );
+            this.reset();
             EventSystem.dispatchEvent("inputControllerDisconnected");
           } else {
             console.log(
@@ -3339,32 +3609,35 @@ var Gleam = (() => {
       );
       window.addEventListener("blur", () => this.reset(), false);
     }
-    draw(context) {
-      if (this.index < 0) {
-        return;
-      }
-      this.cursors.forEach((cursor) => cursor.draw(context));
-    }
-    update(dt) {
-      this.cursors.forEach((cursor) => cursor.update(dt));
+    /** Read the current gamepad state and return one {@link Vec2} per stick pair with a circular deadzone applied (`0.25` inner radius, output magnitude clamped to `[0, 1]`). The returned array (and each `Vec2` in it) is reused across calls — clone if you need to retain. Also refreshes {@link buttons}. Returns the cached array unchanged when the gamepad timestamp hasn't advanced. */
+    poll() {
       const gp = this.getGamepad();
       if (!gp || this.lastTime === gp.timestamp) {
-        return;
+        return this.axes;
       }
       this.lastTime = gp.timestamp;
       this.buttons = gp.buttons.map(
         (button) => button.pressed
       );
-      this.axes.length = 0;
-      const axes = gp.axes;
-      for (let i = 0; i + 1 < axes.length; i += 2) {
-        this.axes.push(new Vec2(axes[i], axes[i + 1]));
+      for (let i = 0; i < this.axes.length; i++) {
+        this.axes[i].set(gp.axes[i * 2], gp.axes[i * 2 + 1]);
+        const mag = this.axes[i].length();
+        if (mag < DEADZONE) {
+          this.axes[i].set(0, 0);
+        } else {
+          this.axes[i].mult(
+            (Math.min(1, mag) - DEADZONE) / (1 - DEADZONE) / mag
+          );
+        }
       }
+      return this.axes;
     }
+    /** Clear {@link buttons} and the cached stick axes. Called automatically on `window` blur and on gamepad disconnect. */
     reset() {
       this.buttons.length = 0;
       this.axes.length = 0;
     }
+    /** Trigger a 400 ms full-strength dual-rumble pulse. Returns `false` when no gamepad is connected or the pad has no `vibrationActuator`; `true` when the effect was dispatched. */
     vibrate() {
       const gp = this.getGamepad();
       if (!gp) {
@@ -3381,14 +3654,6 @@ var Gleam = (() => {
       }
       return !!vibrator;
     }
-    stick(index) {
-      if (this.index < 0 || index >= this.axes.length) {
-        return new Vec2();
-      }
-      return this.axes[index].clone().map((value) => threshold(value, AXIS_THRESHOLD)).map(
-        (value) => Math.sign(value) * map(Math.abs(value), AXIS_THRESHOLD, 1, 0, 1)
-      );
-    }
     getGamepad() {
       return this.index < 0 ? null : navigator.getGamepads()[this.index] ?? null;
     }
@@ -3427,8 +3692,9 @@ var Gleam = (() => {
       this.addPoints(...points);
     }
     /**
-     * `angle` is the simplification threshold in radians: vertices whose turn
-     * angle wraps to within ±`angle` of straight are dropped.
+     * Trace an outline around the opaque pixels of `canvas` via four directional sweeps (top, right, bottom, left). `detail` is the pixel stride (≥ 2) between scanline samples — higher = faster but coarser. `angle` is the simplification threshold in radians: vertices whose turn angle wraps to within ±`angle` of straight are dropped. Throws if fewer than 3 vertices survive.
+     *
+     * **Convex shapes only.** The sweep ignores anything an outer-perimeter ray can't reach: holes (donuts), inward bays (a "C" opening sideways), or any row/column with multiple disjoint opaque spans. For those inputs the result is either a broken polygon or simply the outer hull, and {@link Polygon.collide} relies on convexity anyway.
      */
     static fromCanvas(canvas, detail, angle) {
       detail = Math.max(2, detail);
@@ -3530,6 +3796,7 @@ var Gleam = (() => {
       }
       return new _Polygon(...points);
     }
+    /** Regular convex polygon with `edges` vertices, inscribed in a bounding box of `size` (number = square). */
     static fromEdges(edges, size) {
       const s = size instanceof Vec2 ? size : new Vec2(size, size);
       const rad = Math.min(s.x, s.y) * 0.5;
@@ -3550,6 +3817,7 @@ var Gleam = (() => {
       }
       return new _Polygon(...points);
     }
+    /** Polygon from the four corners of `rect`. */
     static fromRect(rect) {
       return new _Polygon(
         new Vec2(rect.x, rect.y),
@@ -3558,12 +3826,15 @@ var Gleam = (() => {
         new Vec2(rect.x, rect.y + rect.h)
       );
     }
+    /** Centroid (mean of vertex positions). Recomputed whenever the vertex set changes. */
     get center() {
       return this._center;
     }
+    /** Read-only view of the current vertex list. Use `addPoint`/`offset`/`rotate` to mutate. */
     get points() {
       return this._points;
     }
+    /** Stroke the polygon to `context`, shifted by `offset`. Coordinates are truncated to integers (via `| 0`) for crisp lines. */
     draw(context, offset = new Vec2()) {
       if (this._points.length === 0) {
         return;
@@ -3582,21 +3853,25 @@ var Gleam = (() => {
       context.closePath();
       context.stroke();
     }
+    /** Append a single vertex at `(x, y)`. Mutates and returns `this`. */
     addPoint(x, y) {
       this._points.push(new Vec2(x, y));
       this.update();
       return this;
     }
+    /** Append cloned copies of every passed vertex. Mutates and returns `this`. */
     addPoints(...points) {
       points.forEach((point) => this._points.push(point.clone()));
       this.update();
       return this;
     }
+    /** Translate every vertex by `(x, y)`. Mutates and returns `this`. */
     offset(x = 0, y = 0) {
       this._points.forEach((point) => point.add(x, y));
       this.update();
       return this;
     }
+    /** Rotate by `angle` radians around `pos` (defaults to the centroid). Mutates and returns `this`. */
     rotate(angle, pos = this.center) {
       if (!angle) {
         return this;
@@ -3611,6 +3886,7 @@ var Gleam = (() => {
       this.update();
       return this;
     }
+    /** SAT collision against `otherPolygon`. **Both polygons must be convex** — SAT silently misses collisions for concave shapes. Pass a non-zero `velocity` to also compute whether the polygons would intersect after that displacement. Warns and returns a no-collision result if either polygon has zero edges. */
     collide(otherPolygon, velocity = new Vec2()) {
       const result = {
         intersect: true,
@@ -3678,6 +3954,7 @@ var Gleam = (() => {
       }
       return result;
     }
+    /** New `Polygon` with the same vertices. */
     clone() {
       return new _Polygon(...this._points);
     }