@adukiorg/anza 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adukiorg/anza",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Anza web platform library — reactive state, networking, offline, animations, custom elements. Instant build step. Pure browser ESM.",
   "author": "fescii",
   "license": "MIT",

package/src/core/api/index.js

@@ -20,7 +20,7 @@ import { cache as apiCache } from './caches/index.js';
 
 let cache = null;
 
-export function sync() {
+function sync() {
   if (typeof document === 'undefined') return;
   const el = document.getElementById('anza-state');
   if (el) {
@@ -156,7 +156,7 @@ async function request(url, method, body, opts = {}) {
 
 export const api = {
   get:    (url, opts) => request(url, 'GET', null, opts),
-  state:  () => cache ? JSON.parse(JSON.stringify(cache.__route || {})) : null,
+  state:  () => cache ? JSON.parse(JSON.stringify(cache.__route || {})) : {},
   sync,
   post:   (url, body, opts) => request(url, 'POST', body, opts),
   put:    (url, body, opts) => request(url, 'PUT', body, opts),

package/src/core/offline/sync.js

@@ -15,7 +15,7 @@ export class SyncManager {
   constructor() {
     if (
       typeof navigator !== 'undefined' &&
-      'serviceWorker' in navigator
+      navigator.serviceWorker
     ) {
       navigator.serviceWorker.addEventListener('message', async (event) => {
         const data = event.data;
@@ -38,7 +38,7 @@ export class SyncManager {
   async register(tag) {
     if (
       typeof navigator !== 'undefined' &&
-      'serviceWorker' in navigator
+      navigator.serviceWorker
     ) {
       try {
         const registration = await navigator.serviceWorker.ready;

package/src/core/router/cascade.js

@@ -32,7 +32,16 @@ export async function ensure(target, current = 'main') {
   if (live) return live;
 
   const segments = path(current, target);
-  if (!segments) throw new Error(`CascadeError: no path '${current}' → '${target}'`);
+  if (!segments) {
+    // The container graph has no registered path from `current` to `target`.
+    // This almost always means a dock() declaration is missing or was imported
+    // after the page() that lists it in `via`.
+    throw new Error(
+      `[Router] CascadeError: cannot mount '${target}' — no graph path from '${current}'.\n` +
+      `Ensure dock('${target}', { parent: '${current}' }) is called and its file is imported\n` +
+      `before any page() that lists '${target}' in its via chain.`
+    );
+  }
 
   // Find the deepest node on the path that is currently connected.
   let mounted = null;
@@ -47,26 +56,22 @@ export async function ensure(target, current = 'main') {
   const start = segments.indexOf(mounted) + 1;
   for (let i = start; i < segments.length; i++) {
     const node = segments[i];
+    if (resolve(node.name)) continue;
     const parentEl = node.parent?.ref?.deref() ?? null;
-    if (!parentEl || !parentEl.isConnected) {
-      throw new Error(`CascadeError: parent '${node.parent?.name}' is disconnected while mounting '${node.name}'`);
-    }
-
-    const tag = node.name;
-    if (tag.includes('-') && typeof customElements !== 'undefined' && !customElements.get(tag)) {
-      await customElements.whenDefined(tag);
-    }
-
+    if (!parentEl || !parentEl.isConnected) throw new Error(`CascadeError: parent '${node.parent?.name}' is disconnected while mounting '${node.name}'`);
+    const tag = node.tag;
+    if (tag.includes('-') && typeof customElements !== 'undefined' && !customElements.get(tag)) await customElements.whenDefined(tag);
     const el = document.createElement(tag);
-    if (typeof parentEl.swap === 'function') {
-      await parentEl.swap(el, { direction: 'push' });
-    } else {
-      parentEl.replaceChildren(el);
-    }
-
-    // Yield so connectedCallback fires and the dock self-registers in the graph.
-    await frame();
+    parentEl.replaceChildren(el);
 
+    // Wait for the element's connectedCallback to complete, including any
+    // async resource loading (template/style fetches). A single frame is
+    // not sufficient when preloadResources() hits the network.
+    let attempts = 0;
+    while (!resolve(node.name) && attempts < 50) {
+      await frame();
+      attempts++;
+    }
     if (!resolve(node.name)) {
       throw new Error(`CascadeError: container '${node.name}' failed to register after mount`);
     }

package/src/core/router/container.js

@@ -62,8 +62,8 @@ function ensureObserver() {
  * @param {string|null} [parent='main'] - parent container key in the graph.
  *   Pass null explicitly when registering the root (no parent).
  */
-export function registerContainer(name, element, parent = 'main') {
-  add(name, element, parent);
+export function registerContainer(name, element, parent = 'main', tag = null) {
+  add(name, element, parent, tag);
 }
 
 /**
@@ -76,6 +76,10 @@ export function unregisterContainer(name, element) {
   remove(name, element);
 }
 
+export function hasContainer(name) {
+  return get(name) !== null;
+}
+
 /**
  * Retrieves an active layout container by name.
  *

package/src/core/router/graph.js

@@ -14,8 +14,9 @@
  */
 
 class Node {
-  constructor(name, ref, parent) {
+  constructor(name, tag, ref, parent) {
     this.name = name;            // registry key, e.g. 'main' | 'sidebar'
+    this.tag = tag;              // custom element tag, e.g. 'dock-docs' | 'main'
     this.ref = ref;              // WeakRef<Element> | null (null for virtual root)
     this.parent = parent;        // Node | null
     this.children = new Set();   // Set<Node>
@@ -33,7 +34,7 @@ const nodes = new Map();
 // The permanent root node. ref is null at module-evaluation time because
 // modules may be evaluated before the parser reaches <main id="main">.
 // boot.js fills in the WeakRef during anchor().
-const root = new Node('main', null, null);
+const root = new Node('main', 'main', null, null);
 root.depth = 0;
 nodes.set('main', root);
 
@@ -41,15 +42,23 @@ nodes.set('main', root);
 // 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.
+// Prune stale nodes after their element is collected by GC.
+// This is the ONLY place a node is structurally removed from the graph.
+// Normal DOM disconnects (remove()) only null the ref — they preserve topology.
 const finalizer = typeof FinalizationRegistry !== 'undefined'
   ? new FinalizationRegistry((name) => {
       const node = nodes.get(name);
+      // Only detach if the node still has no live element (i.e. truly GC'd,
+      // not just remounted under a new element instance).
       if (node && !node.alive()) detach(name);
     })
   : { register() {}, unregister() {} };
 
-/** Removes a node from the tree, reparenting its children to its parent. */
+/**
+ * Structurally removes a node from the tree, reparenting its children to its
+ * parent. Called ONLY from the FinalizationRegistry (GC path). DOM disconnects
+ * must NOT call this — they use remove() which only nulls the ref.
+ */
 function detach(name) {
   const node = nodes.get(name);
   if (!node || node === root) return;
@@ -68,9 +77,10 @@ function detach(name) {
  * @param {string} name - unique registry key.
  * @param {Element} el - the container element.
  * @param {string} [parent='main'] - parent registry key.
+ * @param {string} [tag] - custom element tag; defaults to name.
  * @returns {Node} the inserted node.
  */
-export function add(name, el, parent = 'main') {
+export function add(name, el, parent = 'main', tag = null) {
   gone.delete(name);
 
   const existing = nodes.get(name);
@@ -78,45 +88,66 @@ export function add(name, el, parent = 'main') {
     if (existing === root) {
       // Root re-registration from anchor(): refresh the WeakRef and return.
       // The root cannot be reparented and must not spawn a duplicate node.
-      existing.ref = new WeakRef(el);
+      if (el) existing.ref = new WeakRef(el);
       return existing;
     }
     const prev = existing.ref?.deref();
-    if (prev && prev !== el) {
+    if (prev && el && 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);
+    // Re-registering after a disconnect (ref was null) or HMR: refresh the ref.
+    // Also re-register with the finalizer so the new element instance is tracked.
+    if (el) {
+      existing.ref = new WeakRef(el);
+      finalizer.register(el, name);
+    }
     return existing;
   }
 
   const parentNode = nodes.get(parent) ?? root;
-  const node = new Node(name, new WeakRef(el), parentNode);
+  const resolvedTag = tag || name;
+  const node = new Node(name, resolvedTag, el ? new WeakRef(el) : null, parentNode);
   parentNode.children.add(node);
   nodes.set(name, node);
-  finalizer.register(el, name);
+  if (el) 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.
+ * Unregisters the live element of a container node when the element disconnects
+ * from the DOM. The node itself stays in `nodes` to preserve graph topology for
+ * future ensure()/lca() calls — only its element ref is cleared.
+ *
+ * The name is marked `gone` for one macrotask so any lookup that races the
+ * disconnect (e.g. an in-flight navigation reading the old element) gets
+ * `undefined` rather than the stale ref.
+ *
+ * Structural removal (nodes.delete) is deferred to the FinalizationRegistry so
+ * it only happens after the element is truly GC'd and cannot be remounted.
  *
  * @param {string} name - registry key.
- * @param {Element} [el] - element guard; if given, only removes when it matches.
+ * @param {Element} [el] - element guard; if given, only clears when it matches.
  */
 export function remove(name, el) {
   const node = nodes.get(name);
   if (!node || node === root) return;
 
   const current = node.ref?.deref();
+  // Guard: if a specific element is given and it doesn't match the registered
+  // one, this is a stale disconnect from a previous instance — ignore.
   if (el && current && current !== el) return;
 
+  // Unregister from the finalizer (we're clearing the ref manually).
   if (current) {
     try { finalizer.unregister(current); } catch (_) {}
   }
-  detach(name);
 
+  // Clear the element ref but KEEP the node in the graph.
+  // This preserves topology: lca() and path() can still traverse the tree
+  // on the next navigation that needs to remount this container.
+  node.ref = null;
+
+  // Mark as transiently gone for one macrotask.
   gone.add(name);
   if (typeof setTimeout !== 'undefined') {
     setTimeout(() => gone.delete(name), 0);

package/src/core/router/index.js

@@ -12,6 +12,7 @@ import { register, match, clear, getRoutes, load } from './match.js';
 import {
   setup, destroy,
   addGuard, setNotFound,
+  addTransformer,
   guardsApi, missApi,
   on, nav, registerNavigator,
   getShell, getWin
@@ -44,7 +45,8 @@ import {
   registerContainer,
   unregisterContainer,
   getContainer,
-  clearContainers
+  clearContainers,
+  hasContainer
 } from './container.js';
 
 import { cache, prefetch } from './cache.js';
@@ -56,6 +58,7 @@ export const router = {
   clear,
   guard: addGuard,
   notFound: setNotFound,
+  transform: addTransformer,
 
   // Grouped APIs
   guards: guardsApi,
@@ -101,6 +104,7 @@ export const router = {
   unregisterContainer,
   getContainer,
   clearContainers,
+  hasContainer,
 
   // Lifecycle
   setup,
@@ -151,6 +155,7 @@ export {
   // intercept sub-module
   addGuard,
   setNotFound,
+  addTransformer as transform,
   setup,
   destroy,
   on,
@@ -168,6 +173,7 @@ export {
   unregisterContainer,
   getContainer,
   clearContainers,
+  hasContainer,
   // cache sub-module
   cache,
   prefetch