@vectojs/core 0.1.0 → 0.2.1

package/dist/index.mjs

@@ -12,12 +12,17 @@ import {
   parseColorToRGBA
 } from "./chunk-2Y45S4JK.mjs";
 import {
+  Easing,
   Entity,
   MSDFFont,
   MSDFTextEntity,
   SVGEntity,
-  VectoJSEvent
-} from "./chunk-M2IZPGOL.mjs";
+  SpringDriver,
+  SpringPhysics,
+  TweenDriver,
+  VectoJSEvent,
+  isTweenConfig
+} from "./chunk-H3QIE77O.mjs";
 import {
   ArabicShaper,
   BidiResolver,
@@ -313,6 +318,8 @@ var Scene = class _Scene {
    */
   renderMode = "always";
   dirty = true;
+  /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
+  autoThrottle = true;
   /**
    * Frame-rate cap (power saving). `0` = uncapped (native refresh). When set,
    * the loop renders at most `maxFPS` times per second; animations still run,
@@ -323,6 +330,10 @@ var Scene = class _Scene {
   respectReducedMotion = true;
   /** Cached media-query list; `.matches` is read live each frame. */
   reducedMotionQuery = null;
+  /** True when the OS asks for reduced motion and we respect it. Read by the animation drivers. */
+  get prefersReducedMotion() {
+    return this.respectReducedMotion && !!this.reducedMotionQuery?.matches;
+  }
   /**
    * Throttle interval (ms) for the a11y/automation shadow sync. `0` = every
    * frame. See {@link SceneOptions.a11ySyncInterval}.
@@ -393,6 +404,7 @@ var Scene = class _Scene {
     const isTest = globalProcess && (globalProcess.env?.NODE_ENV === "test" || globalProcess.env?.VITEST === "true");
     this.maxFPS = options.maxFPS ?? (isTest ? 0 : 60);
     this.respectReducedMotion = options.respectReducedMotion ?? true;
+    this.autoThrottle = options.autoThrottle ?? true;
     this.particleBackend = options.particleBackend ?? "auto";
     this.a11ySyncInterval = options.a11ySyncInterval ?? 0;
     this.reducedMotionQuery = typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
@@ -1081,7 +1093,7 @@ var Scene = class _Scene {
   loop(time) {
     if (!this.isRunning) return;
     let cap = this.effectiveMaxFPS();
-    const isStatic = !this.dirty && !this.hasAnyPendingAnimation(this.root) && !this.hasAnyPendingAnimation(this.overlayRoot);
+    const isStatic = this.autoThrottle && !this.dirty && !this.hasAnyPendingAnimation(this.root) && !this.hasAnyPendingAnimation(this.overlayRoot);
     if (isStatic && this.renderMode === "always" && this.maxFPS > 0) {
       cap = Math.min(cap, 2);
     }
@@ -2064,37 +2076,6 @@ var SpatialHashGrid = class {
   }
 };
 
-// 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/tree/DOMPortalEntity.ts
 var DOMPortalEntity = class extends Entity {
   domElement;
@@ -2203,6 +2184,7 @@ export {
   CanvasRenderer,
   ComputeParticleEntity,
   DOMPortalEntity,
+  Easing,
   Entity,
   GridTextEntity,
   LayoutEngine,
@@ -2225,13 +2207,16 @@ export {
   Scene,
   SpatialHashGrid,
   SplineEntity,
+  SpringDriver,
   SpringPhysics,
   TextEntity,
+  TweenDriver,
   VectoJSEvent,
   WebGPUParticleSystemManager,
   computeLineSegments,
   createCanvasMeasurer,
   createWebGLPointRenderer,
+  isTweenConfig,
   loadSpline,
   parseColorToRGBA,
   polySegmentToBezier

package/dist/{layout.d.mts → layout/LayoutEngine.d.ts}

@@ -4,7 +4,7 @@
  * Each entry provides the glyph's pixel `width` at `baseSize`, and an `ast`
  * property holding the raw vector path data used by the renderer.
  */
-interface GlyphAtlas {
+export interface GlyphAtlas {
     [char: string]: {
         width: number;
         baseSize: number;
@@ -18,14 +18,14 @@ interface GlyphAtlas {
  * Implemented by {@link createCanvasMeasurer} (canvas `measureText`), but kept
  * abstract so callers can supply their own metrics source.
  */
-interface GlyphMeasurer {
+export interface GlyphMeasurer {
     measure(char: string, fontSize: number): number;
 }
 /**
  * Per-run inline style for rich text ({@link LayoutEngine.prepareRich}). All
  * fields are optional and inherited from the call's base style when omitted.
  */
-interface TextStyle {
+export interface TextStyle {
     /** Font size in px for this run; overrides the base size (affects width + line height). */
     fontSize?: number;
     /** Fill color, e.g. `'#38bdf8'`. */
@@ -38,14 +38,14 @@ interface TextStyle {
     href?: string;
 }
 /** A run of text sharing one {@link TextStyle}, the input unit of {@link LayoutEngine.prepareRich}. */
-interface StyledSpan {
+export interface StyledSpan {
     text: string;
     style?: TextStyle;
 }
 /**
  * A single positioned glyph produced by {@link LayoutEngine.layoutText}.
  */
-interface LayoutNode {
+export interface LayoutNode {
     char: string;
     x: number;
     y: number;
@@ -62,14 +62,14 @@ interface LayoutNode {
  * The complete output of a text layout pass — an ordered list of positioned
  * glyphs and the total bounding-box dimensions.
  */
-interface LayoutResult {
+export interface LayoutResult {
     nodes: LayoutNode[];
     totalWidth: number;
     totalHeight: number;
     fallbackToCanvas?: boolean;
 }
 /** A single measured grapheme (the "cold" half of the cold/hot split). */
-interface PreparedGlyph {
+export interface PreparedGlyph {
     char: string;
     /** Advance width at the prepared `fontSize`. */
     width: number;
@@ -81,7 +81,7 @@ interface PreparedGlyph {
     combining?: string[];
 }
 /** A measured word/segment, ready to be placed without re-measuring. */
-interface PreparedWord {
+export interface PreparedWord {
     glyphs: PreparedGlyph[];
     /** Sum of glyph advances — used for word-level wrap decisions. */
     width: number;
@@ -90,7 +90,7 @@ interface PreparedWord {
     isWhitespace: boolean;
 }
 /** A measured paragraph; `isEmpty` marks a blank line (forced newline). */
-interface PreparedParagraph {
+export interface PreparedParagraph {
     words: PreparedWord[];
     isEmpty: boolean;
     fallbackToCanvas?: boolean;
@@ -103,7 +103,7 @@ interface PreparedParagraph {
  * re-layouts ({@link LayoutEngine.layoutPrepared}) on resize / reposition,
  * avoiding the per-frame `Intl.Segmenter` + measurement cost.
  */
-interface PreparedText {
+export interface PreparedText {
     paragraphs: PreparedParagraph[];
     fontSize: number;
     fallbackToCanvas?: boolean;
@@ -113,14 +113,14 @@ interface PreparedText {
  * flow around — the v1 of text flow exclusion shapes. A left/right rect acts
  * like a CSS float; a centered rect splits the affected lines in two.
  */
-interface ExclusionRect {
+export interface ExclusionRect {
     x: number;
     y: number;
     width: number;
     height: number;
 }
 /** A free horizontal interval `[x0, x1)` available for text on one line. */
-interface LineSegment {
+export interface LineSegment {
     x0: number;
     x1: number;
 }
@@ -133,12 +133,12 @@ interface LineSegment {
  *
  * Time O(n log n) in the number of overlapping exclusions; space O(n).
  */
-declare function computeLineSegments(top: number, bottom: number, maxWidth: number, exclusions: ExclusionRect[]): LineSegment[];
+export declare function computeLineSegments(top: number, bottom: number, maxWidth: number, exclusions: ExclusionRect[]): LineSegment[];
 /**
  * VectoJS Global Layout Engine (Intl.Segmenter)
  * Advanced Typography Engine supporting CJK, Emoji, and Western Graphemes
  */
-declare class LayoutEngine {
+export declare class LayoutEngine {
     maxWidth: number;
     maxHeight: number;
     preserveLeadingSpaces: boolean;
@@ -243,7 +243,7 @@ declare class LayoutEngine {
  * Pre-allocated buffer for zero-GC layout results.
  * Reuse a single instance across frames by calling reset() before each layout pass.
  */
-declare class LayoutResultBuffer {
+export declare class LayoutResultBuffer {
     static readonly CAPACITY = 16384;
     /** X positions of each glyph. */
     xs: Float32Array;
@@ -262,58 +262,3 @@ declare class LayoutResultBuffer {
     /** Convert to the standard LayoutResult format (allocates — use sparingly). */
     toLayoutResult(): LayoutResult;
 }
-
-/**
- * Create a {@link GlyphMeasurer} backed by a single lazily-created offscreen
- * Canvas 2D context.
- *
- * Each grapheme is measured once at `baseSize` and cached; because canvas
- * `measureText` advance width is linear in font size, later queries at any
- * `fontSize` are derived by pure arithmetic (no re-measure). This gives the
- * {@link LayoutEngine} real per-glyph metrics for text that has no pre-baked
- * vector atlas, fixing the coarse `0.5em` line-breaking fallback.
- *
- * Returns `null` in DOM-free environments (SSR, workers without a canvas) so
- * callers stay portable and the engine keeps its `0.5em` fallback.
- *
- * @param fontFamily - CSS font family used for measurement; should match what
- *   the renderer actually draws (e.g. `TextEntity` falls back to `sans-serif`).
- * @param baseSize - Pixel size at which each glyph is measured and cached.
- * @returns A measurer, or `null` when no Canvas 2D context is available.
- */
-declare function createCanvasMeasurer(fontFamily?: string, baseSize?: number): GlyphMeasurer | null;
-
-interface LayoutWorkerResponse {
-    id: string;
-    seqId: number;
-    width: number;
-    height: number;
-    codePoints: Uint32Array;
-    xCoords: Float32Array;
-    yCoords: Float32Array;
-    packedStyles: Uint32Array;
-}
-
-declare class LayoutWorkerManager {
-    private static instance;
-    private worker;
-    private registeredFonts;
-    private pendingCallbacks;
-    private seqIdCounter;
-    private debounceTimers;
-    private constructor();
-    static getInstance(): LayoutWorkerManager;
-    queueLayout(entityId: string, text: string, options: {
-        fontId: string;
-        fontSize: number;
-        maxWidth: number;
-        maxHeight: number;
-        fontData?: any;
-        lineHeight?: number;
-        letterSpacing?: number;
-        callback: (res: LayoutWorkerResponse) => void;
-    }): void;
-    cancelLayout(entityId: string): void;
-}
-
-export { type ExclusionRect, type GlyphAtlas, type GlyphMeasurer, LayoutEngine, type LayoutNode, type LayoutResult, LayoutResultBuffer, LayoutWorkerManager, type LineSegment, type PreparedGlyph, type PreparedParagraph, type PreparedText, type PreparedWord, type StyledSpan, type TextStyle, computeLineSegments, createCanvasMeasurer };

package/dist/layout/LayoutWorker.d.ts

@@ -0,0 +1,23 @@
+import { MSDFFontData } from '../text/MSDFFont';
+export interface LayoutWorkerRequest {
+    id: string;
+    seqId: number;
+    text: string;
+    fontId: string;
+    fontData?: MSDFFontData;
+    maxWidth: number;
+    maxHeight: number;
+    fontSize: number;
+    lineHeight?: number;
+    letterSpacing?: number;
+}
+export interface LayoutWorkerResponse {
+    id: string;
+    seqId: number;
+    width: number;
+    height: number;
+    codePoints: Uint32Array;
+    xCoords: Float32Array;
+    yCoords: Float32Array;
+    packedStyles: Uint32Array;
+}

package/dist/layout/LayoutWorkerManager.d.ts

@@ -0,0 +1,22 @@
+import { LayoutWorkerResponse } from './LayoutWorker';
+export declare class LayoutWorkerManager {
+    private static instance;
+    private worker;
+    private registeredFonts;
+    private pendingCallbacks;
+    private seqIdCounter;
+    private debounceTimers;
+    private constructor();
+    static getInstance(): LayoutWorkerManager;
+    queueLayout(entityId: string, text: string, options: {
+        fontId: string;
+        fontSize: number;
+        maxWidth: number;
+        maxHeight: number;
+        fontData?: any;
+        lineHeight?: number;
+        letterSpacing?: number;
+        callback: (res: LayoutWorkerResponse) => void;
+    }): void;
+    cancelLayout(entityId: string): void;
+}

package/dist/layout/LayoutWorkerSource.d.ts

@@ -0,0 +1 @@
+export declare const WORKER_SOURCE_STRING = "\"use strict\";(()=>{var b=new Map;self.onmessage=x=>{let{id:S,seqId:k,text:A,fontId:i,fontData:c,maxWidth:d,maxHeight:H,fontSize:o,lineHeight:F,letterSpacing:C}=x.data;c&&b.set(i,c);let n=b.get(i);if(!n)return;let f=[],u=[],y=[],l=[],e=0,r=0,h=n.metrics?.ascender??.8,D=n.metrics?.descender??-.2,m=F??o*(h-D),p=Array.from(A);for(let s=0;s<p.length;s++){let a=p[s].codePointAt(0),g=(n.glyphs?.find(w=>w.unicode===a)?.advance??1)*o;e+g>d&&a===32&&(e=0,r++),f.push(a),u.push(e);let M=r*m+h*o;y.push(M),l.push(-256),e+=g+(C??0)}let t={id:S,seqId:k,width:Math.min(e,d),height:(r+1)*m,codePoints:new Uint32Array(f),xCoords:new Float32Array(u),yCoords:new Float32Array(y),packedStyles:new Uint32Array(l)};self.postMessage(t,[t.codePoints.buffer,t.xCoords.buffer,t.yCoords.buffer,t.packedStyles.buffer])};})();\n";

package/dist/layout/index.d.ts

@@ -0,0 +1,3 @@
+export * from './LayoutEngine';
+export * from './LayoutWorkerManager';
+export * from './measure';

package/dist/layout/measure.d.ts

@@ -0,0 +1,20 @@
+import type { GlyphMeasurer } from './LayoutEngine';
+/**
+ * Create a {@link GlyphMeasurer} backed by a single lazily-created offscreen
+ * Canvas 2D context.
+ *
+ * Each grapheme is measured once at `baseSize` and cached; because canvas
+ * `measureText` advance width is linear in font size, later queries at any
+ * `fontSize` are derived by pure arithmetic (no re-measure). This gives the
+ * {@link LayoutEngine} real per-glyph metrics for text that has no pre-baked
+ * vector atlas, fixing the coarse `0.5em` line-breaking fallback.
+ *
+ * Returns `null` in DOM-free environments (SSR, workers without a canvas) so
+ * callers stay portable and the engine keeps its `0.5em` fallback.
+ *
+ * @param fontFamily - CSS font family used for measurement; should match what
+ *   the renderer actually draws (e.g. `TextEntity` falls back to `sans-serif`).
+ * @param baseSize - Pixel size at which each glyph is measured and cached.
+ * @returns A measurer, or `null` when no Canvas 2D context is available.
+ */
+export declare function createCanvasMeasurer(fontFamily?: string, baseSize?: number): GlyphMeasurer | null;

package/dist/math/SpatialHashGrid.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Fixed-cell Spatial Hash Grid for O(1) average-case AABB neighbor queries.
+ * Insert entities each frame, then query by AABB to find nearby entity IDs.
+ */
+export declare class SpatialHashGrid {
+    private cellSize;
+    private grid;
+    private entityCells;
+    constructor(cellSize?: number);
+    private hash;
+    private cellsForAABB;
+    /**
+     * Insert or update an entity's axis-aligned bounding box in the grid.
+     *
+     * If the entity is already registered its old cell memberships are removed
+     * before the new ones are computed, so this method is safe to call every
+     * frame.
+     *
+     * @param id - Unique string identifier for the entity.
+     * @param x - Left edge of the AABB in world space.
+     * @param y - Top edge of the AABB in world space.
+     * @param w - Width of the AABB.
+     * @param h - Height of the AABB.
+     */
+    insert(id: string, x: number, y: number, w: number, h: number): void;
+    /**
+     * Remove an entity from all grid cells it currently occupies.
+     *
+     * Silently does nothing if the entity is not registered.
+     *
+     * @param id - Unique string identifier of the entity to remove.
+     */
+    remove(id: string): void;
+    /**
+     * Return all entity IDs whose grid cells overlap the given AABB.
+     *
+     * Time complexity: O(k) where k is the number of cells the query AABB spans
+     * plus the number of results — O(1) average for small, similarly-sized entities.
+     *
+     * @param x - Left edge of the query AABB.
+     * @param y - Top edge of the query AABB.
+     * @param w - Width of the query AABB.
+     * @param h - Height of the query AABB.
+     * @returns A `Set` of entity ID strings whose cells intersect the query region.
+     */
+    query(x: number, y: number, w: number, h: number): Set<string>;
+    /**
+     * Clear all cells and entity registrations, resetting the grid to an empty state.
+     *
+     * Call once per frame before re-inserting all dynamic entities.
+     */
+    clear(): void;
+}

package/dist/math/SpringPhysics.d.ts

@@ -0,0 +1,13 @@
+export declare class SpringPhysics {
+    value: number;
+    target: number;
+    velocity: number;
+    stiffness: number;
+    damping: number;
+    mass: number;
+    private readonly valEpsilon;
+    private readonly velEpsilon;
+    constructor(initial: number);
+    update(dt: number): void;
+    isAtRest(): boolean;
+}

package/dist/renderer/CanvasRenderer.d.ts

@@ -0,0 +1,81 @@
+import { IRenderer } from './IRenderer';
+export declare class CanvasRenderer implements IRenderer {
+    private ctx;
+    private width;
+    private height;
+    /**
+     * Max circles per batched `fill()`. A single Canvas 2D `fill()` over a path is
+     * superlinear in sub-path count, so an unbounded batch is *slower* than many
+     * small fills at high entity counts. Capping bounds each fill's path
+     * complexity while still amortizing per-draw overhead. Tuned via the benchmark.
+     */
+    static readonly MAX_BATCH = 64;
+    private batchActive;
+    private batchColor;
+    private batchAlpha;
+    private batchCount;
+    constructor(canvas: HTMLCanvasElement);
+    /**
+     * Expose the underlying `CanvasRenderingContext2D` for operations not
+     * covered by the {@link IRenderer} interface.
+     *
+     * @returns The raw 2D rendering context.
+     */
+    getContext(): CanvasRenderingContext2D;
+    /**
+     * Resize the backing canvas buffer and re-apply DPR scaling.
+     *
+     * Called automatically by {@link Scene} on `window.resize` events.
+     *
+     * @param width - New logical width in CSS pixels.
+     * @param height - New logical height in CSS pixels.
+     */
+    resize(width: number, height: number): void;
+    /** @inheritdoc */
+    clear(): void;
+    /** @inheritdoc */
+    save(): void;
+    /** @inheritdoc */
+    restore(): void;
+    /** @inheritdoc */
+    translate(x: number, y: number): void;
+    /** @inheritdoc */
+    scale(x: number, y: number): void;
+    /** @inheritdoc */
+    rotate(angle: number): void;
+    /** @inheritdoc */
+    setGlobalAlpha(alpha: number): void;
+    /** @inheritdoc */
+    clip(x: number, y: number, width: number, height: number): void;
+    /** @inheritdoc */
+    beginPath(): void;
+    /** @inheritdoc */
+    moveTo(x: number, y: number): void;
+    /** @inheritdoc */
+    lineTo(x: number, y: number): void;
+    /** @inheritdoc */
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    /** @inheritdoc */
+    closePath(): void;
+    /** @inheritdoc */
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    /** @inheritdoc */
+    roundRect(x: number, y: number, width: number, height: number, radii: number | number[]): void;
+    /** @inheritdoc */
+    drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
+    /** @inheritdoc */
+    fillCircle(cx: number, cy: number, radius: number, color: string, alpha?: number): void;
+    /** @inheritdoc */
+    flush(): void;
+    /** @inheritdoc */
+    fill(color: string | any): void;
+    /** @inheritdoc */
+    stroke(color: string | any, lineWidth?: number): void;
+    /** @inheritdoc */
+    fillText(text: string, x: number, y: number, font: string, color: string | any): void;
+    /** @inheritdoc */
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number, colorStops: {
+        stop: number;
+        color: string;
+    }[]): any;
+}