@adaas/are-html 0.0.21 → 0.0.22

package/jest.config.ts

@@ -17,6 +17,7 @@ const config: Config.InitialOptions = {
         "@adaas/are-html/instructions/(.*)": "<rootDir>/src/instructions/$1",
         "@adaas/are-html/watchers/(.*)":     "<rootDir>/src/watchers/$1",
         "@adaas/are-html/signals/(.*)":      "<rootDir>/src/signals/$1",
+        "@adaas/are-html/helpers/(.*)":      "<rootDir>/src/helpers/$1",
         // Custom lib exports
         "@adaas/are-html/style/(.*)":        "<rootDir>/src/lib/AreStyle/$1",
         "@adaas/are-html/directive/(.*)":    "<rootDir>/src/lib/AreDirective/$1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/are-html",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "A-Concept Rendering Engine (ARE) is a powerful rendering engine designed to work seamlessly with the A-Concept framework. This library provides an HTML engine implementation of ARE, enabling developers to create dynamic and interactive user interfaces for web applications using standard HTML syntax.",
   "keywords": [
     "a-concept",
@@ -73,6 +73,7 @@
     "example:signal-routing": "nodemon ./examples/signal-routing/concept.ts",
     "example:component-styles": "nodemon ./examples/component-styles/concept.ts",
     "example:auxta": "nodemon ./examples/auxta/concept.ts",
+    "example:for-perf": "nodemon ./examples/for-perf/concept.ts",
     "test:test": "nodemon ./src/test/app.ts",
     "release": " npm run build && git add . && git commit -m \"new version created :: $(cat package.json | grep version | head -1  | awk -F: '{ print $2 }'  | sed 's/[\",]//g')\" && npm version patch && npm publish --access public",
     "preversion": "echo test",
@@ -82,16 +83,16 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@adaas/a-concept": "^0.3.27",
-    "@adaas/a-frame": "^0.1.14",
-    "@adaas/a-utils": "^0.3.32",
-    "@adaas/are": "^0.0.21"
+    "@adaas/a-concept": "^0.3.29",
+    "@adaas/a-frame": "^0.1.17",
+    "@adaas/a-utils": "^0.3.34",
+    "@adaas/are": "^0.0.23"
   },
   "devDependencies": {
-    "@adaas/a-concept": "^0.3.27",
-    "@adaas/a-frame": "^0.1.14",
-    "@adaas/a-utils": "^0.3.32",
-    "@adaas/are": "^0.0.21",
+    "@adaas/a-concept": "^0.3.29",
+    "@adaas/a-frame": "^0.1.17",
+    "@adaas/a-utils": "^0.3.34",
+    "@adaas/are": "^0.0.23",
     "@types/chai": "^4.3.14",
     "@types/jest": "^29.5.12",
     "@types/mocha": "^10.0.6",

package/src/directives/AreDirectiveFor.directive.ts

@@ -7,6 +7,7 @@ import { AddCommentInstruction } from "@adaas/are-html/instructions/AddComment.i
 import { AreHTMLNode } from "@adaas/are-html/node";
 import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 import { A_Frame } from "@adaas/a-frame/core";
+import { AreSchedulerHelper } from "@adaas/are-html/helpers/AreScheduler.helper";
 
 
 type AreForExpression = {
@@ -17,6 +18,12 @@ type AreForExpression = {
     trackExpr: string | undefined;
 };
 
+/**
+ * Per-`$for` reentrancy state used to serialize chunked (async) renders.
+ * Keyed by the directive attribute instance (one per `$for` in the template).
+ */
+type AreForRenderState = { running: boolean; pending: boolean };
+
 
 @A_Frame.Define({
     namespace: 'a-are-html',
@@ -25,6 +32,32 @@ type AreForExpression = {
 @AreDirective.Priority(1)
 export class AreDirectiveFor extends AreDirective {
 
+    /**
+     * Lists whose number of NEW item nodes is at or below this threshold render
+     * fully synchronously — byte-for-byte the previous behavior. Typical UIs
+     * (menus, small tables) are therefore completely unaffected; only genuinely
+     * large lists pay the (tiny) scheduling cost to keep the main thread responsive.
+     */
+    private static readonly SYNC_THRESHOLD = 100;
+
+    /**
+     * Per-chunk time budget (ms). During a large-list render we mount item nodes
+     * until this much time has elapsed, then yield to the browser so it can paint
+     * and process input before the next chunk. ~16ms targets one animation frame.
+     */
+    private static readonly CHUNK_BUDGET_MS = 16;
+
+    /**
+     * Per-attribute serialization state. A new update() that arrives while a
+     * chunked render of the SAME `$for` is still in flight does NOT start a second
+     * concurrent pass (which could interleave mutations on the shared children
+     * list); instead it marks `pending` and the in-flight run re-runs once more
+     * with the latest data when it finishes. This guarantees the children list is
+     * only ever mutated by one pass at a time and the final state always reflects
+     * the most recent store value.
+     */
+    private static readonly renderState = new WeakMap<object, AreForRenderState>();
+
 
     @AreDirective.Transform
     transform(
@@ -122,7 +155,40 @@ export class AreDirectiveFor extends AreDirective {
         @A_Inject(AreStore) store: AreStore,
         @A_Inject(AreScene) scene: AreScene,
         ...args: any[]
-    ): void {
+    ): void | Promise<void> {
+        /**
+         * Serialize chunked renders per `$for`. If a previous large-list render
+         * is still streaming item nodes across macrotasks, do NOT start a second
+         * concurrent pass — that would interleave two diffs over the same shared
+         * children list (and leave half-compiled item nodes that the next diff
+         * would wrongly "reuse"). Mark a pass as pending instead; the in-flight
+         * run re-diffs once more from the latest store value when it completes.
+         */
+        let state = AreDirectiveFor.renderState.get(attribute);
+        if (!state) {
+            state = { running: false, pending: false };
+            AreDirectiveFor.renderState.set(attribute, state);
+        }
+        if (state.running) {
+            state.pending = true;
+            return;
+        }
+
+        return this.performUpdate(attribute, store, scene, state);
+    }
+
+    /**
+     * Core of the `$for` update: re-diff the source array against the current
+     * children, reconcile reused/removed items, then mount the new ones (small
+     * lists synchronously, large lists time-sliced). Never called while another
+     * pass for the same `$for` is in flight (see `update`).
+     */
+    private performUpdate(
+        attribute: AreDirectiveAttribute,
+        store: AreStore,
+        scene: AreScene,
+        state: AreForRenderState,
+    ): void | Promise<void> {
         /**
          * Re-evaluate the source array.
          */
@@ -167,9 +233,13 @@ export class AreDirectiveFor extends AreDirective {
             remaining.add(child);
         }
 
-        // ── 2. Walk desired list; reuse existing or spawn new ───────────────
-        const desired: AreHTMLNode[] = [];
-        const newOnes: AreHTMLNode[] = [];
+        // ── 2. Walk desired list; reuse existing or record items to create ──
+        // NOTE: new item nodes are NOT spawned here. Spawning (cloneWithScope +
+        // subtree init + scene activation) is the dominant cost of a large
+        // render, so it is deferred into the time-sliced loop below alongside
+        // transform/compile/mount. Existing (keyed) children are reconciled in
+        // place synchronously — that is cheap and keeps reused rows stable.
+        const toCreate: Array<{ item: any; idx: number }> = [];
 
         for (let i = 0; i < newArray.length; i++) {
             const item = newArray[i];
@@ -189,11 +259,8 @@ export class AreDirectiveFor extends AreDirective {
                     [key]: item,
                     [index || 'index']: i,
                 };
-                desired.push(existing);
             } else {
-                const itemNode = this.spawnItemNode(attribute.template!, owner, key, index, item, i);
-                desired.push(itemNode);
-                newOnes.push(itemNode);
+                toCreate.push({ item, idx: i });
             }
         }
 
@@ -206,8 +273,13 @@ export class AreDirectiveFor extends AreDirective {
             owner.removeChild(child);
         }
 
-        // ── 4. Mount only the new ones (kept children stay where they are). ─
-        for (const child of newOnes) {
+        // ── 4. Create + mount the new item nodes. ───────────────────────────
+        // `spawnItemNode` appends to `owner.children` immediately, so iterating
+        // `toCreate` in source order preserves list order (reused children keep
+        // their positions, new rows are appended in order) — identical to the
+        // previous synchronous behavior.
+        const createItem = (desc: { item: any; idx: number }) => {
+            const child = this.spawnItemNode(attribute.template!, owner, key, index, desc.item, desc.idx);
             child.transform();
             child.compile();
             // While detached, stop after compile: the item's instructions are
@@ -215,6 +287,65 @@ export class AreDirectiveFor extends AreDirective {
             // the correct container once the condition becomes truthy. Mounting
             // here would hoist the item to the nearest mounted ancestor.
             if (attached) child.mount();
+        };
+
+        // Small lists → fully synchronous, identical to the previous behavior.
+        if (toCreate.length <= AreDirectiveFor.SYNC_THRESHOLD) {
+            for (const desc of toCreate) createItem(desc);
+            return this.finishUpdate(attribute, store, scene, state);
+        }
+
+        // Large lists → time-sliced render. Create item nodes until the frame
+        // budget elapses, then yield to the browser (zero-delay macrotask) so
+        // it can paint and stay responsive instead of blocking for the whole
+        // batch. The `state.running` flag (see `update`) prevents any other
+        // update() for this `$for` from interleaving while we stream.
+        state.running = true;
+        let cursor = 0;
+
+        const processChunk = (): void | Promise<void> => {
+            try {
+                const start = AreSchedulerHelper.now();
+                while (cursor < toCreate.length) {
+                    createItem(toCreate[cursor]);
+                    cursor++;
+                    if (AreSchedulerHelper.now() - start >= AreDirectiveFor.CHUNK_BUDGET_MS) break;
+                }
+            } catch (error) {
+                // Never leave the `$for` wedged in the running state on failure,
+                // or every future update would be silently deferred forever.
+                state.running = false;
+                state.pending = false;
+                throw error;
+            }
+
+            if (cursor < toCreate.length) {
+                return new Promise<void>(resolve => {
+                    AreSchedulerHelper.scheduleMacrotask(() => resolve(processChunk()));
+                });
+            }
+
+            return this.finishUpdate(attribute, store, scene, state);
+        };
+
+        return processChunk();
+    }
+
+    /**
+     * Completes an update pass. If another update() arrived while a chunked
+     * render was streaming, run exactly one more pass now from the latest store
+     * value so the final DOM always reflects the most recent data.
+     */
+    private finishUpdate(
+        attribute: AreDirectiveAttribute,
+        store: AreStore,
+        scene: AreScene,
+        state: AreForRenderState,
+    ): void | Promise<void> {
+        state.running = false;
+        if (state.pending) {
+            state.pending = false;
+            return this.performUpdate(attribute, store, scene, state);
         }
     }
 

package/src/engine/AreHTML.lifecycle.ts

@@ -10,6 +10,7 @@ import { AreDirectiveFeatures } from "@adaas/are-html/directive/AreDirective.con
 import { AreHTMLEngineContext } from "./AreHTML.context";
 import { AreHTMLNode } from "../lib/AreHTMLNode/AreHTMLNode";
 import { A_Frame } from "@adaas/a-frame/core";
+import { AreSchedulerHelper } from "@adaas/are-html/helpers/AreScheduler.helper";
 
 
 @A_Frame.Define({
@@ -18,6 +19,14 @@ import { A_Frame } from "@adaas/a-frame/core";
 })
 export class AreHTMLLifecycle extends AreLifecycle {
 
+    /**
+     * Per-chunk time budget (ms) for the time-sliced initial mount walk. While
+     * mounting a large subtree we keep applying nodes until this much wall-clock
+     * time has elapsed, then yield to the browser so it can paint and process
+     * input before the next chunk. ~16ms targets a single animation frame.
+     */
+    private static readonly MOUNT_BUDGET_MS = 16;
+
     @AreLifecycle.Init(AreComponentNode)
     initComponent(
         @A_Inject(A_Caller) node: AreHTMLNode,
@@ -92,7 +101,7 @@ export class AreHTMLLifecycle extends AreLifecycle {
 
         @A_Inject(A_Logger) logger?: A_Logger,
         ...args: any[]
-    ) {
+    ): void | Promise<void> {
 
         logger?.debug(`[Mount] Component Trigger for <${node.aseid.entity}>  with aseid :{${node.aseid.toString()}}`);
 
@@ -103,18 +112,86 @@ export class AreHTMLLifecycle extends AreLifecycle {
         if (scene.isInactive) return;
 
         /**
-         * 1. We should simply run and render node itself.
+         * 1. Render the root of this mount itself.
          */
         node.interpret();
+
         /**
-         * 2. Then go through all children of the node and mount the.
+         * 2. Walk the descendant subtree iteratively with an explicit enter/exit
+         *    stack so we can TIME-SLICE the work. The previous implementation
+         *    recursed via `child.mount()`, which fires onBeforeMount → onMount
+         *    (interpret + recurse) → onAfterMount per node and runs the whole tree
+         *    in one synchronous, un-yielding block. For large initial trees that
+         *    froze the main thread on first page load.
+         *
+         *    We replicate the exact per-node hook ordering:
+         *      - enter  → onBeforeMount, then (if active) interpret + queue children
+         *      - exit   → onAfterMount (fires AFTER the node's whole subtree, i.e.
+         *                 post-order, matching the recursive `node.mount()` contract)
+         *
+         *    Small trees complete entirely within a single time budget and the
+         *    handler returns `void` synchronously — a true fast-path with NO
+         *    behavioural change for typical UIs. Only genuinely large trees exceed
+         *    the budget, at which point we yield a macrotask (letting the browser
+         *    paint / stay responsive) and resume the remaining work, returning a
+         *    Promise that resolves when the whole subtree is mounted.
          */
-        for (let i = 0; i < node.children.length; i++) {
-            const child = node.children[i];
-            child.mount();
+        interface MountFrame { node: AreHTMLNode; entered: boolean; }
+
+        const stack: MountFrame[] = [];
+        for (let i = node.children.length - 1; i >= 0; i--) {
+            stack.push({ node: node.children[i] as AreHTMLNode, entered: false });
         }
+
+        const step = (): void => {
+            const frame = stack[stack.length - 1];
+            const current = frame.node;
+
+            if (frame.entered) {
+                // Post-order exit: the whole subtree below `current` is mounted.
+                stack.pop();
+                current.call(AreNodeFeatures.onAfterMount, current.scope);
+                return;
+            }
+
+            frame.entered = true;
+
+            // onBeforeMount always fires (even for inactive nodes), matching the
+            // recursive AreNode.mount() semantics.
+            current.call(AreNodeFeatures.onBeforeMount, current.scope);
+
+            if (!current.scene.isInactive) {
+                current.interpret();
+                // Push children in reverse so they pop in document order.
+                for (let i = current.children.length - 1; i >= 0; i--) {
+                    stack.push({ node: current.children[i] as AreHTMLNode, entered: false });
+                }
+            }
+        };
+
+        const drive = (): void | Promise<void> => {
+            const start = AreSchedulerHelper.now();
+            while (stack.length > 0) {
+                step();
+                if (stack.length > 0 && AreSchedulerHelper.now() - start >= AreHTMLLifecycle.MOUNT_BUDGET_MS) {
+                    // Budget exhausted with work remaining — yield, then resume.
+                    return new Promise<void>((resolve, reject) => {
+                        AreSchedulerHelper.scheduleMacrotask(() => {
+                            try {
+                                resolve(drive());
+                            } catch (error) {
+                                reject(error);
+                            }
+                        });
+                    });
+                }
+            }
+        };
+
+        return drive();
     }
 
+
     @A_Feature.Extend({
         name: AreAttributeFeatures.Update,
         scope: [AreDirectiveAttribute],

package/src/helpers/AreScheduler.helper.ts

@@ -0,0 +1,61 @@
+/**
+ * AreSchedulerHelper
+ *
+ * Cooperative time-slicing primitives shared by the chunked (async) render
+ * paths — the initial whole-page mount walk and the `$for` directive. Both need
+ * the SAME two capabilities:
+ *   1. a high-resolution clock to measure how long the current chunk has run, and
+ *   2. a zero-delay macrotask scheduler to yield to the browser between chunks
+ *      so it can paint and process input before resuming work.
+ *
+ * Keeping these in one helper avoids duplicating the `MessageChannel` plumbing
+ * across directives/lifecycle and gives a single place to tune the strategy.
+ */
+export class AreSchedulerHelper {
+
+    /**
+     * Lazily-created `MessageChannel` used to post zero-delay macrotasks.
+     * Created on first use so non-DOM environments (tests / SSR) that never
+     * schedule a chunk pay nothing.
+     */
+    private static _channel?: MessageChannel;
+
+    /** FIFO queue of callbacks waiting for their posted macrotask to fire. */
+    private static readonly _queue: Array<() => void> = [];
+
+    /**
+     * High-resolution wall-clock time in milliseconds. Uses `performance.now()`
+     * when available (monotonic, sub-millisecond), falling back to `Date.now()`.
+     */
+    static now(): number {
+        return (typeof performance !== 'undefined' && typeof performance.now === 'function')
+            ? performance.now()
+            : Date.now();
+    }
+
+    /**
+     * Schedule `fn` to run on the next macrotask.
+     *
+     * `MessageChannel` yields a true macrotask without the ~4ms clamp that nested
+     * `setTimeout(0)` calls incur, so the browser can paint between chunks with
+     * minimal scheduling overhead. Falls back to `setTimeout` in non-DOM
+     * environments (e.g. tests / SSR).
+     */
+    static scheduleMacrotask(fn: () => void): void {
+        if (typeof MessageChannel === 'undefined') {
+            setTimeout(fn, 0);
+            return;
+        }
+
+        if (!this._channel) {
+            this._channel = new MessageChannel();
+            this._channel.port1.onmessage = () => {
+                const next = this._queue.shift();
+                if (next) next();
+            };
+        }
+
+        this._queue.push(fn);
+        this._channel.port2.postMessage(null);
+    }
+}

package/src/lib/AreRoot/AreRoot.component.ts

@@ -160,7 +160,10 @@ export class AreRoot extends Are {
             child.transform();
 
             child.compile();
-            child.mount();
+            // The HTML engine time-slices large initial mounts; await so a heavy
+            // routed component renders in yielding chunks instead of freezing the
+            // main thread on first entry. Small subtrees resolve synchronously.
+            await child.mount();
         }
     }
 

package/tsconfig.json

@@ -15,6 +15,7 @@
       "@adaas/are-html/instructions/*": ["src/instructions/*"],
       "@adaas/are-html/watchers/*": ["src/watchers/*"],
       "@adaas/are-html/signals/*": ["src/signals/*"],
+      "@adaas/are-html/helpers/*": ["src/helpers/*"],
       // Custom Lib Exports
       "@adaas/are-html/style/*": ["src/lib/AreStyle/*"],
       "@adaas/are-html/directive/*": ["src/lib/AreDirective/*"],