@adaas/are-html 0.0.22 → 0.0.23

package/src/engine/AreHTML.interpreter.ts

@@ -15,6 +15,7 @@ import { AddElementInstruction } from "@adaas/are-html/instructions/AddElement.i
 import { AddListenerInstruction } from "@adaas/are-html/instructions/AddListener.instruction";
 import { AddTextInstruction } from "@adaas/are-html/instructions/AddText.instruction";
 import { AddStyleInstruction } from "@adaas/are-html/instructions/AddStyle.instruction";
+import { AddStaticHTMLInstruction } from "@adaas/are-html/instructions/AddStaticHTML.instruction";
 import { HideElementInstruction } from "@adaas/are-html/instructions/HideElement.instruction";
 import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 import { AreHTMLNode } from "../lib/AreHTMLNode/AreHTMLNode";
@@ -84,16 +85,25 @@ export class AreHTMLInterpreter extends AreInterpreter {
                     ? context.container.createElementNS(SVG_NAMESPACE, tag)
                     : context.container.createElement(tag);
 
-                if (mountPoint.nodeType === Node.ELEMENT_NODE) {
+                // Index the element synchronously so descendants can resolve this
+                // node as their mount point during the same (still off-document) pass.
+                context.setInstructionElement(declaration, element);
+
+                const attach = mountPoint.nodeType === Node.ELEMENT_NODE
                     // parent is a real element — just append
-                    mountPoint.appendChild(element);
-                } else {
+                    ? () => mountPoint.appendChild(element)
                     // parent is an anchor (comment/text node) — insert before it
                     // so content always appears before the anchor marker
-                    mountPoint.parentNode?.insertBefore(element, mountPoint);
-                }
+                    : () => { mountPoint.parentNode?.insertBefore(element, mountPoint); };
 
-                context.setInstructionElement(declaration, element);
+                // When batching, only the mutation that touches the *live* document
+                // needs deferring; appends into an already-detached subtree are free
+                // and run immediately so the offline tree keeps taking shape.
+                if (context.isBatching && mountPoint.isConnected) {
+                    context.deferAttach(attach);
+                } else {
+                    attach();
+                }
 
             } else {
                 const mountPoint = context.container.getElementById(node.id);
@@ -108,9 +118,17 @@ export class AreHTMLInterpreter extends AreInterpreter {
                     ? context.container.createElementNS(SVG_NAMESPACE, tag)
                     : context.container.createElement(tag);
 
-                mountPoint.parentNode?.replaceChild(element, mountPoint);
-
                 context.setInstructionElement(declaration, element);
+
+                const attach = () => { mountPoint.parentNode?.replaceChild(element, mountPoint); };
+
+                // The placeholder lives in the live DOM — defer the swap so the
+                // whole subtree built into `element` lands in one mutation.
+                if (context.isBatching && mountPoint.isConnected) {
+                    context.deferAttach(attach);
+                } else {
+                    attach();
+                }
             }
 
             // Register the element in the context index
@@ -135,7 +153,12 @@ export class AreHTMLInterpreter extends AreInterpreter {
     ) {
         const element = context.getElementByInstruction(declaration);
 
-        if (element && element.parentNode) {
+        // Skip the live-DOM detach when the element is already off-document: an
+        // ancestor removed earlier in the same unmount took this whole subtree
+        // with it, and a detached subtree is garbage-collected as a unit. The
+        // per-node removeChild would be wasted work. The index bookkeeping below
+        // must still run to drop the strong references that would pin it in memory.
+        if (element && element.parentNode && element.isConnected) {
             element.parentNode.removeChild(element);
         }
 
@@ -283,7 +306,10 @@ export class AreHTMLInterpreter extends AreInterpreter {
 
             const { name } = mutation.payload;
 
-            if (name && element.nodeType === Node.ELEMENT_NODE) {
+            // No point stripping attributes off an element that is already
+            // detached from the live document (it is about to be discarded with
+            // its whole subtree). Only touch attributes while the element is live.
+            if (name && element.nodeType === Node.ELEMENT_NODE && element.isConnected) {
                 const colonIdx = name.indexOf(':');
                 if (colonIdx > 0) {
                     const ns = SVG_ATTRIBUTE_NS[name.slice(0, colonIdx)];
@@ -343,6 +369,10 @@ export class AreHTMLInterpreter extends AreInterpreter {
 
         if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
 
+        // A detached element is being discarded with its subtree — restoring its
+        // inline display would be pointless work. Only restore while it is live.
+        if (!element.isConnected) return;
+
         const el = element as HTMLElement;
 
         // Restore the cached inline display. An explicit payload display, when
@@ -510,7 +540,12 @@ export class AreHTMLInterpreter extends AreInterpreter {
         const listener = (mutation.payload as any)._callback as EventListenerOrEventListenerObject | undefined;
 
         if (listener) {
-            element.removeEventListener(eventName, listener);
+            // Detaching a listener from an element that is already off-document is
+            // unnecessary — the element and its listeners are collected together.
+            // Still clear the context bookkeeping so no strong reference lingers.
+            if (element.isConnected) {
+                element.removeEventListener(eventName, listener);
+            }
             context.removeListener(element, name, listener);
             (mutation.payload as any)._callback = undefined;
         }
@@ -592,11 +627,73 @@ export class AreHTMLInterpreter extends AreInterpreter {
 
         if (!element) return;
 
-        element.parentNode?.removeChild(element);
+        // Off-document text nodes vanish with their detached parent subtree, so
+        // skip the removeChild and just release the index reference.
+        if (element.isConnected) {
+            element.parentNode?.removeChild(element);
+        }
         context.removeInstructionElement(declaration);
     }
 
 
+    // ─────────────────────────────────────────────────────────────────────────────
+    // ── AddStaticHTML — Apply / Update / Revert ──────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Materialises a fully static subtree (a "static island") onto its host
+    // element in a single pass. The tokenizer captured the inner markup verbatim
+    // instead of exploding it into per-element/per-text AreNodes, so here we hand
+    // the markup to the browser parser ONCE (via a cached <template>) and clone
+    // the pre-parsed fragment in. This collapses N DOM mutations into one and
+    // decodes HTML entities (e.g. &nbsp;) natively.
+    @A_Frame.Define({
+        description: 'Inject a static island\'s inner markup onto its host element in one pass via a cached, browser-parsed <template> clone. Decodes HTML entities natively.'
+    })
+    @AreInterpreter.Apply(AreHTMLInstructions.AddStaticHTML)
+    @AreInterpreter.Update(AreHTMLInstructions.AddStaticHTML)
+    addStaticHTML(
+        @A_Inject(A_Caller) mutation: AddStaticHTMLInstruction,
+        @A_Inject(AreHTMLEngineContext) context: AreHTMLEngineContext,
+        @A_Inject(A_Logger) logger?: A_Logger,
+    ) {
+        const element = context.getElementByInstruction(mutation.parent!);
+
+        if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+            throw new AreInterpreterError({
+                title: 'Element Not Found',
+                description: `Could not find a DOM element associated with the instruction ASEID "${mutation.parent}". Ensure the host element is rendered before materialising its static island.`
+            });
+        }
+
+        const el = element as HTMLElement;
+        const { html } = mutation.payload;
+
+        // Clear any previously injected content (Update path) before re-injecting.
+        el.textContent = '';
+
+        // Parse once (in the host tag's context) and clone the cached fragment.
+        const fragment = context.getStaticFragment(el.tagName.toLowerCase(), html);
+        el.appendChild(fragment.cloneNode(true));
+
+        logger?.debug('green', `Static island materialised onto <${(mutation.owner.parent ?? mutation.owner)?.aseid?.toString?.()}>`);
+    }
+
+
+    @A_Frame.Define({
+        description: 'Clear a static island\'s injected markup from its host element on revert.'
+    })
+    @AreInterpreter.Revert(AreHTMLInstructions.AddStaticHTML)
+    removeStaticHTML(
+        @A_Inject(A_Caller) mutation: AddStaticHTMLInstruction,
+        @A_Inject(AreHTMLEngineContext) context: AreHTMLEngineContext,
+    ) {
+        const element = context.getElementByInstruction(mutation.parent!);
+
+        if (element && element.nodeType === Node.ELEMENT_NODE && element.isConnected) {
+            (element as HTMLElement).textContent = '';
+        }
+    }
+
+
 
     @A_Frame.Define({
         description: 'Add a comment node to the DOM based on the provided declaration instruction.'
@@ -667,7 +764,11 @@ export class AreHTMLInterpreter extends AreInterpreter {
 
         if (!element) return;
 
-        element.parentNode?.removeChild(element);
+        // Off-document comment anchors are discarded with their detached parent
+        // subtree; skip the removeChild and just release the index reference.
+        if (element.isConnected) {
+            element.parentNode?.removeChild(element);
+        }
         context.removeInstructionElement(declaration);
     }
 

package/src/engine/AreHTML.lifecycle.ts

@@ -10,7 +10,6 @@ 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({
@@ -19,14 +18,6 @@ import { AreSchedulerHelper } from "@adaas/are-html/helpers/AreScheduler.helper"
 })
 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,
@@ -112,83 +103,99 @@ export class AreHTMLLifecycle extends AreLifecycle {
         if (scene.isInactive) return;
 
         /**
-         * 1. Render the root of this mount itself.
-         */
-        node.interpret();
-
-        /**
-         * 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.
+         * Open a batching scope for the whole (synchronous) mount pass. Every
+         * element created below is built into a *detached* root and attached to
+         * the live DOM only when the batch flushes — turning O(nodes) reflows into
+         * a single one per mount root. `try/finally` guarantees the batch closes
+         * (and the depth counter stays balanced) even if interpretation throws.
          *
-         *    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.
+         * The context is resolved from the node's scope (the scope the onMount
+         * feature runs in) so the override keeps the base `mount` signature.
          */
-        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 context = node.scope.resolve<AreHTMLEngineContext>(AreHTMLEngineContext);
 
-        const step = (): void => {
-            const frame = stack[stack.length - 1];
-            const current = frame.node;
+        context?.beginBatch();
 
-            if (frame.entered) {
-                // Post-order exit: the whole subtree below `current` is mounted.
-                stack.pop();
-                current.call(AreNodeFeatures.onAfterMount, current.scope);
-                return;
+        /**
+         * `onAfterMount` must observe the node already connected to the live
+         * document (consumer components may measure layout / focus there). Since
+         * the subtree is built off-document and attached only when the batch
+         * flushes, we collect the post-order `onAfterMount` targets here and fire
+         * them once the flush has connected everything.
+         */
+        const afterMountQueue: AreHTMLNode[] = [];
+
+        try {
+            /**
+             * 1. Render the root of this mount itself.
+             */
+            node.interpret();
+
+            /**
+             * 2. Walk the descendant subtree iteratively with an explicit enter/exit
+             *    stack. We keep the iterative (non-recursive) shape — it is cheaper
+             *    than deep recursion and gives us a single, clear place that owns the
+             *    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)
+             *
+             * [!] The initial mount is intentionally ATOMIC (fully synchronous). It
+             *     does NOT time-slice / yield. Yielding mid-walk exposes a partially
+             *     mounted tree to the event loop: any update dispatched during a gap
+             *     (signal-driven re-render, async data load, etc.) interprets a node
+             *     whose parent has not been mounted yet — producing
+             *     `mount-point-not-found` and out-of-order DOM. The whole page must
+             *     therefore appear in the DOM in one uninterrupted pass. Heavy lists
+             *     are sliced at the source instead (see AreDirectiveFor), where the
+             *     batching is reentrancy-safe.
+             */
+            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 });
             }
 
-            frame.entered = true;
+            while (stack.length > 0) {
+                const frame = stack[stack.length - 1];
+                const current = frame.node;
+
+                if (frame.entered) {
+                    // Post-order exit: the whole subtree below `current` is mounted.
+                    // Defer the onAfterMount hook until after the batch flush so the
+                    // node is connected to the live DOM when it runs.
+                    stack.pop();
+                    afterMountQueue.push(current);
+                    continue;
+                }
 
-            // onBeforeMount always fires (even for inactive nodes), matching the
-            // recursive AreNode.mount() semantics.
-            current.call(AreNodeFeatures.onBeforeMount, current.scope);
+                frame.entered = true;
 
-            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 });
-                }
-            }
-        };
+                // onBeforeMount always fires (even for inactive nodes), matching the
+                // recursive AreNode.mount() semantics.
+                current.call(AreNodeFeatures.onBeforeMount, current.scope);
 
-        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);
-                            }
-                        });
-                    });
+                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 });
+                    }
                 }
             }
-        };
+        } finally {
+            // Flush the deferred attachments — the fully built subtree lands in the
+            // live DOM in a single pass.
+            context?.endBatch();
+        }
 
-        return drive();
+        // The subtree is now connected; fire onAfterMount in the original
+        // post-order, each with its node live in the document.
+        for (let i = 0; i < afterMountQueue.length; i++) {
+            const mounted = afterMountQueue[i];
+            mounted.call(AreNodeFeatures.onAfterMount, mounted.scope);
+        }
     }
 
 

package/src/engine/AreHTML.tokenizer.ts

@@ -8,6 +8,8 @@ import { AreEventAttribute } from "@adaas/are-html/attributes/AreEvent.attribute
 import { AreBindingAttribute } from "@adaas/are-html/attributes/AreBinding.attribute";
 import { AreStaticAttribute } from "@adaas/are-html/attributes/AreStatic.attribute";
 import { AreHTMLAttribute } from "../lib/AreHTMLAttribute/AreHTML.attribute";
+import { AreHTMLNode } from "../lib/AreHTMLNode/AreHTMLNode";
+import { isStaticMarkup } from "./AreHTML.constants";
 import { A_Frame } from "@adaas/a-frame/core";
 
 
@@ -30,7 +32,34 @@ export class AreHTMLTokenizer extends AreTokenizer {
         @A_Inject(A_Logger) logger?: A_Logger
     ): void {
 
-        super.tokenize(node, context, logger);
+        /**
+         * Static-island fast path.
+         *
+         * When a node's entire inner subtree is fully static — no `{{ }}`
+         * interpolations, no dynamic (`$`/`:`/`@`) attributes and only standard
+         * HTML tags — we skip exploding it into one child AreNode per element /
+         * text run and instead capture the inner markup verbatim. The interpreter
+         * later materialises it in a single pass (browser-parsed innerHTML /
+         * cached `<template>` clone), which:
+         *   - eliminates N node + scope + scene + instruction allocations,
+         *   - collapses N isolated DOM mutations into one, and
+         *   - decodes HTML entities (e.g. `&nbsp;`) for free.
+         *
+         * Routing outlets (AreRootNode) are intentionally excluded — they own
+         * their content dynamically. The node's OWN attributes are still
+         * extracted below, so a dynamic attribute on the island root itself
+         * (e.g. `<div :class="x"> …static… </div>`) keeps working.
+         */
+        const isStaticIsland =
+            node instanceof AreComponentNode &&
+            !!node.content &&
+            isStaticMarkup(node.content);
+
+        if (isStaticIsland) {
+            (node as AreHTMLNode).markStatic(node.content);
+        } else {
+            super.tokenize(node, context, logger);
+        }
 
         context.startPerformance('attributeExtraction');
 

package/src/index.ts

@@ -21,6 +21,7 @@ export * from './instructions/AddAttribute.instruction';
 export * from './instructions/AddElement.instruction';
 export * from './instructions/AddInterpolation.instruction';
 export * from './instructions/AddListener.instruction';
+export * from './instructions/AddStaticHTML.instruction';
 export * from './instructions/AddStyle.instruction';
 export * from './instructions/AddText.instruction';
 export * from './instructions/HideElement.instruction';

package/src/instructions/AddStaticHTML.instruction.ts

@@ -0,0 +1,23 @@
+import { A_Frame } from "@adaas/a-frame/core"
+import { AreDeclaration, AreMutation, AreInstructionSerialized } from "@adaas/are";
+import { AreHtmlAddStaticHTMLInstructionPayload } from "./AreHTML.instructions.types";
+import { AreHTMLInstructions } from "./AreHTML.instructions.constants";
+
+
+@A_Frame.Define({
+    namespace: 'a-are-html',
+    description: 'Materialises a fully static subtree (a "static island") onto its parent element in a single pass via browser-parsed innerHTML / a cached <template> clone. Apply injects the markup; revert clears it. Decodes HTML entities (e.g. &nbsp;) for free.'
+})
+export class AddStaticHTMLInstruction extends AreMutation<AreHtmlAddStaticHTMLInstructionPayload> {
+
+    constructor(
+        parent: AreDeclaration,
+        props: AreHtmlAddStaticHTMLInstructionPayload | AreInstructionSerialized<AreHtmlAddStaticHTMLInstructionPayload>
+    ) {
+        if ('aseid' in props) {
+            super(props as AreInstructionSerialized<AreHtmlAddStaticHTMLInstructionPayload>);
+        } else {
+            super(AreHTMLInstructions.AddStaticHTML, parent, props);
+        }
+    }
+}

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

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

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

@@ -34,6 +34,15 @@ export type AreHtmlAddStyleInstructionPayload = {
     styles: string;
 }
 
+export type AreHtmlAddStaticHTMLInstructionPayload = {
+    /**
+     * Verbatim inner markup of a static island, materialised on the parent
+     * element in a single pass (browser-parsed `innerHTML` / cached `<template>`
+     * clone). Decodes HTML entities (e.g. `&nbsp;`) for free via the parser.
+     */
+    html: string;
+}
+
 export type AreHtmlHideInstructionPayload = {
     /**
      * Optional explicit display value to restore when the element becomes

package/src/lib/AreHTMLNode/AreHTMLNode.ts

@@ -16,6 +16,19 @@ import { AreDirectiveMeta } from "@adaas/are-html/directive/AreDirective.meta";
     description: 'AreHTMLNode represents a node in the HTML structure. It extends the base AreNode and includes properties and methods specific to HTML nodes, such as handling attributes, directives, events, and styles.'
 })
 export class AreHTMLNode extends AreNode {
+    /**
+     * When set, this node is a *static island* root: its entire inner subtree
+     * was detected (at tokenize time) to contain no ARE-reactive constructs —
+     * no interpolations, no dynamic attributes and only standard HTML tags.
+     *
+     * Instead of being exploded into one child AreNode per element/text node,
+     * the inner markup is preserved verbatim here and materialised in a single
+     * pass by the interpreter (browser-parsed `innerHTML` / cached `<template>`
+     * clone). The node's OWN attributes (including any dynamic `:`/`@`/`$` on
+     * the island root) still compile and stay reactive as usual.
+     */
+    protected _staticInnerHTML?: string;
+
     /**
      * Actual node type. 
      * By default it's a tag name
@@ -23,6 +36,67 @@ export class AreHTMLNode extends AreNode {
     get tag(): string {
         return this.aseid.entity;
     }
+
+    /**
+     * The verbatim inner markup captured when this node was identified as a
+     * static island, or `undefined` for ordinary (per-node) nodes.
+     */
+    get staticInnerHTML(): string | undefined {
+        return this._staticInnerHTML;
+    }
+
+    /**
+     * Whether this node is a static-island root (see `_staticInnerHTML`).
+     */
+    get isStaticIsland(): boolean {
+        return this._staticInnerHTML !== undefined;
+    }
+
+    /**
+     * Marks this node as a static-island root, capturing the verbatim inner
+     * markup to be materialised in one shot by the interpreter. Called by the
+     * tokenizer when the node's inner content is detected to be fully static.
+     */
+    markStatic(innerHTML: string): void {
+        this._staticInnerHTML = innerHTML;
+    }
+
+    /**
+     * Deep-clone the node. Overridden to carry over the static-island marker
+     * (`_staticInnerHTML`), which lives on AreHTMLNode and is therefore NOT
+     * copied by the base AreNode.clone(). Without this, cloning a directive
+     * template ($if/$for) that wraps a static island (e.g. `<span $if>★</span>`)
+     * would drop the captured inner markup and render an empty element. The
+     * base clone() recurses via each child's polymorphic clone(), so nested
+     * island children are preserved automatically through this override.
+     */
+    clone<T extends AreNode = AreNode>(this: T): T {
+        const cloned = super.clone() as unknown as AreHTMLNode;
+        const self = this as unknown as AreHTMLNode;
+
+        if (self._staticInnerHTML !== undefined)
+            cloned.markStatic(self._staticInnerHTML);
+
+        return cloned as unknown as T;
+    }
+
+    /**
+     * Clone the node while transferring its existing scope to the clone (used by
+     * the $if/$for directives to turn the original node into a lightweight group
+     * container). Overridden for the same reason as `clone()`: the static-island
+     * marker must survive so a directive applied to an island root keeps its
+     * inner markup.
+     */
+    cloneWithScope<T extends AreNode = AreNode>(this: T): T {
+        const cloned = super.cloneWithScope() as unknown as AreHTMLNode;
+        const self = this as unknown as AreHTMLNode;
+
+        if (self._staticInnerHTML !== undefined)
+            cloned.markStatic(self._staticInnerHTML);
+
+        return cloned as unknown as T;
+    }
+
     /**
       * The static attributes defined for the node, which are typically used to represent static properties or characteristics of the node that do not change based on the context or state. These attributes are usually defined in the template and are not reactive.
       * 

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

@@ -160,9 +160,9 @@ export class AreRoot extends Are {
             child.transform();
 
             child.compile();
-            // 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.
+            // The initial mount is atomic (synchronous): the routed subtree is
+            // rendered in one uninterrupted pass so no update can observe a
+            // partially mounted tree. The await is a harmless no-op here.
             await child.mount();
         }
     }