@adaas/are-html 0.0.20 → 0.0.22

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/index.ts

@@ -12,6 +12,7 @@ export * from './attributes/AreStatic.attribute';
 export * from './directives/AreComponent.directive';
 export * from './directives/AreDirectiveFor.directive';
 export * from './directives/AreDirectiveIf.directive';
+export * from './directives/AreDirectiveShow.directive';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // ── Instructions ─────────────────────────────────────────────────────────────
@@ -22,6 +23,7 @@ export * from './instructions/AddInterpolation.instruction';
 export * from './instructions/AddListener.instruction';
 export * from './instructions/AddStyle.instruction';
 export * from './instructions/AddText.instruction';
+export * from './instructions/HideElement.instruction';
 export * from './instructions/AreHTML.instructions.constants';
 export * from './instructions/AreHTML.instructions.types';
 
@@ -67,6 +69,7 @@ export * from './lib/AreDirective/AreDirective.types';
 // ── Lib / AreRoot ────────────────────────────────────────────────────────────
 // ─────────────────────────────────────────────────────────────────────────────
 export * from './lib/AreRoot/AreRoot.component';
+export * from './lib/AreRoot/AreRootCache.context';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // ── Lib / AreStyle ───────────────────────────────────────────────────────────

package/src/instructions/AreHTML.instructions.constants.ts

@@ -8,4 +8,5 @@ export const AreHTMLInstructions = {
     AddListener: '_AreHTML_AddListener',
     AddInterpolation: '_AreHTML_AddInterpolation',
     AddComment: '_AreHTML_AddComment',
+    HideElement: '_AreHTML_HideElement',
 } as const

package/src/instructions/AreHTML.instructions.types.ts

@@ -34,6 +34,15 @@ export type AreHtmlAddStyleInstructionPayload = {
     styles: string;
 }
 
+export type AreHtmlHideInstructionPayload = {
+    /**
+     * Optional explicit display value to restore when the element becomes
+     * visible again. When omitted, the interpreter caches and restores the
+     * element's own prior inline `display` value (Vue `v-show` semantics).
+     */
+    display?: string;
+}
+
 export type AreHtmlAddListenerInstructionPayload = {
     /** DOM event name (e.g. "click", "input", "submit") */
     name: string;

package/src/instructions/HideElement.instruction.ts

@@ -0,0 +1,29 @@
+import { A_Frame } from "@adaas/a-frame/core"
+import { AreDeclaration, AreMutation, AreInstructionSerialized } from "@adaas/are";
+import { AreHtmlHideInstructionPayload } from "./AreHTML.instructions.types";
+import { AreHTMLInstructions } from "./AreHTML.instructions.constants";
+
+
+@A_Frame.Define({
+    namespace: 'a-are-html',
+    description: 'Toggles the visibility of an existing element by setting its inline display to "none" on apply and restoring the previous inline display on revert. Used by the $show directive to hide/show an element without unmounting it, preserving its subtree, listeners and scene state.'
+})
+export class HideElementInstruction extends AreMutation<AreHtmlHideInstructionPayload> {
+
+    /**
+     * Caches the element's inline `display` value captured at apply time so it
+     * can be restored verbatim on revert (mirrors Vue `v-show`).
+     */
+    cache?: string;
+
+    constructor(
+        parent: AreDeclaration,
+        props: AreHtmlHideInstructionPayload | AreInstructionSerialized<AreHtmlHideInstructionPayload>
+    ) {
+        if ('aseid' in props) {
+            super(props as AreInstructionSerialized<AreHtmlHideInstructionPayload>);
+        } else {
+            super(AreHTMLInstructions.HideElement, parent, props);
+        }
+    }
+}

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

@@ -1,9 +1,10 @@
-import { A_Caller, A_Context, A_FormatterHelper, A_Inject, } from "@adaas/a-concept";
+import { A_Caller, A_Context, A_FormatterHelper, A_Inject, A_TYPES__Ctor } from "@adaas/a-concept";
 import { A_Frame } from "@adaas/a-frame/core";
 import { A_Logger } from "@adaas/a-utils/a-logger";
-import { A_SignalVector } from "@adaas/a-utils/a-signal";
+import { A_Signal, A_SignalState, A_SignalVector } from "@adaas/a-utils/a-signal";
 import { Are, AreNode, AreSignals, AreSignalsMeta, AreSignalsContext } from "@adaas/are";
 import { AreRoute } from "@adaas/are-html/signals/AreRoute.signal";
+import { AreRootCache, AreRootCacheEntry } from "./AreRootCache.context";
 
 
 @A_Frame.Define({
@@ -17,6 +18,7 @@ export class AreRoot extends Are {
         @A_Inject(A_Caller) root: AreNode,
         @A_Inject(A_Logger) logger: A_Logger,
         @A_Inject(AreSignalsContext) signalsContext?: AreSignalsContext,
+        @A_Inject(A_SignalState) signalState?: A_SignalState,
     ) {
 
         const rootId = root.id;
@@ -36,39 +38,19 @@ export class AreRoot extends Are {
             return;
         }
 
-        const currentRoute = AreRoute.default();
-
-        let componentName: string | undefined;
-
-        if (currentRoute) {
-            const initialVector = new A_SignalVector([currentRoute]);
-
-            // 1. Lookup via AreSignalsContext (per root-id conditions)
-            let renderTarget = signalsContext?.findComponentByVector(rootId, initialVector);
-
-            // 2. Fall back to global AreSignalsMeta, pool-filtered.
-            // IMPORTANT: pass the pool *into* the lookup so it can skip over
-            // out-of-pool matches (e.g. a meta-outlet component whose condition
-            // also matches the same vector) and find the highest-priority match
-            // that this outlet can actually render. Filtering only after the
-            // fact would mask valid in-pool matches and surface the outlet's
-            // default instead.
-            if (!renderTarget) {
-                const signalsMeta = A_Context.meta<AreSignalsMeta>(AreSignals);
-                const pool = signalsContext?.getComponentById(rootId);
-                const metaTarget = signalsMeta?.findComponentByVector(
-                    initialVector,
-                    pool?.length ? pool : undefined,
-                );
-                if (metaTarget && (!pool?.length || pool.includes(metaTarget))) {
-                    renderTarget = metaTarget;
-                }
-            }
+        // Select from the ACCUMULATED signal state (every signal dispatched so
+        // far), not just the current URL route. Outlets keyed on domain signals
+        // (e.g. a primary-display selector) must reflect the live vector the
+        // moment they mount — even when they mount AFTER the routing signal was
+        // dispatched (a nested outlet inside a just-rendered parent). Using the
+        // same vector + lookup as onSignal keeps initial render and subsequent
+        // updates consistent.
+        const initialVector = this.buildInitialVector(signalState);
+        const renderTarget = this.matchComponent(rootId, initialVector, signalsContext);
 
-            if (renderTarget?.name) {
-                componentName = A_FormatterHelper.toKebabCase(renderTarget.name);
-            }
-        }
+        let componentName: string | undefined = renderTarget?.name
+            ? A_FormatterHelper.toKebabCase(renderTarget.name)
+            : undefined;
 
         // 3. Fall back to body content (the nodes already placed inside the
         //    <are-root> tag act as the default).  No setContent() call needed —
@@ -106,6 +88,7 @@ export class AreRoot extends Are {
         @A_Inject(A_SignalVector) vector: A_SignalVector,
         @A_Inject(A_Logger) logger: A_Logger,
         @A_Inject(AreSignalsContext) signalsContext?: AreSignalsContext,
+        @A_Inject(AreRootCache) cache?: AreRootCache,
     ) {
         const rootId = root.id;
 
@@ -114,27 +97,10 @@ export class AreRoot extends Are {
             return;
         }
 
-        // 1. Try root-specific lookup via AreSignalsContext (keyed by the are-root's id attribute)
-        let renderTarget = signalsContext?.findComponentByVector(rootId, vector);
-
-        // 2. Fall back to global AreSignalsMeta lookup, restricted to this
-        //    outlet's pool. Passing the pool *into* the lookup is critical:
-        //    without it, the first globally matching component wins and may
-        //    belong to a different outlet (e.g. AisRequirementsPanel for the
-        //    meta-outlet matching AisEditorCursorScope) — the pool check then
-        //    rejects it and the outlet falls back to default, hiding a valid
-        //    in-pool match (e.g. AisDiagramTab matching AisSetPrimaryDisplay).
-        if (!renderTarget) {
-            const signalsMeta = A_Context.meta<AreSignalsMeta>(AreSignals);
-            const pool = signalsContext?.getComponentById(rootId);
-            const metaTarget = signalsMeta?.findComponentByVector(
-                vector,
-                pool?.length ? pool : undefined,
-            );
-            if (metaTarget && (!pool?.length || pool.includes(metaTarget))) {
-                renderTarget = metaTarget;
-            }
-        }
+        // Resolve the target component for the incoming vector using the SAME
+        // lookup the initial template render uses (root-id conditions first,
+        // then the global pool-filtered meta map).
+        const renderTarget = this.matchComponent(rootId, vector, signalsContext);
 
         const def = signalsContext?.getDefault(rootId);
         const componentName = renderTarget?.name
@@ -145,12 +111,8 @@ export class AreRoot extends Are {
 
         // No matching condition for this signal vector and no default — clear the outlet.
         if (!componentName) {
-            for (let i = 0; i < root.children.length; i++) {
-                const child = root.children[i];
-                signalsContext?.unsubscribe(child);
-                child.unmount();
-                child.destroy();
-                root.removeChild(child);
+            for (const child of [...root.children]) {
+                this.stashChild(root, child, signalsContext, cache);
             }
             root.setContent('');
             return;
@@ -166,20 +128,25 @@ export class AreRoot extends Are {
             return;
         }
 
+        // Stash the currently displayed children so routing back to them can be
+        // re-injected instantly from the cache (they are unmounted + detached but
+        // NOT destroyed). Falls back to full teardown when no cache is available.
+        for (const child of [...root.children]) {
+            this.stashChild(root, child, signalsContext, cache);
+        }
+
         root.setContent(`<${componentName}></${componentName}>`);
 
-        // Unsubscribe old children BEFORE destroying them.
-        // Without this, AreSignals.handleSignalVector keeps iterating stale
-        // (scope-less) nodes on every subsequent signal and throws an error.
-        for (let i = 0; i < root.children.length; i++) {
-            const child = root.children[i];
-            signalsContext?.unsubscribe(child);
-            child.unmount();
-            child.destroy();
-            root.removeChild(child);
+        // Fast path: a previously rendered subtree for this component is cached —
+        // re-attach it and re-mount from the preserved scene plan, skipping the
+        // expensive tokenize/init/load/transform/compile pipeline.
+        const cached = cache?.take(root.id, componentName);
+        if (cached) {
+            this.restoreChild(root, cached, signalsContext);
+            return;
         }
 
-
+        // Slow path: build the component subtree from scratch.
         root.tokenize();
 
         for (let i = 0; i < root.children.length; i++) {
@@ -193,7 +160,173 @@ 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();
+        }
+    }
+
+    /**
+     * Resolves the component a vector should render for the given root, mirroring
+     * the priority used everywhere in the routing system:
+     *   1. Root-specific conditions registered on AreSignalsContext.
+     *   2. The global AreSignalsMeta map, restricted to this outlet's pool.
+     *
+     * Passing the pool *into* the meta lookup is critical: without it, the first
+     * globally matching component wins and may belong to a different outlet
+     * (e.g. AisRequirementsPanel for the meta-outlet matching
+     * AisEditorCursorScope) — the pool check would then reject it and the outlet
+     * would fall back to its default, hiding a valid in-pool match (e.g.
+     * AisDiagramTab matching AisSetPrimaryDisplay).
+     *
+     * Returns `undefined` when nothing matches — callers decide whether to use a
+     * configured default, body content, or clear the outlet.
+     */
+    protected matchComponent(
+        rootId: string,
+        vector: A_SignalVector | undefined,
+        signalsContext?: AreSignalsContext,
+    ): A_TYPES__Ctor<Are> | undefined {
+        if (!vector) return undefined;
+
+        // 1. Root-specific conditions.
+        let renderTarget = signalsContext?.findComponentByVector(rootId, vector);
+
+        // 2. Global pool-filtered meta map.
+        if (!renderTarget) {
+            const signalsMeta = A_Context.meta<AreSignalsMeta>(AreSignals);
+            const pool = signalsContext?.getComponentById(rootId);
+            const metaTarget = signalsMeta?.findComponentByVector(
+                vector,
+                pool?.length ? pool : undefined,
+                rootId,
+            );
+            if (metaTarget && (!pool?.length || pool.includes(metaTarget))) {
+                renderTarget = metaTarget;
+            }
+        }
+
+        return renderTarget as A_TYPES__Ctor<Are> | undefined;
+    }
+
+    /**
+     * Builds the vector used for the INITIAL render. It is seeded from the
+     * accumulated signal state (every signal dispatched on the bus so far) so a
+     * freshly-mounted outlet reflects the live application state immediately,
+     * not just on the next signal tick. The current URL route is appended when
+     * no AreRoute is already present in the state, so route-driven outlets still
+     * resolve on the very first paint (before AreRouteWatcher has dispatched).
+     */
+    protected buildInitialVector(signalState?: A_SignalState): A_SignalVector {
+        const signals: A_Signal[] = [];
+
+        if (signalState) {
+            for (const signal of signalState.toVector()) {
+                if (signal) signals.push(signal);
+            }
+        }
+
+        if (!signals.some(signal => signal instanceof AreRoute)) {
+            try {
+                const currentRoute = AreRoute.default();
+                if (currentRoute) signals.push(currentRoute);
+            } catch {
+                // Non-browser environment (no document) — route is simply absent.
+            }
+        }
+
+        return new A_SignalVector(signals);
+    }
+
+    /**
+     * Detach a displayed child subtree from the outlet and stash it in the cache
+     * for fast re-injection later. The subtree is unmounted (its scene plan is
+     * preserved) and deregistered from the root scope, but NOT destroyed. The
+     * nodes that were subscribed to the signal bus are unsubscribed while cached
+     * so the detached DOM never reacts to signals, and recorded so they can be
+     * re-subscribed verbatim on restore.
+     *
+     * When no cache is available, or the LRU evicts an entry, the affected
+     * subtree is fully destroyed.
+     */
+    protected stashChild(
+        root: AreNode,
+        child: AreNode,
+        signalsContext: AreSignalsContext | undefined,
+        cache: AreRootCache | undefined,
+    ): void {
+        const tag = child.type;
+
+        child.unmount();
+
+        // Collect exactly the nodes that are currently subscribed within this
+        // subtree, then unsubscribe them. Without this, AreSignals keeps
+        // delivering vectors to a detached subtree that would update reverted
+        // DOM (unmount does not deactivate the scene).
+        const subscribers = signalsContext
+            ? this.collectSubscribers(child, signalsContext)
+            : [];
+        for (const node of subscribers) {
+            signalsContext?.unsubscribe(node);
+        }
+
+        // Deregister from the root scope (the "deregister node from parent").
+        root.removeChild(child);
+
+        if (!cache) {
+            void child.destroy();
+            return;
+        }
+
+        const evicted = cache.put(root.id, tag, { node: child, subscribers });
+        for (const entry of evicted) {
+            // Evicted entries are already unmounted + unsubscribed + detached.
+            void entry.node.destroy();
+        }
+    }
+
+    /**
+     * Re-attach a cached subtree to the outlet and re-mount it from its preserved
+     * scene plan, re-subscribing exactly the nodes that were subscribed before it
+     * was cached.
+     */
+    protected restoreChild(
+        root: AreNode,
+        entry: AreRootCacheEntry,
+        signalsContext: AreSignalsContext | undefined,
+    ): void {
+        const child = entry.node;
+
+        root.addChild(child);
+
+        for (const node of entry.subscribers) {
+            signalsContext?.subscribe(node);
+        }
+
+        child.mount();
+    }
+
+    /**
+     * Walk a subtree and collect the nodes currently registered as signal
+     * subscribers. Mirrors the subscription performed at init time in
+     * AreHTMLLifecycle (component nodes and root nodes) without depending on the
+     * concrete node classes — it simply intersects the subtree with the live
+     * subscriber registry.
+     */
+    protected collectSubscribers(
+        node: AreNode,
+        signalsContext: AreSignalsContext,
+    ): AreNode[] {
+        const result: AreNode[] = [];
+        const queue: AreNode[] = [node];
+        while (queue.length > 0) {
+            const current = queue.shift()!;
+            if (signalsContext.subscribers.has(current)) {
+                result.push(current);
+            }
+            queue.push(...current.children);
         }
+        return result;
     }
 }