@vectojs/core 0.1.0 → 0.2.1

package/dist/animation/drivers.d.ts

@@ -0,0 +1,48 @@
+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;
+}

package/dist/animation/easing.d.ts

@@ -0,0 +1,16 @@
+/** An easing function: maps normalized time t in [0,1] to eased progress. */
+export type EasingFn = (t: number) => number;
+/** Curated easing set. Add sparingly — every entry must map f(0)=0, f(1)=1. */
+export declare const Easing: {
+    linear: (t: number) => number;
+    easeInQuad: (t: number) => number;
+    easeOutQuad: (t: number) => number;
+    easeInOutQuad: (t: number) => number;
+    easeInCubic: (t: number) => number;
+    easeOutCubic: (t: number) => number;
+    easeInOutCubic: (t: number) => number;
+    easeOutBack: (t: number) => number;
+    easeInOutBack: (t: number) => number;
+};
+/** Name of a built-in easing curve. */
+export type EasingName = keyof typeof Easing;

package/dist/{chunk-M2IZPGOL.mjs → chunk-H3QIE77O.mjs}

@@ -2,6 +2,120 @@ import {
   LayoutWorkerManager
 } from "./chunk-YA2J5ZH7.mjs";
 
+// src/math/SpringPhysics.ts
+var SpringPhysics = class {
+  value;
+  target;
+  velocity = 0;
+  stiffness = 180;
+  damping = 12;
+  mass = 1;
+  valEpsilon = 5e-3;
+  velEpsilon = 5e-3;
+  constructor(initial) {
+    this.value = initial;
+    this.target = initial;
+  }
+  update(dt) {
+    if (this.isAtRest()) {
+      this.value = this.target;
+      this.velocity = 0;
+      return;
+    }
+    const forceSpring = -this.stiffness * (this.value - this.target);
+    const forceDamping = -this.damping * this.velocity;
+    const acceleration = (forceSpring + forceDamping) / this.mass;
+    this.velocity += acceleration * dt;
+    this.value += this.velocity * dt;
+  }
+  isAtRest() {
+    return Math.abs(this.value - this.target) < this.valEpsilon && Math.abs(this.velocity) < this.velEpsilon;
+  }
+};
+
+// src/animation/easing.ts
+var c1 = 1.70158;
+var c3 = c1 + 1;
+var Easing = {
+  linear: (t) => t,
+  easeInQuad: (t) => t * t,
+  easeOutQuad: (t) => t * (2 - t),
+  easeInOutQuad: (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
+  easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+  easeOutBack: (t) => 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2),
+  easeInOutBack: (t) => {
+    const c2 = c1 * 1.525;
+    return t < 0.5 ? Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2) / 2 : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
+  }
+};
+
+// src/animation/drivers.ts
+function isTweenConfig(c) {
+  return typeof c === "object" && "duration" in c;
+}
+var TweenDriver = class {
+  value;
+  from;
+  to;
+  elapsed = 0;
+  duration;
+  delay;
+  ease;
+  constructor(from, to, cfg) {
+    this.value = from;
+    this.from = from;
+    this.to = to;
+    this.duration = Math.max(1, cfg.duration);
+    this.delay = cfg.delay ?? 0;
+    this.ease = typeof cfg.easing === "function" ? cfg.easing : Easing[cfg.easing ?? "easeOutQuad"];
+  }
+  get target() {
+    return this.to;
+  }
+  retarget(to) {
+    this.from = this.value;
+    this.to = to;
+    this.elapsed = 0;
+  }
+  tick(dtMs) {
+    this.elapsed += dtMs;
+    const active = this.elapsed - this.delay;
+    if (active <= 0) return;
+    const p = Math.min(active / this.duration, 1);
+    this.value = this.from + (this.to - this.from) * this.ease(p);
+  }
+  isDone() {
+    return this.elapsed - this.delay >= this.duration;
+  }
+};
+var SpringDriver = class {
+  spring;
+  constructor(from, to, cfg) {
+    this.spring = new SpringPhysics(from);
+    if (cfg.stiffness !== void 0) this.spring.stiffness = cfg.stiffness;
+    if (cfg.damping !== void 0) this.spring.damping = cfg.damping;
+    if (cfg.mass !== void 0) this.spring.mass = cfg.mass;
+    this.spring.target = to;
+  }
+  get value() {
+    return this.spring.value;
+  }
+  get target() {
+    return this.spring.target;
+  }
+  retarget(to) {
+    this.spring.target = to;
+  }
+  tick(dtMs) {
+    this.spring.update(dtMs / 1e3);
+  }
+  isDone() {
+    return this.spring.isAtRest();
+  }
+};
+
 // src/tree/Entity.ts
 var VectoJSEvent = class {
   /** The event name. */
@@ -80,12 +194,60 @@ var Entity = class {
     if (this._scene) return this._scene;
     return this.parent ? this.parent.scene : null;
   }
-  x = 0;
-  y = 0;
-  scaleX = 1;
-  scaleY = 1;
-  rotation = 0;
-  opacity = 1;
+  _x = 0;
+  _y = 0;
+  _scaleX = 1;
+  _scaleY = 1;
+  _rotation = 0;
+  _opacity = 1;
+  // Fast-path flag: false for the overwhelming majority of entities (incl. the
+  // Danmaku hot loop), so a bare `entity.x = v` is one boolean check + field write.
+  _hasTransitions = false;
+  _transitions = null;
+  _drivers = /* @__PURE__ */ new Map();
+  _mounted = false;
+  get x() {
+    return this._x;
+  }
+  set x(v) {
+    if (this._hasTransitions) this._animateProp("x", v);
+    else this._x = v;
+  }
+  get y() {
+    return this._y;
+  }
+  set y(v) {
+    if (this._hasTransitions) this._animateProp("y", v);
+    else this._y = v;
+  }
+  get scaleX() {
+    return this._scaleX;
+  }
+  set scaleX(v) {
+    if (this._hasTransitions) this._animateProp("scaleX", v);
+    else this._scaleX = v;
+  }
+  get scaleY() {
+    return this._scaleY;
+  }
+  set scaleY(v) {
+    if (this._hasTransitions) this._animateProp("scaleY", v);
+    else this._scaleY = v;
+  }
+  get rotation() {
+    return this._rotation;
+  }
+  set rotation(v) {
+    if (this._hasTransitions) this._animateProp("rotation", v);
+    else this._rotation = v;
+  }
+  get opacity() {
+    return this._opacity;
+  }
+  set opacity(v) {
+    if (this._hasTransitions) this._animateProp("opacity", v);
+    else this._opacity = v;
+  }
   isDOMPortal = false;
   _interactive = false;
   get interactive() {
@@ -140,9 +302,20 @@ var Entity = class {
     if (s) {
       s.a11yNeedsReorder = true;
       s.markDirty();
+      child._notifyMounted();
     }
     return this;
   }
+  /** Called once when this entity becomes attached to a live Scene. Override to react. */
+  onMounted() {
+  }
+  /** Fire onMounted for this node and its descendants, guarded against double-fire. */
+  _notifyMounted() {
+    if (this._mounted) return;
+    this._mounted = true;
+    this.onMounted();
+    for (const c of this.children) c._notifyMounted();
+  }
   /**
    * Remove a child entity from this node.
    *
@@ -195,6 +368,123 @@ var Entity = class {
     });
     return this;
   }
+  /** Write a driver-computed value to a backing field without re-triggering the setter. */
+  _applyAnimated(prop, v) {
+    switch (prop) {
+      case "x":
+        this._x = v;
+        break;
+      case "y":
+        this._y = v;
+        break;
+      case "scaleX":
+        this._scaleX = v;
+        break;
+      case "scaleY":
+        this._scaleY = v;
+        break;
+      case "rotation":
+        this._rotation = v;
+        break;
+      case "opacity":
+        this._opacity = v;
+        break;
+    }
+  }
+  _currentOf(prop) {
+    switch (prop) {
+      case "x":
+        return this._x;
+      case "y":
+        return this._y;
+      case "scaleX":
+        return this._scaleX;
+      case "scaleY":
+        return this._scaleY;
+      case "rotation":
+        return this._rotation;
+      case "opacity":
+        return this._opacity;
+    }
+  }
+  /**
+   * 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`).
+   */
+  setImmediate(prop, v) {
+    this._drivers.delete(prop);
+    this._applyAnimated(prop, v);
+  }
+  _spawnDriver(prop, to, cfg) {
+    if (prop !== "opacity" && this.scene?.prefersReducedMotion) {
+      this._drivers.delete(prop);
+      this._applyAnimated(prop, to);
+      return;
+    }
+    const existing = this._drivers.get(prop);
+    if (existing) {
+      existing.retarget(to);
+      return;
+    }
+    const from = this._currentOf(prop);
+    const driver = isTweenConfig(cfg) ? new TweenDriver(from, to, cfg) : new SpringDriver(from, to, cfg === "spring" ? {} : cfg);
+    this._drivers.set(prop, driver);
+    this.scene?.markDirty();
+  }
+  /** Assignment path when a declarative transition is configured for `prop`. */
+  _animateProp(prop, to) {
+    const cfg = this._transitions?.get(prop);
+    if (!cfg) {
+      this._applyAnimated(prop, to);
+      return;
+    }
+    this._spawnDriver(prop, to, cfg);
+  }
+  /** Declare which properties animate, and how. Subsequent assignment animates them. */
+  setTransition(config) {
+    this._transitions ??= /* @__PURE__ */ new Map();
+    for (const [k, v] of Object.entries(config))
+      this._transitions.set(k, v);
+    this._hasTransitions = this._transitions.size > 0;
+    return this;
+  }
+  /** Imperative tween toward targets; resolves when all reach their end. */
+  animateTo(props, cfg) {
+    return this._driveTo(props, cfg);
+  }
+  /** Imperative spring toward targets; resolves when all reach rest. */
+  springTo(props, cfg = {}) {
+    return this._driveTo(props, cfg);
+  }
+  _driveTo(props, cfg) {
+    const entries = Object.entries(props);
+    return Promise.all(
+      entries.map(
+        (e) => new Promise((resolve) => {
+          this._spawnDriver(e[0], e[1], cfg);
+          const d = this._drivers.get(e[0]);
+          if (!d)
+            resolve();
+          else d.onDone = resolve;
+        })
+      )
+    ).then(() => void 0);
+  }
+  /** Advance active property drivers one frame. Call from update(). */
+  tickDrivers(dt) {
+    if (this._drivers.size === 0) return;
+    for (const [prop, driver] of this._drivers) {
+      driver.tick(dt);
+      if (driver.isDone()) {
+        this._applyAnimated(prop, driver.target);
+        driver.onDone?.();
+        this._drivers.delete(prop);
+      } else {
+        this._applyAnimated(prop, driver.value);
+      }
+    }
+    this.scene?.markDirty();
+  }
   /**
    * Advance the entity's internal state for one frame.
    *
@@ -204,7 +494,8 @@ var Entity = class {
    * @param dt - Elapsed time since the last frame in milliseconds.
    * @param time - Absolute timestamp from `performance.now()`.
    */
-  update(_dt, time) {
+  update(dt, time) {
+    this.tickDrivers(dt);
     if (this.animations.length > 0) {
       const anim = this.animations[0];
       if (anim.startTime === -1) {
@@ -438,15 +729,23 @@ var Entity = class {
     return 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() {
-    return this.animations.length > 0;
+    return this.animations.length > 0 || this._drivers.size > 0;
   }
 };
 
@@ -899,6 +1198,11 @@ var SVGEntity = class extends Entity {
 };
 
 export {
+  SpringPhysics,
+  Easing,
+  isTweenConfig,
+  TweenDriver,
+  SpringDriver,
   VectoJSEvent,
   Entity,
   MSDFFont,