@cosmoledo/gleam 1.0.1 → 1.0.2

package/dist/gleam.d.ts

@@ -1,18 +1,30 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/** Entry shape passed to {@link AudioBase.register}. */
 export interface RegisterData {
+	/** URL or relative path to the audio file. */
 	path: string;
+	/** Identifier used by `play(name)` / `fade(name)`. */
 	name: string;
+	/** Per-song volume override in `[0, 1]`. Falls back to `register`'s `defaultVolume`. */
 	volume?: number;
 }
+/**
+ * Shared registration, enable/disable, and teardown machinery for {@link Sound} and {@link Music}. Auto-subscribes to the `"gameloopStopped"` event so playback halts on loop teardown.
+ */
 export declare abstract class AudioBase {
+	/** Registered audio elements keyed by name. Subclasses read this; mutate via {@link register}. */
 	protected songs: Map<string, HTMLAudioElement>;
 	private _enabled;
 	private registered;
+	/** Whether playback is permitted. Setting to `false` invokes {@link stop} immediately. */
 	get enabled(): boolean;
+	/** Setting to `false` invokes {@link stop} immediately; subclasses (notably {@link Music}) may re-start playback when flipped back to `true`. */
 	set enabled(value: boolean);
 	constructor(enabled?: boolean);
+	/** 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?: number, ...songs: (RegisterData | string)[]): void;
+	/** 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(): void;
 	private throwOnBadVolume;
 }
@@ -32,64 +44,119 @@ export declare function easeOut(t: number): number;
  * Identity (constant rate of change).
  */
 export declare function linear(t: number): number;
+/** Names of the built-in easing curves. Use as a key into {@link EASINGS}. */
 export type EasingName = "ease-in" | "ease-in-out" | "ease-out" | "linear";
+/** Lookup table from {@link EasingName} to its easing function (`t ∈ [0, 1] → eased t`). */
 export declare const EASINGS: Record<EasingName, (t: number) => number>;
+/**
+ * Background music with eased cross-fades. Tracks auto-cycle: when the current track ends, the next one fades in. Inherits registration, enable/disable, and volume from {@link AudioBase}.
+ *
+ * Random track picking excludes the previous two songs to avoid back-to-back repeats. If only one track is registered, it's looped instead of faded.
+ */
 export declare class Music extends AudioBase {
 	private last;
 	private current;
 	private next;
 	private fadeCancel;
+	/** `true` while a fade is in progress OR the current track is actively playing. */
 	get isPlaying(): boolean;
+	/** Whether music playback is permitted (inherited from {@link AudioBase}). */
 	get enabled(): boolean;
+	/** Flipping from `false` to `true` while no music is playing auto-starts a fade-in to a random track. */
 	set enabled(value: boolean);
+	/**
+	 * 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?: string | null, fadeTime?: number, easing?: {
 		cur: EasingName;
 		next: EasingName;
 	}): void;
+	/** 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(): void;
 	private getRandom;
 }
+/** One-shot SFX. Each {@link play} call clones the registered `HTMLAudioElement` so the same sound can overlap itself; {@link stop} cuts every in-flight clone. Inherits registration, enable/disable, and volume from {@link AudioBase}. */
 export declare class Sound extends AudioBase {
 	private 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: string): Promise<void>;
+	/** Stop and forget every currently-playing clone. Also calls the base-class teardown. */
 	stop(): void;
 }
+/** Components returned by {@link Color.toHSLObject}. */
+export interface HSLObject {
+	/** Hue in degrees, `[0, 360]`. */
+	h: number;
+	/** Saturation in percent, `[0, 100]`. */
+	s: number;
+	/** Lightness in percent, `[0, 100]`. */
+	l: number;
+	/** Alpha in `[0, 1]`. */
+	a: number;
+}
+/**
+ * RGBA color with chainable mutators. Channels are stored clamped (`r/g/b` ∈ `[0, 255]`, `alpha` ∈ `[0, 1]`) — every mutator routes through {@link set}, so direct field writes aren't possible and clamping/rounding is uniform.
+ *
+ * **Hue unit gotcha**: {@link fromHSL} takes hue in **degrees** (CSS convention), but {@link hueRotate} takes **radians** (codebase convention). Use `Math.PI` etc. for hueRotate.
+ *
+ * All `to*` methods return CSS-compatible strings; `toHSLObject` returns the components as numbers if you need to mutate them.
+ */
 export declare class Color {
+	/** Parse `#rgb`, `#rgba`, `#rrggbb`, or `#rrggbbaa` (case-insensitive, `#` optional). Throws on any other shape or on non-hex characters. */
 	static fromHex(hex: string): Color;
+	/** 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: number, s: number, l: number, a?: number): Color;
 	private _r;
 	private _g;
 	private _b;
 	private _alpha;
+	/** Red channel, `[0, 255]`. Read-only; mutate via {@link set} or any chainable transform. */
 	get r(): number;
+	/** Green channel, `[0, 255]`. Read-only; mutate via {@link set} or any chainable transform. */
 	get g(): number;
+	/** Blue channel, `[0, 255]`. Read-only; mutate via {@link set} or any chainable transform. */
 	get b(): number;
+	/** Alpha channel, `[0, 1]`. Read-only; mutate via {@link set} (pass the fourth arg). */
 	get alpha(): number;
 	constructor(r: number, g: number, b: number, a?: number);
+	/** 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: number, g: number, b: number, a?: number): 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: number, m2: number, m3: number, m4: number, m5: number, m6: number, m7: number, m8: number, m9: number): this;
+	/** Multiply each channel by `factor`. `factor < 1` darkens, `factor > 1` brightens (clamped at 255). Mutates and returns `this`. */
 	brightness(factor: number): this;
+	/** 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: number): this;
+	/** 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?: number): this;
+	/** Rotate hue by `radians` (use `Math.PI / 2` etc.). Unlike {@link fromHSL}, this takes radians, not degrees. Mutates and returns `this`. */
 	hueRotate(radians: number): this;
+	/** 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?: number): this;
+	/** Linear blend toward `other`. `amount` in `[0, 1]`: `0` keeps `this`, `1` becomes `other`. Mixes alpha too. Mutates and returns `this`. */
 	mix(other: Color, amount: number): this;
+	/** Round each RGB channel to the nearest integer. Alpha is untouched. Mutates and returns `this`. */
 	round(): this;
+	/** 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?: number): this;
+	/** Sepia matrix. `value` in `[0, 1]`: `0` is unchanged, `1` is full sepia. Mutates and returns `this`. */
 	sepia(value?: number): this;
+	/** 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: number): this;
+	/** CSS hex string. `#rrggbb` when alpha is exactly `1`, `#rrggbbaa` otherwise. Channels are rounded. */
 	toHex(): string;
+	/** CSS HSL string. `hsl(h, s%, l%)` when alpha is exactly `1`, `hsla(...)` otherwise. Hue is in degrees. */
 	toHSL(): string;
-	toHSLObject(): {
-		h: number;
-		s: number;
-		l: number;
-		a: number;
-	};
+	/** 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(): HSLObject;
+	/** CSS RGB string. `rgb(r, g, b)` when alpha is exactly `1`, `rgba(r, g, b, a)` otherwise. Channels are rounded. */
 	toRGB(): string;
+	/** New `Color` with the same channels. */
 	clone(): Color;
+	/** Approximate equality (within `approxEqual` tolerance). Pass `compareAlpha: false` to ignore the alpha channel. */
 	equals(other: Color, compareAlpha?: boolean): boolean;
 }
+/** `[r, g, b]` tuple of integer channel values, each in `[0, 255]`. */
 export type RGB = [
 	number,
 	number,
@@ -134,42 +201,69 @@ export declare function randomRgb(min?: number, max?: number): RGB;
  * console.log(colorShifter(randomRgb(1, 10)));
  */
 export declare function colorShifter(rgb: RGB): string;
+/** Result of a {@link Polygon.collide} call. */
 export interface PolygonCollisionResult {
+	/** `true` if the polygons currently overlap. */
 	intersect: boolean;
+	/** Smallest displacement that would separate the polygons (zero `Vec2` when they're disjoint). */
 	minimumTranslationVector: Vec2;
+	/** `true` if applying the `velocity` passed to `collide` would put the polygons into contact. */
 	willIntersect: boolean;
 }
+/**
+ * Convex 2D polygon. **The collision API ({@link Polygon.collide}) uses SAT, which is mathematically defined only for convex polygons** — feeding it a concave polygon silently produces wrong results.
+ */
 export declare class Polygon {
 	/**
-	 * `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: HTMLCanvasElement, detail: number, angle: number): Polygon;
+	/** Regular convex polygon with `edges` vertices, inscribed in a bounding box of `size` (number = square). */
 	static fromEdges(edges: number, size: Vec2 | number): Polygon;
+	/** Polygon from the four corners of `rect`. */
 	static fromRect(rect: Rect): Polygon;
 	private _center;
 	private _points;
 	private edges;
+	/** Centroid (mean of vertex positions). Recomputed whenever the vertex set changes. */
 	get center(): Readonly<Vec2>;
+	/** Read-only view of the current vertex list. Use `addPoint`/`offset`/`rotate` to mutate. */
 	get points(): Readonly<Vec2[]>;
 	constructor(...points: Vec2[]);
+	/** Stroke the polygon to `context`, shifted by `offset`. Coordinates are truncated to integers (via `| 0`) for crisp lines. */
 	draw(context: CanvasRenderingContext2D, offset?: Vec2): void;
+	/** Append a single vertex at `(x, y)`. Mutates and returns `this`. */
 	addPoint(x: number, y: number): Polygon;
+	/** Append cloned copies of every passed vertex. Mutates and returns `this`. */
 	addPoints(...points: Vec2[]): Polygon;
+	/** Translate every vertex by `(x, y)`. Mutates and returns `this`. */
 	offset(x?: number, y?: number): Polygon;
+	/** Rotate by `angle` radians around `pos` (defaults to the centroid). Mutates and returns `this`. */
 	rotate(angle: number, pos?: Readonly<Vec2>): 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: Polygon, velocity?: Vec2): PolygonCollisionResult;
+	/** New `Polygon` with the same vertices. */
 	clone(): Polygon;
 	private update;
 }
+/** Derived geometry returned by {@link Rect.sides}. */
 export interface Sides {
+	/** Lower edge (`y + h`). */
 	bottom: number;
+	/** Center point. */
 	centerPos: Vec2;
+	/** Half the width and height. */
 	halfSize: Vec2;
+	/** Right edge (`x + w`). */
 	right: number;
 }
+/** Axis-aligned 2D rectangle (`x`, `y`, `w`, `h`). */
 export declare class Rect {
+	/** Build from an `HTMLElement` (via `getBoundingClientRect`) or a `DOMRect`. */
 	static fromBoundingClientRect(rect: DOMRect | HTMLElement): Rect;
+	/** Axis-aligned bounding box of a polygon's points. Throws if the polygon has no points. */
 	static fromPolygon(polygon: Polygon): Rect;
 	private _h;
 	private _w;
@@ -177,35 +271,64 @@ export declare class Rect {
 	private _y;
 	private _sides;
 	private sideIsDirty;
+	/** Height. */
 	get h(): number;
+	/** Height. */
 	set h(value: number);
+	/** Width. */
 	get w(): number;
+	/** Width. */
 	set w(value: number);
+	/** Top-left x. */
 	get x(): number;
+	/** Top-left x. */
 	set x(value: number);
+	/** Top-left y. */
 	get y(): number;
+	/** Top-left y. */
 	set y(value: number);
+	/** Derived sides/center/halfSize. Lazily recomputed after any `x`/`y`/`w`/`h` change. */
 	get sides(): Readonly<Sides>;
 	constructor(x?: number, y?: number, w?: number, h?: number);
+	/** 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: number): Rect;
+	/** Round `x` and `y` to the nearest integer. `w`/`h` are unchanged. Mutates and returns `this`. */
 	round(): Rect;
+	/**
+	 * 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?: Vector4 | Vector2 | number, y?: number, w?: number, h?: number): Rect;
+	/** AABB-vs-AABB overlap test (inclusive of touching edges). */
 	collide(rect: Rect): boolean;
+	/** `true` when `rect` is fully inside `this`. */
 	collideFull(rect: Rect): boolean;
+	/** `true` when `vec` lies inside `this` (inclusive of edges). */
 	collidePoint(vec: Vector2): boolean;
+	/** Side of `this` that `rect` overlaps from, or `"none"` if disjoint. Useful for picking a bounce axis. */
 	collideSide(rect: Rect): "none" | "top" | "bottom" | "left" | "right";
+	/** Top-left corner as a new `Vec2`. */
 	pos(): Vec2;
+	/** Width and height as a new `Vec2`. */
 	size(): Vec2;
+	/** Debug string like `"Rect [x: 0, y: 0, w: 10, h: 20]"`. */
 	toString(): string;
+	/** New `Rect` with the same values. */
 	clone(): Rect;
+	/** Approximate equality. Pass `withSize: false` to compare position only. */
 	equals(other: Rect, withSize?: boolean): boolean;
 }
+/** Object literal compatible with `Vec2` (e.g. `{ x, y }`). */
 export interface Vector2 {
+	/** Horizontal component. */
 	x: number;
+	/** Vertical component. */
 	y: number;
 }
+/** {@link Vector2} plus `w`/`h` for AABB-style values. */
 export interface Vector4 extends Vector2 {
+	/** Width. */
 	w: number;
+	/** Height. */
 	h: number;
 }
 /**
@@ -214,16 +337,24 @@ export interface Vector4 extends Vector2 {
  * both. Pass `(x, y)` or a `Vector2` for per-axis values.
  */
 export declare class Vec2 {
+	/** Unit vector at angle `rad` (radians), scaled per-axis. `scaleY` defaults to `scaleX`. */
 	static fromAngle(rad: number, scaleX?: number, scaleY?: number): Vec2;
+	/** Horizontal component. */
 	x: number;
+	/** Vertical component. */
 	y: number;
 	constructor(x?: Vector2 | number, y?: number);
+	/** Replace components. Mutates and returns `this`. */
 	set(v: Vector2): Vec2;
 	set(x: number, y?: number): Vec2;
+	/** Set each component to its absolute value. Mutates and returns `this`. */
 	abs(): Vec2;
+	/** Per-axis add. Mutates and returns `this`. */
 	add(v: Vector2): Vec2;
 	add(x: number, y?: number): Vec2;
+	/** Round each component up. Mutates and returns `this`. */
 	ceil(): Vec2;
+	/** Clamp each axis to its `[min, max]` range. `y` defaults to `x`. Mutates and returns `this`. */
 	clamp(x: [
 		number,
 		number
@@ -231,70 +362,125 @@ export declare class Vec2 {
 		number,
 		number
 	]): Vec2;
+	/** Per-axis divide. Mutates and returns `this`. */
 	div(v: Vector2): Vec2;
 	div(x: number, y?: number): Vec2;
+	/** Round each component down. Mutates and returns `this`. */
 	floor(): Vec2;
+	/**
+	 * 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: (value: number, index: number) => number): Vec2;
+	/** Per-axis Euclidean modulo (result sign matches the divisor). Mutates and returns `this`. */
 	mod(v: Vector2): Vec2;
 	mod(x: number, y?: number): Vec2;
+	/** Per-axis multiply. Mutates and returns `this`. */
 	mult(v: Vector2): Vec2;
 	mult(x: number, y?: number): Vec2;
+	/** Flip the sign of both components (same as `mult(-1)`). Mutates and returns `this`. */
 	negate(): Vec2;
+	/** Scale to unit length. Zero-length vectors are left untouched and warn (throttled). Mutates and returns `this`. */
 	normalize(): Vec2;
+	/** Scale so `|x| + |y| === 1`. Zero-length vectors are left untouched. Mutates and returns `this`. */
 	normalizeManhattan(): Vec2;
+	/** Per-axis remainder (JavaScript `%`, sign follows the dividend). Mutates and returns `this`. */
 	rem(v: Vector2): Vec2;
 	rem(x: number, y?: number): Vec2;
+	/** Round each component to the nearest integer. Mutates and returns `this`. */
 	round(): Vec2;
+	/** Per-axis subtract. Mutates and returns `this`. */
 	sub(v: Vector2): Vec2;
 	sub(x: number, y?: number): Vec2;
+	/** Angle in radians. No arg: angle of `this` from origin. With `other`: angle from `this` toward `other`. */
 	angle(other?: Vector2): number;
+	/** Euclidean distance to `other`. */
 	distance(other: Vector2): number;
+	/** Manhattan distance (`|dx| + |dy|`) to `other`. */
 	distanceManhattan(other: Vector2): number;
+	/** Dot product with `other`. */
 	dotProduct(other: Vector2): number;
+	/** `true` when both components are finite (rules out `NaN` and `±Infinity`). */
 	isValid(): boolean;
+	/** Euclidean magnitude (`sqrt(x² + y²)`). */
 	length(): number;
+	/** Manhattan magnitude (`|x| + |y|`). */
 	lengthManhattan(): number;
+	/** Larger of the two components. */
 	max(): number;
+	/** Smaller of the two components. */
 	min(): number;
+	/** Tuple `[x, y]`. */
 	toArray(): [
 		number,
 		number
 	];
+	/** Build a `Rect` with the argument as position and `this` as size. */
 	toRectAddPos(v: Vector2): Rect;
 	toRectAddPos(x: number, y?: number): Rect;
+	/** Build a `Rect` with `this` as position and the argument as size. */
 	toRectAddSize(v: Vector2): Rect;
 	toRectAddSize(x: number, y?: number): Rect;
+	/** Debug string like `"Vec2 [x: 1, y: 2]"`. */
 	toString(): string;
+	/** New `Vec2` with the same components. */
 	clone(): Vec2;
+	/** Approximate equality (within `approxEqual` tolerance). Scalar broadcasts. */
 	equals(v: Vector2): boolean;
 	equals(x: number, y?: number): boolean;
 	private calculate;
 	private concat;
 	private getValues;
 }
+/** A named animation: a list of frame sprites and the per-frame `timing` (seconds). */
 export interface SpriteAnimation {
+	/** Mark this animation as the default — played by {@link Animator.reset} and right after {@link Animator.add} when registered. At most one per Animator. */
 	default?: boolean;
+	/** Unique identifier. Pass to {@link Animator.play}. */
 	name: string;
+	/** Frame images in playback order. Uniform size is assumed within a single animation. */
 	sprites: HTMLCanvasElement[] | HTMLImageElement[];
+	/** Seconds each frame stays visible before advancing. */
 	timing: number;
 }
+/** Fires once after the last frame of an animation plays. Cleared after firing. */
 export type onEndType = () => void;
+/** Map of `frameIndex → callback`. The callback for a given frame fires once when that frame becomes active, then is removed from the map. */
 export type onFrameType = Record<number, () => void>;
+/** Minimum shape an entity must satisfy to be animated by {@link Animator}. */
 export interface BaseEntity {
+	/** Top-left position used as the draw anchor. */
 	pos: Vec2;
+	/** Optional horizontal anchor offset for flipped frames. Defaults to the current sprite width on first render. */
 	flipX?: number;
 }
+/**
+ * Sprite-sheet animator. Hosts a list of named animations (registered via {@link add} / {@link addAnimation}) and drives them per-frame from `update(dt)`. Pre-renders each frame to a 2×-wide cached canvas keyed by `${namespace}.${animationName}` — so multiple entities sharing a `namespace` reuse the same rendered images.
+ *
+ * Use {@link play} to switch animations, {@link playOnce} for one-shot animations that fall back to the previous one, and {@link Animator.onEnd}/`onFrame` callbacks for frame- or animation-end hooks.
+ */
 export declare class Animator {
 	private static spriteCache;
 	/**
 	 * Drop cached rendered sprites. Pass a namespace to evict only that prefix; omit to clear all.
 	 */
 	static clearSpriteCache(namespace?: string): void;
+	/** 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. */
 	active: boolean;
+	/** Current rendered frame (after flip processing). Pulled from the cache by {@link setImage} every time the frame advances. */
 	image: HTMLCanvasElement;
+	/** Index of the current frame within the current animation's `sprites` array. */
 	imageId: number;
+	/** Flip the rendered sprite horizontally. Caches a separate "flipped" bucket so toggling is cheap. */
 	lookLeft: boolean;
+	/** One-shot callback that fires when the current animation's last frame finishes. Cleared after firing. */
 	onEnd: onEndType | undefined;
+	/** Current sprite's `(width, height)`. Updated by {@link setImage}. */
 	size: Vec2;
 	private animations;
 	private currentAnimation;
@@ -304,73 +490,195 @@ export declare class Animator {
 	private onFrame?;
 	private playVersion;
 	private timer;
+	/** The currently-playing animation. `undefined` if no animations have been added yet. */
 	get current(): SpriteAnimation;
 	/**
-	 * 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: BaseEntity, namespace: string);
+	/** Blit the current cached frame at `entity.pos + offset`, shifted left by `size.x` to compensate for the 2×-wide cache canvas. */
 	draw(context: CanvasRenderingContext2D, offset?: Vec2): void;
+	/** 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: number): void;
+	/** 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: string, sprites: HTMLCanvasElement[] | HTMLImageElement[], timing: number, defaultAnim?: boolean): void;
+	/** Convenience wrapper around {@link add} that takes a packed {@link SpriteAnimation}. `defaultAnim` is OR'd with `anim.default`. */
 	addAnimation(anim: SpriteAnimation, defaultAnim?: boolean): void;
+	/** 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: CanvasRenderingContext2D, angle: number, offset?: Vec2): void;
+	/** 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: string, onEnd?: onEndType, onFrame?: onFrameType): void;
+	/** {@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: string, onEnd?: onEndType, onFrame?: onFrameType): boolean;
+	/** Queue an animation to play once the current one finishes. Pass `undefined` to cancel the queue. Used internally by {@link playOnce}. */
 	playNextOnce(name: string | undefined): void;
 	/**
 	 * Play `name` once, then return to the previously-playing animation. Calling with the currently-playing name re-loops it indefinitely (lastPlayed restores to itself).
 	 */
 	playOnce(name: string, onEnd?: onEndType, onFrame?: onFrameType): void;
+	/** 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(): void;
+	/** Drop every registered animation and clear this instance's cached frames. {@link active} resets to `true`; pending callbacks are cleared. */
 	removeAllAnimations(): void;
+	/** Switch back to the default animation if one was registered (marked via `defaultAnim`); otherwise just stop animating ({@link active} = `false`). */
 	reset(): void;
+	/** `true` when `name` matches the currently-playing animation. */
 	isPlaying(name: string): boolean;
 	/**
 	 * Update `image` and `size` from the current sprite. Assumes uniform sprite size within an animation. Caches rendered canvases per (animation, frame, lookLeft) — if you mutate `entity.flipX` after first render, call `removeAllAnimations()` or recreate the Animator to invalidate.
 	 */
 	protected setImage(): void;
 }
+/** Button indices for the standard gamepad mapping (W3C Gamepad spec). Use as the index into {@link Controller.buttons}. */
+export declare const CONTROLLER_KEYS: {
+	/** Bottom face button — `A` on Xbox, `×` on PlayStation. */
+	readonly A: 0;
+	/** Right face button — `B` on Xbox, `○` on PlayStation. */
+	readonly B: 1;
+	/** Left face button — `X` on Xbox, `□` on PlayStation. */
+	readonly X: 2;
+	/** Top face button — `Y` on Xbox, `△` on PlayStation. */
+	readonly Y: 3;
+	/** Left bumper / shoulder. */
+	readonly LB: 4;
+	/** Right bumper / shoulder. */
+	readonly RB: 5;
+	/** Left trigger. The digital pressed-state lives here; the analog value is on the underlying `Gamepad.buttons[6].value`. */
+	readonly LT: 6;
+	/** Right trigger. The digital pressed-state lives here; the analog value is on the underlying `Gamepad.buttons[7].value`. */
+	readonly RT: 7;
+	/** Back / Select / Share. */
+	readonly SELECT: 8;
+	/** Start / Options / Menu. */
+	readonly START: 9;
+	/** Left stick click (L3). */
+	readonly LEFT_STICK: 10;
+	/** Right stick click (R3). */
+	readonly RIGHT_STICK: 11;
+	/** D-pad up. */
+	readonly UP: 12;
+	/** D-pad down. */
+	readonly DOWN: 13;
+	/** D-pad left. */
+	readonly LEFT: 14;
+	/** D-pad right. */
+	readonly RIGHT: 15;
+	/** Guide / Home / PS button. Not exposed by all browsers. */
+	readonly GUIDE: 16;
+};
+/**
+ * Gamepad input. The first connected gamepad becomes "our" gamepad; later ones are ignored until ours disconnects. Connection / disconnection fires {@link EventSystem} `"inputControllerConnected"` / `"inputControllerDisconnected"`.
+ *
+ * Poll {@link buttons} (indexed via {@link CONTROLLER_KEYS}) and {@link poll} from your `update`. State is cleared on `window` blur and on disconnect so held buttons / non-neutral sticks don't stay live across focus loss. Visualizing is not the controller's responsibility — see {@link ControllerCursor} for the built-in on-screen visualization, or read {@link poll} directly to drive your own.
+ *
+ * Logs to `console.error` if the browser doesn't expose the Gamepad API.
+ */
+export declare class Controller {
+	/** 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. */
+	buttons: boolean[];
+	private axes;
+	private index;
+	private lastTime;
+	constructor();
+	/** 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(): Vec2[];
+	/** Clear {@link buttons} and the cached stick axes. Called automatically on `window` blur and on gamepad disconnect. */
+	reset(): void;
+	/** 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(): boolean;
+	private getGamepad;
+}
+/**
+ * On-screen crosshairs driven by a {@link Controller}'s analog sticks. Each anchor in `sticks` gets its own crosshair that follows the corresponding stick's deflection with frame-rate-independent exponential smoothing (50 ms half-life). The caller owns the anchor positions and the crosshair image — any `CanvasImageSource` works (a loaded `HTMLImageElement`, a procedurally-drawn `HTMLCanvasElement`, an `ImageBitmap`, …).
+ *
+ * {@link update} polls the controller for you; don't call {@link Controller.poll} again from the same `update` step.
+ */
+export declare class ControllerCursor {
+	private controller;
+	private crosshair;
+	private range;
+	private sticks;
+	/**
+	 * @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: Controller, crosshair: CanvasImageSource, sticks: Vec2[], range?: number);
+	/** Draw a crosshair at `anchor + offset` for each tracked stick. */
+	draw(context: CanvasRenderingContext2D): void;
+	/** 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: number): void;
+}
+/**
+ * Single particle drawn as a filled circle. The constructor seeds a random velocity (random angle, per-axis speed in `[50, 150]` px/s) and a random `maxLifeTime` in `[0.5, 1.5]` s — spawn many at once for spark/dust effects. Each tick `update(dt)` advances `lifetime` and `pos`; the particle is "dead" when {@link alive} flips to `false`.
+ */
 export declare class Particle {
+	/** CSS color string passed to `context.fillStyle` in {@link draw}. */
 	protected color: string;
+	/** Accumulated time (seconds) since spawn or last {@link resetLifetime}. */
 	protected lifetime: number;
+	/** Lifetime cap in seconds, randomized to `[0.5, 1.5]` at construction. */
 	protected maxLifeTime: number;
+	/** Top-left position. Cloned from the constructor arg so the caller's `Vec2` isn't aliased. */
 	protected pos: Vec2;
+	/** Circle radius (pixels). */
 	protected size: number;
+	/** Velocity in px/s. Seeded randomly by the constructor (random angle, random magnitude per axis). */
 	protected vel: Vec2;
+	/** Backing storage for the {@link rect} getter. Subclasses can read it; the public-facing accessor is {@link rect}. */
 	protected _rect: Rect;
+	/** `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(): boolean;
+	/** Read-only AABB tracking `pos` and the particle's `size`. Recomputed each {@link update}. */
 	get rect(): Readonly<Rect>;
 	constructor(pos: Vec2, color: string, size?: number);
+	/** Fill a circle at `pos + offset` using {@link color}. `offset` is useful for shifting by a camera/world transform without mutating `pos`. */
 	draw(context: CanvasRenderingContext2D, offset?: Vec2): void;
+	/** Integrate lifetime, position, and bounding rect. */
 	update(dt: number): void;
+	/** 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(): void;
 }
+/**
+ * A self-propelled sprite — `update(dt)` advances `pos` along `vel * speed`, accumulates `lifetime`, and flips {@link alive} to `false` once `lifetime >= maxLifetime`. The image is pre-baked to a rotated canvas matching the velocity direction; call {@link rebuildRotation} after re-aiming.
+ *
+ * The `T` generic types the optional {@link payload} so callers can attach typed metadata (damage, owner, etc.) without losing inference.
+ */
 export declare class Projectile<T = unknown> {
+	/** Seconds after which {@link alive} flips to `false`. Defaults to `Infinity` — no natural expiry. */
 	maxLifetime: number;
+	/** Caller-supplied data. Typed via the class generic so consumers can read `projectile.payload` without casting. */
 	payload?: T;
+	/** Magnitude multiplier applied to `vel` each update: `pos += vel * speed * dt`. Pass a unit-length `vel` to make this read as "pixels per second". */
 	speed: number;
+	/** Current pre-rotated sprite. Re-baked by {@link rebuildRotation} from the un-rotated `originalImage`. */
 	protected image: HTMLCanvasElement;
+	/** Accumulated time (seconds). Drives the {@link alive} check against {@link maxLifetime}. */
 	protected lifetime: number;
+	/** Top-left position. Cloned from the constructor arg so the caller's `Vec2` isn't aliased. */
 	protected pos: Vec2;
+	/** Current sprite rotation in radians, kept in sync with `vel` by {@link rebuildRotation}. */
 	protected rotation: number;
+	/** 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. */
 	protected vel: Vec2;
+	/** Backing storage for the {@link rect} getter. Subclasses can read it; mutate via `pos`/{@link rebuildRotation} instead of touching it directly. */
 	protected _rect: Rect;
 	private originalImage;
+	/** `false` once {@link lifetime} reaches {@link maxLifetime}. Owners typically filter dead projectiles out of their list each frame. */
 	get alive(): boolean;
+	/** Read-only AABB tracking `pos` and the (rotated) image size. Recomputed in {@link update} and {@link rebuildRotation}. */
 	get rect(): Readonly<Rect>;
 	constructor(pos: Vec2, image: HTMLCanvasElement, vel?: Vec2);
+	/** Blit the pre-rotated image at `pos + offset`. `offset` is useful for shifting by a camera/world transform without mutating `pos`. */
 	draw(context: CanvasRenderingContext2D, offset?: Vec2): void;
+	/** Integrate motion and advance lifetime. Doesn't re-bake the rotation — call {@link rebuildRotation} after mutating `vel`. */
 	update(dt: number): void;
 	/**
-	 * 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(): void;
+	/** Force {@link alive} to `false` immediately (sets `lifetime` past `maxLifetime`). Use when the projectile should die on collision/impact, not from natural expiry. */
 	remove(): void;
 }
 declare global {
@@ -485,8 +793,11 @@ declare global {
 		toImage(): Promise<HTMLImageElement>;
 	}
 }
+/** A `<canvas>` element paired with its 2D rendering context. Returned by {@link createNewCanvas} / {@link getCanvasConstruct} and inherited by {@link CanvasHolder}. */
 export interface CanvasConstruct {
+	/** The `<canvas>` element. */
 	canvas: HTMLCanvasElement;
+	/** Its 2D rendering context. */
 	context: CanvasRenderingContext2D;
 }
 /**
@@ -523,118 +834,234 @@ export declare function splitSpriteSheet(img: HTMLCanvasElement, elementsX: numb
  * `removeLowerThan` / `removeHigherThan` drop entries outside the range; `0` disables either bound.
  */
 export declare function getUsedColors(image: HTMLCanvasElement, pixelAmount?: number, removeLowerThan?: number, removeHigherThan?: number): Map<string, number>;
+/** Role tags for canvases passed to {@link CanvasManager.setupCanvas}. Only `MAIN` is enforced (exactly one); the others are free-form labels you can use to group background/overlay canvases. */
 export declare const CANVAS_TYPES: {
+	/** Catch-all tag for canvases without a specific role. */
 	readonly ANY: symbol;
+	/** Generic placeholder tag — distinct from `ANY` so consumers can differentiate. */
 	readonly DEFAULT: symbol;
+	/** Background canvas (drawn behind the main one). */
 	readonly BACKGROUND: symbol;
+	/** Primary render target. Exactly one canvas must be registered with this type before {@link CanvasManager.finishSetup}. */
 	readonly MAIN: symbol;
 };
+/** Entry stored in {@link CanvasManager.canvasHolder} for each registered canvas. */
 export interface CanvasHolder extends CanvasConstruct {
+	/** Selector the canvas was registered under (also the map key). */
 	id: string;
+	/** Whether this canvas participates in {@link CanvasManager.resize} (rescaled to fit the window while preserving its buffer aspect ratio). */
 	resize: boolean;
+	/** Role tag — one of {@link CANVAS_TYPES}. */
 	type: symbol;
 }
+/**
+ * Tracks registered canvases and exposes the main 2D context. The width/height accessors and `size` getter all refer to the **buffer** dimensions (the canvas's `width`/`height` attributes — drawing-space pixels), while {@link resizedSize} and {@link ratio} describe the **display** size after CSS scaling.
+ *
+ * Owned by `Game` (`game.canman`). Lifecycle: subclass registers canvases via {@link setupCanvas} in its constructor, then `preInit()` calls {@link finishSetup}.
+ */
 export declare class CanvasManager {
+	/** Cached `getBoundingClientRect()` of the main canvas. Refreshed in {@link resize}. Used to map pointer client coords into canvas space. */
 	canvasBoundingClientRect: DOMRect;
+	/** Registry of every {@link setupCanvas}-registered canvas, keyed by selector. */
 	canvasHolder: Record<string, CanvasHolder>;
+	/** Display-to-buffer scale factor after the last {@link resize} (`displayWidth / bufferWidth`). `1` until the first resize. */
 	ratio: number;
+	/** Display (CSS-pixel) size of the main canvas after the last {@link resize}. Independent of the buffer dimensions in {@link width}/{@link height}. */
 	resizedSize: Vec2;
 	private mainHolder;
+	/** Main canvas element (the one registered with `CANVAS_TYPES.MAIN`). */
 	get canvas(): HTMLCanvasElement;
+	/** Main canvas 2D rendering context. */
 	get canvasContext(): CanvasRenderingContext2D;
+	/** Main canvas **buffer** height (the drawing surface, not the CSS display size). */
 	get height(): number;
+	/** Main canvas **buffer** height (the drawing surface, not the CSS display size). */
 	set height(height: number);
+	/** Main canvas buffer dimensions as a new `Vec2`. */
 	get size(): Vec2;
+	/** Main canvas **buffer** width (the drawing surface, not the CSS display size). */
 	get width(): number;
+	/** Main canvas **buffer** width (the drawing surface, not the CSS display size). */
 	set width(width: number);
+	/** 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(): void;
+	/** 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(): void;
+	/** Set the main context's `font` to `${size}px "${font}"`. Defaults the family to `Settings.font`. */
 	setFontSize(size: number, font?: string): void;
+	/** 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: symbol, selector: string, resize?: boolean): CanvasHolder;
 }
+/** rAF gaps larger than this (s) reset the accumulator instead of running catch-up steps — keeps a backgrounded tab or paused debugger from fast-forwarding the simulation on resume. */
+export declare const MAX_DT_SECONDS = 0.25;
+/** Hard cap on update steps per rendered frame. If simulation can't keep up, it falls behind in `levelTime` rather than blocking the main thread. */
+export declare const MAX_STEPS_PER_FRAME = 5;
+/**
+ * Fixed-step game loop. Owned by `Game` (`game.gameloop`) — usually started automatically by `preInit()` when `Settings.autoloop` is `true`. Each rendered frame:
+ *
+ * 1. Accumulates real time
+ * 2. Runs `game.update(Settings.fps)` zero-or-more times until the accumulator is drained (bounded by {@link MAX_STEPS_PER_FRAME} to avoid runaway catch-up)
+ * 3. Clears the canvas (per `Settings.doNotClear` / `Settings.useClearRect`) and calls `game.draw(context)`
+ *
+ * Fires the {@link EventSystem} `"gameloopStopped"` event when teardown completes (not when {@link stopLoop} is called).
+ */
 export declare class Gameloop {
+	/** 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. */
 	levelTime: number;
 	private _isLooping;
 	private accumulator;
 	private game;
 	private stop;
+	/** `true` while the rAF callback is registered. Goes `false` only after the final frame fires the `"gameloopStopped"` event. */
 	get isLooping(): boolean;
 	constructor(game: Game);
+	/** Begin the rAF loop. Throws if {@link stopLoop} was called but teardown hasn't completed yet — wait for the `"gameloopStopped"` event before restarting. */
 	startLoop(): void;
+	/** Request that the loop stop on its next tick. Asynchronous — the loop tears down on the following frame and dispatches `"gameloopStopped"` when done. */
 	stopLoop(): void;
 	private draw;
 	private looper;
 }
+/** `KeyboardEvent.code` constants for the keys Gleam tracks by name. Use as the argument to {@link Keyboard.isPressed} / {@link Keyboard.stopPress} or as a string key into {@link Keyboard.keys}. */
 export declare const KEYBOARD_KEYS: {
+	/** Digit row `0`. */
 	readonly KEY_0: "Digit0";
+	/** Digit row `1`. */
 	readonly KEY_1: "Digit1";
+	/** Digit row `2`. */
 	readonly KEY_2: "Digit2";
+	/** Digit row `3`. */
 	readonly KEY_3: "Digit3";
+	/** Digit row `4`. */
 	readonly KEY_4: "Digit4";
+	/** Digit row `5`. */
 	readonly KEY_5: "Digit5";
+	/** Digit row `6`. */
 	readonly KEY_6: "Digit6";
+	/** Digit row `7`. */
 	readonly KEY_7: "Digit7";
+	/** Digit row `8`. */
 	readonly KEY_8: "Digit8";
+	/** Digit row `9`. */
 	readonly KEY_9: "Digit9";
+	/** Letter `A`. */
 	readonly KEY_A: "KeyA";
+	/** Letter `B`. */
 	readonly KEY_B: "KeyB";
+	/** Letter `C`. */
 	readonly KEY_C: "KeyC";
+	/** Letter `D`. */
 	readonly KEY_D: "KeyD";
+	/** Down arrow. */
 	readonly KEY_DOWN: "ArrowDown";
+	/** Letter `E`. */
 	readonly KEY_E: "KeyE";
+	/** Enter / Return. */
 	readonly KEY_ENTER: "Enter";
+	/** Escape. Note: in `Settings.debug` mode this stops the gameloop. */
 	readonly KEY_ESCAPE: "Escape";
+	/** Letter `F`. */
 	readonly KEY_F: "KeyF";
+	/** Letter `G`. */
 	readonly KEY_G: "KeyG";
+	/** Letter `H`. */
 	readonly KEY_H: "KeyH";
+	/** Letter `I`. */
 	readonly KEY_I: "KeyI";
+	/** Letter `J`. */
 	readonly KEY_J: "KeyJ";
+	/** Letter `K`. */
 	readonly KEY_K: "KeyK";
+	/** Letter `L`. */
 	readonly KEY_L: "KeyL";
+	/** Left arrow. */
 	readonly KEY_LEFT: "ArrowLeft";
+	/** Letter `M`. */
 	readonly KEY_M: "KeyM";
+	/** Letter `N`. */
 	readonly KEY_N: "KeyN";
+	/** Letter `O`. */
 	readonly KEY_O: "KeyO";
+	/** Letter `P`. */
 	readonly KEY_P: "KeyP";
+	/** Letter `Q`. */
 	readonly KEY_Q: "KeyQ";
+	/** Letter `R`. */
 	readonly KEY_R: "KeyR";
+	/** Right arrow. */
 	readonly KEY_RIGHT: "ArrowRight";
+	/** Letter `S`. */
 	readonly KEY_S: "KeyS";
+	/** Space bar. */
 	readonly KEY_SPACE: "Space";
+	/** Letter `T`. */
 	readonly KEY_T: "KeyT";
+	/** Tab. */
 	readonly KEY_TAB: "Tab";
+	/** Letter `U`. */
 	readonly KEY_U: "KeyU";
+	/** Up arrow. */
 	readonly KEY_UP: "ArrowUp";
+	/** Letter `V`. */
 	readonly KEY_V: "KeyV";
+	/** Letter `W`. */
 	readonly KEY_W: "KeyW";
+	/** Letter `X`. */
 	readonly KEY_X: "KeyX";
+	/** Letter `Y`. */
 	readonly KEY_Y: "KeyY";
+	/** Letter `Z`. */
 	readonly KEY_Z: "KeyZ";
 };
+/**
+ * Keyboard state. Wired into `Game` automatically. The preferred way to consume input is to poll {@link isPressed} from `update` — game input is held-state-based ("is W held this frame?"), and combining with {@link stopPress} handles one-shot actions cleanly. The {@link EventSystem} `"inputKeyboard"` event (payload: `(keys, code, pressed)`) is available for cases that genuinely need edge-triggered handling.
+ *
+ * State is cleared on `window` blur and on `gameloopStopped` so held keys don't stay "pressed" when focus or the loop is lost. In `Settings.debug` mode, pressing Escape stops the gameloop.
+ */
 export declare class Keyboard {
+	/** 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`). */
 	keys: Record<string, boolean>;
 	constructor(game: Game);
+	/** Mark every tracked key as released. Called automatically on `window` blur and on `gameloopStopped`. */
 	reset(): void;
+	/** 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: string): void;
+	/** `true` when `code` is currently held. Safe for untouched keys (returns `false` rather than `undefined`). */
 	isPressed(code: string): boolean;
 }
+/** Subset of writable Settings fields that {@link Settings.init} accepts (everything except the methods and persisted-storage view). Pass to `super()` when subclassing {@link Game}. */
 export type SettingsOverrides = Partial<Omit<typeof Settings, "prototype" | "init" | "setLocalStorage" | "localStorage">>;
+/** Engine-wide configuration. A static-class singleton — read/write top-level fields directly (`Settings.fps = 1 / 30`). Initialised once via {@link init} from `Game`'s constructor; calling `init` twice throws. */
 export declare class Settings {
+	/** Enable smoothing on the main canvas context. Default `false` for crisp pixel art. */
 	static antialias: boolean;
+	/** Start the gameloop automatically after `init()` resolves. Disable to drive `gameloop.startLoop()` manually. Default `true`. */
 	static autoloop: boolean;
+	/** CSS color used when {@link useClearRect} is `false`. Default `"#444"`. */
 	static backgroundColor: string;
+	/** Debug mode: assigns the `Game` instance to `window.game` and lets {@link Keyboard} Escape stop the loop. Default `false`. */
 	static debug: boolean;
+	/** Skip the per-frame canvas clear. Use for trail/decay effects where you manage clearing yourself. Default `false`. */
 	static doNotClear: boolean;
+	/** Stretch the main canvas to fill the window on resize while preserving its aspect ratio. Default `true`. */
 	static enableResize: boolean;
+	/** Default font family for `canman.setFontSize`. Default `"Arial"`. */
 	static font: string;
+	/** **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. */
 	static fps: number;
+	/** Callback invoked from the `beforeunload` handler when {@link warnBeforeClose} is `true`. Useful for "are you sure?" autosave logic. */
 	static triedToClose?: () => void;
+	/** Clear the canvas with `clearRect` (transparent) when `true`, or `fillRect` with {@link backgroundColor} when `false`. Default `true`. */
 	static useClearRect: boolean;
+	/** Show a browser "are you sure?" dialog on tab close. Required for {@link triedToClose} to fire. Default `false`. */
 	static warnBeforeClose: boolean;
 	private static initialized;
 	private static readonly _localStorage;
+	/** Read-only view of the persisted localStorage blob. Writes go through {@link setLocalStorage}. */
 	static get localStorage(): Readonly<typeof Settings._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: SettingsOverrides, game: Game): void;
+	/** 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<K extends keyof typeof Settings._localStorage>(key: K, value: (typeof Settings._localStorage)[K]): void;
 }
 declare global {
@@ -643,7 +1070,11 @@ declare global {
 		t(key: string): string;
 	}
 }
+/** Translation tables keyed by `languageCode → translationKey → text` (e.g. `{ en: { hello: "Hi" }, de: { hello: "Hallo" } }`). */
 export type Languages = Record<string, Record<string, string>>;
+/**
+ * Install the global `window.t(key)` translator. Picks the active language from `Settings.localStorage.language` (seeded from `navigator.language` and overridable via `Settings.setLocalStorage("language", ...)`). Falls back to `defaultLanguage` when the active language isn't registered; returns the key itself when a translation is missing. Both fallback cases log a throttled `console.warn`. Logs `console.error` per missing key during preparation if some languages don't cover every key. Throws if `defaultLanguage` isn't in `languages`.
+ */
 export declare function prepareLanguage(languages: Languages, defaultLanguage?: string): void;
 declare global {
 	interface HTMLAudioElement {
@@ -791,141 +1222,168 @@ declare global {
 		subImage(x: number, y: number, w?: number, h?: number): HTMLCanvasElement;
 	}
 }
+/**
+ * Abstract base for a Gleam game. Subclass it and implement {@link init}, {@link update}, and {@link draw}. The constructor wires up {@link CanvasManager}, {@link Gameloop}, {@link Keyboard}, and {@link Pointer}; the subclass must register at least one canvas with `canman.setupCanvas(...)` and then call {@link preInit} to start everything.
+ *
+ * **Singleton-per-page.** The framework registers global listeners on `window`/`document` and writes `history.scrollRestoration`; multiple instances on the same page will fight each other.
+ */
 export declare abstract class Game {
+	/** Canvas registry + 2D context exposure. Register canvases here from the constructor (`canman.setupCanvas(CANVAS_TYPES.MAIN, "#game")`) before calling {@link preInit}. */
 	canman: CanvasManager;
+	/** The fixed-step driver. Started automatically by `preInit` when `Settings.autoloop` is `true`. */
 	gameloop: Gameloop;
+	/** Live keyboard state. See {@link Keyboard}. */
 	keyboard: Keyboard;
+	/** Live pointer (mouse / pen / touch) state. See {@link Pointer}. */
 	pointer: Pointer;
 	private initialized;
 	constructor(settingOverrides?: SettingsOverrides);
+	/** Render the current frame. Called by {@link Gameloop} after the canvas is cleared. Subclasses must override — the default throws. */
 	draw(_context: CanvasRenderingContext2D): void;
+	/** 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: number): void;
+	/** 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. */
 	init(): Promise<void>;
+	/** 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). */
 	protected preInit(doInit?: boolean): Promise<void>;
 }
+/** Button indices that match `PointerEvent.button` and index into {@link Pointer.pressed}. */
 export declare const POINTER_KEYS: {
+	/** Primary button (left for right-handers). */
 	readonly LEFT: 0;
+	/** Middle button / wheel click. */
 	readonly MIDDLE: 1;
+	/** Secondary button (right for right-handers). */
 	readonly RIGHT: 2;
+	/** "Back" side button (browser back). */
 	readonly PREV: 3;
+	/** "Forward" side button. */
 	readonly FORWARD: 4;
 };
+/**
+ * Pointer (mouse / pen / touch) state. Wired into `Game` automatically. The preferred way to consume input is to subscribe to the {@link EventSystem} `"inputPointer"` event — it fires on every move and button transition, with this `Pointer` instance as the payload. If you need the latest state on a frame boundary instead, poll `game.pointer.posScaled` and `game.pointer.pressed[POINTER_KEYS.LEFT]` from `update`.
+ *
+ * Suppresses the browser context menu on right-click globally.
+ */
 export declare class Pointer {
+	/** 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". */
 	hasMoved: boolean;
+	/** Last raw `PointerEvent` received. `null` until any pointer event fires. Use for properties not surfaced as Vec2/booleans (pressure, pointerType, etc.). */
 	lastEvent: PointerEvent | null;
+	/** Viewport-space coordinates (`event.clientX/Y` — CSS pixels relative to the page). */
 	posReal: Vec2;
+	/** Previous tick's {@link posReal}. Subtract for a per-frame delta. */
 	posRealLast: 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. */
 	posScaled: Vec2;
+	/** Previous tick's {@link posScaled}. */
 	posScaledLast: Vec2;
+	/** Per-button pressed state. Index with {@link POINTER_KEYS} (e.g. `pressed[POINTER_KEYS.LEFT]`). Sparse — unindexed entries are `undefined`, not `false`. */
 	pressed: boolean[];
 	private game;
 	constructor(game: Game);
+	/** Clear all pressed-button state. Called automatically on `window` blur so held buttons don't stay "pressed" forever when focus is lost. */
 	reset(): void;
 	private update;
 }
+/**
+ * Type-safe registry of engine events and their payload tuples. Both {@link EventSystem.addEventListener} and {@link EventSystem.dispatchEvent} are generic over this map, so the listener callback and dispatched args are checked against the declared shape.
+ */
 export interface GameEventMap {
+	/** Fired by {@link Gameloop} once teardown completes, after `stopLoop()` is called. */
 	gameloopStopped: [
 	];
+	/** Fired by {@link Controller} when a gamepad is connected. Payload is the native `Gamepad`. */
 	inputControllerConnected: [
 		event: Gamepad
 	];
+	/** Fired by {@link Controller} when *our* tracked gamepad disconnects. Other gamepads disconnecting are logged but don't dispatch. */
 	inputControllerDisconnected: [
 	];
+	/** Fired by {@link Keyboard} on every key down/up with the live `keys` map, the `code` that changed, and its new pressed state. */
 	inputKeyboard: [
 		keys: Record<string, boolean>,
 		code: string,
 		pressed: boolean
 	];
+	/** Fired by {@link Pointer} on every move and button transition. Payload is the `Pointer` instance — read `posScaled`/`pressed` from it. */
 	inputPointer: [
 		pointer: Pointer
 	];
+	/** Fired by {@link Game.preInit} once at startup and on every debounced `window.resize` thereafter. The canonical "viewport changed" signal. */
 	resized: [
 	];
 }
+/** Options for {@link EventSystem.addEventListener}. */
 export interface EventSystemOptions {
+	/** Auto-dispose the listener after the first dispatch. */
 	once?: boolean;
+	/** Dispose the listener when the signal aborts. Already-aborted signals make `addEventListener` a no-op. */
 	signal?: AbortSignal;
 }
+/**
+ * Synchronous, type-safe pub/sub for engine-wide events. Static-only — call as `EventSystem.addEventListener(...)` / `EventSystem.dispatchEvent(...)`. Event names and payloads are constrained by {@link GameEventMap}.
+ *
+ * Guarantees:
+ *
+ * - Listeners registered during a dispatch are deferred to the next dispatch (won't fire in the round that registered them).
+ * - `once` listeners are removed *before* their callback runs, so nested dispatches and throwing callbacks can't double-fire them.
+ * - A throwing callback is caught and logged (throttled per `eventName:message`); siblings still receive the event.
+ */
 export declare class EventSystem {
 	private static eventListener;
 	private static logListenerError;
 	private static nextId;
+	/**
+	 * 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<K extends keyof GameEventMap>(eventName: K, callback: (...args: GameEventMap[K]) => void, options?: EventSystemOptions): () => void;
+	/** Synchronously fire `eventName` with the typed payload. Listeners are invoked in registration order; nested dispatches and self-disposing listeners are handled safely. */
 	static dispatchEvent<K extends keyof GameEventMap>(eventName: K, ...params: GameEventMap[K]): void;
 }
+/** String-valued keys of `CSSStyleDeclaration` — the ones safe to assign a `string` value to via {@link CssProxy}. */
 export type CssStyleKey = {
 	[K in keyof CSSStyleDeclaration]: K extends string ? CSSStyleDeclaration[K] extends string ? K : never : never;
 }[keyof CSSStyleDeclaration];
+/** Setter handed to {@link ShakeType.update} that writes a CSS value. Snapshots the prior value on first write per key so it can be restored on dispose. */
 export type CssProxy = (key: CssStyleKey, value: string) => void;
+/** Shape for a custom shake recipe. */
 export interface ShakeType {
+	/** Decay rate applied each frame: `timer -= step * dt`. Higher = shorter shake (3 ≈ ⅓s, 15 ≈ 1/15s). */
 	step: number;
+	/** Per-frame mutator. `time` decays from `1` to `0` over the shake — multiply your intensity by it for a natural fall-off. */
 	update: (updateCss: CssProxy, time: number) => void;
 }
+/** Built-in shake recipes. Pass one to {@link Screenshake.shake}. */
 export declare const SHAKE_TYPES: {
+	/** ~0.33 s wobble combining a small random rotation with a blur fall-off. */
 	NORMAL: {
+		/** Decay rate — see {@link ShakeType.step}. */
 		step: number;
+		/** Per-frame mutator — see {@link ShakeType.update}. */
 		update(updateCss: CssProxy, time: number): void;
 	};
+	/** ~0.07 s impact: blur-only fall-off, no rotation. */
 	FAST: {
+		/** Decay rate — see {@link ShakeType.step}. */
 		step: number;
+		/** Per-frame mutator — see {@link ShakeType.update}. */
 		update(updateCss: CssProxy, time: number): void;
 	};
 };
 /**
- * Only the built-in shake types (NORMAL, FAST) are supported today.
- * Letting callers define their own could be a possible feature — impact pulses, slow rumble, directional jolts.
+ * Shake an element by mutating its inline CSS each rAF tick. One shake per instance — re-calling {@link shake} while one is active returns `null`. The returned dispose function (and natural timer expiry) restores every CSS key the shake touched.
+ *
+ * Only the built-in {@link SHAKE_TYPES} (`NORMAL`, `FAST`) are supported today. Letting callers define their own would be a natural extension — impact pulses, slow rumble, directional jolts — since {@link ShakeType} is already public.
  */
 export declare class Screenshake {
 	private isShaking;
 	private shakeType;
 	private style;
 	constructor(element: HTMLElement);
-	/** 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?: ShakeType): null | (() => void);
 }
-export declare class ControllerCursor {
-	private axisId;
-	private controller;
-	private game;
-	private pos;
-	get centerPos(): Vec2;
-	constructor(controller: Controller, game: Game, axisId: number);
-	draw(context: CanvasRenderingContext2D): void;
-	update(dt: number): void;
-}
-export declare const CONTROLLER_KEYS: {
-	readonly A: 0;
-	readonly B: 1;
-	readonly X: 2;
-	readonly Y: 3;
-	readonly LB: 4;
-	readonly RB: 5;
-	readonly LT: 6;
-	readonly RT: 7;
-	readonly SELECT: 8;
-	readonly START: 9;
-	readonly LEFT_STICK: 10;
-	readonly RIGHT_STICK: 11;
-	readonly UP: 12;
-	readonly DOWN: 13;
-	readonly LEFT: 14;
-	readonly RIGHT: 15;
-	readonly GUIDE: 16;
-};
-export declare class Controller {
-	buttons: boolean[];
-	cursors: ControllerCursor[];
-	private axes;
-	private index;
-	private lastTime;
-	constructor(game: Game);
-	draw(context: CanvasRenderingContext2D): void;
-	update(dt: number): void;
-	reset(): void;
-	vibrate(): boolean;
-	stick(index: number): Vec2;
-	private getGamepad;
-}
 /**
  * Validates URL format and protocol before any side effects.
  * Throws on invalid URLs or disallowed protocols.
@@ -986,9 +1444,13 @@ export declare function remove<T>(arr: T[], item: T): void;
  * Shuffle array using Fisher-Yates algorithm with custom random signer
  */
 export declare function shuffle<T>(arr: ReadonlyArray<T>): T[];
+/** `get`/`set` helpers for CSS custom properties (`--name`) on `:root`. Build via {@link initCSSVariables}. */
 export interface CSSVariables {
+	/** The `:root` element these helpers read from / write to. */
 	root: HTMLElement;
+	/** Read the computed value of `--${name}`. */
 	get(name: string): string;
+	/** Write `value` to `--${name}` on the root element's inline style. */
 	set(name: string, value: string): void;
 }
 /**
@@ -1074,6 +1536,7 @@ export declare function convert1DTo2D(index: number, width: number): Vector2;
  * Convert 2D `(x, y)` coordinates to a 1D index for a grid of the given row width.
  */
 export declare function convert2DTo1D(indexX: number, indexY: number, width: number): number;
+/** Primitive cell types accepted by {@link generateGrid}'s overload that takes a default value (used so every cell can safely share the same primitive without aliasing). */
 export type GridPrimitive = string | number | boolean | bigint | symbol | null | undefined;
 /**
  * Generate a `height × width` 2D grid; every cell holds `defaultValue`. Restricted to primitives at the type level — for object/array cells use the factory overload to avoid every cell sharing the same reference.
@@ -1178,6 +1641,7 @@ export declare function toDotted(value: number): string;
  * Bounds are swapped if passed in reverse order. Throws when `min ≈ max` (degenerate range, via `approxEqual`).
  */
 export declare function wrapValue(value: number, min: number, max: number): number;
+/** Conditional helper used by {@link defineMethod}: given `T[K]` is a function, produces a corresponding function type with `this: T` bound to the prototype owner. Non-function members resolve to `never` so prototype patches can't target accessors or fields by mistake. */
 export type Method<T, K extends keyof T> = T[K] extends (...args: infer A) => infer R ? (this: T, ...args: A) => R : never;
 /**
  * Define `name` as a non-enumerable method on `proto`. Carries the declared signature so impl `this` and parameters are inferred from the merged declaration.