Merge branch 'add-unionfind-room-collision-mode'

Author: Tim Willebrands

.cargo/config.toml

@@ -0,0 +1,7 @@
+# The lighting engine builds a large precomputed ray table (`ALL_RAYS` in
+# `src/lighting.rs`) on first use. In test builds it lives on the thread
+# stack during construction, which overflows the default 2 MiB. Setting
+# `RUST_MIN_STACK` here removes the foot-gun — invoking `cargo test`
+# directly just works without remembering the env var.
+[env]
+RUST_MIN_STACK = "8388608"

CHANGE_LOG.md

@@ -0,0 +1,77 @@
+# Change Log
+
+All notable changes to `bresenham-lighting-engine` are documented here.
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] — 2026-05-25
+
+### Added
+
+- **`LightingEngine` type** ([`src/engine.rs`](src/engine.rs)). Construct one
+  with `LightingEngine::new()` and call methods on it directly. Each engine
+  owns its own tile map, block map, collision system, and light registry —
+  multiple engines can coexist in one process. This unlocks two things that
+  were previously impossible:
+    - **Parallel tests**: each test builds its own engine, so the default
+      `cargo test` thread pool no longer races on shared globals.
+    - **Embedding**: Rust callers (servers, level editors, comparison
+      harnesses) can hold more than one scene at a time. See
+      [ADR-0007](docs/decisions/0007-extract-lighting-engine-type.md).
+- **`LightingEngine::render_canvas_text(light_id)`** — ASCII-matrix view of a
+  light's canvas, suitable for stdout, panic messages, or piping to other
+  tools.
+- **Scenarios module** ([`src/scenarios/`](src/scenarios/mod.rs)) — plain Rust
+  functions like `single_light` and `object_shadow` that populate a
+  `LightingEngine`. Shared between the exploration CLI and the regression
+  tests so the same scene definition drives both.
+- **`scenario` example** — `cargo run --example scenario -- --list` enumerates
+  the available scenarios; `--name <NAME>` prints the ASCII matrix;
+  `--output-format png --out path.png` renders a PNG.
+- **`CONTEXT.md`** — canonical vocabulary (Tile, Cell, Wall, Object, Room,
+  LightingEngine, Light, Canvas, Ray). Read this before contributing.
+- **`.cargo/config.toml`** sets `RUST_MIN_STACK=8388608` so `cargo test`
+  works without remembering the env var.
+
+### Changed
+
+- `lighting::*`, `collision::*`, and `block_map::*` free functions are now
+  thin shims that forward to a process-wide `DEFAULT_ENGINE` singleton.
+  **WASM/JS callers are unaffected** — every `#[wasm_bindgen]` function
+  keeps its current name and signature, including `put`, `put_solid_color`,
+  `put_custom_color`, `set_tile`, `set_map_data`, `set_pixel`,
+  `set_pixel_batch`, `clear_pixel_collisions`, `get_tiles`, and
+  `get_blockmap`.
+- New Rust code should prefer `LightingEngine` methods; the free functions
+  exist for back-compat and operate on a shared global, which serialises
+  callers under a `RwLock`.
+
+### Removed
+
+- `IsBlockedFn` and `reset_is_blocked_fn` (dead since the collision-system
+  rewrite — they were never read at runtime).
+- `TileCollisionMap` (superseded by the unified `HybridCollisionMap` in
+  [ADR-0006](docs/decisions/0006-unify-collision-detection.md); was no
+  longer reachable from any code path).
+- `VISUAL_TESTING.md`, `tests/output_mechanisms.rs`, `tests/README.md`, the
+  `test_output/` and `test_output.before/` directories, and
+  `benches/collision_performance.rs`. The PNG-snapshot harness they
+  described had silently broken when the collision modes were unified —
+  every "obstacle" snapshot in version control was either from
+  pre-unification code or from post-unification code with no occlusion
+  wired up. Replaced by the scenarios CLI and `tests/scenarios.rs`.
+
+### Migration notes
+
+- **JS / WASM callers**: no change required. The `pkg/` artifact keeps the
+  same exports and ABI.
+- **Rust callers using free functions**: still work, but each call now
+  takes the global write lock. For tests or any code that wants
+  independent scenes, switch to `LightingEngine::new()` and call methods
+  on the instance directly.
+- **Test authors**: do **not** use `DEFAULT_ENGINE` from tests. Each test
+  must construct its own `LightingEngine` — that is what makes parallel
+  test execution safe.
+
+## [0.2.7] and earlier
+
+See `git log` for prior history.

CONTEXT.md

@@ -0,0 +1,71 @@
+# Bresenham Lighting Engine — Context
+
+A 2D lighting engine that raycasts light from point sources across a hierarchical world (coarse **tile** grid containing fine **cell** subdivisions), using Bresenham line walks for ray traversal and a unified pixel + room collision system to occlude rays.
+
+## Language
+
+### World structure
+
+**Tile**:
+A coarse-grid cell — the unit of the world's main layout (`TILES_PER_ROW × TILES_PER_ROW`, currently 30×30). A tile has a type; same-type adjacent tiles form a contiguous **Room**.
+_Avoid_: "main-grid cell" (informal), "block" (overloaded).
+
+**Cell**:
+A fine-grid cell — the unit lighting operates on (`CELLS_PER_ROW × CELLS_PER_ROW`, currently 180×180; `CELLS_PER_TILE = 6` per tile edge). Light rays are traced cell-by-cell.
+_Avoid_: "pixel" (in this codebase, "pixel" historically refers to a cell, which is misleading — see Flagged ambiguities), "subgrid cell" (informal alias OK in prose).
+
+### Collision primitives
+
+**Wall**:
+A blocked edge between two adjacent tiles of different types. Materialises in two equivalent views: (a) as `n/e/s/w_blocked` flags on the cells that sit on the tile boundary, and (b) as a partition in the `UnionFind` room graph. Walls are derived from the tile map — they are not authored directly per edge.
+_Avoid_: "obstacle" (ambiguous with **Object**), "edge collision".
+
+**Object**:
+A coherent group of blocked **Cells** in the runtime-mutable collision bitmap (`PixelCollisionMap`) that represents one in-world thing — a chair, a barrel, a character. The atomic write primitive (`set_pixel(cx, cy, true)`) marks a single cell as blocked; an Object is the higher-level concept built from many such writes.
+_Avoid_: "obstacle" (ambiguous with **Wall**), "pixel obstacle" (confusing — see "Cell"), conflating "Object" with the atomic single-cell write.
+
+**Room**:
+A maximal set of tiles connected by walkable adjacency (same tile type, no wall between them, and no closed **Door** on the boundary). Computed by `UnionFind` from the tile map plus the door-edge overlay. The broad-phase collision check rejects a ray when its endpoints lie in different rooms.
+_Avoid_: "region", "area".
+
+**Door**:
+A passable edge between two tiles that the tile-map alone would split into different **Rooms**. Stored separately from the tile map as `door_edges: HashMap<(TileIdx, TileIdx), DoorState>` on `LightingEngine`. Consulted by both the broad-phase Room check (an open Door joins the rooms across that edge) and the narrow-phase cell-edge wall flags (an open Door clears the wall along its tile boundary). Doors are not **Wall**s and not **Object**s — they are a third collision primitive.
+_Avoid_: "passage", "doorway gap" (the empty-tile case is just a same-type tile boundary, no Door needed), "wall token" (a downstream JS authoring concept).
+
+### Lighting
+
+**LightingEngine**:
+An owned instance of the engine's mutable runtime state — tile map, room/wall data, object bitmap, and the registry of active Lights. Multiple instances can coexist (e.g. one per test scenario). Process-wide caches like the precomputed ray lookup table live outside any single LightingEngine.
+_Avoid_: "World", "Scene", "Stage", "LightingWorld".
+
+**Light**:
+A point source with a position (in cell coords), an integer radius, and a unique id. Produces a square canvas of size `(2·radius + 1)²` of RGBA pixels.
+
+**Canvas**:
+The output buffer for a single light — RGBA values per cell within the light's bounding square. Composited externally for multi-light scenes.
+
+**Ray**:
+A precomputed Bresenham path from a light's centre to one of `ANGLES` directions at one of `MAX_DIST` distances. Stored in the `ALL_RAYS` lookup table.
+
+## Relationships
+
+- The world has exactly **one** Tile layout, which deterministically defines all **Walls** and all **Rooms**.
+- A **Cell** belongs to exactly one **Tile** (and via that tile, exactly one **Room**).
+- An **Object** occupies one **Cell** and is independent of Walls and Rooms.
+- A ray from a **Light** is occluded if (a) its endpoints lie in different **Rooms** (broad-phase, UnionFind), OR (b) any **Cell** on its Bresenham path contains an **Object** (narrow-phase, `PixelCollisionMap`).
+- Walls and Objects are authored through **different** APIs and should be tested by **different** scenarios.
+
+## Example dialogue
+
+> **Dev:** "If I want to test that a light is blocked by an inner wall of a room, do I add an Object or a Wall?"
+> **Domain expert:** "A Wall — define the tile layout so the two tiles you care about have different types. The wall appears automatically as an edge between them. Objects are for things that aren't part of the architecture, like a chair sitting in the middle of a room."
+
+> **Dev:** "So `PixelCollisionMap` stores walls?"
+> **Domain expert:** "No — it stores Objects only. Walls live in the tile map and are read through the UnionFind room graph (broad-phase) and the cell edge-flags (narrow-phase rendering hints). The 'pixel' in the type name is historical and refers to cells, not screen pixels."
+
+## Flagged ambiguities
+
+- **"pixel"** in code (`PixelCollisionMap`, `set_pixel`, `get_pixel`) refers to a **Cell**, not a screen pixel. The public API name is preserved for back-compat (WASM/JS callers); treat the word as a synonym for **Cell** when reading the collision module.
+- **"obstacle"** has been used in tests and docs (notably `VISUAL_TESTING.md`) to mean either a **Wall** or an **Object**. These are now distinct primitives with different storage, different authoring APIs, and different failure modes — do not use "obstacle" as a canonical term.
+- **"grid" / "subgrid"** (informal) map to **Tile** / **Cell** (canonical). Use the canonical terms in code, comments, and ADRs.
+- **"hybrid collision"** (from ADR-0006) names the combination but not its components. Prefer "**Room** + **Object** collision" when describing what the system does.

Cargo.lock

@@ -25,11 +25,25 @@ The core idea is simple:
 
 This requires a bundler like Vite to wire up the wasm and stuff. Package it with `wasm-pack build --target web` to get a version that doesn't need bundlers. 
 
+The engine has two ways to block light, and they exist for different things:
+
+- **`set_pixel(x, y, blocked)`** marks a single cell of the 180×180 grid as
+  an in-world object — a chair, a barrel, a character. Use this for stuff
+  that moves or gets placed at runtime.
+- **`set_tile(tx, ty, type)`** / **`set_map_data(types, size)`** define the
+  coarse 30×30 tile layout. Boundaries between tiles of different types
+  become walls automatically, and contiguous same-type tiles form rooms
+  used to skip occluded rays cheaply. Use this for architecture.
+
 ```typescript
-import { memory, put, set_collision_mode } from 'bresenham-lighting-engine';
+import { memory, put, set_pixel, set_tile } from 'bresenham-lighting-engine';
 
-// Initialize collision detection
-set_collision_mode(1); // 0=tile-based, 1=pixel-based
+// Architecture: tile (5,3) is type 1, surrounded by type 0 → walls on all
+// four sides of that tile.
+set_tile(5, 3, 1);
+
+// A runtime object: mark the cell at (120, 90) as blocking.
+set_pixel(120, 90, 1);
 
 // Create a light: id=0, radius=50, x=200, y=100
 const lightPtr = put(0, 50, 200, 100);
@@ -49,6 +63,23 @@ const imageData = new ImageData(pixelData, lightSize, lightSize);
 ctx.putImageData(imageData, 0, 0);
 ```
 
+## Visual feedback & scenarios
+
+Scenarios live in [`src/scenarios/`](src/scenarios/mod.rs) as plain Rust
+functions taking `&mut LightingEngine`. They are shared by:
+
+- **Exploration loop** — `cargo run --example scenario -- --name single_light`
+  prints an ASCII matrix of the resulting canvas to stdout. Pass
+  `--output-format png --out path.png` to render a PNG, or `--list` to see
+  what's defined.
+- **Regression loop** — `cargo test --test scenarios` runs invariant-based
+  assertions. Failures embed the ASCII matrix in the panic message so the
+  output is self-explanatory.
+
+See [`CONTEXT.md`](CONTEXT.md) for the canonical vocabulary
+(Tile/Cell/Wall/Object/Room/LightingEngine/Light/Canvas/Ray) and
+[`docs/decisions/`](docs/decisions/) for ADRs.
+
 ## Development
 
 Install `wasm-pack`: