@adukiorg/anza 0.4.1 → 0.4.3

package/src/core/router/intercept.js

@@ -8,16 +8,321 @@
  * Source: doc 09 — Routing §2, §5, §9, §13
  */
 
-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 { isCallback, runCallback } from './handler.js';
+
 import { ensure } from './cascade.js';
+import { getContainer } from './container.js';
+import { get as graphGet } from './graph.js';
+import { match } from './match.js';
+import { specRegistry } from '../ui/define/state.js';
+
+/**
+ * Built-in minimal 404 HTML rendered when no user notfound is configured.
+ * Kept intentionally plain so it inherits the app's base typography.
+ */
+const DEFAULT_NOTFOUND_HTML = `
+  <div style="
+    display:flex;flex-direction:column;align-items:center;justify-content:center;
+    min-height:60vh;gap:1rem;padding:2rem;text-align:center;font-family:inherit;
+  ">
+    <span style="font-size:3rem;font-weight:800;opacity:.15;">404</span>
+    <p style="margin:0;font-size:1rem;opacity:.5;">Page not found</p>
+    <a href="/" style="font-size:.875rem;opacity:.6;text-decoration:none;">← Go home</a>
+  </div>
+`;
+
+/**
+ * Wraps a plain array with non-enumerable `first`, `last`, and named
+ * index getters. Mirrors spec.js makeAccessorArray for use in the router.
+ *
+ * @param {any[]} values
+ * @param {string[]} names
+ */
+function makeAccessorArray(values, names) {
+  const arr = [...values];
+  Object.defineProperties(arr, {
+    first: { get() { return arr[0] ?? null; }, enumerable: false },
+    last:  { get() { return arr[arr.length - 1] ?? null; }, enumerable: false },
+  });
+  names.forEach((name, i) => {
+    if (!(name in arr)) {
+      Object.defineProperty(arr, name, {
+        get() { return arr[i] ?? null; },
+        enumerable: false,
+      });
+    }
+  });
+  return arr;
+}
+
+/**
+ * Casts a URL string value to the declared type.
+ * @param {string} value
+ * @param {'string'|'number'} cast
+ */
+function castValue(value, cast) {
+  if (cast === 'number') {
+    const n = Number(value);
+    return Number.isNaN(n) ? value : n;
+  }
+  return value;
+}
+
+/**
+ * Builds the typed params and query context arrays for a matched route.
+ *
+ * Reads the component's declared `params`/`query` contract from specRegistry.
+ * Falls back to the raw match params/query objects for undeclared segments.
+ *
+ * @param {string} tag - custom element tag
+ * @param {object} rawParams - raw segment map from trie/URLPattern match
+ * @param {URL|string} url - the matched URL (or string)
+ * @returns {{ params: any[], query: any[], raw: URLSearchParams }}
+ */
+function buildRouteContext(tag, rawParams, url) {
+  const spec = specRegistry.get(tag);
+  const paramDecls = spec?.params ?? [];
+  const queryDecls = spec?.query ?? [];
+
+  // Build the URLSearchParams object from the URL.
+  let searchParams;
+  try {
+    const u = url instanceof URL ? url : new URL(url, globalThis.location?.href || 'http://localhost');
+    searchParams = u.searchParams;
+  } catch (_) {
+    searchParams = new URLSearchParams();
+  }
+
+  // Build params array from declarations in order, casting as needed.
+  // Undeclared segments that appear in rawParams are appended at the end.
+  let params;
+  if (paramDecls.length > 0) {
+    const declared = new Set(paramDecls.map(d => d.name));
+    const declaredValues = paramDecls.map(({ name, cast }) => {
+      const raw = rawParams[name];
+      return raw !== undefined ? castValue(raw, cast) : null;
+    });
+    // Append undeclared segments as strings so they remain accessible by index.
+    const extra = Object.entries(rawParams)
+      .filter(([k]) => !declared.has(k))
+      .map(([, v]) => v);
+    const allValues = [...declaredValues, ...extra];
+    const allNames = [...paramDecls.map(d => d.name)];
+    params = makeAccessorArray(allValues, allNames);
+  } else {
+    // No contract declared: expose raw params as an ordered array (string values).
+    const entries = Object.entries(rawParams ?? {});
+    params = makeAccessorArray(entries.map(([, v]) => v), entries.map(([k]) => k));
+  }
+
+  // Build query array from declarations in order, casting as needed.
+  let query;
+  if (queryDecls.length > 0) {
+    const declared = new Set(queryDecls.map(d => d.name));
+    const declaredValues = queryDecls.map(({ name, cast }) => {
+      const raw = searchParams.get(name);
+      return raw !== null ? castValue(raw, cast) : null;
+    });
+    // Extra undeclared query keys appended as strings.
+    const extra = [];
+    for (const [k, v] of searchParams.entries()) {
+      if (!declared.has(k)) extra.push(v);
+    }
+    const allValues = [...declaredValues, ...extra];
+    const allNames = [...queryDecls.map(d => d.name)];
+    query = makeAccessorArray(allValues, allNames);
+  } else {
+    // No contract: flat array of all query values in iteration order.
+    const entries = [...searchParams.entries()];
+    query = makeAccessorArray(entries.map(([, v]) => v), entries.map(([k]) => k));
+  }
+
+  return { params, query, raw: searchParams };
+}
+
+/**
+ * Pushes params and query values reactively onto a live element instance
+ * without re-instantiating it. Used for layout-invariant param-only navigations.
+ *
+ * @param {HTMLElement} el - the live element
+ * @param {string} tag - for looking up the contract in specRegistry
+ * @param {object} rawParams - raw segment map
+ * @param {URL|string} url - the target URL
+ */
+function pushToElement(el, tag, rawParams, url) {
+  const spec = specRegistry.get(tag);
+  const paramDecls = spec?.params ?? [];
+  const queryDecls = spec?.query ?? [];
+
+  let searchParams;
+  try {
+    const u = url instanceof URL ? url : new URL(url, globalThis.location?.href || 'http://localhost');
+    searchParams = u.searchParams;
+  } catch (_) {
+    searchParams = new URLSearchParams();
+  }
+
+  // Push path params.
+  for (const { name, cast } of paramDecls) {
+    const raw = rawParams[name];
+    if (raw !== undefined) el[name] = castValue(raw, cast);
+  }
+  // Push any undeclared params as strings.
+  const declaredNames = new Set(paramDecls.map(d => d.name));
+  for (const [k, v] of Object.entries(rawParams ?? {})) {
+    if (!declaredNames.has(k)) el[k] = v;
+  }
+
+  // Push query params.
+  for (const { name, cast } of queryDecls) {
+    const raw = searchParams.get(name);
+    if (raw !== null) el[name] = castValue(raw, cast);
+  }
+}
+
+/**
+ * Async navigation pipeline — extracted from handler to prevent browser spinner.
+ * Runs fire-and-forget via queueMicrotask so the Navigation API handler resolves
+ * immediately, eliminating the loading indicator during async work.
+ *
+ * @param {NavigationEvent} event - The navigation event
+ * @param {boolean} precommitted - Whether precommitHandler ran (guards already checked)
+ */
+async function pipe(event, precommitted) {
+  const destination = event.destination;
+  let routeMatch = null;
+  try {
+    routeMatch = await match(destination.url);
+  } catch (err) {
+    emit('error', { error: err, url: destination.url, route: null, phase: 'match' });
+    return;
+  }
+
+  if (routeMatch) {
+    for (const fn of transformers) {
+      try { fn(routeMatch); } catch (e) { console.error(e); }
+    }
+  }
+
+  let chain = [];
+  if (routeMatch) {
+    const meta = routeMatch.route?.meta ?? {};
+    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] ?? 'main');
+        }
+      }
+    } catch (err) {
+      emit('error', { error: err, url: destination.url, route: routeMatch.route, phase: 'container' });
+      throw err;
+    }
+  }
+
+  if (!precommitted) {
+    for (const guardFn of guards) {
+      let redirectUrl;
+      try {
+        redirectUrl = await guardFn(destination, null);
+      } catch (err) {
+        emit('error', { error: err, url: destination.url, route: routeMatch?.route ?? null, phase: 'guard' });
+        return;
+      }
+      if (redirectUrl) {
+        window.navigation.navigate(redirectUrl, { history: 'replace' });
+        return;
+      }
+    }
+  }
+
+  if (routeMatch) {
+    if (isCallback(routeMatch.route.handler)) {
+      try {
+        await runCallback(routeMatch.route.handler, routeMatch.params, event);
+      } catch (err) {
+        emit('error', { error: err, url: destination.url, route: routeMatch.route, phase: 'handler' });
+        return;
+      }
+    }
+
+    const ctx = buildRouteContext(routeMatch.tag, routeMatch.params, destination.url);
+    emit('found', {
+      tag: routeMatch.tag,
+      params: ctx.params,
+      query: ctx.query,
+      raw: ctx.raw,
+      hash: routeMatch.hash,
+      chain: routeMatch.chain,
+      via: chain,
+      container: chain.at(-1) ?? null,
+      url: destination.url,
+      direction: event.navigationType
+    });
+  } else {
+    emit('notfound', { url: destination.url });
+    if (notFoundHandler) {
+      await notFoundHandler(event);
+    } else {
+      renderNotFound('main');
+    }
+  }
+}
+
+/**
+ * Renders the not-found fallback into the deepest currently-live container.
+ * Walks the graph from the deepest live node upward until it finds a mounted
+ * dock element, then swaps a notfound div into it.
+ *
+ * Each dock may expose a static `notfound` property (set by dock() when the
+ * user supplies a notfound config). The deepest configured one wins.
+ *
+ * @param {string} [activeContainer='main'] - hint: the last-active container.
+ */
+function renderNotFound(activeContainer = 'main') {
+  // Walk from the hinted container upward until we find a live element.
+  let name = activeContainer;
+  let host = null;
+  const visited = new Set();
+  while (name && !visited.has(name)) {
+    visited.add(name);
+    const el = getContainer(name);
+    if (el && el.isConnected) { host = el; break; }
+    const node = graphGet(name);
+    name = node?.parent?.name ?? null;
+  }
+  if (!host) {
+    // Last resort: use the root main element directly.
+    host = document.getElementById('main');
+  }
+  if (!host) return;
+
+  // Build the notfound element. Check for a user-defined template on the
+  // host element's class (set by dock() via the notfound config option).
+  const Cls = host.constructor;
+  const userHtml = Cls?.notfound ?? null;
+  const html = typeof userHtml === 'string' ? userHtml : DEFAULT_NOTFOUND_HTML;
+
+  const wrapper = document.createElement('div');
+  wrapper.setAttribute('role', 'status');
+  wrapper.setAttribute('aria-label', 'Page not found');
+  wrapper.innerHTML = html;
+
+  if (typeof host.swap === 'function') {
+    host.swap(wrapper);
+  } else {
+    host.replaceChildren(wrapper);
+  }
+}
 
 let guards = [];
 let notFoundHandler = null;
 let ready = false;
+let transformers = [];
 
 // Module-level root slots — captured once in setup(), cleared in destroy().
 let win   = null;
@@ -89,6 +394,17 @@ export function addGuard(guardFn) {
   };
 }
 
+/**
+ * Registers a global route transformer. Transformers can modify matched route metadata dynamically.
+ */
+export function addTransformer(fn) {
+  transformers.push(fn);
+  return () => {
+    const idx = transformers.indexOf(fn);
+    if (idx !== -1) transformers.splice(idx, 1);
+  };
+}
+
 /** Grouped guard API. */
 export const guardsApi = {
   add: addGuard,
@@ -128,20 +444,44 @@ export function setup() {
   // throws if the element is absent at boot time.
   if (mainEl) shell = new WeakRef(mainEl);
   navListener = (event) => {
-    // Skip cross-origin navigations, file downloads, or same-document hash scrolls
+    // Only intercept same-origin navigations that the browser would otherwise
+    // follow as a full page load. External links, file downloads, and
+    // same-document hash scrolls are intentionally left to the browser.
     if (!event.canIntercept || event.hashChange || event.downloadRequest) {
       return;
     }
+    // Guard: only intercept same-origin URLs. Cross-origin clicks must
+    // navigate normally (open in browser / new tab).
+    try {
+      const dest = new URL(event.destination.url);
+      if (dest.origin !== location.origin) return;
+    } catch (_) { return; }
 
     const url = event.destination.url;
     let precommitted = false; // Scoped precommitted guard state (RT-02)
 
-    event.intercept({
+    // Build intercept options. precommitHandler is only valid on cancelable
+    // events (Navigation API spec §4.3). Including it unconditionally throws
+    // InvalidStateError on non-cancelable navigations (e.g. back/forward).
+    const interceptOpts = {
+      focusReset: 'manual',   // router owns focus — browser must not reset it
+      scroll: 'manual',       // router owns scroll — browser must not reset it
       /**
-       * Runs guards before URL changes.
-       * Supports atomic redirection before URL commit (Chrome & Firefox).
+       * Executes DOM mutations, layout changes, and provides fallbacks for Safari.
+       * Always provided — this is what prevents the browser from reloading.
        */
-      async precommitHandler(controller) {
+      handler() {
+        // Resolve immediately — no browser spinner, no focus/scroll side effects.
+        // pipe() runs detached; the router's own emit() system handles success/error.
+        queueMicrotask(() => pipe(event, precommitted));
+      }
+    };
+
+    // Only attach precommitHandler on cancelable events (Navigation API §4.3).
+    // Non-cancelable navigations (e.g. browser back/forward in some browsers)
+    // throw InvalidStateError if precommitHandler is present.
+    if (event.cancelable) {
+      interceptOpts.precommitHandler = async function precommitHandler(controller) {
         precommitted = true;
         const destination = event.destination;
         for (const guardFn of guards) {
@@ -151,96 +491,10 @@ export function setup() {
             return;
           }
         }
-      },
-
-      /**
-       * Executes DOM mutations, layout changes, and provides fallbacks for Safari.
-       */
-      handler() {
-        (async () => {
-          const destination = event.destination;
-          let routeMatch = null;
-          try {
-            routeMatch = await match(destination.url);
-          } catch (err) {
-            emit('error', { error: err, url: destination.url, route: null, phase: 'match' });
-            return;
-          }
-
-        // 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] ?? 'main');   // was 'body'
-              }
-            }
-          } catch (err) {
-            emit('error', { error: err, url: destination.url, route: routeMatch.route, phase: 'container' });
-            throw err;
-          }
-        }
-
-        // Graceful Safari Fallback: Evaluate guards inside post-commit handler if precommit is ignored.
-        if (!precommitted) {
-          for (const guardFn of guards) {
-            let redirectUrl;
-            try {
-              redirectUrl = await guardFn(destination, null);
-            } catch (err) {
-              emit('error', { error: err, url: destination.url, route: routeMatch?.route ?? null, phase: 'guard' });
-              return;
-            }
-            if (redirectUrl) {
-              window.navigation.navigate(redirectUrl, { history: 'replace' });
-              return;
-            }
-          }
-        }
+      };
+    }
 
-        await transitions.run(async () => {
-          if (routeMatch) {
-            // Run callback handlers exactly once, here (never during match()).
-            if (isCallback(routeMatch.route.handler)) {
-              try {
-                await runCallback(routeMatch.route.handler, routeMatch.params, event);
-              } catch (err) {
-                emit('error', { error: err, url: destination.url, route: routeMatch.route, phase: 'handler' });
-                return;
-              }
-            }
-
-            emit('found', {
-              tag: routeMatch.tag,
-              params: routeMatch.params,
-              query: routeMatch.query,
-              hash: routeMatch.hash,
-              chain: routeMatch.chain,
-              url: destination.url,
-              direction: event.navigationType
-            });
-          } else {
-            emit('notfound', { url: destination.url });
-
-            if (notFoundHandler) {
-              await notFoundHandler(event);
-            } else {
-              console.error(`Route matching failed and no not-found boundary handler was configured: ${destination.url}`);
-            }
-          }
-        });
-        })();
-      }
-    });
+    event.intercept(interceptOpts);
   };
 
   successListener = () => {
@@ -286,17 +540,59 @@ export function setup() {
     const url = window.navigation.currentEntry?.url || window.location.href;
     const routeMatch = await match(url);
     if (routeMatch) {
+      for (const fn of transformers) {
+        try { fn(routeMatch); } catch (e) { console.error(e); }
+      }
+      const meta = routeMatch.route?.meta ?? {};
+      const chain = Array.isArray(meta.via) && meta.via.length
+        ? meta.via
+        : (meta.container ? [meta.container] : []);
+
+      // Layout resolution: ensure the route's container chain is mounted on boot.
+      // Retry once after a frame — a dock element may still be connecting on
+      // the first attempt (especially on hard refresh when layout docks are
+      // mounting concurrently with the boot gate settling).
+      const mountChain = async () => {
+        for (let i = 0; i < chain.length; i++) {
+          if (!getContainer(chain[i])) {
+            await ensure(chain[i], chain[i - 1] ?? 'main');
+          }
+        }
+      };
+      try {
+        await mountChain();
+      } catch (err) {
+        // Yield one animation frame and retry before giving up.
+        await new Promise(r => {
+          if (typeof requestAnimationFrame !== 'undefined') requestAnimationFrame(r);
+          else setTimeout(r, 16);
+        });
+        try {
+          await mountChain();
+        } catch (retryErr) {
+          // Both attempts failed — emit error but do NOT throw so the router
+          // can still attempt a notfound render rather than leaving a blank page.
+          emit('error', { error: retryErr, url, route: routeMatch.route, phase: 'container' });
+          return;
+        }
+      }
+
+      const ctx = buildRouteContext(routeMatch.tag, routeMatch.params, url);
       emit('found', {
         tag: routeMatch.tag,
-        params: routeMatch.params,
-        query: routeMatch.query,
+        params: ctx.params,
+        query: ctx.query,
+        raw: ctx.raw,
         hash: routeMatch.hash,
         chain: routeMatch.chain,
+        via: chain,
+        container: chain.at(-1) ?? null,
         url,
         direction: 'load'
       });
     } else {
       emit('notfound', { url });
+      renderNotFound('main');
     }
   });
 }
@@ -321,6 +617,7 @@ export function destroy() {
   errorListener = null;
 
   guards = [];
+  transformers = [];
   notFoundHandler = null;
   resetBoot();
 

package/src/core/router/match.js

@@ -39,10 +39,40 @@ function getSpecificity(patternStr) {
   return 1;                                // Wildcard: low
 }
 
+function conflict(pathA, pathB) {
+  if (pathA === pathB) return false;
+  const segsA = pathA.split('/').filter(s => s.length > 0);
+  const segsB = pathB.split('/').filter(s => s.length > 0);
+
+  if (segsA.length !== segsB.length) return false;
+
+  for (let i = 0; i < segsA.length; i++) {
+    const sa = segsA[i];
+    const sb = segsB[i];
+    const isDynA = sa.startsWith(':') || sa === '*' || sa.includes('*');
+    const isDynB = sb.startsWith(':') || sb === '*' || sb.includes('*');
+
+    if (!isDynA && !isDynB && sa !== sb) {
+      return false; // static mismatch
+    }
+  }
+
+  return true;
+}
+
 /**
  * Registers a route mapping.
  */
 export function register(patternStr, handler, meta = {}) {
+  // Check conflicts with existing routes before registering
+  for (const r of routes) {
+    if (conflict(patternStr, r.patternStr)) {
+      console.warn(
+        `[anza] WARNING: Route pattern conflict: "${patternStr}" overlaps with "${r.patternStr}"`
+      );
+    }
+  }
+
   const route = {
     patternStr,
     handler,

package/src/core/router/transitions.js

@@ -21,12 +21,13 @@ function injectSheet() {
   try {
     const sheet = new CSSStyleSheet();
     sheet.replaceSync(`
-      ::view-transition-group(root) {
+      /* Dock-swap group: element-scoped content transitions */
+      ::view-transition-group(dock-swap) {
         animation-duration: var(--transition-duration);
         animation-timing-function: var(--transition-easing);
       }
-      ::view-transition-old(root),
-      ::view-transition-new(root) {
+      ::view-transition-old(dock-swap),
+      ::view-transition-new(dock-swap) {
         animation-duration: var(--transition-duration);
         animation-timing-function: var(--transition-easing);
         background: var(--transition-bg);

package/src/core/ui/define/container.js

@@ -53,7 +53,9 @@ export function container(tag, spec, base = import.meta.url) {
         delete this.dataset.transitionDirection;
       };
 
-      // Strategy 1: Element-scoped transition (Chrome 147+, concurrent-safe)
+      // Only use element-scoped view transitions. Document-level
+      // startViewTransition() captures the entire page and causes
+      // chrome flicker — never use it as a fallback.
       if (typeof this.startViewTransition === 'function') {
         try {
           const vt = this.startViewTransition(doSwap);
@@ -64,18 +66,6 @@ export function container(tag, spec, base = import.meta.url) {
         return;
       }
 
-      // Strategy 2: Document-scoped transition (Baseline Oct 2025)
-      if (typeof document.startViewTransition === 'function') {
-        try {
-          const vt = document.startViewTransition(doSwap);
-          await vt.ready;
-        } catch (err) {
-          if (err?.name !== 'AbortError') console.warn('[UI Container] Document VT aborted:', err);
-        }
-        return;
-      }
-
-      // Strategy 3: Synchronous direct swap
       doSwap();
     };
   }