toiljs 0.0.7 → 0.0.9

package/src/client/components/Script.tsx

@@ -0,0 +1,113 @@
+import { useEffect, type ReactNode } from 'react';
+
+/**
+ * When a {@link Script} is injected, relative to the app becoming interactive:
+ * - `afterInteractive` (default), on mount, once the app is running. Good for analytics, widgets.
+ * - `lazyOnload`, deferred until the browser is idle (after `window.load`). For low-priority scripts.
+ * - `beforeInteractive`, as early as possible. In a client-only SPA there is no SSR, so this still
+ *   runs after hydration, but synchronously on first mount with high fetch priority.
+ */
+export type ScriptStrategy = 'beforeInteractive' | 'afterInteractive' | 'lazyOnload';
+
+/** Props for {@link Script}. Provide either `src` (external) or inline `children` (script body). */
+export interface ScriptProps {
+    /** URL of an external script. Omit when providing an inline script body via `children`. */
+    src?: string;
+    /** When to load the script. Default `'afterInteractive'`. */
+    strategy?: ScriptStrategy;
+    /** Stable identity for dedup (required for inline scripts; defaults to `src` for external ones). */
+    id?: string;
+    /** `type` attribute (e.g. `'module'`, `'application/json'`). */
+    type?: string;
+    /** Fired once the script has loaded (external) or been inserted (inline). */
+    onLoad?: () => void;
+    /** Fired after load, and on every later mount once the script is already loaded. */
+    onReady?: () => void;
+    /** Fired if an external script fails to load. */
+    onError?: (error: unknown) => void;
+    /** Inline script body. Mutually exclusive with `src`. */
+    children?: string;
+}
+
+type LoadState = 'loading' | 'ready';
+/** Module-level registry so a given script is injected/executed at most once across the app. */
+const registry = new Map<string, LoadState>();
+
+function inject(props: ScriptProps, key: string): void {
+    const { src, type, onLoad, onReady, onError, children } = props;
+    const el = document.createElement('script');
+    el.dataset.toilScript = key;
+    if (type !== undefined) el.type = type;
+
+    if (src !== undefined) {
+        el.src = src;
+        el.async = true;
+        el.addEventListener('load', () => {
+            registry.set(key, 'ready');
+            onLoad?.();
+            onReady?.();
+        });
+        el.addEventListener('error', (event) => {
+            registry.delete(key); // allow a later remount to retry
+            onError?.(event);
+        });
+        document.head.appendChild(el);
+    } else {
+        el.textContent = children ?? '';
+        document.head.appendChild(el);
+        registry.set(key, 'ready');
+        onLoad?.();
+        onReady?.();
+    }
+}
+
+/**
+ * Loads an external or inline `<script>` with a load `strategy`, deduplicated across the app so the
+ * same script never executes twice. Renders nothing. Mirrors the ergonomics of Next.js `next/script`
+ * for a client-only SPA.
+ */
+export function Script(props: ScriptProps): ReactNode {
+    const { src, id, strategy = 'afterInteractive', onReady } = props;
+    const key = id ?? src;
+
+    useEffect(() => {
+        if (key === undefined) {
+            // No id and no src: nothing to dedup or load (an inline script needs at least an id).
+            return;
+        }
+
+        const state = registry.get(key);
+        if (state === 'ready') {
+            onReady?.();
+            return;
+        }
+        if (state === 'loading') {
+            return; // another instance is already injecting it
+        }
+
+        registry.set(key, 'loading');
+        const run = (): void => {
+            inject(props, key);
+        };
+
+        if (strategy === 'lazyOnload') {
+            if (document.readyState === 'complete') {
+                const idle = window.requestIdleCallback?.bind(window);
+                if (idle) idle(run);
+                else setTimeout(run, 0);
+            } else {
+                window.addEventListener('load', run, { once: true });
+            }
+            return () => {
+                window.removeEventListener('load', run);
+            };
+        }
+
+        // beforeInteractive + afterInteractive: inject now (on mount).
+        run();
+        // Intentionally keyed on identity only: inject once per script key; later prop changes
+        // (handlers, body) are read at inject time and must not re-run/re-inject the script.
+    }, [key, strategy]);
+
+    return null;
+}

package/src/client/components/Slot.tsx

@@ -0,0 +1,21 @@
+import { useContext, type ReactNode } from 'react';
+
+import { SlotContext } from '../routing/slot-context.js';
+
+/** Props for {@link Slot}. */
+export interface SlotProps {
+    /** The parallel-slot name, the `@name` directory under `routes/` (without the `@`). */
+    name: string;
+    /** Rendered when the slot has no match for the current URL. Default `null`. */
+    fallback?: ReactNode;
+}
+
+/**
+ * Renders the parallel-route slot named `name` for the current URL. Place it in a layout or page to
+ * show an `@name` route tree alongside the main content (e.g. a persistent sidebar, or a modal that
+ * an intercepting route fills). Renders `fallback` (default nothing) when no slot route matches.
+ */
+export function Slot({ name, fallback = null }: SlotProps): ReactNode {
+    const slots = useContext(SlotContext);
+    return slots[name] ?? fallback;
+}

package/src/client/dev/error-overlay.tsx

@@ -0,0 +1,197 @@
+/**
+ * Development-only error overlay. In dev, surfaces errors that would otherwise leave a blank page or
+ * live only in the console: uncaught render errors (incl. those thrown by a loader during render),
+ * plus `window` `error` / `unhandledrejection` events. Shows the message, stack, and (for render
+ * errors) the React component stack, with Dismiss / Reload. Inert in production builds.
+ */
+import {
+    Component,
+    useSyncExternalStore,
+    type CSSProperties,
+    type ErrorInfo,
+    type ReactNode,
+} from 'react';
+
+/** A captured dev error. */
+interface DevError {
+    readonly error: Error;
+    readonly componentStack?: string;
+    /** Where it came from, a render boundary, a window `error`, or an unhandled rejection. */
+    readonly source: 'render' | 'window' | 'unhandledrejection';
+}
+
+let current: DevError | null = null;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+    for (const listener of listeners) listener();
+}
+function setDevError(next: DevError | null): void {
+    current = next;
+    emit();
+}
+function subscribe(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+
+/** True when running under Vite's dev server (replaced at build time; falsy in production). */
+export function isDevMode(): boolean {
+    try {
+        return Boolean((import.meta as { env?: { DEV?: boolean } }).env?.DEV);
+    } catch {
+        return false;
+    }
+}
+
+let windowBound = false;
+/** Wires `window` error / unhandledrejection into the overlay (idempotent; dev only). */
+export function initDevErrorOverlay(): void {
+    if (windowBound || typeof window === 'undefined') return;
+    windowBound = true;
+    window.addEventListener('error', (event) => {
+        if (event.error instanceof Error) setDevError({ error: event.error, source: 'window' });
+    });
+    window.addEventListener('unhandledrejection', (event) => {
+        const reason: unknown = event.reason;
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        setDevError({ error, source: 'unhandledrejection' });
+    });
+}
+
+interface BoundaryProps {
+    readonly children: ReactNode;
+}
+interface BoundaryState {
+    readonly crashed: boolean;
+}
+
+/**
+ * Catches render errors in its subtree and reports them to the overlay. While crashed it renders
+ * nothing (the subtree threw); it recovers when the overlay is dismissed. Class component because
+ * React error boundaries have no hook equivalent.
+ */
+export class DevErrorBoundary extends Component<BoundaryProps, BoundaryState> {
+    public state: BoundaryState = { crashed: false };
+    private unsubscribe: (() => void) | undefined;
+
+    public static getDerivedStateFromError(): BoundaryState {
+        return { crashed: true };
+    }
+
+    public override componentDidCatch(error: Error, info: ErrorInfo): void {
+        setDevError({ error, componentStack: info.componentStack ?? undefined, source: 'render' });
+    }
+
+    public override componentDidMount(): void {
+        // Recover (re-render children) once the error is dismissed from the overlay.
+        this.unsubscribe = subscribe(() => {
+            if (current === null && this.state.crashed) this.setState({ crashed: false });
+        });
+    }
+
+    public override componentWillUnmount(): void {
+        this.unsubscribe?.();
+    }
+
+    public override render(): ReactNode {
+        return this.state.crashed ? null : this.props.children;
+    }
+}
+
+const overlayStyle: CSSProperties = {
+    position: 'fixed',
+    inset: 0,
+    zIndex: 2147483647,
+    background: 'rgba(8, 8, 12, 0.88)',
+    color: '#f5f6fa',
+    font: '13px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace',
+    padding: '2rem',
+    overflow: 'auto',
+    display: 'flex',
+    justifyContent: 'center',
+    alignItems: 'flex-start',
+};
+const panelStyle: CSSProperties = {
+    maxWidth: 900,
+    width: '100%',
+    background: '#15151c',
+    border: '1px solid #ef4444',
+    borderRadius: 10,
+    padding: '1.25rem 1.5rem',
+    boxShadow: '0 12px 48px rgba(0,0,0,0.5)',
+};
+const titleStyle: CSSProperties = {
+    margin: 0,
+    color: '#ff6b6b',
+    fontSize: '1rem',
+    fontWeight: 700,
+    wordBreak: 'break-word',
+};
+const preStyle: CSSProperties = {
+    whiteSpace: 'pre-wrap',
+    wordBreak: 'break-word',
+    margin: '0.75rem 0 0',
+    color: '#c8cee0',
+};
+const buttonStyle: CSSProperties = {
+    font: 'inherit',
+    color: '#f5f6fa',
+    background: '#2a2a36',
+    border: '1px solid #3a3a48',
+    borderRadius: 6,
+    padding: '0.4em 1em',
+    cursor: 'pointer',
+    marginRight: '0.5rem',
+};
+
+const SOURCE_LABEL: Record<DevError['source'], string> = {
+    render: 'Render error',
+    window: 'Uncaught error',
+    unhandledrejection: 'Unhandled promise rejection',
+};
+
+/** Renders the overlay when a dev error is captured. Mount once at the app root (dev only). */
+export function DevErrorOverlay(): ReactNode {
+    const devError = useSyncExternalStore(
+        subscribe,
+        () => current,
+        () => null,
+    );
+    if (!devError) return null;
+    return (
+        <div
+            style={overlayStyle}
+            role="alert">
+            <div style={panelStyle}>
+                <p style={titleStyle}>
+                    {SOURCE_LABEL[devError.source]}, {devError.error.name}: {devError.error.message}
+                </p>
+                {devError.error.stack !== undefined && <pre style={preStyle}>{devError.error.stack}</pre>}
+                {devError.componentStack !== undefined && (
+                    <pre style={{ ...preStyle, color: '#8b9ab4' }}>{devError.componentStack}</pre>
+                )}
+                <div style={{ marginTop: '1.25rem' }}>
+                    <button
+                        type="button"
+                        style={buttonStyle}
+                        onClick={() => {
+                            setDevError(null);
+                        }}>
+                        Dismiss
+                    </button>
+                    <button
+                        type="button"
+                        style={buttonStyle}
+                        onClick={() => {
+                            window.location.reload();
+                        }}>
+                        Reload
+                    </button>
+                </div>
+            </div>
+        </div>
+    );
+}

package/src/client/head/head.ts

@@ -4,7 +4,7 @@
  * (later/deeper entries win per key) and are reverted when the component unmounts. Pure
  * `mergeHead` resolves the active entries; the manager reconciles `document.head`.
  */
-import { useEffect } from 'react';
+import { useEffect, useLayoutEffect } from 'react';
 
 /** A `<meta>` tag. Use `name` or `property` (OpenGraph) as the dedup key; extra attrs pass through. */
 export interface MetaTag {
@@ -70,6 +70,9 @@ const entries = new Map<number, HeadSpec>();
 let order: number[] = [];
 let seq = 0;
 let baseTitle: string | null = null;
+// The current route's resolved metadata, the lowest-priority spec, so component `useHead`/`<Head>`
+// always compose on top of it. Set by the router via `setRouteHead` on each navigation.
+let routeHead: HeadSpec | null = null;
 
 function setAttrs(el: Element, attrs: Record<string, string | undefined>): void {
     el.setAttribute('data-toil-head', '');
@@ -83,7 +86,8 @@ function apply(): void {
     if (typeof document === 'undefined') return;
     if (baseTitle === null) baseTitle = document.title;
 
-    const resolved = mergeHead(order.map((id) => entries.get(id)).filter((s): s is HeadSpec => !!s));
+    const specs = [routeHead, ...order.map((id) => entries.get(id))];
+    const resolved = mergeHead(specs.filter((s): s is HeadSpec => !!s));
 
     document.title = resolved.title ?? baseTitle;
 
@@ -116,7 +120,7 @@ function removeHead(id: number): void {
 
 /**
  * Applies a head contribution for the lifetime of the calling component: title, `<meta>`, `<link>`.
- * Reverts on unmount. Compose freely — a root layout can set defaults a page overrides.
+ * Reverts on unmount. Compose freely, a root layout can set defaults a page overrides.
  */
 export function useHead(spec: HeadSpec): void {
     const json = JSON.stringify(spec);
@@ -138,3 +142,24 @@ export function Head(props: HeadSpec): null {
     useHead(props);
     return null;
 }
+
+/** Sets the current route's baseline head (lowest priority). Pass `null` to clear it. */
+export function setRouteHead(spec: HeadSpec | null): void {
+    routeHead = spec;
+    apply();
+}
+
+/**
+ * Applies a route's resolved `metadata` as the baseline head for the calling route's lifetime, and
+ * clears it on unmount. Used internally by the router; a layout-effect so the title updates before
+ * paint (no flicker).
+ */
+export function useRouteHead(spec: HeadSpec | undefined): void {
+    const json = spec ? JSON.stringify(spec) : '';
+    useLayoutEffect(() => {
+        setRouteHead(json ? (JSON.parse(json) as HeadSpec) : null);
+        return () => {
+            setRouteHead(null);
+        };
+    }, [json]);
+}

package/src/client/head/metadata.ts

@@ -0,0 +1,92 @@
+/**
+ * Route metadata, the declarative SEO counterpart to `useHead`/`<Head>`. A route file may
+ * `export const metadata` (static) or `export const generateMetadata` (dynamic, using its loader
+ * data); the compiler-driven loader resolves it to a {@link HeadSpec} that the router applies as the
+ * route's baseline head (component-level `useHead`/`<Head>` still compose on top and can override).
+ */
+import type { HeadSpec, LinkTag, MetaTag } from './head.js';
+import type { RouteParams } from '../routing/match.js';
+
+/** OpenGraph fields, expanded to `og:*` meta tags. */
+export interface OpenGraph {
+    readonly title?: string;
+    readonly description?: string;
+    readonly type?: string;
+    readonly url?: string;
+    readonly image?: string;
+    readonly siteName?: string;
+}
+
+/** A route's metadata. Convenience fields expand to the right `<meta>`/`<link>` tags. */
+export interface Metadata {
+    /** Document title. */
+    readonly title?: string;
+    /** Template applied to the title (`%s` = the title), e.g. `'%s · toiljs'`. */
+    readonly titleTemplate?: string;
+    /** `<meta name="description">`. */
+    readonly description?: string;
+    /** `<meta name="keywords">`, joined with `, ` if an array. */
+    readonly keywords?: string | readonly string[];
+    /** `<link rel="canonical">`. */
+    readonly canonical?: string;
+    /** `<meta name="robots">`, e.g. `'noindex, nofollow'`. */
+    readonly robots?: string;
+    /** `<meta name="theme-color">`. */
+    readonly themeColor?: string;
+    /** OpenGraph (`og:*`) tags. */
+    readonly openGraph?: OpenGraph;
+    /** Escape hatch: extra raw `<meta>` tags. */
+    readonly meta?: readonly MetaTag[];
+    /** Escape hatch: extra raw `<link>` tags. */
+    readonly link?: readonly LinkTag[];
+}
+
+/** Arguments passed to {@link GenerateMetadata}: route params, query, and the loader's data. */
+export interface GenerateMetadataArgs<T = unknown> {
+    readonly params: RouteParams;
+    readonly searchParams: URLSearchParams;
+    readonly data: T;
+}
+
+/** A route's `export const generateMetadata`, dynamic metadata derived from params/query/loader data. */
+export type GenerateMetadata<T = unknown> = (
+    args: GenerateMetadataArgs<T>,
+) => Metadata | Promise<Metadata>;
+
+/** Expands a {@link Metadata} into a {@link HeadSpec} (title + concrete meta/link tags). */
+export function resolveMetadata(metadata: Metadata): HeadSpec {
+    const meta: MetaTag[] = [];
+    if (metadata.description !== undefined) {
+        meta.push({ name: 'description', content: metadata.description });
+    }
+    if (metadata.keywords !== undefined) {
+        const content =
+            typeof metadata.keywords === 'string' ? metadata.keywords : metadata.keywords.join(', ');
+        meta.push({ name: 'keywords', content });
+    }
+    if (metadata.robots !== undefined) meta.push({ name: 'robots', content: metadata.robots });
+    if (metadata.themeColor !== undefined) {
+        meta.push({ name: 'theme-color', content: metadata.themeColor });
+    }
+    const og = metadata.openGraph;
+    if (og) {
+        const pairs: readonly [string, string | undefined][] = [
+            ['og:title', og.title],
+            ['og:description', og.description],
+            ['og:type', og.type],
+            ['og:url', og.url],
+            ['og:image', og.image],
+            ['og:site_name', og.siteName],
+        ];
+        for (const [property, content] of pairs) {
+            if (content !== undefined) meta.push({ property, content });
+        }
+    }
+    if (metadata.meta) meta.push(...metadata.meta);
+
+    const link: LinkTag[] = [];
+    if (metadata.canonical !== undefined) link.push({ rel: 'canonical', href: metadata.canonical });
+    if (metadata.link) link.push(...metadata.link);
+
+    return { title: metadata.title, titleTemplate: metadata.titleTemplate, meta, link };
+}

package/src/client/index.ts

@@ -14,7 +14,7 @@ export { Link } from './navigation/Link.js';
 export type { LinkProps } from './navigation/Link.js';
 export { NavLink, matchActive } from './navigation/NavLink.js';
 export type { NavLinkProps, NavLinkState } from './navigation/NavLink.js';
-export { navigate, back, forward, refresh } from './navigation/navigation.js';
+export { navigate, back, forward, refresh, setViewTransitions } from './navigation/navigation.js';
 export type { NavigateOptions } from './navigation/navigation.js';
 export {
     useParams,
@@ -26,8 +26,15 @@ export {
     useNavigationPending,
 } from './routing/hooks.js';
 export type { RouterInstance } from './routing/hooks.js';
-export { useLoaderData } from './routing/loader.js';
-export type { LoaderArgs, LoaderFunction } from './routing/loader.js';
+export { useLoaderData, revalidate, invalidateLoaderData } from './routing/loader.js';
+export type { LoaderArgs, LoaderFunction, LoaderData, Revalidate } from './routing/loader.js';
+export { useAction } from './routing/action.js';
+export type {
+    UseActionOptions,
+    ActionState,
+    ActionHandle,
+    RevalidateTarget,
+} from './routing/action.js';
 export { prefetch } from './navigation/prefetch.js';
 export type {
     RouteDef,
@@ -45,3 +52,13 @@ export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel
 export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
 export { useHead, useTitle, Head, mergeHead } from './head/head.js';
 export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';
+export { resolveMetadata } from './head/metadata.js';
+export type { Metadata, GenerateMetadata, GenerateMetadataArgs, OpenGraph } from './head/metadata.js';
+export { Image } from './components/Image.js';
+export type { ImageProps } from './components/Image.js';
+export { Script } from './components/Script.js';
+export type { ScriptProps, ScriptStrategy } from './components/Script.js';
+export { Form } from './components/Form.js';
+export type { FormProps } from './components/Form.js';
+export { Slot } from './components/Slot.js';
+export type { SlotProps } from './components/Slot.js';

package/src/client/navigation/Link.tsx

@@ -37,7 +37,7 @@ function isExternalHref(href: string): boolean {
 
 /**
  * Client-side navigation link. Forwards all anchor attributes to the underlying `<a>`, and
- * prefetches the target route's chunk on hover/focus. Intercepts only plain same-origin clicks —
+ * prefetches the target route's chunk on hover/focus. Intercepts only plain same-origin clicks , 
  * modified clicks, `target=_blank`, `download`, in-page `#hash`, and external URLs fall through to
  * native browser behavior.
  */

package/src/client/navigation/navigation.ts

@@ -3,6 +3,9 @@
  * the per-entry history keys used for scroll restoration. Consumed by `useLocation` (to re-render),
  * `Link` / `navigate` (to change location), and `Router` (which calls `applyScroll` after commit).
  */
+import { startTransition } from 'react';
+import { flushSync } from 'react-dom';
+
 import {
     enableManualScrollRestoration,
     planScroll,
@@ -13,6 +16,26 @@ import type { Href } from '../types.js';
 const listeners = new Set<() => void>();
 let popstateBound = false;
 
+/** `document.startViewTransition`, present only where the View Transitions API is supported. */
+interface ViewTransitionDocument {
+    startViewTransition?: (callback: () => void) => unknown;
+}
+let viewTransitions = false;
+
+/** Enables animated View Transitions for navigation. Called once by `mount` from `client.viewTransitions`. */
+export function setViewTransitions(enabled: boolean): void {
+    viewTransitions = enabled;
+}
+
+/** Whether the current navigation should animate via the View Transitions API. */
+function shouldViewTransition(): boolean {
+    if (!viewTransitions || typeof document === 'undefined' || typeof window === 'undefined') {
+        return false;
+    }
+    if (typeof (document as ViewTransitionDocument).startViewTransition !== 'function') return false;
+    return !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
 interface ToilHistoryState {
     __toilKey?: string;
 }
@@ -23,11 +46,51 @@ function nextKey(): string {
     return `t${String(keyCounter)}`;
 }
 
-/** Notifies every subscriber that the location may have changed. */
-function notify(): void {
+function runListeners(): void {
     for (const listener of listeners) listener();
 }
 
+/**
+ * Re-renders subscribers for a location change. Normally wrapped in `startTransition` (smooth: the
+ * current page stays while the next route loads). When View Transitions are enabled and supported,
+ * the commit runs synchronously inside `document.startViewTransition` so the browser animates the
+ * old and new DOM (a crossfade, or shared-element transitions via `view-transition-name`).
+ */
+function notify(): void {
+    if (shouldViewTransition()) {
+        (document as ViewTransitionDocument).startViewTransition?.(() => {
+            flushSync(runListeners);
+        });
+    } else {
+        startTransition(runListeners);
+    }
+}
+
+// Soft vs hard navigation, for intercepting routes. The initial page load (and any full refresh) is
+// "hard"; client navigations (`navigate` / back / forward) are "soft". `previousPath` is the path we
+// were on before the latest soft navigation, the route the main view keeps showing while an
+// intercepting route fills a slot (the modal overlay).
+let softNav = false;
+let currentPath = typeof window === 'undefined' ? '/' : window.location.pathname;
+let previousPath = currentPath;
+
+/** Records a transition to the live location; `soft` is false only for the initial load. */
+function recordTransition(soft: boolean): void {
+    previousPath = currentPath;
+    currentPath = typeof window === 'undefined' ? '/' : window.location.pathname;
+    softNav = soft;
+}
+
+/** Whether the current location was reached by a client navigation (not an initial load / refresh). */
+export function isSoftNavigation(): boolean {
+    return softNav;
+}
+
+/** The path the app was on before the latest navigation (what the main view keeps during an intercept). */
+export function previousPathname(): string {
+    return previousPath;
+}
+
 // Navigation-pending tracking: a navigation is "pending" from when it starts until the new route
 // commits. Drives useNavigationPending() (e.g. a top loading bar).
 let startedTick = 0;
@@ -54,7 +117,7 @@ export function isNavigationPending(): boolean {
     return startedTick !== committedTick;
 }
 
-/** Monotonic id incremented on each navigation — used to key/revalidate per-navigation route data. */
+/** Monotonic id incremented on each navigation, used to key/revalidate per-navigation route data. */
 export function navigationEpoch(): number {
     return startedTick;
 }
@@ -103,6 +166,7 @@ export function navigate(href: Href, options?: NavigateOptions): void {
         currentKey = nextKey();
         window.history.pushState({ __toilKey: currentKey }, '', href);
     }
+    recordTransition(true);
     planScroll({ hash, toTop: options?.scroll !== false });
     notify();
 }
@@ -117,8 +181,13 @@ export function forward(): void {
     window.history.forward();
 }
 
-/** Re-renders the current route without changing the URL (there is no server data to refetch). */
+/**
+ * Re-renders the current route, bumping the navigation epoch so a revalidation of the *same* URL
+ * re-keys its Suspense boundary (its `loading.tsx` shows while the loader re-runs) and
+ * `useNavigationPending` reports the in-flight refetch, instead of silently freezing the old page.
+ */
 export function refresh(): void {
+    beginNavigation();
     notify();
 }
 
@@ -128,6 +197,7 @@ function handlePopState(event: PopStateEvent): void {
     rememberScroll(currentKey);
     const state = event.state as ToilHistoryState | null;
     currentKey = state?.__toilKey ?? 'initial';
+    recordTransition(true);
     planScroll({ restoreKey: currentKey, hash: window.location.hash, toTop: false });
     notify();
 }

package/src/client/navigation/prefetch.ts

@@ -45,7 +45,7 @@ function warm(route: RouteDef): void {
 
 /**
  * Prefetches the route chunk for an internal `href` so a later navigation resolves instantly.
- * No-op for external, unknown, or already-prefetched targets — safe to call from anywhere,
+ * No-op for external, unknown, or already-prefetched targets, safe to call from anywhere,
  * including before an imperative {@link navigate} (e.g. `prefetch('/dashboard')` on hover/intent).
  */
 export function prefetch(href: string): void {
@@ -83,7 +83,7 @@ function shouldSkipForConnection(): boolean {
 
 /**
  * Starts idle-time prefetching of internal links. As each `<a>` pointing at a known route scrolls
- * into view (or near it — 200px margin) its chunk is warmed once; links added later by client
+ * into view (or near it, 200px margin) its chunk is warmed once; links added later by client
  * navigation are picked up via a MutationObserver. Called by {@link mount}; runs once per app.
  */
 export function startPrefetcher(routes: RouteDef[]): void {