@adaas/are-html 0.0.21 → 0.0.23

package/dist/node/{AreBinding.attribute-doUvtOjc.d.mts → AreBinding.attribute-BWzEIw6H.d.mts}

@@ -65,11 +65,56 @@ declare class AreStaticAttribute extends AreHTMLAttribute {
 }
 
 declare 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
      */
     get tag(): string;
+    /**
+     * 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;
+    /**
+     * Whether this node is a static-island root (see `_staticInnerHTML`).
+     */
+    get isStaticIsland(): boolean;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
       * 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/dist/node/{AreBinding.attribute-Bm5LlOyE.d.ts → AreBinding.attribute-GpT-5Qmf.d.ts}

@@ -65,11 +65,56 @@ declare class AreStaticAttribute extends AreHTMLAttribute {
 }
 
 declare 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
      */
     get tag(): string;
+    /**
+     * 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;
+    /**
+     * Whether this node is a static-island root (see `_staticInnerHTML`).
+     */
+    get isStaticIsland(): boolean;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
       * 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/dist/node/attributes/AreBinding.attribute.d.mts

@@ -1,4 +1,4 @@
-export { A as AreBindingAttribute } from '../AreBinding.attribute-doUvtOjc.mjs';
+export { A as AreBindingAttribute } from '../AreBinding.attribute-BWzEIw6H.mjs';
 import '@adaas/are';
 import '@adaas/a-concept';
 import '../lib/AreStyle/AreStyle.context.mjs';

package/dist/node/attributes/AreBinding.attribute.d.ts

@@ -1,4 +1,4 @@
-export { A as AreBindingAttribute } from '../AreBinding.attribute-Bm5LlOyE.js';
+export { A as AreBindingAttribute } from '../AreBinding.attribute-GpT-5Qmf.js';
 import '@adaas/are';
 import '@adaas/a-concept';
 import '../lib/AreStyle/AreStyle.context.js';

package/dist/node/attributes/AreDirective.attribute.d.mts

@@ -1,4 +1,4 @@
-export { b as AreDirectiveAttribute } from '../AreBinding.attribute-doUvtOjc.mjs';
+export { b as AreDirectiveAttribute } from '../AreBinding.attribute-BWzEIw6H.mjs';
 import '@adaas/are';
 import '@adaas/a-concept';
 import '../lib/AreStyle/AreStyle.context.mjs';

package/dist/node/attributes/AreDirective.attribute.d.ts

@@ -1,4 +1,4 @@
-export { b as AreDirectiveAttribute } from '../AreBinding.attribute-Bm5LlOyE.js';
+export { b as AreDirectiveAttribute } from '../AreBinding.attribute-GpT-5Qmf.js';
 import '@adaas/are';
 import '@adaas/a-concept';
 import '../lib/AreStyle/AreStyle.context.js';

package/dist/node/attributes/AreEvent.attribute.d.mts

@@ -1,4 +1,4 @@
-export { c as AreEventAttribute } from '../AreBinding.attribute-doUvtOjc.mjs';
+export { c as AreEventAttribute } from '../AreBinding.attribute-BWzEIw6H.mjs';
 import '@adaas/are';
 import '@adaas/a-concept';
 import '../lib/AreStyle/AreStyle.context.mjs';

package/dist/node/attributes/AreEvent.attribute.d.ts

@@ -1,4 +1,4 @@
-export { c as AreEventAttribute } from '../AreBinding.attribute-Bm5LlOyE.js';
+export { c as AreEventAttribute } from '../AreBinding.attribute-GpT-5Qmf.js';
 import '@adaas/are';
 import '@adaas/a-concept';
 import '../lib/AreStyle/AreStyle.context.js';

package/dist/node/attributes/AreStatic.attribute.d.mts

@@ -1,4 +1,4 @@
-export { f as AreStaticAttribute } from '../AreBinding.attribute-doUvtOjc.mjs';
+export { f as AreStaticAttribute } from '../AreBinding.attribute-BWzEIw6H.mjs';
 import '@adaas/are';
 import '@adaas/a-concept';
 import '../lib/AreStyle/AreStyle.context.mjs';

package/dist/node/attributes/AreStatic.attribute.d.ts

@@ -1,4 +1,4 @@
-export { f as AreStaticAttribute } from '../AreBinding.attribute-Bm5LlOyE.js';
+export { f as AreStaticAttribute } from '../AreBinding.attribute-GpT-5Qmf.js';
 import '@adaas/are';
 import '@adaas/a-concept';
 import '../lib/AreStyle/AreStyle.context.js';

package/dist/node/directives/AreDirectiveFor.directive.d.mts

@@ -1,13 +1,60 @@
 import { A_Scope } from '@adaas/a-concept';
 import { A_Logger } from '@adaas/a-utils/a-logger';
-import { a as AreDirective, b as AreDirectiveAttribute } from '../AreBinding.attribute-doUvtOjc.mjs';
+import { a as AreDirective, b as AreDirectiveAttribute } from '../AreBinding.attribute-BWzEIw6H.mjs';
 import { AreStore, AreScene } from '@adaas/are';
 import '../lib/AreStyle/AreStyle.context.mjs';
 
 declare class AreDirectiveFor extends AreDirective {
+    /**
+     * Lists whose number of NEW item nodes is at or below this threshold render
+     * fully synchronously — byte-for-byte the previous behavior. Typical UIs
+     * (menus, small tables) are therefore completely unaffected; only genuinely
+     * large lists pay the (tiny) scheduling cost to keep the main thread responsive.
+     */
+    private static readonly SYNC_THRESHOLD;
+    /**
+     * Per-chunk time budget (ms). During a large-list render we mount item nodes
+     * until this much time has elapsed, then yield to the browser so it can paint
+     * and process input before the next chunk. ~16ms targets one animation frame.
+     */
+    private static readonly CHUNK_BUDGET_MS;
+    /**
+     * Per-attribute serialization state. A new update() that arrives while a
+     * chunked render of the SAME `$for` is still in flight does NOT start a second
+     * concurrent pass (which could interleave mutations on the shared children
+     * list); instead it marks `pending` and the in-flight run re-runs once more
+     * with the latest data when it finishes. This guarantees the children list is
+     * only ever mutated by one pass at a time and the final state always reflects
+     * the most recent store value.
+     */
+    private static readonly renderState;
     transform(attribute: AreDirectiveAttribute, scope: A_Scope, store: AreStore, scene: AreScene, logger: A_Logger, ...args: any[]): void;
     compile(attribute: AreDirectiveAttribute, store: AreStore, scene: AreScene, ...args: any[]): void;
-    update(attribute: AreDirectiveAttribute, store: AreStore, scene: AreScene, ...args: any[]): void;
+    update(attribute: AreDirectiveAttribute, store: AreStore, scene: AreScene, ...args: any[]): void | Promise<void>;
+    /**
+     * Core of the `$for` update: re-diff the source array against the current
+     * children, reconcile reused/removed items, then mount the new ones (small
+     * lists synchronously, large lists time-sliced). Never called while another
+     * pass for the same `$for` is in flight (see `update`).
+     */
+    private performUpdate;
+    /**
+     * 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.
+     */
+    private reconcileOrder;
+    /**
+     * Completes an update pass. If another update() arrived while a chunked
+     * render was streaming, run exactly one more pass now from the latest store
+     * value so the final DOM always reflects the most recent data.
+     */
+    private finishUpdate;
     /**
      * Walks the node's ancestor chain (inclusive) and reports whether the
      * whole path is currently active — i.e. the subtree is actually rendered
@@ -39,6 +86,12 @@ declare class AreDirectiveFor extends AreDirective {
      * Supports both plain key lookups and function-call expressions:
      *   items          → store.get('items')
      *   filter(items)  → store.get('filter')(store.get('items'))
+     *
+     * `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.
      */
     private resolveArray;
     /**

package/dist/node/directives/AreDirectiveFor.directive.d.ts

@@ -1,13 +1,60 @@
 import { A_Scope } from '@adaas/a-concept';
 import { A_Logger } from '@adaas/a-utils/a-logger';
-import { a as AreDirective, b as AreDirectiveAttribute } from '../AreBinding.attribute-Bm5LlOyE.js';
+import { a as AreDirective, b as AreDirectiveAttribute } from '../AreBinding.attribute-GpT-5Qmf.js';
 import { AreStore, AreScene } from '@adaas/are';
 import '../lib/AreStyle/AreStyle.context.js';
 
 declare class AreDirectiveFor extends AreDirective {
+    /**
+     * Lists whose number of NEW item nodes is at or below this threshold render
+     * fully synchronously — byte-for-byte the previous behavior. Typical UIs
+     * (menus, small tables) are therefore completely unaffected; only genuinely
+     * large lists pay the (tiny) scheduling cost to keep the main thread responsive.
+     */
+    private static readonly SYNC_THRESHOLD;
+    /**
+     * Per-chunk time budget (ms). During a large-list render we mount item nodes
+     * until this much time has elapsed, then yield to the browser so it can paint
+     * and process input before the next chunk. ~16ms targets one animation frame.
+     */
+    private static readonly CHUNK_BUDGET_MS;
+    /**
+     * Per-attribute serialization state. A new update() that arrives while a
+     * chunked render of the SAME `$for` is still in flight does NOT start a second
+     * concurrent pass (which could interleave mutations on the shared children
+     * list); instead it marks `pending` and the in-flight run re-runs once more
+     * with the latest data when it finishes. This guarantees the children list is
+     * only ever mutated by one pass at a time and the final state always reflects
+     * the most recent store value.
+     */
+    private static readonly renderState;
     transform(attribute: AreDirectiveAttribute, scope: A_Scope, store: AreStore, scene: AreScene, logger: A_Logger, ...args: any[]): void;
     compile(attribute: AreDirectiveAttribute, store: AreStore, scene: AreScene, ...args: any[]): void;
-    update(attribute: AreDirectiveAttribute, store: AreStore, scene: AreScene, ...args: any[]): void;
+    update(attribute: AreDirectiveAttribute, store: AreStore, scene: AreScene, ...args: any[]): void | Promise<void>;
+    /**
+     * Core of the `$for` update: re-diff the source array against the current
+     * children, reconcile reused/removed items, then mount the new ones (small
+     * lists synchronously, large lists time-sliced). Never called while another
+     * pass for the same `$for` is in flight (see `update`).
+     */
+    private performUpdate;
+    /**
+     * 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.
+     */
+    private reconcileOrder;
+    /**
+     * Completes an update pass. If another update() arrived while a chunked
+     * render was streaming, run exactly one more pass now from the latest store
+     * value so the final DOM always reflects the most recent data.
+     */
+    private finishUpdate;
     /**
      * Walks the node's ancestor chain (inclusive) and reports whether the
      * whole path is currently active — i.e. the subtree is actually rendered
@@ -39,6 +86,12 @@ declare class AreDirectiveFor extends AreDirective {
      * Supports both plain key lookups and function-call expressions:
      *   items          → store.get('items')
      *   filter(items)  → store.get('filter')(store.get('items'))
+     *
+     * `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.
      */
     private resolveArray;
     /**

package/dist/node/directives/AreDirectiveFor.directive.js

@@ -7,6 +7,8 @@ var AreDirective_component = require('@adaas/are-html/directive/AreDirective.com
 var AddComment_instruction = require('@adaas/are-html/instructions/AddComment.instruction');
 var AreDirective_context = require('@adaas/are-html/directive/AreDirective.context');
 var core = require('@adaas/a-frame/core');
+var AreScheduler_helper = require('@adaas/are-html/helpers/AreScheduler.helper');
+var context = require('@adaas/are-html/context');
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -32,7 +34,8 @@ exports.AreDirectiveFor = class AreDirectiveFor extends AreDirective_component.A
     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(AreDirective_context.AreDirectiveContext)?.scope || {};
+    const array = this.resolveArray(store, arrayExpr, attribute.content, contextScope);
     attribute.value = array;
     for (let i = 0; i < array.length; i++) {
       this.spawnItemNode(attribute.template, attribute.owner, key, index, array[i], i);
@@ -47,9 +50,28 @@ exports.AreDirectiveFor = class AreDirectiveFor extends AreDirective_component.A
     scene.unPlan(hostInstruction);
   }
   update(attribute, store, scene, ...args) {
+    let state = exports.AreDirectiveFor.renderState.get(attribute);
+    if (!state) {
+      state = { running: false, pending: false };
+      exports.AreDirectiveFor.renderState.set(attribute, state);
+    }
+    if (state.running) {
+      state.pending = true;
+      return;
+    }
+    return this.performUpdate(attribute, store, scene, state);
+  }
+  /**
+   * Core of the `$for` update: re-diff the source array against the current
+   * children, reconcile reused/removed items, then mount the new ones (small
+   * lists synchronously, large lists time-sliced). Never called while another
+   * pass for the same `$for` is in flight (see `update`).
+   */
+  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(AreDirective_context.AreDirectiveContext)?.scope || {};
+    const newArray = this.resolveArray(store, arrayExpr, attribute.content, contextScope);
     const currentChildren = [...owner.children];
     attribute.value = newArray;
     const attached = this.isAttached(owner);
@@ -63,13 +85,17 @@ exports.AreDirectiveFor = class AreDirectiveFor extends AreDirective_component.A
       childByKey.set(k, child);
       remaining.add(child);
     }
-    const newOnes = [];
+    const toCreate = [];
+    const finalByKey = /* @__PURE__ */ new Map();
+    const orderedKeys = new Array(newArray.length);
     for (let i = 0; i < newArray.length; i++) {
       const item = newArray[i];
       const k = computeKey(item, i);
+      orderedKeys[i] = k;
       const existing = childByKey.get(k);
       if (existing) {
         remaining.delete(existing);
+        finalByKey.set(k, existing);
         let directiveContext = existing.scope.resolveFlat(AreDirective_context.AreDirectiveContext);
         if (!directiveContext) {
           directiveContext = new AreDirective_context.AreDirectiveContext(existing.aseid);
@@ -81,18 +107,88 @@ exports.AreDirectiveFor = class AreDirectiveFor extends AreDirective_component.A
           [index || "index"]: i
         };
       } else {
-        const itemNode = this.spawnItemNode(attribute.template, owner, key, index, item, i);
-        newOnes.push(itemNode);
+        toCreate.push({ item, idx: i, key: k });
       }
     }
     for (const child of remaining) {
       if (attached) child.unmount();
       owner.removeChild(child);
     }
-    for (const child of newOnes) {
+    const createItem = (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();
+    };
+    if (toCreate.length <= exports.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;
+    let cursor = 0;
+    const processChunk = () => {
+      try {
+        const start = AreScheduler_helper.AreSchedulerHelper.now();
+        while (cursor < toCreate.length) {
+          createItem(toCreate[cursor]);
+          cursor++;
+          if (AreScheduler_helper.AreSchedulerHelper.now() - start >= exports.AreDirectiveFor.CHUNK_BUDGET_MS) break;
+        }
+      } catch (error) {
+        state.running = false;
+        state.pending = false;
+        throw error;
+      }
+      if (cursor < toCreate.length) {
+        return new Promise((resolve) => {
+          AreScheduler_helper.AreSchedulerHelper.scheduleMacrotask(() => resolve(processChunk()));
+        });
+      }
+      if (attached) this.reconcileOrder(owner, orderedKeys, finalByKey);
+      return this.finishUpdate(attribute, store, scene, state);
+    };
+    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$1 = owner.scope.resolve(context.AreHTMLEngineContext);
+    if (!context$1) return;
+    const anchor = context$1.getNodeElement(owner);
+    if (!anchor || !anchor.parentNode) return;
+    const parent = anchor.parentNode;
+    let ref = anchor;
+    for (let i = orderedKeys.length - 1; i >= 0; i--) {
+      const node = finalByKey.get(orderedKeys[i]);
+      if (!node) continue;
+      const element = context$1.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
+   * value so the final DOM always reflects the most recent data.
+   */
+  finishUpdate(attribute, store, scene, state) {
+    state.running = false;
+    if (state.pending) {
+      state.pending = false;
+      return this.performUpdate(attribute, store, scene, state);
     }
   }
   /**
@@ -173,13 +269,23 @@ exports.AreDirectiveFor = class AreDirectiveFor extends AreDirective_component.A
    * Supports both plain key lookups and function-call expressions:
    *   items          → store.get('items')
    *   filter(items)  → store.get('filter')(store.get('items'))
+   *
+   * `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) {
+  resolveArray(store, arrayExpr, fullContent, contextScope = {}) {
+    const getRoot = (rawKey) => {
+      const k = rawKey.replace(/\?$/, "");
+      return k in contextScope ? contextScope[k] : store.get(k);
+    };
     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 are.AreCompilerError({
           title: 'Invalid "for" Directive Function',
@@ -193,25 +299,25 @@ exports.AreDirectiveFor = class AreDirectiveFor extends AreDirective_component.A
         const stripped = arg.replace(/\?$/, "");
         if (stripped.includes(".")) {
           const parts = stripped.split(".").map((p) => p.replace(/\?$/, ""));
-          let val = store.get(parts[0]);
+          let val = getRoot(parts[0]);
           for (let j = 1; j < parts.length; j++) {
             if (val == null) return void 0;
             val = val[parts[j]];
           }
           return val ?? void 0;
         }
-        return store.get(stripped);
+        return getRoot(stripped);
       });
       result = fn(...resolvedArgs);
     } else if (arrayExpr.includes(".")) {
       const parts = arrayExpr.split(".").map((p) => p.replace(/\?$/, ""));
-      result = store.get(parts[0]);
+      result = getRoot(parts[0]);
       for (let i = 1; i < parts.length; i++) {
         if (result == null) break;
         result = result[parts[i]];
       }
     } else {
-      result = store.get(arrayExpr.replace(/\?$/, ""));
+      result = getRoot(arrayExpr);
     }
     if (result == null) return [];
     if (!Array.isArray(result))
@@ -253,6 +359,29 @@ exports.AreDirectiveFor = class AreDirectiveFor extends AreDirective_component.A
     return itemNode;
   }
 };
+/**
+ * Lists whose number of NEW item nodes is at or below this threshold render
+ * fully synchronously — byte-for-byte the previous behavior. Typical UIs
+ * (menus, small tables) are therefore completely unaffected; only genuinely
+ * large lists pay the (tiny) scheduling cost to keep the main thread responsive.
+ */
+exports.AreDirectiveFor.SYNC_THRESHOLD = 100;
+/**
+ * Per-chunk time budget (ms). During a large-list render we mount item nodes
+ * until this much time has elapsed, then yield to the browser so it can paint
+ * and process input before the next chunk. ~16ms targets one animation frame.
+ */
+exports.AreDirectiveFor.CHUNK_BUDGET_MS = 16;
+/**
+ * Per-attribute serialization state. A new update() that arrives while a
+ * chunked render of the SAME `$for` is still in flight does NOT start a second
+ * concurrent pass (which could interleave mutations on the shared children
+ * list); instead it marks `pending` and the in-flight run re-runs once more
+ * with the latest data when it finishes. This guarantees the children list is
+ * only ever mutated by one pass at a time and the final state always reflects
+ * the most recent store value.
+ */
+exports.AreDirectiveFor.renderState = /* @__PURE__ */ new WeakMap();
 __decorateClass([
   AreDirective_component.AreDirective.Transform,
   __decorateParam(0, aConcept.A_Inject(aConcept.A_Caller)),