@vectojs/core 1.15.0 → 1.16.0

package/dist/layout.js

@@ -1,2 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _createStarExport(obj) { Object.keys(obj) .filter((key) => key !== "default" && key !== "__esModule") .forEach((key) => { if (exports.hasOwnProperty(key)) { return; } Object.defineProperty(exports, key, {enumerable: true, configurable: true, get: () => obj[key]}); }); }// src/layout/index.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _createStarExport(obj) { Object.keys(obj) .filter((key) => key !== "default" && key !== "__esModule") .forEach((key) => { if (exports.hasOwnProperty(key)) { return; } Object.defineProperty(exports, key, {enumerable: true, configurable: true, get: () => obj[key]}); }); }const __vecto_cjs_url=require("url").pathToFileURL(__filename).href;
+
+// src/layout/index.ts
 var _layout = require('@vectojs/layout'); _createStarExport(_layout);

package/dist/renderer/CanvasRenderer.d.ts

@@ -3,6 +3,14 @@ export declare class CanvasRenderer implements IRenderer {
     private ctx;
     private width;
     private height;
+    private canvas;
+    /** True between a `contextlost` and its `contextrestored` — the 2D context is
+     *  unusable, so draw calls are skipped until it comes back. Canvas2D context
+     *  loss is rare (GPU reset / memory pressure) but a real browser event. */
+    private contextLost;
+    /** Invoked after the context is restored + re-initialized, so the owner
+     *  (`Scene`) can repaint the now-blank canvas. Set via {@link onContextRestored}. */
+    private contextRestoredCb;
     /**
      * Cap on the effective device pixel ratio applied by the constructor and
      * {@link resize}. `undefined` (default) uses the real, uncapped
@@ -38,6 +46,17 @@ export declare class CanvasRenderer implements IRenderer {
         width: number;
         height: number;
     }, maxDPR?: number);
+    /** Register a callback fired after a lost 2D context is restored + re-scaled,
+     *  so the owner can repaint (the restored canvas comes back cleared). */
+    onContextRestored(cb: () => void): void;
+    /**
+     * Handle Canvas2D context loss/restore (GPU reset, memory pressure). The
+     * `contextlost` handler MUST call `preventDefault()` or the browser never
+     * fires `contextrestored`; while lost, draw calls are skipped. On restore we
+     * re-acquire the 2D context, re-apply the DPR scale, drop cached style, and
+     * notify the owner to repaint.
+     */
+    private setupContextLossRecovery;
     /**
      * Expose the underlying `CanvasRenderingContext2D` for operations not
      * covered by the {@link IRenderer} interface.
@@ -56,6 +75,9 @@ export declare class CanvasRenderer implements IRenderer {
      * @param height - New logical height in CSS pixels.
      */
     resize(width: number, height: number): void;
+    /** Whether the 2D context is currently lost (drawing is a no-op until it is
+     *  restored). The owner skips its render pass while this is true. */
+    isContextLost(): boolean;
     /** @inheritdoc */
     clear(): void;
     /** @inheritdoc */

package/dist/renderer/IRenderer.d.ts

@@ -191,4 +191,17 @@ export interface IRenderer {
      * successful teardown must be a silent no-op, not throw.
      */
     dispose?(): void;
+    /**
+     * Whether the renderer's drawing context is currently lost (e.g. a Canvas2D
+     * `contextlost` before its `contextrestored`, or a WebGL context loss). While
+     * true the renderer's draw calls are no-ops and the owner should skip its
+     * render pass. Optional — a renderer that can't lose its context omits it.
+     */
+    isContextLost?(): boolean;
+    /**
+     * Register a callback invoked after a lost context is restored and
+     * re-initialized, so the owner can repaint (a restored canvas comes back
+     * cleared). Optional, paired with {@link isContextLost}.
+     */
+    onContextRestored?(cb: () => void): void;
 }

package/dist/renderer.js

@@ -1,16 +1,17 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});const __vecto_cjs_url=require("url").pathToFileURL(__filename).href;
 
 
 
 
 
 
-var _chunkBEUIB3U7js = require('./chunk-BEUIB3U7.js');
 
+var _chunkIYPLG4Z4js = require('./chunk-IYPLG4Z4.js');
 
 
 
 
 
 
-exports.CanvasRenderer = _chunkBEUIB3U7js.CanvasRenderer; exports.SVGRenderer = _chunkBEUIB3U7js.SVGRenderer; exports.TextRasterCache = _chunkBEUIB3U7js.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkBEUIB3U7js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkBEUIB3U7js.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkBEUIB3U7js.parseColorToRGBA;
+
+exports.CanvasRenderer = _chunkIYPLG4Z4js.CanvasRenderer; exports.SVGRenderer = _chunkIYPLG4Z4js.SVGRenderer; exports.TextRasterCache = _chunkIYPLG4Z4js.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkIYPLG4Z4js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkIYPLG4Z4js.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkIYPLG4Z4js.parseColorToRGBA;

package/dist/renderer.mjs

@@ -5,7 +5,7 @@ import {
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
   parseColorToRGBA
-} from "./chunk-L5BCKFQE.mjs";
+} from "./chunk-JFU56BX4.mjs";
 export {
   CanvasRenderer,
   SVGRenderer,

package/dist/text/MSDFTextEntity.d.ts

@@ -12,6 +12,12 @@ export interface MSDFTextEntityOptions {
     maxWidth?: number;
     /** Layout height limit in logical pixels. Defaults to 1000. */
     maxHeight?: number;
+    /**
+     * Horizontal alignment. `'justify'` stretches every wrapped line flush to
+     * {@link maxWidth} (the paragraph-final and newline-ended lines stay ragged);
+     * `'left'` (default) leaves them ragged.
+     */
+    textAlign?: 'left' | 'justify';
 }
 export declare class MSDFTextEntity extends Entity {
     private font;
@@ -23,6 +29,9 @@ export declare class MSDFTextEntity extends Entity {
     private lineHeight?;
     private maxWidth;
     private maxHeight;
+    private textAlign;
+    private hyphenator;
+    private layoutText;
     private text;
     private lastRenderedSeqId;
     private rgbColorCache;
@@ -31,7 +40,27 @@ export declare class MSDFTextEntity extends Entity {
     constructor(text: string, options: MSDFTextEntityOptions);
     /** Change the wrap boundary and re-run layout for the current text. */
     setMaxWidth(maxWidth: number): void;
+    /**
+     * Set horizontal alignment (`'justify'` stretches wrapped lines flush to
+     * {@link setMaxWidth}'s width; the last line stays ragged) and re-run layout.
+     */
+    setTextAlign(align: 'left' | 'justify'): void;
+    /**
+     * Plug a hyphenator (word → parts). Break opportunities are inserted as soft
+     * hyphens (U+00AD) into the string sent to layout, so a word that doesn't fit
+     * can break with a visible hyphen. Soft hyphens already present in the text
+     * work without one. Pass `null` to disable. The original text is preserved
+     * for accessibility — only the layout string carries the hyphens.
+     */
+    setHyphenator(fn: ((word: string) => string[]) | null): void;
     setText(text: string): void;
+    /**
+     * Recompute {@link layoutText} from {@link text}: with a hyphenator active,
+     * split each whitespace-delimited word and rejoin its parts with U+00AD so
+     * the worker sees the break opportunities. Without one, the layout string is
+     * the text unchanged.
+     */
+    private rebuildLayoutText;
     private queueLayout;
     /**
      * Mirror the rendered text into the DOM content layer: find-in-page, screen

package/dist/text.js

@@ -1,11 +1,12 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _createStarExport(obj) { Object.keys(obj) .filter((key) => key !== "default" && key !== "__esModule") .forEach((key) => { if (exports.hasOwnProperty(key)) { return; } Object.defineProperty(exports, key, {enumerable: true, configurable: true, get: () => obj[key]}); }); }
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _createStarExport(obj) { Object.keys(obj) .filter((key) => key !== "default" && key !== "__esModule") .forEach((key) => { if (exports.hasOwnProperty(key)) { return; } Object.defineProperty(exports, key, {enumerable: true, configurable: true, get: () => obj[key]}); }); }const __vecto_cjs_url=require("url").pathToFileURL(__filename).href;
 
 
-var _chunkJ6NHSFIEjs = require('./chunk-J6NHSFIE.js');
+
+var _chunkDUYB4GX4js = require('./chunk-DUYB4GX4.js');
 
 // src/text/index.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
 
 
 
-exports.MSDFTextEntity = _chunkJ6NHSFIEjs.MSDFTextEntity; exports.SVGEntity = _chunkJ6NHSFIEjs.SVGEntity;
+exports.MSDFTextEntity = _chunkDUYB4GX4js.MSDFTextEntity; exports.SVGEntity = _chunkDUYB4GX4js.SVGEntity;

package/dist/text.mjs

@@ -1,7 +1,7 @@
 import {
   MSDFTextEntity,
   SVGEntity
-} from "./chunk-64UFEHOJ.mjs";
+} from "./chunk-AQTO7OSU.mjs";
 
 // src/text/index.ts
 export * from "@vectojs/text";

package/dist/tree/ComputeParticleEntity.d.ts

@@ -1,5 +1,6 @@
 import { Entity } from './Entity';
 import { IRenderer } from '../renderer/IRenderer';
+import type { ParticleBackend } from '../wasm/particle-backend';
 /**
  * Options for configuring a {@link ComputeParticleEntity}.
  */
@@ -60,6 +61,10 @@ export declare class ComputeParticleEntity extends Entity {
     computeBindGroup: any;
     /** WebGPU bind group for the render pass (usually same as compute). */
     renderBindGroup: any;
+    /** When the last simulation step ran through the WASM backend, its fused
+     *  pending-animation flag; `null` when the last step used the JS `updateCPU`
+     *  path (so `hasPendingAnimations` falls back to its own scan). */
+    private _wasmPending;
     constructor(options?: ComputeParticleOptions);
     /**
      * Disperses all particles randomly across the specified screen bounds.
@@ -127,6 +132,19 @@ export declare class ComputeParticleEntity extends Entity {
      * @param height - Boundary height.
      */
     updateCPU(dt: number, mouseX: number, mouseY: number, width: number, height: number): void;
+    /**
+     * Advance the simulation one step through the WASM particle kernel: transpose
+     * this entity's AoS buffer into the backend's SoA views, run `particle_step`,
+     * and scatter position/velocity/life back. Produces an f32 result (matching
+     * the WGSL shader) that differs from {@link updateCPU}'s f64 by <1 ULP/step —
+     * the accepted CPU-vs-GPU-class divergence. Caches the kernel's fused
+     * pending-animation flag so {@link hasPendingAnimations} needs no second scan.
+     *
+     * 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.
+     */
+    stepWithBackend(backend: ParticleBackend, dt: number, mouseX: number, mouseY: number, width: number, height: number): void;
     destroy(): void;
     /**
      * Frees all GPU resources allocated for WebGPU simulation.

package/dist/tree/DOMPortalEntity.d.ts

@@ -4,6 +4,7 @@ export declare class DOMPortalEntity extends Entity {
     isDOMPortal: boolean;
     private domListeners;
     private resizeObserver;
+    private domBound;
     cachedWidth: number;
     cachedHeight: number;
     lastWidth: string;
@@ -12,6 +13,23 @@ export declare class DOMPortalEntity extends Entity {
     lastZIndex: string;
     lastOpacity: string;
     constructor(domElement: HTMLElement, width?: number, height?: number, id?: string);
+    /**
+     * Attach the ResizeObserver + DOM event listeners that bridge native DOM
+     * events into the Vecto event system. Idempotent: safe to call every frame
+     * from the projection path (`Scene.syncPortalGeometry`), which is what lets a
+     * portal survive a `scene.remove()` -> re-add cycle — {@link releaseDOMBindings}
+     * tears these down on removal and the next projection re-attaches them.
+     */
+    attachDOMBindings(): void;
+    /**
+     * Disconnect the ResizeObserver and remove the DOM event listeners, without
+     * touching the scene graph or the element's DOM parentage. Called on the
+     * `scene.remove()` path so a detached portal doesn't leak an observer that
+     * keeps its element alive and firing; the element itself is removed from the
+     * document by the scene's portal pruning. Re-attached lazily on the next
+     * projection frame via {@link attachDOMBindings}.
+     */
+    releaseDOMBindings(): void;
     isPointInside(globalX: number, globalY: number): boolean;
     add(..._children: Entity[]): this;
     render(): void;

package/dist/tree/Entity.d.ts

@@ -1,4 +1,4 @@
-import { type MotionConfig, type TweenConfig, type SpringConfig } from '@vectojs/animation';
+import { type PropertyDriver, type MotionConfig, type TweenConfig, type SpringConfig } from '@vectojs/animation';
 import type { PreparedContentGrid } from '@vectojs/text';
 /** A numeric transform/visual property that participates in the animation system. */
 export type AnimatableProp = 'x' | 'y' | 'scaleX' | 'scaleY' | 'rotation' | 'opacity';
@@ -65,6 +65,21 @@ export interface ContentProjectionRun {
     text: string;
     /** CSS font shorthand matching the canvas run. */
     font?: string;
+    /**
+     * Absolute local x of this run within the entity. Set it (with {@link width})
+     * for justified or otherwise non-naturally-spaced text: the Scene then places
+     * each run as a positioned carrier (`inline-block` + relative `left`) at the
+     * exact canvas x, so the DOM selection box overlaps the drawn glyphs instead
+     * of drifting under the browser's own inter-word spacing. When omitted, runs
+     * flow naturally (the default for left-aligned text).
+     */
+    x?: number;
+    /**
+     * Advance (width in px) the canvas used for this run, including any widened
+     * trailing gap for justify. Used only alongside {@link x} to size the
+     * positioned carrier so the next run starts flush at its own `x`.
+     */
+    width?: number;
 }
 export interface ContentProjectionLine {
     /** Text for browser find-in-page and native selection. */
@@ -186,6 +201,30 @@ export interface A11yAttributes {
     activedescendant?: string;
     valuemin?: string;
     valuemax?: string;
+    /**
+     * ARIA live-region politeness (`aria-live`). Set on the container whose text
+     * changes as content streams in (chat message, toast, async validation
+     * summary) so a screen reader announces updates without moving focus.
+     * `'polite'` waits for a pause; `'assertive'` interrupts. WCAG 4.1.3.
+     */
+    live?: 'off' | 'polite' | 'assertive';
+    /** `aria-atomic`: announce the whole region on change, not just the diff. */
+    atomic?: boolean;
+    /** `aria-relevant`: which mutation types to announce (e.g. `'additions text'`). */
+    relevant?: string;
+    /** `aria-labelledby`: id(s) of the element(s) that label this one. */
+    labelledby?: string;
+    /** `aria-describedby`: id(s) of the element(s) that describe this one. */
+    describedby?: string;
+    /** `aria-required`: the field must be filled before submit. */
+    required?: boolean;
+    /** `aria-invalid`: the field's current value fails validation. */
+    invalid?: boolean;
+    /** `aria-level`: hierarchical level (headings, tree items, etc.). */
+    level?: number;
+    /** `aria-modal`: marks a `role="dialog"` as modal so assistive tech confines
+     *  reading to it. Set on a modal dialog's shell. */
+    ariaModal?: 'true' | 'false';
     /** Explicit native editor typography; ignored for non-input elements. */
     textInputStyle?: TextInputStyle;
 }
@@ -295,6 +334,18 @@ export declare abstract class Entity {
     private _transitions;
     private _drivers;
     private _mounted;
+    private _destroyed;
+    _driversTickedFrame: number;
+    private readonly _trig;
+    private _trigRotation;
+    private _wa;
+    private _wb;
+    private _wc;
+    private _wd;
+    private _we;
+    private _wf;
+    private _worldFrame;
+    _storeSlot: number;
     get x(): number;
     set x(v: number);
     get y(): number;
@@ -330,9 +381,9 @@ export declare abstract class Entity {
      * fixed viewport. Off by default (children render unclipped). Canvas2D only.
      */
     clipChildren: boolean;
-    protected listeners: Map<VectoEvent, Array<(e: any) => void>>;
+    protected listeners: Map<VectoEvent, Array<(e: any) => void>> | null;
     /** Capture-phase listeners (fired root→target before bubble). */
-    protected captureListeners: Map<VectoEvent, Array<(e: any) => void>>;
+    protected captureListeners: Map<VectoEvent, Array<(e: any) => void>> | null;
     private animations;
     constructor(id?: string);
     /**
@@ -422,6 +473,26 @@ export declare abstract class Entity {
     private _driveTo;
     /** Advance active property drivers one frame. Call from update(). */
     protected tickDrivers(dt: number): void;
+    /**
+     * Internal: this entity's active-driver map (read-only view), or `null` if
+     * it has none. Called only by Scene's batched WASM animation pass, never
+     * application code. Returns the Map directly (not a callback iteration) so
+     * a caller can `for...of` it with zero per-entity closure allocation — the
+     * integrated benchmark (benchmarks/anim-wasm-scene) found a fresh callback
+     * per entity per frame was a real cost, not a negligible one.
+     */
+    _driverEntries(): ReadonlyMap<AnimatableProp, PropertyDriver> | null;
+    /**
+     * Internal: finalize one driver that was ALREADY advanced externally this
+     * frame (e.g. by Scene's batched WASM tick via `driver.syncExternal`, or a
+     * direct `driver.tick()` call for a driver the batch can't offload) —
+     * exactly mirrors tickDrivers()'s own per-driver completion logic, so a
+     * driver behaves identically regardless of which path ticked it. Called
+     * only by Scene, never application code.
+     */
+    _applyDriverTick(prop: AnimatableProp, driver: PropertyDriver): void;
+    /** Internal: true if this entity currently has any active property driver. */
+    _hasActiveDrivers(): boolean;
     /**
      * Advance the entity's internal state for one frame.
      *
@@ -456,8 +527,21 @@ export declare abstract class Entity {
      */
     off(event: VectoEvent, callback: (e: any) => void, options?: ListenerOptions): this;
     /**
-     * Tear down this entity: clear all animations, event listeners, and detach
-     * from parent. Call before discarding an entity to prevent memory leaks.
+     * Tear down this entity **and its entire subtree**: recursively destroy every
+     * descendant (leaf-first), clear all animations, event listeners, and property
+     * drivers, then detach from the parent. Call before discarding an entity to
+     * prevent memory leaks.
+     *
+     * Recursing here is what frees a subtree's GPU buffers, layout workers, and DOM
+     * observers when an app does `entity.destroy()` or `scene.remove(subtree)` on a
+     * route change — without it, only the root's own state was released and every
+     * descendant (and its subclass resources) was stranded. Subclasses that own
+     * external resources override `destroy()`, free their resource, then call
+     * `super.destroy()`; because children don't depend on a parent's resource, the
+     * order (parent resource first, then descendants) is safe.
+     *
+     * Idempotent and re-entrancy safe: a second call is a no-op, and because each
+     * child is detached as it is destroyed, destroying a subtree never double-frees.
      */
     destroy(): void;
     /**
@@ -498,10 +582,42 @@ export declare abstract class Entity {
      * @returns World-space {@link Point} for this entity.
      */
     getGlobalPosition(): Point;
+    /**
+     * Internal: read this entity's cached world matrix into `out` — the SAME
+     * cache {@link getWorldTransform} reads — without allocating a wrapper
+     * object. Returns `false` (leaving `out` untouched) when the cache isn't
+     * valid for `frame` (typically the caller's `scene.currentFrame`), exactly
+     * mirroring {@link getWorldTransform}'s own validity check; the caller
+     * falls back to {@link getWorldTransform}'s full walk in that case. Exists
+     * so a per-entity gather that runs every entity through this (e.g. G3's
+     * `gatherHitAABBs`) pays for six scalar reads instead of one object
+     * allocation per entity per call — the exact class of per-frame garbage
+     * the G2 integrated benchmark found dominating its own gather cost.
+     */
+    _readWorldCache(frame: number, out: AffineTransform): boolean;
     /**
      * Return the exact accumulated Canvas `T * S * R` transform for this entity.
      */
     getWorldTransform(): AffineTransform;
+    /**
+     * Return this entity's cached `{ cos, sin }` of its current rotation,
+     * recomputing only when `rotation` has actually changed since the last call.
+     * The same object identity is returned across calls with an unchanged
+     * rotation, so callers must treat it as read-only. Used by the render walk
+     * and {@link getWorldTransform} to avoid V8's comparatively slow Math.cos/sin
+     * (a software libm call, ~2.5x slower than other engines) per entity/frame.
+     */
+    _getTrig(): Readonly<{
+        cos: number;
+        sin: number;
+    }>;
+    /**
+     * Store the world matrix Scene computed for this entity during the render
+     * walk, stamped with the frame it belongs to. {@link getWorldTransform}
+     * returns it verbatim while `frame === scene.currentFrame`. Internal: called
+     * only by Scene's renderer, never by application code.
+     */
+    _setWorldCache(a: number, b: number, c: number, d: number, e: number, f: number, frame: number): void;
     /** Convert a point from this entity's local space to Scene/world space. */
     localToWorld(localX: number, localY: number): Point;
     /**