hono-preact 0.4.0 → 0.5.0

package/dist/iso/define-routes.d.ts

@@ -51,7 +51,6 @@ export type RoutesManifest = {
 export declare function defineRoutes(tree: RouteDef[]): RoutesManifest;
 export type RoutesProps = {
     routes: RoutesManifest;
-    onRouteChange?: (url: string) => void;
 };
 export declare const Routes: ComponentType<RoutesProps>;
 export {};

package/dist/iso/define-routes.js

@@ -1,6 +1,7 @@
 import { h } from 'preact';
 import { lazy, Route, Router, useLocation } from 'preact-iso';
 import { RouteLocationsProvider } from './internal/route-locations.js';
+import { __noteLoadEnd, __noteLoadStart } from './internal/route-change.js';
 function wrapWithRouteLocations(serverMod, location, node) {
     const moduleKey = serverMod
         ?.__moduleKey;
@@ -158,7 +159,10 @@ function makeLayoutGroupComponent(layoutImport, server, layoutPathPattern, child
         const inner = buildInnerRoutes(children, viewCache);
         const Wrapper = (location) => {
             const layoutLocation = deriveLayoutLocation(location, layoutPathPattern);
-            const layoutNode = h(Layout, null, h(Router, null, ...inner));
+            const layoutNode = h(Layout, null, h(asRouteComponent(Router), {
+                onLoadStart: __noteLoadStart,
+                onLoadEnd: __noteLoadEnd,
+            }, ...inner));
             return wrapWithRouteLocations(serverMod, layoutLocation, layoutNode);
         };
         return { default: Wrapper };
@@ -276,8 +280,11 @@ export function defineRoutes(tree) {
         serverRoutes: collectServerRoutes(tree),
     };
 }
-export const Routes = ({ routes, onRouteChange, }) => {
-    return h(asRouteComponent(Router), onRouteChange ? { onRouteChange } : null, ...routes.flat.map((r) => h(Route, {
+export const Routes = ({ routes }) => {
+    return h(asRouteComponent(Router), {
+        onLoadStart: __noteLoadStart,
+        onLoadEnd: __noteLoadEnd,
+    }, ...routes.flat.map((r) => h(Route, {
         key: r.key,
         path: r.path,
         component: asRouteComponent(r.component),

package/dist/iso/form.js

@@ -34,6 +34,12 @@ export function Form({ action, children, ...rest }) {
             ? window.location.pathname + window.location.search
             : '/';
         const fd = new FormData(formEl);
+        // Source the action identity from props, not the DOM hidden inputs. On an
+        // initial SSR page those inputs render empty (server-side defineAction
+        // carries no name metadata) and Preact's hydrate() does not patch their
+        // values, so reading them back would post __module/__action='' and 404.
+        fd.set('__module', moduleKey);
+        fd.set('__action', actionName);
         const payload = collectFormData(fd);
         let handle;
         if (optimistic)

package/dist/iso/index.d.ts

@@ -38,7 +38,7 @@ export type { HeadProps } from './head.js';
 export { ClientScript } from './client-script.js';
 export { useViewTransitionLifecycle, type ViewTransitionLifecycle, type ViewTransitionPhaseCallback, } from './view-transition-lifecycle.js';
 export type { ViewTransitionEvent, NavDirection, ViewTransitionReason, } from './internal/view-transition-event.js';
-export { useViewTransitionTypes, type ViewTransitionTypesInput, type ViewTransitionTypesNav, } from './view-transition-types.js';
+export { useViewTransitionTypes, subscribeViewTransitionTypes, type ViewTransitionTypesInput, type ViewTransitionTypesNav, } from './view-transition-types.js';
 export { getNavDirection as getViewTransitionDirection } from './internal/history-shim.js';
 export { useViewTransitionName, useViewTransitionClass, ViewTransitionName, ViewTransitionGroup, type ViewTransitionNameProps, type ViewTransitionGroupProps, } from './view-transition-name.js';
 export { Persist, PersistHost, type PersistProps } from './persist.js';

package/dist/iso/index.js

@@ -35,7 +35,7 @@ export { ClientScript } from './client-script.js';
 // View transition lifecycle hook.
 export { useViewTransitionLifecycle, } from './view-transition-lifecycle.js';
 // View transitions types.
-export { useViewTransitionTypes, } from './view-transition-types.js';
+export { useViewTransitionTypes, subscribeViewTransitionTypes, } from './view-transition-types.js';
 export { getNavDirection as getViewTransitionDirection } from './internal/history-shim.js';
 // View transition name + group hooks and components.
 export { useViewTransitionName, useViewTransitionClass, ViewTransitionName, ViewTransitionGroup, } from './view-transition-name.js';

package/dist/iso/internal/history-shim.d.ts

@@ -1,6 +1,19 @@
 import type { NavDirection } from './view-transition-event.js';
+export declare function onNavigation(listener: () => void): () => void;
 export declare function installHistoryShim(): void;
 export declare function getNavDirection(): NavDirection;
+/**
+ * True once any client-side navigation (push, replace, or popstate) has
+ * occurred since the page loaded. Before the first navigation the document is
+ * still showing its server-rendered, freshly hydrated route. PageMiddlewareHost
+ * uses this to pick its render strategy: on the initial load it renders the
+ * server children during hydration and applies the client middleware outcome
+ * afterwards (so a Suspense boundary never resolves to non-SSR content
+ * mid-hydration, which would orphan the server route DOM); after a navigation
+ * it suspends on the chain normally. `lastDirection` only ever moves away from
+ * 'initial' (never back), so this is a monotonic "have we navigated yet" flag.
+ */
+export declare function hasClientNavigated(): boolean;
 /** Test-only reset. Do not call from production code. */
 export declare function resetHistoryShimForTesting(): void;
 /** Test-only direction setter. Do not call from production code. */

package/dist/iso/internal/history-shim.js

@@ -1,6 +1,19 @@
 let installed = false;
 let counter = 0;
 let lastDirection = 'initial';
+// Fires synchronously whenever a navigation occurs (pushState / replaceState /
+// popstate), BEFORE the resulting re-render. Lets the view-transition scheduler
+// observe a navigation at navigation time rather than only at render time (which
+// Preact's render batching can coalesce away). See route-change.ts.
+const navListeners = new Set();
+export function onNavigation(listener) {
+    navListeners.add(listener);
+    return () => navListeners.delete(listener);
+}
+function notifyNavigation() {
+    for (const listener of navListeners)
+        listener();
+}
 let originalPush = null;
 let originalReplace = null;
 let popstateListener = null;
@@ -28,6 +41,7 @@ export function installHistoryShim() {
         };
         originalPush(merged, title, url);
         lastDirection = 'push';
+        notifyNavigation();
     };
     history.replaceState = function patchedReplace(state, title, url) {
         const merged = {
@@ -36,12 +50,14 @@ export function installHistoryShim() {
         };
         originalReplace(merged, title, url);
         lastDirection = 'replace';
+        notifyNavigation();
     };
     popstateListener = (e) => {
         const incoming = e.state?.__hpVtIdx ?? 0;
         lastDirection =
             incoming < counter ? 'back' : incoming > counter ? 'forward' : 'replace';
         counter = incoming;
+        notifyNavigation();
     };
     window.addEventListener('popstate', popstateListener, { capture: true });
     // Stamp the current entry so subsequent diffs are well-defined.
@@ -52,6 +68,20 @@ export function installHistoryShim() {
 export function getNavDirection() {
     return lastDirection;
 }
+/**
+ * True once any client-side navigation (push, replace, or popstate) has
+ * occurred since the page loaded. Before the first navigation the document is
+ * still showing its server-rendered, freshly hydrated route. PageMiddlewareHost
+ * uses this to pick its render strategy: on the initial load it renders the
+ * server children during hydration and applies the client middleware outcome
+ * afterwards (so a Suspense boundary never resolves to non-SSR content
+ * mid-hydration, which would orphan the server route DOM); after a navigation
+ * it suspends on the chain normally. `lastDirection` only ever moves away from
+ * 'initial' (never back), so this is a monotonic "have we navigated yet" flag.
+ */
+export function hasClientNavigated() {
+    return lastDirection !== 'initial';
+}
 /** Test-only reset. Do not call from production code. */
 export function resetHistoryShimForTesting() {
     if (installed &&
@@ -72,6 +102,7 @@ export function resetHistoryShimForTesting() {
     originalPush = null;
     originalReplace = null;
     popstateListener = null;
+    navListeners.clear();
 }
 /** Test-only direction setter. Do not call from production code. */
 export function setNavDirectionForTesting(dir) {

package/dist/iso/internal/page-middleware-host.js

@@ -1,12 +1,13 @@
 import { Fragment as _Fragment, jsx as _jsx } from "preact/jsx-runtime";
 import { useLocation } from 'preact-iso';
 import { Suspense } from 'preact/compat';
-import { useContext, useEffect, useRef } from 'preact/hooks';
+import { useContext, useEffect, useRef, useState } from 'preact/hooks';
 import { isBrowser } from '../is-browser.js';
 import { isRedirect, isRender } from '../outcomes.js';
 import { dispatchServer, dispatchClient } from './middleware-runner.js';
 import { partitionUse } from './use-partitioner.js';
 import wrapPromise from './wrap-promise.js';
+import { hasClientNavigated } from './history-shim.js';
 import { HonoRequestContext } from './contexts.js';
 function startChain(use, location, honoCtx) {
     const { middleware } = partitionUse(use);
@@ -44,68 +45,147 @@ function startChain(use, location, honoCtx) {
         inner: async () => undefined,
     }).then((r) => r.kind === 'outcome' ? { outcome: r.outcome } : { outcome: undefined });
 }
-function HostConsumer({ resultRef, children, }) {
-    // resultRef.current is populated by the parent before this consumer
-    // renders; the null branch is just a type-narrow guard.
-    const wrapped = resultRef.current;
-    const { outcome } = wrapped ? wrapped.read() : { outcome: undefined };
-    const { route } = useLocation();
-    // Client-side redirect: navigate in an effect rather than during render.
-    // Render-time side effects are forbidden by Suspense semantics; doing
-    // route() in render would also fire on every Preact re-entry during
-    // suspension resume. Keyed on the resolved target so a fresh outcome
-    // for the same path doesn't refire (the outcome is cached per chain,
-    // so this only changes when the path itself changes and a new chain
-    // produces a redirect to a different target).
-    const redirectTo = isRedirect(outcome) && isBrowser() ? outcome.to : null;
-    useEffect(() => {
-        if (redirectTo !== null)
-            route(redirectTo);
-        // `route` is intentionally omitted from deps: it comes from
-        // useLocation() which is stable per LocationProvider mount, and
-        // referencing it here would re-fire the effect on every render the
-        // provider produces.
-    }, [redirectTo]);
+/**
+ * Applies a settled host outcome to the rendered tree. Shared rendering logic
+ * for both host strategies (Suspense and Deferred).
+ */
+function renderOutcome(outcome, children) {
     if (outcome === undefined) {
         return _jsx(_Fragment, { children: children });
     }
     if (isRedirect(outcome)) {
         if (isBrowser()) {
-            // Effect above will schedule the navigation; render nothing in the
-            // meantime so the old tree doesn't briefly flash.
+            // The navigation is scheduled in an effect; render nothing meanwhile so
+            // the old tree doesn't briefly flash.
             return null;
         }
-        // Server: rethrow so renderPage's outer handler can translate to HTTP redirect.
+        // Server: rethrow so renderPage's outer handler can translate to an HTTP redirect.
         throw outcome;
     }
     if (isRender(outcome)) {
         const Alt = outcome.Component;
-        // Equality-by-reference semantics: each `render(Component)` call
-        // returns a fresh outcome object, but the wrapped chain caches its
-        // result for the lifetime of a path. Within the same path render
-        // outcomes are stable. Across paths, the `resultRef` is rewrapped
-        // (see PageMiddlewareHost below), so a fresh chain produces a fresh
-        // outcome and Preact remounts naturally when `Alt` differs. If a
-        // middleware returns the SAME component reference across paths,
-        // Preact treats it as the same element and preserves state. That's
-        // the documented semantic; if callers need a forced remount, they
-        // can wrap the returned component or vary props.
+        // Equality-by-reference semantics: each `render(Component)` call returns a
+        // fresh outcome object, but the wrapped chain caches its result for the
+        // lifetime of a path. Within the same path render outcomes are stable.
+        // Across paths the chain is re-dispatched, so a fresh chain produces a
+        // fresh outcome and Preact remounts naturally when `Alt` differs. If a
+        // middleware returns the SAME component reference across paths, Preact
+        // treats it as the same element and preserves state. That's the documented
+        // semantic; callers needing a forced remount can wrap the component or vary
+        // props.
         return _jsx(Alt, {});
     }
     // Deny on the page-render path: rethrow so the outer error boundary or
     // handler can translate to the right response.
     throw outcome;
 }
-export const PageMiddlewareHost = ({ use = [], location, fallback, children }) => {
-    const honoCtx = useContext(HonoRequestContext).context;
+/**
+ * Suspense strategy: suspend on the middleware chain and render its outcome.
+ * Used for SSR (prerender awaits the suspension) and for post-navigation client
+ * renders (no hydration to mismatch, a fallback is fine while the chain runs).
+ */
+function HostConsumer({ resultRef, children, }) {
+    // resultRef.current is populated by the parent before this consumer
+    // renders; the null branch is just a type-narrow guard.
+    const wrapped = resultRef.current;
+    const { outcome } = wrapped ? wrapped.read() : { outcome: undefined };
+    const { route } = useLocation();
+    // Client-side redirect: navigate in an effect rather than during render
+    // (render-time side effects are forbidden by Suspense semantics, and route()
+    // in render would also re-fire on every Preact re-entry during suspension
+    // resume). Keyed on the resolved target so a fresh outcome for the same path
+    // doesn't refire.
+    const redirectTo = isRedirect(outcome) && isBrowser() ? outcome.to : null;
+    useEffect(() => {
+        if (redirectTo === null)
+            return;
+        // A plain SPA route() is correct here. This consumer only runs on the
+        // server (where the redirect outcome is thrown above, not routed) and for
+        // post-navigation client renders; initial-load redirects are handled by
+        // DeferredHost, which renders the SSR content during hydration so there is
+        // no server-committed tree for the Router to orphan. (The
+        // orphan-on-hydration-mismatch is expected Preact behavior, see
+        // preactjs/preact#4442.)
+        route(redirectTo);
+        // `route` is intentionally omitted from deps: it comes from useLocation()
+        // which is stable per LocationProvider mount, and referencing it here would
+        // re-fire the effect on every render the provider produces.
+    }, [redirectTo]);
+    return renderOutcome(outcome, children);
+}
+/**
+ * Deferred strategy: used on the INITIAL document load (browser, before any
+ * client navigation). Renders the server-rendered children during hydration so
+ * the hydrated DOM matches SSR, then runs the client chain post-hydration and
+ * applies its outcome as a normal update. This avoids a Suspense boundary
+ * resolving to non-SSR content mid-hydration, which orphans the server route
+ * DOM (expected Preact behavior, preactjs/preact#4442) and stacks the redirect
+ * target on top (the "client redirect double-mount").
+ *
+ * Timing contract: on the initial load the client middleware runs AFTER
+ * hydration (in the effect), not before first paint. The server already
+ * authorized and rendered this content, so a client guard is advisory here and
+ * applies once hydrated; anything it would redirect away from is already on
+ * screen from SSR, so deferring exposes nothing new. Post-navigation renders
+ * take SuspenseHost, where the chain blocks the render as before.
+ *
+ * Known limitation: this matches the COMMON case where the server passed and
+ * rendered `children`. If a SERVER middleware instead rendered an alternative
+ * (so SSR markup != children) and the client produces no matching outcome, the
+ * client still renders `children` and the SSR/client mismatch is on the user -
+ * the framework does not transmit the server outcome to the client. This is
+ * pre-existing (it predates the deferred strategy) and out of scope here.
+ */
+function DeferredHost({ use, location, honoCtx, children, }) {
+    const { route } = useLocation();
+    // null = chain not yet settled, or settled to a redirect/pass: keep rendering
+    // the server children. A settled render()/deny outcome is stored so it can be
+    // swapped in via a normal post-hydration update.
+    const [applied, setApplied] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        // Reset to the server children before re-dispatching, so a stale render()
+        // outcome from a previous path cannot linger if this host is ever reused
+        // across a path change (in practice it only handles the initial load, but
+        // a persisted layout host could in principle see location.path change).
+        setApplied(null);
+        startChain(use, location, honoCtx).then((result) => {
+            if (cancelled)
+                return;
+            if (isRedirect(result.outcome)) {
+                // SPA navigate from the fully hydrated tree. Because the server's
+                // content (not null) was rendered during hydration, there is no
+                // orphaned route DOM for the Router to stack the target on top of.
+                route(result.outcome.to);
+            }
+            else if (result.outcome !== undefined) {
+                // render() / deny: surface after hydration via a normal update.
+                setApplied(result);
+            }
+            // undefined (chain passed): keep the already-rendered children.
+        });
+        return () => {
+            cancelled = true;
+        };
+        // Re-dispatch if the path changes (mirrors SuspenseHost's per-path dispatch).
+    }, [location.path]);
+    if (applied === null)
+        return _jsx(_Fragment, { children: children });
+    return renderOutcome(applied.outcome, children);
+}
+/**
+ * Suspense strategy wrapper. Lazily dispatches the chain once per path (see the
+ * lazy-ref note below) and renders the outcome through HostConsumer.
+ */
+function SuspenseHost({ use, location, honoCtx, fallback, children, }) {
     // Lazy ref pattern. `useRef(null)` serves a dual purpose: it's the
-    // "not-yet-computed" sentinel AND the persistent slot for the wrapped
-    // chain result. We compute on first render and on subsequent renders
-    // ONLY when the path changed. `useRef(wrapPromise(startChain(...)))`
-    // would evaluate `startChain` every render before useRef decided whether
-    // to keep it, which synchronously fires `dispatchServer`/`dispatchClient`
-    // every render. That's O(renders) middleware invocations instead of
-    // O(navigations); auth checks, analytics, redirects would all repeat.
+    // "not-yet-computed" sentinel AND the persistent slot for the wrapped chain
+    // result. We compute on first render and on subsequent renders ONLY when the
+    // path changed. `useRef(wrapPromise(startChain(...)))` would evaluate
+    // `startChain` every render before useRef decided whether to keep it, which
+    // synchronously fires `dispatchServer`/`dispatchClient` every render. That's
+    // O(renders) middleware invocations instead of O(navigations); auth checks,
+    // analytics, redirects would all repeat.
     const resultRef = useRef(null);
     const prevPath = useRef(location.path);
     if (resultRef.current === null) {
@@ -116,4 +196,27 @@ export const PageMiddlewareHost = ({ use = [], location, fallback, children }) =
         resultRef.current = wrapPromise(startChain(use, location, honoCtx));
     }
     return (_jsx(Suspense, { fallback: fallback, children: _jsx(HostConsumer, { resultRef: resultRef, children: children }) }));
+}
+export const PageMiddlewareHost = ({ use = [], location, fallback, children }) => {
+    const honoCtx = useContext(HonoRequestContext).context;
+    // Choose the render strategy ONCE per mount so the hook order stays stable
+    // across renders (hasClientNavigated() flips to true after the first
+    // navigation, which would otherwise change which child - and its hooks - we
+    // render).
+    //
+    // Initial document load (browser, no navigation yet) -> DeferredHost: a
+    // Suspense boundary that suspends during hydration and resolves to non-SSR
+    // content (e.g. null for a redirect) orphans the server-rendered route DOM
+    // (expected Preact behavior, preactjs/preact#4442), which the Router then
+    // stacks the redirect target on top of. Rendering the server children during
+    // hydration and applying the client outcome afterwards removes that mismatch.
+    //
+    // Server render and post-navigation client renders have no hydration to
+    // mismatch, so the Suspense path (suspend on the chain, render the outcome)
+    // is correct there.
+    const deferRef = useRef(isBrowser() && !hasClientNavigated());
+    if (deferRef.current) {
+        return (_jsx(DeferredHost, { use: use, location: location, honoCtx: honoCtx, children: children }));
+    }
+    return (_jsx(SuspenseHost, { use: use, location: location, honoCtx: honoCtx, fallback: fallback, children: children }));
 };

package/dist/iso/internal/route-change.d.ts

@@ -4,6 +4,23 @@ type PhaseSub = (event: ViewTransitionEvent) => void | Promise<void>;
 type LegacySub = (to: string, from: string | undefined) => void;
 export declare function __subscribePhase(phase: PhaseName, sub: PhaseSub): () => void;
 export declare function __subscribeRouteChange(sub: LegacySub): () => void;
+export declare function __noteLoadStart(): void;
+export declare function __noteLoadEnd(): void;
+/** @internal Test-only reset for coordinator state. */
+export declare function __resetTransitionStateForTesting(): void;
+/**
+ * @internal Install the view-transition render scheduler (client only).
+ *
+ * Takes ownership of `options.debounceRendering`: it captures the previous value
+ * as `prevDebounce` (delegated to for every non-navigation flush) and installs
+ * `scheduleRender` in its place. This assumes nothing else permanently overrides
+ * `options.debounceRendering` afterward. `preact/compat`'s `flushSync` swaps it
+ * temporarily and restores it, so that composes fine; a second permanent
+ * override would shadow this scheduler (the install is idempotent, so calling it
+ * twice is a no-op, not a double-install). Reversed by
+ * `__resetTransitionStateForTesting`.
+ */
+export declare function installNavTransitionScheduler(): void;
 export declare function __dispatchRouteChange(to: string, from: string | undefined): void;
 /** @internal Test-only reset for default-types installer. */
 export declare function resetDefaultTypesForTesting(): void;

package/dist/iso/internal/route-change.js

@@ -1,6 +1,6 @@
-import { flushSync } from 'preact/compat';
+import { options } from 'preact';
 import { ViewTransitionEvent, } from './view-transition-event.js';
-import { getNavDirection } from './history-shim.js';
+import { getNavDirection, onNavigation } from './history-shim.js';
 const phaseSubs = {
     beforeTransition: new Set(),
     beforeSwap: new Set(),
@@ -30,71 +30,377 @@ function getStartViewTransition() {
     const fn = document.startViewTransition;
     return typeof fn === 'function' ? fn.bind(document) : undefined;
 }
-export function __dispatchRouteChange(to, from) {
+function currentPath() {
+    return typeof location !== 'undefined'
+        ? location.pathname + location.search
+        : '';
+}
+// `loadingDepth`: how many Routers are mid-suspense (via onLoadStart/onLoadEnd).
+// Read right after a navigation commits to tell whether the route suspended (a
+// cold navigation), so the transition can wait for the suspended content.
+let loadingDepth = 0;
+export function __noteLoadStart() {
+    loadingDepth++;
+}
+export function __noteLoadEnd() {
+    loadingDepth = Math.max(0, loadingDepth - 1);
+}
+// The path the app is currently on (the previous navigation's `to`); seeds
+// `from` for the first navigation. A server render leaves it undefined.
+let lastPath = typeof location !== 'undefined'
+    ? location.pathname + location.search
+    : undefined;
+// Cold-navigation state: a navigation's transition holds until the suspending
+// route's content flushes have all run (see the scheduler below).
+let coldTimeout = null;
+// Bumped per navigation so a superseded transition's (async) callback bows out.
+let navGen = 0;
+// Cap on how long a navigation holds the old snapshot waiting for a suspending
+// route's content. Past it the navigation completes without finishing the
+// transition rather than freezing the page on a slow/stalled load.
+const COLD_COMMIT_TIMEOUT_MS = 500;
+// Extra grace, after the shell is ready, to let a morph partner that loads with
+// the route's DATA (behind inner Suspense, which doesn't move loadingDepth)
+// appear in the new snapshot before the transition captures it.
+const MORPH_PARTNER_GRACE_MS = 150;
+/** @internal Test-only reset for coordinator state. */
+export function __resetTransitionStateForTesting() {
+    loadingDepth = 0;
+    navGen = 0;
+    lastPath =
+        typeof location !== 'undefined'
+            ? location.pathname + location.search
+            : undefined;
+    coldRouteSignal = null;
+    if (coldTimeout !== null) {
+        clearTimeout(coldTimeout);
+        coldTimeout = null;
+    }
+    transitionActive = false;
+    // Uninstall the render scheduler (restoring Preact's debounceRendering) so
+    // each test can install it fresh.
+    if (schedulerInstalled) {
+        options.debounceRendering = prevDebounce;
+        schedulerInstalled = false;
+        prevDebounce = undefined;
+        if (unsubscribeNav) {
+            unsubscribeNav();
+            unsubscribeNav = null;
+        }
+    }
+}
+function fireAfterSwap(event) {
+    for (const sub of phaseSubs.afterSwap)
+        sub(event);
+    // Legacy subscribers fire at the afterSwap slot: after the DOM swap, before
+    // the browser begins animating the new frame.
+    fireLegacy(event.to, event.from);
+}
+function fireAfterTransition(event, reason) {
+    if (reason !== undefined)
+        event.reason = reason;
+    for (const sub of phaseSubs.afterTransition)
+        sub(event);
+}
+function applyTypes(transition, types) {
+    const vtTypes = transition.types;
+    if (vtTypes && typeof vtTypes.add === 'function') {
+        for (const t of types)
+            vtTypes.add(t);
+    }
+}
+function skipTransition(transition) {
+    const t = transition;
+    if (typeof t.skipTransition === 'function')
+        t.skipTransition();
+}
+// Build the event for a navigation that has just committed: `to`/`direction`
+// are only correct after the commit (pushState updates the history shim), so
+// this is always called post-commit. Advances `lastPath`.
+function buildEvent(from) {
     ensureDefaultTypes();
+    const to = currentPath();
+    lastPath = to;
     const direction = getNavDirection();
     const event = new ViewTransitionEvent({ to, from, direction });
     for (const sub of phaseSubs.beforeTransition)
         sub(event);
-    const fireAfterSwap = () => {
-        for (const sub of phaseSubs.afterSwap)
-            sub(event);
-        // Legacy subscribers fire at the afterSwap slot: after the DOM swap,
-        // before the browser begins animating the new frame.
-        fireLegacy(to, from);
-    };
-    const fireAfterTransition = (reason) => {
-        if (reason !== undefined)
-            event.reason = reason;
-        for (const sub of phaseSubs.afterTransition)
-            sub(event);
-    };
-    if (event._skipped) {
-        flushSync(() => { });
-        fireAfterSwap();
-        fireAfterTransition('skipped');
+    return event;
+}
+let schedulerInstalled = false;
+let lastHref = '';
+let prevDebounce;
+let unsubscribeNav = null;
+// True while a navigation's transition is in flight (its callback is pending or
+// awaiting cold content). Lets the navigation observer abandon it.
+let transitionActive = false;
+// Set while a cold navigation's transition awaits a content flush; the next
+// same-URL flush hands its `process` here (or `null` on supersede/timeout) so
+// the transition can run it inside itself.
+let coldRouteSignal = null;
+function defaultSchedule(process) {
+    if (prevDebounce)
+        prevDebounce(process);
+    else
+        Promise.resolve().then(process);
+}
+// Fired (via the history shim) at navigation time, before the re-render. If a
+// transition from a previous navigation is still in flight, abandon it here:
+// Preact may coalesce the new navigation's render into the in-flight one, so
+// scheduleRender never sees it and its own supersede branch can't fire.
+function onNavObserved() {
+    if (!transitionActive && !coldRouteSignal)
         return;
+    navGen++; // the in-flight callback bows out at its next navGen check
+    transitionActive = false;
+    if (coldRouteSignal) {
+        const resolve = coldRouteSignal;
+        coldRouteSignal = null;
+        if (coldTimeout !== null) {
+            clearTimeout(coldTimeout);
+            coldTimeout = null;
+        }
+        resolve(null);
     }
-    const start = getStartViewTransition();
+}
+/**
+ * @internal Install the view-transition render scheduler (client only).
+ *
+ * Takes ownership of `options.debounceRendering`: it captures the previous value
+ * as `prevDebounce` (delegated to for every non-navigation flush) and installs
+ * `scheduleRender` in its place. This assumes nothing else permanently overrides
+ * `options.debounceRendering` afterward. `preact/compat`'s `flushSync` swaps it
+ * temporarily and restores it, so that composes fine; a second permanent
+ * override would shadow this scheduler (the install is idempotent, so calling it
+ * twice is a no-op, not a double-install). Reversed by
+ * `__resetTransitionStateForTesting`.
+ */
+export function installNavTransitionScheduler() {
+    if (schedulerInstalled)
+        return;
+    if (typeof document === 'undefined' || typeof location === 'undefined')
+        return;
+    schedulerInstalled = true;
+    lastHref = location.href;
+    prevDebounce = options.debounceRendering;
+    options.debounceRendering = scheduleRender;
+    unsubscribeNav = onNavigation(onNavObserved);
+}
+function scheduleRender(process) {
+    const href = location.href;
+    const navigated = href !== lastHref;
+    // The content flush for an in-flight cold navigation (same URL): hand it back
+    // to that transition so it lands in the new snapshot.
+    if (coldRouteSignal && !navigated) {
+        const resolve = coldRouteSignal;
+        coldRouteSignal = null;
+        if (coldTimeout !== null) {
+            clearTimeout(coldTimeout);
+            coldTimeout = null;
+        }
+        resolve(process); // the transition's callback runs `process()` itself
+        return;
+    }
+    // A new navigation arrived while a cold one was still loading: abandon it.
+    if (coldRouteSignal && navigated) {
+        navGen++;
+        const resolve = coldRouteSignal;
+        coldRouteSignal = null;
+        if (coldTimeout !== null) {
+            clearTimeout(coldTimeout);
+            coldTimeout = null;
+        }
+        resolve(null);
+    }
+    if (navigated) {
+        // Reset the load counter at the start of a navigation. A previous route's
+        // loads are abandoned by a new navigation, and preact-iso fires onLoadStart
+        // without a matching onLoadEnd when a still-suspended Router unmounts (it
+        // emits onLoadEnd only on a committed render, not on unmount). Left alone,
+        // that leaked depth would make this nav (and later ones) look perpetually
+        // cold and burn the cold-load timeout. This nav re-increments it as its own
+        // route suspends.
+        loadingDepth = 0;
+    }
+    lastHref = href;
+    const start = navigated ? getStartViewTransition() : undefined;
     if (!start) {
-        flushSync(() => { });
-        fireAfterSwap();
-        fireAfterTransition('unsupported');
+        defaultSchedule(process);
         return;
     }
-    const transition = start(() => {
-        flushSync(() => { });
+    runNavTransition(process, start);
+}
+// Wait for the next content flush of an in-flight cold navigation (routed here
+// by scheduleRender), or null on timeout/supersede.
+function waitForColdFlush(myGen, timeoutMs) {
+    return new Promise((resolve) => {
+        coldRouteSignal = resolve;
+        coldTimeout = setTimeout(() => {
+            if (navGen === myGen && coldRouteSignal) {
+                coldRouteSignal = null;
+                coldTimeout = null;
+                resolve(null);
+            }
+        }, timeoutMs);
+    });
+}
+// Elements carrying an inline `view-transition-name`. The attribute selector
+// lets the browser filter natively instead of walking every node in JS — this
+// runs on the frozen hot path (inside the transition callback, possibly once per
+// grace tick), so the candidate set should be as small as possible. The selector
+// is a substring match on the serialized `style` attribute, so we still confirm
+// each match by reading the resolved property below.
+function queryVtNamedElements() {
+    if (typeof document === 'undefined' || !document.querySelectorAll)
+        return [];
+    return Array.from(document.querySelectorAll('[style*="view-transition-name"]'));
+}
+// The view-transition-names currently applied in the document (inline styles).
+function collectVtNames() {
+    const names = new Set();
+    for (const el of queryVtNamedElements()) {
+        const n = el.style?.getPropertyValue?.('view-transition-name');
+        if (n)
+            names.add(n);
+    }
+    return names;
+}
+// Whether any currently-applied view-transition-name was also in `oldNames` —
+// i.e. a morph pair (same name old + new) is present.
+function hasMorphPartner(oldNames) {
+    if (oldNames.size === 0)
+        return false;
+    for (const el of queryVtNamedElements()) {
+        const n = el.style?.getPropertyValue?.('view-transition-name');
+        if (n && oldNames.has(n))
+            return true;
+    }
+    return false;
+}
+function runNavTransition(process, start) {
+    const from = lastPath;
+    // The names present in the outgoing route — used to know when a morph partner
+    // has appeared in the new route (see the grace wait below).
+    const oldNames = collectVtNames();
+    const myGen = ++navGen;
+    transitionActive = true;
+    let transition;
+    let event;
+    try {
+        transition = start(async () => {
+            // The old snapshot has been captured. Flush the navigation render.
+            process();
+            if (navGen !== myGen)
+                return;
+            event = buildEvent(from);
+            event.transition = transition;
+            applyTypes(transition, event.types);
+            if (event._skipped) {
+                skipTransition(transition);
+            }
+            else {
+                for (const sub of phaseSubs.beforeSwap)
+                    sub(event);
+                // Cold: the route suspended. Keep routing its content flushes into the
+                // transition until every route module has loaded (loadingDepth back to
+                // 0) — the page-level shell.
+                while (loadingDepth > 0) {
+                    const contentProcess = await waitForColdFlush(myGen, COLD_COMMIT_TIMEOUT_MS);
+                    if (navGen !== myGen)
+                        return;
+                    if (!contentProcess)
+                        break; // timed out waiting
+                    contentProcess();
+                }
+                // If the outgoing route had named elements but none has a partner in the
+                // new shell yet, the partner may load with the route's DATA (behind
+                // inner Suspense, which doesn't move loadingDepth — e.g. a list whose
+                // items come from a loader). Wait briefly for it so the morph can pair.
+                if (oldNames.size > 0 && !hasMorphPartner(oldNames)) {
+                    while (!hasMorphPartner(oldNames)) {
+                        const contentProcess = await waitForColdFlush(myGen, MORPH_PARTNER_GRACE_MS);
+                        if (navGen !== myGen)
+                            return;
+                        if (!contentProcess)
+                            break; // grace expired — capture as-is
+                        contentProcess();
+                    }
+                }
+            }
+            if (navGen !== myGen)
+                return;
+            fireAfterSwap(event);
+            transitionActive = false; // reached only when still current
+        });
+    }
+    catch {
+        // Non-conformant startViewTransition: just flush and fire the post phases.
+        transitionActive = false;
+        process();
+        const ev = buildEvent(from);
+        fireAfterSwap(ev);
+        fireAfterTransition(ev, 'unsupported');
+        return;
+    }
+    transition.finished.then(() => {
+        if (event)
+            fireAfterTransition(event, event._skipped ? 'skipped' : undefined);
+    }, () => {
+        if (event)
+            fireAfterTransition(event, 'aborted');
+    });
+}
+// Synchronous route-change dispatch for an explicit `to`/`from`: fires
+// `beforeTransition` and runs a transition that wraps a no-op swap (the route is
+// assumed already on screen), firing the post-swap phases and applying types.
+// Production navigations are driven by the scheduler (installNavTransition
+// scheduler); this drives the same phase/type/lifecycle machinery directly for
+// callers that change the route outside the normal navigation flow (and in unit
+// tests).
+export function __dispatchRouteChange(to, from) {
+    ensureDefaultTypes();
+    const event = new ViewTransitionEvent({
+        to,
+        from,
+        direction: getNavDirection(),
     });
-    // Set event.transition before firing beforeSwap so all subsequent phase
-    // subscribers see a non-null transition. In real browsers startViewTransition
-    // invokes the callback asynchronously, meaning transition is set here before
-    // the browser calls the update function. In synchronous test mocks the
-    // callback returns before start() does, so we set transition here (after
-    // start() returns) and then fire the post-swap phases manually.
+    for (const sub of phaseSubs.beforeTransition)
+        sub(event);
+    const start = getStartViewTransition();
+    if (!start || event._skipped) {
+        // No transition runs, so `beforeSwap` (which precedes a real swap) is
+        // skipped; the post-swap phases still fire.
+        fireAfterSwap(event);
+        fireAfterTransition(event, event._skipped ? 'skipped' : 'unsupported');
+        return;
+    }
+    let transition;
+    try {
+        transition = start(() => { });
+    }
+    catch {
+        fireAfterSwap(event);
+        fireAfterTransition(event, 'unsupported');
+        return;
+    }
     event.transition = transition;
+    applyTypes(transition, event.types);
     for (const sub of phaseSubs.beforeSwap)
         sub(event);
-    fireAfterSwap();
-    // Apply types accumulated across all phases. beforeTransition and beforeSwap
-    // have both run by this point, so the full set of types is available here.
-    const vtTypes = transition.types;
-    if (vtTypes && typeof vtTypes.add === 'function') {
-        for (const t of event.types)
-            vtTypes.add(t);
-    }
-    transition.finished.then(() => fireAfterTransition(), () => fireAfterTransition('aborted'));
+    fireAfterSwap(event);
+    transition.finished.then(() => fireAfterTransition(event), () => fireAfterTransition(event, 'aborted'));
 }
 let defaultTypesInstalled = false;
-let firstDispatchSeen = false;
+let firstNavSeen = false;
 let defaultTypeUnsubscriber = null;
 function ensureDefaultTypes() {
     if (defaultTypesInstalled)
         return;
     defaultTypesInstalled = true;
     defaultTypeUnsubscriber = __subscribePhase('beforeTransition', (event) => {
-        if (!firstDispatchSeen) {
+        if (!firstNavSeen) {
             event.types.push('nav-initial');
-            firstDispatchSeen = true;
+            firstNavSeen = true;
         }
         else {
             event.types.push(`nav-${event.direction}`);
@@ -108,6 +414,6 @@ export function resetDefaultTypesForTesting() {
         defaultTypeUnsubscriber();
     }
     defaultTypesInstalled = false;
-    firstDispatchSeen = false;
+    firstNavSeen = false;
     defaultTypeUnsubscriber = null;
 }

package/dist/iso/internal.d.ts

@@ -11,7 +11,7 @@ export { runRequestScope, getRequestStore, captureRequestScope, getActionResultS
 export { default as wrapPromise } from './internal/wrap-promise.js';
 export { HonoRequestContext } from './internal/contexts.js';
 export { PageMiddlewareHost } from './internal/page-middleware-host.js';
-export { __dispatchRouteChange, __subscribeRouteChange, } from './internal/route-change.js';
+export { installNavTransitionScheduler, __subscribeRouteChange, } from './internal/route-change.js';
 export { installHistoryShim, getNavDirection, } from './internal/history-shim.js';
 export { __subscribePhase, type PhaseName } from './internal/route-change.js';
 export { ViewTransitionEvent, type NavDirection, type ViewTransitionReason, } from './internal/view-transition-event.js';

package/dist/iso/internal.js

@@ -37,7 +37,7 @@ export { runRequestScope, getRequestStore, captureRequestScope, getActionResultS
 export { default as wrapPromise } from './internal/wrap-promise.js';
 export { HonoRequestContext } from './internal/contexts.js';
 export { PageMiddlewareHost } from './internal/page-middleware-host.js';
-export { __dispatchRouteChange, __subscribeRouteChange, } from './internal/route-change.js';
+export { installNavTransitionScheduler, __subscribeRouteChange, } from './internal/route-change.js';
 export { installHistoryShim, getNavDirection, } from './internal/history-shim.js';
 export { __subscribePhase } from './internal/route-change.js';
 export { ViewTransitionEvent, } from './internal/view-transition-event.js';

package/dist/iso/view-transition-types.d.ts

@@ -5,4 +5,15 @@ export interface ViewTransitionTypesNav {
     direction: NavDirection;
 }
 export type ViewTransitionTypesInput = string | string[] | ((nav: ViewTransitionTypesNav) => string | string[] | null | undefined);
+/**
+ * Register a global, route-aware view-transition type rule. The resolver runs on
+ * every navigation with `{ to, from, direction }` and returns the type(s) to add
+ * to that navigation's transition (a static string/array adds the same type(s) to
+ * every navigation). Returns an unsubscribe.
+ *
+ * Unlike {@link useViewTransitionTypes}, this is not tied to a mounted component,
+ * so it covers entering AND leaving a section (a layout hook is not subscribed yet
+ * on enter and is already torn down on leave). No-op on the server (no document).
+ */
+export declare function subscribeViewTransitionTypes(input: ViewTransitionTypesInput): () => void;
 export declare function useViewTransitionTypes(input: ViewTransitionTypesInput): void;

package/dist/iso/view-transition-types.js

@@ -1,21 +1,36 @@
 import { useEffect, useRef } from 'preact/hooks';
 import { __subscribePhase } from './internal/route-change.js';
+/**
+ * Register a global, route-aware view-transition type rule. The resolver runs on
+ * every navigation with `{ to, from, direction }` and returns the type(s) to add
+ * to that navigation's transition (a static string/array adds the same type(s) to
+ * every navigation). Returns an unsubscribe.
+ *
+ * Unlike {@link useViewTransitionTypes}, this is not tied to a mounted component,
+ * so it covers entering AND leaving a section (a layout hook is not subscribed yet
+ * on enter and is already torn down on leave). No-op on the server (no document).
+ */
+export function subscribeViewTransitionTypes(input) {
+    if (typeof document === 'undefined')
+        return () => { };
+    return __subscribePhase('beforeTransition', (event) => {
+        const resolved = typeof input === 'function'
+            ? input({ to: event.to, from: event.from, direction: event.direction })
+            : input;
+        if (resolved == null)
+            return;
+        if (typeof resolved === 'string')
+            event.types.push(resolved);
+        else
+            for (const t of resolved)
+                event.types.push(t);
+    });
+}
 export function useViewTransitionTypes(input) {
     const ref = useRef(input);
     ref.current = input;
-    useEffect(() => {
-        return __subscribePhase('beforeTransition', (event) => {
-            const v = ref.current;
-            const resolved = typeof v === 'function'
-                ? v({ to: event.to, from: event.from, direction: event.direction })
-                : v;
-            if (resolved == null)
-                return;
-            if (typeof resolved === 'string')
-                event.types.push(resolved);
-            else
-                for (const t of resolved)
-                    event.types.push(t);
-        });
-    }, []);
+    useEffect(() => subscribeViewTransitionTypes((nav) => {
+        const v = ref.current;
+        return typeof v === 'function' ? v(nav) : v;
+    }), []);
 }

package/dist/vite/client-entry.js

@@ -5,10 +5,11 @@ export function generateClientEntrySource(opts) {
     return (`import { h, hydrate, render as renderPreact } from 'preact';\n` +
         `import { LocationProvider } from 'preact-iso';\n` +
         `import { Routes, PersistHost } from 'hono-preact';\n` +
-        `import { __dispatchRouteChange, installStreamRegistry, installHistoryShim } from 'hono-preact/internal';\n` +
+        `import { installNavTransitionScheduler, installStreamRegistry, installHistoryShim } from 'hono-preact/internal';\n` +
         `import routes from '${opts.routesAbsPath}';\n` +
         `\n` +
         `installHistoryShim();\n` +
+        `installNavTransitionScheduler();\n` +
         `installStreamRegistry();\n` +
         `\n` +
         `let persistHost = document.getElementById('__hp_persist_root');\n` +
@@ -19,16 +20,13 @@ export function generateClientEntrySource(opts) {
         `}\n` +
         `renderPreact(h(PersistHost, null), persistHost);\n` +
         `\n` +
-        `let lastPath;\n` +
-        `function onRouteChange(path) {\n` +
-        `  const from = lastPath;\n` +
-        `  lastPath = path;\n` +
-        `  __dispatchRouteChange(path, from);\n` +
-        `}\n` +
-        `\n` +
+        // View transitions are driven by installNavTransitionScheduler() above: it
+        // overrides Preact's render scheduler so a navigation's re-render runs inside
+        // document.startViewTransition (capturing the outgoing route as the old
+        // snapshot before the new one swaps in). No per-navigation wiring needed.
         `hydrate(\n` +
         `  h(LocationProvider, null,\n` +
-        `    h(Routes, { routes, onRouteChange })\n` +
+        `    h(Routes, { routes })\n` +
         `  ),\n` +
         `  document.getElementById('app')\n` +
         `);\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-preact",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Hono on the edge, Preact in the browser, manifest driven routes, typed RPC, streaming everywhere.",
   "keywords": [
     "hono",
@@ -95,8 +95,8 @@
   },
   "devDependencies": {
     "typescript": "*",
-    "@hono-preact/server": "0.1.0",
     "@hono-preact/iso": "0.1.0",
+    "@hono-preact/server": "0.1.0",
     "@hono-preact/vite": "0.1.0"
   },
   "scripts": {