@zenithbuild/router 0.7.3 → 0.7.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zenith Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,4 @@
-# @zenith/router
+# @zenithbuild/router
 
 > Internal Zenith package. The generated router runtime is the authoritative surface here, not a general SPA framework API.
 
@@ -18,3 +18,4 @@
 - Redirects, denies, unmatched routes, non-HTML responses, and runtime failures fall back to browser navigation.
 - Client routing mirrors server route precedence and pathname-based identity.
 - Phase 2 adds awaited lifecycle barriers at `navigation:before-leave`, `navigation:before-swap`, and `navigation:before-enter`.
+- `zenNavigationShell(...)` is the narrow canonical Phase 3 utility for projecting visual shell phase on top of that lifecycle without changing route truth.

package/dist/history.js

@@ -1,12 +1,17 @@
 // ---------------------------------------------------------------------------
 // history.js — Zenith Router V0
 // ---------------------------------------------------------------------------
-// Minimal navigation helpers without History API mutation.
+// Minimal source-router path helpers.
 //
-// - push(path)     → hard navigation (assign)
-// - replace(path)  → hard navigation (replace)
+// The template-generated router owns real History API writes.
+// This source helper keeps a narrow in-memory path override for
+// source-level tests and simple router assembly without leaking
+// soft-nav history writes into the shipped runtime contract.
+//
+// - push(path)     → update source-router current path
+// - replace(path)  → update source-router current path
 // - listen(cb)     → popstate listener, returns unlisten
-// - current()      → location.pathname
+// - current()      → source-router path or current location.pathname
 //
 // No hash routing. No scroll restoration. No batching.
 // ---------------------------------------------------------------------------
@@ -14,11 +19,26 @@
 const _listeners = new Set();
 /** @type {boolean} */
 let _listening = false;
+/** @type {string | null} */
+let _currentPathOverride = null;
+/** @type {string | null} */
+let _lastObservedWindowPath = null;
+function _readWindowPath() {
+    return window.location.pathname;
+}
+function _syncWindowPath() {
+    const windowPath = _readWindowPath();
+    if (_lastObservedWindowPath !== windowPath) {
+        _lastObservedWindowPath = windowPath;
+        _currentPathOverride = null;
+    }
+    return windowPath;
+}
 /**
  * Internal popstate handler — fires all registered listeners.
  */
 function _onPopState() {
-    const path = current();
+    const path = _syncWindowPath();
     for (const cb of _listeners) {
         cb(path);
     }
@@ -38,7 +58,8 @@ function _ensureListening() {
  * @param {string} path
  */
 export function push(path) {
-    window.location.assign(path);
+    _lastObservedWindowPath = _readWindowPath();
+    _currentPathOverride = path;
 }
 /**
  * Replace the current path in browser history.
@@ -46,7 +67,8 @@ export function push(path) {
  * @param {string} path
  */
 export function replace(path) {
-    window.location.replace(path);
+    _lastObservedWindowPath = _readWindowPath();
+    _currentPathOverride = path;
 }
 /**
  * Subscribe to popstate (back/forward) events.
@@ -72,5 +94,6 @@ export function listen(callback) {
  * @returns {string}
  */
 export function current() {
-    return window.location.pathname;
+    const windowPath = _syncWindowPath();
+    return _currentPathOverride ?? windowPath;
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createRouter } from "./router.js";
+export { zenNavigationShell } from "./navigation-shell.js";
 export { matchRoute } from "./match.js";
-export { navigate, back, forward, getCurrentPath } from "./navigate.js";
+export { navigate, refreshCurrentRoute, back, forward, getCurrentPath } from "./navigate.js";
 export { onRouteChange, on, off, setRouteProtectionPolicy, _getRouteProtectionPolicy, _dispatchRouteEvent } from "./events.js";

package/dist/index.js

@@ -4,6 +4,7 @@
 // Structural navigation exports + route protection policy/event hooks.
 // ---------------------------------------------------------------------------
 export { createRouter } from './router.js';
-export { navigate, back, forward, getCurrentPath } from './navigate.js';
+export { navigate, refreshCurrentRoute, back, forward, getCurrentPath } from './navigate.js';
 export { onRouteChange, on, off, setRouteProtectionPolicy, _getRouteProtectionPolicy, _dispatchRouteEvent } from './events.js';
+export { zenNavigationShell } from './navigation-shell.js';
 export { matchRoute } from './match.js';

package/dist/navigate.d.ts

@@ -1,5 +1,7 @@
 export declare function _setNavigationResolver(resolver: ((path: string) => Promise<void>) | null): void;
+export declare function _setRefreshResolver(resolver: (() => Promise<void>) | null): void;
 export declare function navigate(path: string): Promise<void>;
+export declare function refreshCurrentRoute(): Promise<void>;
 export declare function back(): void;
 export declare function forward(): void;
 export declare function getCurrentPath(): string;

package/dist/navigate.js

@@ -4,6 +4,7 @@
 // Navigation API.
 //
 // - navigate(path)    → push to history, trigger route change
+// - refreshCurrentRoute() → rerun the current matched route without pushing history
 // - back()            → history.back()
 // - forward()         → history.forward()
 // - getCurrentPath()  → current pathname
@@ -13,15 +14,30 @@
 // ---------------------------------------------------------------------------
 import { current, push } from './history.js';
 let resolveNavigation = null;
+let resolveRefresh = null;
+const ROUTER_REFRESH_KEY = '__zenith_refresh_current_route';
 export function _setNavigationResolver(resolver) {
     resolveNavigation = resolver;
 }
+export function _setRefreshResolver(resolver) {
+    resolveRefresh = resolver;
+}
 export async function navigate(path) {
     push(path);
     if (resolveNavigation) {
         await resolveNavigation(path);
     }
 }
+export async function refreshCurrentRoute() {
+    const scope = typeof globalThis === 'object' && globalThis
+        ? globalThis
+        : {};
+    const resolver = resolveRefresh || scope[ROUTER_REFRESH_KEY] || null;
+    if (typeof resolver !== 'function') {
+        throw new Error('[Zenith Router] refreshCurrentRoute() requires a current matched Zenith page route');
+    }
+    await resolver();
+}
 export function back() {
     history.back();
 }

package/dist/navigation-shell.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tiny visual-only navigation shell controller layered on the existing router lifecycle.
+ *
+ * @param {{ current?: Element | null }} ref
+ * @param {{ timeoutMs?: number, onStateChange?: ((state: { phase: ZenNavigationShellPhase, navigationId: number | null, navigationType: 'push' | 'pop' | null }, context: { previousState: { phase: ZenNavigationShellPhase, navigationId: number | null, navigationType: 'push' | 'pop' | null } }) => void) } | null | undefined} [options]
+ * @returns {{
+ *   mount: () => () => void,
+ *   destroy: () => void,
+ *   getPhase: () => ZenNavigationShellPhase,
+ *   getState: () => { phase: ZenNavigationShellPhase, navigationId: number | null, navigationType: 'push' | 'pop' | null }
+ * }}
+ */
+export function zenNavigationShell(ref: {
+    current?: Element | null;
+}, options?: {
+    timeoutMs?: number;
+    onStateChange?: ((state: {
+        phase: ZenNavigationShellPhase;
+        navigationId: number | null;
+        navigationType: "push" | "pop" | null;
+    }, context: {
+        previousState: {
+            phase: ZenNavigationShellPhase;
+            navigationId: number | null;
+            navigationType: "push" | "pop" | null;
+        };
+    }) => void);
+} | null | undefined): {
+    mount: () => () => void;
+    destroy: () => void;
+    getPhase: () => ZenNavigationShellPhase;
+    getState: () => {
+        phase: ZenNavigationShellPhase;
+        navigationId: number | null;
+        navigationType: "push" | "pop" | null;
+    };
+};
+export type ZenNavigationShellPhase = "idle" | "leaving" | "swapping" | "entering";

package/dist/navigation-shell.js

@@ -0,0 +1,392 @@
+// @ts-nocheck
+import { on, off } from './events.js';
+/**
+ * @typedef {'idle' | 'leaving' | 'swapping' | 'entering'} ZenNavigationShellPhase
+ */
+function isRefLike(value) {
+    return !!value && typeof value === 'object' && 'current' in value;
+}
+function normalizeOptions(options) {
+    if (options === undefined || options === null) {
+        return {
+            timeoutMs: undefined,
+            onStateChange: null
+        };
+    }
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new Error('[Zenith Router] zenNavigationShell(ref, options) requires an options object when provided');
+    }
+    if (options.timeoutMs !== undefined) {
+        if (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0) {
+            throw new Error('[Zenith Router] zenNavigationShell options.timeoutMs must be a non-negative number');
+        }
+    }
+    if (options.onStateChange !== undefined && typeof options.onStateChange !== 'function') {
+        throw new Error('[Zenith Router] zenNavigationShell options.onStateChange must be a function when provided');
+    }
+    return {
+        timeoutMs: options.timeoutMs === undefined ? undefined : Math.floor(options.timeoutMs),
+        onStateChange: typeof options.onStateChange === 'function' ? options.onStateChange : null
+    };
+}
+function parseCssTimeToken(token) {
+    const value = String(token || '').trim();
+    if (value.length === 0) {
+        return 0;
+    }
+    if (value.endsWith('ms')) {
+        const milliseconds = Number.parseFloat(value.slice(0, -2));
+        return Number.isFinite(milliseconds) ? Math.max(0, milliseconds) : 0;
+    }
+    if (value.endsWith('s')) {
+        const seconds = Number.parseFloat(value.slice(0, -1));
+        return Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : 0;
+    }
+    const numeric = Number.parseFloat(value);
+    return Number.isFinite(numeric) ? Math.max(0, numeric) : 0;
+}
+function parseCssTimeList(value) {
+    return String(value || '')
+        .split(',')
+        .map((entry) => parseCssTimeToken(entry))
+        .filter((candidate) => Number.isFinite(candidate));
+}
+function computeMaxCssTotal(durations, delays) {
+    if (!Array.isArray(durations) || durations.length === 0) {
+        return 0;
+    }
+    let maxTotal = 0;
+    for (let index = 0; index < durations.length; index += 1) {
+        const duration = durations[index] || 0;
+        const delay = Array.isArray(delays) && delays.length > 0
+            ? delays[index % delays.length] || 0
+            : 0;
+        const total = duration + delay;
+        if (total > maxTotal) {
+            maxTotal = total;
+        }
+    }
+    return maxTotal;
+}
+function resolveFallbackTimeoutMs(node, explicitTimeoutMs) {
+    if (Number.isFinite(explicitTimeoutMs)) {
+        return explicitTimeoutMs;
+    }
+    const activeWindow = node?.ownerDocument?.defaultView;
+    if (!activeWindow || typeof activeWindow.getComputedStyle !== 'function') {
+        return 0;
+    }
+    const styles = activeWindow.getComputedStyle(node);
+    const transitionTotal = computeMaxCssTotal(parseCssTimeList(styles.transitionDuration), parseCssTimeList(styles.transitionDelay));
+    const animationTotal = computeMaxCssTotal(parseCssTimeList(styles.animationDuration), parseCssTimeList(styles.animationDelay));
+    const total = Math.max(transitionTotal, animationTotal);
+    return total > 0 ? Math.ceil(total + 34) : 0;
+}
+function getTimerApi(node) {
+    const activeWindow = node?.ownerDocument?.defaultView;
+    if (activeWindow && typeof activeWindow.setTimeout === 'function' && typeof activeWindow.clearTimeout === 'function') {
+        return {
+            setTimeout: activeWindow.setTimeout.bind(activeWindow),
+            clearTimeout: activeWindow.clearTimeout.bind(activeWindow)
+        };
+    }
+    return {
+        setTimeout: globalThis.setTimeout.bind(globalThis),
+        clearTimeout: globalThis.clearTimeout.bind(globalThis)
+    };
+}
+function addOwnedListener(node, eventName, handler) {
+    if (!node || typeof node.addEventListener !== 'function' || typeof node.removeEventListener !== 'function') {
+        return () => {
+        };
+    }
+    node.addEventListener(eventName, handler);
+    return () => {
+        node.removeEventListener(eventName, handler);
+    };
+}
+function isOwnedEvent(event, node) {
+    return !!event && event.target === node;
+}
+function cloneState(state) {
+    return {
+        phase: state.phase,
+        navigationId: state.navigationId,
+        navigationType: state.navigationType
+    };
+}
+function normalizeNavigationType(value) {
+    return value === 'push' || value === 'pop' ? value : null;
+}
+function readNavigationId(payload) {
+    return payload && typeof payload.navigationId === 'number' ? payload.navigationId : null;
+}
+function isLifecyclePayload(payload) {
+    return !!payload && typeof payload === 'object';
+}
+/**
+ * Tiny visual-only navigation shell controller layered on the existing router lifecycle.
+ *
+ * @param {{ current?: Element | null }} ref
+ * @param {{ timeoutMs?: number, onStateChange?: ((state: { phase: ZenNavigationShellPhase, navigationId: number | null, navigationType: 'push' | 'pop' | null }, context: { previousState: { phase: ZenNavigationShellPhase, navigationId: number | null, navigationType: 'push' | 'pop' | null } }) => void) } | null | undefined} [options]
+ * @returns {{
+ *   mount: () => () => void,
+ *   destroy: () => void,
+ *   getPhase: () => ZenNavigationShellPhase,
+ *   getState: () => { phase: ZenNavigationShellPhase, navigationId: number | null, navigationType: 'push' | 'pop' | null }
+ * }}
+ */
+export function zenNavigationShell(ref, options = null) {
+    if (!isRefLike(ref)) {
+        throw new Error('[Zenith Router] zenNavigationShell(ref, options) requires a ref-like object with current');
+    }
+    const normalizedOptions = normalizeOptions(options);
+    let mounted = false;
+    let pendingPhaseWait = null;
+    let phaseEpoch = 0;
+    let routeDisposers = [];
+    let shellState = {
+        phase: /** @type {ZenNavigationShellPhase} */ ('idle'),
+        navigationId: null,
+        navigationType: null
+    };
+    function getNode() {
+        const candidate = ref.current;
+        if (!candidate || typeof candidate !== 'object' || typeof candidate.nodeType !== 'number') {
+            return null;
+        }
+        return candidate;
+    }
+    function getState() {
+        return cloneState(shellState);
+    }
+    function applyStateToNode() {
+        const node = getNode();
+        if (!node) {
+            return;
+        }
+        node.setAttribute('data-zen-navigation-phase', shellState.phase);
+        if (shellState.navigationId === null) {
+            node.removeAttribute('data-zen-navigation-id');
+        }
+        else {
+            node.setAttribute('data-zen-navigation-id', String(shellState.navigationId));
+        }
+        if (shellState.navigationType === null) {
+            node.removeAttribute('data-zen-navigation-type');
+        }
+        else {
+            node.setAttribute('data-zen-navigation-type', shellState.navigationType);
+        }
+    }
+    function clearNodeState() {
+        const node = getNode();
+        if (!node) {
+            return;
+        }
+        node.removeAttribute('data-zen-navigation-phase');
+        node.removeAttribute('data-zen-navigation-id');
+        node.removeAttribute('data-zen-navigation-type');
+    }
+    function notifyStateChange(previousState) {
+        if (typeof normalizedOptions.onStateChange !== 'function') {
+            return;
+        }
+        normalizedOptions.onStateChange(getState(), {
+            previousState: cloneState(previousState)
+        });
+    }
+    function setState(nextState, forceApply = false) {
+        const previousState = cloneState(shellState);
+        const changed = previousState.phase !== nextState.phase ||
+            previousState.navigationId !== nextState.navigationId ||
+            previousState.navigationType !== nextState.navigationType;
+        if (!changed && !forceApply) {
+            return;
+        }
+        shellState = cloneState(nextState);
+        if (mounted) {
+            applyStateToNode();
+        }
+        if (changed) {
+            notifyStateChange(previousState);
+        }
+    }
+    function cancelPendingPhaseWait() {
+        if (!pendingPhaseWait) {
+            return;
+        }
+        pendingPhaseWait.cancel();
+        pendingPhaseWait = null;
+    }
+    function resetShellState() {
+        phaseEpoch += 1;
+        cancelPendingPhaseWait();
+        setState({
+            phase: 'idle',
+            navigationId: null,
+            navigationType: null
+        });
+    }
+    function waitForPhaseSettlement(nextPhase, payload) {
+        phaseEpoch += 1;
+        cancelPendingPhaseWait();
+        const navigationId = readNavigationId(payload);
+        const navigationType = normalizeNavigationType(payload?.navigationType);
+        setState({
+            phase: nextPhase,
+            navigationId,
+            navigationType
+        });
+        const node = getNode();
+        const timeoutMs = resolveFallbackTimeoutMs(node, normalizedOptions.timeoutMs);
+        if (!mounted || !node || timeoutMs === 0) {
+            return Promise.resolve();
+        }
+        const timerApi = getTimerApi(node);
+        const activeEpoch = phaseEpoch;
+        return new Promise((resolve) => {
+            const disposers = [];
+            let settled = false;
+            let timeoutId = null;
+            const finish = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                while (disposers.length > 0) {
+                    const dispose = disposers.pop();
+                    try {
+                        dispose();
+                    }
+                    catch {
+                    }
+                }
+                if (timeoutId !== null) {
+                    timerApi.clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                if (pendingPhaseWait === record) {
+                    pendingPhaseWait = null;
+                }
+                resolve();
+            };
+            const handleEnd = (event) => {
+                if (activeEpoch !== phaseEpoch) {
+                    return;
+                }
+                if (!isOwnedEvent(event, node)) {
+                    return;
+                }
+                finish();
+            };
+            disposers.push(addOwnedListener(node, 'transitionend', handleEnd));
+            disposers.push(addOwnedListener(node, 'animationend', handleEnd));
+            timeoutId = timerApi.setTimeout(finish, timeoutMs);
+            const record = {
+                cancel() {
+                    finish();
+                }
+            };
+            pendingPhaseWait = record;
+        });
+    }
+    async function handlePhase(phase, payload) {
+        if (!mounted || !isLifecyclePayload(payload)) {
+            return;
+        }
+        await waitForPhaseSettlement(phase, payload);
+        if (!mounted) {
+            return;
+        }
+        const activeNavigationId = readNavigationId(payload);
+        if (activeNavigationId !== null && shellState.navigationId !== activeNavigationId) {
+            return;
+        }
+        if (phase === 'entering') {
+            setState({
+                phase: 'idle',
+                navigationId: null,
+                navigationType: null
+            });
+        }
+    }
+    function shouldResetForPayload(payload) {
+        if (!mounted || !isLifecyclePayload(payload)) {
+            return false;
+        }
+        const navigationId = readNavigationId(payload);
+        if (navigationId === null) {
+            return shellState.phase !== 'idle';
+        }
+        return shellState.navigationId === navigationId;
+    }
+    function installRouteListeners() {
+        if (routeDisposers.length > 0) {
+            return;
+        }
+        const subscriptions = [
+            ['navigation:before-leave', (payload) => handlePhase('leaving', payload)],
+            ['navigation:before-swap', (payload) => handlePhase('swapping', payload)],
+            ['navigation:before-enter', (payload) => handlePhase('entering', payload)],
+            ['navigation:abort', (payload) => {
+                    if (shouldResetForPayload(payload)) {
+                        resetShellState();
+                    }
+                }],
+            ['navigation:error', (payload) => {
+                    if (shouldResetForPayload(payload)) {
+                        resetShellState();
+                    }
+                }]
+        ];
+        for (let index = 0; index < subscriptions.length; index += 1) {
+            const [eventName, handler] = subscriptions[index];
+            on(eventName, handler);
+            routeDisposers.push(() => {
+                off(eventName, handler);
+            });
+        }
+    }
+    function destroy() {
+        cancelPendingPhaseWait();
+        while (routeDisposers.length > 0) {
+            const dispose = routeDisposers.pop();
+            try {
+                dispose();
+            }
+            catch {
+            }
+        }
+        const previousState = cloneState(shellState);
+        mounted = false;
+        shellState = {
+            phase: 'idle',
+            navigationId: null,
+            navigationType: null
+        };
+        clearNodeState();
+        if (previousState.phase !== 'idle' || previousState.navigationId !== null || previousState.navigationType !== null) {
+            notifyStateChange(previousState);
+        }
+    }
+    function mount() {
+        destroy();
+        mounted = true;
+        installRouteListeners();
+        setState({
+            phase: 'idle',
+            navigationId: null,
+            navigationType: null
+        }, true);
+        return destroy;
+    }
+    return {
+        mount,
+        destroy,
+        getPhase() {
+            return shellState.phase;
+        },
+        getState
+    };
+}

package/dist/router.js

@@ -14,7 +14,7 @@
 import { _dispatchRouteChange } from './events.js';
 import { current, listen } from './history.js';
 import { matchRoute } from './match.js';
-import { _setNavigationResolver } from './navigate.js';
+import { _setNavigationResolver, _setRefreshResolver } from './navigate.js';
 export function createRouter(config) {
     const { routes, container } = config;
     const mountFn = typeof config.mount === 'function' ? config.mount : null;
@@ -28,9 +28,12 @@ export function createRouter(config) {
     let unlisten = null;
     let started = false;
     let hasMounted = false;
-    async function resolvePath(path) {
+    async function resolvePath(path, options = {}) {
         const result = matchRoute(routes, path);
         if (!result) {
+            if (options.failOnUnmatched) {
+                throw new Error('[Zenith Router] refreshCurrentRoute() requires a current matched Zenith page route');
+            }
             _dispatchRouteChange({ path, matched: false });
             return;
         }
@@ -53,6 +56,9 @@ export function createRouter(config) {
             return;
         started = true;
         _setNavigationResolver(resolvePath);
+        _setRefreshResolver(async () => {
+            await resolvePath(current(), { failOnUnmatched: true });
+        });
         unlisten = listen((path) => {
             void resolvePath(path);
         });
@@ -64,6 +70,7 @@ export function createRouter(config) {
             unlisten = null;
         }
         _setNavigationResolver(null);
+        _setRefreshResolver(null);
         started = false;
     }
     return { start, destroy };