@mulsense/xnew 0.6.8 → 0.7.0

package/README.md

@@ -13,7 +13,7 @@ providing a flexible architecture well-suited for applications with dynamic scen
 ### Via CDN
 Include the following script in your HTML file:
 ```html
-<script src="https://unpkg.com/@mulsense/xnew@0.6.x/dist/xnew.js"></script>
+<script src="https://unpkg.com/@mulsense/xnew@0.7.x/dist/xnew.js"></script>
 ```
 
 ### Via CDN (ESM)
@@ -22,7 +22,7 @@ Use the ES module version with an import map:
 <script type="importmap">
 {
     "imports": {
-        "@mulsense/xnew": "https://unpkg.com/@mulsense/xnew@0.6.x/dist/xnew.mjs"
+        "@mulsense/xnew": "https://unpkg.com/@mulsense/xnew@0.7.x/dist/xnew.mjs"
     }
 }
 </script>
@@ -37,7 +37,7 @@ import xnew from '@mulsense/xnew';
 ### Via npm
 Install `xnew` using npm:
 ```bash
-npm install @mulsense/xnew@0.6.x
+npm install @mulsense/xnew@0.7.x
 ```
 
 Then import it in your JavaScript file:

package/dist/addons/xpixi.js

@@ -29,6 +29,11 @@
         },
         nest(object) {
             xnew(Nest, { object });
+            xnew.extend(() => {
+                return {
+                    get pixiObject() { return object; }
+                };
+            });
             return object;
         },
         get renderer() {

package/dist/addons/xpixi.mjs

@@ -7,6 +7,11 @@ var xpixi = {
     },
     nest(object) {
         xnew(Nest, { object });
+        xnew.extend(() => {
+            return {
+                get pixiObject() { return object; }
+            };
+        });
         return object;
     },
     get renderer() {

package/dist/addons/xthree.js

@@ -29,6 +29,11 @@
         },
         nest(object) {
             xnew(Nest, { object });
+            xnew.extend(() => {
+                return {
+                    get threeObject() { return object; }
+                };
+            });
             return object;
         },
         get renderer() {
@@ -67,6 +72,17 @@
         parent.add(object);
         unit.on('finalize', () => {
             parent.remove(object);
+            object.traverse((obj) => {
+                if (obj.isMesh) {
+                    obj.geometry.dispose();
+                    if (Array.isArray(obj.material)) {
+                        obj.material.forEach((mat) => mat.dispose());
+                    }
+                    else {
+                        obj.material.dispose();
+                    }
+                }
+            });
         });
         return {
             get threeObject() { return object; },

package/dist/addons/xthree.mjs

@@ -7,6 +7,11 @@ var xthree = {
     },
     nest(object) {
         xnew(Nest, { object });
+        xnew.extend(() => {
+            return {
+                get threeObject() { return object; }
+            };
+        });
         return object;
     },
     get renderer() {
@@ -45,6 +50,17 @@ function Nest(unit, { object }) {
     parent.add(object);
     unit.on('finalize', () => {
         parent.remove(object);
+        object.traverse((obj) => {
+            if (obj.isMesh) {
+                obj.geometry.dispose();
+                if (Array.isArray(obj.material)) {
+                    obj.material.forEach((mat) => mat.dispose());
+                }
+                else {
+                    obj.material.dispose();
+                }
+            }
+        });
     });
     return {
         get threeObject() { return object; },

package/dist/xnew.d.ts

@@ -44,6 +44,7 @@ declare class Eventor {
 }
 
 type UnitElement = HTMLElement | SVGElement;
+type UnitArgs = [Component?: Function | string, props?: Object] | [target: UnitElement | string, Component?: Function | string, props?: Object];
 interface Context {
     previous: Context | null;
     key?: any;
@@ -55,39 +56,38 @@ interface Snapshot {
     element: UnitElement;
     Component: Function | null;
 }
-interface Internal {
-    parent: Unit | null;
-    ancestors: Unit[];
-    children: Unit[];
-    state: string;
-    tostart: boolean;
-    protected: boolean;
-    promises: UnitPromise[];
-    results: Record<string, any>;
-    defines: Record<string, any>;
-    systems: Record<string, {
-        listener: Function;
-        execute: Function;
-    }[]>;
-    currentElement: UnitElement;
-    currentContext: Context;
-    currentComponent: Function | null;
-    nestElements: {
-        element: UnitElement;
-        owned: boolean;
-    }[];
-    Components: Function[];
-    listeners: MapMap<string, Function, {
-        element: UnitElement;
-        Component: Function | null;
-        execute: Function;
-    }>;
-    eventor: Eventor;
-}
 declare class Unit {
     [key: string]: any;
-    _: Internal;
-    constructor(parent: Unit | null, target: UnitElement | string | null, Component?: Function | string | number, props?: Object);
+    _: {
+        parent: Unit | null;
+        ancestors: Unit[];
+        children: Unit[];
+        state: string;
+        tostart: boolean;
+        protected: boolean;
+        promises: UnitPromise[];
+        results: Record<string, any>;
+        defines: Record<string, any>;
+        systems: Record<string, {
+            listener: Function;
+            execute: Function;
+        }[]>;
+        currentElement: UnitElement;
+        currentContext: Context;
+        currentComponent: Function | null;
+        nestElements: {
+            element: UnitElement;
+            owned: boolean;
+        }[];
+        Components: Function[];
+        listeners: MapMap<string, Function, {
+            element: UnitElement;
+            Component: Function | null;
+            execute: Function;
+        }>;
+        eventor: Eventor;
+    };
+    constructor(parent: Unit | null, ...args: UnitArgs);
     get element(): UnitElement;
     start(): void;
     stop(): void;
@@ -120,49 +120,26 @@ declare class Unit {
     static emit(type: string, props?: object): void;
 }
 declare class UnitPromise {
-    promise: Promise<any>;
-    Component: Function | null;
-    constructor(promise: Promise<any>, Component: Function | null);
+    private promise;
+    constructor(promise: Promise<any>);
     then(callback: Function): UnitPromise;
     catch(callback: Function): UnitPromise;
     finally(callback: Function): UnitPromise;
+    static all(promises: UnitPromise[]): UnitPromise;
     private wrap;
 }
 declare class UnitTimer {
     private unit;
     private queue;
     clear(): void;
-    timeout(callback: Function, duration?: number): UnitTimer;
-    interval(callback: Function, duration?: number, iterations?: number): UnitTimer;
+    timeout(timeout: Function, duration?: number): UnitTimer;
+    interval(timeout: Function, duration?: number, iterations?: number): UnitTimer;
     transition(transition: Function, duration?: number, easing?: string): UnitTimer;
     private static execute;
     private static next;
     private static Component;
 }
 
-interface CreateUnit {
-    /**
-     * creates a new Unit component
-     * @param Component - component function
-     * @param props - properties for component function
-     * @returns a new Unit instance
-     * @example
-     * const unit = xnew(MyComponent, { data: 0 })
-     */
-    (Component?: Function | string, props?: Object): Unit;
-    /**
-     * creates a new Unit component
-     * @param target - HTMLElement | SVGElement, or HTML tag for new element
-     * @param Component - component function
-     * @param props - properties for component function
-     * @returns a new Unit instance
-     * @example
-     * const unit = xnew(element, MyComponent, { data: 0 })
-     * const unit = xnew('<div>', MyComponent, { data: 0 })
-     */
-    (target: HTMLElement | SVGElement | string, Component?: Function | string, props?: Object): Unit;
-}
-
 interface TransitionOptions {
     duration?: number;
     easing?: string;
@@ -230,12 +207,21 @@ declare function Panel(unit: Unit, { params }: PanelOptions): {
     separator(): void;
 };
 
+declare function Scene(unit: Unit): void;
 declare function Flow(unit: Unit): {
     get scene(): Unit | null;
     set scene(value: Unit);
-    next(Component: Function, props?: any): void;
+    next(Component: Function, props?: any, callback?: Function): void;
 };
 
+declare class XImage {
+    canvas: HTMLCanvasElement;
+    constructor(canvas: HTMLCanvasElement);
+    constructor(width: number, height: number);
+    clip(x: number, y: number, width: number, height: number): XImage;
+    download(filename: string): void;
+}
+
 type SynthesizerOptions = {
     oscillator: OscillatorOptions;
     amp: AmpOptions;
@@ -280,17 +266,22 @@ declare namespace xnew {
     type Unit = InstanceType<typeof Unit>;
     type UnitTimer = InstanceType<typeof UnitTimer>;
 }
-declare const xnew: CreateUnit & {
+declare const xnew: ((...args: UnitArgs) => Unit) & {
     nest(target: UnitElement | string): HTMLElement | SVGElement;
     extend(Component: Function, props?: Object): {
         [key: string]: any;
     };
+    append(parent: Unit, ...args: UnitArgs): void;
     context(key: any): any;
     promise(promise: Function | Promise<any> | Unit): UnitPromise;
     then(callback: Function): UnitPromise;
     catch(callback: Function): UnitPromise;
-    commit(object?: Record<string, any>): void;
     finally(callback: Function): UnitPromise;
+    resolvers(): {
+        resolve(): void;
+        reject(): void;
+    };
+    output(object?: Record<string, any>): void;
     scope(callback: any): any;
     find(Component: Function): Unit[];
     emit(type: string, ...args: any[]): void;
@@ -308,12 +299,16 @@ declare const xnew: CreateUnit & {
         Accordion: typeof Accordion;
         Popup: typeof Popup;
         Flow: typeof Flow;
+        Scene: typeof Scene;
     };
     audio: {
         load(path: string): UnitPromise;
         synthesizer(props: SynthesizerOptions): Synthesizer;
         volume: number;
     };
+    image: {
+        from(canvas: HTMLCanvasElement): XImage;
+    };
 };
 
 export { xnew as default };

package/dist/xnew.js

@@ -192,7 +192,7 @@
                     this.id = null;
                     this.time = { start: 0.0, processed: 0.0 };
                     (_b = (_a = this.options).transition) === null || _b === void 0 ? void 0 : _b.call(_a, 1.0);
-                    (_d = (_c = this.options).callback) === null || _d === void 0 ? void 0 : _d.call(_c);
+                    (_d = (_c = this.options).timeout) === null || _d === void 0 ? void 0 : _d.call(_c);
                     this.clear();
                 }, this.options.duration - this.time.processed);
                 this.time.start = Date.now();
@@ -519,16 +519,26 @@
         return { position };
     }
 
-    //----------------------------------------------------------------------------------------------------
-    // utils
-    //----------------------------------------------------------------------------------------------------
     const SYSTEM_EVENTS = ['start', 'update', 'render', 'stop', 'finalize'];
     //----------------------------------------------------------------------------------------------------
     // unit
     //----------------------------------------------------------------------------------------------------
     class Unit {
-        constructor(parent, target, Component, props) {
+        constructor(parent, ...args) {
             var _a;
+            let target;
+            let Component;
+            let props;
+            if (args[0] instanceof HTMLElement || args[0] instanceof SVGElement || typeof args[0] === 'string') {
+                target = args[0];
+                Component = args[1];
+                props = args[2];
+            }
+            else {
+                target = null;
+                Component = args[0];
+                props = args[1];
+            }
             const backup = Unit.currentUnit;
             Unit.currentUnit = this;
             parent === null || parent === void 0 ? void 0 : parent._.children.push(this);
@@ -650,7 +660,7 @@
                     return element;
                 }
                 else {
-                    throw new Error(`xnew.nest: invalid html string [${target}]`);
+                    throw new Error(`xnew.nest: invalid tag string [${target}]`);
                 }
             }
         }
@@ -692,7 +702,7 @@
                     Object.defineProperty(unit._.defines, key, wrapper);
                     Object.defineProperty(unit, key, wrapper);
                 });
-                return defines;
+                return Object.assign({}, unit._.defines);
             }
         }
         static start(unit) {
@@ -729,7 +739,7 @@
         static reset() {
             var _a;
             (_a = Unit.rootUnit) === null || _a === void 0 ? void 0 : _a.finalize();
-            Unit.currentUnit = Unit.rootUnit = new Unit(null, null);
+            Unit.currentUnit = Unit.rootUnit = new Unit(null);
             const ticker = new AnimationTicker(() => {
                 Unit.start(Unit.rootUnit);
                 Unit.update(Unit.rootUnit);
@@ -769,7 +779,7 @@
         }
         static getContext(unit, key) {
             for (let context = unit._.currentContext; context.previous !== null; context = context.previous) {
-                if (context.value === Unit.currentUnit && key === Unit.currentUnit._.currentComponent)
+                if (context.value === Unit.currentUnit)
                     continue;
                 if (context.key === key)
                     return context.value;
@@ -848,13 +858,13 @@
     // extensions
     //----------------------------------------------------------------------------------------------------
     class UnitPromise {
-        constructor(promise, Component) {
-            this.promise = promise;
-            this.Component = Component;
-        }
+        constructor(promise) { this.promise = promise; }
         then(callback) { return this.wrap('then', callback); }
         catch(callback) { return this.wrap('catch', callback); }
         finally(callback) { return this.wrap('finally', callback); }
+        static all(promises) {
+            return new UnitPromise(Promise.all(promises.map(p => p.promise)));
+        }
         wrap(key, callback) {
             const snapshot = Unit.snapshot(Unit.currentUnit);
             this.promise = this.promise[key]((...args) => Unit.scope(snapshot, callback, ...args));
@@ -872,11 +882,11 @@
             (_a = this.unit) === null || _a === void 0 ? void 0 : _a.finalize();
             this.unit = null;
         }
-        timeout(callback, duration = 0) {
-            return UnitTimer.execute(this, { callback, duration }, 1);
+        timeout(timeout, duration = 0) {
+            return UnitTimer.execute(this, { timeout, duration }, 1);
         }
-        interval(callback, duration = 0, iterations = 0) {
-            return UnitTimer.execute(this, { callback, duration }, iterations);
+        interval(timeout, duration = 0, iterations = 0) {
+            return UnitTimer.execute(this, { timeout, duration }, iterations);
         }
         transition(transition, duration = 0, easing) {
             return UnitTimer.execute(this, { transition, duration, easing }, 1);
@@ -884,7 +894,7 @@
         static execute(timer, options, iterations) {
             const props = { options, iterations, snapshot: Unit.snapshot(Unit.currentUnit) };
             if (timer.unit === null || timer.unit._.state === 'finalized') {
-                timer.unit = new Unit(Unit.currentUnit, null, UnitTimer.Component, props);
+                timer.unit = new Unit(Unit.currentUnit, UnitTimer.Component, props);
             }
             else if (timer.queue.length === 0) {
                 timer.queue.push(props);
@@ -897,18 +907,18 @@
         }
         static next(timer) {
             if (timer.queue.length > 0) {
-                timer.unit = new Unit(Unit.currentUnit, null, UnitTimer.Component, timer.queue.shift());
+                timer.unit = new Unit(Unit.currentUnit, UnitTimer.Component, timer.queue.shift());
                 timer.unit.on('finalize', () => UnitTimer.next(timer));
             }
         }
         static Component(unit, { options, iterations, snapshot }) {
             let counter = 0;
-            let timer = new Timer({ callback, transition, duration: options.duration, easing: options.easing });
-            function callback() {
-                if (options.callback)
-                    Unit.scope(snapshot, options.callback);
+            let timer = new Timer({ timeout, transition, duration: options.duration, easing: options.easing });
+            function timeout() {
+                if (options.timeout)
+                    Unit.scope(snapshot, options.timeout);
                 if (iterations <= 0 || counter < iterations - 1) {
-                    timer = new Timer({ callback, transition, duration: options.duration, easing: options.easing });
+                    timer = new Timer({ timeout, transition, duration: options.duration, easing: options.easing });
                 }
                 else {
                     unit.finalize();
@@ -923,29 +933,31 @@
         }
     }
 
-    const xnew$1 = Object.assign(function (...args) {
+    const xnew$1 = Object.assign(
+    /**
+     * creates a new Unit component
+     * xnew(Component?: Function | string, props?: Object): Unit;
+     * xnew(target: HTMLElement | SVGElement | string, Component?: Function | string, props?: Object): Unit;
+     * @param target - HTMLElement | SVGElement, or HTML tag for new element
+     * @param Component - component function
+     * @param props - properties for component function
+     * @returns a new Unit instance
+     * @example
+     * const unit = xnew(MyComponent, { data: 0 })
+     * const unit = xnew(element, MyComponent, { data: 0 })
+     * const unit = xnew('<div>', MyComponent, { data: 0 })
+     */
+    function (...args) {
         if (Unit.rootUnit === undefined)
             Unit.reset();
-        let target;
-        if (args[0] instanceof HTMLElement || args[0] instanceof SVGElement) {
-            target = args.shift(); // an existing html element
-        }
-        else if (typeof args[0] === 'string' && args[0].match(/<((\w+)[^>]*?)\/?>/)) {
-            target = args.shift();
-        }
-        else {
-            target = null;
-        }
-        const Component = args.shift();
-        const props = args.shift();
-        const unit = new Unit(Unit.currentUnit, target, Component, props);
-        return unit;
+        return new Unit(Unit.currentUnit, ...args);
     }, {
         /**
-         * Creates a nested HTML/SVG element within the current component
-         * @param target - HTML or SVG tag string (e.g., '<div class="my-class">', '<span style="color:red">', '<svg viewBox="0 0 24 24">')
-         * @returns The created HTML/SVG element
-         * @throws Error if called after component initialization
+         * Creates a child HTML/SVG element inside the current component's element.
+         * Must be called during component initialization (before setup completes).
+         * @param target - An existing HTML/SVG element, or a tag string like `'<div>'`
+         * @returns The provided element, or the newly created element
+         * @throws Error if called after the component has finished initializing
          * @example
          * const div = xnew.nest('<div>')
          * div.textContent = 'Hello'
@@ -958,7 +970,7 @@
                 return Unit.nest(Unit.currentUnit, target);
             }
             catch (error) {
-                console.error('xnew.nest(target: HTMLElement | SVGElement | string): ', error);
+                console.error('xnew.nest(target: UnitElement | string): ', error);
                 throw error;
             }
         },
@@ -984,17 +996,25 @@
                 throw error;
             }
         },
+        append(parent, ...args) {
+            try {
+                new Unit(parent, ...args);
+            }
+            catch (error) {
+                console.error('xnew.append(parent: Unit, ...args: UnitArgs): ', error);
+                throw error;
+            }
+        },
         /**
-         * Gets a context value that can be accessed in follow context
-         * @param key - component function
-         * @returns The context value
+         * Gets the Unit instance associated with the given component in the ancestor context chain
+         * @param key - component function used as context key
+         * @returns The Unit instance registered with the given component, or undefined if not found
          * @example
-         * // Create unit
-         * const a = xnew(A);
-         * ------------------------------
+         * // Create parent unit with component A
+         * const parent = xnew(A);
          *
-         * // Get context in child
-         * const a = xnew.context(A)
+         * // Inside a child component, get the parent unit
+         * const parentUnit = xnew.context(A)
          */
         context(key) {
             try {
@@ -1007,24 +1027,22 @@
         },
         /**
          * Registers a promise with the current component for lifecycle management
-         * @param promise - Promise to register
+         * @param promise - A Promise, async function, or Unit to register
          * @returns UnitPromise wrapper for chaining
          * @example
          * xnew.promise(fetchData()).then(data => console.log(data))
          */
         promise(promise) {
             try {
-                const Component = Unit.currentUnit._.currentComponent;
                 let unitPromise;
                 if (promise instanceof Unit) {
-                    unitPromise = new UnitPromise(Promise.all(promise._.promises.map(p => p.promise)), Component)
-                        .then(() => promise._.results);
+                    unitPromise = UnitPromise.all(promise._.promises).then(() => promise._.results);
                 }
                 else if (promise instanceof Promise) {
-                    unitPromise = new UnitPromise(promise, Component);
+                    unitPromise = new UnitPromise(promise);
                 }
                 else {
-                    unitPromise = new UnitPromise(new Promise(xnew$1.scope(promise)), Component);
+                    unitPromise = new UnitPromise(new Promise(xnew$1.scope(promise)));
                 }
                 Unit.currentUnit._.promises.push(unitPromise);
                 return unitPromise;
@@ -1044,8 +1062,7 @@
         then(callback) {
             try {
                 const currentUnit = Unit.currentUnit;
-                return new UnitPromise(Promise.all(Unit.currentUnit._.promises.map(p => p.promise)), null)
-                    .then(() => callback(currentUnit._.results));
+                return UnitPromise.all(Unit.currentUnit._.promises).then(() => callback(currentUnit._.results));
             }
             catch (error) {
                 console.error('xnew.then(callback: Function): ', error);
@@ -1061,7 +1078,7 @@
          */
         catch(callback) {
             try {
-                return new UnitPromise(Promise.all(Unit.currentUnit._.promises.map(p => p.promise)), null)
+                return UnitPromise.all(Unit.currentUnit._.promises)
                     .catch(callback);
             }
             catch (error) {
@@ -1070,35 +1087,67 @@
             }
         },
         /**
-         * Commits a value to the current unit's promise results
-         * @param object - object to commit to the promise
-         * @returns void
+         * Executes callback after all registered promises settle (resolve or reject)
+         * @param callback - Function to call after promises settle
+         * @returns UnitPromise for chaining
          * @example
-         * xnew.commit({ data: 123});
+         * xnew.finally(() => console.log('All promises settled'))
          */
-        commit(object) {
+        finally(callback) {
             try {
-                Object.assign(Unit.currentUnit._.results, object);
+                return UnitPromise.all(Unit.currentUnit._.promises).finally(callback);
             }
             catch (error) {
-                console.error('xnew.commit(object?: Record<string, any>): ', error);
+                console.error('xnew.finally(callback: Function): ', error);
                 throw error;
             }
         },
+        resolvers() {
+            let state = null;
+            let resolve = null;
+            let reject = null;
+            const unitPromise = new UnitPromise(new Promise((res, rej) => {
+                if (state === 'resolved') {
+                    res(null);
+                }
+                else if (state === 'rejected') {
+                    rej();
+                }
+                else {
+                    resolve = res;
+                    reject = rej;
+                    state = 'pending';
+                }
+            }));
+            Unit.currentUnit._.promises.push(unitPromise);
+            return {
+                resolve() {
+                    if (state === 'pending') {
+                        resolve === null || resolve === void 0 ? void 0 : resolve(null);
+                    }
+                    state = 'resolved';
+                },
+                reject() {
+                    if (state === 'pending') {
+                        reject === null || reject === void 0 ? void 0 : reject();
+                    }
+                    state = 'rejected';
+                }
+            };
+        },
         /**
-         * Executes callback after all registered promises settle (resolve or reject)
-         * @param callback - Function to call after promises settle
-         * @returns UnitPromise for chaining
+         * Outputs a value to the current unit's promise results
+         * @param object - object to output for the promise
+         * @returns void
          * @example
-         * xnew.finally(() => console.log('All promises settled'))
+         * xnew.output({ data: 123});
          */
-        finally(callback) {
+        output(object) {
             try {
-                return new UnitPromise(Promise.all(Unit.currentUnit._.promises.map(p => p.promise)), null)
-                    .finally(callback);
+                Object.assign(Unit.currentUnit._.results, object);
             }
             catch (error) {
-                console.error('xnew.finally(callback: Function): ', error);
+                console.error('xnew.output(object?: Record<string, any>): ', error);
                 throw error;
             }
         },
@@ -1136,7 +1185,7 @@
         /**
          * Emits a custom event to components
          * @param type - Event type to emit (prefix with '+' for global events, '-' for local events)
-         * @param args - Additional arguments to pass to event listeners
+         * @param props - Event properties object to pass to listeners
          * @returns void
          * @example
          * xnew.emit('+globalevent', { data: 123 }); // Global event
@@ -1153,7 +1202,7 @@
         },
         /**
          * Executes a callback once after a delay, managed by component lifecycle
-         * @param callback - Function to execute after Duration
+         * @param callback - Function to execute after duration
          * @param duration - Duration in milliseconds
          * @returns Object with clear() method to cancel the timeout
          * @example
@@ -1275,7 +1324,7 @@
         }
         const canvas = xnew$1(`<canvas width="${width}" height="${height}" style="width: 100%; height: 100%; vertical-align: bottom;">`);
         return {
-            get canvas() { return canvas.element; }
+            get canvas() { return canvas.element; },
         };
     }
 
@@ -1561,6 +1610,8 @@
         }
     }
 
+    function Scene(unit) {
+    }
     function Flow(unit) {
         let scene = null;
         return {
@@ -1570,15 +1621,52 @@
             get scene() {
                 return scene;
             },
-            next(Component, props) {
-                var _a;
-                // scene change
-                (_a = unit.scene) === null || _a === void 0 ? void 0 : _a.finalize();
-                unit.scene = xnew$1(Component, props);
-            }
+            next(Component, props, callback) {
+                callback = callback !== null && callback !== void 0 ? callback : defaultCallback;
+                callback(scene, create);
+                function defaultCallback(current, create) {
+                    current === null || current === void 0 ? void 0 : current.finalize();
+                    create();
+                }
+                function create() {
+                    scene = xnew$1((unit) => {
+                        xnew$1.extend(Scene);
+                        xnew$1.extend(Component, props);
+                    });
+                    return scene;
+                }
+            },
         };
     }
 
+    class XImage {
+        constructor(...args) {
+            if (args[0] instanceof HTMLCanvasElement) {
+                this.canvas = args[0];
+            }
+            else {
+                const canvas = document.createElement('canvas');
+                canvas.width = args[0];
+                canvas.height = args[1];
+                this.canvas = canvas;
+            }
+        }
+        clip(x, y, width, height) {
+            var _a;
+            const canvas = document.createElement('canvas');
+            canvas.width = width;
+            canvas.height = height;
+            (_a = canvas.getContext('2d')) === null || _a === void 0 ? void 0 : _a.drawImage(this.canvas, x, y, width, height, 0, 0, width, height);
+            return new XImage(canvas);
+        }
+        download(filename) {
+            const link = document.createElement('a');
+            link.download = filename;
+            link.href = this.canvas.toDataURL('image/png');
+            link.click();
+        }
+    }
+
     const context = new window.AudioContext();
     const master = context.createGain();
     //----------------------------------------------------------------------------------------------------
@@ -1812,6 +1900,7 @@
         Accordion,
         Popup,
         Flow,
+        Scene,
     };
     const audio = {
         load(path) {
@@ -1840,7 +1929,12 @@
             master.gain.value = value;
         }
     };
-    const xnew = Object.assign(xnew$1, { basics, audio });
+    const image = {
+        from(canvas) {
+            return new XImage(canvas);
+        }
+    };
+    const xnew = Object.assign(xnew$1, { basics, audio, image });
 
     return xnew;
 

package/dist/xnew.mjs

@@ -186,7 +186,7 @@ class Timer {
                 this.id = null;
                 this.time = { start: 0.0, processed: 0.0 };
                 (_b = (_a = this.options).transition) === null || _b === void 0 ? void 0 : _b.call(_a, 1.0);
-                (_d = (_c = this.options).callback) === null || _d === void 0 ? void 0 : _d.call(_c);
+                (_d = (_c = this.options).timeout) === null || _d === void 0 ? void 0 : _d.call(_c);
                 this.clear();
             }, this.options.duration - this.time.processed);
             this.time.start = Date.now();
@@ -513,16 +513,26 @@ function pointer(element, event) {
     return { position };
 }
 
-//----------------------------------------------------------------------------------------------------
-// utils
-//----------------------------------------------------------------------------------------------------
 const SYSTEM_EVENTS = ['start', 'update', 'render', 'stop', 'finalize'];
 //----------------------------------------------------------------------------------------------------
 // unit
 //----------------------------------------------------------------------------------------------------
 class Unit {
-    constructor(parent, target, Component, props) {
+    constructor(parent, ...args) {
         var _a;
+        let target;
+        let Component;
+        let props;
+        if (args[0] instanceof HTMLElement || args[0] instanceof SVGElement || typeof args[0] === 'string') {
+            target = args[0];
+            Component = args[1];
+            props = args[2];
+        }
+        else {
+            target = null;
+            Component = args[0];
+            props = args[1];
+        }
         const backup = Unit.currentUnit;
         Unit.currentUnit = this;
         parent === null || parent === void 0 ? void 0 : parent._.children.push(this);
@@ -644,7 +654,7 @@ class Unit {
                 return element;
             }
             else {
-                throw new Error(`xnew.nest: invalid html string [${target}]`);
+                throw new Error(`xnew.nest: invalid tag string [${target}]`);
             }
         }
     }
@@ -686,7 +696,7 @@ class Unit {
                 Object.defineProperty(unit._.defines, key, wrapper);
                 Object.defineProperty(unit, key, wrapper);
             });
-            return defines;
+            return Object.assign({}, unit._.defines);
         }
     }
     static start(unit) {
@@ -723,7 +733,7 @@ class Unit {
     static reset() {
         var _a;
         (_a = Unit.rootUnit) === null || _a === void 0 ? void 0 : _a.finalize();
-        Unit.currentUnit = Unit.rootUnit = new Unit(null, null);
+        Unit.currentUnit = Unit.rootUnit = new Unit(null);
         const ticker = new AnimationTicker(() => {
             Unit.start(Unit.rootUnit);
             Unit.update(Unit.rootUnit);
@@ -763,7 +773,7 @@ class Unit {
     }
     static getContext(unit, key) {
         for (let context = unit._.currentContext; context.previous !== null; context = context.previous) {
-            if (context.value === Unit.currentUnit && key === Unit.currentUnit._.currentComponent)
+            if (context.value === Unit.currentUnit)
                 continue;
             if (context.key === key)
                 return context.value;
@@ -842,13 +852,13 @@ Unit.type2units = new MapSet();
 // extensions
 //----------------------------------------------------------------------------------------------------
 class UnitPromise {
-    constructor(promise, Component) {
-        this.promise = promise;
-        this.Component = Component;
-    }
+    constructor(promise) { this.promise = promise; }
     then(callback) { return this.wrap('then', callback); }
     catch(callback) { return this.wrap('catch', callback); }
     finally(callback) { return this.wrap('finally', callback); }
+    static all(promises) {
+        return new UnitPromise(Promise.all(promises.map(p => p.promise)));
+    }
     wrap(key, callback) {
         const snapshot = Unit.snapshot(Unit.currentUnit);
         this.promise = this.promise[key]((...args) => Unit.scope(snapshot, callback, ...args));
@@ -866,11 +876,11 @@ class UnitTimer {
         (_a = this.unit) === null || _a === void 0 ? void 0 : _a.finalize();
         this.unit = null;
     }
-    timeout(callback, duration = 0) {
-        return UnitTimer.execute(this, { callback, duration }, 1);
+    timeout(timeout, duration = 0) {
+        return UnitTimer.execute(this, { timeout, duration }, 1);
     }
-    interval(callback, duration = 0, iterations = 0) {
-        return UnitTimer.execute(this, { callback, duration }, iterations);
+    interval(timeout, duration = 0, iterations = 0) {
+        return UnitTimer.execute(this, { timeout, duration }, iterations);
     }
     transition(transition, duration = 0, easing) {
         return UnitTimer.execute(this, { transition, duration, easing }, 1);
@@ -878,7 +888,7 @@ class UnitTimer {
     static execute(timer, options, iterations) {
         const props = { options, iterations, snapshot: Unit.snapshot(Unit.currentUnit) };
         if (timer.unit === null || timer.unit._.state === 'finalized') {
-            timer.unit = new Unit(Unit.currentUnit, null, UnitTimer.Component, props);
+            timer.unit = new Unit(Unit.currentUnit, UnitTimer.Component, props);
         }
         else if (timer.queue.length === 0) {
             timer.queue.push(props);
@@ -891,18 +901,18 @@ class UnitTimer {
     }
     static next(timer) {
         if (timer.queue.length > 0) {
-            timer.unit = new Unit(Unit.currentUnit, null, UnitTimer.Component, timer.queue.shift());
+            timer.unit = new Unit(Unit.currentUnit, UnitTimer.Component, timer.queue.shift());
             timer.unit.on('finalize', () => UnitTimer.next(timer));
         }
     }
     static Component(unit, { options, iterations, snapshot }) {
         let counter = 0;
-        let timer = new Timer({ callback, transition, duration: options.duration, easing: options.easing });
-        function callback() {
-            if (options.callback)
-                Unit.scope(snapshot, options.callback);
+        let timer = new Timer({ timeout, transition, duration: options.duration, easing: options.easing });
+        function timeout() {
+            if (options.timeout)
+                Unit.scope(snapshot, options.timeout);
             if (iterations <= 0 || counter < iterations - 1) {
-                timer = new Timer({ callback, transition, duration: options.duration, easing: options.easing });
+                timer = new Timer({ timeout, transition, duration: options.duration, easing: options.easing });
             }
             else {
                 unit.finalize();
@@ -917,29 +927,31 @@ class UnitTimer {
     }
 }
 
-const xnew$1 = Object.assign(function (...args) {
+const xnew$1 = Object.assign(
+/**
+ * creates a new Unit component
+ * xnew(Component?: Function | string, props?: Object): Unit;
+ * xnew(target: HTMLElement | SVGElement | string, Component?: Function | string, props?: Object): Unit;
+ * @param target - HTMLElement | SVGElement, or HTML tag for new element
+ * @param Component - component function
+ * @param props - properties for component function
+ * @returns a new Unit instance
+ * @example
+ * const unit = xnew(MyComponent, { data: 0 })
+ * const unit = xnew(element, MyComponent, { data: 0 })
+ * const unit = xnew('<div>', MyComponent, { data: 0 })
+ */
+function (...args) {
     if (Unit.rootUnit === undefined)
         Unit.reset();
-    let target;
-    if (args[0] instanceof HTMLElement || args[0] instanceof SVGElement) {
-        target = args.shift(); // an existing html element
-    }
-    else if (typeof args[0] === 'string' && args[0].match(/<((\w+)[^>]*?)\/?>/)) {
-        target = args.shift();
-    }
-    else {
-        target = null;
-    }
-    const Component = args.shift();
-    const props = args.shift();
-    const unit = new Unit(Unit.currentUnit, target, Component, props);
-    return unit;
+    return new Unit(Unit.currentUnit, ...args);
 }, {
     /**
-     * Creates a nested HTML/SVG element within the current component
-     * @param target - HTML or SVG tag string (e.g., '<div class="my-class">', '<span style="color:red">', '<svg viewBox="0 0 24 24">')
-     * @returns The created HTML/SVG element
-     * @throws Error if called after component initialization
+     * Creates a child HTML/SVG element inside the current component's element.
+     * Must be called during component initialization (before setup completes).
+     * @param target - An existing HTML/SVG element, or a tag string like `'<div>'`
+     * @returns The provided element, or the newly created element
+     * @throws Error if called after the component has finished initializing
      * @example
      * const div = xnew.nest('<div>')
      * div.textContent = 'Hello'
@@ -952,7 +964,7 @@ const xnew$1 = Object.assign(function (...args) {
             return Unit.nest(Unit.currentUnit, target);
         }
         catch (error) {
-            console.error('xnew.nest(target: HTMLElement | SVGElement | string): ', error);
+            console.error('xnew.nest(target: UnitElement | string): ', error);
             throw error;
         }
     },
@@ -978,17 +990,25 @@ const xnew$1 = Object.assign(function (...args) {
             throw error;
         }
     },
+    append(parent, ...args) {
+        try {
+            new Unit(parent, ...args);
+        }
+        catch (error) {
+            console.error('xnew.append(parent: Unit, ...args: UnitArgs): ', error);
+            throw error;
+        }
+    },
     /**
-     * Gets a context value that can be accessed in follow context
-     * @param key - component function
-     * @returns The context value
+     * Gets the Unit instance associated with the given component in the ancestor context chain
+     * @param key - component function used as context key
+     * @returns The Unit instance registered with the given component, or undefined if not found
      * @example
-     * // Create unit
-     * const a = xnew(A);
-     * ------------------------------
+     * // Create parent unit with component A
+     * const parent = xnew(A);
      *
-     * // Get context in child
-     * const a = xnew.context(A)
+     * // Inside a child component, get the parent unit
+     * const parentUnit = xnew.context(A)
      */
     context(key) {
         try {
@@ -1001,24 +1021,22 @@ const xnew$1 = Object.assign(function (...args) {
     },
     /**
      * Registers a promise with the current component for lifecycle management
-     * @param promise - Promise to register
+     * @param promise - A Promise, async function, or Unit to register
      * @returns UnitPromise wrapper for chaining
      * @example
      * xnew.promise(fetchData()).then(data => console.log(data))
      */
     promise(promise) {
         try {
-            const Component = Unit.currentUnit._.currentComponent;
             let unitPromise;
             if (promise instanceof Unit) {
-                unitPromise = new UnitPromise(Promise.all(promise._.promises.map(p => p.promise)), Component)
-                    .then(() => promise._.results);
+                unitPromise = UnitPromise.all(promise._.promises).then(() => promise._.results);
             }
             else if (promise instanceof Promise) {
-                unitPromise = new UnitPromise(promise, Component);
+                unitPromise = new UnitPromise(promise);
             }
             else {
-                unitPromise = new UnitPromise(new Promise(xnew$1.scope(promise)), Component);
+                unitPromise = new UnitPromise(new Promise(xnew$1.scope(promise)));
             }
             Unit.currentUnit._.promises.push(unitPromise);
             return unitPromise;
@@ -1038,8 +1056,7 @@ const xnew$1 = Object.assign(function (...args) {
     then(callback) {
         try {
             const currentUnit = Unit.currentUnit;
-            return new UnitPromise(Promise.all(Unit.currentUnit._.promises.map(p => p.promise)), null)
-                .then(() => callback(currentUnit._.results));
+            return UnitPromise.all(Unit.currentUnit._.promises).then(() => callback(currentUnit._.results));
         }
         catch (error) {
             console.error('xnew.then(callback: Function): ', error);
@@ -1055,7 +1072,7 @@ const xnew$1 = Object.assign(function (...args) {
      */
     catch(callback) {
         try {
-            return new UnitPromise(Promise.all(Unit.currentUnit._.promises.map(p => p.promise)), null)
+            return UnitPromise.all(Unit.currentUnit._.promises)
                 .catch(callback);
         }
         catch (error) {
@@ -1064,35 +1081,67 @@ const xnew$1 = Object.assign(function (...args) {
         }
     },
     /**
-     * Commits a value to the current unit's promise results
-     * @param object - object to commit to the promise
-     * @returns void
+     * Executes callback after all registered promises settle (resolve or reject)
+     * @param callback - Function to call after promises settle
+     * @returns UnitPromise for chaining
      * @example
-     * xnew.commit({ data: 123});
+     * xnew.finally(() => console.log('All promises settled'))
      */
-    commit(object) {
+    finally(callback) {
         try {
-            Object.assign(Unit.currentUnit._.results, object);
+            return UnitPromise.all(Unit.currentUnit._.promises).finally(callback);
         }
         catch (error) {
-            console.error('xnew.commit(object?: Record<string, any>): ', error);
+            console.error('xnew.finally(callback: Function): ', error);
             throw error;
         }
     },
+    resolvers() {
+        let state = null;
+        let resolve = null;
+        let reject = null;
+        const unitPromise = new UnitPromise(new Promise((res, rej) => {
+            if (state === 'resolved') {
+                res(null);
+            }
+            else if (state === 'rejected') {
+                rej();
+            }
+            else {
+                resolve = res;
+                reject = rej;
+                state = 'pending';
+            }
+        }));
+        Unit.currentUnit._.promises.push(unitPromise);
+        return {
+            resolve() {
+                if (state === 'pending') {
+                    resolve === null || resolve === void 0 ? void 0 : resolve(null);
+                }
+                state = 'resolved';
+            },
+            reject() {
+                if (state === 'pending') {
+                    reject === null || reject === void 0 ? void 0 : reject();
+                }
+                state = 'rejected';
+            }
+        };
+    },
     /**
-     * Executes callback after all registered promises settle (resolve or reject)
-     * @param callback - Function to call after promises settle
-     * @returns UnitPromise for chaining
+     * Outputs a value to the current unit's promise results
+     * @param object - object to output for the promise
+     * @returns void
      * @example
-     * xnew.finally(() => console.log('All promises settled'))
+     * xnew.output({ data: 123});
      */
-    finally(callback) {
+    output(object) {
         try {
-            return new UnitPromise(Promise.all(Unit.currentUnit._.promises.map(p => p.promise)), null)
-                .finally(callback);
+            Object.assign(Unit.currentUnit._.results, object);
         }
         catch (error) {
-            console.error('xnew.finally(callback: Function): ', error);
+            console.error('xnew.output(object?: Record<string, any>): ', error);
             throw error;
         }
     },
@@ -1130,7 +1179,7 @@ const xnew$1 = Object.assign(function (...args) {
     /**
      * Emits a custom event to components
      * @param type - Event type to emit (prefix with '+' for global events, '-' for local events)
-     * @param args - Additional arguments to pass to event listeners
+     * @param props - Event properties object to pass to listeners
      * @returns void
      * @example
      * xnew.emit('+globalevent', { data: 123 }); // Global event
@@ -1147,7 +1196,7 @@ const xnew$1 = Object.assign(function (...args) {
     },
     /**
      * Executes a callback once after a delay, managed by component lifecycle
-     * @param callback - Function to execute after Duration
+     * @param callback - Function to execute after duration
      * @param duration - Duration in milliseconds
      * @returns Object with clear() method to cancel the timeout
      * @example
@@ -1269,7 +1318,7 @@ function Screen(unit, { width = 800, height = 600, fit = 'contain' } = {}) {
     }
     const canvas = xnew$1(`<canvas width="${width}" height="${height}" style="width: 100%; height: 100%; vertical-align: bottom;">`);
     return {
-        get canvas() { return canvas.element; }
+        get canvas() { return canvas.element; },
     };
 }
 
@@ -1555,6 +1604,8 @@ function Select(_, { key = '', value, items = [] } = {}) {
     }
 }
 
+function Scene(unit) {
+}
 function Flow(unit) {
     let scene = null;
     return {
@@ -1564,15 +1615,52 @@ function Flow(unit) {
         get scene() {
             return scene;
         },
-        next(Component, props) {
-            var _a;
-            // scene change
-            (_a = unit.scene) === null || _a === void 0 ? void 0 : _a.finalize();
-            unit.scene = xnew$1(Component, props);
-        }
+        next(Component, props, callback) {
+            callback = callback !== null && callback !== void 0 ? callback : defaultCallback;
+            callback(scene, create);
+            function defaultCallback(current, create) {
+                current === null || current === void 0 ? void 0 : current.finalize();
+                create();
+            }
+            function create() {
+                scene = xnew$1((unit) => {
+                    xnew$1.extend(Scene);
+                    xnew$1.extend(Component, props);
+                });
+                return scene;
+            }
+        },
     };
 }
 
+class XImage {
+    constructor(...args) {
+        if (args[0] instanceof HTMLCanvasElement) {
+            this.canvas = args[0];
+        }
+        else {
+            const canvas = document.createElement('canvas');
+            canvas.width = args[0];
+            canvas.height = args[1];
+            this.canvas = canvas;
+        }
+    }
+    clip(x, y, width, height) {
+        var _a;
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        (_a = canvas.getContext('2d')) === null || _a === void 0 ? void 0 : _a.drawImage(this.canvas, x, y, width, height, 0, 0, width, height);
+        return new XImage(canvas);
+    }
+    download(filename) {
+        const link = document.createElement('a');
+        link.download = filename;
+        link.href = this.canvas.toDataURL('image/png');
+        link.click();
+    }
+}
+
 const context = new window.AudioContext();
 const master = context.createGain();
 //----------------------------------------------------------------------------------------------------
@@ -1806,6 +1894,7 @@ const basics = {
     Accordion,
     Popup,
     Flow,
+    Scene,
 };
 const audio = {
     load(path) {
@@ -1834,6 +1923,11 @@ const audio = {
         master.gain.value = value;
     }
 };
-const xnew = Object.assign(xnew$1, { basics, audio });
+const image = {
+    from(canvas) {
+        return new XImage(canvas);
+    }
+};
+const xnew = Object.assign(xnew$1, { basics, audio, image });
 
 export { xnew as default };

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "Component-Oriented Programming"
   ],
-  "version": "0.6.8",
+  "version": "0.7.0",
   "main": "dist/xnew.js",
   "module": "dist/xnew.mjs",
   "types": "dist/xnew.d.ts",