hono-preact 0.1.0 → 0.2.0

package/dist/vite/server-entry.js

@@ -2,10 +2,18 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { parse } from '@babel/parser';
 import { BABEL_PARSER_PLUGINS } from './parser-options.js';
-export function generateServerEntrySource(opts) {
-    const { layoutAbsPath, routesAbsPath, apiAbsPath } = opts;
+export function generateCoreAppModule(opts) {
+    const { layoutAbsPath, routesAbsPath, apiAbsPath, appConfigAbsPath } = opts;
     const apiImport = apiAbsPath ? `import userApp from '${apiAbsPath}';\n` : '';
     const apiMount = apiAbsPath ? `  .route('/', userApp)\n` : '';
+    // appConfig is optional: when no app-config.ts file exists, fall back to
+    // an empty config so the handler chain composition (root -> page -> unit)
+    // still works without the user authoring anything. The default-export
+    // shape mirrors the `import appConfig from './app-config'` convention so
+    // consumers can adopt the file later without other entry changes.
+    const appConfigImport = appConfigAbsPath
+        ? `import appConfig from '${appConfigAbsPath}';\n`
+        : `const appConfig = { use: [] };\n`;
     // The generated source is loaded as a virtual module, which Vite/esbuild
     // treats as plain JS by default. Use h() to construct vnodes rather than
     // JSX so the source compiles without a TSX loader hint.
@@ -16,25 +24,32 @@ export function generateServerEntrySource(opts) {
         `import {\n` +
         `  actionsHandler,\n` +
         `  loadersHandler,\n` +
+        `  makePageUseResolvers,\n` +
         `  renderPage,\n` +
         `  routeServerModules,\n` +
         `} from 'hono-preact/server';\n` +
         `import Layout from '${layoutAbsPath}';\n` +
         `import routes from '${routesAbsPath}';\n` +
         apiImport +
+        appConfigImport +
         `\n` +
         `env.current = 'server';\n` +
+        `const dev = import.meta.env.DEV;\n` +
         `const serverModules = routeServerModules(routes);\n` +
-        `const handlerOpts = { dev: import.meta.env.DEV };\n` +
+        `const pageUseResolvers = makePageUseResolvers(routes.serverRoutes, { dev });\n` +
         `\n` +
         `export const app = new Hono()\n` +
-        `  .post('/__loaders', loadersHandler(serverModules, handlerOpts))\n` +
-        `  .post('/__actions', actionsHandler(serverModules, handlerOpts))\n` +
         apiMount +
-        `  .get('*', (c) => renderPage(c, h(Layout, null, h(LocationProvider, null, h(Routes, { routes })))));\n` +
+        `  .post('/__loaders', loadersHandler(serverModules, { dev, appConfig, resolvePageUse: pageUseResolvers.byPath }))\n` +
+        `  .post('/__actions', actionsHandler(serverModules, { dev, appConfig, resolvePageUse: pageUseResolvers.byModuleKey }))\n` +
+        `  .get('*', (c) => renderPage(c, h(Layout, null, h(LocationProvider, null, h(Routes, { routes }))), { appConfig }));\n` +
         `\n` +
         `export default app;\n`);
 }
+// Framework-reserved request paths. A literal registration of either in
+// api.ts shadows the framework's RPC handler now that the user app mounts
+// ahead of them.
+const RESERVED_PATHS = new Set(['/__loaders', '/__actions']);
 const HONO_METHODS = new Set([
     'get',
     'post',
@@ -57,8 +72,8 @@ const FUNCTION_BODY_PARENTS = new Set([
     'ObjectMethod',
     'ClassMethod',
 ]);
-export function findApiCatchAllRoutes(source) {
-    const warnings = [];
+export function findApiShadowingRoutes(source) {
+    const found = [];
     let ast;
     try {
         ast = parse(source, {
@@ -70,23 +85,23 @@ export function findApiCatchAllRoutes(source) {
     catch (err) {
         // If api.ts won't parse, the build will fail elsewhere with a clearer
         // error. Surface a note so the framework user can correlate a missing
-        // catch-all warning with a parse-time syntax issue rather than wondering
+        // shadowing warning with a parse-time syntax issue rather than wondering
         // why nothing was reported.
         const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`[hono-preact] Failed to parse api.ts for catch-all route detection: ${msg}. ` +
+        console.warn(`[hono-preact] Failed to parse api.ts for shadowing-route detection: ${msg}. ` +
             `The build will surface the real syntax error; this warning explains why ` +
-            `route-overlap warnings may be missing.`);
-        return warnings;
+            `route-overlap diagnostics may be missing.`);
+        return found;
     }
-    walk(ast.program, warnings);
-    return warnings;
+    walk(ast.program, found);
+    return found;
 }
-function walk(node, warnings) {
+function walk(node, found) {
     if (!node || typeof node !== 'object')
         return;
     if (Array.isArray(node)) {
         for (const child of node)
-            walk(child, warnings);
+            walk(child, found);
         return;
     }
     const n = node;
@@ -97,19 +112,32 @@ function walk(node, warnings) {
         const method = n.callee.property.name;
         const line = n.loc?.start?.line;
         if (method === 'notFound') {
-            warnings.push({ kind: 'notFound', line });
+            found.push({ kind: 'notFound', line, severity: 'warning' });
         }
         else if (HONO_METHODS.has(method)) {
-            const firstArg = n.arguments?.[0];
-            if (firstArg?.type === 'StringLiteral' &&
-                typeof firstArg.value === 'string' &&
-                WILDCARD_PATTERNS.has(firstArg.value)) {
-                warnings.push({
-                    kind: 'wildcard',
-                    method,
-                    pattern: firstArg.value,
-                    line,
-                });
+            // `app.on(method, path, ...)` puts the path at argument index 1;
+            // every other Hono routing method takes the path as argument 0.
+            const pathArg = n.arguments?.[method === 'on' ? 1 : 0];
+            if (pathArg?.type === 'StringLiteral' &&
+                typeof pathArg.value === 'string') {
+                if (WILDCARD_PATTERNS.has(pathArg.value)) {
+                    found.push({
+                        kind: 'wildcard',
+                        method,
+                        pattern: pathArg.value,
+                        line,
+                        severity: 'error',
+                    });
+                }
+                else if (RESERVED_PATHS.has(pathArg.value)) {
+                    found.push({
+                        kind: 'reserved',
+                        method,
+                        pattern: pathArg.value,
+                        line,
+                        severity: 'error',
+                    });
+                }
             }
         }
     }
@@ -121,81 +149,136 @@ function walk(node, warnings) {
             continue;
         if (isFunctionParent && key === 'body')
             continue;
-        walk(node[key], warnings);
+        walk(node[key], found);
     }
 }
-// Project-relative path of the on-disk file the plugin writes during
-// configResolved. We use a relative path because @hono/vite-build prepends
-// `/` to the entry when constructing its `import.meta.glob([...])`, and
-// absolute paths produce a `//Users/...` double-slash that's brittle in the
-// Cloudflare Workers runtime. Project-relative keeps the resulting glob
-// pattern (`/node_modules/.vite/hono-preact/server-entry.tsx`) clean.
-//
-// We write to disk rather than register a virtual module because
-// @hono/vite-build resolves its entry via `import.meta.glob([entry])`, which
-// cannot match a `virtual:*` id. The Cloudflare Workers runtime then fails
-// with "Can't import modules from ['/virtual:...']" when it tries to load the
-// generated bundle.
-export const GENERATED_SERVER_ENTRY_RELATIVE = 'node_modules/.vite/hono-preact/server-entry.tsx';
-export function generatedServerEntryAbsPath(cwd = process.cwd()) {
-    return path.resolve(cwd, GENERATED_SERVER_ENTRY_RELATIVE);
+// Both generated files live in the Vite cache dir. The wrapper keeps the
+// `server-entry.tsx` name because that is the file the adapter's build/dev
+// plugins (and wrangler.jsonc `main`) point at; the core app module is a
+// separate file the wrapper imports.
+export const GENERATED_CORE_APP_RELATIVE = 'node_modules/.vite/hono-preact/core-app.tsx';
+export const GENERATED_ENTRY_WRAPPER_RELATIVE = 'node_modules/.vite/hono-preact/server-entry.tsx';
+export function generatedCoreAppAbsPath(cwd = process.cwd()) {
+    return path.resolve(cwd, GENERATED_CORE_APP_RELATIVE);
+}
+export function generatedEntryWrapperAbsPath(cwd = process.cwd()) {
+    return path.resolve(cwd, GENERATED_ENTRY_WRAPPER_RELATIVE);
+}
+// Returns true if the parsed program contains a top-level
+// `export default ...`. The app-config diagnostic uses this to detect a
+// common mistake: writing `export const appConfig = defineApp(...)`
+// instead of `export default defineApp(...)`. Without a default the
+// generated `import appConfig from '...'` binds to undefined and the
+// app-level middleware chain silently never runs.
+function hasDefaultExport(source) {
+    let ast;
+    try {
+        ast = parse(source, {
+            sourceType: 'module',
+            plugins: BABEL_PARSER_PLUGINS,
+            errorRecovery: true,
+        });
+    }
+    catch {
+        // Fall back to "true" on parse failure so we don't pile a misleading
+        // app-config error on top of an obvious syntax error elsewhere in the
+        // file. The real parse error surfaces from the Vite build itself.
+        return true;
+    }
+    for (const node of ast.program.body) {
+        if (node.type === 'ExportDefaultDeclaration')
+            return true;
+    }
+    return false;
 }
 export function serverEntryPlugin(opts) {
-    // Paths resolved during configResolved (cheap) — actual disk write
-    // happens in buildStart so config-only Vite invocations (IDE probes,
-    // typecheck-only runs, dependency-optimizer cold runs) don't side-effect
-    // the cache directory. Writing on every config resolution was a tax that
-    // showed up when integration tests loaded vite.config.ts to inspect the
-    // plugin chain.
-    let layoutAbsPath;
-    let routesAbsPath;
     let apiAbsPath;
+    let appConfigAbsPath;
     return {
         name: 'hono-preact:server-entry',
         enforce: 'pre',
-        configResolved(config) {
-            layoutAbsPath = path.isAbsolute(opts.layout)
+        // Write generated files in `config` -- the earliest hook -- so the entry
+        // wrapper exists before @cloudflare/vite-plugin's own `config` hook does
+        // fs.existsSync on wrangler.jsonc `main`.
+        config(userConfig) {
+            const root = userConfig.root
+                ? path.resolve(userConfig.root)
+                : process.cwd();
+            const layoutAbsPath = path.isAbsolute(opts.layout)
                 ? opts.layout
-                : path.resolve(config.root, opts.layout);
-            routesAbsPath = path.isAbsolute(opts.routes)
+                : path.resolve(root, opts.layout);
+            const routesAbsPath = path.isAbsolute(opts.routes)
                 ? opts.routes
-                : path.resolve(config.root, opts.routes);
+                : path.resolve(root, opts.routes);
             const candidateApi = path.isAbsolute(opts.api)
                 ? opts.api
-                : path.resolve(config.root, opts.api);
+                : path.resolve(root, opts.api);
             apiAbsPath = fs.existsSync(candidateApi) ? candidateApi : undefined;
-        },
-        buildStart() {
-            // configResolved must have run first. Bail loudly if not — silent
-            // emission of a stub would be much harder to debug.
-            if (!layoutAbsPath || !routesAbsPath) {
-                throw new Error('[hono-preact] server-entry buildStart fired before configResolved; ' +
-                    'layout/routes paths were never resolved.');
-            }
-            const source = generateServerEntrySource({
+            const candidateAppConfig = path.isAbsolute(opts.appConfig)
+                ? opts.appConfig
+                : path.resolve(root, opts.appConfig);
+            appConfigAbsPath = fs.existsSync(candidateAppConfig)
+                ? candidateAppConfig
+                : undefined;
+            const source = generateCoreAppModule({
                 layoutAbsPath,
                 routesAbsPath,
                 apiAbsPath,
+                appConfigAbsPath,
+            });
+            fs.mkdirSync(path.dirname(opts.coreAppPath), { recursive: true });
+            fs.writeFileSync(opts.coreAppPath, source, 'utf8');
+            const wrapper = opts.adapter.wrapEntry({
+                root,
+                coreAppModuleId: opts.coreAppPath,
+                entryWrapperId: opts.entryWrapperPath,
+                apiModuleId: apiAbsPath,
             });
-            fs.mkdirSync(path.dirname(opts.outputPath), { recursive: true });
-            fs.writeFileSync(opts.outputPath, source, 'utf8');
+            fs.writeFileSync(opts.entryWrapperPath, wrapper, 'utf8');
+        },
+        buildStart() {
+            // The api.ts shadowing diagnostic stays in buildStart: it needs
+            // this.warn / this.error, which the `config` hook context lacks.
+            // The app-config default-export diagnostic lives here for the same
+            // reason.
+            if (appConfigAbsPath) {
+                const appConfigSource = fs.readFileSync(appConfigAbsPath, 'utf8');
+                if (!hasDefaultExport(appConfigSource)) {
+                    this.error(`[hono-preact] ${appConfigAbsPath}: app-config.ts must default-export ` +
+                        `the result of defineApp(...) (e.g. ` +
+                        `\`export default defineApp({ use: [...] })\`). The generated entry ` +
+                        `does \`import appConfig from '...'\`; without a default export the ` +
+                        `import resolves to undefined and the app-level middleware chain ` +
+                        `silently never runs.`);
+                }
+            }
             if (!apiAbsPath)
                 return;
             const apiSource = fs.readFileSync(apiAbsPath, 'utf8');
-            const warnings = findApiCatchAllRoutes(apiSource);
-            for (const w of warnings) {
-                const where = `${apiAbsPath}${w.line != null ? `:${w.line}` : ''}`;
-                if (w.kind === 'notFound') {
-                    this.warn(`[hono-preact] ${where}: app.notFound(...) acts as a catch-all and ` +
-                        `will be shadowed by the framework's renderPage handler. ` +
-                        `Move the behavior to a more specific path, or accept that it won't fire.`);
+            const shadowing = findApiShadowingRoutes(apiSource);
+            const errors = [];
+            for (const r of shadowing) {
+                const where = `${apiAbsPath}${r.line != null ? `:${r.line}` : ''}`;
+                if (r.kind === 'notFound') {
+                    this.warn(`[hono-preact] ${where}: app.notFound(...) will not fire — the ` +
+                        `framework's renderPage handler matches every unmatched request. ` +
+                        `Move the behavior to a specific path, or accept that it won't fire.`);
+                }
+                else if (r.kind === 'wildcard') {
+                    errors.push(`${where}: app.${r.method}('${r.pattern}', ...) is a catch-all route`);
                 }
                 else {
-                    this.warn(`[hono-preact] ${where}: app.${w.method}('${w.pattern}', ...) is a ` +
-                        `catch-all route and will be shadowed by the framework's renderPage ` +
-                        `handler. Move it to a more specific path, or accept that it won't fire.`);
+                    errors.push(`${where}: app.${r.method}('${r.pattern}', ...) registers the ` +
+                        `framework-reserved path '${r.pattern}'`);
                 }
             }
+            if (errors.length > 0) {
+                this.error(`[hono-preact] api.ts registers routes that shadow framework handlers:\n` +
+                    errors.map((e) => `  - ${e}`).join('\n') +
+                    `\nThe framework mounts your app ahead of its reserved paths ` +
+                    `(/__loaders, /__actions) and the SSR handler, so these routes break ` +
+                    `loaders/actions and/or page rendering. Use specific, non-wildcard paths.`);
+            }
         },
     };
 }

package/dist/vite/server-exports-contract.d.ts

@@ -0,0 +1,6 @@
+export declare const RECOGNIZED_SERVER_EXPORTS: readonly ["serverActions", "serverLoaders", "pageUse", "loaderUse", "actionUse"];
+export type RecognizedServerExport = (typeof RECOGNIZED_SERVER_EXPORTS)[number];
+export declare const RECOGNIZED_SERVER_EXPORTS_SET: ReadonlySet<string>;
+export declare const RECOGNIZED_USE_EXPORTS: readonly ["pageUse", "loaderUse", "actionUse"];
+export type RecognizedUseExport = (typeof RECOGNIZED_USE_EXPORTS)[number];
+export declare const RECOGNIZED_USE_EXPORTS_SET: ReadonlySet<string>;

package/dist/vite/server-exports-contract.js

@@ -0,0 +1,43 @@
+// Single source of truth for the recognized named exports a `.server.*`
+// file may declare. Three plugins enforce this contract and used to keep
+// independent copies of the list, which drifted silently when a new name
+// was added:
+//
+// - `server-only.ts` rejects unknown specifiers when client code imports
+//   from a `.server.*` module.
+// - `server-loader-validation.ts` runs at build time on the `.server.*`
+//   file itself and rejects unknown top-level named exports.
+// - `server-loaders-parser.ts` documents the middleware-carrying subset
+//   (`pageUse`/`loaderUse`/`actionUse`) used by the route map builder.
+//
+// Centralizing the list here forces all three to agree by import.
+//
+// Status of each entry:
+// - `serverLoaders` / `serverActions`: the two value-bearing exports the
+//   handlers read at runtime.
+// - `pageUse`: page-layer middleware chain composed into the resolver map
+//   in `route-server-modules.ts`. Load-bearing.
+// - `loaderUse` / `actionUse`: reserved names for future per-file
+//   middleware. The handlers do not yet read them; per-unit middleware
+//   rides on `defineLoader({ use })` / `defineAction({ use })`. Plan
+//   item E7 may drop them in a follow-up; until then they're recognized
+//   so users who write them get an array stub on the client and a
+//   passing build instead of an opaque "unknown export" error.
+export const RECOGNIZED_SERVER_EXPORTS = [
+    'serverActions',
+    'serverLoaders',
+    'pageUse',
+    'loaderUse',
+    'actionUse',
+];
+export const RECOGNIZED_SERVER_EXPORTS_SET = new Set(RECOGNIZED_SERVER_EXPORTS);
+// Subset of RECOGNIZED_SERVER_EXPORTS that names a middleware-carrying
+// array. Used by the validation plugin to enforce that values are
+// `ArrayExpression` literals (so a typo like `pageUse = singleMw` fails
+// the build instead of silently disabling the gate at runtime).
+export const RECOGNIZED_USE_EXPORTS = [
+    'pageUse',
+    'loaderUse',
+    'actionUse',
+];
+export const RECOGNIZED_USE_EXPORTS_SET = new Set(RECOGNIZED_USE_EXPORTS);

package/dist/vite/server-loader-validation.js

@@ -1,13 +1,8 @@
 import { parse } from '@babel/parser';
 import { BABEL_PARSER_PLUGINS } from './parser-options.js';
-const ALLOWED_NAMED_EXPORTS = new Set([
-    'serverActions',
-    'actionGuards',
-    'serverLoaders',
-]);
-const ALLOWED_NAMED_EXPORTS_LIST = [...ALLOWED_NAMED_EXPORTS]
-    .map((n) => `'${n}'`)
-    .join(', ');
+import { RECOGNIZED_SERVER_EXPORTS, RECOGNIZED_SERVER_EXPORTS_SET, } from './server-exports-contract.js';
+import { findUseExports } from './server-loaders-parser.js';
+const ALLOWED_NAMED_EXPORTS_LIST = RECOGNIZED_SERVER_EXPORTS.map((n) => `'${n}'`).join(', ');
 export function serverLoaderValidationPlugin() {
     return {
         name: 'server-loader-validation',
@@ -51,7 +46,39 @@ export function serverLoaderValidationPlugin() {
                     }
                 }
             }
-            const disallowedExports = namedExports.filter((n) => !ALLOWED_NAMED_EXPORTS.has(n));
+            // F3: pageUse / loaderUse / actionUse must resolve to an array at
+            // runtime so the route-map builder and dispatcher receive a real
+            // ReadonlyArray. We can't statically prove that an identifier (e.g.
+            // `pageUse = requireSession` re-exporting an array from another
+            // module) holds an array, so we reject only the obviously-wrong
+            // literal shapes here and let the runtime guard in
+            // `makePageUseResolvers` catch indirect non-array values at first
+            // request. The literal denylist still catches the canonical typo
+            // case (`pageUse = singleMwObject`). findUseExports is shared with
+            // server-loaders-parser so the recognized-name list stays in one
+            // place.
+            const REJECTED_LITERAL_TYPES = new Set([
+                'ObjectExpression',
+                'NumericLiteral',
+                'StringLiteral',
+                'BooleanLiteral',
+                'NullLiteral',
+                'RegExpLiteral',
+                'TemplateLiteral',
+                'BigIntLiteral',
+            ]);
+            for (const useExport of findUseExports(ast.program)) {
+                if (useExport.init == null)
+                    continue;
+                if (REJECTED_LITERAL_TYPES.has(useExport.init.type)) {
+                    errors.push(`${id}: \`${useExport.name}\` must be an array literal or an ` +
+                        `identifier that points to an array ` +
+                        `(e.g. \`export const ${useExport.name} = [requireAuth]\` or ` +
+                        `\`export const ${useExport.name} = requireSession\`). ` +
+                        `A non-array value silently disables the middleware at runtime.`);
+                }
+            }
+            const disallowedExports = namedExports.filter((n) => !RECOGNIZED_SERVER_EXPORTS_SET.has(n));
             if (disallowedExports.length > 0) {
                 errors.push(`${id}: .server files may only export ${ALLOWED_NAMED_EXPORTS_LIST} as named exports (found: ${disallowedExports.join(', ')}). ` +
                     `Export the server loader as the default export only.`);

package/dist/vite/server-loaders-parser.d.ts

@@ -1,4 +1,20 @@
-import type { Program, CallExpression, ObjectExpression } from '@babel/types';
+import type { Program, CallExpression, ObjectExpression, Expression } from '@babel/types';
+export declare const RECOGNIZED_USE_EXPORTS: ReadonlySet<string>;
+export declare function hasNamedUseExport(program: Program, name: string): boolean;
+export type ParsedUseExport = {
+    /** The export name -- one of pageUse / loaderUse / actionUse. */
+    name: string;
+    /** The initializer expression, or null if `export const foo;` with no init. */
+    init: Expression | null;
+};
+/**
+ * Walk a parsed program for top-level `export const <use> = ...` declarations
+ * where `<use>` is one of the recognized middleware-carrying names
+ * (`pageUse` / `loaderUse` / `actionUse`). Returns each one with its
+ * initializer expression so callers can validate the shape (e.g. require
+ * an ArrayExpression literal).
+ */
+export declare function findUseExports(program: Program): ParsedUseExport[];
 export type ParsedLoaderEntry = {
     /** Loader name (the key in serverLoaders, e.g. "summary"). */
     name: string;

package/dist/vite/server-loaders-parser.js

@@ -1,3 +1,44 @@
+import { RECOGNIZED_USE_EXPORTS_SET } from './server-exports-contract.js';
+// Re-exported for backward compatibility. The canonical list now lives in
+// `server-exports-contract.ts` so the server-only stub plugin, the
+// validation plugin, and this parser all agree by import. New consumers
+// should import directly from the contract file.
+export const RECOGNIZED_USE_EXPORTS = RECOGNIZED_USE_EXPORTS_SET;
+export function hasNamedUseExport(program, name) {
+    for (const stmt of program.body) {
+        if (stmt.type !== 'ExportNamedDeclaration' ||
+            stmt.declaration?.type !== 'VariableDeclaration')
+            continue;
+        for (const decl of stmt.declaration.declarations) {
+            if (decl.id.type === 'Identifier' && decl.id.name === name)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Walk a parsed program for top-level `export const <use> = ...` declarations
+ * where `<use>` is one of the recognized middleware-carrying names
+ * (`pageUse` / `loaderUse` / `actionUse`). Returns each one with its
+ * initializer expression so callers can validate the shape (e.g. require
+ * an ArrayExpression literal).
+ */
+export function findUseExports(program) {
+    const found = [];
+    for (const stmt of program.body) {
+        if (stmt.type !== 'ExportNamedDeclaration' ||
+            stmt.declaration?.type !== 'VariableDeclaration')
+            continue;
+        for (const decl of stmt.declaration.declarations) {
+            if (decl.id.type !== 'Identifier')
+                continue;
+            if (!RECOGNIZED_USE_EXPORTS_SET.has(decl.id.name))
+                continue;
+            found.push({ name: decl.id.name, init: decl.init ?? null });
+        }
+    }
+    return found;
+}
 /**
  * Walk a parsed program for `export const serverLoaders = { name: defineLoader(fn, opts?), ... }`.
  * Returns one entry per object property whose value is a defineLoader(...) call.

package/dist/vite/server-only.js

@@ -5,6 +5,11 @@ import MagicString from 'magic-string';
 import { deriveModuleKey } from './module-key.js';
 import { parseServerLoaders, readParamsOpt } from './server-loaders-parser.js';
 import { BABEL_PARSER_PLUGINS } from './parser-options.js';
+import { RECOGNIZED_SERVER_EXPORTS } from './server-exports-contract.js';
+// The unknown-specifier rejection message lists every recognized server
+// export so a user can immediately see the valid set. The list is derived
+// from the shared contract so it cannot drift from the validation plugin.
+const ALLOWED_SPECIFIERS_LIST = RECOGNIZED_SERVER_EXPORTS.join(', ');
 // Symbol-keyed accessor used by unit tests to verify `configResolved` fires
 // and captures the root. Hidden behind a Symbol so it does not appear in IDE
 // autocomplete for the public Plugin surface.
@@ -184,13 +189,26 @@ export function serverOnlyPlugin() {
                     }
                     else if (specifier.type === 'ImportSpecifier' &&
                         specifier.imported.type === 'Identifier' &&
-                        specifier.imported.name === 'actionGuards') {
+                        (specifier.imported.name === 'pageUse' ||
+                            specifier.imported.name === 'loaderUse' ||
+                            specifier.imported.name === 'actionUse')) {
+                        // Middleware-carrying named exports never run on the client; the
+                        // client only needs the array to exist so user imports don't
+                        // crash. The real `use` arrays live on the server side and are
+                        // wired into the dispatcher via pageUse resolvers.
                         stubs.push(`const ${specifier.local.name} = [];`);
                     }
                     else if (specifier.type === 'ImportSpecifier' &&
                         specifier.imported.type === 'Identifier' &&
                         specifier.imported.name === 'serverActions') {
                         needsUseActionImport = true;
+                        // F9: each `serverActions.<name>` read constructs a fresh
+                        // stub object, so `serverActions.create !== serverActions.create`
+                        // across two reads. Not new in the middleware refactor, but
+                        // worth flagging: callers that store the stub in a variable
+                        // and treat it as a stable identity (e.g. `Map` keys) will
+                        // surprise themselves. The contract is "stubs are descriptor
+                        // records, not singletons."
                         stubs.push(`const ${specifier.local.name} = new Proxy({}, {\n` +
                             `  get(_, action) {\n` +
                             `    const stub = { __module: ${JSON.stringify(moduleKey)}, __action: String(action) };\n` +
@@ -207,7 +225,7 @@ export function serverOnlyPlugin() {
                                 ? '* as ' + specifier.local.name
                                 : '<unknown>';
                         throw new Error(`${id}: \`${importedName}\` is not a recognized export from a *.server.* module. ` +
-                            `Allowed: serverLoaders, serverActions, actionGuards.`);
+                            `Allowed: ${ALLOWED_SPECIFIERS_LIST}.`);
                     }
                 }
                 if (stubs.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-preact",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Hono on the edge, Preact in the browser, manifest driven routes, typed RPC, streaming everywhere.",
   "keywords": [
     "hono",
@@ -36,6 +36,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./page": {
+      "types": "./dist/page.d.ts",
+      "import": "./dist/page.js"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js"
@@ -44,6 +48,14 @@
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
     },
+    "./adapter-cloudflare": {
+      "types": "./dist/adapter-cloudflare.d.ts",
+      "import": "./dist/adapter-cloudflare.js"
+    },
+    "./adapter-node": {
+      "types": "./dist/adapter-node.d.ts",
+      "import": "./dist/adapter-node.js"
+    },
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
@@ -52,18 +64,34 @@
   "dependencies": {
     "@babel/parser": "^7.29.2",
     "@babel/types": "^7.29.0",
-    "@hono/vite-build": "^1.11.1",
-    "@hono/vite-dev-server": "^0.25.1",
     "@preact/preset-vite": "^2.10.5",
     "magic-string": "^0.30.21"
   },
   "peerDependencies": {
+    "@cloudflare/vite-plugin": "^1.37.1",
+    "@hono/node-server": "^1.19.14",
+    "@hono/node-ws": "^1.3.1",
     "hono": ">=4.0.0",
     "hoofd": ">=1.0.0",
     "preact": ">=10.0.0",
     "preact-iso": ">=2.11.0",
     "preact-render-to-string": ">=6.0.0",
-    "vite": ">=5.0.0"
+    "vite": ">=6.0.0",
+    "wrangler": "^4.92.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/vite-plugin": {
+      "optional": true
+    },
+    "@hono/node-server": {
+      "optional": true
+    },
+    "@hono/node-ws": {
+      "optional": true
+    },
+    "wrangler": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "typescript": "*",