@zenithbuild/router 0.7.4 → 0.7.7

package/README.md

@@ -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 };

package/index.d.ts

@@ -1,11 +1,26 @@
+export type RouteDownloadBody = string | Uint8Array | ArrayBuffer;
+
+export interface RouteDownloadOptions {
+    filename: string;
+    contentType?: string;
+}
+
 export type RouteResult =
     | { kind: "allow" }
     | { kind: "redirect"; location: string; status?: number }
     | { kind: "deny"; status: 401 | 403 | 404; message?: string }
-    | { kind: "data"; data: any };
+    | { kind: "data"; data: any }
+    | { kind: "invalid"; data: any; status: 400 | 422 }
+    | { kind: "json"; data: any; status?: number }
+    | { kind: "text"; body: string; status?: number }
+    | { kind: "download"; filename: string; contentType: string; status?: 200 };
 
 export type GuardResult = Extract<RouteResult, { kind: "allow" | "redirect" | "deny" }>;
 export type LoadResult = Extract<RouteResult, { kind: "data" | "redirect" | "deny" }>;
+export type RouteSession = Record<string, unknown>;
+export type RequireSessionOptions =
+    | { redirectTo: string; status?: 302 | 303 | 307 }
+    | { deny: 401 | 403 | 404; message?: string };
 
 export interface RouteContext {
     params: Record<string, string>;
@@ -17,17 +32,24 @@ export interface RouteContext {
     route: { id: string; pattern: string; file: string };
     env: Record<string, string>;
     auth: {
-        getSession(ctx: RouteContext): Promise<any>;
-        requireSession(ctx: RouteContext): Promise<void>;
+        getSession(): Promise<RouteSession | null>;
+        requireSession(options: RequireSessionOptions): Promise<RouteSession>;
+        signIn(sessionObject: RouteSession): Promise<void>;
+        signOut(): Promise<void>;
     };
     allow(): { kind: "allow" };
     redirect(location: string, status?: number): { kind: "redirect"; location: string; status: number };
     deny(status: 401 | 403 | 404, message?: string): { kind: "deny"; status: 401 | 403 | 404; message?: string };
     data(payload: any): { kind: "data"; data: any };
+    invalid(payload: any, status?: 400 | 422): { kind: "invalid"; data: any; status: 400 | 422 };
+    json(payload: any, status?: number): { kind: "json"; data: any; status: number };
+    text(body: string, status?: number): { kind: "text"; body: string; status: number };
+    download(body: RouteDownloadBody, options: RouteDownloadOptions): { kind: "download"; filename: string; contentType: string; status: 200 };
 }
 
 export declare function createRouter(config: { routes: any[]; container: HTMLElement }): { start: () => Promise<void>; destroy: () => 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;
@@ -41,7 +63,26 @@ export interface RouteProtectionPolicy {
     forbiddenPath?: string;
 }
 
-export type NavigationType = "push" | "pop";
+export type NavigationType = "push" | "pop" | "refresh";
+export type NavigationShellPhase = "idle" | "leaving" | "swapping" | "entering";
+
+export interface NavigationShellState {
+    phase: NavigationShellPhase;
+    navigationId: number | null;
+    navigationType: NavigationType | null;
+}
+
+export interface NavigationShellOptions {
+    timeoutMs?: number;
+    onStateChange?: (state: NavigationShellState, context: { previousState: NavigationShellState }) => void;
+}
+
+export interface NavigationShellController {
+    mount(): () => void;
+    destroy(): void;
+    getPhase(): NavigationShellPhase;
+    getState(): NavigationShellState;
+}
 
 export interface NavigationLifecyclePayload {
     navigationId: number;
@@ -95,3 +136,4 @@ export type RouteEventName =
 export declare function setRouteProtectionPolicy(policy: RouteProtectionPolicy): void;
 export declare function on(eventName: RouteEventName, handler: RouteEventHandler): void;
 export declare function off(eventName: RouteEventName, handler: RouteEventHandler): void;
+export declare function zenNavigationShell(ref: { current?: Element | null }, options?: NavigationShellOptions | null): NavigationShellController;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/router",
-  "version": "0.7.4",
+  "version": "0.7.7",
   "description": "File-based SPA router for Zenith framework with deterministic, compile-time route resolution",
   "license": "MIT",
   "type": "module",

package/template-core.js

@@ -437,6 +437,14 @@ function resolveScrollTarget(targetUrl, historyMode, popstateState) {
     const saved = readStoredScroll(popstateState);
     return { mode: "restore", x: saved.x, y: saved.y, focusTarget: null };
   }
+  if (historyMode === "refresh") {
+    return {
+      mode: "restore",
+      x: window.scrollX || window.pageXOffset || 0,
+      y: window.scrollY || window.pageYOffset || 0,
+      focusTarget: null
+    };
+  }
   return { mode: "top", x: 0, y: 0, focusTarget: null };
 }
 

package/template-form.js

@@ -36,15 +36,6 @@ function resolveFormMethod(form, submitter) {
   );
 }
 
-function resolveFormEnctype(form, submitter) {
-  return String(
-    readSubmitOverride(submitter, "formenctype", "formEnctype") ||
-    form.getAttribute("enctype") ||
-    form.enctype ||
-    "application/x-www-form-urlencoded"
-  ).toLowerCase();
-}
-
 function createFormSubmissionPayload(form, submitter) {
   try {
     return submitter ? new FormData(form, submitter) : new FormData(form);
@@ -63,7 +54,6 @@ function shouldEnhanceForm(form, submitter) {
   const target = resolveFormTargetValue(form, submitter);
   if (target && target !== "_self") return false;
   if (resolveFormMethod(form, submitter) !== "POST") return false;
-  if (resolveFormEnctype(form, submitter).includes("multipart/form-data")) return false;
 
   const targetUrl = resolveFormTargetUrl(form, submitter);
   if (targetUrl.origin !== window.location.origin) return false;

package/template-navigation.js

@@ -1,5 +1,6 @@
-export function renderRouterNavigationSource() {
-    return `async function requestRouteCheck(context, resolved, targetUrl, signal) {
+export function renderRouterNavigationSource({ routeCheck = false, formsEnabled = true } = {}) {
+    const routeCheckSource = routeCheck
+        ? `async function requestRouteCheck(context, resolved, targetUrl, signal) {
   if (!__ZENITH_ROUTE_CHECK_ENABLED__) {
     return { kind: "allow" };
   }
@@ -79,7 +80,12 @@ export function renderRouterNavigationSource() {
     });
     return { kind: "allow" };
   }
-}
+}`
+        : `async function requestRouteCheck() {
+  return { kind: "allow" };
+}`;
+
+    return `${routeCheckSource}
 
 function resolveRedirectUrl(location, fallbackUrl) {
   try {
@@ -98,6 +104,10 @@ function navigateViaBrowser(targetUrl, replace) {
   window.location.assign(targetUrl.href);
 }
 
+function shouldReplaceBrowserNavigation(historyMode) {
+  return historyMode === "pop";
+}
+
 function dispatchNavigationFallback(context, detail) {
   emitNavigationAbort(context, detail);
 }
@@ -231,7 +241,7 @@ async function performNavigation(targetUrl, historyMode, popstateState) {
         location: redirectUrl.href,
         status: checkResult.status
       });
-      navigateViaBrowser(redirectUrl, historyMode === "pop");
+      navigateViaBrowser(redirectUrl, shouldReplaceBrowserNavigation(historyMode));
       return true;
     }
     if (checkResult.kind === "deny") {
@@ -239,7 +249,7 @@ async function performNavigation(targetUrl, historyMode, popstateState) {
         reason: "server-deny",
         status: checkResult.status
       });
-      navigateViaBrowser(targetUrl, historyMode === "pop");
+      navigateViaBrowser(targetUrl, shouldReplaceBrowserNavigation(historyMode));
       return true;
     }
 
@@ -259,7 +269,7 @@ async function performNavigation(targetUrl, historyMode, popstateState) {
         location: redirectUrl.href,
         status: response.status
       });
-      navigateViaBrowser(redirectUrl, historyMode === "pop");
+      navigateViaBrowser(redirectUrl, shouldReplaceBrowserNavigation(historyMode));
       return true;
     }
 
@@ -270,7 +280,7 @@ async function performNavigation(targetUrl, historyMode, popstateState) {
         reason: "http-status",
         status: response.status
       });
-      navigateViaBrowser(targetUrl, historyMode === "pop");
+      navigateViaBrowser(targetUrl, shouldReplaceBrowserNavigation(historyMode));
       return true;
     }
     if (!isHtmlResponse(response)) {
@@ -278,7 +288,7 @@ async function performNavigation(targetUrl, historyMode, popstateState) {
         reason: "non-html",
         status: response.status
       });
-      navigateViaBrowser(targetUrl, historyMode === "pop");
+      navigateViaBrowser(targetUrl, shouldReplaceBrowserNavigation(historyMode));
       return true;
     }
 
@@ -287,7 +297,7 @@ async function performNavigation(targetUrl, historyMode, popstateState) {
       dispatchNavigationFallback(context, {
         reason: "document-parse"
       });
-      navigateViaBrowser(targetUrl, historyMode === "pop");
+      navigateViaBrowser(targetUrl, shouldReplaceBrowserNavigation(historyMode));
       return true;
     }
     const committed = await commitNavigationDocument(
@@ -317,7 +327,7 @@ async function performNavigation(targetUrl, historyMode, popstateState) {
         reason: "runtime-failure",
         historyCommitted
       });
-      navigateViaBrowser(targetUrl, historyMode === "pop" || historyCommitted);
+      navigateViaBrowser(targetUrl, shouldReplaceBrowserNavigation(historyMode) || historyCommitted);
       return true;
     }
     dispatchNavigationFallback(context, context.abortReason || {
@@ -361,7 +371,7 @@ function start() {
     currentUrl = new URL(window.location.href);
     queueScrollSnapshot();
   });
-  installEnhancedFormHandling();
+${formsEnabled ? "  installEnhancedFormHandling();\n" : ""}
 
   document.addEventListener("click", function(event) {
     if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;

package/template.js

@@ -3,6 +3,7 @@ import { renderRouterDocumentSource } from './template-document.js';
 import { renderRouterFormSource } from './template-form.js';
 import { renderRouterLifecycleSource } from './template-lifecycle.js';
 import { renderRouterNavigationSource } from './template-navigation.js';
+import { renderRouterRefreshSource } from './template-refresh.js';
 
 function normalizeManifestJson(manifestJson) {
     return manifestJson.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
@@ -21,7 +22,7 @@ export function renderRouterModule(opts) {
         throw new Error('renderRouterModule(opts) requires an options object');
     }
 
-    const { manifestJson, runtimeImport, coreImport, routeCheck = false } = opts;
+    const { manifestJson, runtimeImport, coreImport, routeCheck = false, formsEnabled = true } = opts;
     if (typeof manifestJson !== 'string' || manifestJson.length === 0) {
         throw new Error('renderRouterModule(opts) requires opts.manifestJson string');
     }
@@ -36,5 +37,5 @@ export function renderRouterModule(opts) {
     const runtimeSpec = sanitizeImportSpecifier(runtimeImport);
     const coreSpec = sanitizeImportSpecifier(coreImport);
 
-    return `${renderRouterCoreSource({ manifest, runtimeSpec, coreSpec, routeCheck })}\n\n${renderRouterDocumentSource()}\n\n${renderRouterLifecycleSource()}\n\n${renderRouterNavigationSource()}\n\n${renderRouterFormSource()}\n`;
+    return `${renderRouterCoreSource({ manifest, runtimeSpec, coreSpec, routeCheck })}\n\n${renderRouterDocumentSource()}\n\n${renderRouterLifecycleSource()}\n\n${renderRouterRefreshSource()}\n\n${renderRouterNavigationSource({ routeCheck, formsEnabled })}${formsEnabled ? `\n\n${renderRouterFormSource()}` : ""}\n`;
 }