@adukiorg/anza 0.2.0 → 0.2.3

package/src/core/router/container.js

@@ -1,121 +1,109 @@
 /**
  * src/core/router/container.js
  *
- * Dynamic Container Registry for Advanced Topologies (v2).
- * Maintains a real-time, non-blocking map of actively mounted DOM layout containers.
- * Employs WeakRef and FinalizationRegistry for perfect GC safety, and idle
- * MutationObservers for standard HTML fallback tracking.
+ * Container registry facade. Delegates storage to the hierarchical graph
+ * (graph.js) while preserving the historical public API and the CSS-selector
+ * fallback for containers that are plain DOM elements rather than registered
+ * docks.
  *
- * Source: advance2.md
+ * Source: tasks.md Phase 3, advance2.md
  */
 
-// string -> WeakRef<HTMLElement>
-const containerNodeMap = new Map();
+import { add, remove, element as graphElement, get, clear } from './graph.js';
 
-// Passive safety net: prune stale map entries after GC
-const cleanupRegistry = typeof FinalizationRegistry !== 'undefined' 
-  ? new FinalizationRegistry((name) => {
-      if (containerNodeMap.get(name)?.deref() === undefined) {
-        containerNodeMap.delete(name);
-      }
-    })
-  : { register() {}, unregister() {} };
-
-let observer;
+// Selectors we are still waiting to appear in the DOM.
 const observedSelectors = new Set();
+let observer;
 
 /**
- * Boots the MutationObserver at idle priority if standard selectors are tracked.
+ * Boots the MutationObserver to discover standard (non-dock) containers that
+ * match a tracked CSS selector. Uses requestIdleCallback with a 100ms timeout
+ * so it still fires under sustained animation load, falling back to
+ * requestAnimationFrame where idle callbacks are unavailable (RT bug 8.1).
  */
 function ensureObserver() {
-  if (observer || typeof window === 'undefined' || typeof requestIdleCallback === 'undefined') return;
+  if (observer || typeof window === 'undefined' || typeof MutationObserver === 'undefined') return;
 
-  requestIdleCallback(() => {
+  const attach = () => {
+    if (observer) return;
     observer = new MutationObserver(() => {
-      let activeObservationNeeded = false;
+      let stillWaiting = false;
       for (const selector of observedSelectors) {
-        if (!containerNodeMap.get(selector)?.deref()) {
+        if (!graphElement(selector)) {
           const el = document.querySelector(selector);
-          if (el) {
-            registerContainer(selector, el);
-          } else {
-            activeObservationNeeded = true;
-          }
+          if (el) registerContainer(selector, el);
+          else stillWaiting = true;
         }
       }
-
-      // RT-06: Automatically disconnect MutationObserver if all observed selectors are resolved
-      if (!activeObservationNeeded && observer) {
+      if (!stillWaiting && observer) {
         observer.disconnect();
         observer = null;
       }
     });
-
     observer.observe(document.body, { childList: true, subtree: true });
-  });
+  };
+
+  if (typeof requestIdleCallback !== 'undefined') {
+    requestIdleCallback(attach, { timeout: 100 });
+  } else {
+    requestAnimationFrame(attach);
+  }
 }
 
 /**
  * Registers a layout container as actively mounted in the DOM.
- * @param {string} name - The unique identifier/selector of the container.
- * @param {HTMLElement} element - The DOM element instance.
+ *
+ * @param {string} name - unique registry key (or CSS selector).
+ * @param {HTMLElement} element - the DOM element instance.
+ * @param {string} [parent='body'] - parent container key in the graph.
  */
-export function registerContainer(name, element) {
-  const existing = containerNodeMap.get(name)?.deref();
-  if (existing && existing !== element) {
-    throw new Error(`ContainerError: Singleton violation — '${name}' is already mounted. A second instance cannot register while the first is active.`);
-  }
-
-  containerNodeMap.set(name, new WeakRef(element));
-  cleanupRegistry.register(element, name);
+export function registerContainer(name, element, parent = 'body') {
+  add(name, element, parent);
 }
 
 /**
  * Unregisters a layout container when it is removed from the DOM.
- * @param {string} name - The unique identifier/selector of the container.
- * @param {HTMLElement} element - The DOM element instance (used for safety check).
+ *
+ * @param {string} name - the registry key.
+ * @param {HTMLElement} [element] - element guard for the safety check.
  */
 export function unregisterContainer(name, element) {
-  const existing = containerNodeMap.get(name)?.deref();
-  if (!element || existing === element) {
-    containerNodeMap.delete(name);
-    if (existing) {
-      try { cleanupRegistry.unregister(existing); } catch(e) {}
-    }
-  }
+  remove(name, element);
 }
 
 /**
  * Retrieves an active layout container by name.
- * @param {string} name - The unique identifier of the container.
- * @returns {HTMLElement|undefined} The active container element, or undefined if not mounted.
+ *
+ * A plain key (e.g. 'main') is resolved only through the graph. A CSS selector
+ * (starts with '#', '.', '[', or contains a combinator) additionally resolves
+ * against the document and self-registers on first hit.
+ *
+ * @param {string} name - the registry key or selector.
+ * @returns {HTMLElement|undefined} the element, or undefined if not mounted.
  */
 export function getContainer(name) {
-  let el = containerNodeMap.get(name)?.deref();
+  let el = graphElement(name);
+  if (el) return el;
 
-  // A plain registry key (e.g. 'main') is only ever looked up in the registry.
-  // A CSS selector (starts with '#', '.', '[', or contains a combinator) is
-  // resolved against the document. This removes the ambiguity where 'main'
-  // could mean a registry key or `querySelector('main')`.
-  if (!el && isSelector(name) && typeof document !== 'undefined') {
+  if (isSelector(name) && typeof document !== 'undefined') {
     try {
       el = document.querySelector(name);
       if (el) {
         registerContainer(name, el);
-      } else {
-        if (!observedSelectors.has(name)) {
-          observedSelectors.add(name);
-        }
-        ensureObserver();
+        return el;
       }
-    } catch (err) {
-      // Invalid selector string, ignore.
+      if (!observedSelectors.has(name)) observedSelectors.add(name);
+      ensureObserver();
+    } catch (_) {
+      // Invalid selector string — ignore.
     }
+    return el ?? undefined;
   }
 
-  // Warn on ambiguous names that look like they could be either a key or selector
-  if (!el && typeof name === 'string' && !isSelector(name) && typeof document !== 'undefined') {
-    const queryResult = document.querySelector(name);
+  // Warn when a plain key shadows a real DOM element of the same tag name.
+  if (typeof name === 'string' && typeof document !== 'undefined') {
+    let queryResult = null;
+    try { queryResult = document.querySelector(name); } catch (_) {}
     if (queryResult) {
       console.warn(
         `[Router] Container name "${name}" is ambiguous: it exists in the DOM as a selector ` +
@@ -125,7 +113,7 @@ export function getContainer(name) {
     }
   }
 
-  return el;
+  return el ?? undefined;
 }
 
 /** Heuristic: does this string look like a CSS selector rather than a key? */
@@ -134,13 +122,16 @@ function isSelector(name) {
 }
 
 /**
- * Clears the entire container registry.
+ * Clears the entire container registry and stops selector observation.
  */
 export function clearContainers() {
-  containerNodeMap.clear();
+  clear();
   observedSelectors.clear();
   if (observer) {
     observer.disconnect();
     observer = null;
   }
 }
+
+// Re-export the graph node accessor for modules that need topology directly.
+export { get as getNode };

package/src/core/router/graph.js

@@ -0,0 +1,144 @@
+/**
+ * src/core/router/graph.js
+ *
+ * Hierarchical container graph. Replaces the flat name->WeakRef registry with a
+ * tree that knows parent/child relationships and depth, enabling lowest-common-
+ * ancestor traversal (lca.js) and sequential cascade mounting (cascade.js).
+ *
+ * Every node holds a WeakRef to its element so an unmounted container can be
+ * garbage-collected without a manual unregister. A FinalizationRegistry prunes
+ * stale nodes. The virtual root 'body' always exists.
+ *
+ * Source: tasks.md Phase 3
+ */
+
+class Node {
+  constructor(name, ref, parent) {
+    this.name = name;            // registry key, e.g. 'main' | 'sidebar'
+    this.ref = ref;              // WeakRef<Element> | null (null for virtual root)
+    this.parent = parent;        // Node | null
+    this.children = new Set();   // Set<Node>
+    this.depth = parent ? parent.depth + 1 : 0;
+  }
+
+  /** @returns {boolean} true while the referenced element is still alive. */
+  alive() {
+    return this.ref ? this.ref.deref() !== undefined : true;
+  }
+}
+
+const nodes = new Map();
+const root = new Node('body', null, null);
+nodes.set('body', root);
+
+// Explicit unregistrations. element() returns undefined for a name in this set
+// so a just-unmounted container is not confused with a GC'd one (RT bug 8.2).
+const gone = new Set();
+
+// Prune stale nodes after their element is collected.
+const finalizer = typeof FinalizationRegistry !== 'undefined'
+  ? new FinalizationRegistry((name) => {
+      const node = nodes.get(name);
+      if (node && !node.alive()) detach(name);
+    })
+  : { register() {}, unregister() {} };
+
+/** Removes a node from the tree, reparenting its children to its parent. */
+function detach(name) {
+  const node = nodes.get(name);
+  if (!node || node === root) return;
+  node.parent?.children.delete(node);
+  for (const child of node.children) {
+    child.parent = node.parent;
+    child.depth = child.parent ? child.parent.depth + 1 : 0;
+    node.parent?.children.add(child);
+  }
+  nodes.delete(name);
+}
+
+/**
+ * Inserts (or re-points) a container node under a parent.
+ *
+ * @param {string} name - unique registry key.
+ * @param {Element} el - the container element.
+ * @param {string} [parent='body'] - parent registry key.
+ * @returns {Node} the inserted node.
+ */
+export function add(name, el, parent = 'body') {
+  gone.delete(name);
+
+  const existing = nodes.get(name);
+  if (existing && existing !== root) {
+    const prev = existing.ref?.deref();
+    if (prev && prev !== el) {
+      throw new Error(`ContainerError: Singleton violation — '${name}' is already mounted. A second instance cannot register while the first is active.`);
+    }
+    // Same element re-registering (e.g. HMR): refresh the ref and return.
+    existing.ref = new WeakRef(el);
+    return existing;
+  }
+
+  const parentNode = nodes.get(parent) ?? root;
+  const node = new Node(name, new WeakRef(el), parentNode);
+  parentNode.children.add(node);
+  nodes.set(name, node);
+  finalizer.register(el, name);
+  return node;
+}
+
+/**
+ * Removes a container node. Marks the name as explicitly gone for one macrotask
+ * so a lookup during teardown does not fall back to a stale resolution.
+ *
+ * @param {string} name - registry key.
+ * @param {Element} [el] - element guard; if given, only removes when it matches.
+ */
+export function remove(name, el) {
+  const node = nodes.get(name);
+  if (!node || node === root) return;
+
+  const current = node.ref?.deref();
+  if (el && current && current !== el) return;
+
+  if (current) {
+    try { finalizer.unregister(current); } catch (_) {}
+  }
+  detach(name);
+
+  gone.add(name);
+  if (typeof setTimeout !== 'undefined') {
+    setTimeout(() => gone.delete(name), 0);
+  }
+}
+
+/**
+ * @param {string} name - registry key.
+ * @returns {Node|null} the node, or null if absent.
+ */
+export function get(name) {
+  return nodes.get(name) ?? null;
+}
+
+/**
+ * Resolves a node's live element.
+ *
+ * @param {string} name - registry key.
+ * @returns {Element|null|undefined} element, null if absent,
+ *   or undefined if the name was just explicitly removed.
+ */
+export function element(name) {
+  if (gone.has(name)) return undefined;
+  const node = nodes.get(name);
+  if (!node) return null;
+  return node.ref ? (node.ref.deref() ?? null) : null;
+}
+
+/** Resets the graph to root-only. */
+export function clear() {
+  nodes.clear();
+  root.children.clear();
+  gone.clear();
+  nodes.set('body', root);
+}
+
+export { Node, root };

package/src/core/router/index.js

@@ -48,8 +48,6 @@ import {
 
 import { cache, prefetch } from './cache.js';
 
-import './outlet.js';
-
 export const router = {
   // Registration and boundary hooks
   register,
@@ -110,6 +108,18 @@ export const router = {
 
 // Auto-bootstrap client-side navigation listeners on client load
 if (typeof window !== 'undefined') {
+  // Expose the router globally so non-module scripts, devtools, and definition
+  // helpers (page/dock) can reach it without importing. Non-enumerable and
+  // non-configurable so it cannot be accidentally clobbered or redefined.
+  if (!('router' in window)) {
+    Object.defineProperty(window, 'router', {
+      value: router,
+      writable: false,
+      enumerable: false,
+      configurable: false
+    });
+  }
+
   registerNavigator(navigate);
   setup();
   setupTabSync(router);

package/src/core/router/intercept.js

@@ -12,6 +12,8 @@ import { match } from './match.js';
 import { transitions } from './transitions.js';
 import { getContainer } from './container.js';
 import { isCallback, runCallback } from './handler.js';
+import { boot, reset as resetBoot } from './boot.js';
+import { ensure } from './cascade.js';
 
 let guards = [];
 let notFoundHandler = null;
@@ -147,11 +149,24 @@ export function setup() {
           return;
         }
 
-        // Strict Layout Resolution Guard: prevent blind mounts if required container is inactive
-        if (routeMatch?.route?.meta?.container) {
-          const containerName = routeMatch.route.meta.container;
-          if (!getContainer(containerName)) {
-            const err = new Error(`RouteError: Required layout container '${containerName}' is not active in the DOM.`);
+        // Layout resolution: ensure the route's container chain is mounted.
+        // Routes declare an ordered `via` chain (root-to-leaf) or a single
+        // `container`. Missing containers are mounted via cascade rather than
+        // throwing — a hard refresh on a deep route can now build its own
+        // layout instead of erroring out.
+        if (routeMatch) {
+          const meta = routeMatch.route?.meta ?? {};
+          const chain = Array.isArray(meta.via) && meta.via.length
+            ? meta.via
+            : (meta.container ? [meta.container] : []);
+
+          try {
+            for (let i = 0; i < chain.length; i++) {
+              if (!getContainer(chain[i])) {
+                await ensure(chain[i], chain[i - 1] ?? 'body');
+              }
+            }
+          } catch (err) {
             emit('error', { error: err, url: destination.url, route: routeMatch.route, phase: 'container' });
             throw err;
           }
@@ -244,8 +259,11 @@ export function setup() {
   window.navigation.addEventListener('navigatesuccess', successListener);
   window.navigation.addEventListener('navigateerror', errorListener);
 
-  // Trigger initial on-boot matching and emit initial events once setup is completed
-  Promise.resolve().then(async () => {
+  // Trigger initial on-boot matching once the DOM is parsed and every gated
+  // prerequisite (element definitions registered via boot.gate) has settled.
+  // Deferring this past DOMContentLoaded is what survives a hard refresh on a
+  // deep route — the first match no longer races element registration.
+  boot(async () => {
     const url = window.navigation.currentEntry?.url || window.location.href;
     const routeMatch = await match(url);
     if (routeMatch) {
@@ -284,6 +302,7 @@ export function destroy() {
 
   guards = [];
   notFoundHandler = null;
+  resetBoot();
 
   for (const set of Object.values(listeners)) {
     set.clear();

package/src/core/router/lca.js

@@ -0,0 +1,58 @@
+/**
+ * src/core/router/lca.js
+ *
+ * Lowest common ancestor over the container graph. Given two container names,
+ * computes the deepest node that is an ancestor of both — the pivot for a
+ * cross-branch navigation (everything below it on the source side unmounts,
+ * everything below it on the target side mounts).
+ *
+ * O(d) where d is tree depth. For real UI trees d rarely exceeds 5.
+ *
+ * Source: tasks.md Phase 4
+ */
+
+import { get } from './graph.js';
+
+/**
+ * @param {string} a - first container name.
+ * @param {string} b - second container name.
+ * @returns {import('./graph.js').Node|null} the lowest common ancestor, or null.
+ */
+export function lca(a, b) {
+  let na = get(a);
+  let nb = get(b);
+  if (!na || !nb) return null;
+
+  // Phase 1: equalize depth.
+  while (na.depth > nb.depth) na = na.parent;
+  while (nb.depth > na.depth) nb = nb.parent;
+
+  // Phase 2: walk up in tandem until the pointers meet.
+  while (na && nb && na !== nb) {
+    na = na.parent;
+    nb = nb.parent;
+  }
+
+  return na ?? null;
+}
+
+/**
+ * Ordered node path from the common ancestor down to `to`.
+ *
+ * @param {string} from - source container name.
+ * @param {string} to - target container name.
+ * @returns {import('./graph.js').Node[]|null} ancestor-first node chain, or null.
+ */
+export function path(from, to) {
+  const ancestor = lca(from, to);
+  if (!ancestor) return null;
+
+  const segments = [];
+  let current = get(to);
+  while (current && current !== ancestor) {
+    segments.unshift(current);
+    current = current.parent;
+  }
+  segments.unshift(ancestor);
+  return segments;
+}

package/src/core/router/match.js

@@ -9,6 +9,7 @@
 
 import { guard } from '../platform/index.js';
 import { resolveTag } from './handler.js';
+import { insert as trieInsert, find as trieFind, clear as trieClear } from './trie.js';
 
 const routes = [];
 // Resolve Pattern class at module load if available natively (RT-03)
@@ -42,12 +43,18 @@ function getSpecificity(patternStr) {
  * Registers a route mapping.
  */
 export function register(patternStr, handler, meta = {}) {
-  routes.push({
+  const route = {
     patternStr,
     handler,
     meta,
     pattern: null
-  });
+  };
+  routes.push(route);
+
+  // Index in the radix trie for O(k) matching. Patterns the trie cannot
+  // express (regex groups, modifiers, absolute URLs) stay on the URLPattern
+  // scan below — trieInsert returns false for those.
+  trieInsert(patternStr, route);
 
   // Sort routes by specificity (descending) and length (longer first) at registration time (RT-04)
   routes.sort((a, b) => {
@@ -66,6 +73,15 @@ export async function match(url) {
   const P = Pattern || (await getURLPattern());
   const targetUrl = new URL(url, globalThis.location?.href || 'http://localhost');
 
+  // Fast path: O(k) radix-trie lookup on the pathname. Covers the common case
+  // of plain/:param/* patterns without compiling or executing a URLPattern.
+  const trieHit = trieFind(targetUrl.pathname);
+  if (trieHit) {
+    return finalize(trieHit.route, trieHit.params, targetUrl, null);
+  }
+
+  // Fallback: URLPattern scan for patterns the trie cannot express
+  // (regex groups, modifiers, absolute-URL patterns).
   for (const route of routes) {
     if (!route.pattern) {
       if (route.patternStr.startsWith('http://') || route.patternStr.startsWith('https://')) {
@@ -77,51 +93,48 @@ export async function match(url) {
 
     const result = route.pattern.exec(targetUrl.href);
     if (result) {
-      // Resolve to a tag without ever invoking callback handlers (see handler.js).
-      const tag = await resolveTag(route.handler);
-
-      const query = Object.fromEntries(targetUrl.searchParams.entries());
-      const hash = targetUrl.hash;
-
-      const chain = [];
-      let currentRoute = route;
-      while (currentRoute) {
-        const currentTag = await resolveTag(currentRoute.handler);
-        chain.unshift({
-          route: currentRoute,
-          tag: currentTag,
-          params: result.pathname.groups || {}
-        });
-
-        const parentPattern = currentRoute.meta?.parent;
-        if (parentPattern) {
-          const parentRoute = routes.find(r => r.patternStr === parentPattern);
-          currentRoute = parentRoute;
-        } else {
-          currentRoute = null;
-        }
-      }
-
-      return {
-        route,
-        tag,
-        params: result.pathname.groups || {},
-        query,
-        hash,
-        chain,
-        result
-      };
+      return finalize(route, result.pathname.groups || {}, targetUrl, result);
     }
   }
 
   return null;
 }
 
+/**
+ * Builds the full match result (tag, query, hash, parent chain) for a matched
+ * route. The parent chain walk is cycle-guarded so a misconfigured
+ * A→B→A parent loop breaks instead of hanging (RT bug 8.3).
+ */
+async function finalize(route, params, targetUrl, result) {
+  const tag = await resolveTag(route.handler);
+  const query = Object.fromEntries(targetUrl.searchParams.entries());
+  const hash = targetUrl.hash;
+
+  const chain = [];
+  const visited = new Set();
+  let currentRoute = route;
+  while (currentRoute) {
+    if (visited.has(currentRoute.patternStr)) break; // cycle detected
+    visited.add(currentRoute.patternStr);
+
+    const currentTag = await resolveTag(currentRoute.handler);
+    chain.unshift({ route: currentRoute, tag: currentTag, params });
+
+    const parentPattern = currentRoute.meta?.parent;
+    currentRoute = parentPattern
+      ? routes.find(r => r.patternStr === parentPattern)
+      : null;
+  }
+
+  return { route, tag, params, query, hash, chain, result };
+}
+
 /**
  * Clears the route registry.
  */
 export function clear() {
   routes.length = 0;
+  trieClear();
 }
 
 /**