feat(api)!: singleton modules, shared cache, direct namespace export (0.9.0, closes #41)

[kalwalt]

Closes #41. Breaking change — ships as 0.9.0. Restores original jsfeat's calling convention. Designed via /brainstorming; full migration guide added at docs/migration-0.9.md.

What changes for consumers

// BEFORE (0.8.x)
import pkg from "@webarkit/jsfeat-next";
const jsfeatNext = pkg.jsfeatNext;          // double-namespace unwrap
const imgproc = new jsfeatNext.imgproc();   // instantiate every module
imgproc.grayscale(rgba, w, h, gray);

// AFTER (0.9.0)
import jsfeatNext from "@webarkit/jsfeat-next";   // default export IS the namespace
jsfeatNext.imgproc.grayscale(rgba, w, h, gray);   // singleton — no `new`

Three things resolved (all three were rows 1, 4, 5 of the parity audit's Axis 2):

1. Double namespace gone — src/index.ts default-exports the namespace directly, so the UMD global and ESM default both ARE the namespace.
2. Algorithm modules are singletons — the 14 algorithm modules (imgproc, math, matmath, linalg, transform, fast_corners, yape, yape06, orb, optical_flow_lk, motion_estimator, affine2d, homography2d, cache) are pre-constructed instances on the namespace; no new.
3. One shared buffer pool — src/core/core.ts creates a module-level shared_cache every module binds to, replacing per-instance 30-buffer/76.8 KB pools. Falls out naturally from singletons.

Unchanged: the data-structure constructors (matrix_t, keypoint_t, pyramid_t, ransac_params_t) are still newed — they're genuine constructors in jsfeat too. Constants stay on the namespace.

Why singletons, not a statics-rewrite (the ground truth)

This isn't "match jsfeat for its own sake" — verified against the actual inspirit/jsfeat source:

• jsfeat's modules are singletons by design, even stateful ones. jsfeat_fast_corners.js is an IIFE holding closure-level _threshold, exposed as one object, and configured once at load via fast_corners.set_threshold(20). There was never a notion of multiple independently-configured detectors.
• The cache's whole purpose requires sharing. jsfeat's imgproc borrows from the one global jsfeat.cache so buffers freed by one stage feed the next. Per-instance pools defeated that.
• Removes a footgun. With classes, following jsfeat-style examples you could new a module inside a per-frame loop and silently reallocate pools every frame. With singletons that's impossible by construction.
• The classes are kept verbatim (only how they're attached changed), so the 57 parity tests keep guarding unmodified algorithm code — a statics-rewrite would have churned every protected line for zero benefit.

Versioning

Ships as 0.9.0 (pre-1.0 semver allows breaking minors). 1.0.0-alpha was considered and rejected — the release pipeline can't handle prerelease tags yet (filed as #81). Hard cut, no compat shim.

Tests & verification

• Parity suite converted to the new convention; new tests/api-shape.test.ts pins the namespace shape, singleton identity, shared-cache identity, and constructor surface. 63/63 pass.
• All 22 examples/ converted; the 5 non-camera ones executed in Node against the new bundle, all 22 static-scanned, and browser-tested by @kalwalt. browser.html's new jsfeat.cache() usage rewritten (jsfeat never supported that either).
• tsc --noEmit clean · prettier --check clean · UMD+ESM bundle shapes verified (no double namespace, singletons callable, shared pool public).
• dist/ + types/ rebuilt and committed in this PR — a deliberate deviation from the source-only convention, at @kalwalt's request: for an API-breaking change, a stale committed bundle made local browser testing confusing.

Docs

docs/migration-0.9.md (full old→new table + motivation), README quick start, AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and the audit doc (Axis 2 marked resolved with a new status column).

Decision log

Decision	Alternative	Why
Singletons via new X() in aggregator	Rewrite classes into static/object-literal namespaces	Keeps classes verbatim → parity tests still guard them
Shared module-level shared_cache	Keep per-instance pools	Matches jsfeat; removes per-frame realloc footgun
0.9.0, hard cut	1.0.0-alpha / compat shim	Pipeline can't do prerelease tags (#81); few consumers; shim adds surface
Single PR	Module-per-PR (like #47)	One coherent, interdependent change
Commit dist/types here	Source-only (rebuild at release)	User request; avoids stale-bundle test confusion on a breaking change

🤖 Generated with Claude Code