@vectojs/core 1.22.0 → 1.23.0

package/dist/tree/ComputeParticleEntity.d.ts

@@ -143,8 +143,12 @@ export declare class ComputeParticleEntity extends Entity {
      * The backend holds one resident SoA store, so a Scene with multiple particle
      * entities reuses it sequentially — origin is therefore re-gathered each call
      * (not upload-once), a couple of extra f32 reads per particle.
+     *
+     * Returns `false` if the kernel declined the call and {@link updateCPU} ran
+     * instead, so the Scene can report which path actually simulated this frame
+     * rather than assuming an installed backend did the work.
      */
-    stepWithBackend(backend: ParticleBackend, dt: number, mouseX: number, mouseY: number, width: number, height: number): void;
+    stepWithBackend(backend: ParticleBackend, dt: number, mouseX: number, mouseY: number, width: number, height: number): boolean;
     destroy(): void;
     /**
      * Frees all GPU resources allocated for WebGPU simulation.

package/dist/tree/Scene.d.ts

@@ -208,6 +208,60 @@ export interface SceneOptions {
 }
 /** Frame-rate the loop is capped to when the OS requests reduced motion. */
 export declare const REDUCED_MOTION_FPS = 30;
+/**
+ * Why an accelerator did or did not run on the most recent frame.
+ *
+ * `'active'` is the only value that means the accelerator ran. Everything else
+ * is a distinct decline, kept separate because they call for different actions:
+ * `'not-installed'` means enable it, `'below-gate'` means the workload is too
+ * small to be worth it (working as designed), and `'rejected'` means the kernel
+ * refused its arguments — a fault worth reporting, not a tuning outcome.
+ */
+export type AcceleratorReason = 
+/** Ran on this frame. */
+'active'
+/** No backend installed; the JS path is the permanent fallback. */
+ | 'not-installed'
+/** Installed, but the per-frame gate chose JS (workload below threshold). */
+ | 'below-gate'
+/** Installed and gated in, but the kernel rejected the call and wrote nothing. */
+ | 'rejected'
+/** Not applicable to this pass (e.g. a non-main renderer, or nothing to do). */
+ | 'not-applicable';
+/**
+ * One accelerator's per-frame status, read from {@link Scene.accelerators}.
+ *
+ * The pair exists because `available` and `activeThisFrame` genuinely differ:
+ * before this shape, `transformBackend`/`animBackend` reported only that a
+ * backend was *installed*, which invites concluding an accelerator is doing work
+ * when its gate never opens. Read `activeThisFrame` for what actually happened
+ * and `reason` for why.
+ */
+export interface AcceleratorStatus {
+    /** A backend is installed and could run, gate permitting. */
+    available: boolean;
+    /** It ran on the most recent frame. */
+    activeThisFrame: boolean;
+    /** Why it did or did not run. */
+    reason: AcceleratorReason;
+    /** Which implementation actually did the work on the most recent frame. */
+    path: string;
+}
+/**
+ * Per-frame status of every invisible accelerator, read from
+ * {@link Scene.accelerators}. Each is independent: a scene can compose
+ * transforms in WASM while ticking drivers in JS.
+ */
+export interface AcceleratorReport {
+    /** World-matrix composition (`compose_simd`). */
+    transform: AcceleratorStatus;
+    /** Batched property drivers (`spring_step`/`tween_step`). */
+    animation: AcceleratorStatus;
+    /** Hit-test broad phase (`hit_build`/`hit_query`) and its gather source. */
+    hitTest: AcceleratorStatus;
+    /** Particle simulation — WebGPU compute, the WASM CPU kernel, or JS. */
+    particle: AcceleratorStatus;
+}
 /**
  * Live render-loop telemetry, read from {@link Scene.frameStats}. See that
  * getter for how each field is measured.
@@ -574,6 +628,41 @@ export declare class Scene {
     private _wasmAabbsFresh;
     /** Did the last hit-grid build use the fused (WASM-store) gather? */
     get hitGatherPath(): 'fused' | 'js';
+    /**
+     * Why the transform accelerator did or did not run on the most recent frame.
+     * Written by the render walk and `_syncWasmStore`.
+     */
+    private _transformReason;
+    /** Why the batched-driver accelerator did or did not run. */
+    private _animReason;
+    /**
+     * Why the hit-test accelerator did or did not serve the last pointer query.
+     * The grid is built lazily on demand, not every frame, so this describes the
+     * most recent BUILD. Starts at `'not-installed'` because that is the truth
+     * before a backend exists; `_ensureHitGrid` moves it to `'not-applicable'`
+     * once one is installed but nothing has queried yet.
+     */
+    private _hitReason;
+    /** Why the particle accelerator did or did not run. */
+    private _particleReason;
+    /** Which particle implementation actually simulated the most recent frame. */
+    private _particlePath;
+    /**
+     * Per-frame status of every invisible accelerator: whether each is installed,
+     * whether it actually ran on the most recent frame, and why.
+     *
+     * This exists because the older per-accelerator getters
+     * ({@link transformBackend}, {@link animBackend}, {@link hitTestBackend},
+     * {@link particleBackend}) report only that a backend is INSTALLED. Reading
+     * `'wasm'` from one of those and concluding the accelerator is doing work is
+     * wrong whenever a gate never opens, a kernel rejects its arguments, or a
+     * faster backend takes the pass instead. Read {@link AcceleratorStatus.reason}
+     * for which of those happened.
+     *
+     * Reflects the most recent main-renderer frame; a secondary renderer (SVG
+     * export, offscreen snapshot) does not overwrite it.
+     */
+    get accelerators(): AcceleratorReport;
     /** Which backend answers `findEntityAt` for the main tree. */
     get hitTestBackend(): 'js' | 'wasm';
     /** Install (or clear) a WASM hit-test backend directly. Prefer

package/dist/wasm/anim-backend.d.ts

@@ -56,10 +56,27 @@ export declare class AnimBackend {
      * writing first and sizing after would write into a stale buffer.
      */
     ensure(springCount: number, tweenCount: number): void;
-    /** Advance `count` springs (from index 0) by `dtMs` milliseconds, in place. */
-    stepSprings(dtMs: number, count: number): void;
-    /** Advance `count` tweens (from index 0) by `dtMs` milliseconds, writing `val`. */
-    stepTweens(dtMs: number, count: number): void;
+    /**
+     * Advance `count` springs (from index 0) by `dtMs` milliseconds, in place.
+     * Returns `true` when the kernel ran. `false` means it rejected the call
+     * (count beyond the capacity {@link ensure} allocated, or no `anim_init` yet)
+     * and wrote nothing, so the caller must tick those drivers in JS instead of
+     * scattering back a pack the kernel never touched. See {@link lastStatus}.
+     */
+    stepSprings(dtMs: number, count: number): boolean;
+    /**
+     * Advance `count` tweens (from index 0) by `dtMs` milliseconds, writing `val`.
+     * Returns `true` when the kernel ran; `false` means it rejected the call and
+     * wrote nothing (see {@link stepSprings}). `elapsed` is kernel-side state, so
+     * a rejected tween pack must not be read back — it is unadvanced, not
+     * partially advanced.
+     */
+    stepTweens(dtMs: number, count: number): boolean;
+    /**
+     * Status of the most recent kernel call — `WASM_STATUS.OK` unless the kernel
+     * declined it. Mirrors {@link TransformBackend.lastStatus}.
+     */
+    lastStatus: number;
     private refreshViews;
 }
 /**

package/dist/wasm/backend.d.ts

@@ -84,8 +84,11 @@ export declare class WasmTransformBackend {
      */
     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;
+     *  the resident views. Call when the tree structure changes, not per frame.
+     *  Returns `false` if the crate rejected the run count, in which case the
+     *  PREVIOUS topology is still published and any kernel run against it would
+     *  compose the wrong tree — the caller must not proceed. */
+    uploadRuns(store: TransformStore): boolean;
     /**
      * 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.
@@ -125,8 +128,10 @@ export declare class WasmTransformBackend {
     computeAabbs(store: TransformStore): void;
     /** Run the AABB pass only, over `count` entities already resident in wasm
      *  memory (bounds written via {@link boundsView}, world matrices already
-     *  composed). No upload/readback — the per-frame resident path. */
-    runAabbs(count: number): void;
+     *  composed). No upload/readback — the per-frame resident path. Returns
+     *  `false` if the kernel rejected `count` (beyond capacity, or uninitialized),
+     *  in which case {@link aabbView} still holds the previous frame's bounds. */
+    runAabbs(count: number): boolean;
     /** Resident wasm local-bounds input views (`bx,by,bw,bh`) for the AABB pass. */
     boundsView(): {
         bx: Float64Array;

package/dist/wasm/particle-backend.d.ts

@@ -71,8 +71,19 @@ export declare class ParticleBackend {
      * Advance `count` particles one step in place. Returns `true` when at least
      * one live particle is still moving or off-origin beyond epsilon (the fused
      * `hasPendingAnimations` flag), so the caller need not re-scan the buffer.
+     *
+     * Returns `null` when the kernel REJECTED the call — `count` beyond the
+     * capacity {@link ensure} allocated, or no `particle_init` yet. Nothing was
+     * written, so the caller must NOT {@link scatter} (that would write the
+     * gathered pre-step values back and freeze the simulation) and should fall
+     * back to the JS `updateCPU` path for this frame. See {@link lastStatus}.
      */
-    step(count: number, p: ParticleStepParams): boolean;
+    step(count: number, p: ParticleStepParams): boolean | null;
+    /**
+     * Status of the most recent {@link step} — `WASM_STATUS.OK` unless the kernel
+     * declined it. Mirrors {@link TransformBackend.lastStatus}.
+     */
+    lastStatus: number;
     /** Transpose the AoS stride-8 buffer into the SoA views (position/velocity/
      *  life every frame; origin upload-once when `withOrigin`). */
     gather(data: Float32Array, count: number, withOrigin: boolean): void;

package/package.json

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