@vectojs/core 0.1.0 → 0.2.1

package/dist/tree/ComputeParticleEntity.d.ts

@@ -0,0 +1,118 @@
+import { Entity } from './Entity';
+import { IRenderer } from '../renderer/IRenderer';
+/**
+ * Options for configuring a {@link ComputeParticleEntity}.
+ */
+export interface ComputeParticleOptions {
+    /** Maximum number of particles to simulate. Defaults to 10000. */
+    maxParticles?: number;
+    /** Spring stiffness coefficient for returning to origin. Defaults to 0.05. */
+    springK?: number;
+    /** Velocity damping factor in `[0, 1]`. Defaults to 0.95. */
+    damping?: number;
+    /** Bounce damping factor for boundary collisions in `[0, 1]`. Defaults to 0.5. */
+    bounceDamping?: number;
+    /** Speed limit for particles. Defaults to 500.0. */
+    maxVelocity?: number;
+    /** Base particle size in pixels. Defaults to 4. */
+    size?: number;
+    /** CSS color string for the particles. Defaults to '#00f0ff'. */
+    color?: string;
+    /** Whether the particle layer captures pointer/hit events. Defaults to false. */
+    pointerEvents?: boolean;
+}
+export declare const PARTICLE_STRIDE_FLOATS = 8;
+export declare const PARTICLE_OFFSET_POSITION_X = 0;
+export declare const PARTICLE_OFFSET_POSITION_Y = 1;
+export declare const PARTICLE_OFFSET_VELOCITY_X = 2;
+export declare const PARTICLE_OFFSET_VELOCITY_Y = 3;
+export declare const PARTICLE_OFFSET_ORIGIN_X = 4;
+export declare const PARTICLE_OFFSET_ORIGIN_Y = 5;
+export declare const PARTICLE_OFFSET_SIZE = 6;
+export declare const PARTICLE_OFFSET_LIFE = 7;
+/**
+ * An entity representing a high-performance WebGPU/CPU particle simulation layer.
+ */
+export declare class ComputeParticleEntity extends Entity {
+    maxParticles: number;
+    springK: number;
+    damping: number;
+    bounceDamping: number;
+    maxVelocity: number;
+    size: number;
+    baseColor: string;
+    pointerEvents: boolean;
+    /** Flat array containing layout of all particles: position, velocity, origin, size, life. */
+    particleData: Float32Array;
+    /** Flag indicating whether the particle coordinates need to be initialized. */
+    needsInit: boolean;
+    /** Active explosion impulse to apply in the next simulation step. */
+    pendingExplosion: {
+        x: number;
+        y: number;
+        force: number;
+    } | null;
+    /** WebGPU storage buffer containing particle states. */
+    gpuStorageBuffer: any;
+    /** WebGPU uniform buffer containing simulation parameters. */
+    gpuUniformBuffer: any;
+    /** WebGPU bind group for the compute shader pass. */
+    computeBindGroup: any;
+    /** WebGPU bind group for the render pass (usually same as compute). */
+    renderBindGroup: any;
+    constructor(options?: ComputeParticleOptions);
+    /**
+     * Disperses all particles randomly across the specified screen bounds.
+     * Sets initial positions, velocities, origins, and sizes.
+     *
+     * @param width - Simulation zone width.
+     * @param height - Simulation zone height.
+     */
+    initRandomParticles(width: number, height: number): void;
+    /**
+     * Sets the origins (ox, oy) for a subset or all particles.
+     * Also sets position to origin if requestPositionReset is true.
+     *
+     * @param points - Flat Float32Array containing [x0, y0, x1, y1, ...]
+     * @param requestPositionReset - Whether to set current positions to the new origins. Defaults to true.
+     */
+    setOrigins(points: Float32Array | number[], requestPositionReset?: boolean): void;
+    /**
+     * Sets the current positions (x, y) for a subset or all particles.
+     *
+     * @param positions - Flat Float32Array containing [x0, y0, x1, y1, ...]
+     */
+    setPositions(positions: Float32Array | number[]): void;
+    /**
+     * Sets the current velocities (vx, vy) for a subset or all particles.
+     *
+     * @param velocities - Flat Float32Array containing [vx0, vy0, vx1, vy1, ...]
+     */
+    setVelocities(velocities: Float32Array | number[]): void;
+    /**
+     * Triggers an explosion force center.
+     *
+     * @param x - Explosion center x-coordinate.
+     * @param y - Explosion center y-coordinate.
+     * @param force - Magnitude force scalar.
+     */
+    triggerExplosion(x: number, y: number, force: number): void;
+    isPointInside(_x: number, _y: number): boolean;
+    render(_r: IRenderer): void;
+    /**
+     * Updates particle simulation on the CPU.
+     * Handles spring forces, mouse repulsion, explosion impulses, velocity capping, and bounds bouncing/clamping.
+     *
+     * @param dt - Delta time in seconds.
+     * @param mouseX - Mouse x-coordinate, or a value below -9000 if inactive.
+     * @param mouseY - Mouse y-coordinate, or a value below -9000 if inactive.
+     * @param width - Boundary width.
+     * @param height - Boundary height.
+     */
+    updateCPU(dt: number, mouseX: number, mouseY: number, width: number, height: number): void;
+    destroy(): void;
+    /**
+     * Frees all GPU resources allocated for WebGPU simulation.
+     */
+    destroyGPUResources(): void;
+}

package/dist/tree/DOMPortalEntity.d.ts

@@ -0,0 +1,18 @@
+import { Entity } from './Entity';
+export declare class DOMPortalEntity extends Entity {
+    domElement: HTMLElement;
+    isDOMPortal: boolean;
+    private domListeners;
+    private resizeObserver;
+    cachedWidth: number;
+    cachedHeight: number;
+    lastWidth: string;
+    lastHeight: string;
+    lastTransform: string;
+    lastZIndex: string;
+    constructor(domElement: HTMLElement, width?: number, height?: number, id?: string);
+    isPointInside(globalX: number, globalY: number): boolean;
+    add(child: Entity): this;
+    render(): void;
+    destroy(): void;
+}

package/dist/{Entity-D-rfAFCf.d.mts → tree/Entity.d.ts}

@@ -1,186 +1,10 @@
-/**
- * Renderer abstraction consumed by every {@link Entity}.
- *
- * Implementations wrap a concrete drawing backend (Canvas 2D, WebGL, …) and
- * expose a path-based drawing API.  Entities must only depend on `IRenderer`
- * so they remain backend-agnostic.
- *
- * @example
- * // Inside an Entity.render() implementation:
- * render(r: IRenderer) {
- *   r.beginPath();
- *   r.fill('#38bdf8');
- * }
- */
-interface IRenderer {
-    /** Clear the entire drawing surface to transparent / background color. */
-    clear(): void;
-    /** Push the current transform + state onto the renderer's stack. */
-    save(): void;
-    /** Pop the last saved transform + state from the renderer's stack. */
-    restore(): void;
-    /**
-     * Apply a translation to the current transform matrix.
-     *
-     * @param x - Horizontal offset in pixels.
-     * @param y - Vertical offset in pixels.
-     */
-    translate(x: number, y: number): void;
-    /**
-     * Apply a scale to the current transform matrix.
-     *
-     * @param x - Horizontal scale factor.
-     * @param y - Vertical scale factor.
-     */
-    scale(x: number, y: number): void;
-    /**
-     * Apply a clockwise rotation to the current transform matrix.
-     *
-     * @param angle - Rotation angle in radians.
-     */
-    rotate(angle: number): void;
-    /**
-     * Set the global opacity applied to all subsequent draw calls.
-     *
-     * @param alpha - Opacity in the range `[0, 1]`.
-     */
-    setGlobalAlpha(alpha: number): void;
-    /**
-     * Intersect the current clip region with a rectangle. Affects all subsequent
-     * draws until the next {@link restore}; wrap in {@link save}/{@link restore}.
-     *
-     * @param x - Left edge.
-     * @param y - Top edge.
-     * @param width - Rectangle width.
-     * @param height - Rectangle height.
-     */
-    clip(x: number, y: number, width: number, height: number): void;
-    /** Begin a new sub-path, discarding the current path. */
-    beginPath(): void;
-    /**
-     * Move the pen to the given point without drawing a line.
-     *
-     * @param x - Target X coordinate.
-     * @param y - Target Y coordinate.
-     */
-    moveTo(x: number, y: number): void;
-    /**
-     * Add a straight line segment from the current pen position to the given point.
-     *
-     * @param x - Target X coordinate.
-     * @param y - Target Y coordinate.
-     */
-    lineTo(x: number, y: number): void;
-    /**
-     * Add a cubic Bézier curve to the current path.
-     *
-     * @param cp1x - X of the first control point.
-     * @param cp1y - Y of the first control point.
-     * @param cp2x - X of the second control point.
-     * @param cp2y - Y of the second control point.
-     * @param x - X of the end point.
-     * @param y - Y of the end point.
-     */
-    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
-    /** Close the current sub-path by drawing a line back to its starting point. */
-    closePath(): void;
-    /**
-     * Add a circular arc to the current path.
-     *
-     * @param x - X of the arc center.
-     * @param y - Y of the arc center.
-     * @param radius - Arc radius in pixels.
-     * @param startAngle - Start angle in radians (0 = 3 o'clock).
-     * @param endAngle - End angle in radians.
-     * @param counterclockwise - If `true`, draws the arc counter-clockwise.
-     */
-    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
-    /**
-     * Add a rounded rectangle to the current path.
-     *
-     * @param x - Left edge.
-     * @param y - Top edge.
-     * @param width - Rectangle width.
-     * @param height - Rectangle height.
-     * @param radii - Corner radius (uniform) or per-corner array as accepted by `CanvasRenderingContext2D.roundRect()`.
-     */
-    roundRect(x: number, y: number, width: number, height: number, radii: number | number[]): void;
-    /**
-     * Draw an image or video frame into the canvas.
-     *
-     * @param source - The image source (HTMLImageElement, HTMLVideoElement, HTMLCanvasElement, etc.).
-     * @param dx - Destination X.
-     * @param dy - Destination Y.
-     * @param dw - Destination width.
-     * @param dh - Destination height.
-     */
-    drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
-    /**
-     * Fill the current path with the given color or gradient.
-     *
-     * @param colorOrGradient - CSS color string or a gradient object.
-     */
-    fill(colorOrGradient: string | any): void;
-    /**
-     * Stroke the current path with the given color or gradient.
-     *
-     * @param colorOrGradient - CSS color string or a gradient object.
-     * @param lineWidth - Stroke width in pixels (default: `1`).
-     */
-    stroke(colorOrGradient: string | any, lineWidth?: number): void;
-    /**
-     * Render a text string at the given position.
-     *
-     * @param text - The string to draw.
-     * @param x - Left edge of the text baseline.
-     * @param y - Baseline Y coordinate.
-     * @param font - CSS font shorthand, e.g. `'16px monospace'`.
-     * @param color - CSS color string or gradient.
-     */
-    fillText(text: string, x: number, y: number, font: string, color: string | any): void;
-    /**
-     * Draw a filled circle through the order-preserving batch.
-     *
-     * Consecutive calls sharing the same `color` and `alpha` are coalesced into a
-     * single path and committed with one `fill()` on {@link flush} (or when the
-     * style changes / another draw call intervenes). Coordinates are in the
-     * current transform space. This collapses the per-entity
-     * `beginPath`/`arc`/`fill` of large point clouds into a handful of draw calls
-     * while preserving painter's-order semantics.
-     *
-     * @param cx - Center X in the current transform space.
-     * @param cy - Center Y in the current transform space.
-     * @param radius - Circle radius.
-     * @param color - CSS color string.
-     * @param alpha - Opacity in `[0, 1]` (default `1`).
-     */
-    fillCircle(cx: number, cy: number, radius: number, color: string, alpha?: number): void;
-    /**
-     * Commit any pending batched draws (see {@link fillCircle}). Safe to call when
-     * no batch is active (no-op). The {@link Scene} flushes at the end of each
-     * sibling group and frame.
-     */
-    flush(): void;
-    /**
-     * Create a linear gradient between two points with the given color stops.
-     *
-     * @param x0 - X of the gradient start point.
-     * @param y0 - Y of the gradient start point.
-     * @param x1 - X of the gradient end point.
-     * @param y1 - Y of the gradient end point.
-     * @param colorStops - Array of `{ stop, color }` pairs where `stop` is in `[0, 1]`.
-     * @returns An opaque gradient object suitable for {@link fill} or {@link stroke}.
-     */
-    createLinearGradient(x0: number, y0: number, x1: number, y1: number, colorStops: {
-        stop: number;
-        color: string;
-    }[]): any;
-}
-
+import { type MotionConfig, type TweenConfig, type SpringConfig } from '../animation/drivers';
+/** A numeric transform/visual property that participates in the animation system. */
+export type AnimatableProp = 'x' | 'y' | 'scaleX' | 'scaleY' | 'rotation' | 'opacity';
 /**
  * A 2-D coordinate in canvas/world space.
  */
-interface Point {
+export interface Point {
     x: number;
     y: number;
 }
@@ -189,7 +13,7 @@ interface Point {
  *
  * Returned from {@link Entity.getBounds} to enable viewport culling.
  */
-interface Bounds {
+export interface Bounds {
     x: number;
     y: number;
     width: number;
@@ -200,7 +24,7 @@ interface Bounds {
  * origin, returned from {@link Entity.getBatchCircle} to opt into the renderer's
  * draw-call batching fast-path.
  */
-interface BatchCircle {
+export interface BatchCircle {
     /** Circle radius in the entity's local space. */
     radius: number;
     /** CSS fill color. */
@@ -211,7 +35,7 @@ interface BatchCircle {
  * origin, returned from {@link Entity.getBatchRect} to opt into the GPU
  * instanced-rectangle fast-path (WebGL `pointBackend` only).
  */
-interface BatchRect {
+export interface BatchRect {
     /** Rectangle width in the entity's local space. */
     width: number;
     /** Rectangle height in the entity's local space. */
@@ -227,7 +51,7 @@ interface BatchRect {
  * to create and label the shadow DOM node (e.g. a real `<button>` or `<a href>`)
  * so the canvas stays accessible and clickable by automation/agents.
  */
-interface A11yAttributes {
+export interface A11yAttributes {
     /** Shadow element tag to create. Defaults to `'div'`. */
     tag?: 'div' | 'a' | 'button' | 'img' | 'input' | 'textarea';
     /** ARIA role applied via the `role` attribute. */
@@ -263,9 +87,9 @@ interface A11yAttributes {
 /**
  * Union of all pointer/interaction events that can be emitted by an {@link Entity}.
  */
-type VectoEvent = 'click' | 'hover' | 'pointerdown' | 'pointerup' | 'pointermove' | 'pointerleave' | 'change' | 'focus' | 'blur' | 'wheel' | 'keydown' | 'keyup';
+export type VectoEvent = 'click' | 'hover' | 'pointerdown' | 'pointerup' | 'pointermove' | 'pointerleave' | 'change' | 'focus' | 'blur' | 'wheel' | 'keydown' | 'keyup';
 /** Options for {@link Entity.on} / {@link Entity.off}. */
-interface ListenerOptions {
+export interface ListenerOptions {
     /** Register the listener for the capture phase (root→target) instead of bubble. */
     capture?: boolean;
 }
@@ -279,7 +103,7 @@ interface ListenerOptions {
  * `clientX`, `key`, …) and `preventDefault()` pass through to `nativeEvent`, so
  * handlers written against the raw DOM event keep working.
  */
-declare class VectoJSEvent<N = unknown> {
+export declare class VectoJSEvent<N = unknown> {
     /** The event name. */
     readonly type: VectoEvent;
     /** The entity the event originated on. */
@@ -334,7 +158,7 @@ declare class VectoJSEvent<N = unknown> {
  *   }
  * }
  */
-declare abstract class Entity {
+export declare abstract class Entity {
     id: string;
     children: Entity[];
     parent: Entity | null;
@@ -342,12 +166,28 @@ declare abstract class Entity {
      * Walk up the parent chain to find the scene this entity is currently attached to.
      */
     get scene(): any;
-    x: number;
-    y: number;
-    scaleX: number;
-    scaleY: number;
-    rotation: number;
-    opacity: number;
+    private _x;
+    private _y;
+    private _scaleX;
+    private _scaleY;
+    private _rotation;
+    private _opacity;
+    private _hasTransitions;
+    private _transitions;
+    private _drivers;
+    private _mounted;
+    get x(): number;
+    set x(v: number);
+    get y(): number;
+    set y(v: number);
+    get scaleX(): number;
+    set scaleX(v: number);
+    get scaleY(): number;
+    set scaleY(v: number);
+    get rotation(): number;
+    set rotation(v: number);
+    get opacity(): number;
+    set opacity(v: number);
     isDOMPortal: boolean;
     private _interactive;
     get interactive(): boolean;
@@ -383,6 +223,10 @@ declare abstract class Entity {
      * @returns `this` for method chaining.
      */
     add(child: Entity): this;
+    /** Called once when this entity becomes attached to a live Scene. Override to react. */
+    protected onMounted(): void;
+    /** Fire onMounted for this node and its descendants, guarded against double-fire. */
+    private _notifyMounted;
     /**
      * Remove a child entity from this node.
      *
@@ -411,6 +255,26 @@ declare abstract class Entity {
      * @example entity.animate({ x: 400, opacity: 0 }, 500);
      */
     animate(targetProps: Partial<this>, durationMs: number): this;
+    /** Write a driver-computed value to a backing field without re-triggering the setter. */
+    private _applyAnimated;
+    private _currentOf;
+    /**
+     * Write a value immediately, bypassing any configured transition. For subclasses
+     * that need to seed a starting state (e.g. the presence helper's enter `from`).
+     */
+    protected setImmediate(prop: AnimatableProp, v: number): void;
+    private _spawnDriver;
+    /** Assignment path when a declarative transition is configured for `prop`. */
+    private _animateProp;
+    /** Declare which properties animate, and how. Subsequent assignment animates them. */
+    setTransition(config: Partial<Record<AnimatableProp, MotionConfig>>): this;
+    /** Imperative tween toward targets; resolves when all reach their end. */
+    animateTo(props: Partial<Record<AnimatableProp, number>>, cfg: TweenConfig): Promise<void>;
+    /** Imperative spring toward targets; resolves when all reach rest. */
+    springTo(props: Partial<Record<AnimatableProp, number>>, cfg?: SpringConfig): Promise<void>;
+    private _driveTo;
+    /** Advance active property drivers one frame. Call from update(). */
+    protected tickDrivers(dt: number): void;
     /**
      * Advance the entity's internal state for one frame.
      *
@@ -420,7 +284,7 @@ declare abstract class Entity {
      * @param dt - Elapsed time since the last frame in milliseconds.
      * @param time - Absolute timestamp from `performance.now()`.
      */
-    update(_dt: number, time: number): void;
+    update(dt: number, time: number): void;
     /**
      * Register a listener for a {@link VectoEvent}.
      *
@@ -549,12 +413,20 @@ declare abstract class Entity {
      */
     getBatchRect(): BatchRect | null;
     /**
-     * Whether this entity still has a queued/running tween animation.
+     * Whether this entity still has a queued/running tween animation, or an
+     * active {@link setTransition}/{@link animateTo}/{@link springTo} property
+     * driver.
      *
-     * Used by {@link Scene}'s `onDemand` render mode to keep redrawing while an
-     * animation is in flight.
+     * Used by {@link Scene} to keep rendering continuously while an animation
+     * is in flight — both in `onDemand` render mode, and to hold off the
+     * `always`-mode idle auto-throttle. Without checking `_drivers` here, a
+     * property driver becomes invisible to that throttle: `markDirty()` called
+     * from inside `update()`/`tickDrivers()` is wiped by the loop's own
+     * `dirty = false` at the end of that same tick, so once the throttle
+     * engages an in-flight spring/tween only advances one animation-frame per
+     * external `markDirty()` trigger instead of every render frame.
      *
-     * @returns `true` if at least one animation remains.
+     * @returns `true` if at least one animation or property driver remains.
      */
     hasPendingAnimations(): boolean;
     abstract isPointInside(globalX: number, globalY: number): boolean;
@@ -568,5 +440,3 @@ declare abstract class Entity {
      */
     abstract render(renderer: any): void;
 }
-
-export { type A11yAttributes as A, type Bounds as B, Entity as E, type IRenderer as I, type ListenerOptions as L, type Point as P, type VectoEvent as V, type BatchCircle as a, type BatchRect as b, VectoJSEvent as c };