@nmmty/lazycanvas 0.6.5 → 1.0.0-dev.3

package/ReadMe.md

@@ -1,4 +1,4 @@
-![Logo](./resources/logo.svg)
+![Logo](https://raw.githubusercontent.com/NMMTY/LazyCanvas/refs/heads/main/packages/lazycanvas/resources/logo.svg)
 
 [![npm version](https://badge.fury.io/js/%40nmmty%2Flazycanvas.svg)](https://www.npmjs.com/package/@nmmty/lazycanvas)
 [![downloads](https://img.shields.io/npm/dm/%40nmmty%2Flazycanvas.svg)](https://www.npmjs.com/package/@nmmty/lazycanvas)

package/biome.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": false,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "ignore": [
+      "node_modules/",
+      "dist/",
+      "biome.json",
+      ".biome/",
+      ".git/",
+      ".hg/",
+      ".svn/",
+      "public/",
+      "docs/",
+      "resources/"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": { "recommended": true }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  }
+}

package/dist/core/Interpolation.d.ts

@@ -0,0 +1,30 @@
+export type Interpolator<T> = (from: T, to: T, progress: number) => T;
+/**
+ * Linear interpolation for numbers
+ */
+export declare function lerpNumber(from: number, to: number, progress: number): number;
+/**
+ * Interpolate colors in RGB space
+ */
+export declare function lerpColorRGB(from: string, to: string, progress: number): string;
+/**
+ * Interpolate colors in HSL space (smoother for hue transitions)
+ */
+export declare function lerpColorHSL(from: string, to: string, progress: number): string;
+/**
+ * Interpolate 2D vectors/points
+ */
+export declare function lerpVector(from: {
+    x: number;
+    y: number;
+}, to: {
+    x: number;
+    y: number;
+}, progress: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Auto-detect interpolator based on value type
+ */
+export declare function getInterpolator<T>(from: T, to: T): Interpolator<T>;

package/dist/core/Interpolation.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lerpNumber = lerpNumber;
+exports.lerpColorRGB = lerpColorRGB;
+exports.lerpColorHSL = lerpColorHSL;
+exports.lerpVector = lerpVector;
+exports.getInterpolator = getInterpolator;
+/**
+ * Linear interpolation for numbers
+ */
+function lerpNumber(from, to, progress) {
+    return from + (to - from) * progress;
+}
+/**
+ * Parse color string to RGBA components
+ */
+function parseColor(color) {
+    // Handle hex colors
+    if (color.startsWith("#")) {
+        const hex = color.slice(1);
+        let r, g, b, a = 1;
+        if (hex.length === 3 || hex.length === 4) {
+            r = parseInt(hex[0] + hex[0], 16);
+            g = parseInt(hex[1] + hex[1], 16);
+            b = parseInt(hex[2] + hex[2], 16);
+            a = hex.length === 4 ? parseInt(hex[3] + hex[3], 16) / 255 : 1;
+        }
+        else if (hex.length === 6 || hex.length === 8) {
+            r = parseInt(hex.slice(0, 2), 16);
+            g = parseInt(hex.slice(2, 4), 16);
+            b = parseInt(hex.slice(4, 6), 16);
+            a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1;
+        }
+        else {
+            return null;
+        }
+        return { r, g, b, a };
+    }
+    // Handle rgb/rgba
+    const rgbaMatch = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+    if (rgbaMatch) {
+        return {
+            r: parseInt(rgbaMatch[1]),
+            g: parseInt(rgbaMatch[2]),
+            b: parseInt(rgbaMatch[3]),
+            a: rgbaMatch[4] ? parseFloat(rgbaMatch[4]) : 1,
+        };
+    }
+    // Handle hsl/hsla
+    const hslaMatch = color.match(/hsla?\((\d+),\s*(\d+)%,\s*(\d+)%(?:,\s*([\d.]+))?\)/);
+    if (hslaMatch) {
+        const h = parseInt(hslaMatch[1]) / 360;
+        const s = parseInt(hslaMatch[2]) / 100;
+        const l = parseInt(hslaMatch[3]) / 100;
+        const a = hslaMatch[4] ? parseFloat(hslaMatch[4]) : 1;
+        // Convert HSL to RGB
+        const { r, g, b } = hslToRgb(h, s, l);
+        return { r, g, b, a };
+    }
+    return null;
+}
+/**
+ * Convert HSL to RGB
+ */
+function hslToRgb(h, s, l) {
+    let r, g, b;
+    if (s === 0) {
+        r = g = b = l;
+    }
+    else {
+        const hue2rgb = (p, q, t) => {
+            if (t < 0)
+                t += 1;
+            if (t > 1)
+                t -= 1;
+            if (t < 1 / 6)
+                return p + (q - p) * 6 * t;
+            if (t < 1 / 2)
+                return q;
+            if (t < 2 / 3)
+                return p + (q - p) * (2 / 3 - t) * 6;
+            return p;
+        };
+        const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+        const p = 2 * l - q;
+        r = hue2rgb(p, q, h + 1 / 3);
+        g = hue2rgb(p, q, h);
+        b = hue2rgb(p, q, h - 1 / 3);
+    }
+    return {
+        r: Math.round(r * 255),
+        g: Math.round(g * 255),
+        b: Math.round(b * 255),
+    };
+}
+/**
+ * Convert RGB to HSL
+ */
+function rgbToHsl(r, g, b) {
+    r /= 255;
+    g /= 255;
+    b /= 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    let h = 0, s = 0;
+    const l = (max + min) / 2;
+    if (max !== min) {
+        const d = max - min;
+        s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+        switch (max) {
+            case r:
+                h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+                break;
+            case g:
+                h = ((b - r) / d + 2) / 6;
+                break;
+            case b:
+                h = ((r - g) / d + 4) / 6;
+                break;
+        }
+    }
+    return { h, s, l };
+}
+/**
+ * Interpolate colors in RGB space
+ */
+function lerpColorRGB(from, to, progress) {
+    const fromColor = parseColor(from);
+    const toColor = parseColor(to);
+    if (!fromColor || !toColor) {
+        return progress < 0.5 ? from : to;
+    }
+    const r = Math.round(lerpNumber(fromColor.r, toColor.r, progress));
+    const g = Math.round(lerpNumber(fromColor.g, toColor.g, progress));
+    const b = Math.round(lerpNumber(fromColor.b, toColor.b, progress));
+    const a = lerpNumber(fromColor.a, toColor.a, progress);
+    return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+/**
+ * Interpolate colors in HSL space (smoother for hue transitions)
+ */
+function lerpColorHSL(from, to, progress) {
+    const fromColor = parseColor(from);
+    const toColor = parseColor(to);
+    if (!fromColor || !toColor) {
+        return progress < 0.5 ? from : to;
+    }
+    const fromHSL = rgbToHsl(fromColor.r, fromColor.g, fromColor.b);
+    const toHSL = rgbToHsl(toColor.r, toColor.g, toColor.b);
+    // Interpolate hue with shortest path
+    let deltaH = toHSL.h - fromHSL.h;
+    if (deltaH > 0.5)
+        deltaH -= 1;
+    if (deltaH < -0.5)
+        deltaH += 1;
+    const h = fromHSL.h + deltaH * progress;
+    const s = lerpNumber(fromHSL.s, toHSL.s, progress);
+    const l = lerpNumber(fromHSL.l, toHSL.l, progress);
+    const a = lerpNumber(fromColor.a, toColor.a, progress);
+    const { r, g, b } = hslToRgb(h, s, l);
+    return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+/**
+ * Interpolate 2D vectors/points
+ */
+function lerpVector(from, to, progress) {
+    return {
+        x: lerpNumber(from.x, to.x, progress),
+        y: lerpNumber(from.y, to.y, progress),
+    };
+}
+/**
+ * Auto-detect interpolator based on value type
+ */
+function getInterpolator(from, to) {
+    // Number
+    if (typeof from === "number" && typeof to === "number") {
+        return lerpNumber;
+    }
+    // String (assume color)
+    if (typeof from === "string" && typeof to === "string") {
+        // Try to detect if it's a color
+        if (from.startsWith("#") || from.startsWith("rgb") || from.startsWith("hsl")) {
+            return lerpColorRGB;
+        }
+    }
+    // Vector/Point
+    if (typeof from === "object" &&
+        from !== null &&
+        typeof to === "object" &&
+        to !== null &&
+        "x" in from &&
+        "y" in from &&
+        "x" in to &&
+        "y" in to) {
+        return lerpVector;
+    }
+    // Default: snap to end value
+    return ((from, to, progress) => (progress < 1 ? from : to));
+}

package/dist/core/Scene.d.ts

@@ -0,0 +1,96 @@
+import { Div } from "../structures/components";
+import { AnyLayer } from "../types";
+import { ThreadGenerator, Signal } from "./Signal";
+import { LazyCanvas } from "../structures/LazyCanvas";
+import { Canvas } from "@napi-rs/canvas";
+/**
+ * Scene class - manages canvas, context, layers, and animation timeline
+ */
+export declare class Scene {
+    readonly lazyCanvas: LazyCanvas;
+    private allLayers;
+    private scheduler;
+    private lastFrameTime;
+    /**
+     * Create a new Scene
+     * @param width - Canvas width in pixels
+     * @param height - Canvas height in pixels
+     */
+    constructor(width: number, height: number);
+    /**
+     * Load a layer tree created via JSX
+     * Registers all layers with IDs into the manager
+     * @param tree - Root layer or group
+     */
+    load(tree: AnyLayer | Div): void;
+    /**
+     * Render a single frame at the given time
+     * @param time - Time in seconds
+     */
+    renderFrame(time: number): Promise<void>;
+    renderFirstFrame(): Promise<Canvas>;
+    /**
+     * Get current frame as ImageData (Uint8ClampedArray)
+     * Much faster than encoding to PNG
+     */
+    getImageData(): Uint8ClampedArray;
+    /**
+     * Get canvas width
+     */
+    get width(): number;
+    /**
+     * Get canvas height
+     */
+    get height(): number;
+    /**
+     * Update state for all layers that have signals
+     * @param time - Current time in seconds
+     */
+    private updateAllStates;
+    /**
+     * Draw a layer or group
+     * @param layer - Layer to draw
+     */
+    private drawLayer;
+    /**
+     * Render multiple frames and return as animation
+     * @param startTime - Start time in seconds
+     * @param endTime - End time in seconds
+     * @param fps - Frames per second (default: 30)
+     * @returns Array of PNG buffers for each frame
+     */
+    renderAnimation(startTime: number, endTime: number, fps?: number): Promise<Buffer[]>;
+    /**
+     * Render multiple frames and return as ImageData array (much faster)
+     * @param startTime - Start time in seconds
+     * @param endTime - End time in seconds
+     * @param fps - Frames per second (default: 30)
+     * @returns Array of Uint8ClampedArray for each frame
+     */
+    renderAnimationData(startTime: number, endTime: number, fps?: number): Promise<Uint8ClampedArray[]>;
+    /**
+     * Get a layer by ID from the manager
+     * @param id - Layer ID
+     * @returns Layer or undefined
+     */
+    getLayer(id: string): AnyLayer | Div | undefined;
+    /**
+     * Add animation generator to scheduler
+     * @param generator - Animation generator to run
+     */
+    addAnimation(generator: ThreadGenerator): void;
+    /**
+     * Play animation on a signal
+     * @param signal - Signal to animate
+     * @param generator - Animation generator
+     */
+    playAnimation<T>(signal: Signal<T>, generator: ThreadGenerator): void;
+    /**
+     * Clear all animations
+     */
+    clearAnimations(): void;
+    /**
+     * Reset scene timeline
+     */
+    resetTimeline(): void;
+}

package/dist/core/Scene.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scene = void 0;
+const ThreadScheduler_1 = require("./ThreadScheduler");
+const LazyCanvas_1 = require("../structures/LazyCanvas");
+/**
+ * Scene class - manages canvas, context, layers, and animation timeline
+ */
+class Scene {
+    /**
+     * Create a new Scene
+     * @param width - Canvas width in pixels
+     * @param height - Canvas height in pixels
+     */
+    constructor(width, height) {
+        this.allLayers = [];
+        this.scheduler = new ThreadScheduler_1.ThreadScheduler();
+        this.lastFrameTime = 0;
+        this.lazyCanvas = new LazyCanvas_1.LazyCanvas().create(width, height);
+    }
+    /**
+     * Load a layer tree created via JSX
+     * Registers all layers with IDs into the manager
+     * @param tree - Root layer or group
+     */
+    load(tree) {
+        this.lazyCanvas.manager.layers.add(tree);
+        this.allLayers = this.lazyCanvas.manager.layers.toArray();
+    }
+    /**
+     * Render a single frame at the given time
+     * @param time - Time in seconds
+     */
+    async renderFrame(time) {
+        if (this.lazyCanvas.manager.layers.size() === 0) {
+            throw new Error("Scene: No root layer loaded. Call scene.load(tree) first.");
+        }
+        // 1. Update scheduler with current time
+        this.scheduler.update(time);
+        // 2. Clear canvas
+        this.lazyCanvas.ctx.clearRect(0, 0, this.lazyCanvas.canvas.width, this.lazyCanvas.canvas.height);
+        // 3. PHASE 1: Update all layer states from signals
+        this.updateAllStates(time);
+        // 4. PHASE 2: Draw the layer tree
+        await this.drawLayer(this.lazyCanvas.manager.layers.toArray()[0]);
+        this.lastFrameTime = time;
+    }
+    async renderFirstFrame() {
+        await this.renderFrame(0);
+        return this.lazyCanvas.canvas;
+    }
+    /**
+     * Get current frame as ImageData (Uint8ClampedArray)
+     * Much faster than encoding to PNG
+     */
+    getImageData() {
+        const imageData = this.lazyCanvas.ctx.getImageData(0, 0, this.width, this.height);
+        return imageData.data;
+    }
+    /**
+     * Get canvas width
+     */
+    get width() {
+        return this.lazyCanvas.canvas.width;
+    }
+    /**
+     * Get canvas height
+     */
+    get height() {
+        return this.lazyCanvas.canvas.height;
+    }
+    /**
+     * Update state for all layers that have signals
+     * @param time - Current time in seconds
+     */
+    updateAllStates(time) {
+        for (const layer of this.allLayers) {
+            // Check if layer has updateState method (added by BaseLayer)
+            if ("updateState" in layer && typeof layer.updateState === "function") {
+                layer.updateState(time);
+            }
+        }
+    }
+    /**
+     * Draw a layer or group
+     * @param layer - Layer to draw
+     */
+    async drawLayer(layer) {
+        if (!layer.visible)
+            return;
+        // Set global composite operation if present
+        if ("props" in layer && layer.props?.globalComposite) {
+            this.lazyCanvas.ctx.globalCompositeOperation = layer.props.globalComposite;
+        }
+        // Draw the layer
+        if ("draw" in layer && typeof layer.draw === "function") {
+            await layer.draw(this.lazyCanvas.ctx, this.lazyCanvas.canvas, this.lazyCanvas.manager.layers, false);
+        }
+        // Reset shadow after drawing
+        this.lazyCanvas.ctx.shadowColor = "transparent";
+    }
+    /**
+     * Render multiple frames and return as animation
+     * @param startTime - Start time in seconds
+     * @param endTime - End time in seconds
+     * @param fps - Frames per second (default: 30)
+     * @returns Array of PNG buffers for each frame
+     */
+    async renderAnimation(startTime, endTime, fps = 30) {
+        const frames = [];
+        const frameDuration = 1 / fps;
+        for (let time = startTime; time <= endTime; time += frameDuration) {
+            await this.renderFrame(time);
+            frames.push(await this.lazyCanvas.canvas.encode("png"));
+        }
+        return frames;
+    }
+    /**
+     * Render multiple frames and return as ImageData array (much faster)
+     * @param startTime - Start time in seconds
+     * @param endTime - End time in seconds
+     * @param fps - Frames per second (default: 30)
+     * @returns Array of Uint8ClampedArray for each frame
+     */
+    async renderAnimationData(startTime, endTime, fps = 30) {
+        const frames = [];
+        const frameDuration = 1 / fps;
+        for (let time = startTime; time <= endTime; time += frameDuration) {
+            await this.renderFrame(time);
+            frames.push(this.getImageData());
+        }
+        return frames;
+    }
+    /**
+     * Get a layer by ID from the manager
+     * @param id - Layer ID
+     * @returns Layer or undefined
+     */
+    getLayer(id) {
+        return this.lazyCanvas.manager.layers.get(id, true);
+    }
+    /**
+     * Add animation generator to scheduler
+     * @param generator - Animation generator to run
+     */
+    addAnimation(generator) {
+        this.scheduler.add(generator);
+    }
+    /**
+     * Play animation on a signal
+     * @param signal - Signal to animate
+     * @param generator - Animation generator
+     */
+    playAnimation(signal, generator) {
+        signal.run(generator);
+        this.scheduler.add(generator);
+    }
+    /**
+     * Clear all animations
+     */
+    clearAnimations() {
+        this.scheduler.clear();
+    }
+    /**
+     * Reset scene timeline
+     */
+    resetTimeline() {
+        this.scheduler.reset();
+        this.lastFrameTime = 0;
+    }
+}
+exports.Scene = Scene;

package/dist/core/Signal.d.ts

@@ -0,0 +1,133 @@
+import { Interpolator } from "./Interpolation";
+/**
+ * Easing function type
+ */
+export type EasingFunction = (t: number) => number;
+/**
+ * Standard easing functions
+ */
+export declare const Easing: {
+    linear: (t: number) => number;
+    easeIn: (t: number) => number;
+    easeOut: (t: number) => number;
+    easeInOut: (t: number) => number;
+    easeInCubic: (t: number) => number;
+    easeOutCubic: (t: number) => number;
+    easeInOutCubic: (t: number) => number;
+    easeInQuart: (t: number) => number;
+    easeOutQuart: (t: number) => number;
+    easeInOutQuart: (t: number) => number;
+    easeInQuint: (t: number) => number;
+    easeOutQuint: (t: number) => number;
+    easeInOutQuint: (t: number) => number;
+    easeInSine: (t: number) => number;
+    easeOutSine: (t: number) => number;
+    easeInOutSine: (t: number) => number;
+    easeInExpo: (t: number) => number;
+    easeOutExpo: (t: number) => number;
+    easeInOutExpo: (t: number) => number;
+    easeInCirc: (t: number) => number;
+    easeOutCirc: (t: number) => number;
+    easeInOutCirc: (t: number) => number;
+    easeInBack: (t: number) => number;
+    easeOutBack: (t: number) => number;
+    easeInOutBack: (t: number) => number;
+    easeInElastic: (t: number) => number;
+    easeOutElastic: (t: number) => number;
+    easeInOutElastic: (t: number) => number;
+    easeInBounce: (t: number) => number;
+    easeOutBounce: (t: number) => number;
+    easeInOutBounce: (t: number) => number;
+};
+/**
+ * Thread generator type - the core of animation system
+ */
+export type ThreadGenerator = Generator<void | number, void, number | void>;
+/**
+ * Tween configuration
+ */
+export interface TweenConfig<T> {
+    to: T;
+    duration: number;
+    easing?: EasingFunction;
+    interpolator?: Interpolator<T>;
+    colorSpace?: "rgb" | "hsl";
+}
+/**
+ * Signal options
+ */
+export interface SignalOptions<T> {
+    interpolator?: Interpolator<T>;
+    colorSpace?: "rgb" | "hsl";
+}
+/**
+ * Signal class - reactive value that can be animated
+ */
+export declare class Signal<T = number> {
+    private _value;
+    private _initialValue;
+    private _currentThread;
+    private _interpolator;
+    private _colorSpace;
+    constructor(initial: T, options?: SignalOptions<T>);
+    /**
+     * Get current value at specific time (backward compatibility)
+     */
+    get(time: number): T;
+    /**
+     * Get current value (sync)
+     */
+    value(): T;
+    /**
+     * Set value directly
+     */
+    set(value: T): void;
+    /**
+     * Reset to initial value
+     */
+    reset(): void;
+    /**
+     * Animate to a new value - returns a generator
+     */
+    to(value: T, duration: number, config?: Partial<TweenConfig<T>> & {
+        easing?: EasingFunction;
+    }): ThreadGenerator;
+    /**
+     * Wait for a duration without changing value
+     */
+    wait(duration: number): ThreadGenerator;
+    /**
+     * Run animation from generator
+     */
+    run(generator: ThreadGenerator): this;
+    /**
+     * Update signal (called by scheduler)
+     */
+    update(delta: number): boolean;
+    /**
+     * Check if signal has active animation
+     */
+    isAnimating(): boolean;
+    /**
+     * Internal: get interpolator for values
+     */
+    private _getInterpolator;
+}
+/**
+ * Create a new signal
+ */
+export declare function createSignal<T = number>(initial: T, options?: SignalOptions<T>): Signal<T>;
+/**
+ * Type guard for signals
+ */
+export declare function isSignal<T>(value: any): value is Signal<T>;
+/**
+ * Unwrap signal or return value
+ */
+export declare function unwrap<T>(value: T | Signal<T>): T extends Signal<infer U> ? U : T;
+/**
+ * Reset multiple signals to their initial values
+ */
+export declare function resetSignals(...signals: Signal<any>[]): void;
+export type SignalValue<T> = T | Signal<T>;
+export default Signal;