@adaas/are-html 0.0.20 → 0.0.22

package/dist/browser/index.mjs

@@ -1,11 +1,11 @@
-import { AreStore, AreScene, AreSyntax, AreCompiler, AreInterpreter, AreInstructionDefaultNames, AreNodeFeatures, AreContext, AreLifecycle, AreSignalsContext, AreAttributeFeatures, Are, AreNode, AreDeclaration, AreAttribute, AreCompilerError, AreMutation, AreSignal, AreInterpreterError, AreTokenizer, AreTransformer, AreEngine, AreSignals, AreEvent } from '@adaas/are';
+import { AreStore, AreScene, AreSyntax, AreCompiler, AreInterpreter, AreInstructionDefaultNames, AreNodeFeatures, AreContext, AreLifecycle, AreSignalsContext, AreAttributeFeatures, Are, AreCompilerError, AreNode, AreDeclaration, AreAttribute, AreMutation, AreSignal, AreInterpreterError, AreTokenizer, AreTransformer, AreEngine, AreSignals, AreEvent } from '@adaas/are';
 import { A_Frame } from '@adaas/a-frame/core';
 import { A_Inject, A_Caller, A_Feature, A_Meta, A_Scope, A_Dependency, A_Component, A_Context, A_ComponentMeta, A_FormatterHelper, A_Fragment } from '@adaas/a-concept';
 import { A_Logger } from '@adaas/a-utils/a-logger';
 import { A_ExecutionContext } from '@adaas/a-utils/a-execution';
 import { A_Route } from '@adaas/a-utils/a-route';
 import { A_ServiceFeatures } from '@adaas/a-utils/a-service';
-import { A_SignalVector } from '@adaas/a-utils/a-signal';
+import { A_SignalState, A_SignalVector } from '@adaas/a-utils/a-signal';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -207,7 +207,8 @@ var AreHTMLInstructions = {
   AddStyle: "_AreHTML_AddStyle",
   AddListener: "_AreHTML_AddListener",
   AddInterpolation: "_AreHTML_AddInterpolation",
-  AddComment: "_AreHTML_AddComment"
+  AddComment: "_AreHTML_AddComment",
+  HideElement: "_AreHTML_HideElement"
 };
 
 // src/instructions/AddComment.instruction.ts
@@ -235,6 +236,44 @@ var AreDirectiveContext = class extends A_ExecutionContext {
     this.scope = {};
   }
 };
+
+// src/helpers/AreScheduler.helper.ts
+var AreSchedulerHelper = class {
+  /**
+   * 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);
+  }
+};
+/** FIFO queue of callbacks waiting for their posted macrotask to fire. */
+AreSchedulerHelper._queue = [];
+
+// src/directives/AreDirectiveFor.directive.ts
 var AreDirectiveFor = class extends AreDirective {
   transform(attribute, scope, store, scene, logger, ...args) {
     logger.debug(`[Transform] directive $FOR for <${attribute.owner.aseid.toString()}>`);
@@ -263,11 +302,30 @@ var AreDirectiveFor = class extends AreDirective {
     scene.unPlan(hostInstruction);
   }
   update(attribute, store, scene, ...args) {
+    let state = AreDirectiveFor.renderState.get(attribute);
+    if (!state) {
+      state = { running: false, pending: false };
+      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 currentChildren = [...owner.children];
     attribute.value = newArray;
+    const attached = this.isAttached(owner);
     const computeKey = this.makeKeyFn(key, index, trackExpr);
     const childByKey = /* @__PURE__ */ new Map();
     const remaining = /* @__PURE__ */ new Set();
@@ -278,7 +336,7 @@ var AreDirectiveFor = class extends AreDirective {
       childByKey.set(k, child);
       remaining.add(child);
     }
-    const newOnes = [];
+    const toCreate = [];
     for (let i = 0; i < newArray.length; i++) {
       const item = newArray[i];
       const k = computeKey(item, i);
@@ -296,20 +354,73 @@ var AreDirectiveFor = class extends AreDirective {
           [index || "index"]: i
         };
       } else {
-        const itemNode = this.spawnItemNode(attribute.template, owner, key, index, item, i);
-        newOnes.push(itemNode);
+        toCreate.push({ item, idx: i });
       }
     }
     for (const child of remaining) {
-      child.unmount();
+      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);
       child.transform();
       child.compile();
-      child.mount();
+      if (attached) child.mount();
+    };
+    if (toCreate.length <= AreDirectiveFor.SYNC_THRESHOLD) {
+      for (const desc of toCreate) createItem(desc);
+      return this.finishUpdate(attribute, store, scene, state);
+    }
+    state.running = true;
+    let cursor = 0;
+    const processChunk = () => {
+      try {
+        const start = AreSchedulerHelper.now();
+        while (cursor < toCreate.length) {
+          createItem(toCreate[cursor]);
+          cursor++;
+          if (AreSchedulerHelper.now() - start >= AreDirectiveFor.CHUNK_BUDGET_MS) break;
+        }
+      } catch (error) {
+        state.running = false;
+        state.pending = false;
+        throw error;
+      }
+      if (cursor < toCreate.length) {
+        return new Promise((resolve) => {
+          AreSchedulerHelper.scheduleMacrotask(() => resolve(processChunk()));
+        });
+      }
+      return this.finishUpdate(attribute, store, scene, state);
+    };
+    return processChunk();
+  }
+  /**
+   * 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);
     }
   }
+  /**
+   * Walks the node's ancestor chain (inclusive) and reports whether the
+   * whole path is currently active — i.e. the subtree is actually rendered
+   * into the DOM. A single inactive ancestor scene (e.g. a `$if` whose
+   * condition is false) means the subtree is detached.
+   */
+  isAttached(node) {
+    let current = node;
+    while (current) {
+      if (current.scene?.isInactive) return false;
+      current = current.parent;
+    }
+    return true;
+  }
   // ─────────────────────────────────────────────────────────────────────────────
   // ── Helpers ──────────────────────────────────────────────────────────────────
   // ─────────────────────────────────────────────────────────────────────────────
@@ -454,6 +565,29 @@ var AreDirectiveFor = class extends AreDirective {
     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.
+ */
+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.
+ */
+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.
+ */
+AreDirectiveFor.renderState = /* @__PURE__ */ new WeakMap();
 __decorateClass([
   AreDirective.Transform,
   __decorateParam(0, A_Inject(A_Caller)),
@@ -556,6 +690,79 @@ AreDirectiveIf = __decorateClass([
   }),
   AreDirective.Priority(2)
 ], AreDirectiveIf);
+var HideElementInstruction = class extends AreMutation {
+  constructor(parent, props) {
+    if ("aseid" in props) {
+      super(props);
+    } else {
+      super(AreHTMLInstructions.HideElement, parent, props);
+    }
+  }
+};
+HideElementInstruction = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: 'Toggles the visibility of an existing element by setting its inline display to "none" on apply and restoring the previous inline display on revert. Used by the $show directive to hide/show an element without unmounting it, preserving its subtree, listeners and scene state.'
+  })
+], HideElementInstruction);
+var AreDirectiveShow = class extends AreDirective {
+  transform(attribute, logger, ...args) {
+    logger.debug(`[Transform] directive $SHOW for <${attribute.owner.aseid.toString()}> (no structural change)`);
+  }
+  compile(attribute, store, scene, syntax, directiveContext, ...args) {
+    const visible = !!syntax.evaluate(attribute.content, store, {
+      ...directiveContext?.scope || {}
+    });
+    attribute.value = visible;
+    const hide = new HideElementInstruction(scene.host, {});
+    attribute.cache = hide;
+    if (!visible)
+      scene.plan(hide);
+  }
+  update(attribute, store, scene, syntax, directiveContext, ...args) {
+    const previous = !!attribute.value;
+    const next = !!syntax.evaluate(attribute.content, store, {
+      ...directiveContext?.scope || {}
+    });
+    attribute.value = next;
+    if (previous === next) return;
+    const hide = attribute.cache;
+    if (!hide) return;
+    if (next)
+      scene.unPlan(hide);
+    else
+      scene.plan(hide);
+    attribute.owner.interpret();
+  }
+};
+__decorateClass([
+  AreDirective.Transform,
+  __decorateParam(0, A_Inject(A_Caller)),
+  __decorateParam(1, A_Inject(A_Logger))
+], AreDirectiveShow.prototype, "transform", 1);
+__decorateClass([
+  AreDirective.Compile,
+  __decorateParam(0, A_Inject(A_Caller)),
+  __decorateParam(1, A_Inject(AreStore)),
+  __decorateParam(2, A_Inject(AreScene)),
+  __decorateParam(3, A_Inject(AreSyntax)),
+  __decorateParam(4, A_Inject(AreDirectiveContext))
+], AreDirectiveShow.prototype, "compile", 1);
+__decorateClass([
+  AreDirective.Update,
+  __decorateParam(0, A_Inject(A_Caller)),
+  __decorateParam(1, A_Inject(AreStore)),
+  __decorateParam(2, A_Inject(AreScene)),
+  __decorateParam(3, A_Inject(AreSyntax)),
+  __decorateParam(4, A_Inject(AreDirectiveContext))
+], AreDirectiveShow.prototype, "update", 1);
+AreDirectiveShow = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "Built-in $show directive. Toggles an element's visibility by flipping its inline display value based on a store expression, keeping the element mounted (subtree, listeners and scene state preserved) instead of unmounting it like $if."
+  }),
+  AreDirective.Priority(3)
+], AreDirectiveShow);
 var AddAttributeInstruction = class extends AreMutation {
   constructor(parent, props) {
     if ("aseid" in props) {
@@ -1486,6 +1693,19 @@ var AreHTMLInterpreter = class extends AreInterpreter {
       console.log("Error removing attribute:", error);
     }
   }
+  hideElement(mutation, context) {
+    const element = context.getElementByInstruction(mutation.parent);
+    if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
+    const el = element;
+    mutation.cache = el.style.display;
+    el.style.display = "none";
+  }
+  showElement(mutation, context) {
+    const element = context.getElementByInstruction(mutation.parent);
+    if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
+    const el = element;
+    el.style.display = mutation.payload?.display ?? mutation.cache ?? "";
+  }
   addEventListener(mutation, context, store, syntax, directiveContext, logger) {
     const element = context.getElementByInstruction(mutation.parent);
     if (!element) {
@@ -1738,6 +1958,22 @@ __decorateClass([
   __decorateParam(0, A_Inject(A_Caller)),
   __decorateParam(1, A_Inject(AreHTMLEngineContext))
 ], AreHTMLInterpreter.prototype, "removeAttribute", 1);
+__decorateClass([
+  A_Frame.Define({
+    description: "Hide an element by setting inline display:none, caching its previous inline display value for restoration on revert."
+  }),
+  AreInterpreter.Apply(AreHTMLInstructions.HideElement),
+  __decorateParam(0, A_Inject(A_Caller)),
+  __decorateParam(1, A_Inject(AreHTMLEngineContext))
+], AreHTMLInterpreter.prototype, "hideElement", 1);
+__decorateClass([
+  A_Frame.Define({
+    description: "Restore an element hidden by a HideElement instruction back to its previous inline display value."
+  }),
+  AreInterpreter.Revert(AreHTMLInstructions.HideElement),
+  __decorateParam(0, A_Inject(A_Caller)),
+  __decorateParam(1, A_Inject(AreHTMLEngineContext))
+], AreHTMLInterpreter.prototype, "showElement", 1);
 __decorateClass([
   A_Frame.Define({
     description: "Add an event listener to an HTML element based on the provided mutation instruction."
@@ -1908,10 +2144,45 @@ var AreHTMLLifecycle = class extends AreLifecycle {
     logger?.debug(`[Mount] Component Trigger for <${node.aseid.entity}>  with aseid :{${node.aseid.toString()}}`);
     if (scene.isInactive) return;
     node.interpret();
-    for (let i = 0; i < node.children.length; i++) {
-      const child = node.children[i];
-      child.mount();
-    }
+    const stack = [];
+    for (let i = node.children.length - 1; i >= 0; i--) {
+      stack.push({ node: node.children[i], entered: false });
+    }
+    const step = () => {
+      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 i = current.children.length - 1; i >= 0; i--) {
+          stack.push({ node: current.children[i], entered: false });
+        }
+      }
+    };
+    const drive = () => {
+      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);
+              }
+            });
+          });
+        }
+      }
+    };
+    return drive();
   }
   updateDirectiveAttribute(directive, scope, feature, logger, ...args) {
     if (directive.component) {
@@ -1921,6 +2192,13 @@ var AreHTMLLifecycle = class extends AreLifecycle {
     }
   }
 };
+/**
+ * Per-chunk time budget (ms) for the time-sliced initial mount walk. While
+ * mounting a large subtree we keep applying nodes until this much wall-clock
+ * time has elapsed, then yield to the browser so it can paint and process
+ * input before the next chunk. ~16ms targets a single animation frame.
+ */
+AreHTMLLifecycle.MOUNT_BUDGET_MS = 16;
 __decorateClass([
   AreLifecycle.Init(AreComponentNode),
   __decorateParam(0, A_Inject(A_Caller)),
@@ -2003,6 +2281,97 @@ AreHTMLTransformer = __decorateClass([
     description: "HTML-specific transformer extending AreTransformer. Handles directive-attribute structural rewrites before compilation \u2014 sorting directives by declared priority and expanding compound directive expressions \u2014 so the compiler receives a clean, ordered AreHTMLNode tree ready for instruction emission."
   })
 ], AreHTMLTransformer);
+var AreRootCache = class extends A_Fragment {
+  constructor(limit = 10) {
+    super({ name: "AreRootCache" });
+    /**
+     * rootId -> (component tag -> cache entry). The inner Map preserves
+     * insertion order which is used as the LRU recency order: the first key is
+     * the least-recently-used entry, the last key the most-recently-used.
+     */
+    this._cache = /* @__PURE__ */ new Map();
+    this._limit = Math.max(0, Math.floor(limit));
+  }
+  /**
+   * Maximum number of cached subtrees kept per root.
+   */
+  get limit() {
+    return this._limit;
+  }
+  bucket(rootId) {
+    let bucket = this._cache.get(rootId);
+    if (!bucket) {
+      bucket = /* @__PURE__ */ new Map();
+      this._cache.set(rootId, bucket);
+    }
+    return bucket;
+  }
+  /**
+   * Whether a subtree for the given component tag is currently cached.
+   */
+  has(rootId, tag) {
+    return this.bucket(rootId).has(tag);
+  }
+  /**
+   * Retrieve AND remove a cached subtree so it can become live again. Returns
+   * `undefined` on a cache miss.
+   */
+  take(rootId, tag) {
+    const bucket = this.bucket(rootId);
+    const entry = bucket.get(tag);
+    if (entry) {
+      bucket.delete(tag);
+    }
+    return entry;
+  }
+  /**
+   * Stash a detached subtree under the given component tag. Returns any entries
+   * that were evicted to honour the LRU limit (or replaced for the same tag) so
+   * the caller can `destroy()` them.
+   */
+  put(rootId, tag, entry) {
+    const bucket = this.bucket(rootId);
+    const evicted = [];
+    const existing = bucket.get(tag);
+    if (existing) {
+      bucket.delete(tag);
+      if (existing.node !== entry.node) {
+        evicted.push(existing);
+      }
+    }
+    bucket.set(tag, entry);
+    while (bucket.size > this._limit) {
+      const oldestKey = bucket.keys().next().value;
+      if (oldestKey === void 0) {
+        break;
+      }
+      const oldest = bucket.get(oldestKey);
+      bucket.delete(oldestKey);
+      evicted.push(oldest);
+    }
+    return evicted;
+  }
+  /**
+   * Remove and return every cached entry for a root (e.g. on teardown) so the
+   * caller can destroy them.
+   */
+  clear(rootId) {
+    const bucket = this._cache.get(rootId);
+    if (!bucket) {
+      return [];
+    }
+    const entries = [...bucket.values()];
+    bucket.clear();
+    this._cache.delete(rootId);
+    return entries;
+  }
+};
+AreRootCache = __decorateClass([
+  A_Frame.Define({
+    namespace: "a-are-html",
+    description: "AreRootCache is a fragment that keeps a small per-root LRU of previously rendered are-root subtrees. When an are-root swaps the component it displays, the outgoing subtree is stashed here (unmounted + detached, but not destroyed) so that routing back to it can re-inject the preserved scene instantly instead of rebuilding from scratch."
+  })
+], AreRootCache);
 
 // src/engine/AreHTML.engine.ts
 var AreHTMLEngine = class extends AreEngine {
@@ -2049,7 +2418,7 @@ var AreHTMLEngine = class extends AreEngine {
       ]
     });
   }
-  async init(scope, signalContext) {
+  async init(scope, signalContext, rootCache) {
     this.package(scope, {
       context: new AreHTMLEngineContext({}),
       syntax: this.DefaultSyntax,
@@ -2063,6 +2432,10 @@ var AreHTMLEngine = class extends AreEngine {
       signalContext = new AreSignalsContext();
       scope.register(signalContext);
     }
+    if (!rootCache) {
+      rootCache = new AreRootCache();
+      scope.register(rootCache);
+    }
   }
   rootElementMatcher(source, from, to, build) {
     const rootTag = "are-root";
@@ -2172,7 +2545,8 @@ __decorateClass([
     before: /.*/
   }),
   __decorateParam(0, A_Inject(A_Scope)),
-  __decorateParam(1, A_Inject(AreSignalsContext))
+  __decorateParam(1, A_Inject(AreSignalsContext)),
+  __decorateParam(2, A_Inject(AreRootCache))
 ], AreHTMLEngine.prototype, "init", 1);
 AreHTMLEngine = __decorateClass([
   A_Frame.Define({
@@ -2181,7 +2555,7 @@ AreHTMLEngine = __decorateClass([
   })
 ], AreHTMLEngine);
 var AreRoot = class extends Are {
-  async template(root, logger, signalsContext) {
+  async template(root, logger, signalsContext, signalState) {
     const rootId = root.id;
     if (signalsContext && !signalsContext.hasRoot(rootId)) {
       if (!root.content?.trim()) {
@@ -2193,26 +2567,9 @@ var AreRoot = class extends Are {
       }
       return;
     }
-    const currentRoute = AreRoute.default();
-    let componentName;
-    if (currentRoute) {
-      const initialVector = new A_SignalVector([currentRoute]);
-      let renderTarget = signalsContext?.findComponentByVector(rootId, initialVector);
-      if (!renderTarget) {
-        const signalsMeta = A_Context.meta(AreSignals);
-        const pool = signalsContext?.getComponentById(rootId);
-        const metaTarget = signalsMeta?.findComponentByVector(
-          initialVector,
-          pool?.length ? pool : void 0
-        );
-        if (metaTarget && (!pool?.length || pool.includes(metaTarget))) {
-          renderTarget = metaTarget;
-        }
-      }
-      if (renderTarget?.name) {
-        componentName = A_FormatterHelper.toKebabCase(renderTarget.name);
-      }
-    }
+    const initialVector = this.buildInitialVector(signalState);
+    const renderTarget = this.matchComponent(rootId, initialVector, signalsContext);
+    let componentName = renderTarget?.name ? A_FormatterHelper.toKebabCase(renderTarget.name) : void 0;
     if (!componentName) {
       if (root.content?.trim()) {
         return;
@@ -2234,32 +2591,17 @@ var AreRoot = class extends Are {
     }
     root.setContent(`<${componentName}></${componentName}>`);
   }
-  async onSignal(root, vector, logger, signalsContext) {
+  async onSignal(root, vector, logger, signalsContext, cache) {
     const rootId = root.id;
     if (signalsContext && !signalsContext.hasRoot(rootId)) {
       return;
     }
-    let renderTarget = signalsContext?.findComponentByVector(rootId, vector);
-    if (!renderTarget) {
-      const signalsMeta = A_Context.meta(AreSignals);
-      const pool = signalsContext?.getComponentById(rootId);
-      const metaTarget = signalsMeta?.findComponentByVector(
-        vector,
-        pool?.length ? pool : void 0
-      );
-      if (metaTarget && (!pool?.length || pool.includes(metaTarget))) {
-        renderTarget = metaTarget;
-      }
-    }
+    const renderTarget = this.matchComponent(rootId, vector, signalsContext);
     const def = signalsContext?.getDefault(rootId);
     const componentName = renderTarget?.name ? A_FormatterHelper.toKebabCase(renderTarget.name) : def?.name ? A_FormatterHelper.toKebabCase(def.name) : void 0;
     if (!componentName) {
-      for (let i = 0; i < root.children.length; i++) {
-        const child = root.children[i];
-        signalsContext?.unsubscribe(child);
-        child.unmount();
-        child.destroy();
-        root.removeChild(child);
+      for (const child of [...root.children]) {
+        this.stashChild(root, child, signalsContext, cache);
       }
       root.setContent("");
       return;
@@ -2268,13 +2610,14 @@ var AreRoot = class extends Are {
     if (currentChild?.type === componentName) {
       return;
     }
+    for (const child of [...root.children]) {
+      this.stashChild(root, child, signalsContext, cache);
+    }
     root.setContent(`<${componentName}></${componentName}>`);
-    for (let i = 0; i < root.children.length; i++) {
-      const child = root.children[i];
-      signalsContext?.unsubscribe(child);
-      child.unmount();
-      child.destroy();
-      root.removeChild(child);
+    const cached = cache?.take(root.id, componentName);
+    if (cached) {
+      this.restoreChild(root, cached, signalsContext);
+      return;
     }
     root.tokenize();
     for (let i = 0; i < root.children.length; i++) {
@@ -2286,22 +2629,141 @@ var AreRoot = class extends Are {
       }
       child.transform();
       child.compile();
-      child.mount();
+      await child.mount();
+    }
+  }
+  /**
+   * Resolves the component a vector should render for the given root, mirroring
+   * the priority used everywhere in the routing system:
+   *   1. Root-specific conditions registered on AreSignalsContext.
+   *   2. The global AreSignalsMeta map, restricted to this outlet's pool.
+   *
+   * Passing the pool *into* the meta lookup is critical: without it, the first
+   * globally matching component wins and may belong to a different outlet
+   * (e.g. AisRequirementsPanel for the meta-outlet matching
+   * AisEditorCursorScope) — the pool check would then reject it and the outlet
+   * would fall back to its default, hiding a valid in-pool match (e.g.
+   * AisDiagramTab matching AisSetPrimaryDisplay).
+   *
+   * Returns `undefined` when nothing matches — callers decide whether to use a
+   * configured default, body content, or clear the outlet.
+   */
+  matchComponent(rootId, vector, signalsContext) {
+    if (!vector) return void 0;
+    let renderTarget = signalsContext?.findComponentByVector(rootId, vector);
+    if (!renderTarget) {
+      const signalsMeta = A_Context.meta(AreSignals);
+      const pool = signalsContext?.getComponentById(rootId);
+      const metaTarget = signalsMeta?.findComponentByVector(
+        vector,
+        pool?.length ? pool : void 0,
+        rootId
+      );
+      if (metaTarget && (!pool?.length || pool.includes(metaTarget))) {
+        renderTarget = metaTarget;
+      }
     }
+    return renderTarget;
+  }
+  /**
+   * Builds the vector used for the INITIAL render. It is seeded from the
+   * accumulated signal state (every signal dispatched on the bus so far) so a
+   * freshly-mounted outlet reflects the live application state immediately,
+   * not just on the next signal tick. The current URL route is appended when
+   * no AreRoute is already present in the state, so route-driven outlets still
+   * resolve on the very first paint (before AreRouteWatcher has dispatched).
+   */
+  buildInitialVector(signalState) {
+    const signals = [];
+    if (signalState) {
+      for (const signal of signalState.toVector()) {
+        if (signal) signals.push(signal);
+      }
+    }
+    if (!signals.some((signal) => signal instanceof AreRoute)) {
+      try {
+        const currentRoute = AreRoute.default();
+        if (currentRoute) signals.push(currentRoute);
+      } catch {
+      }
+    }
+    return new A_SignalVector(signals);
+  }
+  /**
+   * Detach a displayed child subtree from the outlet and stash it in the cache
+   * for fast re-injection later. The subtree is unmounted (its scene plan is
+   * preserved) and deregistered from the root scope, but NOT destroyed. The
+   * nodes that were subscribed to the signal bus are unsubscribed while cached
+   * so the detached DOM never reacts to signals, and recorded so they can be
+   * re-subscribed verbatim on restore.
+   *
+   * When no cache is available, or the LRU evicts an entry, the affected
+   * subtree is fully destroyed.
+   */
+  stashChild(root, child, signalsContext, cache) {
+    const tag = child.type;
+    child.unmount();
+    const subscribers = signalsContext ? this.collectSubscribers(child, signalsContext) : [];
+    for (const node of subscribers) {
+      signalsContext?.unsubscribe(node);
+    }
+    root.removeChild(child);
+    if (!cache) {
+      void child.destroy();
+      return;
+    }
+    const evicted = cache.put(root.id, tag, { node: child, subscribers });
+    for (const entry of evicted) {
+      void entry.node.destroy();
+    }
+  }
+  /**
+   * Re-attach a cached subtree to the outlet and re-mount it from its preserved
+   * scene plan, re-subscribing exactly the nodes that were subscribed before it
+   * was cached.
+   */
+  restoreChild(root, entry, signalsContext) {
+    const child = entry.node;
+    root.addChild(child);
+    for (const node of entry.subscribers) {
+      signalsContext?.subscribe(node);
+    }
+    child.mount();
+  }
+  /**
+   * Walk a subtree and collect the nodes currently registered as signal
+   * subscribers. Mirrors the subscription performed at init time in
+   * AreHTMLLifecycle (component nodes and root nodes) without depending on the
+   * concrete node classes — it simply intersects the subtree with the live
+   * subscriber registry.
+   */
+  collectSubscribers(node, signalsContext) {
+    const result = [];
+    const queue = [node];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (signalsContext.subscribers.has(current)) {
+        result.push(current);
+      }
+      queue.push(...current.children);
+    }
+    return result;
   }
 };
 __decorateClass([
   Are.Template,
   __decorateParam(0, A_Inject(A_Caller)),
   __decorateParam(1, A_Inject(A_Logger)),
-  __decorateParam(2, A_Inject(AreSignalsContext))
+  __decorateParam(2, A_Inject(AreSignalsContext)),
+  __decorateParam(3, A_Inject(A_SignalState))
 ], AreRoot.prototype, "template", 1);
 __decorateClass([
   Are.Signal,
   __decorateParam(0, A_Inject(A_Caller)),
   __decorateParam(1, A_Inject(A_SignalVector)),
   __decorateParam(2, A_Inject(A_Logger)),
-  __decorateParam(3, A_Inject(AreSignalsContext))
+  __decorateParam(3, A_Inject(AreSignalsContext)),
+  __decorateParam(4, A_Inject(AreRootCache))
 ], AreRoot.prototype, "onSignal", 1);
 AreRoot = __decorateClass([
   A_Frame.Define({
@@ -2372,6 +2834,6 @@ AreRouteWatcher = __decorateClass([
   })
 ], AreRouteWatcher);
 
-export { AddAttributeInstruction, AddElementInstruction, AddInterpolationInstruction, AddListenerInstruction, AddStyleInstruction, AddTextInstruction, AreBindingAttribute, AreComment, AreComponentNode, AreDirective, AreDirectiveAttribute, AreDirectiveContext, AreDirectiveFeatures, AreDirectiveFor, AreDirectiveIf, AreDirectiveMeta, AreEventAttribute, AreHTMLAttribute, AreHTMLCompiler, AreHTMLEngine, AreHTMLEngineContext, AreHTMLInstructions, AreHTMLInterpreter, AreHTMLLifecycle, AreHTMLNode, AreHTMLTokenizer, AreHTMLTransformer, AreInterpolation, AreRoot, AreRootNode, AreRoute, AreRouteWatcher, AreStaticAttribute, AreStyle, AreText, BOOLEAN_ATTRIBUTES, IDL_FORM_PROPERTIES, LISTENER_OPTION_MODIFIERS, SVG_ATTRIBUTE_NS, SVG_NAMESPACE, VOID_ELEMENTS, isBooleanAttribute, isIDLFormProperty, isVoidElement, normalizeClassValue, normalizeStyleValue, parseEventName, toDOMString };
+export { AddAttributeInstruction, AddElementInstruction, AddInterpolationInstruction, AddListenerInstruction, AddStyleInstruction, AddTextInstruction, AreBindingAttribute, AreComment, AreComponentNode, AreDirective, AreDirectiveAttribute, AreDirectiveContext, AreDirectiveFeatures, AreDirectiveFor, AreDirectiveIf, AreDirectiveMeta, AreDirectiveShow, AreEventAttribute, AreHTMLAttribute, AreHTMLCompiler, AreHTMLEngine, AreHTMLEngineContext, AreHTMLInstructions, AreHTMLInterpreter, AreHTMLLifecycle, AreHTMLNode, AreHTMLTokenizer, AreHTMLTransformer, AreInterpolation, AreRoot, AreRootCache, AreRootNode, AreRoute, AreRouteWatcher, AreStaticAttribute, AreStyle, AreText, BOOLEAN_ATTRIBUTES, HideElementInstruction, IDL_FORM_PROPERTIES, LISTENER_OPTION_MODIFIERS, SVG_ATTRIBUTE_NS, SVG_NAMESPACE, VOID_ELEMENTS, isBooleanAttribute, isIDLFormProperty, isVoidElement, normalizeClassValue, normalizeStyleValue, parseEventName, toDOMString };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map