@adaas/are-html 0.0.22 → 0.0.23

package/examples/for-perf/dist/{mqh9ryfo-6a8d0o.js → mqj1mpf2-z4aokv.js}

@@ -2845,8 +2845,8 @@ var __decorateClass2 = /* @__PURE__ */ __name((decorators, target, key, kind) =>
 }, "__decorateClass");
 var __decorateParam2 = /* @__PURE__ */ __name((index, decorator) => (target, key) => decorator(target, key, index), "__decorateParam");
 
-// node_modules/@adaas/a-frame/dist/browser/chunk-UWXOV5XO.mjs
-var t = "0.1.15";
+// node_modules/@adaas/a-frame/dist/browser/chunk-VBGV4GJ5.mjs
+var t = "0.1.16";
 
 // node_modules/@adaas/a-frame/dist/browser/chunk-IKIN4MJV.mjs
 var h2 = Object.defineProperty;
@@ -2858,7 +2858,7 @@ var k2 = /* @__PURE__ */ __name((c3, a4, e, d4) => {
 }, "k");
 var l = /* @__PURE__ */ __name((c3, a4) => (e, d4) => a4(e, d4, c3), "l");
 
-// node_modules/@adaas/a-frame/dist/browser/chunk-PTHJM2MP.mjs
+// node_modules/@adaas/a-frame/dist/browser/chunk-6K7VISNV.mjs
 var _a39;
 var _2 = (_a39 = class extends H {
   get A_FRAME_TOKEN() {
@@ -3468,7 +3468,7 @@ var n3 = (_a48 = class extends D {
 j2(n3, "A_FrameDefinition");
 var h3 = n3;
 
-// node_modules/@adaas/a-frame/dist/browser/chunk-FYZWOISU.mjs
+// node_modules/@adaas/a-frame/dist/browser/chunk-3ROGJ3YE.mjs
 var _a49;
 var z2 = (_a49 = class extends H {
   constructor() {
@@ -4439,7 +4439,7 @@ var a3 = (_a64 = class extends D {
 j2(a3, "A_FrameSchema");
 var s2 = a3;
 
-// node_modules/@adaas/a-frame/dist/browser/chunk-PIH5MHMV.mjs
+// node_modules/@adaas/a-frame/dist/browser/chunk-4KUCX5R6.mjs
 var d3 = { Request: "_A_FRAME_REQUEST", Socket: "_A_FRAME_SOCKET", Stream: "_A_FRAME_STREAM", Send: "_A_FRAME_SEND" };
 var _a65;
 var J2 = (_a65 = class extends H {
@@ -5008,7 +5008,7 @@ var l3 = (_a76 = class extends O {
 j2(l3, "A_FrameChannel"), k2([N.Extend({ name: r4.Embed, scope: [h3] }), l(0, Yt(te)), l(1, Yt(f3))], l3.prototype, "embedDefinition", 1), k2([N.Extend({ name: m3.Embed, scope: [w2] }), l(0, Yt(te)), l(1, Yt(f3))], l3.prototype, "embedNamespace", 1), k2([N.Extend({ name: r5.Embed, scope: [_4] }), l(0, Yt(te)), l(1, Yt(f3))], l3.prototype, "embedSegment", 1), k2([N.Extend({ name: D3.Generate, scope: [O3] }), l(0, Yt(te)), l(1, Yt(v4))], l3.prototype, "generateDynamicStructure", 1), k2([N.Extend({ name: D3.Patch, scope: [O3] }), l(0, Yt(te)), l(1, Yt(v4))], l3.prototype, "patchDynamicStructure", 1), k2([N.Extend({ name: C4.Generate, scope: [P3] }), l(0, Yt(te)), l(1, Yt(w5))], l3.prototype, "generateDynamicFeature", 1), k2([N.Extend({ name: C4.Patch, scope: [P3] }), l(0, Yt(te)), l(1, Yt(w5))], l3.prototype, "patchDynamicFeature", 1), k2([N.Extend({ name: F3.Generate, scope: [w4] }), l(0, Yt(te)), l(1, Yt(f2))], l3.prototype, "generateDynamicContent", 1), k2([N.Extend({ name: F3.Patch, scope: [w4] }), l(0, Yt(te)), l(1, Yt(f2))], l3.prototype, "patchDynamicContent", 1), k2([N.Extend({ name: n4.Generate, scope: [m4] }), l(0, Yt(te)), l(1, Yt(f3))], l3.prototype, "generateCompletion", 1), k2([N.Extend({ name: r6.Extract, scope: [s2] }), l(0, Yt(te)), l(1, Yt(f3))], l3.prototype, "extractSchema", 1), k2([N.Extend({ name: r6.ExtractMultiple, scope: [s2] }), l(0, Yt(te)), l(1, Yt(f3))], l3.prototype, "extractSchemaMultiple", 1);
 var Fe2 = l3;
 
-// node_modules/@adaas/a-frame/dist/browser/chunk-2O3HAEYW.mjs
+// node_modules/@adaas/a-frame/dist/browser/chunk-P6WICUUU.mjs
 var _a77;
 var r7 = (_a77 = class extends Fe2 {
   async request(e, a4) {
@@ -8809,7 +8809,9 @@ var AreScene = (_a127 = class extends H {
     super({ name: id.toString() });
     this._groupToInstructionsMap = /* @__PURE__ */ new Map();
     this._plan = [];
+    this._planIndex = /* @__PURE__ */ new Map();
     this._state = [];
+    this._stateIndex = /* @__PURE__ */ new Map();
     this._status = AreSceneStatuses.Active;
   }
   /**
@@ -8969,6 +8971,7 @@ var AreScene = (_a127 = class extends H {
     } catch (error) {
     }
     this._plan.push(instruction);
+    this._planIndex.set(instruction.aseid.toString(), instruction);
     if (!this._groupToInstructionsMap.has(instruction.group || "default")) {
       this._groupToInstructionsMap.set(instruction.group || "default", /* @__PURE__ */ new Set());
     }
@@ -8989,6 +8992,7 @@ var AreScene = (_a127 = class extends H {
       } catch (error) {
       }
       this._plan.splice(beforeIndex, 0, instruction);
+      this._planIndex.set(instruction.aseid.toString(), instruction);
     } else {
       this._plan.splice(instructionIndex, 1);
       this._plan.splice(beforeIndex, 0, instruction);
@@ -9006,6 +9010,7 @@ var AreScene = (_a127 = class extends H {
     if (instructionIndex === -1) {
       this.scope.register(instruction);
       this._plan.splice(afterIndex + 1, 0, instruction);
+      this._planIndex.set(instruction.aseid.toString(), instruction);
     } else {
       this._plan.splice(instructionIndex, 1);
       this._plan.splice(afterIndex + 1, 0, instruction);
@@ -9035,7 +9040,9 @@ var AreScene = (_a127 = class extends H {
    * @param instruction 
    */
   unPlan(instruction) {
-    this._plan = this._plan.filter((i6) => i6.aseid.toString() !== instruction.aseid.toString());
+    const key = instruction.aseid.toString();
+    if (!this._planIndex.delete(key)) return;
+    this._plan = this._plan.filter((i6) => i6.aseid.toString() !== key);
   }
   /**
    * Checks if the instruction is already in the plan, so it will be rendered in the next render cycle.
@@ -9044,8 +9051,7 @@ var AreScene = (_a127 = class extends H {
    * @returns 
    */
   getPlanned(instruction) {
-    const found = this._plan.find((i6) => i6.aseid.toString() === instruction.aseid.toString());
-    return found;
+    return this._planIndex.get(instruction.aseid.toString());
   }
   /**
    * Checks if the instruction is already in the plan, so it will be rendered in the next render cycle.
@@ -9054,7 +9060,7 @@ var AreScene = (_a127 = class extends H {
    * @returns 
    */
   isInPlan(instruction) {
-    return !!this.getPlanned(instruction);
+    return this._planIndex.has(instruction.aseid.toString());
   }
   // -------------------------------------------------------------------------------------------------------------
   // Scene Apply Methods
@@ -9065,8 +9071,10 @@ var AreScene = (_a127 = class extends H {
    * @param instruction 
    */
   apply(instruction) {
-    if (!this.isApplied(instruction)) {
+    const key = instruction.aseid.toString();
+    if (!this._stateIndex.has(key)) {
       this._state.push(instruction);
+      this._stateIndex.set(key, instruction);
     }
   }
   /**
@@ -9075,7 +9083,9 @@ var AreScene = (_a127 = class extends H {
    * @param instruction 
    */
   unApply(instruction) {
-    this._state = this._state.filter((i6) => i6.aseid.toString() !== instruction.aseid.toString());
+    const key = instruction.aseid.toString();
+    if (!this._stateIndex.delete(key)) return;
+    this._state = this._state.filter((i6) => i6.aseid.toString() !== key);
   }
   /**
    * Checks if the instruction is already in the state, so it is currently applied to the scene.
@@ -9084,8 +9094,7 @@ var AreScene = (_a127 = class extends H {
    * @returns 
    */
   getApplied(instruction) {
-    const found = this._state.find((i6) => i6.aseid.toString() === instruction.aseid.toString());
-    return found;
+    return this._stateIndex.get(instruction.aseid.toString());
   }
   /**
    * Checks if the instruction is already in the state, so it is currently applied to the scene.
@@ -9094,7 +9103,7 @@ var AreScene = (_a127 = class extends H {
    * @returns 
    */
   isApplied(instruction) {
-    return !!this.getApplied(instruction);
+    return this._stateIndex.has(instruction.aseid.toString());
   }
   /**
    * Method that should reset the scene to the initial state, so it will clear the plan and state, but it will not deregister the instructions from the scene scope, so they will still be registered in the scene and can be planned and applied again if needed.
@@ -9103,6 +9112,8 @@ var AreScene = (_a127 = class extends H {
   reset() {
     this._plan = [];
     this._state = [];
+    this._planIndex.clear();
+    this._stateIndex.clear();
   }
 }, __name(_a127, "AreScene"), _a127);
 AreScene = __decorateClass3([
@@ -12440,6 +12451,7 @@ var AreHTMLInstructions = {
   AddListener: "_AreHTML_AddListener",
   AddInterpolation: "_AreHTML_AddInterpolation",
   AddComment: "_AreHTML_AddComment",
+  AddStaticHTML: "_AreHTML_AddStaticHTML",
   HideElement: "_AreHTML_HideElement"
 };
 
@@ -12495,11 +12507,109 @@ var AreHTMLEngineContext = class extends AreContext {
        */
       elementListeners: /* @__PURE__ */ new WeakMap()
     };
+    /**
+     * 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.
+     */
+    this._staticFragmentCache = /* @__PURE__ */ new Map();
+    /**
+     * 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.
+     */
+    this._pendingAttachments = [];
+    /**
+     * Depth of the currently open batching scopes. Re-entrant so that nested
+     * `beginBatch`/`endBatch` pairs flush exactly once, when the outermost scope
+     * closes.
+     */
+    this._batchDepth = 0;
     this._container = props.container;
   }
   get container() {
     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() {
+    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() {
+    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) {
+    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() {
+    if (this._batchDepth === 0) return;
+    this._batchDepth--;
+    if (this._batchDepth > 0) return;
+    const pending = this._pendingAttachments;
+    this._pendingAttachments = [];
+    for (let i6 = 0; i6 < pending.length; i6++) {
+      pending[i6]();
+    }
+  }
+  /**
+   * 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, html) {
+    const key = `${hostTag}\0${html}`;
+    let fragment = this._staticFragmentCache.get(key);
+    if (!fragment) {
+      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;
+  }
   getNodeElement(node) {
     if (typeof node === "string") {
       return this.index.nodeToHostElements.get(node);
@@ -12753,6 +12863,171 @@ function toDOMString(value) {
   }
 }
 __name(toDOMString, "toDOMString");
+var STANDARD_HTML_TAGS = /* @__PURE__ */ new Set([
+  // root / sections
+  "html",
+  "body",
+  "header",
+  "footer",
+  "main",
+  "nav",
+  "section",
+  "article",
+  "aside",
+  "address",
+  "hgroup",
+  // headings
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  // grouping
+  "div",
+  "p",
+  "span",
+  "pre",
+  "blockquote",
+  "figure",
+  "figcaption",
+  "hr",
+  "br",
+  "wbr",
+  // lists
+  "ul",
+  "ol",
+  "li",
+  "dl",
+  "dt",
+  "dd",
+  "menu",
+  // text-level / phrasing
+  "a",
+  "b",
+  "i",
+  "u",
+  "s",
+  "em",
+  "strong",
+  "small",
+  "mark",
+  "abbr",
+  "cite",
+  "q",
+  "code",
+  "kbd",
+  "samp",
+  "var",
+  "sub",
+  "sup",
+  "time",
+  "data",
+  "dfn",
+  "bdi",
+  "bdo",
+  "ruby",
+  "rt",
+  "rp",
+  "del",
+  "ins",
+  // media / embedded (no special namespace handling needed)
+  "img",
+  "picture",
+  "source",
+  "figure",
+  "audio",
+  "video",
+  "track",
+  // tables
+  "table",
+  "caption",
+  "colgroup",
+  "col",
+  "thead",
+  "tbody",
+  "tfoot",
+  "tr",
+  "th",
+  "td",
+  // forms (display only — these still render fine from innerHTML)
+  "label",
+  "fieldset",
+  "legend",
+  "datalist",
+  "option",
+  "optgroup",
+  "output",
+  "progress",
+  "meter",
+  // interactive
+  "details",
+  "summary",
+  "dialog"
+]);
+function isStaticMarkup(inner) {
+  if (!inner) return false;
+  if (inner.indexOf("{{") !== -1) return false;
+  const n6 = inner.length;
+  let i6 = 0;
+  while (i6 < n6) {
+    const lt = inner.indexOf("<", i6);
+    if (lt === -1) break;
+    if (inner.startsWith("<!--", lt)) {
+      const end = inner.indexOf("-->", lt + 4);
+      if (end === -1) return false;
+      i6 = end + 3;
+      continue;
+    }
+    if (inner[lt + 1] === "/" || inner[lt + 1] === "!" || inner[lt + 1] === "?") {
+      const gt2 = inner.indexOf(">", lt);
+      if (gt2 === -1) return false;
+      i6 = gt2 + 1;
+      continue;
+    }
+    const nameMatch = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(inner.slice(lt));
+    if (!nameMatch) {
+      i6 = lt + 1;
+      continue;
+    }
+    const tag = nameMatch[1].toLowerCase();
+    if (tag.indexOf("-") !== -1 || !STANDARD_HTML_TAGS.has(tag)) return false;
+    let j5 = lt + nameMatch[0].length;
+    let inSingle = false;
+    let inDouble = false;
+    let atNameBoundary = true;
+    let tagEnd = -1;
+    while (j5 < n6) {
+      const ch = inner[j5];
+      if (inDouble) {
+        if (ch === '"') inDouble = false;
+      } else if (inSingle) {
+        if (ch === "'") inSingle = false;
+      } else if (ch === '"') {
+        inDouble = true;
+        atNameBoundary = false;
+      } else if (ch === "'") {
+        inSingle = true;
+        atNameBoundary = false;
+      } else if (ch === ">") {
+        tagEnd = j5;
+        break;
+      } else if (ch === " " || ch === "	" || ch === "\n" || ch === "\r" || ch === "/") {
+        atNameBoundary = true;
+      } else {
+        if (atNameBoundary && (ch === "$" || ch === ":" || ch === "@")) {
+          return false;
+        }
+        atNameBoundary = false;
+      }
+      j5++;
+    }
+    if (tagEnd === -1) return false;
+    i6 = tagEnd + 1;
+  }
+  return true;
+}
+__name(isStaticMarkup, "isStaticMarkup");
 
 // src/engine/AreHTML.interpreter.ts
 var AreHTMLInterpreter = class extends AreInterpreter {
@@ -12779,12 +13054,15 @@ var AreHTMLInterpreter = class extends AreInterpreter {
           });
         }
         const element = isSVG ? context.container.createElementNS(SVG_NAMESPACE, tag) : context.container.createElement(tag);
-        if (mountPoint.nodeType === Node.ELEMENT_NODE) {
-          mountPoint.appendChild(element);
-        } else {
+        context.setInstructionElement(declaration, element);
+        const attach = mountPoint.nodeType === Node.ELEMENT_NODE ? () => mountPoint.appendChild(element) : () => {
           mountPoint.parentNode?.insertBefore(element, mountPoint);
+        };
+        if (context.isBatching && mountPoint.isConnected) {
+          context.deferAttach(attach);
+        } else {
+          attach();
         }
-        context.setInstructionElement(declaration, element);
       } else {
         const mountPoint = context.container.getElementById(node.id);
         if (!mountPoint) {
@@ -12794,8 +13072,15 @@ var AreHTMLInterpreter = class extends AreInterpreter {
           });
         }
         const element = isSVG ? context.container.createElementNS(SVG_NAMESPACE, tag) : context.container.createElement(tag);
-        mountPoint.parentNode?.replaceChild(element, mountPoint);
         context.setInstructionElement(declaration, element);
+        const attach = /* @__PURE__ */ __name(() => {
+          mountPoint.parentNode?.replaceChild(element, mountPoint);
+        }, "attach");
+        if (context.isBatching && mountPoint.isConnected) {
+          context.deferAttach(attach);
+        } else {
+          attach();
+        }
       }
       logger?.debug("green", `Element ${node.aseid.toString()} added to Context:`);
     } catch (error) {
@@ -12805,7 +13090,7 @@ var AreHTMLInterpreter = class extends AreInterpreter {
   }
   removeElement(declaration, context) {
     const element = context.getElementByInstruction(declaration);
-    if (element && element.parentNode) {
+    if (element && element.parentNode && element.isConnected) {
       element.parentNode.removeChild(element);
     }
     context.removeInstructionElement(declaration);
@@ -12908,7 +13193,7 @@ var AreHTMLInterpreter = class extends AreInterpreter {
       const element = context.getElementByInstruction(mutation.parent);
       if (!element) return;
       const { name } = mutation.payload;
-      if (name && element.nodeType === Node.ELEMENT_NODE) {
+      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)];
@@ -12935,6 +13220,7 @@ var AreHTMLInterpreter = class extends AreInterpreter {
   showElement(mutation, context) {
     const element = context.getElementByInstruction(mutation.parent);
     if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
+    if (!element.isConnected) return;
     const el = element;
     el.style.display = mutation.payload?.display ?? mutation.cache ?? "";
   }
@@ -13029,7 +13315,9 @@ var AreHTMLInterpreter = class extends AreInterpreter {
     const { event: eventName } = parseEventName(name);
     const listener = mutation.payload._callback;
     if (listener) {
-      element.removeEventListener(eventName, listener);
+      if (element.isConnected) {
+        element.removeEventListener(eventName, listener);
+      }
       context.removeListener(element, name, listener);
       mutation.payload._callback = void 0;
     }
@@ -13067,9 +13355,32 @@ var AreHTMLInterpreter = class extends AreInterpreter {
   removeText(declaration, context) {
     const element = context.getElementByInstruction(declaration);
     if (!element) return;
-    element.parentNode?.removeChild(element);
+    if (element.isConnected) {
+      element.parentNode?.removeChild(element);
+    }
     context.removeInstructionElement(declaration);
   }
+  addStaticHTML(mutation, context, 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;
+    const { html } = mutation.payload;
+    el.textContent = "";
+    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?.()}>`);
+  }
+  removeStaticHTML(mutation, context) {
+    const element = context.getElementByInstruction(mutation.parent);
+    if (element && element.nodeType === Node.ELEMENT_NODE && element.isConnected) {
+      element.textContent = "";
+    }
+  }
   addComment(declaration, context, store, syntax, directiveContext, logger) {
     const node = declaration.owner.parent;
     const { content, evaluate } = declaration.payload;
@@ -13103,7 +13414,9 @@ var AreHTMLInterpreter = class extends AreInterpreter {
   removeComment(declaration, context) {
     const element = context.getElementByInstruction(declaration);
     if (!element) return;
-    element.parentNode?.removeChild(element);
+    if (element.isConnected) {
+      element.parentNode?.removeChild(element);
+    }
     context.removeInstructionElement(declaration);
   }
   addStyle(mutation, context, logger) {
@@ -13248,6 +13561,24 @@ __decorateClass([
   __decorateParam(0, Yt(te)),
   __decorateParam(1, Yt(AreHTMLEngineContext))
 ], AreHTMLInterpreter.prototype, "removeText", 1);
+__decorateClass([
+  R4.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),
+  __decorateParam(0, Yt(te)),
+  __decorateParam(1, Yt(AreHTMLEngineContext)),
+  __decorateParam(2, Yt(A_Logger))
+], AreHTMLInterpreter.prototype, "addStaticHTML", 1);
+__decorateClass([
+  R4.Define({
+    description: "Clear a static island's injected markup from its host element on revert."
+  }),
+  AreInterpreter.Revert(AreHTMLInstructions.AddStaticHTML),
+  __decorateParam(0, Yt(te)),
+  __decorateParam(1, Yt(AreHTMLEngineContext))
+], AreHTMLInterpreter.prototype, "removeStaticHTML", 1);
 __decorateClass([
   R4.Define({
     description: "Add a comment node to the DOM based on the provided declaration instruction."
@@ -13392,6 +13723,57 @@ var AreHTMLNode = class extends AreNode {
   get tag() {
     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() {
+    return this._staticInnerHTML;
+  }
+  /**
+   * Whether this node is a static-island root (see `_staticInnerHTML`).
+   */
+  get isStaticIsland() {
+    return this._staticInnerHTML !== void 0;
+  }
+  /**
+   * 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) {
+    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() {
+    const cloned = super.clone();
+    const self = this;
+    if (self._staticInnerHTML !== void 0)
+      cloned.markStatic(self._staticInnerHTML);
+    return cloned;
+  }
+  /**
+   * 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() {
+    const cloned = super.cloneWithScope();
+    const self = this;
+    if (self._staticInnerHTML !== void 0)
+      cloned.markStatic(self._staticInnerHTML);
+    return cloned;
+  }
   /**
     * 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.
     * 
@@ -13575,7 +13957,12 @@ var AreHTMLTokenizer = class extends AreTokenizer {
     this.ATTR_PATTERN = /([$:@]?[\w.-]+(?::[\w.-]+)?)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>/"'=]+)))?/g;
   }
   tokenize(node, context, logger) {
-    super.tokenize(node, context, logger);
+    const isStaticIsland = node instanceof AreComponentNode && !!node.content && isStaticMarkup(node.content);
+    if (isStaticIsland) {
+      node.markStatic(node.content);
+    } else {
+      super.tokenize(node, context, logger);
+    }
     context.startPerformance("attributeExtraction");
     const attributes = this.extractAttributes(node.markup);
     for (const attr of attributes) {
@@ -13649,44 +14036,6 @@ var AreDirectiveFeatures = {
   Update: "_AreDirective_Update"
 };
 
-// src/helpers/AreScheduler.helper.ts
-var _AreSchedulerHelper = class _AreSchedulerHelper {
-  /**
-   * High-resolution wall-clock time in milliseconds. Uses `performance.now()`
-   * when available (monotonic, sub-millisecond), falling back to `Date.now()`.
-   */
-  static now() {
-    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) {
-    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);
-  }
-};
-__name(_AreSchedulerHelper, "AreSchedulerHelper");
-/** FIFO queue of callbacks waiting for their posted macrotask to fire. */
-_AreSchedulerHelper._queue = [];
-var AreSchedulerHelper = _AreSchedulerHelper;
-
 // src/engine/AreHTML.lifecycle.ts
 var AreHTMLLifecycle = class extends AreLifecycle {
   initComponent(node, scope, context, signalsContext, logger, ...args) {
@@ -13709,46 +14058,39 @@ var AreHTMLLifecycle = class extends AreLifecycle {
   mount(node, scene, logger, ...args) {
     logger?.debug(`[Mount] Component Trigger for <${node.aseid.entity}>  with aseid :{${node.aseid.toString()}}`);
     if (scene.isInactive) return;
-    node.interpret();
-    const stack = [];
-    for (let i6 = node.children.length - 1; i6 >= 0; i6--) {
-      stack.push({ node: node.children[i6], entered: false });
-    }
-    const step = /* @__PURE__ */ __name(() => {
-      const frame = stack[stack.length - 1];
-      const current = frame.node;
-      if (frame.entered) {
-        stack.pop();
-        current.call(AreNodeFeatures.onAfterMount, current.scope);
-        return;
-      }
-      frame.entered = true;
-      current.call(AreNodeFeatures.onBeforeMount, current.scope);
-      if (!current.scene.isInactive) {
-        current.interpret();
-        for (let i6 = current.children.length - 1; i6 >= 0; i6--) {
-          stack.push({ node: current.children[i6], entered: false });
-        }
+    const context = node.scope.resolve(AreHTMLEngineContext);
+    context?.beginBatch();
+    const afterMountQueue = [];
+    try {
+      node.interpret();
+      const stack = [];
+      for (let i6 = node.children.length - 1; i6 >= 0; i6--) {
+        stack.push({ node: node.children[i6], entered: false });
       }
-    }, "step");
-    const drive = /* @__PURE__ */ __name(() => {
-      const start = AreSchedulerHelper.now();
       while (stack.length > 0) {
-        step();
-        if (stack.length > 0 && AreSchedulerHelper.now() - start >= AreHTMLLifecycle.MOUNT_BUDGET_MS) {
-          return new Promise((resolve, reject) => {
-            AreSchedulerHelper.scheduleMacrotask(() => {
-              try {
-                resolve(drive());
-              } catch (error) {
-                reject(error);
-              }
-            });
-          });
+        const frame = stack[stack.length - 1];
+        const current = frame.node;
+        if (frame.entered) {
+          stack.pop();
+          afterMountQueue.push(current);
+          continue;
+        }
+        frame.entered = true;
+        current.call(AreNodeFeatures.onBeforeMount, current.scope);
+        if (!current.scene.isInactive) {
+          current.interpret();
+          for (let i6 = current.children.length - 1; i6 >= 0; i6--) {
+            stack.push({ node: current.children[i6], entered: false });
+          }
         }
       }
-    }, "drive");
-    return drive();
+    } finally {
+      context?.endBatch();
+    }
+    for (let i6 = 0; i6 < afterMountQueue.length; i6++) {
+      const mounted = afterMountQueue[i6];
+      mounted.call(AreNodeFeatures.onAfterMount, mounted.scope);
+    }
   }
   updateDirectiveAttribute(directive, scope, feature, logger, ...args) {
     if (directive.component) {
@@ -13759,13 +14101,6 @@ var AreHTMLLifecycle = class extends AreLifecycle {
   }
 };
 __name(AreHTMLLifecycle, "AreHTMLLifecycle");
-/**
- * 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.
- */
-AreHTMLLifecycle.MOUNT_BUDGET_MS = 16;
 __decorateClass([
   AreLifecycle.Init(AreComponentNode),
   __decorateParam(0, Yt(te)),
@@ -13924,10 +14259,31 @@ AddStyleInstruction = __decorateClass([
   })
 ], AddStyleInstruction);
 
+// src/instructions/AddStaticHTML.instruction.ts
+var AddStaticHTMLInstruction = class extends AreMutation {
+  constructor(parent, props) {
+    if ("aseid" in props) {
+      super(props);
+    } else {
+      super(AreHTMLInstructions.AddStaticHTML, parent, props);
+    }
+  }
+};
+__name(AddStaticHTMLInstruction, "AddStaticHTMLInstruction");
+AddStaticHTMLInstruction = __decorateClass([
+  R4.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.'
+  })
+], AddStaticHTMLInstruction);
+
 // src/engine/AreHTML.compiler.ts
 var AreHTMLCompiler = class extends AreCompiler {
   compileHTMLNode(node, scene, logger, ...args) {
     super.compile(node, scene, logger, ...args);
+    if (node.isStaticIsland && scene.host) {
+      scene.plan(new AddStaticHTMLInstruction(scene.host, { html: node.staticInnerHTML }));
+    }
     if (node.styles?.styles) {
       const host = scene.host;
       if (host) {
@@ -14496,6 +14852,44 @@ AreDirectiveIf = __decorateClass([
   AreDirective.Priority(2)
 ], AreDirectiveIf);
 
+// src/helpers/AreScheduler.helper.ts
+var _AreSchedulerHelper = class _AreSchedulerHelper {
+  /**
+   * High-resolution wall-clock time in milliseconds. Uses `performance.now()`
+   * when available (monotonic, sub-millisecond), falling back to `Date.now()`.
+   */
+  static now() {
+    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) {
+    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);
+  }
+};
+__name(_AreSchedulerHelper, "AreSchedulerHelper");
+/** FIFO queue of callbacks waiting for their posted macrotask to fire. */
+_AreSchedulerHelper._queue = [];
+var AreSchedulerHelper = _AreSchedulerHelper;
+
 // src/directives/AreDirectiveFor.directive.ts
 var AreDirectiveFor = class extends AreDirective {
   transform(attribute, scope, store, scene, logger, ...args) {
@@ -14510,7 +14904,8 @@ var AreDirectiveFor = class extends AreDirective {
     node.init();
     attribute.template = forTemplate;
     const { key, index, arrayExpr } = this.parseExpression(attribute.content);
-    const array = this.resolveArray(store, arrayExpr, attribute.content);
+    const contextScope = attribute.owner.scope.resolve(AreDirectiveContext)?.scope || {};
+    const array = this.resolveArray(store, arrayExpr, attribute.content, contextScope);
     attribute.value = array;
     for (let i6 = 0; i6 < array.length; i6++) {
       this.spawnItemNode(attribute.template, attribute.owner, key, index, array[i6], i6);
@@ -14544,8 +14939,9 @@ var AreDirectiveFor = class extends AreDirective {
    */
   performUpdate(attribute, store, scene, state) {
     const { key, index, arrayExpr, trackExpr } = this.parseExpression(attribute.content);
-    const newArray = this.resolveArray(store, arrayExpr, attribute.content);
     const owner = attribute.owner;
+    const contextScope = owner.scope.resolve(AreDirectiveContext)?.scope || {};
+    const newArray = this.resolveArray(store, arrayExpr, attribute.content, contextScope);
     const currentChildren = [...owner.children];
     attribute.value = newArray;
     const attached = this.isAttached(owner);
@@ -14560,12 +14956,16 @@ var AreDirectiveFor = class extends AreDirective {
       remaining.add(child);
     }
     const toCreate = [];
+    const finalByKey = /* @__PURE__ */ new Map();
+    const orderedKeys = new Array(newArray.length);
     for (let i6 = 0; i6 < newArray.length; i6++) {
       const item = newArray[i6];
       const k4 = computeKey(item, i6);
+      orderedKeys[i6] = k4;
       const existing = childByKey.get(k4);
       if (existing) {
         remaining.delete(existing);
+        finalByKey.set(k4, existing);
         let directiveContext = existing.scope.resolveFlat(AreDirectiveContext);
         if (!directiveContext) {
           directiveContext = new AreDirectiveContext(existing.aseid);
@@ -14577,7 +14977,7 @@ var AreDirectiveFor = class extends AreDirective {
           [index || "index"]: i6
         };
       } else {
-        toCreate.push({ item, idx: i6 });
+        toCreate.push({ item, idx: i6, key: k4 });
       }
     }
     for (const child of remaining) {
@@ -14586,12 +14986,14 @@ var AreDirectiveFor = class extends AreDirective {
     }
     const createItem = /* @__PURE__ */ __name((desc) => {
       const child = this.spawnItemNode(attribute.template, owner, key, index, desc.item, desc.idx);
+      finalByKey.set(desc.key, child);
       child.transform();
       child.compile();
       if (attached) child.mount();
     }, "createItem");
     if (toCreate.length <= AreDirectiveFor.SYNC_THRESHOLD) {
       for (const desc of toCreate) createItem(desc);
+      if (attached) this.reconcileOrder(owner, orderedKeys, finalByKey);
       return this.finishUpdate(attribute, store, scene, state);
     }
     state.running = true;
@@ -14614,10 +15016,39 @@ var AreDirectiveFor = class extends AreDirective {
           AreSchedulerHelper.scheduleMacrotask(() => resolve(processChunk()));
         });
       }
+      if (attached) this.reconcileOrder(owner, orderedKeys, finalByKey);
       return this.finishUpdate(attribute, store, scene, state);
     }, "processChunk");
     return processChunk();
   }
+  /**
+   * Repositions the item nodes' DOM elements so the rendered order matches the
+   * source array order. The keyed diff (steps 1–4) reuses existing nodes in
+   * place and mounts new ones at the end; without this pass a `prepend` or
+   * `shuffle` would leave reused rows where they were and pile new rows at the
+   * bottom. We walk the desired order RIGHT-TO-LEFT, keeping a `ref` pointer to
+   * the element each item must precede (starting at the `$for` anchor comment),
+   * and only call `insertBefore` when an element is not already in position —
+   * so a plain `append` (already-correct order) performs ZERO DOM moves.
+   */
+  reconcileOrder(owner, orderedKeys, finalByKey) {
+    const context = owner.scope.resolve(AreHTMLEngineContext);
+    if (!context) return;
+    const anchor = context.getNodeElement(owner);
+    if (!anchor || !anchor.parentNode) return;
+    const parent = anchor.parentNode;
+    let ref = anchor;
+    for (let i6 = orderedKeys.length - 1; i6 >= 0; i6--) {
+      const node = finalByKey.get(orderedKeys[i6]);
+      if (!node) continue;
+      const element = context.getNodeElement(node);
+      if (!element || element.parentNode !== parent) continue;
+      if (element.nextSibling !== ref) {
+        parent.insertBefore(element, ref);
+      }
+      ref = element;
+    }
+  }
   /**
    * Completes an update pass. If another update() arrived while a chunked
    * render was streaming, run exactly one more pass now from the latest store
@@ -14708,13 +15139,23 @@ var AreDirectiveFor = class extends AreDirective {
    * Supports both plain key lookups and function-call expressions:
    *   items          → store.get('items')
    *   filter(items)  → store.get('filter')(store.get('items'))
-   */
-  resolveArray(store, arrayExpr, fullContent) {
+   *
+   * `contextScope` carries item-scoped variables introduced by an enclosing
+   * directive (e.g. the `row` of an outer `$for`). It is consulted BEFORE the
+   * store so a nested `$for="cell in row.cells"` resolves `row` from the
+   * parent iteration instead of looking for a (non-existent) top-level store
+   * key. Leading identifiers not present in the context fall back to the store.
+   */
+  resolveArray(store, arrayExpr, fullContent, contextScope = {}) {
+    const getRoot = /* @__PURE__ */ __name((rawKey) => {
+      const k4 = rawKey.replace(/\?$/, "");
+      return k4 in contextScope ? contextScope[k4] : store.get(k4);
+    }, "getRoot");
     let result;
     const callMatch = arrayExpr.match(/^([^(]+)\((.+)\)$/);
     if (callMatch) {
       const fnName = callMatch[1].trim();
-      const fn = store.get(fnName);
+      const fn = getRoot(fnName);
       if (typeof fn !== "function")
         throw new AreCompilerError({
           title: 'Invalid "for" Directive Function',
@@ -14728,25 +15169,25 @@ var AreDirectiveFor = class extends AreDirective {
         const stripped = arg.replace(/\?$/, "");
         if (stripped.includes(".")) {
           const parts = stripped.split(".").map((p5) => p5.replace(/\?$/, ""));
-          let val = store.get(parts[0]);
+          let val = getRoot(parts[0]);
           for (let j5 = 1; j5 < parts.length; j5++) {
             if (val == null) return void 0;
             val = val[parts[j5]];
           }
           return val ?? void 0;
         }
-        return store.get(stripped);
+        return getRoot(stripped);
       });
       result = fn(...resolvedArgs);
     } else if (arrayExpr.includes(".")) {
       const parts = arrayExpr.split(".").map((p5) => p5.replace(/\?$/, ""));
-      result = store.get(parts[0]);
+      result = getRoot(parts[0]);
       for (let i6 = 1; i6 < parts.length; i6++) {
         if (result == null) break;
         result = result[parts[i6]];
       }
     } else {
-      result = store.get(arrayExpr.replace(/\?$/, ""));
+      result = getRoot(arrayExpr);
     }
     if (result == null) return [];
     if (!Array.isArray(result))