@vectojs/core 1.16.2 → 1.17.0

package/dist/tree/Scene.d.ts

@@ -13,6 +13,7 @@ export interface IWebGPUParticleSystemManager {
 import { Entity } from './Entity';
 import { IRenderer } from '../renderer/IRenderer';
 import { type WasmModuleSource, type WasmTransformBackend } from '../wasm/backend';
+import { type CoreWasmRuntime } from '../wasm/runtime';
 import { type HitModuleSource, type HitTestBackend } from '../wasm/hit-backend';
 import { type AnimModuleSource, type AnimBackend } from '../wasm/anim-backend';
 import { type ParticleModuleSource, type ParticleBackend } from '../wasm/particle-backend';
@@ -380,11 +381,54 @@ export declare class Scene {
      * Resolves `true` if WASM is now active, `false` if the JS path remains.
      */
     enableWasmTransforms(source: WasmModuleSource): Promise<boolean>;
+    /**
+     * The one WASM instance this Scene's accelerators share.
+     *
+     * Each `enableWasm*` used to instantiate the binary itself, so enabling all
+     * four compiled the same module four times and held four linear memories. The
+     * Rust crate already keeps transform/anim/hit/particle in separate statics, so
+     * one instance serves all of them without aliasing. The compiled module is
+     * cached globally; the instance is per-Scene, which is the isolation that
+     * actually matters.
+     */
+    private _wasmRuntime;
+    /**
+     * Load (or reuse) this Scene's shared WASM runtime.
+     *
+     * Returns `null` on any failure — CSP `wasm-unsafe-eval`, a 404, corrupt bytes,
+     * unsupported SIMD — so every caller keeps its JS path. Failure is the default
+     * state here, not an error path.
+     */
+    private ensureWasmRuntime;
+    /**
+     * Install a pre-built runtime, so several Scenes can share one compile while
+     * each keeps its own stores. Pass `null` to detach (backends already installed
+     * keep working; only subsequent `enableWasm*` calls re-load).
+     */
+    setWasmRuntime(runtime: CoreWasmRuntime | null): void;
+    /** The shared WASM runtime, if one has been loaded. */
+    get wasmRuntime(): CoreWasmRuntime | null;
     private _hitWasm;
     private _hitGridFrame;
     private _hitGridOk;
     private _hitSlotEntity;
     private _hitBoundless;
+    /** Reused buffer for the fused gather, so a pointer query allocates nothing. */
+    private _hitGatherBuffer;
+    /**
+     * Whether the last grid build sourced its AABBs from the WASM transform store
+     * rather than recomputing them in JS. Diagnostic only — both paths must
+     * produce the same entity for a given point.
+     */
+    private _hitFusedGather;
+    /**
+     * Whether `compute_aabbs` has run against the current frame's world matrices.
+     * The AABB pass is only meaningful after a `compose_*`, so the fused gather
+     * must not read the views before then.
+     */
+    private _wasmAabbsFresh;
+    /** Did the last hit-grid build use the fused (WASM-store) gather? */
+    get hitGatherPath(): 'fused' | 'js';
     /** Which backend answers `findEntityAt` for the main tree. */
     get hitTestBackend(): 'js' | 'wasm';
     /** Install (or clear) a WASM hit-test backend directly. Prefer
@@ -464,7 +508,51 @@ export declare class Scene {
      * own target browser mix and driver-kind distribution, or leave WASM
      * animation batching disabled entirely on a Firefox-heavy audience.
      */
-    animDriverGateCount: number;
+    /**
+     * Back-compat alias for {@link animGate}. Reading it returns the tween gate
+     * (the conservative one the single knob used to represent); writing it sets all
+     * three, so code that tuned one number keeps behaving as before.
+     *
+     * Prefer {@link animGate} — a single threshold cannot be right for both kinds,
+     * which is why this exists as an alias rather than the primary control.
+     */
+    get animDriverGateCount(): number;
+    set animDriverGateCount(n: number);
+    /**
+     * Per-kind driver gates, in active batchable drivers.
+     *
+     * Measured on the integrated path (`benchmarks/anim-wasm-scene`, real Chrome
+     * 150 / Firefox 153): spring and mixed workloads are a ~1.4-2.3x win from 128
+     * drivers up through 16384, while pure tween is a **0.71x loss** at 128 and
+     * only turns net-positive near 256. One scalar threshold therefore had to be
+     * set for the worst kind, discarding the 128-255 spring win to avoid making a
+     * tween-heavy scene slower.
+     *
+     * Firefox is a net loss at every count measured up to 16384 — not an
+     * allocation artifact (confirmed after removing all per-frame allocation from
+     * gather/scatter); SpiderMonkey's wasm-boundary cost for this call shape
+     * appears to structurally exceed the saving at these scales. These defaults are
+     * Chrome-oriented; on a Firefox-heavy audience, leave
+     * {@link enableWasmAnimBatching} off entirely rather than tuning these.
+     *
+     * Setting {@link animDriverGateCount} overwrites all three, so existing code
+     * that tuned the single knob keeps working unchanged.
+     */
+    private _animBatchedLastFrame;
+    /**
+     * Whether the WASM batch path actually ran on the most recent frame.
+     *
+     * Distinct from {@link animBackend}, which reports only that a backend is
+     * installed — a gate below the driver count means the frame still ticked in JS.
+     * Conflating the two makes it easy to believe an accelerator is active when it
+     * never opens.
+     */
+    get animBatchedLastFrame(): boolean;
+    animGate: {
+        spring: number;
+        tween: number;
+        mixed: number;
+    };
     /** Which backend advances active property drivers on the current gate
      *  decision. Reflects only whether a backend is installed — the per-frame
      *  gate can still choose the JS path even when this reads `'wasm'`. */
@@ -542,6 +630,17 @@ export declare class Scene {
      * input view and runs the kernel. Returns `null` if there is no backend.
      */
     private _syncWasmStore;
+    /**
+     * Run the WASM world-AABB pass over the current frame's world matrices, so the
+     * fused hit gather can read AABBs straight out of the store.
+     *
+     * Local bounds are uploaded here rather than in the per-frame transform sync
+     * because `getBounds()` is a virtual call that allocates a rect on most
+     * entities — paying it every frame for a query that may never come would move
+     * cost onto the render path to save it on hover. Returns `false` if any entity
+     * cannot supply bounds through the store, so the caller uses the JS gather.
+     */
+    private _ensureWasmAabbs;
     /**
      * Authoritative paint order for semantic nodes discovered during the main
      * render. A node may not have a DOM projection until the following a11y
@@ -673,7 +772,19 @@ export declare class Scene {
      * without removing it from the scene graph. Components that manage dynamic
      * interactive *child* entities (e.g. a {@link Entity}'s per-link hotspots) call
      * this before discarding those children so their shadow `<a>`/controls don't
-     * leak (the per-frame `syncA11y` only creates/updates, it never prunes).
+     * leak.
+     *
+     * `syncA11y` itself only creates and updates, never prunes — but it is always
+     * followed by `enforceA11yDomOrder`, whose prune pass removes any element
+     * whose entity is no longer reachable in the tree or no longer satisfies
+     * {@link shouldProjectA11y}. So an entity that is `remove()`d, or whose
+     * `interactive` flips to `false`, has its element torn down on the next synced
+     * frame without any explicit call.
+     *
+     * This method is for the case that pass cannot see: a child dropped from a
+     * component's own bookkeeping while still parented, or one discarded before
+     * the next sync runs. Calling it is always safe and is the right habit for
+     * pooled children.
      *
      * @param entity - The subtree whose shadow nodes should be removed.
      */
@@ -756,6 +867,26 @@ export declare class Scene {
     /** True when any node in the subtree has a pending animation. */
     /** True when any node in the subtree is interactive (drives a11y sync). */
     private syncOptionalAttribute;
+    /**
+     * Whether `node` should have an a11y shadow element projected for it.
+     *
+     * The single authority for that decision. It was previously inlined verbatim
+     * at four call sites — `syncA11y` (create/update), `enforceA11yDomOrder`
+     * (which ids survive pruning), `getA11yTree` (the public snapshot) and
+     * `render` (z-index / reading-order assignment). Four copies of one predicate
+     * is a standing correctness hazard: if any of them drifts, elements either
+     * leak (created but never marked active, so pruned every frame and rebuilt) or
+     * go missing from the semantic tree while still present in the DOM.
+     *
+     * A box is required because a zero-size element is unfocusable and
+     * unhittable; `a11yFullViewport` is the deliberate exception, since those
+     * nodes are boundless interaction surfaces mounted behind everything else.
+     *
+     * Keep this the only place the rule is written. A planned per-entity
+     * `a11yProjection` mode ('eager' | 'onDemand' | 'never') extends exactly this
+     * predicate, which is only tractable while it has one home.
+     */
+    private shouldProjectA11y;
     private syncA11y;
     /**
      * Mirror one entity's static text ({@link Entity.getContentProjection}) as a

package/dist/wasm/backend.d.ts

@@ -9,6 +9,25 @@
  * entity: at ~12-31 ns/crossing a per-entity call at 100k would cost >1 ms/frame.
  */
 import type { TransformStore } from './soa';
+/**
+ * Status codes returned by the crate's fallible exports, mirroring the `STATUS_*`
+ * constants in `crates/vectojs-core-rs/src/lib.rs`.
+ *
+ * The kernels used to trust their arguments completely — the Safety contracts
+ * were enforced only by this file's calling convention, and PR #136's review
+ * found two out-of-bounds read paths that way. Now a rejected call writes nothing
+ * and reports why, so a bad batch degrades to the JS path instead of rendering
+ * from a half-written store.
+ */
+export declare const WASM_STATUS: {
+    readonly OK: 0;
+    /** A count exceeded what `init` allocated. */
+    readonly CAPACITY: 1;
+    /** A kernel ran before `init`. */
+    readonly UNINITIALIZED: 2;
+    /** A sibling run addressed a slot or parent outside the store. */
+    readonly BAD_RUN: 3;
+};
 /** Which kernel to run. `simd` is the default; `scalar` exists for A/B and for
  *  the (theoretical) case of a build without simd128. Both are f64 and
  *  bit-identical to {@link composeJS}. */
@@ -63,10 +82,15 @@ export declare class WasmTransformBackend {
      * once at the current capacity to size the store and set the run count; call
      * {@link uploadRuns} after a topology change.
      */
-    runKernel(kernel?: Kernel): void;
+    runKernel(kernel?: Kernel): number;
     /** Upload only the run table + count (topology), leaving per-entity inputs to
      *  the resident views. Call when the tree structure changes, not per frame. */
     uploadRuns(store: TransformStore): void;
+    /**
+     * Status of the most recent kernel or run-table call. `WASM_STATUS.OK` unless
+     * the crate rejected its arguments, in which case that call was a no-op.
+     */
+    lastStatus: number;
     /** The resident wasm input views (`x,y,sx,sy,cos,sin,opacity`), valid until
      *  the next capacity growth. Writing here is what makes uploads unnecessary. */
     inputView(): {
@@ -117,6 +141,18 @@ export declare class WasmTransformBackend {
         amaxx: Float64Array;
         amaxy: Float64Array;
     };
+    /**
+     * Re-create the typed-array views if the memory buffer they were built over has
+     * been detached.
+     *
+     * Necessary because all backends of a Scene now share one instance, and
+     * therefore one linear memory: another backend's allocation (notably
+     * `hit_init`, which allocates its own grid arrays) can grow the memory and
+     * detach every view built over the old buffer. A detached `Float64Array` reads
+     * as length 0 and silently returns `undefined` for every index, so without this
+     * the transform store appears empty rather than failing loudly.
+     */
+    revalidateViews(): void;
     private ensure;
     /** Rebuild typed-array views after an init() (which may have grown, and thus
      *  detached, the memory buffer). */

package/dist/wasm/hit-store-fused.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Build the hit-test grid's AABB set from the resident WASM transform store,
+ * instead of recomputing every world AABB in JavaScript.
+ *
+ * Why this exists: the WASM hit grid's *kernel* is 65-170x faster than the JS
+ * depth-first walk, but the integrated path was measured **slower** for an
+ * ordinary hover — 11.2ms versus 39us at 100k entities. All of that went to the
+ * JS gather in front of it: walk the tree, `getWorldTransform()`, `getBounds()`,
+ * transform four corners per entity, push into arrays, copy into WASM views. The
+ * kernel win was real and the gather ate it.
+ *
+ * When the transform backend is active, those world AABBs already exist inside
+ * WASM memory: `compose_*` filled the world matrices and `compute_aabbs` reduced
+ * them to `aminx/aminy/amaxx/amaxy`. So the gather can become a copy between two
+ * views of the *same* linear memory (possible only because all backends now share
+ * one instance) plus the index remap below.
+ *
+ * The remap is the whole subtlety. Two different index spaces are in play:
+ *
+ * - The **transform store** re-indexes entities into depth-ordered, contiguous
+ *   sibling runs, because that is what the SIMD composer needs.
+ * - The **hit grid** requires strict **pre-order** indices, because its
+ *   `idx > best` tie-break is only equivalent to `findHitRecursively`'s
+ *   topmost-hit priority under that numbering.
+ *
+ * Those orders differ, so this walks the tree in pre-order exactly as
+ * {@link gatherHitAABBs} does — preserving the priority invariant — and for each
+ * entity reads its AABB from `entity._storeSlot`. Nothing about which entity wins
+ * a hit changes; only where the four numbers come from.
+ */
+import type { Entity } from '../tree/Entity';
+import type { HitGatherResult } from './hit-store';
+/** The resident world-AABB views of the transform backend. */
+export interface ResidentAabbs {
+    aminx: Float64Array;
+    aminy: Float64Array;
+    amaxx: Float64Array;
+    amaxy: Float64Array;
+}
+/**
+ * Pre-order walk collecting AABBs out of the transform store.
+ *
+ * Returns `null` when the store cannot answer for some entity — an unassigned or
+ * out-of-range `_storeSlot`, which happens legitimately when the tree changed
+ * after the last store rebuild. The caller then falls back to the JS gather
+ * rather than indexing a stale slot, because a wrong AABB would mean a wrong
+ * entity under the cursor, and a slower correct answer beats a fast wrong one.
+ *
+ * `slotEntity` here is the *hit* grid's pre-order mapping, unrelated to the
+ * transform store's slots despite the shared name in the result type.
+ */
+export declare function gatherHitAABBsFromStore(root: Entity, aabbs: ResidentAabbs, storeSlotEntity: readonly Entity[], out: HitGatherResult): HitGatherResult | null;
+/** A reusable result buffer, so the fused path allocates nothing per query. */
+export declare function createHitGatherBuffer(): HitGatherResult;

package/dist/wasm/runtime.d.ts

@@ -0,0 +1,76 @@
+/**
+ * A single compiled-and-instantiated `vectojs_core.wasm` shared by every WASM
+ * backend of one Scene.
+ *
+ * Before this, each of the four accelerators (transform, animation, hit-test,
+ * particle) carried its own copy of the same three-way loader and instantiated
+ * the binary independently. A Scene enabling all four therefore compiled the same
+ * module up to four times and held four separate linear memories, plus four sets
+ * of module-level static state.
+ *
+ * Nothing required that: the Rust crate already keeps the transform, anim, hit
+ * and particle stores in distinct statics, so they do not alias inside one
+ * instance. The separate instances bought isolation that was already there, and
+ * paid for it in compile time and memory.
+ *
+ * Two levels of sharing:
+ *
+ * - The compiled {@link WebAssembly.Module} is cached **globally** per source, so
+ *   a second Scene (or a re-enable after `destroy()`) skips compilation.
+ * - The {@link WebAssembly.Instance} is created **per runtime**, so two Scenes
+ *   never share mutable stores. That isolation is the part that matters.
+ *
+ * Backends stay independently gated: holding a runtime does not mean every
+ * accelerator is active. Each `enableWasm*` still decides whether its workload
+ * clears its own threshold.
+ */
+import { WasmTransformBackend } from './backend';
+import { AnimBackend } from './anim-backend';
+import { HitTestBackend } from './hit-backend';
+import { ParticleBackend } from './particle-backend';
+/** Anything a core module can be loaded from. Matches the per-backend loaders. */
+export type CoreModuleSource = BufferSource | string | URL | Response | Promise<Response>;
+/**
+ * Compile a core module, reusing the global cache when the source is a
+ * URL or path. Returns `null` on any failure (CSP `wasm-unsafe-eval`, 404,
+ * corrupt bytes, unsupported) so callers keep the JS path.
+ */
+export declare function loadCoreWasmModule(source: CoreModuleSource): Promise<WebAssembly.Module | null>;
+/**
+ * One instance of the core module, exposing every backend that instance can
+ * serve. All four share its linear memory, which is why they must come from the
+ * same instantiation rather than four independent ones.
+ */
+export declare class CoreWasmRuntime {
+    readonly instance: WebAssembly.Instance;
+    private transformBackend;
+    private animBackend;
+    private hitBackend;
+    private particleBackendInstance;
+    constructor(instance: WebAssembly.Instance);
+    /**
+     * Backends are constructed lazily and memoised: each one's constructor calls
+     * into the instance to size its store and build typed-array views, so building
+     * all four up front would pay for accelerators the Scene never enables.
+     */
+    transform(): WasmTransformBackend;
+    anim(): AnimBackend;
+    hit(): HitTestBackend;
+    particle(): ParticleBackend;
+}
+/**
+ * Instantiate a runtime from an already-compiled module. Separated from
+ * {@link loadCoreWasmModule} so several Scenes can share one compile while each
+ * keeps its own mutable stores.
+ */
+export declare function createCoreWasmRuntime(module: WebAssembly.Module): CoreWasmRuntime | null;
+/**
+ * Compile (or reuse) and instantiate in one step. Returns `null` on any failure
+ * so the caller keeps the JS path.
+ */
+export declare function loadCoreWasmRuntime(source: CoreModuleSource): Promise<CoreWasmRuntime | null>;
+/**
+ * Drop the global compiled-module cache. For tests that need to observe a fresh
+ * compile, and for apps that want to release the memory after teardown.
+ */
+export declare function clearCoreWasmModuleCache(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.16.2",
+  "version": "1.17.0",
   "publishConfig": {
     "access": "public"
   },