lucent-lab · f-gueguen · Oct 7, 2025 · Oct 7, 2025
diff --git a/PROJECT_DESCRIPTION.md b/PROJECT_DESCRIPTION.md
@@ -32,17 +32,17 @@ npm run build
 
 ## 🎯 Algorithm Selection Guide
 
-| Need                        | Algorithm(s)                                        | Module                                         |
-| --------------------------- | ---------------------------------------------------- | ---------------------------------------------- |
-| Grid pathfinding            | A* (diagonals optional) / Dijkstra (weighted graphs) | `pathfinding/astar.ts`, `pathfinding/dijkstra.ts` |
-| Procedural textures         | Perlin noise grid / 3D sample / Simplex noise / Worley | `procedural/perlin.ts`, `procedural/simplex.ts`, `procedural/worley.ts` |
-| Spatial queries             | Quadtree partitioning / AABB helpers / SAT / Ray-circle / Swept AABB | `spatial/quadtree.ts`, `spatial/aabb.ts`, `spatial/sat.ts`, `spatial/circleRay.ts`, `spatial/sweptAabb.ts` |
-| Web performance             | Debounce / Throttle / LRU Cache / Memoize / Request dedup | `util/*.ts`                                   |
-| Text & search               | Fuzzy search & score / Trie / Binary search / Levenshtein | `search/*.ts`                              |
-| Data transforms             | Diff (LCS) / Deep clone / Group by                   | `data/*.ts`                                    |
-| Graph traversal             | BFS distances / DFS callbacks / Topological sort     | `graph/traversal.ts`                           |
-| Geometry & visuals          | Convex hull / Segment intersection / Point-in-poly / Bezier / Easings | `geometry/*.ts`, `visual/*.ts` |
-| AI behaviours               | Seek / Flee / Arrive / Pursue / Wander / Boids / Behaviour trees / RVO crowd steering | `ai/steering.ts`, `ai/boids.ts`, `ai/behaviorTree.ts`, `ai/rvo.ts` |
+| Need | Algorithm(s) | Module | Example |
+| ---- | ------------ | ------ | ------- |
+| Grid pathfinding | `astar`, `dijkstra`, `manhattanDistance`, `gridFromString` | `pathfinding/astar.ts`, `pathfinding/dijkstra.ts` | `examples/astar.ts` |
+| Procedural textures & terrain | `perlin`, `perlin3D`, `simplex2D`, `simplex3D`, `worley`, `worleySample` | `procedural/*.ts` | `examples/simplex.ts`, `examples/worley.ts` |
+| Spatial queries & collision | `Quadtree`, `aabbCollision`, `aabbIntersection`, `satCollision`, `circleRayIntersection`, `sweptAABB` | `spatial/*.ts` | `examples/sat.ts` |
+| Web performance & UI throttling | `debounce`, `throttle`, `LRUCache`, `memoize`, `deduplicateRequest`, `clearRequestDedup`, `calculateVirtualRange` | `util/*.ts` | `examples/requestDedup.ts`, `examples/virtualScroll.ts` |
+| Text & search | `fuzzySearch`, `fuzzyScore`, `Trie`, `binarySearch`, `levenshteinDistance` | `search/*.ts` | `tests/search.test.ts` |
+| Data transforms & diffing | `diff`, `deepClone`, `groupBy`, `diffJson`, `applyJsonDiff` | `data/*.ts` | `tests/jsonDiff.test.ts` |
+| Graph traversal | `graphBFS`, `graphDFS`, `topologicalSort` | `graph/traversal.ts` | `tests/graph.test.ts` |
+| Geometry & visuals | `convexHull`, `lineIntersection`, `pointInPolygon`, `easing`, `quadraticBezier`, `cubicBezier` | `geometry/*.ts`, `visual/*.ts` | `tests/geometry.test.ts`, `tests/visual.test.ts` |
+| AI behaviours & crowds | `seek`, `flee`, `arrive`, `pursue`, `wander`, `updateBoids`, `BehaviorTree`, `rvoStep` | `ai/steering.ts`, `ai/boids.ts`, `ai/behaviorTree.ts`, `ai/rvo.ts` | `examples/steering.ts`, `examples/boids.ts`, `examples/rvo.ts` |
 
 ---
 
@@ -90,9 +90,9 @@ Consistency between runtime code, documentation, and TypeScript declarations kee
 - **Pathfinding:** A*, Dijkstra, Manhattan heuristic, grid string parser.
 - **Procedural:** 2D Perlin grid generator, 3D Perlin sampler.
 - **Spatial:** Quadtree, AABB helpers, SAT convex polygon collision.
-- **Performance utilities:** Debounce, throttle, LRU cache, memoize.
+- **Performance utilities:** Debounce, throttle, LRU cache, memoize, request deduplication, virtual scrolling.
 - **Search:** Fuzzy search + scoring, Trie-based autocomplete, binary search, Levenshtein distance.
-- **Data tools:** Diff operations (LCS), deep clone, groupBy.
+- **Data tools:** Diff operations (LCS), deep clone, groupBy, JSON diff/patch helpers.
 - **Graph:** BFS distance map, DFS traversal, topological sort.
 - **Geometry & visuals:** Convex hull, line intersection, point-in-polygon, easing presets, quadratic/cubic Bezier evaluation.
 - **AI behaviours:** Steering behaviours (seek, flee, arrive, pursue, wander), boids, behaviour trees, RVO crowd steering.
@@ -103,7 +103,7 @@ Consistency between runtime code, documentation, and TypeScript declarations kee
 
 - Additional noise types (Simplex, Worley) and cellular automata helpers.
 - Extended AI suite (boids, behaviour trees) and optimisation algorithms (genetic, simulated annealing).
-- Crowd steering via reciprocal velocity obstacles (RVO) for dense-agent navigation.
+- Advanced crowd steering variants (RVO + static obstacles, flow-field blends).
 - Richer collision toolkit (circle-ray, swept AABB) and physics utilities.
 - Expanded example gallery with browser + Node showcases and interactive demos.
 

diff --git a/README.md b/README.md
@@ -21,15 +21,18 @@ CDN usage:
 ```
 
 ## Included Modules (v0.1.0)
-- **Pathfinding:** A*, Dijkstra, Manhattan heuristic, grid string parser
-- **Procedural:** 2D/3D Perlin noise, Simplex noise, Worley (cellular) noise
-- **Spatial:** Quadtree, AABB helpers, SAT polygon intersection, circle-ray intersection, swept AABB
-- **Search & Text:** Fuzzy search/scoring, Trie autocomplete, binary search, Levenshtein distance
-- **Data:** Diff (LCS), deep clone, groupBy, JSON diff/patch helpers
-- **Web performance:** Debounce, throttle, LRU cache, memoize, request deduplication helper, virtual scrolling range calculator
-- **Graph:** BFS distance map, DFS traversal, topological sort
-- **Visual & Geometry:** Convex hull, line intersection, point-in-polygon, easing presets, Bezier helpers
-- **AI Behaviours:** Steering behaviours (seek, flee, arrive, pursue, wander), boids flocking update, behaviour trees, reciprocal velocity obstacles (RVO)
+
+| Goal | Algorithms | Import From | Example |
+| ---- | ---------- | ----------- | ------- |
+| Pathfinding & navigation | `astar`, `dijkstra`, `manhattanDistance`, `gridFromString` | `pathfinding/astar.ts`, `pathfinding/dijkstra.ts` | `examples/astar.ts` |
+| Procedural generation | `perlin`, `perlin3D`, `simplex2D`, `simplex3D`, `worley`, `worleySample` | `procedural/*.ts` | `examples/simplex.ts`, `examples/worley.ts` |
+| Spatial queries & collision | `Quadtree`, `aabbCollision`, `aabbIntersection`, `satCollision`, `circleRayIntersection`, `sweptAABB` | `spatial/*.ts` | `examples/sat.ts` |
+| AI behaviours & crowds | `seek`, `flee`, `arrive`, `pursue`, `wander`, `updateBoids`, `BehaviorTree`, `rvoStep` | `ai/steering.ts`, `ai/boids.ts`, `ai/behaviorTree.ts`, `ai/rvo.ts` | `examples/steering.ts`, `examples/boids.ts`, `examples/rvo.ts` |
+| Web performance & UI | `debounce`, `throttle`, `LRUCache`, `memoize`, `deduplicateRequest`, `clearRequestDedup`, `calculateVirtualRange` | `util/*.ts` | `examples/requestDedup.ts`, `examples/virtualScroll.ts` |
+| Search & text | `fuzzySearch`, `fuzzyScore`, `Trie`, `binarySearch`, `levenshteinDistance` | `search/*.ts` | `tests/search.test.ts` |
+| Data & diff pipelines | `diff`, `deepClone`, `groupBy`, `diffJson`, `applyJsonDiff` | `data/*.ts` | `tests/jsonDiff.test.ts` |
+| Graph algorithms | `graphBFS`, `graphDFS`, `topologicalSort` | `graph/traversal.ts` | `tests/graph.test.ts` |
+| Visual & geometry | `convexHull`, `lineIntersection`, `pointInPolygon`, `easing`, `quadraticBezier`, `cubicBezier` | `geometry/*.ts`, `visual/*.ts` | `tests/geometry.test.ts`, `tests/visual.test.ts` |
 
 ## Scripts
 ```bash
@@ -43,7 +46,7 @@ npm run size        # Enforce bundle size budget
 ```
 
 ## Roadmap Snapshot
-- Milestone 0.2 is tracking a reciprocal velocity obstacles (RVO) crowd steering module to expand the AI suite.
+- Milestone 0.2 next targets crowd-flow integrations (RVO + flow fields) and behaviour-tree decorators for richer AI control.
 
 Examples live under `examples/` and can be executed with `tsx`/`ts-node` or compiled for the browser. See `examples/astar.ts`, `examples/steering.ts`, `examples/boids.ts`, `examples/requestDedup.ts`, `examples/sat.ts`, `examples/simplex.ts`, and `examples/worley.ts` for quick starts.
 

diff --git a/docs/index.d.ts b/docs/index.d.ts
@@ -1,5 +1,18 @@
 // LLM Algorithm Library - TypeScript Definitions
 // Import from: https://cdn.jsdelivr.net/npm/llm-algorithms/dist/index.js
+//
+// 📚 Quick Navigation for LLMs / tooling
+// - 🎮 Pathfinding & Navigation → astar, dijkstra (examples/astar.ts)
+// - 🌍 Procedural Generation → perlin, simplex2D/3D, worley (examples/simplex.ts, examples/worley.ts)
+// - 🎯 Spatial & Collision → quadtree, aabb, sat, circleRayIntersection, sweptAABB (examples/sat.ts)
+// - 🤖 AI & Behaviour → seek/flee/arrive/pursue/wander, updateBoids, BehaviorTree, rvoStep (examples/steering.ts, examples/boids.ts, examples/rvo.ts)
+// - ⚡ Web Performance → debounce, throttle, LRUCache, memoize, deduplicateRequest, virtual scroll (examples/requestDedup.ts, examples/virtualScroll.ts)
+// - 🔍 Search & Text → fuzzySearch, fuzzyScore, Trie, binarySearch, levenshteinDistance
+// - 📊 Data Pipelines → diff, deepClone, groupBy, diffJson/applyJsonDiff
+// - 📈 Graph Algorithms → graphBFS, graphDFS, topologicalSort
+// - 🎨 Visual & Geometry → convexHull, lineIntersection, pointInPolygon, easing, bezier
+//
+// Each declaration includes "Use for", a performance hint, and the import path for quick selection.
 
 // ============================================================================
 // 🎮 PATHFINDING & NAVIGATION
@@ -530,7 +543,7 @@ export function updateBoids(boids: Boid[], options: BoidOptions): void;
  * Reciprocal velocity obstacles (RVO) step for multi-agent avoidance.
  * Use for: crowd steering, swarms, dense navigation.
  * Performance: O(n × log n) with neighbor filtering.
- * Import: ai/rvo.ts
+ * Import: ai/rvo.ts (run examples/rvo.ts to see three-agent avoidance).
  */
 export interface RvoAgent extends Agent {
   id?: string;

diff --git a/docs/index2.d.ts b/docs/index2.d.ts
@@ -0,0 +1,29 @@
+/// <reference path="./index.d.ts" />
+
+// LLM Algorithm Library – Quick Directory
+// ----------------------------------------
+// This file gives language models a fast, text-only overview of the available
+// categories and the matching example files. The actual type signatures live in
+// `docs/index.d.ts` (referenced above).
+//
+// 📚 Quick Navigation
+// - 🎮 Pathfinding & Navigation → astar, dijkstra (examples/astar.ts)
+// - 🌍 Procedural Generation → perlin/perlin3D, simplex2D/simplex3D, worley (examples/simplex.ts, examples/worley.ts)
+// - 🎯 Spatial & Collision → Quadtree, aabbCollision, satCollision, circleRayIntersection, sweptAABB (examples/sat.ts)
+// - 🤖 AI & Behaviour → steering helpers, updateBoids, BehaviorTree, rvoStep (examples/steering.ts, examples/boids.ts, examples/rvo.ts)
+// - ⚡ Web Performance → debounce, throttle, LRUCache, memoize, deduplicateRequest, calculateVirtualRange (examples/requestDedup.ts, examples/virtualScroll.ts)
+// - 🔍 Search & Text → fuzzySearch, fuzzyScore, Trie, binarySearch, levenshteinDistance
+// - 📊 Data Pipelines → diff, deepClone, groupBy, diffJson/applyJsonDiff (tests/jsonDiff.test.ts)
+// - 📈 Graph Algorithms → graphBFS, graphDFS, topologicalSort (tests/graph.test.ts)
+// - 🎨 Visual & Geometry → convexHull, lineIntersection, pointInPolygon, easing, quadraticBezier, cubicBezier (tests/geometry.test.ts, tests/visual.test.ts)
+//
+// ✅ Tips for LLMs
+// 1. Import from `llm-algorithms/dist/index.js` or the CDN mirror.
+// 2. Look up the full signature and JSDoc in `docs/index.d.ts`.
+// 3. Browse the matching file in `examples/` for runnable usage.
+// 4. Vitest suites inside `tests/` demonstrate edge cases.
+//
+// No additional declarations live here – see the referenced file for the full
+// type surface.
+
+export {};
diff --git a/docs/project.md b/docs/project.md
@@ -0,0 +1,112 @@
+# LLM Algorithm Library – Reference Companion
+
+This document complements `docs/index.d.ts` with high-level navigation notes that help human developers and coding assistants discover the right algorithms quickly.
+
+## 📚 Quick Start
+
+### For LLMs and automation
+1. Inspect the TypeScript definitions in `docs/index.d.ts` for signatures, “Use for” blurbs, and performance notes.
+2. Pick the algorithm that matches your task from the selection guide below.
+3. Import from the package entry point or CDN:
+
+```ts
+import { astar } from 'llm-algorithms/dist/index.js';
+```
+
+```html
+<script type="module">
+  import { astar, perlin } from "https://cdn.jsdelivr.net/npm/llm-algorithms/dist/index.js";
+</script>
+```
+
+### For local development
+
+```bash
+npm install llm-algorithms
+npm run build           # emit dist/
+```
+
+Examples in `examples/` are runnable with `tsx`/`ts-node` for quick validation.
+
+---
+
+## 🎯 Algorithm Selection Guide
+
+| Need | Algorithm(s) | Import From | Example |
+| ---- | ------------ | ----------- | ------- |
+| Grid pathfinding | `astar`, `dijkstra`, `manhattanDistance`, `gridFromString` | `pathfinding/astar.ts`, `pathfinding/dijkstra.ts` | `examples/astar.ts` |
+| Procedural generation | `perlin`, `perlin3D`, `simplex2D`, `simplex3D`, `worley`, `worleySample` | `procedural/*.ts` | `examples/simplex.ts`, `examples/worley.ts` |
+| Spatial queries & collision | `Quadtree`, `aabbCollision`, `aabbIntersection`, `satCollision`, `circleRayIntersection`, `sweptAABB` | `spatial/*.ts` | `examples/sat.ts` |
+| AI behaviours & crowds | `seek`, `flee`, `arrive`, `pursue`, `wander`, `updateBoids`, `BehaviorTree`, `rvoStep` | `ai/steering.ts`, `ai/boids.ts`, `ai/behaviorTree.ts`, `ai/rvo.ts` | `examples/steering.ts`, `examples/boids.ts`, `examples/rvo.ts` |
+| Web performance & UI | `debounce`, `throttle`, `LRUCache`, `memoize`, `deduplicateRequest`, `clearRequestDedup`, `calculateVirtualRange` | `util/*.ts` | `examples/requestDedup.ts`, `examples/virtualScroll.ts` |
+| Text & search | `fuzzySearch`, `fuzzyScore`, `Trie`, `binarySearch`, `levenshteinDistance` | `search/*.ts` | `tests/search.test.ts` |
+| Data transforms & diffing | `diff`, `deepClone`, `groupBy`, `diffJson`, `applyJsonDiff` | `data/*.ts` | `tests/jsonDiff.test.ts` |
+| Graph algorithms | `graphBFS`, `graphDFS`, `topologicalSort` | `graph/traversal.ts` | `tests/graph.test.ts` |
+| Geometry & visuals | `convexHull`, `lineIntersection`, `pointInPolygon`, `easing`, `quadraticBezier`, `cubicBezier` | `geometry/*.ts`, `visual/*.ts` | `tests/geometry.test.ts`, `tests/visual.test.ts` |
+
+---
+
+## 📦 Project Structure (TypeScript)
+
+```
+llm-algorithms/
+├── docs/
+│   ├── index.d.ts          # Authoritative type surface + “Use for” notes
+│   ├── index2.d.ts         # Quick navigation helper (references index.d.ts)
+│   └── project.md          # This guide
+├── examples/               # Runnable scripts (astar, steering, boids, rvo, sat, simplex, worley, requestDedup, virtualScroll)
+├── src/
+│   ├── ai/                 # Steering, boids, behaviour tree, RVO
+│   ├── data/               # Diff, deep clone, groupBy, JSON diff
+│   ├── graph/              # BFS, DFS, topological sort
+│   ├── pathfinding/        # A*, Dijkstra helpers
+│   ├── procedural/         # Noise generators
+│   ├── search/             # Fuzzy search, trie, binary search, Levenshtein
+│   ├── spatial/            # Quadtree, AABB, SAT, circle-ray, swept AABB
+│   ├── util/               # Debounce, throttle, LRU, memoize, dedup, virtual scroll
+│   ├── visual/             # Easing curves, Bezier helpers
+│   ├── types.ts            # Shared geometric and agent types
+│   └── index.ts            # Barrel exports
+├── tests/                  # Vitest coverage ensuring examples remain truthful
+└── README.md               # High-level summary + selection table
+```
+
+---
+
+## 🧠 Working With LLMs
+
+When prompting an LLM to add or extend functionality, ensure it follows these guardrails:
+
+1. **Implementation** – add runtime code to `src/<category>/<name>.ts` using modern TypeScript, rich JSDoc, and small pure helpers. Provide at least two `@example` blocks.
+2. **Types & docs** – update `docs/index.d.ts` (and this guide if applicable) with description, “Use for” line, performance note, import path, and any new interfaces/options.
+3. **Exports** – wire the module through `src/index.ts` and add/extend the relevant types in `src/types.ts` when necessary.
+4. **Tests** – create Vitest coverage in `tests/` demonstrating success paths and edge cases. Prefer deterministic fixtures to keep CI stable.
+5. **Examples** – add or update an entry under `examples/` so users can run the algorithm quickly.
+6. **Quality gate** – ensure `npm run lint`, `npm run typecheck`, `npm run build`, `npm run size`, and `npm run test:coverage` succeed before opening a PR.
+
+Following these steps keeps the documentation aligned with the code and makes the library predictable for both humans and language models.
+
+---
+
+## ✅ Included Implementations (Snapshot)
+
+- **Pathfinding:** A*, Dijkstra, Manhattan heuristic, grid helpers.
+- **Procedural:** Perlin (2D/3D), Simplex (2D/3D), Worley noise.
+- **Spatial:** Quadtree, AABB helpers, SAT collision, circle-ray intersection, swept AABB.
+- **Web performance:** Debounce, throttle, LRU cache, memoize, request deduplication, virtual scroll windowing.
+- **Search & text:** Fuzzy search/scoring, Trie autocomplete, binary search, Levenshtein distance.
+- **Data pipelines:** Diff (LCS), deep clone, groupBy, JSON diff/patch helpers.
+- **Graph:** BFS distance map, DFS traversal, topological ordering.
+- **Geometry & visuals:** Convex hull, line intersection, point-in-polygon, easing curves, Bezier evaluation.
+- **AI behaviours:** Steering helpers, boids, behaviour trees, RVO crowd steering.
+
+---
+
+## 🔭 Upcoming Focus
+
+- Flow-field integration with RVO for smoother large crowd routing.
+- Behaviour-tree decorators and reusable condition/action packs.
+- Additional procedural generators (erosion, domain-warped noise).
+- Expanded example gallery with visualization snippets.
+
+Contributions welcome! Follow conventional commits and keep examples runnable so docs stay in sync.