@adukiorg/anza 0.2.0

package/src/core/router/container.js

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ *
+ * Source: advance2.md
+ */
+
+// string -> WeakRef<HTMLElement>
+const containerNodeMap = new Map();
+
+// 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;
+const observedSelectors = new Set();
+
+/**
+ * Boots the MutationObserver at idle priority if standard selectors are tracked.
+ */
+function ensureObserver() {
+  if (observer || typeof window === 'undefined' || typeof requestIdleCallback === 'undefined') return;
+
+  requestIdleCallback(() => {
+    observer = new MutationObserver(() => {
+      let activeObservationNeeded = false;
+      for (const selector of observedSelectors) {
+        if (!containerNodeMap.get(selector)?.deref()) {
+          const el = document.querySelector(selector);
+          if (el) {
+            registerContainer(selector, el);
+          } else {
+            activeObservationNeeded = true;
+          }
+        }
+      }
+
+      // RT-06: Automatically disconnect MutationObserver if all observed selectors are resolved
+      if (!activeObservationNeeded && observer) {
+        observer.disconnect();
+        observer = null;
+      }
+    });
+
+    observer.observe(document.body, { childList: true, subtree: true });
+  });
+}
+
+/**
+ * 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.
+ */
+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);
+}
+
+/**
+ * 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).
+ */
+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) {}
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+export function getContainer(name) {
+  let el = containerNodeMap.get(name)?.deref();
+
+  // 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') {
+    try {
+      el = document.querySelector(name);
+      if (el) {
+        registerContainer(name, el);
+      } else {
+        if (!observedSelectors.has(name)) {
+          observedSelectors.add(name);
+        }
+        ensureObserver();
+      }
+    } catch (err) {
+      // Invalid selector string, ignore.
+    }
+  }
+
+  // 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);
+    if (queryResult) {
+      console.warn(
+        `[Router] Container name "${name}" is ambiguous: it exists in the DOM as a selector ` +
+        `but is being treated as a registry key. Use a selector prefix (e.g., "#${name}") ` +
+        `to explicitly target the DOM element, or ensure it is registered via registerContainer().`
+      );
+    }
+  }
+
+  return el;
+}
+
+/** Heuristic: does this string look like a CSS selector rather than a key? */
+function isSelector(name) {
+  return typeof name === 'string' && /^[#.\[]|[\s>+~]/.test(name);
+}
+
+/**
+ * Clears the entire container registry.
+ */
+export function clearContainers() {
+  containerNodeMap.clear();
+  observedSelectors.clear();
+  if (observer) {
+    observer.disconnect();
+    observer = null;
+  }
+}

package/src/core/router/handler.js

@@ -0,0 +1,52 @@
+/**
+ * src/core/router/handler.js
+ *
+ * One clear contract for what a route handler can be. This removes the previous
+ * ambiguity where `match()` invoked every function handler as a lazy tag factory
+ * while `intercept()` separately treated functions with arguments as callbacks —
+ * which could run a callback twice (once during matching, once on navigation).
+ *
+ * A handler is exactly one of:
+ *   - a string                  -> a custom element tag, e.g. 'page-home'
+ *   - a zero-arg function       -> a lazy tag factory, e.g. async () => 'page-home'
+ *   - a function (params, event)-> a callback (arity > 0)
+ *   - { tag: string }           -> a static tag
+ *   - { load: () => tag }       -> a lazy tag factory
+ *   - { handler: (params, ev) } -> a callback
+ */
+
+/** Does this handler render via a callback (rather than resolving to a tag)? */
+export function isCallback(handler) {
+  if (typeof handler === 'function') return handler.length > 0;
+  if (handler && typeof handler === 'object') return typeof handler.handler === 'function';
+  return false;
+}
+
+/**
+ * Resolve a handler to its element tag, or `null` when the handler is a callback.
+ * Never invokes callbacks (arity > 0 / `{ handler }`), so it is safe in `match()`.
+ */
+export async function resolveTag(handler) {
+  if (typeof handler === 'string') return handler;
+
+  if (typeof handler === 'function') {
+    return handler.length === 0 ? await handler() : null;
+  }
+
+  if (handler && typeof handler === 'object') {
+    if (typeof handler.tag === 'string') return handler.tag;
+    if (typeof handler.load === 'function') return await handler.load();
+  }
+
+  return null;
+}
+
+/** Run a callback handler. No-op for tag/lazy handlers. */
+export async function runCallback(handler, params, event) {
+  if (typeof handler === 'function' && handler.length > 0) {
+    return handler(params, event);
+  }
+  if (handler && typeof handler === 'object' && typeof handler.handler === 'function') {
+    return handler.handler(params, event);
+  }
+}

package/src/core/router/history.js

@@ -0,0 +1,120 @@
+/**
+ * src/core/router/history.js
+ *
+ * Programmatic history navigation wrapper.
+ * Provides a clean interface for page-level traversals mapping directly
+ * to the Navigation API (native or polyfilled).
+ *
+ * Source: doc 09 — Routing §2, §10, §12
+ */
+
+/** Normalized result shape for callers that await .finished. */
+const resolved = { committed: Promise.resolve(), finished: Promise.resolve() };
+
+/**
+ * Initiates a programmatic push navigation.
+ * Always returns { committed, finished } promises.
+ */
+export function navigate(url, options = {}) {
+  if (typeof window === 'undefined' || !window.navigation) return resolved;
+  const result = window.navigation.navigate(url, options);
+  return result ?? resolved;
+}
+
+/**
+ * Initiates a programmatic replace navigation (replaces current history entry).
+ */
+export function replace(url, options = {}) {
+  if (typeof window === 'undefined' || !window.navigation) return resolved;
+  const result = window.navigation.navigate(url, { history: 'replace', ...options });
+  return result ?? resolved;
+}
+
+/**
+ * Navigates back in history by one step.
+ */
+export function back() {
+  if (typeof window === 'undefined' || !window.navigation) return resolved;
+  return window.navigation.back() ?? resolved;
+}
+
+/**
+ * Navigates forward in history by one step.
+ */
+export function forward() {
+  if (typeof window === 'undefined' || !window.navigation) return resolved;
+  return window.navigation.forward() ?? resolved;
+}
+
+/**
+ * Traverses history by a numeric delta.
+ */
+export function go(delta) {
+  if (typeof window === 'undefined' || !window.navigation) return resolved;
+  return window.navigation.go(delta) ?? resolved;
+}
+
+/**
+ * Returns a list of all active history entries.
+ */
+export function entries() {
+  if (typeof window === 'undefined' || !window.navigation) return [];
+  return typeof window.navigation.entries === 'function' ? window.navigation.entries() : [];
+}
+
+/**
+ * Returns the current active history entry.
+ */
+export function current() {
+  if (typeof window === 'undefined' || !window.navigation) return null;
+  return window.navigation.currentEntry || null;
+}
+
+/**
+ * Checks if a backward navigation traversal is valid.
+ * Prefers native canGoBack property, falls back to entries inspection,
+ * and returns false (not true) when state is unknown.
+ */
+export function canBack() {
+  if (typeof window === 'undefined' || !window.navigation) return false;
+
+  // Use native canGoBack when available (Chrome 123+)
+  if (typeof window.navigation.canGoBack === 'boolean') {
+    return window.navigation.canGoBack;
+  }
+
+  if (typeof window.navigation.entries === 'function') {
+    const list = window.navigation.entries();
+    const active = window.navigation.currentEntry;
+    if (active && list.length > 0) {
+      return list.indexOf(active) > 0;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Checks if a forward navigation traversal is valid.
+ * Prefers native canGoForward property, falls back to entries inspection,
+ * and returns false (not true) when state is unknown.
+ */
+export function canForward() {
+  if (typeof window === 'undefined' || !window.navigation) return false;
+
+  // Use native canGoForward when available (Chrome 123+)
+  if (typeof window.navigation.canGoForward === 'boolean') {
+    return window.navigation.canGoForward;
+  }
+
+  if (typeof window.navigation.entries === 'function') {
+    const list = window.navigation.entries();
+    const active = window.navigation.currentEntry;
+    if (active && list.length > 0) {
+      const idx = list.indexOf(active);
+      return idx >= 0 && idx < list.length - 1;
+    }
+  }
+
+  return false;
+}

package/src/core/router/index.js

@@ -0,0 +1,158 @@
+/**
+ * src/core/router/index.js
+ *
+ * Public client-side routing entry point.
+ * Aggregates route definition registry, guards, programmatic traversals,
+ * and mounts global onnavigate interception listeners.
+ *
+ * Source: doc 09 — Routing §1, §2
+ */
+
+import { register, match, clear, getRoutes, load } from './match.js';
+import {
+  setup, destroy,
+  addGuard, setNotFound,
+  guardsApi, missApi,
+  on, nav, registerNavigator
+} from './intercept.js';
+import {
+  navigate,
+  replace,
+  back,
+  forward,
+  go,
+  current,
+  entries,
+  canBack,
+  canForward
+} from './history.js';
+
+import {
+  setupTabSync,
+  start as syncStart,
+  stop as syncStop,
+  active as syncActive,
+  close as syncClose,
+  registerConnection,
+  getActiveConnections,
+  clearConnections,
+  links
+} from './sync/index.js';
+
+import {
+  registerContainer,
+  unregisterContainer,
+  getContainer,
+  clearContainers
+} from './container.js';
+
+import { cache, prefetch } from './cache.js';
+
+import './outlet.js';
+
+export const router = {
+  // Registration and boundary hooks
+  register,
+  load,
+  clear,
+  guard: addGuard,
+  notFound: setNotFound,
+
+  // Grouped APIs
+  guards: guardsApi,
+  miss: missApi,
+  links,
+
+  // Sync controls
+  sync: {
+    start: (r) => syncStart(r ?? router),
+    stop: syncStop,
+    active: syncActive,
+    close: syncClose
+  },
+
+  // Programmatic history API
+  navigate,
+  replace,
+  back,
+  forward,
+  go,
+  current,
+  entries,
+  canBack,
+  canForward,
+
+  match,
+
+  // Cache API integration (route/view asset caching)
+  cache,
+  prefetch,
+
+  // Event-driven subscription and navigation controllers
+  on,
+  nav,
+
+  // Synchronization and coordination hooks
+  registerConnection,
+  getActiveConnections,
+  clearConnections,
+
+  // Advanced Container Topology API
+  registerContainer,
+  unregisterContainer,
+  getContainer,
+  clearContainers,
+
+  // Lifecycle
+  setup,
+  destroy
+};
+
+// Auto-bootstrap client-side navigation listeners on client load
+if (typeof window !== 'undefined') {
+  registerNavigator(navigate);
+  setup();
+  setupTabSync(router);
+}
+
+export {
+  navigate,
+  replace,
+  back,
+  forward,
+  go,
+  current,
+  entries,
+  canBack,
+  canForward,
+
+  // match sub-module
+  register,
+  load,
+  match,
+  clear,
+  getRoutes,
+  // intercept sub-module
+  addGuard,
+  setNotFound,
+  setup,
+  destroy,
+  on,
+  nav,
+  guardsApi,
+  missApi,
+  // sync sub-module
+  setupTabSync,
+  registerConnection,
+  getActiveConnections,
+  clearConnections,
+  links,
+  // container sub-module
+  registerContainer,
+  unregisterContainer,
+  getContainer,
+  clearContainers,
+  // cache sub-module
+  cache,
+  prefetch
+};