@vectojs/core 1.14.0 → 1.16.0

package/dist/wasm/backend.d.ts

@@ -0,0 +1,154 @@
+/**
+ * WASM transform backend: uploads a {@link TransformStore}, runs the f64x2 SIMD
+ * kernel, and reads world matrices back. This is an invisible accelerator —
+ * {@link composeJS} computes the identical result and is the permanent fallback,
+ * so a caller that cannot instantiate WASM (CSP, no SIMD, missing asset) simply
+ * keeps using the JS path. Failure is the default state, not an error path.
+ *
+ * The seam is two batched crossings per compose (upload, readback), never per
+ * entity: at ~12-31 ns/crossing a per-entity call at 100k would cost >1 ms/frame.
+ */
+import type { TransformStore } from './soa';
+/** 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}. */
+export type Kernel = 'simd' | 'scalar';
+/**
+ * A live WASM backend bound to one module instance. `compose` is allocation-free
+ * after the first call at a given high-water capacity; growing past it re-`init`s
+ * and re-views memory (a `WebAssembly.Memory.buffer` detaches on growth, so the
+ * typed-array views must be rebuilt then — done here, never mid-compose).
+ */
+export declare class WasmTransformBackend {
+    readonly available: true;
+    private readonly ex;
+    private cap;
+    private runCap;
+    private vx;
+    private vy;
+    private vsx;
+    private vsy;
+    private vcos;
+    private vsin;
+    private vop;
+    private vwa;
+    private vwb;
+    private vwc;
+    private vwd;
+    private vwe;
+    private vwf;
+    private vwo;
+    private vbx;
+    private vby;
+    private vbw;
+    private vbh;
+    private vaminx;
+    private vaminy;
+    private vamaxx;
+    private vamaxy;
+    private vrp;
+    private vrs;
+    private vrl;
+    constructor(instance: WebAssembly.Instance);
+    /** Compose world matrices for `store` in WASM, writing back into its
+     *  `wa..wo` arrays. Result is bit-identical to `composeJS(store)`. */
+    compose(store: TransformStore, kernel?: Kernel): void;
+    /**
+     * Run the kernel only, over data already resident in WASM memory — no upload,
+     * no readback. This is the per-frame cost the *designed* integration pays:
+     * entity accessors write `x/y/rotation` straight into the wasm input views
+     * (via {@link inputView}) and the renderer reads world matrices straight from
+     * the wasm output views (via {@link worldView}), so the batch copies in
+     * {@link compose} do not happen every frame. `compose` must have run at least
+     * 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;
+    /** 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 wasm input views (`x,y,sx,sy,cos,sin,opacity`), valid until
+     *  the next capacity growth. Writing here is what makes uploads unnecessary. */
+    inputView(): {
+        x: Float64Array;
+        y: Float64Array;
+        sx: Float64Array;
+        sy: Float64Array;
+        cos: Float64Array;
+        sin: Float64Array;
+        opacity: Float64Array;
+    };
+    /** The resident wasm world-matrix output views (`wa..wo`). Reading here is
+     *  what makes readback unnecessary. */
+    worldView(): {
+        wa: Float64Array;
+        wb: Float64Array;
+        wc: Float64Array;
+        wd: Float64Array;
+        we: Float64Array;
+        wf: Float64Array;
+        wo: Float64Array;
+    };
+    /**
+     * Compute world-space AABBs for `store` in WASM (G1+), writing back into its
+     * `aminx/aminy/amaxx/amaxy` arrays. Uploads the local bounds, runs the AABB
+     * pass, reads results back. Result is bit-identical to `computeAabbsJS(store)`.
+     * `compose` (or `runKernel`) must have populated the world matrices first —
+     * this pass reads them. For the resident (no-copy) integration, write bounds
+     * via {@link boundsView} and read via {@link aabbView} + call
+     * {@link runAabbs} instead.
+     */
+    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;
+    /** Resident wasm local-bounds input views (`bx,by,bw,bh`) for the AABB pass. */
+    boundsView(): {
+        bx: Float64Array;
+        by: Float64Array;
+        bw: Float64Array;
+        bh: Float64Array;
+    };
+    /** Resident wasm world-AABB output views (`aminx,aminy,amaxx,amaxy`). */
+    aabbView(): {
+        aminx: Float64Array;
+        aminy: Float64Array;
+        amaxx: Float64Array;
+        amaxy: Float64Array;
+    };
+    private ensure;
+    /** Rebuild typed-array views after an init() (which may have grown, and thus
+     *  detached, the memory buffer). */
+    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): WasmTransformBackend | null;
+/**
+ * Instantiate asynchronously (browser main thread). Returns `null` on any
+ * failure — CSP `wasm-unsafe-eval`, unsupported SIMD, corrupt/missing bytes —
+ * so the caller keeps using the JS path. This is the loader the Scene hot-swap
+ * (gated integration) will await.
+ */
+export declare function instantiateAsync(bytes: BufferSource): Promise<WasmTransformBackend | null>;
+/**
+ * Anything the transform core can be loaded from: raw bytes, a URL/path string
+ * or {@link URL} to fetch, or a {@link Response} (or a promise of one) — e.g.
+ * `fetch(new URL('./vectojs_core.wasm', import.meta.url))`, the shape every
+ * bundler emits for a co-located `.wasm` asset.
+ */
+export type WasmModuleSource = BufferSource | string | URL | Response | Promise<Response>;
+/**
+ * Instantiate from a URL/Response using streaming compilation when the platform
+ * supports it (the module compiles while it downloads — the fastest cold start),
+ * and transparently falling back to fetch → arrayBuffer → instantiate when
+ * `WebAssembly.instantiateStreaming` is unavailable or the response's MIME type
+ * is not `application/wasm` (some engines reject the stream in that case, e.g. a
+ * dev server serving `application/octet-stream`). Returns `null` on any failure
+ * so the caller keeps the JS path — loading the accelerator is never an error path.
+ */
+export declare function instantiateStreaming(source: string | URL | Response | Promise<Response>): Promise<WasmTransformBackend | null>;

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

@@ -0,0 +1,92 @@
+/**
+ * WASM hit-test broad-phase backend: builds a dense viewport grid from world
+ * AABBs and answers "which entities overlap this cell" so a pointer query scans
+ * a handful of candidates instead of every entity in the tree. This is an
+ * invisible accelerator — the JS depth-first walk ({@link Entity.isPointInside}
+ * over every node) is the permanent fallback, so a caller that cannot
+ * instantiate WASM simply keeps using it. Failure is the default state, not an
+ * error path.
+ *
+ * The grid is a coarse pre-filter only: it never decides a hit by itself.
+ * {@link candidatesAt} returns the AABB-overlapping candidates in a cell
+ * (ascending entity index — scan from the end for topmost-first); the caller
+ * re-checks each one against its entity's own precise `isPointInside` (so
+ * non-rectangular hit shapes stay correct) before trusting a result.
+ */
+export declare class HitTestBackend {
+    private readonly ex;
+    private entityCap;
+    private cellCap;
+    private itemCap;
+    private vminx;
+    private vminy;
+    private vmaxx;
+    private vmaxy;
+    private vCellStart;
+    private vCellCount;
+    private vItems;
+    /** Grid geometry from the last {@link ensure} call. */
+    gridW: number;
+    gridH: number;
+    cellSize: number;
+    constructor(instance: WebAssembly.Instance);
+    /** The resident AABB input views (`minx/miny/maxx/maxy`), valid until the
+     *  next capacity growth. Writing here is what {@link build} reads from. */
+    inputView(): {
+        minx: Float64Array;
+        miny: Float64Array;
+        maxx: Float64Array;
+        maxy: Float64Array;
+    };
+    /**
+     * Size (and grow, if needed) capacity for `count` entities over
+     * `[0,vw] x [0,vh]` at `cellSize`, and record the grid geometry
+     * {@link candidatesAt} needs. Call this BEFORE writing AABBs into
+     * {@link inputView} — a capacity growth detaches the previous views, so
+     * writing first and sizing after would write into a stale buffer.
+     */
+    ensure(count: number, vw: number, vh: number, cellSize: number): void;
+    /**
+     * Run the kernel's bucketing over whatever is currently resident in
+     * {@link inputView} (write the AABBs there, and call {@link ensure} first).
+     * Returns `false` if the build overflowed its item budget — the caller must
+     * not trust {@link candidatesAt} results for this build and should fall back
+     * to the JS walk instead (never return a wrong hit).
+     */
+    runBuild(count: number, vw: number, vh: number, cellSize: number): boolean;
+    /**
+     * Entity indices whose AABB overlaps the cell containing `(px, py)`, in
+     * ascending index order (scan from the end for topmost/highest-index
+     * first), or `null` if the point falls outside the built grid. This is a
+     * coarse candidate LIST, not a hit result — the caller must still confirm
+     * each candidate's AABB contains the point and re-check its precise
+     * `isPointInside`.
+     */
+    candidatesAt(px: number, py: number): Int32Array | null;
+    private growIfNeeded;
+    /** Rebuild typed-array views after a growing `hit_init` (which detaches the
+     *  memory buffer). */
+    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): HitTestBackend | 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<HitTestBackend | null>;
+/** Anything the hit-test core can be loaded from, matching the transform
+ *  core's {@link WasmModuleSource} loading ergonomics. */
+export type HitModuleSource = 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<HitTestBackend | null>;

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

@@ -0,0 +1,48 @@
+/**
+ * Gather world AABBs from a live scene subtree for the WASM hit-test grid.
+ *
+ * This mirrors `Scene.findHitRecursively`'s exact traversal (self, then EVERY
+ * child in array order, recursively — `node.children` unconditionally, so
+ * DOM-portal descendants and anything renderNode's rendering-specific
+ * early-returns skip are still covered) so the grid-accelerated path can never
+ * see a different entity set than the JS walk it replaces.
+ *
+ * Indices are assigned in PRE-ORDER (self before children, children in array
+ * order): a node's own index is always lower than every index in its own
+ * subtree, and an earlier sibling's whole subtree is entirely lower than a
+ * later sibling's. Since `findHitRecursively` checks later siblings' subtrees
+ * before earlier ones, and a node's children before the node itself, "highest
+ * index wins" over this numbering is EXACTLY equivalent to that traversal's
+ * topmost-hit priority — the invariant the WASM grid kernel's `idx > best`
+ * comparison (see hit.rs) and the boundless-entity merge below both rely on.
+ *
+ * Entities without `getBounds()` (opted out of culling — "never known bounds")
+ * cannot be spatially indexed at all; they are collected into `boundless`
+ * instead, each tagged with its index, so the caller can still check them and
+ * compare against the grid's best candidate by that same index.
+ */
+import type { Entity } from '../tree/Entity';
+export interface HitGatherResult {
+    /** Total entities visited (bounded + boundless); the grid's `count`. */
+    count: number;
+    /** index -> Entity, for bounded entities (grid slot == array index). */
+    slotEntity: Entity[];
+    /** Entities with no `getBounds()`, each with its pre-order index, ascending. */
+    boundless: Array<{
+        entity: Entity;
+        index: number;
+    }>;
+    /** World AABBs, indexed like `slotEntity` (a boundless index has garbage —
+     *  never read, since those entities are only resolved via `boundless`). */
+    minx: Float64Array;
+    miny: Float64Array;
+    maxx: Float64Array;
+    maxy: Float64Array;
+}
+/** Walk `root` and all descendants into a flat, pre-order-indexed AABB set.
+ *  `currentFrame` is the scene's frame counter — passed through to
+ *  {@link Entity._readWorldCache} so the common case (every entity was
+ *  rendered this same frame, which the "gather right after a render" call
+ *  site always guarantees) reads six cached scalars per entity instead of
+ *  allocating a fresh `{a,b,c,d,e,f}` object via `getWorldTransform()`. */
+export declare function gatherHitAABBs(root: Entity, currentFrame: number): HitGatherResult;

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

@@ -0,0 +1,104 @@
+/**
+ * WASM particle-simulation backend (G4): advances the whole particle buffer for
+ * a `ComputeParticleEntity` in one `particle_step` call, instead of the JS
+ * per-particle `updateCPU` loop. This is the CPU fallback path — it runs exactly
+ * when there is no GPU — so the machines that most need it get the batched
+ * kernel. The JS `updateCPU` remains the permanent fallback when WASM cannot
+ * instantiate.
+ *
+ * ## f32, and its own differential oracle
+ *
+ * The particle buffer is a `Float32Array` (matches the WGSL compute shader), so
+ * the kernel (`crates/vectojs-core-rs/src/particle.rs`) commits to **f32** and is
+ * NOT bit-comparable to the f64 transform core. Its oracle is
+ * {@link particleStepReferenceF32} below — a JS f32 reference that rounds every
+ * intermediate to f32 (`Math.fround`) in the same op order and uses
+ * `sqrt(dx*dx+dy*dy)` (not `Math.hypot`, which is correctly-rounded f64). With
+ * those two rules the reference is bit-identical to the kernel, since f32
+ * add/sub/mul/div/sqrt of f32 operands round once whether done in f32 or
+ * f64-then-`fround`. (The shipped `updateCPU` stays f64 and differs by <1 ULP
+ * per step — the accepted CPU-vs-GPU-class divergence the survey documents.)
+ *
+ * ## SoA transpose
+ *
+ * The render/GPU buffer is AoS stride-8. The backend transposes position/
+ * velocity/origin/life into per-field f32 arrays ({@link gather}), runs the
+ * kernel, and scatters position/velocity/life back ({@link scatter}); origin and
+ * `size` never change during the sim.
+ */
+/** Per-field SoA views over the kernel's linear memory. Position/velocity/life
+ *  are read back each frame; origin is upload-once. */
+export interface ParticleView {
+    px: Float32Array;
+    py: Float32Array;
+    vx: Float32Array;
+    vy: Float32Array;
+    ox: Float32Array;
+    oy: Float32Array;
+    life: Float32Array;
+}
+/** Scalar simulation parameters + the current explosion impulse, passed to
+ *  `particle_step`. Mirrors `updateCPU`'s arguments. */
+export interface ParticleStepParams {
+    dt: number;
+    mouseX: number;
+    mouseY: number;
+    width: number;
+    height: number;
+    springK: number;
+    damping: number;
+    bounceDamping: number;
+    maxVelocity: number;
+    explosion: {
+        x: number;
+        y: number;
+        force: number;
+    } | null;
+}
+export declare class ParticleBackend {
+    private readonly ex;
+    private cap;
+    private view;
+    constructor(instance: WebAssembly.Instance);
+    /** The resident SoA views, valid until the next capacity growth. */
+    particleView(): ParticleView;
+    /**
+     * Size (and grow, if needed) capacity for `count` particles. Call BEFORE
+     * writing into {@link particleView} — a growth detaches the previous views.
+     */
+    ensure(count: number): void;
+    /**
+     * 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.
+     */
+    step(count: number, p: ParticleStepParams): boolean;
+    /** 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;
+    /** Scatter the mutated position/velocity/life back into the AoS buffer. */
+    scatter(data: Float32Array, count: number): void;
+    private refreshViews;
+}
+/** Instantiate synchronously (Node/tests/worker). Returns `null` on failure so
+ *  callers fall back to the JS `updateCPU`. */
+export declare function instantiateSync(bytes: BufferSource): ParticleBackend | null;
+/** Instantiate asynchronously (browser main thread). Returns `null` on any
+ *  failure so the caller keeps using the JS `updateCPU`. */
+export declare function instantiateAsync(bytes: BufferSource): Promise<ParticleBackend | null>;
+/** Anything the particle core can be loaded from. */
+export type ParticleModuleSource = BufferSource | string | URL | Response | Promise<Response>;
+/** Instantiate from a URL/Response with streaming compilation when available,
+ *  falling back to fetch → arrayBuffer → instantiate. Returns `null` on any
+ *  failure so the caller keeps the JS path. */
+export declare function instantiateStreaming(source: string | URL | Response | Promise<Response>): Promise<ParticleBackend | null>;
+/**
+ * JS f32 reference for `particle_step`, operating on the same {@link ParticleView}
+ * SoA arrays in place and returning the fused pending-animation flag. This is the
+ * kernel's differential oracle: every intermediate is rounded to f32 with
+ * `Math.fround` in the SAME op order as `particle.rs`, and distance uses
+ * `sqrt(dx*dx+dy*dy)` (NOT `Math.hypot`). It is therefore bit-identical to the
+ * Rust kernel — the differential test asserts exact equality. (This is NOT the
+ * shipped fallback; `ComputeParticleEntity.updateCPU` stays f64.)
+ */
+export declare function particleStepReferenceF32(view: ParticleView, count: number, p: ParticleStepParams): boolean;

package/dist/wasm/scene-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Build an SoA {@link TransformStore} from a live scene subtree.
+ *
+ * This is the bridge between the `Entity` tree and the WASM/JS transform core:
+ * it reads each entity's local transform (`x/y/scaleX/scaleY/rotation/opacity`)
+ * and emits the flat `InputNode[]` that {@link buildStore} turns into the
+ * depth-ordered, contiguous-sibling-run layout the kernel requires. It returns a
+ * map from `Entity` to its store index so a caller can read each entity's world
+ * matrix back out of `store.worldView()`/`store.wa…` after composition.
+ *
+ * The passed `root` becomes store index 0 at the identity world transform — its
+ * own local transform is ignored, matching how `Scene` seeds `renderNode` with
+ * the identity for `root`/`overlayRoot`. It touches no render state; wiring it
+ * into `Scene.render` is a separate, flagged step.
+ */
+import type { Entity } from '../tree/Entity';
+import { type TransformStore } from './soa';
+export interface TreeStore {
+    store: TransformStore;
+    /** Entity -> its index in `store` (into `wa…`/`worldView`). */
+    indexOf: Map<Entity, number>;
+}
+/**
+ * Walk `root` and all descendants (via `entity.children`) into an SoA store.
+ * Time O(n) in the subtree size; allocates one store per call (Stage 1 rebuilds
+ * per frame — Stage 3 will cache on structural change).
+ */
+export declare function buildTreeStore(root: Entity): TreeStore;

package/dist/wasm/soa.d.ts

@@ -0,0 +1,146 @@
+/**
+ * SoA transform store and the JS reference composer.
+ *
+ * This is the data-layout half of the Rust/WASM transform core. `buildStore`
+ * turns a tree into the pure Structure-of-Arrays layout the WASM kernel
+ * (`crates/vectojs-core-rs`) requires, and `composeJS` computes world matrices
+ * over that same layout in TypeScript. The two MUST produce bit-identical f64
+ * results — `composeJS` is both the correctness oracle for the differential
+ * test and the permanent fallback when WASM is unavailable (CSP, no SIMD,
+ * missing asset). Neither this file nor the loader touches `Entity`/`Scene`;
+ * wiring them into the render walk is the gated integration step (see the task
+ * plan), so this layer ships and is tested on its own.
+ *
+ * ## Why the layout is shaped this way
+ *
+ * - **Pure SoA** (one flat array per field): consecutive entities' `x` values
+ *   are adjacent, so a `v128` load fetches two at once. An interleaved record
+ *   would put them 8*N bytes apart and make SIMD unreachable.
+ * - **Contiguous sibling runs in depth order**: WASM SIMD has no gather, so the
+ *   parent matrix must be loop-invariant across a run. `buildStore` emits every
+ *   parent's children as one contiguous run and always emits a parent before
+ *   its children, so a run's parent world matrix is already composed when the
+ *   run is processed. The scene root is index 0 at the identity transform.
+ */
+/** A node's local transform (the six animatable scalars). */
+export interface LocalTransform {
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+    rotation: number;
+    opacity: number;
+}
+/**
+ * One input node. `parent` is an index into the input array, or `-1` for the
+ * single root. Input order is arbitrary; `buildStore` re-indexes into store
+ * order (root at 0, then depth-ordered contiguous sibling runs).
+ */
+export interface InputNode extends LocalTransform {
+    parent: number;
+    /**
+     * Local render bounds `[bx, by, bw, bh]` for the world-AABB pass
+     * ({@link computeAabbsJS} / the crate's `compute_aabbs`). Optional; defaults to
+     * `[0, 0, 0, 0]`, matching `Entity.getWorldBounds`'s `[0,0,width,height]`
+     * fallback when a node has no render-specific box (callers pass `width`/
+     * `height` as `bw`/`bh`).
+     */
+    bx?: number;
+    by?: number;
+    bw?: number;
+    bh?: number;
+}
+/** A composed world matrix (`a b c d e f`) plus accumulated opacity. */
+export interface WorldMatrix {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+    opacity: number;
+}
+/**
+ * The SoA store: input fields, output world-matrix fields, and the sibling-run
+ * table. Field arrays are sized `count + 8` so a 2-lane SIMD tail can read one
+ * slot past the logical end without a scalar remainder loop (mirrors the
+ * crate's `+8` padding). `storeIndexOf[k]` maps input index `k` to store index.
+ */
+export interface TransformStore {
+    count: number;
+    capacity: number;
+    x: Float64Array;
+    y: Float64Array;
+    sx: Float64Array;
+    sy: Float64Array;
+    cos: Float64Array;
+    sin: Float64Array;
+    opacity: Float64Array;
+    wa: Float64Array;
+    wb: Float64Array;
+    wc: Float64Array;
+    wd: Float64Array;
+    we: Float64Array;
+    wf: Float64Array;
+    wo: Float64Array;
+    bx: Float64Array;
+    by: Float64Array;
+    bw: Float64Array;
+    bh: Float64Array;
+    aminx: Float64Array;
+    aminy: Float64Array;
+    amaxx: Float64Array;
+    amaxy: Float64Array;
+    runParent: Int32Array;
+    runStart: Int32Array;
+    runLen: Int32Array;
+    runCount: number;
+    storeIndexOf: Int32Array;
+}
+/**
+ * Build the SoA store from a node list. Exactly one node must have
+ * `parent === -1` (the root); it becomes store index 0 at the identity world
+ * transform (its own local transform is ignored, matching how `Scene` leaves
+ * root/overlayRoot at identity). Throws on a missing or duplicate root.
+ *
+ * Emission is BFS per parent: dequeue a parent, emit ALL its children as one
+ * contiguous run, enqueue them. This guarantees (a) each parent's children are
+ * contiguous — required for SIMD — and (b) a parent is assigned a lower store
+ * index and composed before its children.
+ *
+ * Time: O(n). Space: O(n).
+ */
+export declare function buildStore(nodes: InputNode[]): TransformStore;
+/**
+ * Compose world matrices over the store in TypeScript — the reference oracle
+ * and the permanent JS fallback. Bit-identical to the crate's `compose_scalar`:
+ * same Canvas `T * S * R` order, same operation order, same f64 arithmetic.
+ * Seeds the root (index 0) to identity, then walks runs in order.
+ */
+export declare function composeJS(s: TransformStore): void;
+/** Read the world matrix at store index `i`. */
+export declare function readWorld(s: TransformStore, i: number): WorldMatrix;
+/** A world-space axis-aligned bounding box (min/max corner). */
+export interface WorldAabb {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/**
+ * Transform each node's local bounds `[bx, by, bw, bh]` through its already-
+ * composed world matrix into a world-space AABB (the min/max of the four
+ * transformed corners), writing `aminx/aminy/amaxx/amaxy`. This is the reference
+ * oracle and permanent JS fallback for the crate's `compute_aabbs`, and is
+ * bit-identical to `Entity.getWorldBounds` — same corner-selection bit trick
+ * (`i&1`/`i&2`), same `a*x + c*y + e` / `b*x + d*y + f` op order, same
+ * `Math.min`/`Math.max` accumulation over exactly four corners.
+ *
+ * Must run AFTER {@link composeJS} (or a `compose_*` kernel), which fills the
+ * world matrices this reads. A flat pass over `[0, count)` — the world matrices
+ * already encode the hierarchy, so no run walk is needed.
+ */
+export declare function computeAabbsJS(s: TransformStore): void;
+/** Read the world-space AABB at store index `i` (valid after `computeAabbsJS`
+ *  or the crate's `compute_aabbs`). */
+export declare function readAabb(s: TransformStore, i: number): WorldAabb;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "publishConfig": {
     "access": "public"
   },
@@ -46,26 +46,35 @@
       "types": "./dist/text/index.d.ts",
       "import": "./dist/text.mjs",
       "require": "./dist/text.js"
-    }
+    },
+    "./wasm": {
+      "types": "./dist/wasm/asset.d.ts",
+      "import": "./dist/wasm/asset.mjs",
+      "require": "./dist/wasm/asset.js"
+    },
+    "./vectojs_core.wasm": "./dist/wasm/vectojs_core.wasm"
   },
   "files": [
     "dist",
     "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
-    "benchmark:grid": "vitest bench benchmark/PreparedContentGrid.bench.ts --run",
-    "build": "node scripts/build-worker.js && tsup && tsc -p tsconfig.build.json",
+    "build": "(cd ../math && bun run build) && (cd ../text && bun run build) && (cd ../layout && bun run build) && (cd ../animation && bun run build) && tsup && tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:e2e": "bun e2e/hidpi.e2e.ts && bun e2e/text-projection.e2e.ts"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@vectojs/animation": "^0.1.1",
+    "@vectojs/layout": "^0.2.0",
+    "@vectojs/math": "^0.1.1",
+    "@vectojs/text": "^0.2.0"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",
-    "bidi-js": "^1.0.3",
     "esbuild": "^0.28.1",
     "jsdom": "^29.1.1",
+    "puppeteer-core": "^25.3.0",
     "tsup": "^8.3.5",
-    "vitest": "^4.1.10",
-    "puppeteer-core": "^25.3.0"
+    "vitest": "^4.1.10"
   }
 }

package/dist/animation/drivers.d.ts

@@ -1,48 +0,0 @@
-import { type EasingFn, type EasingName } from './easing';
-export interface SpringConfig {
-    stiffness?: number;
-    damping?: number;
-    mass?: number;
-}
-export interface TweenConfig {
-    duration: number;
-    easing?: EasingName | EasingFn;
-    delay?: number;
-}
-/** A motion config. Presence of `duration` selects a tween; otherwise a spring. */
-export type MotionConfig = 'spring' | SpringConfig | TweenConfig;
-export declare function isTweenConfig(c: MotionConfig): c is TweenConfig;
-/** Backs one animating property. Ticked in ms; writes `value`. */
-export interface PropertyDriver {
-    value: number;
-    /** The current destination — applied exactly when the animation completes, so a
-     * finished spring lands on target rather than within its rest epsilon. */
-    readonly target: number;
-    /** Change the destination. Spring keeps velocity; tween restarts from current value. */
-    retarget(to: number): void;
-    tick(dtMs: number): void;
-    isDone(): boolean;
-}
-export declare class TweenDriver implements PropertyDriver {
-    value: number;
-    private from;
-    private to;
-    private elapsed;
-    private readonly duration;
-    private readonly delay;
-    private readonly ease;
-    constructor(from: number, to: number, cfg: TweenConfig);
-    get target(): number;
-    retarget(to: number): void;
-    tick(dtMs: number): void;
-    isDone(): boolean;
-}
-export declare class SpringDriver implements PropertyDriver {
-    private spring;
-    constructor(from: number, to: number, cfg: SpringConfig);
-    get value(): number;
-    get target(): number;
-    retarget(to: number): void;
-    tick(dtMs: number): void;
-    isDone(): boolean;
-}