aiquadtreejs 0.5.5 → 0.5.8

package/llms-full.txt

@@ -13,338 +13,140 @@ The short index lives at `llms.txt` (see https://llmstxt.org/).
 
 # aiquadtreejs
 
-[![npm version](https://img.shields.io/npm/v/aiquadtreejs.svg)](https://www.npmjs.com/package/aiquadtreejs)
-[![CI](https://github.com/yshengliao/aiquadtreejs/actions/workflows/ci.yml/badge.svg)](https://github.com/yshengliao/aiquadtreejs/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
-[![AI Generated](https://img.shields.io/badge/AI_Generated-Claude_Code_Opus_4.7_Max-blueviolet.svg)](https://www.anthropic.com/claude-code)
-[![繁體中文](https://img.shields.io/badge/lang-繁體中文-red.svg)](README_ZHTW.md)
+Tiny 2D quadtree for per-frame rebuild collision broadphase. Insert AABBs, retrieve candidates, then run precise collision checks yourself.
 
-> A tiny 2D quadtree for per-frame rebuild collision broadphase. `insert` AABBs, `retrieve` candidates, `clear`. Caller does precise hit-testing. Designed for PixiJS games with 500–10,000 active entities.
+> **Status: 0.5.8 - stable 1.0-track surface.** The root entry is the public API.
 
-Part of the [ai\*js micro-runtime ecosystem](https://github.com/yshengliao) — see also [aifsmjs](https://github.com/yshengliao/aifsmjs) (FSM), [aiecsjs](https://github.com/yshengliao/aiecsjs) (ECS), [aibridgejs](https://github.com/yshengliao/aibridgejs) (cross-context RPC), [aieventjs](https://github.com/yshengliao/aieventjs) (event emitter), [aipooljs](https://github.com/yshengliao/aipooljs) (object pool), and [aiaudiojs](https://github.com/yshengliao/aiaudiojs) (Web Audio shell).
-
-> **Status: 0.5.1 published.** `insert()` now validates object geometry (non-finite coords, negative dimensions throw `QuadtreeError`); 22 new tests (J/K groups). `retrieveInto(region, target)` is a steady-state zero-allocation broadphase (reused internal scratch + caller buffer); property-based dedup invariants. ≥95% coverage, ≤2 KB gzip.
-
----
-
-## Why aiquadtreejs
-
-Naïve pairwise collision detection on `N` entities is `O(N²)`. At 1,000 entities that's a million comparisons per frame, which at 60 Hz is already a budget killer; at 10,000 entities it's a non-starter. A quadtree replaces the dense outer loop with a spatial filter: each entity asks "who could I possibly collide with?" and the tree returns a small candidate set — sub-linear on average for well-distributed inputs (worst case is `O(N)` when every object overlaps the query region). The precise hit test then runs only on candidates, dropping the actual comparisons by one or two orders of magnitude in typical game distributions.
-
-`aiquadtreejs` makes four deliberate trade-offs:
-
-- **Per-frame rebuild, not move-tracking.** Tracking which leaf an entity migrated into between frames is doable but error-prone; `clear()` + re-`insert()` is faster in practice and easier to reason about. This mirrors the Kontra.js philosophy. (`clear()` resets the root node and drops the child array; subdividing fresh next frame is cheap because the inner subdivision logic touches at most `maxLevels = 4` levels.)
-- **Set-based dedup on `retrieve`.** An AABB that straddles a quadrant boundary lands in multiple leaves. Without dedup the caller sees the same candidate two or four times and pays double for the precise hit test. The Set guarantees each candidate appears once.
-- **2D AABB only — no 3D, no R-tree, no KD-tree, no Circle / Line primitives.** Those are real techniques for real problems but they sit in a different size class. Keep this library at ≤ 2 KB gzipped and let user-land bring in heavier broadphase when needed.
-- **No precise hit-test.** Broadphase libraries that also do collision response always grow. The contract here ends at "here are the candidates"; pixel-perfect or shape-specific tests belong to whatever physics layer you already have.
-
-Why not just import `@timohausmann/quadtree-ts`? That library is solid and you should use it for stand-alone work. `aiquadtreejs` exists so that an ai*js stack can talk to entity IDs from `aiecsjs` without per-frame object adaptation — `insert({ id: eid, x, y, width, height })` lines up with the SoA columns you already maintain.
-
-> `aiquadtreejs` is one of the four 0.3-cycle siblings joining the family — alongside [aipooljs](https://github.com/yshengliao/aipooljs) (object pool), `aieventjs` (typed events; self-built, not a `mitt` fork), and `aiaudiojs` (Web Audio shell over a Howler.js `peerDependency`).
-
----
-
-## Quick Start
+## Install
 
 ```bash
 pnpm add aiquadtreejs
 ```
 
-```typescript
+```ts
 import { createQuadtree, type AABB } from "aiquadtreejs";
+```
+
+## Quick Start
 
-type Body = { id: number } & AABB;
+```ts
+interface Body extends AABB {
+  id: number;
+}
 
-// 1. Build the tree once.
-const qt = createQuadtree<Body>({
+const tree = createQuadtree<Body>({
   bounds: { x: 0, y: 0, width: 800, height: 600 },
   maxObjects: 10,
   maxLevels: 4,
 });
 
-// 2. Per frame: clear and re-insert.
-function rebuild(entities: Body[]) {
-  qt.clear();
-  for (const e of entities) qt.insert(e);
-}
+const bodies: Body[] = [
+  { id: 1, x: 100, y: 100, width: 32, height: 32 },
+  { id: 2, x: 400, y: 250, width: 32, height: 32 },
+];
 
-// 3. Per query: broadphase, then precise hit-test.
-function nearbyEnemies(player: Body, enemies: Body[]): Body[] {
-  const region: AABB = { x: player.x - 50, y: player.y - 50, width: 100, height: 100 };
-  const candidates = qt.retrieve(region);
-  // Caller filters with precise AABB / pixel test:
-  return candidates.filter((c) => aabbOverlap(c, region));
-}
-```
+tree.clear();
+for (const body of bodies) tree.insert(body);
 
-Right-open coordinate semantics: `x + width` and `y + height` are exclusive (renderer-neutral; matches common conventions such as PixiJS `getBounds()`).
+const candidates = tree.retrieve({ x: 80, y: 80, width: 120, height: 120 });
+```
 
----
+## Core API
 
-## Capabilities / Limitations
+- `createQuadtree<T extends AABB>({ bounds, maxObjects?, maxLevels? })` creates a tree.
+- `insert(obj)` stores an object reference in overlapping nodes.
+- `retrieve(region)` returns a deduplicated broadphase candidate array.
+- `retrieveInto(region, target)` reuses a caller-owned result array.
+- `clear()` empties the tree for the next frame and clears scratch buffers.
+- `dispose()` is idempotent permanent teardown.
+- Errors: `QuadtreeError`, `QuadtreeDisposedError`.
 
-| Will do (v1)                                              | Won't do                                              |
-| --------------------------------------------------------- | ----------------------------------------------------- |
-| 2D rectangle quadtree                                     | 3D octree / R-tree / KD-tree                          |
-| `insert()` / `retrieve()` / `clear()` / `dispose()`       | Move-tracking (use `clear()` + re-`insert()`)         |
-| Set-based dedup on `retrieve` (each candidate once)       | Precise hit-test (broadphase only)                    |
-| `maxObjects` + `maxLevels` knobs                          | Auto-rebalance / dynamic depth growth                 |
-| Reuse the root node across frames; resubdivide cheaply    | Circle / Line / polygon primitives                    |
-| `dispose()` idempotent; post-dispose calls throw          | Persistence / snapshot / serialise (out of scope)     |
+## Model
 
----
+- Coordinates are right-open: `{ x, y, width, height }` covers `[x, x + width)` and `[y, y + height)`.
+- This is a broadphase only. Returned candidates may not actually overlap the query region.
+- Expected usage is per-frame rebuild: `clear()`, insert active bodies, query.
+- Objects spanning quadrant boundaries can be stored in multiple child nodes; results are deduplicated.
+- `maxLevels` has no hard cap. Very high values plus spanning objects can create huge node counts.
 
-## API sketch
+## Sharp Edges
 
-```typescript
-interface AABB {
-  x: number;
-  y: number;
-  width: number;   // x + width is exclusive
-  height: number;  // y + height is exclusive
-}
+- Known bug: a zero-size point exactly on the root `left/top` boundary, such as `{ x: bounds.x, y: bounds.y, width: 0, height: 0 }`, is currently ignored by the root overlap check. Zero-size objects away from that root minimum edge are covered by tests. Next code pass should fix the root containment helper and add boundary tests.
+- Fully outside objects are ignored by retrieval.
+- Negative width/height and non-finite coordinates throw.
+- `retrieveInto()` clears the target array before writing results.
+- After `dispose()`, all methods except `dispose()` throw `QuadtreeDisposedError`.
 
-interface QuadtreeOptions {
-  bounds: AABB;
-  maxObjects?: number;   // default 10
-  maxLevels?: number;    // default 4
-}
+## AI Context
 
-interface Quadtree<T extends AABB> {
-  insert(obj: T): void;
-  retrieve(region: AABB): T[];
-  retrieveInto(region: AABB, target: T[]): T[];   // ← new in 0.3.0
-  clear(): void;
-  dispose(): void;
-  readonly disposed: boolean;
-}
+- Short index: [`llms.txt`](llms.txt)
+- Full generated context: [`llms-full.txt`](llms-full.txt)
+- Stability contract: [`STABILITY.md`](STABILITY.md)
+- Current review backlog: [`REVIEW.md`](REVIEW.md)
+- Release history: [`CHANGELOG.md`](CHANGELOG.md)
 
-class QuadtreeError extends Error {}
-class QuadtreeDisposedError extends Error {}
-
-function createQuadtree<T extends AABB>(opts: QuadtreeOptions): Quadtree<T>;
-```
+## License
 
-Full JSDoc lives in [`src/index.ts`](src/index.ts).
+MIT
 
 ---
 
-## Roadmap
+<!-- ===== CHANGELOG.md ===== -->
 
-| Version    | Adds                                                                                                                                  |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| **0.1.0**  | `createQuadtree`, `insert` / `retrieve` / `clear` / `dispose`, Set-based dedup, ≥95% coverage, ≤2 KB gzip.                              |
-| **0.3.0**  | `retrieveInto(region, target)` zero-alloc API; property-based tests (`fast-check`); STABILITY.md tracking.                            |
-| **0.4.0**  | Dependency hygiene (removed unused `tsx`, aligned `fast-check`); 0.3.x public surface frozen for the 1.x track. No runtime API change.                |
-| **0.5.1**  | `insert()` input validation: throws `QuadtreeError` for non-finite coords or negative dimensions; 22 new tests (J1–J15, K1–K7).       |
-| **0.6+**   | Evaluate 3D octree variant (`createOctree<T extends AABB3>`); see `STABILITY.md` for current draft.                                  |
+# Changelog
 
----
+All notable changes to aiquadtreejs are summarized here.
 
-## License
-
-[MIT](LICENSE).
+## [Unreleased]
 
----
+## [0.5.8] - 2026-06-14
 
-<!-- ===== CHANGELOG.md ===== -->
+- Fixed: a zero-size point on the root left/top minimum boundary (`{ x: bounds.x, y: bounds.y, width: 0, height: 0 }`) is now inserted and retrievable. The root insert gate's right-open overlap test dropped it; a new `rootContains` check is inclusive on the minimum edge and exclusive on the maximum edge, preserving right-open `[x, x+width)` semantics. Boundary regression tests added.
+- Documentation-only slimming pass across README, stability notes, review backlog, and LLM context.
 
-# Changelog
+## [0.5.6] - 2026-06-10
 
-All notable changes to this project are documented here. The format follows
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
-adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+- Hardened retrieve validation, scratch cleanup, and size-budget docs.
+- Kept root quadtree API stable and regenerated generated LLM context.
 
-## [Unreleased]
+## Older releases
 
-## [0.5.5] - 2026-06-08
-
-### Changed
-
-- Project home migrated to the [`islumina`](https://github.com/islumina) GitHub org; the package is now published from there via npm trusted publisher (OIDC + SLSA provenance). Family-wide version alignment at `0.5.5` — no runtime or API changes.
+- `0.5.5` through `0.5.1` focused on release hygiene, docs accuracy, and validation/retrieve regressions.
+- `0.4.0` declared the stable ai*js quadtree surface.
+- `0.3.x` added `retrieveInto()` and zero-allocation query paths.
+- `0.1.x` introduced `createQuadtree`, `AABB`, `Quadtree`, and error classes.
 
-## [0.5.2] - 2026-06-05
+---
 
-### Docs
+<!-- ===== STABILITY.md ===== -->
 
-- Review-driven documentation fixes (`README.md`, `README_ZHTW.md`, `llms-full.txt`) and corrected a stale version reference in the `src/index.ts` header comment. No functional change; `dist` byte-identical to 0.5.1.
+# aiquadtreejs Stability
 
-## [0.5.1] - 2026-06-02
+## Stable Surface
 
-### Fixed
+| Surface | Status | Notes |
+| --- | --- | --- |
+| `createQuadtree()` | Stable | Root factory. |
+| `AABB`, `QuadtreeOptions`, `Quadtree<T>` | Stable | Public types. |
+| `insert`, `retrieve`, `retrieveInto`, `clear`, `dispose` | Stable | Main methods. |
+| Error classes | Stable | `QuadtreeError`, `QuadtreeDisposedError`. |
 
-- **`insert()` input validation** — `insert()` now throws `QuadtreeError`
-  when the inserted object contains a non-finite coordinate (`NaN`,
-  `Infinity`, `-Infinity` in any of `x`, `y`, `width`, `height`) or a
-  negative dimension (`width < 0` or `height < 0`). Previously, such
-  objects were silently mishandled (kept before subdivide, silently dropped
-  after). Zero-extent objects (points / lines with `width=0` and/or
-  `height=0`) remain valid and are not rejected. The `QuadtreeError`
-  JSDoc already noted this use was reserved; the behaviour is now
-  implemented and documented in `STABILITY.md`.
-
-### Tests
-
-- Added J-group (J1–J15): `insert()` throws `QuadtreeError` for
-  `width<0`, `height<0`, `NaN`/`Infinity` in any of `x/y/width/height`, and
-  for `null`/`undefined` objects (J14/J15); valid zero-extent objects
-  (width=0, height=0, mixed) are accepted.
-- Added K-group (K1–K7): oversized object appears exactly once in
-  full-region and per-quadrant sub-queries after subdivide; `retrieveInto`
-  buffer identity preserved across 60 clear+insert+retrieveInto frames;
-  negative-origin bounds with negative-coord objects and queries; zero-
-  extent point at a non-midpoint survives deep subdivision (maxLevels=4)
-  and is retrievable with a tight region; maxLevels=1 with many same-
-  quadrant objects — all retrievable, zero duplicates; non-origin bounds
-  insert+retrieve correctness.
-
-## [0.4.0] - 2026-05-29
-
-Dependency hygiene + stability freeze. **No runtime API addition or behaviour
-change** — `dist/index.js` is byte-identical to 0.3.1; consumers see no
-difference. This release unifies the ai*js family version line at 0.4.0 and
-formally freezes the public surface for the 1.x track.
-
-### Changed
-
-- **devDependencies** — removed unused `tsx` (no script, config, or example in
-  this package invoked it) and aligned `fast-check` `^3.23.0` → `^4.8.0` to
-  match the rest of the ai*js family. Both are dev-only and absent from the
-  published tarball (`files` ships `dist` + docs only), so consumers are
-  unaffected.
+## Behavioral Contract
 
-### Stability
+- Bounds use right-open coordinates.
+- Inserted object references are not cloned.
+- Retrieval is broadphase and deduplicated.
+- `retrieveInto()` preserves target array identity and clears it first.
+- `clear()` drains node contents and scratch references.
+- `dispose()` is idempotent and permanent.
 
-- The 0.3.x public surface — `createQuadtree`, the `Quadtree<T>` interface and
-  all its members (`insert` / `retrieve` / `retrieveInto` / `clear` /
-  `dispose` / `disposed`), `AABB`, `QuadtreeOptions`, `QuadtreeError`,
-  `QuadtreeDisposedError` — is declared **frozen for the 1.x track**: it will
-  not break before a 1.0.0+ major. The 3D octree variant remains a draft
-  (target v0.6+).
-
-### Internal (not shipped to npm)
-
-- `pnpm audit` reports no known vulnerabilities; `pnpm-lock.yaml` regenerated
-  after the devDependency changes. Property tests re-run green under
-  fast-check v4.
+## Current Caveat
 
-## [0.3.1] - 2026-05-29
+A zero-size point on the root minimum `x/y` boundary is known to be ignored by the current root overlap check. Treat this as a documented bug, not a stable behavior.
 
-### Changed
-
-- **`retrieveInto` is now genuinely zero-allocation in steady state.** The
-  internal dedup `Set` and DFS stack are hoisted to the tree instance and
-  reused across calls (cleared, not re-created) instead of being allocated
-  per query. Combined with the caller-owned `target` buffer, a per-frame
-  broadphase loop issuing thousands of `retrieveInto` queries now allocates
-  nothing once result sizes stabilise — the design goal stated in 0.3.0.
-  Purely internal: no API, signature, or observable-behaviour change.
-  `retrieve` still returns a fresh array each call.
-- **`dispose()`** now also clears the internal scratch, preserving the
-  "drops references so the GC can reclaim everything" guarantee.
-- **Docs** — `AABB` JSDoc leads with a renderer-neutral right-open
-  definition (PixiJS `getBounds()` demoted to a compatibility note);
-  `dispose()` JSDoc now lists `retrieveInto` among the post-dispose
-  throwers; the 0.3.0 changelog note reworded ("observationally identical"
-  rather than "byte-for-byte"); `STABILITY.md` exports list now includes
-  the `Quadtree<T>` interface.
-
-### Internal (not shipped to npm)
-
-- Property test `prop2` uses `fc.uniqueArray` keyed on `id` instead of an
-  early-return guard that skipped ~39% of runs on id collisions; the
-  id-uniqueness invariant now runs on every case. Property generators mix
-  in zero-extent midpoint points (`fc.oneof`) so the dedup invariants
-  exercise the G4 regression shape, not just deterministic fixtures.
-- Tightened `I4` (`toBe(1)`); added `I13` (retrieve fresh-array vs
-  retrieveInto buffer-reuse contrast — backward-compat lock) and `I14`
-  (interleaved retrieve / retrieveInto correctness — shared-scratch guard).
-
-### Notes
-
-- `dist/index.js` runtime differs from 0.3.0 only by the scratch-hoist
-  optimisation; the public API and all observable behaviour are unchanged.
-
-## [0.3.0] - 2026-05-29
-
-### Added
-
-- **`retrieveInto(region: AABB, target: T[]): T[]`** — zero-allocation
-  variant of `retrieve` for hot-path callers. Clears `target`, walks
-  the same iterative DFS + Set dedup as `retrieve`, writes results
-  into `target`, returns `target`. The returned reference equals the
-  argument — callers can hold a permanent buffer and pass it every
-  frame to eliminate the result-array allocation churn (5,000+ calls
-  per frame in typical bullet-hell broadphase loops).
-- **`STABILITY.md`** — explicit stable vs experimental API tracking.
-  Includes a v0.6+ 3D octree draft (no source code in this release).
-- **Property-based tests** via `fast-check` — 4 invariants covering
-  `retrieve` dedup and `retrieveInto` identity / length / content
-  equivalence. Adds `fast-check` to `devDependencies`.
-
-### Changed
-
-- **`Quadtree.clear` JSDoc** — corrected the claim that "internal
-  node objects are reused across frames"; only the root node is
-  reused, child nodes are released on `clear()` and re-created when
-  subdivision next triggers. No runtime behaviour change.
-- **README Roadmap / Status / API sketch** — synced to v0.3.0,
-  including the `retrieveInto(region, target)` signature (the
-  pre-0.2 Roadmap entry was a single-argument draft).
-
-### Notes
-
-- `retrieve` behaviour is observationally identical to 0.1.1: the
-  internal refactor extracts a shared `retrieveSet` helper that both
-  `retrieve` and `retrieveInto` call, but `Set` insertion order →
-  `Array.from` order is preserved by spec.
-- Bundle size: ≤ 2 KB gzip budget still ~50% headroom after this
-  release (expected ~1050-1090 B gzip).
-
-## [0.1.1] - 2026-05-28
-
-### Changed (CI)
-
-- **`publish.yml` now triggers on `push: tags: ["v*"]`** (was `workflow_dispatch` only). Aligns with the trigger used by `aifsmjs` / `aiecsjs` / `aibridgejs`. Tag push now automatically runs the OIDC trusted publish.
-- **`npm publish --provenance --access public`** — the workflow now emits a [sigstore provenance attestation](https://docs.npmjs.com/generating-provenance-statements) so consumers can verify the tarball was built by this workflow on this commit.
-
-No runtime / source / API changes from 0.1.0. **0.1.1 is also the first version to actually land on npm — 0.1.0 was tagged in git but never published to npm.** Production bundles are byte-identical to the 0.1.0 git tag.
-
-## [0.1.0] - 2026-05-28
-
-### Added
-
-- `createQuadtree({ bounds, maxObjects, maxLevels })` factory — 2D AABB broadphase.
-- `insert(obj)` / `retrieve(region)` / `clear()` / `dispose()` lifecycle.
-- Set-based dedup on `retrieve()` so objects spanning multiple quadrants are returned once.
-- Per-frame rebuild model — `clear()` reuses internal node objects (zero GC churn frame-to-frame).
-- `disposed` read-only flag; post-dispose calls throw `QuadtreeDisposedError`.
-- Test coverage ≥95% statements / lines / functions / ≥90% branches (~30 it() blocks, groups A–H).
-- Size budget: ≤2 KB gzip.
-- Dual ESM + CJS build via `tsup` with `minify: true`; `sideEffects: false`; zero runtime dependencies.
-
-## [0.0.1] - 2026-05-28
-
-### Added (scaffold)
-
-- Full package scaffold landed (`package.json`, `tsconfig.json`,
-  `tsconfig.test.json`, `tsup.config.ts`, `vitest.config.ts`, `biome.json`,
-  `scripts/{verify-exports,check-size,build-llms-full}.mjs`,
-  `test/scaffold.test.ts`, `examples/.gitkeep`, `.github/workflows/{ci,publish}.yml`,
-  `llms.txt`, `llms-full.txt`).
-- `src/index.ts` remains a `throw` stub exposing the frozen 0.1.0 API surface
-  (`createQuadtree`, `Quadtree<T>`, `QuadtreeOptions`, `AABB`,
-  `QuadtreeError`, `QuadtreeDisposedError`).
-- `pnpm typecheck && pnpm lint && pnpm coverage && pnpm build &&
-  pnpm verify:exports && pnpm verify:llms && pnpm check:size` walks clean
-  against a single placeholder test.
-- Coverage thresholds temporarily set to `0/0/0/0`; tightened to
-  `95/90/100/100` in 0.1.0 with real tests.
-- Size budget temporarily set to 3 KB gzip; tightened to the 2 KB README
-  target in 0.1.0.
-- Publish workflow exists but trigger is `workflow_dispatch` only — no
-  accidental npm release on tag push until 0.1.0.
+## Out of Scope
 
+Precise collision checks, physics integration, spatial hashing, and 3D octrees are outside the current package.
 
 ---
 
@@ -352,80 +154,31 @@ No runtime / source / API changes from 0.1.0. **0.1.1 is also the first version
 
 # Contributing to aiquadtreejs
 
-Thanks for taking the time to look. aiquadtreejs is a deliberately small
-library (target ≤ 2 KB gzip); contributions that keep the surface narrow
-are easier to accept than ones that expand it.
+Keep the tree small, allocation-aware, and explicit about broadphase semantics.
 
-## Quick start
+## Local workflow
 
 ```bash
 pnpm install
-pnpm test            # vitest
-pnpm coverage        # vitest with v0.1.0 thresholds (95/90/100/100)
-pnpm typecheck       # tsc --noEmit on strict mode
-pnpm lint            # biome check
-pnpm build           # tsup; dual ESM/CJS + .d.ts
-pnpm verify:exports  # ensures package.json#exports matches dist/
-pnpm verify:llms     # ensures llms-full.txt is in sync with README + CHANGELOG
-pnpm check:size      # gzip per subpath against the size budget
+pnpm typecheck
+pnpm test
+pnpm verify:docs
+pnpm build:llms
+pnpm verify:llms
+pnpm check:size
 ```
 
-The full pre-publish gate is `pnpm prepublishOnly`, which runs typecheck,
-lint, coverage (with thresholds), build, exports verification, llms drift
-check, and size budget check — in that order.
-
-## What gets in easily
-
-- Bug fixes with a failing test added first
-- README / typing corrections
-- Tests that lock down existing behaviour (especially the Set-dedup
-  invariant on `retrieve`)
-- Performance work that keeps per-frame `clear()` + bulk `insert()` zero-GC
-
-## What needs discussion first
-
-- Anything that changes the public surface (`createQuadtree`, `Quadtree<T>`,
-  `AABB`, `QuadtreeOptions`, error classes)
-- Move-tracking / dynamic update (explicit non-goal — `clear()` + re-insert
-  is faster in practice for ≤ 10k entities)
-- Circle / Line / Polygon shape primitives (out of 2D AABB broadphase
-  scope; bring your own user-land wrapper)
-- 3D octree / R-tree / KD-tree (different size class; out of scope)
-- Anything that pushes the core gzip past 2 KB
-
-## Design principles
-
-aiquadtreejs follows the ai*js library-core priority order:
-
-> Security > Correctness > Simplicity > YAGNI > Performance
-
-Key invariants:
-
-- `retrieve()` deduplicates with a `Set` so each candidate appears once
-  regardless of how many quadrants it spans.
-- `clear()` reuses internal node objects across frames; no per-frame node
-  allocation.
-- `x + width` and `y + height` are **right-open** (exclusive), matching
-  PixiJS `getBounds()` semantics.
-- `dispose()` is idempotent.
-
-## Commit & PR style
-
-- Commit messages: imperative subject under 70 chars; body explains *why*.
-- PRs: keep scope to one topic. Link the issue if any.
-- Tests required for any behaviour change. Property-based tests welcome
-  for invariants (especially the Set-dedup property).
+Run `pnpm lint` before PRs. If docs change, regenerate `llms-full.txt`.
 
-## Reporting issues
+## Rules
 
-- Minimal reproduction welcome (paste the smallest insert / retrieve
-  sequence that shows the bug).
-- For security issues, please email the maintainer rather than filing
-  publicly.
+- Preserve right-open coordinate semantics.
+- Add tests for root edges, quadrant boundaries, zero-size objects, `retrieveInto()`, `clear()`, and dispose.
+- Do not turn broadphase results into precise collision promises.
+- Keep allocation behavior visible in docs and tests.
 
 ## License
 
-By contributing, you agree your changes will be licensed under the MIT
-license that covers this project.
+MIT
 
 ---

package/llms.txt

@@ -1,5 +1,9 @@
 # aiquadtreejs
 
-> A tiny 2D quadtree for per-frame rebuild collision broadphase. Insert AABBs, retrieve candidates with Set-based dedup, clear, dispose. Caller does precise hit-testing. Designed for PixiJS games with 500–10,000 active entities. Zero runtime dependencies. Part of the ai*js micro-runtime ecosystem.
+Small 2D quadtree broadphase with insert, retrieve, retrieveInto, clear, and dispose.
 
-For the full LLM context (README + CHANGELOG + CONTRIBUTING concatenated), fetch [llms-full.txt](llms-full.txt).
+- Start: README.md
+- Stability: STABILITY.md
+- Current backlog: REVIEW.md
+- Changelog: CHANGELOG.md
+- Full generated context: llms-full.txt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiquadtreejs",
-  "version": "0.5.5",
+  "version": "0.5.8",
   "description": "Tiny 2D quadtree for per-frame rebuild collision broadphase. Insert AABBs, retrieve candidates, clear. Caller does precise hit-testing. Designed for PixiJS games with 500–10,000 active entities.",
   "keywords": [
     "quadtree",
@@ -50,13 +50,14 @@
     "test:watch": "vitest",
     "lint": "biome check src test",
     "format": "biome format --write src test",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "verify:docs": "node scripts/verify-docs.mjs",
     "verify:exports": "node scripts/verify-exports.mjs",
     "check:size": "node scripts/check-size.mjs",
     "build:llms": "node scripts/build-llms-full.mjs",
     "verify:llms": "node scripts/build-llms-full.mjs --check",
     "coverage": "vitest run --coverage",
-    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm coverage && pnpm build && pnpm verify:exports && pnpm verify:llms && pnpm check:size"
+    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm verify:docs && pnpm coverage && pnpm build && pnpm verify:exports && pnpm verify:llms && pnpm check:size"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",