@cosmoledo/gleam 1.0.0 → 1.0.2

package/dist/gleam.esm.js

@@ -84,6 +84,9 @@ function urlBasename(path) {
 
 // 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() {
@@ -118,6 +121,7 @@ var _EventSystem = class _EventSystem {
     }
     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) {
@@ -165,21 +169,25 @@ var MEDIA_ERROR_CODES = {
 };
 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) {
@@ -208,6 +216,7 @@ var AudioBase = class {
       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) {
@@ -286,7 +295,7 @@ var EASINGS = {
   "ease-in": easeIn,
   "ease-in-out": easeInOut,
   "ease-out": easeOut,
-  "linear": linear
+  linear
 };
 
 // src/utilities/Array.ts
@@ -337,18 +346,24 @@ var Music = class extends AudioBase {
     __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"
@@ -425,6 +440,7 @@ var Music = class extends AudioBase {
       }
     });
   }
+  /** 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?.();
@@ -456,6 +472,7 @@ var Sound = class extends AudioBase {
     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!");
@@ -481,6 +498,7 @@ var Sound = class extends AudioBase {
       throw err;
     });
   }
+  /** Stop and forget every currently-playing clone. Also calls the base-class teardown. */
   stop() {
     super.stop();
     this.currentSounds.forEach((audio) => audio.stop());
@@ -640,6 +658,7 @@ var Color = class _Color {
     __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)) {
@@ -660,6 +679,7 @@ var Color = class _Color {
     }
     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;
@@ -676,18 +696,23 @@ var Color = class _Color {
     }
     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);
@@ -698,6 +723,7 @@ var Color = class _Color {
     }
     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,
@@ -705,9 +731,11 @@ var Color = class _Color {
       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(
@@ -716,6 +744,7 @@ var Color = class _Color {
       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);
@@ -728,6 +757,7 @@ var Color = class _Color {
     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);
@@ -742,6 +772,7 @@ var Color = class _Color {
     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,
@@ -749,6 +780,7 @@ var Color = class _Color {
       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(
@@ -758,6 +790,7 @@ var Color = class _Color {
       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),
@@ -765,6 +798,7 @@ var Color = class _Color {
       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;
@@ -777,6 +811,7 @@ var Color = class _Color {
     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);
@@ -789,6 +824,7 @@ var Color = class _Color {
     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);
@@ -798,6 +834,7 @@ var Color = class _Color {
       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");
@@ -809,6 +846,7 @@ var Color = class _Color {
     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);
@@ -816,6 +854,7 @@ var Color = class _Color {
     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;
@@ -843,15 +882,18 @@ var Color = class _Color {
     }
     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));
   }
@@ -993,12 +1035,14 @@ var Rect = class _Rect {
     __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!");
@@ -1023,34 +1067,43 @@ var Rect = class _Rect {
     });
     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 = {
@@ -1066,6 +1119,7 @@ var Rect = class _Rect {
     }
     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;
@@ -1074,12 +1128,16 @@ var Rect = class _Rect {
     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;
@@ -1101,15 +1159,19 @@ var Rect = class _Rect {
     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);
@@ -1127,18 +1189,23 @@ var Rect = class _Rect {
     }
     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) {
@@ -1170,25 +1237,31 @@ var warnNonFinite = throttle(
 );
 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]);
@@ -1197,9 +1270,19 @@ var Vec2 = class _Vec2 {
   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);
@@ -1211,9 +1294,11 @@ var Vec2 = class _Vec2 {
   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)) {
@@ -1222,6 +1307,7 @@ var Vec2 = class _Vec2 {
     }
     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)) {
@@ -1232,6 +1318,7 @@ var Vec2 = class _Vec2 {
   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);
@@ -1240,38 +1327,48 @@ var Vec2 = class _Vec2 {
   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];
   }
@@ -1281,9 +1378,11 @@ var Vec2 = class _Vec2 {
   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);
   }
@@ -1363,9 +1462,11 @@ var Vec2 = class _Vec2 {
 // 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");
@@ -1405,6 +1506,7 @@ var Settings = class {
     }
     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(
@@ -1413,16 +1515,27 @@ var Settings = class {
     );
   }
 };
+/** 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
@@ -2015,19 +2128,20 @@ function getUsedColors(image, pixelAmount = 1, removeLowerThan = 0, removeHigher
 // 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);
@@ -2055,9 +2169,11 @@ var _Animator = class _Animator {
       }
     });
   }
+  /** 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,
@@ -2065,6 +2181,7 @@ var _Animator = class _Animator {
       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;
@@ -2108,6 +2225,7 @@ var _Animator = class _Animator {
       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!");
@@ -2125,6 +2243,7 @@ var _Animator = class _Animator {
       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,
@@ -2133,6 +2252,7 @@ var _Animator = class _Animator {
       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;
@@ -2143,6 +2263,7 @@ var _Animator = class _Animator {
     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
@@ -2165,6 +2286,7 @@ var _Animator = class _Animator {
     }
     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);
@@ -2172,6 +2294,7 @@ var _Animator = class _Animator {
     }
     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;
   }
@@ -2182,9 +2305,11 @@ var _Animator = class _Animator {
     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;
@@ -2192,6 +2317,7 @@ var _Animator = class _Animator {
     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
@@ -2203,6 +2329,7 @@ var _Animator = class _Animator {
       this.active = false;
     }
   }
+  /** `true` when `name` matches the currently-playing animation. */
   isPlaying(name) {
     return this.current && this.current.name === name;
   }
@@ -2241,15 +2368,63 @@ var _Animator = class _Animator {
 __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;
@@ -2262,12 +2437,15 @@ var Particle = class {
     );
     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(
@@ -2279,12 +2457,14 @@ var Particle = class {
       "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;
   }
@@ -2293,14 +2473,23 @@ var Particle = class {
 // 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();
@@ -2309,12 +2498,15 @@ var Projectile = class {
     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,
@@ -2322,6 +2514,7 @@ var Projectile = class {
       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;
@@ -2329,8 +2522,7 @@ var Projectile = class {
     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);
@@ -2338,6 +2530,7 @@ var Projectile = class {
     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;
   }
@@ -2345,40 +2538,56 @@ var Projectile = class {
 
 // 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.");
@@ -2401,6 +2610,7 @@ var CanvasManager = class {
       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) => {
@@ -2426,10 +2636,12 @@ var CanvasManager = class {
     });
     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!");
     }
@@ -2458,6 +2670,7 @@ var MAX_DT_SECONDS = 0.25;
 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);
@@ -2465,9 +2678,11 @@ var Gameloop = class {
     __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(
@@ -2477,6 +2692,7 @@ var Gameloop = class {
     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;
   }
@@ -2534,53 +2750,98 @@ var Gameloop = class {
 
 // 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;
@@ -2601,14 +2862,17 @@ var Keyboard = class {
     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];
   }
@@ -2616,20 +2880,32 @@ var Keyboard = class {
 
 // 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;
@@ -2662,6 +2938,7 @@ var Pointer = class {
       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;
   }
@@ -3002,9 +3279,13 @@ defineMethod(
 // 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);
@@ -3013,17 +3294,21 @@ var Game = class {
     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(
@@ -3050,8 +3335,11 @@ var Game = class {
 
 // 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);
@@ -3059,8 +3347,11 @@ var SHAKE_TYPES = {
       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)`);
     }
@@ -3073,7 +3364,7 @@ var Screenshake = class {
     __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;
@@ -3111,72 +3402,48 @@ var Screenshake = class {
   }
 };
 
-// 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);
@@ -3184,11 +3451,11 @@ var Controller = class {
       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",
@@ -3205,6 +3472,7 @@ var Controller = class {
             "Our Gamepad was disconnected:",
             event.gamepad.index
           );
+          this.reset();
           EventSystem.dispatchEvent("inputControllerDisconnected");
         } else {
           console.log(
@@ -3216,32 +3484,35 @@ var Controller = class {
     );
     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) {
@@ -3258,14 +3529,6 @@ var Controller = class {
     }
     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;
   }
@@ -3304,8 +3567,9 @@ var Polygon = class _Polygon {
     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);
@@ -3407,6 +3671,7 @@ var Polygon = class _Polygon {
     }
     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;
@@ -3427,6 +3692,7 @@ var Polygon = class _Polygon {
     }
     return new _Polygon(...points);
   }
+  /** Polygon from the four corners of `rect`. */
   static fromRect(rect) {
     return new _Polygon(
       new Vec2(rect.x, rect.y),
@@ -3435,12 +3701,15 @@ var Polygon = class _Polygon {
       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;
@@ -3459,21 +3728,25 @@ var Polygon = class _Polygon {
     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;
@@ -3488,6 +3761,7 @@ var Polygon = class _Polygon {
     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,
@@ -3555,6 +3829,7 @@ var Polygon = class _Polygon {
     }
     return result;
   }
+  /** New `Polygon` with the same vertices. */
   clone() {
     return new _Polygon(...this._points);
   }
@@ -3711,6 +3986,8 @@ export {
   Gameloop,
   KEYBOARD_KEYS,
   Keyboard,
+  MAX_DT_SECONDS,
+  MAX_STEPS_PER_FRAME,
   Music,
   POINTER_KEYS,
   Particle,