@adaas/are-html 0.0.21 → 0.0.23

package/src/engine/AreHTML.context.ts

@@ -54,6 +54,38 @@ export class AreHTMLEngineContext extends AreContext {
      */
     protected _container: Document;
 
+    /**
+     * Parsed-fragment cache for static islands (see AddStaticHTMLInstruction).
+     *
+     * Keyed by `hostTag\u0000markup`, each entry holds a `DocumentFragment` whose
+     * children were parsed by the browser exactly once — in the *correct element
+     * context* (the host tag), so table fragments (`<tr>`, `<td>`, …) and other
+     * context-sensitive content parse correctly. Repeated static islands with
+     * identical markup (e.g. list rows, reused components) clone the pre-parsed
+     * fragment instead of re-parsing the HTML string on every mount — turning an
+     * O(parse) operation into an O(clone) one.
+     */
+    protected _staticFragmentCache = new Map<string, DocumentFragment>();
+
+    /**
+     * Live-DOM attachments deferred while a mount pass is batching.
+     *
+     * A freshly-mounted subtree is built inside a *detached* root element, so
+     * every descendant `appendChild`/`insertBefore` happens off-document and
+     * triggers zero layout/paint invalidation. The single mutation that actually
+     * connects the built subtree to the live document is deferred and collected
+     * here, then flushed once when the batch closes — collapsing O(nodes) reflows
+     * into O(1) per mount root.
+     */
+    protected _pendingAttachments: Array<() => void> = [];
+
+    /**
+     * Depth of the currently open batching scopes. Re-entrant so that nested
+     * `beginBatch`/`endBatch` pairs flush exactly once, when the outermost scope
+     * closes.
+     */
+    protected _batchDepth = 0;
+
 
     constructor(props: Partial<AreHTMLContextConstructor>) {
         super(props.container?.body.innerHTML || props.source || '');
@@ -64,6 +96,86 @@ export class AreHTMLEngineContext extends AreContext {
         return this._container;
     }
 
+    /**
+     * `true` while a synchronous mount pass is batching live-DOM attachments.
+     * Interpreter handlers consult this to decide whether to attach an element
+     * immediately or hand the attachment to {@link deferAttach}.
+     */
+    get isBatching(): boolean {
+        return this._batchDepth > 0;
+    }
+
+    /**
+     * Opens a batching scope. Re-entrant: only the outermost matching
+     * {@link endBatch} flushes the deferred attachments, so a single mount pass
+     * connects its built subtree to the live DOM exactly once.
+     */
+    beginBatch(): void {
+        this._batchDepth++;
+    }
+
+    /**
+     * Registers a live-DOM attachment to run when the current batch flushes. If
+     * no batch is active the attachment runs immediately, preserving the original
+     * synchronous behaviour for updates that mount outside a batch.
+     *
+     * @param attach the DOM mutation that connects a built subtree to the document
+     */
+    deferAttach(attach: () => void): void {
+        if (this._batchDepth > 0) {
+            this._pendingAttachments.push(attach);
+        } else {
+            attach();
+        }
+    }
+
+    /**
+     * Closes a batching scope. When the outermost scope closes, every deferred
+     * attachment runs in registration (document) order, connecting the built
+     * subtrees to the live DOM in a single pass.
+     */
+    endBatch(): void {
+        if (this._batchDepth === 0) return;
+        this._batchDepth--;
+        if (this._batchDepth > 0) return;
+
+        const pending = this._pendingAttachments;
+        this._pendingAttachments = [];
+        for (let i = 0; i < pending.length; i++) {
+            pending[i]();
+        }
+    }
+
+    /**
+     * Returns a `DocumentFragment` containing the parsed form of `html`, parsed
+     * once in the context of `hostTag` (so context-sensitive content such as
+     * table rows/cells parses correctly) and cached thereafter. Callers should
+     * `cloneNode(true)` the returned fragment rather than mutating it, so the
+     * cache stays reusable.
+     *
+     * @param hostTag the tag name of the element the markup will be injected into
+     * @param html    verbatim static-island inner markup
+     */
+    getStaticFragment(hostTag: string, html: string): DocumentFragment {
+        const key = `${hostTag}\u0000${html}`;
+        let fragment = this._staticFragmentCache.get(key);
+        if (!fragment) {
+            // Parse in the correct element context: the fragment-parsing
+            // algorithm uses the container element's tag to choose the right
+            // insertion mode (e.g. `<tbody>` legitimately allows `<tr>`).
+            const container = this._container.createElement(hostTag);
+            container.innerHTML = html;
+
+            fragment = this._container.createDocumentFragment();
+            while (container.firstChild) {
+                fragment.appendChild(container.firstChild);
+            }
+
+            this._staticFragmentCache.set(key, fragment);
+        }
+        return fragment;
+    }
+
 
     /**
      * Retrieves the DOM element associated with a given AreNode. This method looks up the node's ASEID in the nodeToHostElements map to find the corresponding DOM element. If the node is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific nodes in the AreNode tree, enabling dynamic updates and interactions based on the application state.

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

@@ -92,7 +92,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 +103,102 @@ export class AreHTMLLifecycle extends AreLifecycle {
         if (scene.isInactive) return;
 
         /**
-         * 1. We should simply run and render node itself.
+         * 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.
+         *
+         * The context is resolved from the node's scope (the scope the onMount
+         * feature runs in) so the override keeps the base `mount` signature.
          */
-        node.interpret();
+        const context = node.scope.resolve<AreHTMLEngineContext>(AreHTMLEngineContext);
+
+        context?.beginBatch();
+
         /**
-         * 2. Then go through all children of the node and mount the.
+         * `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.
          */
-        for (let i = 0; i < node.children.length; i++) {
-            const child = node.children[i];
-            child.mount();
+        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 });
+            }
+
+            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;
+                }
+
+                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 });
+                    }
+                }
+            }
+        } finally {
+            // Flush the deferred attachments — the fully built subtree lands in the
+            // live DOM in a single pass.
+            context?.endBatch();
+        }
+
+        // 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);
         }
     }
 
+
     @A_Feature.Extend({
         name: AreAttributeFeatures.Update,
         scope: [AreDirectiveAttribute],

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/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

@@ -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