hono-preact 0.1.0 → 0.3.0

package/dist/server/page-action-resolvers.js

@@ -0,0 +1,147 @@
+function extractActions(mod) {
+    const moduleKey = mod.__moduleKey;
+    if (typeof moduleKey !== 'string' || !mod.serverActions)
+        return [];
+    const out = [];
+    for (const [name, val] of Object.entries(mod.serverActions)) {
+        if (typeof val !== 'function')
+            continue;
+        // `defineAction` attaches `use` and `timeoutMs` as non-enumerable
+        // properties on the function (see packages/iso/src/action.ts). Read
+        // them here as the single deserialization boundary; the handler reads
+        // `entry.fn`, `entry.use`, `entry.timeoutMs` through the typed
+        // ActionEntry shape from this point on.
+        const metadata = val;
+        out.push({
+            name,
+            entry: {
+                fn: val,
+                use: metadata.use ?? [],
+                timeoutMs: metadata.timeoutMs,
+                moduleKey,
+            },
+        });
+    }
+    return out;
+}
+function segmentsOf(p) {
+    return p.split('/').filter((s) => s !== '');
+}
+function urlPathMatchesPattern(urlPath, pattern) {
+    const ps = segmentsOf(pattern);
+    const us = segmentsOf(urlPath);
+    for (let i = 0; i < ps.length; i++) {
+        const p = ps[i];
+        if (p === '*')
+            return true;
+        if (i >= us.length)
+            return false;
+        if (p.startsWith(':'))
+            continue;
+        if (p !== us[i])
+            return false;
+    }
+    return ps.length === us.length;
+}
+function patternScore(pattern) {
+    let score = 0;
+    for (const seg of segmentsOf(pattern)) {
+        if (seg === '*')
+            score += 0;
+        else if (seg.startsWith(':'))
+            score += 1;
+        else
+            score += 2;
+    }
+    return score;
+}
+/**
+ * Build action resolvers keyed by route path and by module key. Each
+ * ServerRoute contributes its own serverActions and its ancestors' serverActions
+ * to the merged map for that path. Ancestor entries are written first so that
+ * a page-level action shadows a same-named layout action when names collide.
+ *
+ * Lazy semantics: the first call triggers loading all server modules. The result
+ * is cached for the process lifetime (unless dev=true, which rebuilds on every
+ * call so edits take effect without restarting the server).
+ *
+ * NOTE: framework-private. Intended consumer is the generated server entry and
+ * pageActionHandler.
+ */
+export function makePageActionResolvers(serverRoutes, options = {}) {
+    const dev = options.dev ?? false;
+    let buildPromise = null;
+    const build = async () => {
+        // Load each distinct server thunk once; a thunk may appear as `server`
+        // on one route and as an `ancestor` on its children.
+        const thunkCache = new Map();
+        const load = (thunk) => {
+            let p = thunkCache.get(thunk);
+            if (!p) {
+                p = thunk().then((m) => m);
+                thunkCache.set(thunk, p);
+            }
+            return p;
+        };
+        const byPathMap = new Map();
+        const byModuleKeyMap = new Map();
+        await Promise.all(serverRoutes.map(async (route) => {
+            const ancestorMods = await Promise.all(route.ancestors.map(load));
+            const selfMod = await load(route.server);
+            const merged = new Map();
+            // Write ancestors first (outer -> inner), then self. Later writes
+            // shadow earlier ones, so a page-level action wins over a layout
+            // action of the same name.
+            for (const mod of [...ancestorMods, selfMod]) {
+                for (const { name, entry } of extractActions(mod)) {
+                    merged.set(name, entry);
+                    let m = byModuleKeyMap.get(entry.moduleKey);
+                    if (!m) {
+                        m = new Map();
+                        byModuleKeyMap.set(entry.moduleKey, m);
+                    }
+                    m.set(name, entry);
+                }
+            }
+            byPathMap.set(route.path, merged);
+        }));
+        return { byPathMap, byModuleKeyMap };
+    };
+    const get = () => {
+        if (dev)
+            return build();
+        if (buildPromise)
+            return buildPromise;
+        buildPromise = build().catch((err) => {
+            buildPromise = null;
+            return Promise.reject(err);
+        });
+        return buildPromise;
+    };
+    return {
+        async byPath(path) {
+            const { byPathMap } = await get();
+            let bestPattern = null;
+            let bestScore = -1;
+            let bestDepth = -1;
+            for (const pattern of byPathMap.keys()) {
+                if (!urlPathMatchesPattern(path, pattern))
+                    continue;
+                const score = patternScore(pattern);
+                const depth = segmentsOf(pattern).length;
+                if (score > bestScore || (score === bestScore && depth > bestDepth)) {
+                    bestPattern = pattern;
+                    bestScore = score;
+                    bestDepth = depth;
+                }
+            }
+            return bestPattern
+                ? (byPathMap.get(bestPattern) ?? new Map())
+                : new Map();
+        },
+        async byModuleKey(moduleKey, actionName) {
+            const { byModuleKeyMap } = await get();
+            return byModuleKeyMap.get(moduleKey)?.get(actionName);
+        },
+    };
+}

package/dist/server/render.d.ts

@@ -1,5 +1,7 @@
 import type { Context } from 'hono';
 import type { VNode } from 'preact';
+import { type AppConfig } from '../iso/index';
 export declare function renderPage(c: Context, node: VNode, options?: {
     defaultTitle?: string;
+    appConfig?: AppConfig;
 }): Promise<Response>;

package/dist/server/render.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx } from "preact/jsx-runtime";
 import { createDispatcher, HoofdProvider } from 'hoofd/preact';
 import { prerender, locationStub } from 'preact-iso/prerender';
-import { GuardRedirect, env } from '../iso/index.js';
-import { HonoRequestContext, runRequestScope, captureRequestScope, takeServerStreamingLoaders, } from '../iso/internal/index.js';
+import { env, isOutcome, ActionResultContext, } from '../iso/index.js';
+import { HonoRequestContext, runRequestScope, captureRequestScope, takeServerStreamingLoaders, dispatchServer, partitionUse, getActionResultSlot, } from '../iso/internal.js';
+import { speculationRulesTag } from './speculation-rules.js';
 function escapeHtml(str) {
     return str
         .replace(/&/g, '&')
@@ -24,6 +25,63 @@ function toAttrs(obj) {
         .map(([k, v]) => `${k}="${escapeHtml(String(v))}"`)
         .join(' ');
 }
+// Outcome translation for the root chain dispatched around prerender. The
+// root layer (appConfig.use) only legitimately produces `redirect` or
+// `deny`; a `render` outcome is page-scope and must not flow through here.
+// Defense-in-depth: surface programmer error as a 500 rather than crash.
+function translateRootOutcome(c, outcome) {
+    if (outcome.__outcome === 'redirect') {
+        if (outcome.headers) {
+            for (const [k, v] of Object.entries(outcome.headers))
+                c.header(k, v);
+        }
+        return c.redirect(outcome.to, outcome.status);
+    }
+    if (outcome.__outcome === 'deny') {
+        if (outcome.headers) {
+            for (const [k, v] of Object.entries(outcome.headers))
+                c.header(k, v);
+        }
+        return c.text(outcome.message ?? 'Forbidden', outcome.status);
+    }
+    return c.text('render outcome is page-scope only and cannot be issued by root middleware', 500);
+}
+function buildActionResultContext() {
+    const slot = getActionResultSlot();
+    if (!slot)
+        return null;
+    if (slot.resolution.kind === 'success') {
+        return {
+            module: slot.module,
+            action: slot.action,
+            kind: 'success',
+            data: slot.resolution.data,
+            submittedPayload: slot.submittedPayload,
+        };
+    }
+    if (slot.resolution.kind === 'error') {
+        return {
+            module: slot.module,
+            action: slot.action,
+            kind: 'error',
+            message: slot.resolution.message,
+            submittedPayload: slot.submittedPayload,
+        };
+    }
+    const { outcome } = slot.resolution;
+    if (outcome.__outcome === 'deny') {
+        return {
+            module: slot.module,
+            action: slot.action,
+            kind: 'deny',
+            status: outcome.status,
+            message: outcome.message,
+            data: outcome.data,
+            submittedPayload: slot.submittedPayload,
+        };
+    }
+    return null;
+}
 export async function renderPage(c, node, options) {
     const dispatcher = createDispatcher();
     const previousEnv = env.current;
@@ -37,33 +95,68 @@ export async function renderPage(c, node, options) {
     // binder restores per-request isolation for `getRequestStore` /
     // `getRequestHonoContext` reads from generator continuations.
     let bindRequestScope = (fn) => fn();
+    let rootResult;
     try {
-        const result = await runRequestScope(async () => {
-            // preact-iso's `LocationProvider` reads `globalThis.location` once,
-            // synchronously, when it mounts. Set it on the same microtask as the
-            // `prerender` call so no other request can interleave and trample
-            // the global between us writing it and the provider reading it.
-            // Children resume from reducer state, never re-reading the global,
-            // so the rest of this render is safe even if another request resets
-            // `globalThis.location` while we await suspended children.
+        rootResult = await runRequestScope(async () => {
             const reqUrl = new URL(c.req.url);
-            locationStub(reqUrl.pathname + reqUrl.search);
-            bindRequestScope = captureRequestScope();
-            const rendered = await prerender(_jsx(HonoRequestContext.Provider, { value: { context: c }, children: _jsx(HoofdProvider, { value: dispatcher, children: node }) }));
-            const loaders = takeServerStreamingLoaders();
-            return { html: rendered.html, streamingLoaders: loaders };
+            const location = {
+                path: reqUrl.pathname,
+                searchParams: Object.fromEntries(reqUrl.searchParams),
+                // Path params are route-match output; the root layer runs before
+                // route matching, so they're empty here. Page-layer middleware
+                // (added in a follow-up) will have them populated.
+                pathParams: {},
+            };
+            const rootUse = options?.appConfig?.use ?? [];
+            const serverMw = partitionUse(rootUse).middleware.filter((m) => m.runs === 'server');
+            const ctx = {
+                scope: 'page',
+                c,
+                signal: c.req.raw.signal,
+                location,
+            };
+            const dispatch = await dispatchServer({
+                middleware: serverMw,
+                ctx,
+                inner: async () => {
+                    // preact-iso's `LocationProvider` reads `globalThis.location`
+                    // once, synchronously, when it mounts. Set it on the same
+                    // microtask as the `prerender` call so no other request can
+                    // interleave and trample the global between us writing it and
+                    // the provider reading it. Children resume from reducer state,
+                    // never re-reading the global, so the rest of this render is
+                    // safe even if another request resets `globalThis.location`
+                    // while we await suspended children.
+                    locationStub(reqUrl.pathname + reqUrl.search);
+                    bindRequestScope = captureRequestScope();
+                    const rendered = await prerender(_jsx(ActionResultContext.Provider, { value: buildActionResultContext(), children: _jsx(HonoRequestContext.Provider, { value: { context: c }, children: _jsx(HoofdProvider, { value: dispatcher, children: node }) }) }));
+                    const loaders = takeServerStreamingLoaders();
+                    return {
+                        kind: 'value',
+                        html: rendered.html,
+                        streamingLoaders: loaders,
+                    };
+                },
+            });
+            if (dispatch.kind === 'outcome') {
+                return { kind: 'outcome', outcome: dispatch.outcome };
+            }
+            return dispatch.value;
         }, { honoContext: c });
-        html = result.html;
-        streamingLoaders = result.streamingLoaders;
     }
     catch (e) {
-        if (e instanceof GuardRedirect)
-            return c.redirect(e.location);
+        if (isOutcome(e))
+            return translateRootOutcome(c, e);
         throw e;
     }
     finally {
         env.current = previousEnv;
     }
+    if (rootResult.kind === 'outcome') {
+        return translateRootOutcome(c, rootResult.outcome);
+    }
+    html = rootResult.html;
+    streamingLoaders = rootResult.streamingLoaders;
     const { title, lang, metas = [], links = [] } = dispatcher.toStatic();
     // Only inject a <title> when hoofd produced one or the caller provided a
     // defaultTitle. Layouts that render their own static <title> (via <Head>)
@@ -74,6 +167,7 @@ export async function renderPage(c, node, options) {
         titleSource != null ? `<title>${escapeHtml(titleSource)}</title>` : '',
         ...metas.map((m) => `<meta ${toAttrs(m)} />`),
         ...links.map((l) => `<link ${toAttrs(l)} />`),
+        speculationRulesTag(options?.appConfig ?? {}),
     ]
         .filter(Boolean)
         .join('\n        ');
@@ -137,6 +231,16 @@ export async function renderPage(c, node, options) {
                     if (aborted)
                         return;
                     controller.enqueue(encoder.encode(`<!doctype html>${beforeBody}\n${bootstrap}\n`));
+                    // Yield one microtask before advancing any loader generator past
+                    // its first yield. `renderPage` is still on the synchronous frame
+                    // that constructs this response (`new ReadableStream(...)` returns,
+                    // then `c.body(...)` runs and commits the headers). Resuming a
+                    // generator can call `setCookie(ctx.c, ...)`, which mutates Hono's
+                    // prepared headers; deferring the pump guarantees the response is
+                    // built first, so post-first-yield header writes are consistently
+                    // excluded rather than racing construction. Cookies must be set
+                    // before the loader's first yield to reach the streamed response.
+                    await Promise.resolve();
                     // Drive each pending generator in parallel; emit script tags per chunk.
                     await Promise.all(streamingLoaders.map(async ({ loaderId, gen }) => {
                         try {
@@ -185,19 +289,24 @@ export async function renderPage(c, node, options) {
             });
         }
     });
-    return new Response(responseStream, {
-        status: 200,
-        headers: {
-            'Content-Type': 'text/html; charset=utf-8',
-            'Transfer-Encoding': 'chunked',
-            // Prevent buffering / transformation by intermediate proxies. nginx
-            // honors `X-Accel-Buffering: no` to flush per chunk; `no-transform`
-            // stops middleboxes from rebuffering or gzipping the stream as a
-            // single response. We deliberately do NOT add `no-store`: streamed
-            // HTML can still be legitimately cacheable, and users can override
-            // via their own middleware.
-            'X-Accel-Buffering': 'no',
-            'Cache-Control': 'no-transform',
-        },
+    // Route through `c.body()` rather than `new Response(...)` so Hono merges
+    // its prepared headers into the streamed response. A streaming loader's
+    // body runs up to its first `yield` during prerender, so a `Set-Cookie`
+    // written via `ctx.c` before that yield is sitting in Hono's prepared
+    // headers by now; constructing the Response directly would drop it. The
+    // non-streaming branch above gets this for free via `c.html()`. Cookies
+    // written after a yield run in the pump below, once headers are already
+    // sent, and are unavoidably lost.
+    return c.body(responseStream, 200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Transfer-Encoding': 'chunked',
+        // Prevent buffering / transformation by intermediate proxies. nginx
+        // honors `X-Accel-Buffering: no` to flush per chunk; `no-transform`
+        // stops middleboxes from rebuffering or gzipping the stream as a
+        // single response. We deliberately do NOT add `no-store`: streamed
+        // HTML can still be legitimately cacheable, and users can override
+        // via their own middleware.
+        'X-Accel-Buffering': 'no',
+        'Cache-Control': 'no-transform',
     });
 }

package/dist/server/route-server-modules.d.ts

@@ -1,12 +1,52 @@
-import type { RoutesManifest } from '../iso/index';
+import type { RoutesManifest, ServerRoute } from '../iso/index';
 /**
  * Convert a RoutesManifest into the array of lazy server-module loaders
- * that loadersHandler / actionsHandler accept. Previously returned a record
- * keyed by stringified integers; those keys were unused at the call site
- * (handlers iterate values only), so the array form is just the same data
- * without dead surface. Vite-style globs (`Record<string, ...>`) are still
- * accepted by the handlers directly; this helper is for the
- * routes-manifest-driven path used by the framework's generated server
- * entry.
+ * that loadersHandler accepts. Previously returned a record keyed by
+ * stringified integers; those keys were unused at the call site (handlers
+ * iterate values only), so the array form is just the same data without dead
+ * surface. Vite-style globs (`Record<string, ...>`) are still accepted by
+ * loadersHandler directly; this helper is for the routes-manifest-driven
+ * path used by the framework's generated server entry.
  */
 export declare function routeServerModules(manifest: RoutesManifest): ReadonlyArray<() => Promise<unknown>>;
+/**
+ * Build the two page-layer `use` resolvers wired into loadersHandler and
+ * pageActionHandler. The loader handler matches by the location's URL path;
+ * the action handler matches by the action's owning module key. Both
+ * lookups share one underlying composed map populated by loading every
+ * routed `.server.*` module exactly once (then caching the result).
+ *
+ * Ancestor composition: each ServerRoute carries an explicit list of
+ * ancestor server thunks captured during the route-tree walk. The
+ * resolver loads each ancestor's `pageUse` (if any) and concatenates them
+ * outer-first, with the route's own pageUse appended last. So a layout
+ * group's pageUse runs before each nested leaf's pageUse without the user
+ * having to repeat the import in every leaf .server.*. Order matches the
+ * middleware dispatcher's outer -> inner contract: app -> outermost
+ * layout -> ... -> leaf -> per-unit.
+ *
+ * Why route-tree ancestry (not URL-prefix ancestry): two routes can share
+ * a URL prefix without being parent/child in the tree. For example,
+ * `/demo/projects` and `/demo/projects/:projectId/issues/:issueId` are
+ * siblings of the `/demo` layout group; the latter is NOT a descendant of
+ * the former. URL-prefix matching incorrectly conflates them and runs the
+ * shared gate twice on every nested request.
+ *
+ * Lazy semantics: the first call to either resolver triggers the build of
+ * all server modules listed in `serverRoutes`. Subsequent calls return
+ * from the cached map. A failed build is not cached -- the next call
+ * retries -- so a transient import error doesn't permanently poison the
+ * resolver. Modules that don't export `pageUse` (the common case today)
+ * contribute nothing to the composed arrays. When `dev` is true the cache
+ * is bypassed on every call so editing a `.server.*` file's `pageUse`
+ * takes effect without restarting the server.
+ *
+ * NOTE: framework-private. The only intended consumer outside tests is
+ * the generated server entry. Reach for it at your own risk.
+ */
+export declare function makePageUseResolvers(serverRoutes: ReadonlyArray<ServerRoute>, options?: {
+    dev?: boolean;
+}): {
+    byPath: (path: string) => Promise<ReadonlyArray<unknown>>;
+    byModuleKey: (key: string) => Promise<ReadonlyArray<unknown>>;
+};

package/dist/server/route-server-modules.js

@@ -1,13 +1,196 @@
 /**
  * Convert a RoutesManifest into the array of lazy server-module loaders
- * that loadersHandler / actionsHandler accept. Previously returned a record
- * keyed by stringified integers; those keys were unused at the call site
- * (handlers iterate values only), so the array form is just the same data
- * without dead surface. Vite-style globs (`Record<string, ...>`) are still
- * accepted by the handlers directly; this helper is for the
- * routes-manifest-driven path used by the framework's generated server
- * entry.
+ * that loadersHandler accepts. Previously returned a record keyed by
+ * stringified integers; those keys were unused at the call site (handlers
+ * iterate values only), so the array form is just the same data without dead
+ * surface. Vite-style globs (`Record<string, ...>`) are still accepted by
+ * loadersHandler directly; this helper is for the routes-manifest-driven
+ * path used by the framework's generated server entry.
  */
 export function routeServerModules(manifest) {
     return manifest.serverImports;
 }
+function segmentsOf(path) {
+    return path.split('/').filter((s) => s !== '');
+}
+/**
+ * True when `urlPath` (the concrete URL the user navigated to, with all
+ * params substituted) matches `pattern` exactly: same segment count, and
+ * each pattern segment either equals the URL segment, is a `:param`, or is
+ * a trailing `*`.
+ *
+ * Used at lookup time. `byPath` resolves the URL to the most specific
+ * pattern in the map and returns its already-composed pageUse.
+ */
+function urlPathMatchesPattern(urlPath, pattern) {
+    const ps = segmentsOf(pattern);
+    const us = segmentsOf(urlPath);
+    for (let i = 0; i < ps.length; i++) {
+        const p = ps[i];
+        if (p === '*')
+            return true;
+        if (i >= us.length)
+            return false;
+        if (p.startsWith(':'))
+            continue;
+        if (p !== us[i])
+            return false;
+    }
+    return ps.length === us.length;
+}
+/**
+ * Score a route pattern for tiebreaker purposes when multiple patterns at
+ * the same segment depth match the URL. Mirrors preact-iso's runtime
+ * preference for literal segments: literal=2, param=1, wildcard=0. Within
+ * the same score, the caller falls back to depth, and within the same
+ * depth, to the loaded order in `serverRoutes`. Pre-merged literal wins
+ * over `/admin/users/:id` when the URL is `/admin/users/me`.
+ */
+function patternScore(pattern) {
+    let score = 0;
+    for (const seg of segmentsOf(pattern)) {
+        if (seg === '*')
+            score += 0;
+        else if (seg.startsWith(':'))
+            score += 1;
+        else
+            score += 2;
+    }
+    return score;
+}
+function pageUseFromMod(mod, patternPath) {
+    if (mod.pageUse === undefined || mod.pageUse === null)
+        return [];
+    if (Array.isArray(mod.pageUse))
+        return mod.pageUse;
+    // Runtime guard for non-array pageUse: surface a descriptive error so
+    // the user finds the typo (`pageUse = mySingleMw` instead of `[mySingleMw]`)
+    // immediately rather than experiencing a silent gate failure. The
+    // build-time plugin should catch this first; this is the runtime backstop.
+    throw new Error(`Route '${patternPath}' exports a non-array \`pageUse\`. ` +
+        `pageUse must be an array (typically a reference to a const declared as \`[mw1, mw2]\`). ` +
+        `Wrap a single middleware in brackets: pageUse = [myMiddleware].`);
+}
+/**
+ * Build the two page-layer `use` resolvers wired into loadersHandler and
+ * pageActionHandler. The loader handler matches by the location's URL path;
+ * the action handler matches by the action's owning module key. Both
+ * lookups share one underlying composed map populated by loading every
+ * routed `.server.*` module exactly once (then caching the result).
+ *
+ * Ancestor composition: each ServerRoute carries an explicit list of
+ * ancestor server thunks captured during the route-tree walk. The
+ * resolver loads each ancestor's `pageUse` (if any) and concatenates them
+ * outer-first, with the route's own pageUse appended last. So a layout
+ * group's pageUse runs before each nested leaf's pageUse without the user
+ * having to repeat the import in every leaf .server.*. Order matches the
+ * middleware dispatcher's outer -> inner contract: app -> outermost
+ * layout -> ... -> leaf -> per-unit.
+ *
+ * Why route-tree ancestry (not URL-prefix ancestry): two routes can share
+ * a URL prefix without being parent/child in the tree. For example,
+ * `/demo/projects` and `/demo/projects/:projectId/issues/:issueId` are
+ * siblings of the `/demo` layout group; the latter is NOT a descendant of
+ * the former. URL-prefix matching incorrectly conflates them and runs the
+ * shared gate twice on every nested request.
+ *
+ * Lazy semantics: the first call to either resolver triggers the build of
+ * all server modules listed in `serverRoutes`. Subsequent calls return
+ * from the cached map. A failed build is not cached -- the next call
+ * retries -- so a transient import error doesn't permanently poison the
+ * resolver. Modules that don't export `pageUse` (the common case today)
+ * contribute nothing to the composed arrays. When `dev` is true the cache
+ * is bypassed on every call so editing a `.server.*` file's `pageUse`
+ * takes effect without restarting the server.
+ *
+ * NOTE: framework-private. The only intended consumer outside tests is
+ * the generated server entry. Reach for it at your own risk.
+ */
+export function makePageUseResolvers(serverRoutes, options = {}) {
+    const dev = options.dev ?? false;
+    let buildPromise = null;
+    const build = async () => {
+        // Load every distinct server thunk exactly once. A given thunk may
+        // appear as `server` on one ServerRoute and as an `ancestor` on
+        // descendants; calling it just once keeps module-init side effects
+        // (e.g. logging, registry insertion) idempotent.
+        const thunkCache = new Map();
+        const load = (thunk) => {
+            let p = thunkCache.get(thunk);
+            if (!p) {
+                p = thunk().then((mod) => mod);
+                thunkCache.set(thunk, p);
+            }
+            return p;
+        };
+        const composedByPath = new Map();
+        const patternByModuleKey = new Map();
+        await Promise.all(serverRoutes.map(async (route) => {
+            const ancestorMods = await Promise.all(route.ancestors.map((t) => load(t)));
+            const selfMod = await load(route.server);
+            const composed = [];
+            for (let i = 0; i < ancestorMods.length; i++) {
+                composed.push(...pageUseFromMod(ancestorMods[i], route.path));
+            }
+            composed.push(...pageUseFromMod(selfMod, route.path));
+            // Two ServerRoutes sharing the same path mean two `.server.*` files
+            // claim the same route -- a route-table error. The route validator
+            // is the right place to surface that; here we simply preserve the
+            // load order (last write wins for the composed map, which matches
+            // the previous behavior of `composedByPath.set(path, ...)`).
+            composedByPath.set(route.path, composed);
+            if (typeof selfMod.__moduleKey === 'string') {
+                patternByModuleKey.set(selfMod.__moduleKey, route.path);
+            }
+        }));
+        return { composedByPath, patternByModuleKey };
+    };
+    const get = () => {
+        if (dev) {
+            // In dev, always rebuild so edits to `pageUse` in any .server.* file
+            // take effect on the next request without restarting the process.
+            return build();
+        }
+        if (buildPromise)
+            return buildPromise;
+        buildPromise = build().catch((err) => {
+            buildPromise = null;
+            return Promise.reject(err);
+        });
+        return buildPromise;
+    };
+    return {
+        async byPath(path) {
+            const { composedByPath } = await get();
+            // The handler receives the matched route's URL path (params
+            // substituted to literal values). Walk the composed map and pick the
+            // best-matching pattern. Tiebreaker: (1) higher specificity score
+            // (literal=2, param=1, wildcard=0); (2) within same score, longer
+            // path; (3) within same length, first inserted. Mirrors preact-iso's
+            // runtime preference for literal matches over parameterized siblings.
+            //
+            // NOTE: O(routes) linear scan. Fine for small apps; a precomputed
+            // trie or a request-keyed memo would help at scale.
+            let bestPattern = null;
+            let bestScore = -1;
+            let bestDepth = -1;
+            for (const pattern of composedByPath.keys()) {
+                if (!urlPathMatchesPattern(path, pattern))
+                    continue;
+                const score = patternScore(pattern);
+                const depth = segmentsOf(pattern).length;
+                if (score > bestScore || (score === bestScore && depth > bestDepth)) {
+                    bestPattern = pattern;
+                    bestScore = score;
+                    bestDepth = depth;
+                }
+            }
+            return bestPattern ? (composedByPath.get(bestPattern) ?? []) : [];
+        },
+        async byModuleKey(key) {
+            const { composedByPath, patternByModuleKey } = await get();
+            const pattern = patternByModuleKey.get(key);
+            return pattern ? (composedByPath.get(pattern) ?? []) : [];
+        },
+    };
+}

package/dist/server/speculation-rules.d.ts

@@ -0,0 +1,3 @@
+import type { AppConfig } from '../iso/index';
+export declare const SPECULATION_RULES_TAG = "<script type=\"speculationrules\">{\"prefetch\":[{\"where\":{\"and\":[{\"href_matches\":\"/*\"},{\"not\":{\"selector_matches\":\"[data-no-prefetch]\"}}]},\"eagerness\":\"moderate\"}]}</script>";
+export declare function speculationRulesTag(config: AppConfig): string;

package/dist/server/speculation-rules.js

@@ -0,0 +1,8 @@
+const SPECULATION_RULES_JSON = '{"prefetch":[{"where":{"and":[' +
+    '{"href_matches":"/*"},' +
+    '{"not":{"selector_matches":"[data-no-prefetch]"}}' +
+    ']},"eagerness":"moderate"}]}';
+export const SPECULATION_RULES_TAG = `<script type="speculationrules">${SPECULATION_RULES_JSON}</script>`;
+export function speculationRulesTag(config) {
+    return config.speculation === true ? SPECULATION_RULES_TAG : '';
+}