@vectojs/core 1.14.0 → 1.16.0

package/dist/tree/Scene.d.ts

@@ -12,6 +12,10 @@ export interface IWebGPUParticleSystemManager {
 }
 import { Entity } from './Entity';
 import { IRenderer } from '../renderer/IRenderer';
+import { type WasmModuleSource, type WasmTransformBackend } from '../wasm/backend';
+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';
 /**
  * Options for {@link Scene}.
  */
@@ -110,6 +114,15 @@ export interface SceneOptions {
      * height (`undefined` → resolved to `Scene.height` at sync time).
      */
     contentProjectionMargin?: number;
+    /**
+     * Reading direction used to order the accessibility/automation shadow tree so
+     * keyboard **tab order** and screen-reader traversal follow the *visual*
+     * reading order (top-to-bottom, then inline) rather than scene-graph
+     * insertion order — two entities added in any order but drawn left/right of
+     * each other should Tab left→right (`'ltr'`, default) or right→left
+     * (`'rtl'`). Also settable later via {@link Scene.readingDirection}.
+     */
+    readingDirection?: 'ltr' | 'rtl';
 }
 /** Frame-rate the loop is capped to when the OS requests reduced motion. */
 export declare const REDUCED_MOTION_FPS = 30;
@@ -162,12 +175,23 @@ export interface A11yTreeNode {
 export declare class Scene {
     private static webglCreator;
     private static webgpuManagerClass;
+    /** Upper bound (ms) on a single frame's `dt`. Caps the giant elapsed gap a
+     *  backgrounded/refocused tab produces so physics advances at most one slow
+     *  frame instead of the whole idle duration (~100ms ≈ 6 frames at 60fps). */
+    private static readonly MAX_FRAME_DT;
     static registerWebGLPointRendererCreator(creator: WebGLPointRendererCreator): void;
     static registerWebGPUParticleSystemManager(managerClass: any): void;
     private root;
     overlayRoot: Entity;
     private renderer;
     private isRunning;
+    /** Whether the canvas is at least partially in the viewport. When it scrolls
+     *  fully off-screen the rAF loop pauses (stops rescheduling) instead of
+     *  burning frames on a scene nobody can see; an IntersectionObserver resumes
+     *  it on re-entry. Defaults true (and stays true where IntersectionObserver
+     *  is unavailable, e.g. SSR/jsdom, so behavior is unchanged there). */
+    private _canvasOnScreen;
+    private _canvasObserver;
     private lastTime;
     canvas: HTMLCanvasElement;
     /**
@@ -201,10 +225,34 @@ export declare class Scene {
     maxFPS: number;
     /** Whether the OS prefers-reduced-motion setting auto-caps the loop. */
     respectReducedMotion: boolean;
+    /**
+     * Reading direction for accessibility tab/traversal order (`'ltr'` default,
+     * `'rtl'`). Controls the inline sort within a visual row in
+     * {@link enforceA11yDomOrder}. Set at runtime to re-flow tab order on the
+     * next sync (also trips a reorder).
+     */
+    get readingDirection(): 'ltr' | 'rtl';
+    set readingDirection(dir: 'ltr' | 'rtl');
+    private _readingDirection;
     /** Cached media-query list; `.matches` is read live each frame. */
     private reducedMotionQuery;
+    /** Cached `(forced-colors: active)` query (Windows High Contrast etc.). A
+     *  canvas gets NO automatic forced-colors treatment from the browser (it's
+     *  opaque pixels), so components must read {@link forcedColors} and repaint
+     *  with system colors themselves; a change listener repaints idle scenes. */
+    private forcedColorsQuery;
+    private forcedColorsChangeHandler;
     /** True when the OS asks for reduced motion and we respect it. Read by the animation drivers. */
     get prefersReducedMotion(): boolean;
+    /**
+     * True when the OS is in a forced-colors mode (Windows High Contrast, and the
+     * `forced-colors: active` media feature generally). Canvas pixels are exempt
+     * from the browser's forced-colors remapping, so accessible components should
+     * read this and draw with CSS system colors (`CanvasText`, `Canvas`,
+     * `Highlight`, …) instead of their themed palette. Re-rendered automatically
+     * when the setting toggles.
+     */
+    get forcedColors(): boolean;
     /**
      * Throttle interval (ms) for the a11y/automation shadow sync. `0` = every
      * frame. See {@link SceneOptions.a11ySyncInterval}.
@@ -241,7 +289,32 @@ export declare class Scene {
     private frameHadAnimation;
     private frameHadInteractive;
     private resizeHandler;
+    /** Active `(resolution: Ndppx)` media query watching for a runtime DPR change
+     *  (window moved between monitors, browser zoom) so the canvas backing store
+     *  can be re-scaled — otherwise it stays rasterized at the old DPR and blurs.
+     *  A resolution media query only fires when leaving its exact value, so the
+     *  handler re-arms a fresh query for the new DPR each time. */
+    private dprMediaQuery;
+    /** For embedded (`disableWindowResize`) scenes: observes the canvas element so
+     *  a CSS/layout-driven size change re-runs `resize()`. A window `resize`
+     *  listener never fires for these (the window isn't what changed), so without
+     *  this an embedded canvas stayed at its initial size forever. */
+    private canvasResizeObserver;
+    private dprChangeHandler;
     private focusedA11yElement;
+    /** Last geometry `syncOverlayGeometry` wrote, so an unchanged frame can skip the
+     *  style writes entirely. Reset to `null` to force the next sync (a new overlay
+     *  layer was created and has never been positioned). */
+    private _overlayGeometry;
+    /** Shadow elements the pointer is currently inside. Lets a removal that happens
+     *  mid-hover synthesize the `pointerleave` the browser never sends for a
+     *  detached element, so the entity doesn't keep its hover state. */
+    private readonly hoveredA11yElements;
+    /** Persistent tabindex=-1 element in a11yRoot. When the focused a11y mirror is
+     *  pruned (virtualization/streaming/removal) while it holds focus, we move
+     *  focus here instead of letting the browser drop it to <body> — keeping the
+     *  screen-reader virtual cursor inside the scene's a11y region. */
+    private focusSentinel;
     private caretBlinkTimer;
     a11yNeedsReorder: boolean;
     private portalRoot;
@@ -252,6 +325,223 @@ export declare class Scene {
     private activePortalsPrevFrame;
     private portalEntities;
     private renderOrderCounter;
+    /**
+     * Monotonic render-frame counter, bumped once per authoritative `render()`
+     * pass. Entities stamp their per-frame world-matrix cache with this value and
+     * {@link Entity.getWorldTransform} trusts that cache only while it still
+     * matches, so a query outside the frame that produced it transparently falls
+     * back to the ancestor walk. Public for the same reason `Entity._getTrig`/
+     * `_setWorldCache` are: it is a cross-class render-internal contract.
+     */
+    currentFrame: number;
+    private _wasm;
+    private _transformBackend;
+    private _treeStore;
+    private _slotEntity;
+    private _wasmInputs;
+    private _wasmWorld;
+    private _structureVersion;
+    private _storeStructureVersion;
+    private _computeEntities;
+    private _computeEntitiesVersion;
+    /** Invalidate the resident WASM store layout; the next wasm-mode frame rebuilds
+     *  it. Called by `Entity.add`/`remove` (topology changes only). */
+    markStructureChanged(): void;
+    /** The tree's ComputeParticleEntity instances, cached per structure version so
+     *  a compute-free scene doesn't re-walk the whole tree every frame. */
+    private _computeEntitiesFor;
+    /** Which backend composes world matrices for the main render walk. */
+    get transformBackend(): 'js' | 'wasm';
+    /**
+     * Install (or clear) a WASM transform backend. Passing a backend switches the
+     * main render walk onto it; passing `null` reverts to the JS path. Synchronous
+     * and safe to call between frames — the next `render()` picks it up. Prefer
+     * {@link enableWasmTransforms} for the normal async hot-swap.
+     */
+    setTransformBackend(backend: WasmTransformBackend | null): void;
+    /**
+     * Asynchronously instantiate the WASM transform core and, on success, hot-swap
+     * the render walk onto it. Accepts whatever is convenient at the call site:
+     *
+     * ```ts
+     * // The common case — a bundler-emitted, co-located asset URL:
+     * await scene.enableWasmTransforms(new URL('./vectojs_core.wasm', import.meta.url));
+     * // …or a path string, a Response, or raw bytes you already have:
+     * await scene.enableWasmTransforms('/assets/vectojs_core.wasm');
+     * await scene.enableWasmTransforms(await fetch(url));
+     * await scene.enableWasmTransforms(myUint8Array);
+     * ```
+     *
+     * A URL/Response streams (compiles while it downloads, with a buffered
+     * fallback for a wrong MIME type); raw bytes instantiate directly. The Scene
+     * keeps rendering on the JS path until this resolves, and stays on JS if
+     * instantiation fails (CSP `wasm-unsafe-eval`, unsupported SIMD, corrupt or
+     * missing bytes, a 404) — failure is the default state, not an error path.
+     * Resolves `true` if WASM is now active, `false` if the JS path remains.
+     */
+    enableWasmTransforms(source: WasmModuleSource): Promise<boolean>;
+    private _hitWasm;
+    private _hitGridFrame;
+    private _hitGridOk;
+    private _hitSlotEntity;
+    private _hitBoundless;
+    /** Which backend answers `findEntityAt` for the main tree. */
+    get hitTestBackend(): 'js' | 'wasm';
+    /** Install (or clear) a WASM hit-test backend directly. Prefer
+     *  {@link enableWasmHitTest} for the normal async hot-swap. */
+    setHitTestBackend(backend: HitTestBackend | null): void;
+    /**
+     * Asynchronously instantiate the WASM hit-test core and, on success, hot-swap
+     * `findEntityAt` onto it. Accepts the same source shapes as
+     * {@link enableWasmTransforms} (URL, path string, Response, or raw bytes).
+     * Stays on the JS walk if instantiation fails — failure is the default
+     * state, not an error path. Resolves `true` if WASM is now active.
+     */
+    enableWasmHitTest(source: HitModuleSource): Promise<boolean>;
+    /**
+     * Refresh the hit-test grid for the CURRENT tree state if it is stale (a
+     * structural or transform change may have happened since the last build —
+     * there is no cheap "nothing moved" shortcut for a spatial index the way
+     * there is for the transform store's topology-only run table, since ANY
+     * entity moving invalidates its AABB, not just add/remove/reparent; the
+     * measured build cost is cheap enough to redo per call). Returns `false`
+     * (grid untrustworthy — caller must use the JS walk) when there is no
+     * backend or the build overflowed its item budget.
+     */
+    private _ensureHitGrid;
+    /**
+     * `findEntityAt`'s WASM-accelerated path for the main tree. Scans only the
+     * queried cell's candidates (confirming each against its own AABB and precise
+     * `isPointInside`) merged against the (typically empty or tiny) list of
+     * entities with no `getBounds()`, taking whichever confirmed match has the
+     * higher pre-order index — see hit-store.ts for why that is exactly
+     * equivalent to findHitRecursively's topmost-hit priority. Always
+     * conclusive: returns the correct entity or `null`, never "inconclusive".
+     */
+    private _findEntityAtWasm;
+    private _animWasm;
+    private _activeDriverEntities;
+    private _springEntities;
+    private _springProps;
+    private _springDrivers;
+    private _tweenEntities;
+    private _tweenProps;
+    private _tweenDrivers;
+    /**
+     * Minimum number of batchable (spring, or named-easing tween) active drivers
+     * before a frame engages the WASM batch path at all; below it, every driver
+     * ticks on the normal JS per-entity path, unmodified.
+     *
+     * Re-measured on the INTEGRATED path (benchmarks/anim-wasm-scene, real
+     * Chrome 150 / Firefox 153, 2026-07-24 — correctness verified 0 mismatches
+     * across all three kinds before any of these numbers were trusted): the
+     * isolated kernel spike's "<100 drivers, wins everywhere" verdict did NOT
+     * survive integration, and neither did the first integrated pass's single
+     * gate-count verdict once broken out by driver kind. On Chrome, spring and
+     * mixed drivers are a real ~1.4–2.3× win from n=128 up through the tested
+     * ceiling of 16384, but pure-tween drivers are a LOSS at n=128 (0.71×,
+     * i.e. ~40% slower than the JS path) and only turn net-positive around
+     * n≈256 (1.52×). A single scalar gate can't be tight for spring/mixed
+     * without occasionally opening early on a tween-heavy scene and making it
+     * slower — 256 is chosen to keep the gate net-positive across all three
+     * kinds rather than optimal for any one of them; a kind-aware gate (see
+     * `_tickBatchedDrivers`'s per-kind arrays, which already separate spring
+     * from tween) would recover the 128–255 spring/mixed win without the
+     * tween regression, but that's a larger change than this measurement pass
+     * covers. On Firefox it is a net loss at every driver count measured, up
+     * to 16384 — not an allocation artifact (confirmed after removing all
+     * per-frame allocation from the gather/scatter path); SpiderMonkey's
+     * wasm-boundary/property-dispatch cost for this shape of call appears to
+     * structurally exceed the saving, at least at the scales tested here.
+     *
+     * 256 is set as a Chrome-oriented default so an app that opts in (this
+     * path is never engaged without an explicit {@link enableWasmAnimBatching}
+     * call) sees the gate open only where it reliably helps on Chromium,
+     * regardless of whether the scene's active drivers are spring, tween, or
+     * a mix of both. Unlike G1 (safe to default on everywhere) and G3 (opt-in,
+     * but a reliable win once its own gate condition holds), G2 has no
+     * threshold that is safe on every engine — raise or lower this per your
+     * own target browser mix and driver-kind distribution, or leave WASM
+     * animation batching disabled entirely on a Firefox-heavy audience.
+     */
+    animDriverGateCount: 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'`. */
+    get animBackend(): 'js' | 'wasm';
+    /** Install (or clear) a WASM batched-animation backend directly. Prefer
+     *  {@link enableWasmAnimBatching} for the normal async hot-swap. */
+    setAnimBackend(backend: AnimBackend | null): void;
+    /**
+     * Asynchronously instantiate the WASM batched-animation core and, on
+     * success, make it available to the per-frame gate (see
+     * {@link animDriverGateCount}). Accepts the same source shapes as
+     * {@link enableWasmTransforms}. Stays on the JS tick loop if instantiation
+     * fails — failure is the default state, not an error path. Resolves `true`
+     * if WASM is now available (not necessarily active every frame).
+     */
+    enableWasmAnimBatching(source: AnimModuleSource): Promise<boolean>;
+    private _particleWasm;
+    /** Which backend runs the CPU particle simulation. Reflects only whether a
+     *  backend is installed (the WebGPU compute path, when active, is used first
+     *  regardless). */
+    get particleSimBackend(): 'js' | 'wasm';
+    /** Install (or clear) a WASM particle backend directly. Prefer
+     *  {@link enableWasmParticles} for the normal async hot-swap. */
+    setParticleBackend(backend: ParticleBackend | null): void;
+    /**
+     * Asynchronously instantiate the WASM particle core and, on success, use it
+     * for the CPU particle fallback. Accepts the same source shapes as
+     * {@link enableWasmTransforms}. Stays on the JS `updateCPU` path if
+     * instantiation fails — failure is the default state, not an error path.
+     * Resolves `true` if WASM is now active.
+     */
+    enableWasmParticles(source: ParticleModuleSource): Promise<boolean>;
+    /** Internal: called by `Entity._spawnDriver` when a new property driver
+     *  starts. See {@link _activeDriverEntities}. */
+    _registerActiveDriverEntity(entity: Entity): void;
+    /**
+     * Drop `entity` and its whole subtree from the batched-driver candidate set.
+     * Called by {@link remove}/{@link hideOverlay} on detach: without this a
+     * removed-but-still-animating entity stays pinned in the Set (a leak) and its
+     * drivers keep ticking every frame even though it is off-tree. If it is later
+     * re-added, {@link registerActiveDriverSubtree} re-registers any node that
+     * still has live drivers, so the motion resumes.
+     */
+    private unregisterActiveDriverSubtree;
+    /**
+     * Re-register every node in `entity`'s subtree that still has live property
+     * drivers. Called by {@link add}/{@link showOverlay} so re-attaching a subtree
+     * that was removed mid-animation resumes its batched drivers (they were
+     * dropped from the candidate set on removal, but the driver state still lives
+     * on each entity).
+     */
+    private registerActiveDriverSubtree;
+    /**
+     * Advance every registered entity's active drivers for this frame, batching
+     * whichever are batchable (`SpringDriver`; `TweenDriver` with a named
+     * easing) through one WASM call each when the driver-count gate is open, and
+     * ticking the rest (a `TweenDriver` using a custom `EasingFn`) directly in
+     * JS regardless of the gate. A "claimed" entity must have ALL its drivers
+     * advanced here so it can be safely stamped `_driversTickedFrame` — leaving
+     * one unclaimed would silently stall it, since `tickDrivers()` skips the
+     * whole entity once stamped.
+     *
+     * Must run before ANY entity's `update()`/`tickDrivers()` this frame (see
+     * the call site in {@link render}) — the same ordering constraint G1 Stage 4
+     * discovered: a value this pass writes must be final before anything reads
+     * it, including the JS-mode interleaved walk and the WASM-mode transform
+     * pre-pass.
+     */
+    private _tickBatchedDrivers;
+    /**
+     * Compose the whole main tree's world matrices through the resident WASM store
+     * and return the world-matrix views for the render walk to read. Rebuilds the
+     * store layout (slots + runs) only when the tree structure changed since the
+     * last rebuild; otherwise it just gathers current transforms into the resident
+     * input view and runs the kernel. Returns `null` if there is no backend.
+     */
+    private _syncWasmStore;
     /**
      * Authoritative paint order for semantic nodes discovered during the main
      * render. A node may not have a DOM projection until the following a11y
@@ -261,6 +551,8 @@ export declare class Scene {
     private a11yRenderOrders;
     private pointRenderer;
     private glCanvas;
+    private glContextLostHandler;
+    private glContextRestoredHandler;
     private debugA11y;
     width: number;
     height: number;
@@ -285,6 +577,9 @@ export declare class Scene {
     private mouseY;
     private pointerMoveListener;
     private pointerLeaveListener;
+    /** Element the pointer listeners are bound to (parent container if present,
+     *  else the canvas). Stored so `destroy()` detaches from the same element. */
+    private pointerEventTarget;
     private hasWarnedZeroSize;
     private fontLoadHandler;
     /** Toggle development-mode runtime warnings globally. */
@@ -296,8 +591,46 @@ export declare class Scene {
     /** @internal Periodic dev checks — called once per frame in dev mode. */
     private _devRunChecks;
     constructor(canvas: HTMLCanvasElement, options?: SceneOptions);
+    /**
+     * Arm a `(resolution: Ndppx)` media query for the current devicePixelRatio and
+     * re-apply the canvas scale when it changes. Such a query only fires when the
+     * DPR leaves its exact value, so on each change the old query is detached and
+     * a fresh one is armed for the new DPR. Re-runs `resize(width, height)` (which
+     * re-scales the backing store via the renderer) so text/vectors stay crisp
+     * after a monitor move or zoom. No-op without `matchMedia`.
+     */
+    private watchDevicePixelRatio;
+    /**
+     * Recover the WebGL point layer from a GPU context loss (driver TDR reset,
+     * tab backgrounded on mobile, GPU switch). Two things are required:
+     *
+     *  1. The `webglcontextlost` handler MUST call `preventDefault()`, or the
+     *     browser never fires `webglcontextrestored` and the layer is blank
+     *     forever. While lost, the old renderer's GL calls are silently ignored,
+     *     so we drop it and the render loop simply skips the point layer.
+     *  2. On `webglcontextrestored`, all GL objects (programs, buffers, textures)
+     *     are gone, so we rebuild the renderer from scratch via `Scene.webglCreator`
+     *     on the same canvas, restore DPR/size, and repaint.
+     */
+    private setupGLContextRecovery;
     private endContentSelectionDrag;
     private releaseContentSelectionForRebuild;
+    /**
+     * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
+     * text selection the user made inside it. A streaming message replaces its
+     * projection children on every appended chunk; without this, a selection in
+     * the UNCHANGED prefix is wiped on each frame ("can't select text in a
+     * message still receiving tokens"). We snapshot the selection's anchor/focus
+     * as linear character offsets within `el` before the rebuild and re-resolve
+     * them against the new DOM after, clamped to the new text length.
+     *
+     * Only fires when `el` owns the current selection and there is no active drag
+     * (mid-drag the browser is authoritative). The virtualization case — where
+     * `el` itself is removed from the DOM — is out of scope here (the node is
+     * genuinely freed; the browser clears the selection and there is nothing to
+     * restore against).
+     */
+    private preserveContentSelectionAcrossRebuild;
     /**
      * Expose the underlying {@link IRenderer} for advanced direct-draw operations.
      *
@@ -319,6 +652,14 @@ export declare class Scene {
     add(entity: Entity): this;
     private clearContentGridState;
     private removeA11yRecursively;
+    /**
+     * If `el` is about to be removed from the DOM while it holds browser focus,
+     * move focus to the a11y focus sentinel first. Removing the active element
+     * otherwise drops focus to `<body>`, which pulls a screen reader out of the
+     * scene's a11y region and back to the top of the page — the classic
+     * "lost my place on scroll/stream" bug for virtualized/recycled controls.
+     */
+    private preserveFocusOnRemoval;
     /**
      * Remove a top-level entity from the scene graph and clean up its
      * accessibility shadow elements recursively.
@@ -359,6 +700,14 @@ export declare class Scene {
     start(): void;
     /** Schedule the next frame, or no-op where `requestAnimationFrame` is absent (SSR). */
     private scheduleFrame;
+    /**
+     * Observe whether the canvas is on-screen so the rAF loop can pause when it
+     * scrolls fully out of view (a dashboard tab, a chart below the fold) and
+     * resume when it returns — instead of running the full update/render every
+     * frame for a scene nobody can see. No-op (stays "on screen") where
+     * `IntersectionObserver` is unavailable, so SSR/jsdom behavior is unchanged.
+     */
+    private watchCanvasVisibility;
     /**
      * Halt the render loop after the current frame completes.
      *
@@ -434,6 +783,16 @@ export declare class Scene {
     private getContentMetricScaleX;
     private scheduleContentGridCalibration;
     private enforceA11yDomOrder;
+    /**
+     * Reorder `normalElements` (in place) into visual reading order using the
+     * world positions `syncA11y` already wrote to each element's inline style
+     * (`top`/`left`/`height`). Elements are grouped into rows top-to-bottom (an
+     * element belongs to the current row while its top is above the row's
+     * running bottom edge), then sorted within a row by `left` — ascending for
+     * `'ltr'`, descending for `'rtl'`. The sort is stable, so entities at the
+     * same position keep their scene-graph (collection) order as a tiebreak.
+     */
+    private sortNormalElementsVisually;
     /** Keep DOM/WebGL overlay layers aligned with the canvas's CSS box. */
     private syncOverlayGeometry;
     getA11yTree(): A11yTreeNode[];
@@ -462,6 +821,13 @@ export declare class Scene {
      * Manually resize the Scene's viewport.
      */
     resize(width: number, height: number): void;
+    /** Effective device pixel ratio, matching CanvasRenderer: real DPR clamped to
+     *  `maxDPR` when set. */
+    private effectiveDPR;
+    /** Size the WebGPU particle canvas: backing store at logical × DPR, CSS box at
+     *  the logical size. Sizing the backing store in logical px (the old
+     *  behavior) left it rasterized at 1× and CSS-stretched — blurry on HiDPI. */
+    private sizeGpuCanvas;
     /**
      * Gets the accessibility DOM element projected for the given entity ID.
      */
@@ -483,4 +849,18 @@ export declare class Scene {
     private recreateWebGPUDeviceWithRetry;
     private renderCPUParticles;
     private findHitRecursively;
+    /** Whether `node` opts out of being a pointer hit target: a disabled control
+     *  or an explicit `pointerEvents: 'none'` in its a11y attributes. Its children
+     *  are still walked (a transparent container can hold hittable descendants). */
+    private isPointerTransparent;
+    /**
+     * Whether a confirmed geometric hit on `node` at world `(x, y)` is a REAL hit,
+     * applying the same visibility/input gating as {@link findHitRecursively} but
+     * from a flat candidate (the WASM grid has no recursion clip-stack): the node
+     * and all ancestors are visible (`opacity > 0`), the point lies inside every
+     * `clipChildren` ancestor's world box, and the node isn't pointer-transparent
+     * (disabled / `pointerEvents: 'none'`). Keeps the WASM and JS hit paths in
+     * lockstep so they return the same entity.
+     */
+    private isHitEligible;
 }

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

@@ -0,0 +1,86 @@
+/**
+ * WASM batched-animation backend: advances every currently-active `SpringDriver`/
+ * `TweenDriver` in one call each (`spring_step`/`tween_step`), instead of the JS
+ * per-driver `driver.tick()` loop. This is an invisible accelerator — the JS tick
+ * loop ({@link Entity.tickDrivers}) is the permanent fallback, so a caller that
+ * cannot instantiate WASM, or whose active-driver count never crosses the gate
+ * (see `Scene._tickBatchedDrivers`), simply keeps using it.
+ *
+ * The kernel (`crates/vectojs-core-rs/src/anim.rs`) is bit-identical to
+ * `SpringPhysics.update` for springs; tweens match to ~1e-9 (not bit-exact — a
+ * `Math.pow`-vs-`powi` ULP difference recorded as a spike finding), which is why
+ * a WASM-batched tween needs a `retarget`-style resync, not raw byte reuse.
+ *
+ * Unlike the transform/hit-test stores, this backend holds no cross-frame
+ * residency: every qualifying frame re-gathers ALL currently-active batchable
+ * drivers into a fresh dense pack (see {@link ensure} + the spring/tween input
+ * views), runs the kernel once, and scatters results straight back out. This
+ * keeps the design robust to drivers joining/leaving between frames and to the
+ * gate itself flipping the JS/WASM path frame-to-frame — there is no persistent
+ * wasm-side state to invalidate.
+ */
+export interface SpringView {
+    val: Float64Array;
+    target: Float64Array;
+    vel: Float64Array;
+    stiff: Float64Array;
+    damp: Float64Array;
+    mass: Float64Array;
+}
+export interface TweenView {
+    from: Float64Array;
+    to: Float64Array;
+    elapsed: Float64Array;
+    dur: Float64Array;
+    delay: Float64Array;
+    ease: Float64Array;
+    val: Float64Array;
+}
+export declare class AnimBackend {
+    private readonly ex;
+    private springCap;
+    private tweenCap;
+    private sv;
+    private tv;
+    constructor(instance: WebAssembly.Instance);
+    /** The resident spring SoA input/output views, valid until the next capacity
+     *  growth. Write gathered driver state here before calling {@link stepSprings}. */
+    springView(): SpringView;
+    /** The resident tween SoA input/output views, valid until the next capacity
+     *  growth. Write gathered driver state here before calling {@link stepTweens}. */
+    tweenView(): TweenView;
+    /**
+     * Size (and grow, if needed) capacity for `springCount` springs and
+     * `tweenCount` tweens. Call this BEFORE writing into {@link springView}/
+     * {@link tweenView} — a capacity growth detaches the previous views, so
+     * 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;
+    private refreshViews;
+}
+/**
+ * Instantiate synchronously (Node/tests, or a worker). Rejected on the browser
+ * main thread for modules >4 KB — use {@link instantiateAsync} there. Returns
+ * `null` if compilation/instantiation throws, so callers fall back to JS.
+ */
+export declare function instantiateSync(bytes: BufferSource): AnimBackend | null;
+/**
+ * Instantiate asynchronously (browser main thread). Returns `null` on any
+ * failure — CSP `wasm-unsafe-eval`, unsupported, corrupt/missing bytes — so the
+ * caller keeps using the JS path.
+ */
+export declare function instantiateAsync(bytes: BufferSource): Promise<AnimBackend | null>;
+/** Anything the anim core can be loaded from, matching the transform/hit-test
+ *  cores' loading ergonomics. */
+export type AnimModuleSource = BufferSource | string | URL | Response | Promise<Response>;
+/**
+ * Instantiate from a URL/Response using streaming compilation when the
+ * platform supports it, falling back to fetch → arrayBuffer → instantiate when
+ * unavailable or the response's MIME type is rejected. Returns `null` on any
+ * failure so the caller keeps the JS path.
+ */
+export declare function instantiateStreaming(source: string | URL | Response | Promise<Response>): Promise<AnimBackend | null>;

package/dist/wasm/asset.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolved URL of the prebuilt WebAssembly core, co-located with this module in
+ * the published package (`dist/wasm/vectojs_core.wasm`). Import it and hand it
+ * straight to any of the Scene WASM opt-ins:
+ *
+ * ```ts
+ * import { coreWasmUrl } from '@vectojs/core/wasm';
+ * await scene.enableWasmTransforms(coreWasmUrl);
+ * await scene.enableWasmAnimBatching(coreWasmUrl);
+ * await scene.enableWasmHitTest(coreWasmUrl);
+ * ```
+ *
+ * Why a helper module rather than a bare specifier: `new URL('@vectojs/core/…',
+ * import.meta.url)` does NOT work — `new URL` only resolves *relative* refs
+ * against a base, and a bare package specifier is not relative, so it never
+ * goes through package `exports`. Resolving `./vectojs_core.wasm` from *inside*
+ * the package (where this file sits next to the binary) is the only form that
+ * both native ESM and bundlers resolve correctly.
+ *
+ * The WASM is an optional accelerator: if a bundler tree-shakes this URL away or
+ * a runtime can't fetch it, every `enableWasm*` call simply returns `false` and
+ * the scene stays on the identical-output JS path. Nothing here is required for
+ * `@vectojs/core` to work.
+ */
+export declare const coreWasmUrl: URL;

package/dist/wasm/asset.js

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});const __vecto_cjs_url=require("url").pathToFileURL(__filename).href;
+
+// src/wasm/asset.ts
+var coreWasmUrl = new URL("./vectojs_core.wasm", __vecto_cjs_url);
+
+
+exports.coreWasmUrl = coreWasmUrl;

package/dist/wasm/asset.mjs

@@ -0,0 +1,5 @@
+// src/wasm/asset.ts
+var coreWasmUrl = new URL("./vectojs_core.wasm", import.meta.url);
+export {
+  coreWasmUrl
+};