A little direction for worlds worth wandering. @cranberry-forge/wayfinder is a bounded weighted XZ grid navigator. It combines deterministic A* search, world/cell mapping, atomic terrain edits, explicit corner policies, and validated JSON snapshots in a small independent runtime.
Version 0.1.0 · ESM · JavaScript + TypeScript declarations · Zero runtime dependencies · MIT
Moonpost Dispatch
Run the repository locally and open /wayfinder.html to explore a floating tiled courier garden. Choose a delivery tile, paint blocking planters, or plant costly lavender. The route recalculates immediately and a small courier follows its cell-center points. Try the winding maze or the sealed garden, change diagonal policy, and export or import your arrangement. The keyboard/touch cell map offers the same controls as the 3D canvas. Decorative arches, stairs, buildings, and satellite terraces sit outside the navigable grid.
The showcase uses Three.js; the package does not. Its runtime imports no renderer, framework, storage provider, or other Cranberry Forge tool.
Where it fits
A* and weighted grids are established techniques. Wayfinder's value is the grid-specific integration contract: deterministic results, explicit diagonal semantics, world mapping, bounded edits/searches, and portable validated saves. It is not a new pathfinding algorithm or a general navigation mesh system.
| Tool | Documented focus | A useful fit |
|---|---|---|
| three-pathfinding | Paths on 3D navigation meshes, zones, and movement clamping for Three.js | Imported navigation geometry and movement over irregular walkable surfaces. |
| Yuka | Game AI including steering, agent design, graph search, navigation meshes, and JSON state | Projects needing a broader engine-independent AI system. |
| Wayfinder | Weighted single-layer XZ grids with small, explicit editing and save APIs | Tile gardens, tactical boards, floor layouts, and prototype worlds whose traversability is naturally cell based. |
Primary sources reviewed on September 8, 2026. This is a comparison of documented focus, not a feature-exclusivity claim or performance benchmark. Wayfinder does not handle slopes, multiple floors, agent radius, collision physics, path smoothing, crowd avoidance, steering, or navigation mesh generation. Reserve sufficient blocked-cell clearance for your actor and keep the visual movement consistent with the grid.
Documentation and verification
The Cranberry Forge repository includes nine meaningful runtime tests in tests/wayfinder.test.mjs, including comparison against an independent Dijkstra oracle on 45 seeded weighted grids across all diagonal policies. Other checks cover deterministic ties, entry costs, world boundaries, budgets/statuses, atomic edits, snapshots, sparse inputs, and revision exhaustion. Public declaration usage is checked in tests/wayfinder-types.ts.
node --test tests/wayfinder.test.mjs