npm - rwsdk - Versions diffs - 1.3.0-canary.7 → 1.3.1 - Mend

rwsdk 1.3.0-canary.7 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (85) hide show

package/dist/runtime/client/recovery.d.ts ADDED Viewed

@@ -0,0 +1,17 @@
+export type RecoveryState = "idle" | "waiting" | "checking" | "reload";
+export type RecoveryController = {
+    readonly state: RecoveryState;
+    readonly attempts: number;
+    readonly elapsedMs: number;
+    retry(): void;
+    reload(): void;
+};
+export type RecoveryCallback = (controller: RecoveryController) => void | Promise<void>;
+export type RecoveryHandler = "reloadWhenReady" | RecoveryCallback;
+export type RecoveryOptions = {
+    onModuleNotFound?: RecoveryHandler;
+};
+export declare function configureRecovery(options: RecoveryOptions): void;
+export declare function isRecoveryConfigured(): boolean;
+export declare function startRecovery(reason: "module-not-found"): void;
+export declare function isDynamicImportFailure(error: unknown): boolean;

package/dist/runtime/client/recovery.js ADDED Viewed

@@ -0,0 +1,191 @@
+const DEFAULT_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30000;
+const FALLBACK_TIMEOUT_MS = 30000;
+const FALLBACK_TIMEOUT_JITTER_MS = 10000;
+const STARTUP_JITTER_MS = 1000;
+let configuredOptions = {};
+let activeController = null;
+function debugLog(...args) {
+    if (typeof window !== "undefined" &&
+        (window.__RWSDK_DEBUG__ ||
+            window.__RWSDK_DEBUG_RECOVERY__)) {
+        console.log("[rwsdk:recovery]", ...args);
+    }
+}
+function getBackoffMs(attempt) {
+    const base = Math.min(DEFAULT_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+    const jittered = base * (0.75 + Math.random() * 0.5);
+    return Math.round(Math.min(jittered, MAX_BACKOFF_MS));
+}
+function getJitteredFallbackTimeoutMs() {
+    return (FALLBACK_TIMEOUT_MS + Math.round(Math.random() * FALLBACK_TIMEOUT_JITTER_MS));
+}
+function normalizeRecoveryUrl(url) {
+    const parsed = new URL(url);
+    // A trailing dot on the hostname (e.g. example.com.) is a DNS root
+    // indicator that some Cloudflare Workers routes treat differently. Strip
+    // it so the health check hits the same origin the app uses normally.
+    parsed.hostname = parsed.hostname.replace(/\.$/, "");
+    // Drop query string and hash: we only care whether the document route
+    // itself is ready.
+    return `${parsed.origin}${parsed.pathname}`;
+}
+function getCurrentHydrateRootId() {
+    if (typeof document === "undefined") {
+        return null;
+    }
+    const root = document.getElementById("hydrate-root");
+    return root?.tagName.toLowerCase() ?? null;
+}
+async function checkUrl(url, signal) {
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            cache: "no-store",
+            headers: { Accept: "text/html" },
+            signal,
+        });
+        if (response.status !== 200) {
+            debugLog("checked", url, "status", response.status, "ok", false);
+            return false;
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        if (!contentType.includes("text/html")) {
+            debugLog("checked", url, "content-type", contentType, "ok", false);
+            return false;
+        }
+        const text = await response.text();
+        const isHtml = /<!doctype html|<html/i.test(text);
+        if (!isHtml) {
+            debugLog("checked", url, "not html", "ok", false);
+            return false;
+        }
+        const currentRootId = getCurrentHydrateRootId();
+        if (currentRootId) {
+            // Match the current hydrate root element. We look for id="hydrate-root"
+            // or id='hydrate-root' followed by the same tag name.
+            const rootPattern = new RegExp(`id=["']hydrate-root["'][^>]*>\\s*<${currentRootId}\\b`, "i");
+            const rootMatches = rootPattern.test(text);
+            debugLog("checked", url, "status", 200, "rootId", currentRootId, "rootMatches", rootMatches, "ok", rootMatches);
+            return rootMatches;
+        }
+        debugLog("checked", url, "status", 200, "html", true, "ok", true);
+        return true;
+    }
+    catch (error) {
+        debugLog("check failed", url, error);
+        return false;
+    }
+}
+function createController() {
+    let state = "idle";
+    let attempts = 0;
+    const startedAt = Date.now();
+    let wakeResolver = null;
+    let abortController = new AbortController();
+    const controller = {
+        get state() {
+            return state;
+        },
+        get attempts() {
+            return attempts;
+        },
+        get elapsedMs() {
+            return Date.now() - startedAt;
+        },
+        _setState(next) {
+            state = next;
+        },
+        _incAttempts() {
+            attempts++;
+        },
+        retry() {
+            wakeResolver?.();
+        },
+        reload() {
+            abortController.abort();
+            state = "reload";
+            wakeResolver?.();
+            if (typeof window !== "undefined") {
+                window.location.reload();
+            }
+        },
+        _wait(ms) {
+            return new Promise((resolve) => {
+                const timeout = setTimeout(resolve, ms);
+                wakeResolver = () => {
+                    clearTimeout(timeout);
+                    resolve();
+                };
+            });
+        },
+    };
+    return controller;
+}
+export function configureRecovery(options) {
+    configuredOptions = options;
+}
+export function isRecoveryConfigured() {
+    return configuredOptions.onModuleNotFound != null;
+}
+export function startRecovery(reason) {
+    if (typeof window === "undefined") {
+        return;
+    }
+    debugLog("start", reason);
+    if (activeController) {
+        debugLog("already recovering, ignoring duplicate");
+        return;
+    }
+    const handler = configuredOptions.onModuleNotFound;
+    const controller = createController();
+    activeController = controller;
+    const run = async () => {
+        controller._setState("waiting");
+        debugLog("waiting, handler", typeof handler === "function" ? "custom" : handler);
+        if (typeof handler === "function") {
+            try {
+                await handler(controller);
+            }
+            catch (error) {
+                console.error("[rwsdk] recovery callback threw", error);
+            }
+        }
+        const currentUrl = normalizeRecoveryUrl(window.location.href);
+        const fallbackTimeoutMs = getJitteredFallbackTimeoutMs();
+        const startupJitter = Math.round(Math.random() * STARTUP_JITTER_MS);
+        debugLog("startup jitter", startupJitter, "ms");
+        await controller._wait(startupJitter);
+        while (activeController === controller) {
+            controller._setState("checking");
+            controller._incAttempts();
+            debugLog("checking", currentUrl, "attempt", controller.attempts, "elapsed", controller.elapsedMs);
+            const ok = await checkUrl(currentUrl, new AbortController().signal);
+            if (ok) {
+                debugLog("current route ready, reloading");
+                controller.reload();
+                return;
+            }
+            if (controller.elapsedMs >= fallbackTimeoutMs) {
+                debugLog("fallback timeout reached, checking /");
+                const indexUrl = `${new URL(window.location.href).origin}/`;
+                const indexOk = await checkUrl(indexUrl, new AbortController().signal);
+                if (indexOk) {
+                    debugLog("/ ready, navigating to /");
+                    window.location.href = "/";
+                    return;
+                }
+            }
+            const backoff = getBackoffMs(controller.attempts);
+            debugLog("not ready, backing off", backoff, "ms");
+            controller._setState("waiting");
+            await controller._wait(backoff);
+        }
+    };
+    void run();
+}
+export function isDynamicImportFailure(error) {
+    return (error instanceof TypeError &&
+        typeof error.message === "string" &&
+        error.message.includes("dynamically imported module"));
+}

package/dist/runtime/client/scrollRestoration.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+export declare const HISTORY_STATE_SCROLL_KEY = "__rwsdk_scroll_key";
+export type ScrollPosition = {
+    x: number;
+    y: number;
+};
+export type PendingScroll = ScrollPosition & {
+    behavior: ScrollBehavior;
+};
+export interface NavigationHistoryState extends Record<string, unknown> {
+    path?: string;
+    scrollX?: number;
+    scrollY?: number;
+    [HISTORY_STATE_SCROLL_KEY]?: string;
+}
+export interface ScrollRestorationController {
+    initialize(): void;
+    recordCurrentPosition(x: number, y: number): void;
+    flushCurrentPositionToHistoryState(x?: number, y?: number): void;
+    pushEntry(href: string, url: URL, initialPosition: ScrollPosition): void;
+    replaceEntry(href: string, url: URL, initialPosition: ScrollPosition): void;
+    restorePopStateScroll(): void;
+    setPendingScroll(pendingScroll: PendingScroll): void;
+    applyPendingScroll(): void;
+}
+export declare function createScrollRestoration(): ScrollRestorationController;

package/dist/runtime/client/scrollRestoration.js ADDED Viewed

@@ -0,0 +1,157 @@
+export const HISTORY_STATE_SCROLL_KEY = "__rwsdk_scroll_key";
+export function createScrollRestoration() {
+    const historyEntryKeyPrefix = Math.random().toString(36).slice(2);
+    const scrollPositions = new Map();
+    let currentHistoryEntryKey = null;
+    let nextHistoryEntryKey = 0;
+    let pendingScroll = null;
+    function createHistoryEntryKey() {
+        nextHistoryEntryKey += 1;
+        return `${historyEntryKeyPrefix}:${nextHistoryEntryKey}`;
+    }
+    function readHistoryState() {
+        const state = window.history.state;
+        return state && typeof state === "object"
+            ? { ...state }
+            : {};
+    }
+    function getHistoryEntryKey(state) {
+        const key = state[HISTORY_STATE_SCROLL_KEY];
+        return typeof key === "string" ? key : null;
+    }
+    function getScrollPositionFromState(state) {
+        if (typeof state.scrollX === "number" ||
+            typeof state.scrollY === "number") {
+            return {
+                x: typeof state.scrollX === "number" ? state.scrollX : 0,
+                y: typeof state.scrollY === "number" ? state.scrollY : 0,
+            };
+        }
+        return null;
+    }
+    function ensureCurrentHistoryEntryKey(state = readHistoryState()) {
+        const existingKey = getHistoryEntryKey(state);
+        if (existingKey) {
+            currentHistoryEntryKey = existingKey;
+            return existingKey;
+        }
+        const historyEntryKey = createHistoryEntryKey();
+        currentHistoryEntryKey = historyEntryKey;
+        window.history.replaceState({ ...state, [HISTORY_STATE_SCROLL_KEY]: historyEntryKey }, "", window.location.href);
+        return historyEntryKey;
+    }
+    function getCurrentHistoryEntryKeyForReplace(state) {
+        const existingKey = getHistoryEntryKey(state) ?? currentHistoryEntryKey;
+        if (existingKey) {
+            currentHistoryEntryKey = existingKey;
+            return existingKey;
+        }
+        const historyEntryKey = createHistoryEntryKey();
+        currentHistoryEntryKey = historyEntryKey;
+        return historyEntryKey;
+    }
+    function getSavedScrollPosition(state) {
+        const historyEntryKey = getHistoryEntryKey(state) ?? currentHistoryEntryKey;
+        const savedPosition = historyEntryKey
+            ? scrollPositions.get(historyEntryKey)
+            : undefined;
+        return savedPosition ?? getScrollPositionFromState(state);
+    }
+    function writeHistoryState(state, historyEntryKey, position) {
+        window.history.replaceState({
+            ...state,
+            [HISTORY_STATE_SCROLL_KEY]: historyEntryKey,
+            scrollX: position.x,
+            scrollY: position.y,
+        }, "", window.location.href);
+    }
+    return {
+        initialize() {
+            // Take manual control of scroll restoration. With "auto", the browser
+            // restores scroll immediately on popstate — before the RSC payload has
+            // committed — which causes the old DOM to flash at the new scroll offset.
+            if ("scrollRestoration" in window.history) {
+                window.history.scrollRestoration = "manual";
+            }
+            // Boot can happen after a reload, or after an older runtime wrote only
+            // scrollX/scrollY. Seed the in-memory store from history.state so the
+            // first commit can restore the saved position without per-scroll writes.
+            const bootState = readHistoryState();
+            const bootHistoryEntryKey = ensureCurrentHistoryEntryKey(bootState);
+            const bootScrollPosition = getSavedScrollPosition(bootState);
+            if (bootScrollPosition) {
+                scrollPositions.set(bootHistoryEntryKey, bootScrollPosition);
+                pendingScroll = {
+                    x: bootScrollPosition.x,
+                    y: bootScrollPosition.y,
+                    behavior: "instant",
+                };
+            }
+        },
+        recordCurrentPosition(x, y) {
+            if (!currentHistoryEntryKey) {
+                return;
+            }
+            scrollPositions.set(currentHistoryEntryKey, { x, y });
+        },
+        flushCurrentPositionToHistoryState(x = window.scrollX, y = window.scrollY) {
+            const state = readHistoryState();
+            const historyEntryKey = ensureCurrentHistoryEntryKey(state);
+            const position = { x, y };
+            scrollPositions.set(historyEntryKey, position);
+            writeHistoryState(state, historyEntryKey, position);
+        },
+        pushEntry(href, url, initialPosition) {
+            this.flushCurrentPositionToHistoryState();
+            const historyEntryKey = createHistoryEntryKey();
+            currentHistoryEntryKey = historyEntryKey;
+            scrollPositions.set(historyEntryKey, initialPosition);
+            window.history.pushState({
+                path: href,
+                [HISTORY_STATE_SCROLL_KEY]: historyEntryKey,
+                scrollX: initialPosition.x,
+                scrollY: initialPosition.y,
+            }, "", url);
+        },
+        replaceEntry(href, url, initialPosition) {
+            const state = readHistoryState();
+            const historyEntryKey = getCurrentHistoryEntryKeyForReplace(state);
+            scrollPositions.set(historyEntryKey, initialPosition);
+            window.history.replaceState({
+                ...state,
+                path: href,
+                [HISTORY_STATE_SCROLL_KEY]: historyEntryKey,
+                scrollX: initialPosition.x,
+                scrollY: initialPosition.y,
+            }, "", url);
+        },
+        restorePopStateScroll() {
+            const state = readHistoryState();
+            const historyEntryKey = ensureCurrentHistoryEntryKey(state);
+            const savedScrollPosition = getSavedScrollPosition(state) ?? {
+                x: 0,
+                y: 0,
+            };
+            if (!scrollPositions.has(historyEntryKey)) {
+                scrollPositions.set(historyEntryKey, savedScrollPosition);
+            }
+            pendingScroll = {
+                x: savedScrollPosition.x,
+                y: savedScrollPosition.y,
+                behavior: "instant",
+            };
+        },
+        setPendingScroll(nextPendingScroll) {
+            pendingScroll = nextPendingScroll;
+            this.recordCurrentPosition(nextPendingScroll.x, nextPendingScroll.y);
+        },
+        applyPendingScroll() {
+            if (!pendingScroll)
+                return;
+            const { x, y, behavior } = pendingScroll;
+            pendingScroll = null;
+            window.scrollTo({ top: y, left: x, behavior });
+            this.recordCurrentPosition(x, y);
+        },
+    };
+}

package/dist/runtime/client/scrollRestoration.test.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/dist/runtime/client/scrollRestoration.test.js ADDED Viewed

@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createScrollRestoration, HISTORY_STATE_SCROLL_KEY, } from "./scrollRestoration";
+describe("scrollRestoration", () => {
+    let historyState;
+    beforeEach(() => {
+        historyState = {};
+        vi.stubGlobal("window", {
+            location: { href: "http://localhost/" },
+            scrollX: 0,
+            scrollY: 0,
+            scrollTo: vi.fn(),
+            history: {
+                scrollRestoration: "auto",
+                get state() {
+                    return historyState;
+                },
+                pushState: vi.fn((state) => {
+                    historyState = state;
+                }),
+                replaceState: vi.fn((state) => {
+                    historyState = state;
+                }),
+            },
+        });
+    });
+    it("restores scroll from history state after a reload", () => {
+        historyState = {
+            [HISTORY_STATE_SCROLL_KEY]: "entry:1",
+            scrollX: 12,
+            scrollY: 345,
+        };
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        scrollRestoration.applyPendingScroll();
+        expect(window.scrollTo).toHaveBeenCalledWith({
+            left: 12,
+            top: 345,
+            behavior: "instant",
+        });
+    });
+    it("migrates legacy scrollX/scrollY history state on boot", () => {
+        historyState = { scrollX: 7, scrollY: 222 };
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        scrollRestoration.applyPendingScroll();
+        expect(window.history.replaceState).toHaveBeenCalledWith(expect.objectContaining({
+            [HISTORY_STATE_SCROLL_KEY]: expect.any(String),
+            scrollX: 7,
+            scrollY: 222,
+        }), "", "http://localhost/");
+        expect(window.scrollTo).toHaveBeenCalledWith({
+            left: 7,
+            top: 222,
+            behavior: "instant",
+        });
+    });
+    it("restores back/forward positions from the in-memory key map", () => {
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        const firstEntryState = historyState;
+        window.scrollY = 500;
+        scrollRestoration.recordCurrentPosition(0, 500);
+        scrollRestoration.pushEntry("/next", new URL("/next", "http://localhost/"), { x: 0, y: 0 });
+        historyState = firstEntryState;
+        scrollRestoration.restorePopStateScroll();
+        scrollRestoration.applyPendingScroll();
+        expect(window.scrollTo).toHaveBeenCalledWith({
+            left: 0,
+            top: 500,
+            behavior: "instant",
+        });
+    });
+    it("does not write to history state while recording scroll", () => {
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        vi.mocked(window.history.replaceState).mockClear();
+        scrollRestoration.recordCurrentPosition(0, 100);
+        scrollRestoration.recordCurrentPosition(0, 200);
+        expect(window.history.replaceState).not.toHaveBeenCalled();
+    });
+    it("flushes the latest scroll position to history state on lifecycle boundaries", () => {
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        vi.mocked(window.history.replaceState).mockClear();
+        scrollRestoration.recordCurrentPosition(4, 400);
+        scrollRestoration.flushCurrentPositionToHistoryState(4, 400);
+        expect(window.history.replaceState).toHaveBeenCalledWith(expect.objectContaining({
+            [HISTORY_STATE_SCROLL_KEY]: expect.any(String),
+            scrollX: 4,
+            scrollY: 400,
+        }), "", "http://localhost/");
+    });
+});

package/dist/runtime/imports/client.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import React from "react";
 import { ClientOnly } from "../client/client";
+import { isDynamicImportFailure, isRecoveryConfigured, startRecovery, } from "../client/recovery.js";
 import { memoizeOnId } from "../lib/memoizeOnId";
 // @ts-ignore
 import { useClientLookup } from "virtual:use-client-lookup.js";
@@ -8,7 +9,18 @@ export const loadModule = memoizeOnId(async (id) => {
     if (!moduleFn) {
         throw new Error(`(client) No module found for '${id}' in module lookup for "use client" directive`);
     }
-    return await moduleFn();
+    try {
+        return await moduleFn();
+    }
+    catch (error) {
+        if (isDynamicImportFailure(error) && isRecoveryConfigured()) {
+            startRecovery("module-not-found");
+            // Stall this import forever so React doesn't crash before the recovery
+            // flow reloads the page.
+            return new Promise(() => { });
+        }
+        throw error;
+    }
 });
 // context(justinvdm, 2 Dec 2024): re memoize(): React relies on the same promise instance being returned for the same id
 export const clientWebpackRequire = memoizeOnId(async (id) => {

package/dist/runtime/lib/router.d.ts CHANGED Viewed

@@ -9,6 +9,7 @@ export type RouteMiddleware<T extends RequestInfo = RequestInfo> = BivariantRout
 export type ExceptHandler<T extends RequestInfo = RequestInfo> = {
     __rwExcept: true;
     handler: (error: unknown, requestInfo: T) => MaybePromise<React.JSX.Element | Response | void>;
+    pathPattern?: string;
 };
 type RouteFunction<T extends RequestInfo = RequestInfo> = BivariantRouteHandler<T, MaybePromise<Response>>;
 type RouteComponent<T extends RequestInfo = RequestInfo> = BivariantRouteHandler<T, MaybePromise<React.JSX.Element | Response | void>>;

package/dist/runtime/lib/router.js CHANGED Viewed

@@ -185,11 +185,28 @@ export function defineRoutes(routes) {
             function isExceptHandler(route) {
                 return route.type === "except";
             }
+            function isPathInExceptScope(pathPattern, requestPath) {
+                const normalized = pathPattern.endsWith("/")
+                    ? pathPattern
+                    : pathPattern + "/";
+                const hasParams = normalized.includes(":") || normalized.includes("*");
+                if (hasParams) {
+                    const wildcardPattern = normalized.slice(0, -1) + "/*";
+                    return (matchPath(wildcardPattern, requestPath) !== null ||
+                        matchPath(normalized.slice(0, -1), requestPath) !== null);
+                }
+                return (requestPath === normalized || requestPath.startsWith(normalized));
+            }
             async function executeExceptHandlers(error, startIndex) {
                 // Search backwards from startIndex to find the most recent except handler
                 for (let i = startIndex; i >= 0; i--) {
                     const route = compiledRoutes[i];
                     if (isExceptHandler(route)) {
+                        const pattern = route.handler.pathPattern;
+                        if (pattern &&
+                            !isPathInExceptScope(pattern, getRequestInfo().path)) {
+                            continue;
+                        }
                         try {
                             const result = await route.handler.handler(error, getRequestInfo());
                             const handled = await handleMiddlewareResult(result);
@@ -554,8 +571,16 @@ export function prefix(prefixPath, routes) {
             r !== null &&
             "__rwExcept" in r &&
             r.__rwExcept === true) {
-            // Pass through ExceptHandler as-is
-            return r;
+            const existing = r.pathPattern;
+            const combined = existing
+                ? joinPaths(normalizedPrefix, existing)
+                : normalizedPrefix;
+            const scoped = {
+                __rwExcept: true,
+                handler: r.handler,
+                pathPattern: combined,
+            };
+            return scoped;
         }
         if (Array.isArray(r)) {
             // Recursively process nested route arrays

package/dist/runtime/lib/router.test.js CHANGED Viewed

@@ -1535,5 +1535,101 @@ describe("defineRoutes - Request Handling Behavior", () => {
             expect(response.status).toBe(500);
             expect(await response.text()).toBe(`Caught: ${errorMessage}`);
         });
+        describe("prefix scoping", () => {
+            const makePrefixApp = () => {
+                const globalHandler = except(() => new Response("[GLOBAL]", {
+                    status: 500,
+                }));
+                const adminHandler = except(() => new Response("[ADMIN]", {
+                    status: 500,
+                }));
+                const router = defineRoutes([
+                    globalHandler,
+                    ...prefix("/admin", [
+                        adminHandler,
+                        route("/dashboard/", () => {
+                            throw new Error("admin dashboard error");
+                        }),
+                    ]),
+                    route("/", () => {
+                        throw new Error("home route error");
+                    }),
+                ]);
+                return router;
+            };
+            const handle = async (router, path) => {
+                const deps = createMockDependencies();
+                deps.mockRequestInfo.request = new Request(`http://localhost:3000${path}`);
+                return router.handle({
+                    request: new Request(`http://localhost:3000${path}`),
+                    renderPage: deps.mockRenderPage,
+                    getRequestInfo: deps.getRequestInfo,
+                    onError: deps.onError,
+                    runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                    rscActionHandler: deps.mockRscActionHandler,
+                });
+            };
+            it("an except inside prefix should NOT catch errors from routes outside the prefix", async () => {
+                const router = makePrefixApp();
+                const response = await handle(router, "/");
+                expect(await response.text()).toBe("[GLOBAL]");
+            });
+            it("an except inside prefix should catch errors from routes inside the prefix", async () => {
+                const router = makePrefixApp();
+                const response = await handle(router, "/admin/dashboard/");
+                expect(await response.text()).toBe("[ADMIN]");
+            });
+            it("an except inside prefix that returns void should bubble to the global handler", async () => {
+                const router = defineRoutes([
+                    except(() => new Response("[GLOBAL]", { status: 500 })),
+                    ...prefix("/admin", [
+                        except(() => undefined),
+                        route("/dashboard/", () => {
+                            throw new Error("boom");
+                        }),
+                    ]),
+                ]);
+                const response = await handle(router, "/admin/dashboard/");
+                expect(await response.text()).toBe("[GLOBAL]");
+            });
+            it("nested prefixes compose the scope path", async () => {
+                const router = defineRoutes([
+                    except(() => new Response("[GLOBAL]", { status: 500 })),
+                    ...prefix("/a", [
+                        ...prefix("/b", [
+                            except(() => new Response("[A/B]", { status: 500 })),
+                            route("/c/", () => {
+                                throw new Error("a/b/c error");
+                            }),
+                        ]),
+                    ]),
+                    route("/d/", () => {
+                        throw new Error("d error");
+                    }),
+                ]);
+                const inside = await handle(router, "/a/b/c/");
+                expect(await inside.text()).toBe("[A/B]");
+                const outside = await handle(router, "/d/");
+                expect(await outside.text()).toBe("[GLOBAL]");
+            });
+            it("parameterized prefixes scope the except handler", async () => {
+                const router = defineRoutes([
+                    except(() => new Response("[GLOBAL]", { status: 500 })),
+                    ...prefix("/users/:id", [
+                        except(() => new Response("[USER]", { status: 500 })),
+                        route("/profile/", () => {
+                            throw new Error("profile error");
+                        }),
+                    ]),
+                    route("/about/", () => {
+                        throw new Error("about error");
+                    }),
+                ]);
+                const inside = await handle(router, "/users/42/profile/");
+                expect(await inside.text()).toBe("[USER]");
+                const outside = await handle(router, "/about/");
+                expect(await outside.text()).toBe("[GLOBAL]");
+            });
+        });
     });
 });