hono-svelte 0.4.2 → 0.6.1

package/dist/cli.js

@@ -4,7 +4,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { doctorChecks, checkAppLink, initFiles, isSafeAppPath, } from "./scaffold.js";
+import { checkAppLink, doctorChecks, initFiles, isSafeAppPath, newPageFile, } from "./scaffold.js";
 const args = process.argv.slice(2);
 const command = args[0];
 function flagValue(name) {
@@ -36,18 +36,48 @@ function init() {
     }
     console.log(`[hono-svelte] done (${flavor}). Next:`);
     if (flavor === "minimal") {
-        console.log(`  1. npm install   (or: bun install)`);
-        console.log(`  2. npm run dev   (or: bun run dev)`);
+        console.log(`  1. bun install`);
+        console.log(`  2. bun run dev   (or: bun --bun run dev)`);
         console.log(`  Tip: --full scaffolds auth + dashboard + layout + typed RPC.`);
     }
     else {
-        console.log(`  1. npm install   (or: bun install)`);
-        console.log(`  2. npm run dev   (or: bun run dev)   →  /auth → /dashboard`);
+        console.log(`  1. bun install`);
+        console.log(`  2. bun run dev   (or: bun --bun run dev)   →  /auth → /dashboard`);
     }
 }
 function packageRootForCli() {
     return join(dirname(fileURLToPath(import.meta.url)), "..");
 }
+function addPage() {
+    const name = args[2];
+    if (!name) {
+        console.error("[hono-svelte] usage: hono-svelte add page <name> (e.g. blog/post-1)");
+        process.exitCode = 1;
+        return;
+    }
+    const file = newPageFile(name);
+    if (!file) {
+        console.error(`[hono-svelte] invalid page name: ${name} — use a relative entry name like "blog/post-1" (no ../, no leading /, not "layout")`);
+        process.exitCode = 1;
+        return;
+    }
+    const dest = join(appRoot, file.path);
+    if (!isSafeAppPath(appRoot, dest)) {
+        console.error(`[hono-svelte] refusing to write outside ${appRoot}: ${file.path}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (existsSync(dest)) {
+        console.log(`[hono-svelte] exists, skipping: ${file.path}`);
+        return;
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, file.content);
+    const entryName = file.path.replace(/^src\/pages\//, "").replace(/\.svelte$/, "");
+    console.log(`[hono-svelte] wrote ${file.path}`);
+    console.log(`[hono-svelte] next: render it from a route — c.render("${entryName}")`);
+    console.log(`[hono-svelte] (default pagesDir is src/pages; set a custom one via pages({ pagesDir }))`);
+}
 function doctor() {
     const packageRoot = packageRootForCli();
     const issues = doctorChecks({ packageRoot, appRoot });
@@ -68,8 +98,12 @@ if (command === "init")
     init();
 else if (command === "doctor")
     doctor();
+else if (command === "add" && args[1] === "page")
+    addPage();
 else {
-    console.log("Usage: hono-svelte <init|doctor> [--app=<dir>] [--full]");
-    console.log("  init [--full]   scaffold a runnable app (minimal by default)");
+    console.log("Usage: hono-svelte <init|doctor|add page <name>> [--app=<dir>] [--full]");
+    console.log("  init [--full]            scaffold a runnable app (minimal by default)");
+    console.log("  add page <name>          create src/pages/<name>.svelte (static, zero JS)");
+    console.log("  doctor [--app=<dir>]     check dist, link and vite config");
     process.exitCode = 1;
 }

package/dist/handlers.d.ts

@@ -1,16 +1,38 @@
 import type { HeadProps } from "./head.js";
+/** Data every error page receives (merged under `opts.data`). */
+export type ErrorPageData = {
+    status: number;
+    message: string;
+};
 export type ErrorPageOptions = {
     /** Entry name. @default "404" (not-found) / "500" (error) */
     entry?: string;
     title?: string;
+    /** Extra page data, merged over `{ status, message }`. */
     data?: Record<string, unknown>;
     head?: string | HeadProps;
+    /**
+     * Answer `{ message }` JSON with the same status instead of rendering the
+     * page — e.g. `(c) => c.req.path.startsWith("/api/")` so API clients never
+     * get an HTML document.
+     */
+    json?: (c: any) => boolean;
 };
 /** Hono `notFound` handler: `app.notFound(notFoundHandler())`. */
-export declare function notFoundHandler(opts?: ErrorPageOptions): (c: any) => any;
+export declare function notFoundHandler(opts?: ErrorPageOptions & {
+    message?: string;
+}): (c: any) => Response | Promise<Response>;
 export type ServerErrorHandlerOptions = ErrorPageOptions & {
     /** Log the error. `true` = `console.error`. @default true */
     log?: boolean | ((err: unknown) => void);
+    /** Message for errors whose own message is not exposed. @default "Internal Server Error" */
+    message?: string;
+    /**
+     * Whether the error's own message reaches the page/JSON. Default: only for
+     * errors carrying a 4xx `status` (e.g. hono's `HTTPException(404, …)`) —
+     * 5xx and unknown errors get `message`, never internals.
+     */
+    expose?: (err: Error, status: number) => boolean;
 };
 /** Hono `onError` handler: `app.onError(errorHandler())`. */
-export declare function errorHandler(opts?: ServerErrorHandlerOptions): (err: unknown, c: any) => any;
+export declare function errorHandler(opts?: ServerErrorHandlerOptions): (err: Error, c: any) => Response | Promise<Response>;

package/dist/handlers.js

@@ -1,31 +1,74 @@
 // Conventional error-page handlers: `404.svelte` / `500.svelte` pages
 // rendered with the matching HTTP status.
+//
+// The context parameter stays `any` ON PURPOSE — validated empirically:
+// typing it with hono types works with a single hono copy (and even with
+// duplicate copies of the same version), but breaks when the consumer's
+// resolution picks a hono copy with a DIFFERENT version than the one this
+// package's d.ts resolves to (file:/npm-link/monorepo setups — e.g.
+// app hono 4.13.7 vs package types 4.13.8 fail on `[GET_MATCH_RESULT]`
+// symbol members). hono's `Context<any, ...>` default is not a supertype of
+// concrete contexts either. `any` keeps the handlers assignable in every
+// copy/version layout; everything else (return type, the render call) is
+// typed via the narrow cast below.
+function entryRender(c) {
+    return c.render;
+}
+function respond(c, opts, entry, page, headers) {
+    if (opts.json?.(c)) {
+        return c.json({ message: page.message }, page.status, headers);
+    }
+    return entryRender(c)(entry, {
+        title: opts.title,
+        data: { ...page, ...opts.data },
+        head: opts.head,
+        status: page.status,
+        ...(headers ? { headers } : {}),
+    });
+}
+/**
+ * Headers of the response carried by the error — hono's `HTTPException(401, { res })`
+ * (`basicAuth`, `bearerAuth`) carries `WWW-Authenticate` there. Body headers are
+ * dropped: the page/JSON replaces the body.
+ */
+function headersOf(err) {
+    const res = err.res;
+    if (!(res instanceof Response))
+        return undefined;
+    const out = {};
+    res.headers.forEach((value, name) => {
+        if (name !== "content-type" && name !== "content-length")
+            out[name] = value;
+    });
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 /** Hono `notFound` handler: `app.notFound(notFoundHandler())`. */
 export function notFoundHandler(opts = {}) {
     const entry = opts.entry ?? "404";
-    return (c) => {
-        return c.render(entry, {
-            title: opts.title,
-            data: opts.data,
-            head: opts.head,
-            status: 404,
-        });
-    };
+    const message = opts.message ?? "Not Found";
+    // See the file header for why the context param stays `any`.
+    return (c) => respond(c, opts, entry, { status: 404, message });
+}
+/** HTTP status carried by the error (hono's `HTTPException` and friends), else 500. */
+function statusOf(err) {
+    const status = err.status;
+    return typeof status === "number" && Number.isInteger(status) && status >= 400 && status <= 599 ? status : 500;
 }
 /** Hono `onError` handler: `app.onError(errorHandler())`. */
 export function errorHandler(opts = {}) {
     const entry = opts.entry ?? "500";
     const log = opts.log ?? true;
+    const fallback = opts.message ?? "Internal Server Error";
+    const expose = opts.expose ?? ((_err, status) => status < 500);
     return (err, c) => {
-        if (log === true)
-            console.error(err);
-        else if (typeof log === "function")
-            log(err);
-        return c.render(entry, {
-            title: opts.title,
-            data: opts.data,
-            head: opts.head,
-            status: 500,
-        });
+        const status = statusOf(err);
+        if (status >= 500) {
+            if (log === true)
+                console.error(err);
+            else if (typeof log === "function")
+                log(err);
+        }
+        const message = expose(err, status) && err.message ? err.message : fallback;
+        return respond(c, opts, entry, { status, message }, headersOf(err));
     };
 }

package/dist/index.d.ts

@@ -1,22 +1,43 @@
 import type { Next } from "hono";
 import { type AssetsResolver, type ViteManifest } from "./assets.js";
 import { type HeadProps } from "./head.js";
-export { getIds } from "./ids.js";
-export type { SharedIds } from "./ids.js";
-export { renderHead } from "./head.js";
-export type { HeadMetaItem, HeadProps } from "./head.js";
 export { CACHE_IMMUTABLE, CACHE_NO_STORE, createManifestAssets, immutableHeaders, manifestCssFor, manifestImportsFor, manifestKeysFor, } from "./assets.js";
 export type { AssetsResolver, ManifestAssetsOptions, ViteManifest, ViteManifestChunk, } from "./assets.js";
-export { notFoundHandler, errorHandler } from "./handlers.js";
-export type { ErrorPageOptions, ServerErrorHandlerOptions } from "./handlers.js";
-export { initFiles, doctorChecks, checkAppLink, versionsMatch, isSafeAppPath } from "./scaffold.js";
+export { errorHandler, notFoundHandler } from "./handlers.js";
+export type { ErrorPageData, ErrorPageOptions, ServerErrorHandlerOptions } from "./handlers.js";
+export { renderHead } from "./head.js";
+export type { HeadMetaItem, HeadProps } from "./head.js";
+export { getIds } from "./ids.js";
+export type { PageInfo } from "./page.js";
+export type { SharedIds } from "./ids.js";
+export { checkAppLink, doctorChecks, initFiles, isSafeAppPath, isValidPageName, newPageFile } from "./scaffold.js";
 export type { DoctorIssue, DoctorOptions, InitFile, InitFlavor } from "./scaffold.js";
 export type SsrPageLoader = () => Promise<{
     default: unknown;
 }>;
-export type RenderProps = {
+/**
+ * Type registry filled by the generated `.d.ts` (`pages({ dts: true })`):
+ *
+ * ```ts
+ * declare module "hono-svelte" {
+ *   interface Register { entries: "index" | "dashboard/index" }
+ * }
+ * ```
+ */
+export interface Register {
+}
+/**
+ * Page entry names accepted by `c.render`. The union from the generated
+ * `.d.ts` once it is part of the program; plain `string` without it.
+ * Use it to type helpers that forward an entry to `c.render`:
+ * `function page(entry: Entry) { … }`.
+ */
+export type Entry = Register extends {
+    entries: infer E extends string;
+} ? E : string;
+export type RenderProps<TData = Record<string, unknown>> = {
     title?: string;
-    data?: Record<string, unknown>;
+    data?: TData;
     /** HTTP status of the shell response. @default 200 */
     status?: number;
     /** Extra response headers merged into the shell response. */
@@ -39,6 +60,15 @@ export type ShellOptions = {
     /** Extra CSS links per HTML response. Strings are hrefs verbatim. */
     styles?: string[];
     stylesHref?: string | ((isProd: boolean) => string);
+    /**
+     * Source path of the global stylesheet, relative to the Vite root — the
+     * same file passed to the client build input. Dev links `/<stylesEntry>`
+     * (served by Vite); prod resolves the hashed file from the manifest given
+     * in `assets`, falling back to `/static/styles.css`. `stylesHref` wins
+     * when set.
+     * @default "src/styles.css"
+     */
+    stylesEntry?: string;
     /** Global head HTML (fonts, meta) — page `head` prop is appended after it. */
     head?: string;
     /**
@@ -69,6 +99,11 @@ export type ShellOptions = {
     knownEntries?: string[];
     /** `false` disables unknown-entry validation. @default true */
     strict?: boolean;
+    /**
+     * When SSR of a page throws at request time: log the error and fall back
+     * to client rendering (entry script) instead of a 500. @default false
+     */
+    ssrFallback?: boolean;
     /** Default status when `c.render(entry)` omits it. @default 200 */
     status?: number;
     /** Default headers merged into every shell response. */
@@ -78,6 +113,13 @@ export type ShellOptions = {
      * (`import.meta.env.PROD`, else `NODE_ENV === "production"`).
      */
     isProd?: boolean;
+    /**
+     * Extra attributes on `<html>` (`lang` comes from the `lang` option), e.g.
+     * `{ "data-theme": "dark" }` for DaisyUI themes. A function receives the
+     * Hono context (per-request theme from a cookie). Values are escaped;
+     * invalid attribute names throw.
+     */
+    htmlAttributes?: Record<string, string> | ((c: unknown) => Record<string, string>);
 };
 export type ShellContext = {
     render: (entryName: string, props?: RenderProps) => Response | Promise<Response>;

package/dist/index.js

@@ -1,13 +1,14 @@
 import { createManifestAssets, manifestCssFor, manifestImportsFor, } from "./assets.js";
 import { renderHead } from "./head.js";
 import { getIds } from "./ids.js";
+import { PAGE_ATTRIBUTES, pageContext } from "./page.js";
 import { allEntries as autoAllEntries, ssrLayouts as autoSsrLayouts, ssrPages as autoSsrPages, } from "./ssr-manifest.js";
 import { devEntryUrl } from "./virtual.js";
-export { getIds } from "./ids.js";
-export { renderHead } from "./head.js";
 export { CACHE_IMMUTABLE, CACHE_NO_STORE, createManifestAssets, immutableHeaders, manifestCssFor, manifestImportsFor, manifestKeysFor, } from "./assets.js";
-export { notFoundHandler, errorHandler } from "./handlers.js";
-export { initFiles, doctorChecks, checkAppLink, versionsMatch, isSafeAppPath } from "./scaffold.js";
+export { errorHandler, notFoundHandler } from "./handlers.js";
+export { renderHead } from "./head.js";
+export { getIds } from "./ids.js";
+export { checkAppLink, doctorChecks, initFiles, isSafeAppPath, isValidPageName, newPageFile } from "./scaffold.js";
 function escapeAttr(value) {
     return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
@@ -21,10 +22,46 @@ function isValidEntryName(entryName) {
     const parts = entryName.split("/");
     return parts.every((p) => p.length > 0 && p !== "." && p !== ".." && !p.includes(String.fromCharCode(0)));
 }
+const TITLE_TAG = /<title\b[^>]*>[\s\S]*?<\/title>/gi;
+const DESCRIPTION_META = /<meta\b(?=[^>]*\bname=["']description["'])[^>]*>/gi;
+/**
+ * One `<title>` / `<meta name="description">` per document, page first.
+ * Browsers use the FIRST `<title>`, so the shell default used to beat the
+ * page's `<svelte:head>`. Precedence: `c.render(entry, { title })` > the
+ * page/layout `<svelte:head>` > `shell({ title })`; for the description,
+ * the page (`<svelte:head>` or `props.head`) > `shell({ head })`.
+ */
+function resolveHeadConflicts(input) {
+    let { shellHead, ssrHead } = input;
+    const pageHasTitle = new RegExp(TITLE_TAG.source, "i").test(ssrHead);
+    let title = "";
+    if (input.explicitTitle !== undefined) {
+        title = `<title>${escapeAttr(input.explicitTitle)}</title>`;
+        ssrHead = ssrHead.replace(TITLE_TAG, "");
+    }
+    else if (!pageHasTitle) {
+        title = `<title>${escapeAttr(input.shellTitle)}</title>`;
+    }
+    if (new RegExp(DESCRIPTION_META.source, "i").test(ssrHead + input.pageHead)) {
+        shellHead = shellHead.replace(DESCRIPTION_META, "");
+    }
+    return { title, shellHead, ssrHead };
+}
+const ATTRIBUTE_NAME = /^[A-Za-z_:][-A-Za-z0-9_:.]*$/;
+function renderAttributes(attributes) {
+    let out = "";
+    for (const [name, value] of Object.entries(attributes)) {
+        if (!ATTRIBUTE_NAME.test(name) || name.toLowerCase() === "lang") {
+            throw new Error(`hono-svelte: invalid htmlAttributes name: ${JSON.stringify(name)} (use the lang option for lang)`);
+        }
+        out += ` ${name}="${escapeAttr(String(value))}"`;
+    }
+    return out;
+}
 function nonceAttr(nonce) {
     return nonce ? ` nonce="${escapeAttr(nonce)}"` : "";
 }
-function serializePageData(data, dataId, dataLimit) {
+function serializePageData(entryName, data, dataId, dataLimit) {
     if (!data)
         return { json: "", html: "" };
     let json;
@@ -36,7 +73,7 @@ function serializePageData(data, dataId, dataLimit) {
     }
     if (json === undefined)
         return { json: "", html: "" };
-    checkDataLimit(json, dataLimit);
+    checkDataLimit(entryName, json, dataLimit);
     const safe = json.replace(/</g, "\\u003c");
     const lt = String.fromCharCode(60);
     return {
@@ -45,19 +82,21 @@ function serializePageData(data, dataId, dataLimit) {
     };
 }
 const warnedDataLimit = new Set();
-function checkDataLimit(json, dataLimit) {
+function checkDataLimit(entryName, json, dataLimit) {
     if (dataLimit === false)
         return;
     const bytes = new TextEncoder().encode(json).length;
     if (bytes <= dataLimit)
         return;
-    const key = String(dataLimit);
+    // One warning per (page, limit): a second page over the limit must still
+    // be reported (the key used to be just the limit — one warn per process).
+    const key = entryName + ":" + String(dataLimit);
     if (warnedDataLimit.has(key))
         return;
     warnedDataLimit.add(key);
     const kb = (bytes / 1024).toFixed(1);
     const limitKb = (dataLimit / 1024).toFixed(0);
-    console.warn(`[hono-svelte] page data is ${kb}KB (limit ${limitKb}KB). ` +
+    console.warn(`[hono-svelte] page "${entryName}" data is ${kb}KB (limit ${limitKb}KB). ` +
         `data is inlined in the HTML — move large/sensitive payloads to a typed API (hc<AppType>).`);
 }
 /** Visible for tests. */
@@ -84,7 +123,8 @@ function detectProd() {
         // plain node / vitest: no import.meta.env — bundled server is prod
         return true;
     }
-    return globalThis.process?.env?.NODE_ENV === "production";
+    return (globalThis.process?.env?.NODE_ENV ===
+        "production");
 }
 function isDev() {
     try {
@@ -95,7 +135,8 @@ function isDev() {
         // plain node / vitest
         return false;
     }
-    return globalThis.process?.env?.NODE_ENV !== "production";
+    return (globalThis.process?.env?.NODE_ENV !==
+        "production");
 }
 function defaultKnownEntries(ssrPages) {
     const keys = Object.keys(ssrPages);
@@ -134,18 +175,23 @@ function prefetchHoverScript(nonce, dataId, urls) {
     if (urls.length === 0)
         return "";
     const lt = String.fromCharCode(60);
-    const map = JSON.stringify(Object.fromEntries(urls.map((u) => [u.entry, u.url])));
+    const map = JSON.stringify(Object.fromEntries(urls.map((u) => [u.entry, u.url]))).replace(/</g, "\\u003c");
+    // Links map to entries by path: "/" -> "index", "/a" -> "a" or "a/index".
     const code = `(function(){var m=${map};` +
-        `function pre(u){if(document.querySelector('link[rel=\"prefetch\"][href=\"'+u+'\"]'))return;` +
-        `var l=document.createElement('link');l.rel='prefetch';l.href=u;document.head.appendChild(l);}` +
+        `function pre(u){if(document.querySelector('link[rel=\"modulepreload\"][href=\"'+u+'\"]'))return;` +
+        `var l=document.createElement('link');l.rel='modulepreload';l.href=u;document.head.appendChild(l);}` +
         `document.addEventListener('mouseover',function(e){var a=e.target&&e.target.closest?e.target.closest('a[href]'):null;` +
-        `if(!a)return;try{var p=new URL(a.href,location.origin).pathname.replace(/^\\//,'');` +
-        `var u=m[p];if(u)pre(u);}catch(_){}},{passive:true});})();`;
+        `if(!a)return;try{var p=new URL(a.href,location.origin).pathname.replace(/^\\/+|\\/+$/g,'');` +
+        `var u=m[p]||m[p?p+'/index':'index'];if(u)pre(u);}catch(_){}},{passive:true});})();`;
     return lt + `script${nonceAttr(nonce)}>${code}` + lt + "/script>";
 }
 export function shell(options = {}) {
     const titleDefault = options.title ?? "App";
     const lang = options.lang ?? "en";
+    const htmlAttributes = (c) => {
+        const attrs = typeof options.htmlAttributes === "function" ? options.htmlAttributes(c) : options.htmlAttributes;
+        return attrs ? renderAttributes(attrs) : "";
+    };
     const assetsBase = (options.assetsBase ?? "/static").replace(/\/$/, "");
     const assetsOpt = options.assets ?? assetsBase;
     const head = options.head ?? "";
@@ -153,10 +199,18 @@ export function shell(options = {}) {
     const defaultHeaders = options.headers ?? {};
     const dataLimit = options.dataLimit ?? 102400;
     const strict = options.strict ?? true;
+    const ssrFallback = options.ssrFallback ?? false;
     const extraStyles = options.styles ?? [];
     const resolveStyles = typeof options.stylesHref === "function"
         ? options.stylesHref
         : () => options.stylesHref;
+    const stylesEntry = (options.stylesEntry ?? "src/styles.css").replace(/^\/+/, "");
+    function defaultStylesHref(isProd) {
+        if (!isProd)
+            return "/" + stylesEntry;
+        const file = manifestFor(assetsOpt)?.[stylesEntry]?.file;
+        return file ? "/" + file.replace(/^\/+/, "") : `${assetsBase}/styles.css`;
+    }
     // Zero config: with pages() active, this module is redirected to the
     // in-memory manifest by the plugin's resolveId (enforce: "pre").
     const ssrPages = options.ssrPages ?? autoSsrPages;
@@ -212,13 +266,15 @@ export function shell(options = {}) {
             try {
                 return options.nonce(c) ?? undefined;
             }
-            catch {
+            catch (err) {
+                // Without a nonce the CSP blocks every shell script — never fail silently.
+                console.error("[hono-svelte] nonce() threw — rendering without a nonce:", err);
                 return undefined;
             }
         }
         return options.nonce;
     }
-    async function renderSsrBody(loader, pageData, nonce, layoutChain) {
+    async function renderSsrBody(loader, pageData, nonce, layoutChain, page) {
         const mod = await loader();
         const { render } = await import("svelte/server");
         const renderOpts = {};
@@ -226,12 +282,14 @@ export function shell(options = {}) {
             renderOpts.props = pageData;
         if (nonce)
             renderOpts.csp = { nonce };
+        renderOpts.context = pageContext(page);
         const rendered = render(mod.default, renderOpts);
         let html = rendered.html ?? rendered.body ?? "";
         let headValue = typeof rendered.head === "function" ? rendered.head() : (rendered.head ?? "");
         if (layoutChain.length > 0) {
             const { createRawSnippet } = await import("svelte");
-            for (const layoutLoader of layoutChain) {
+            // The chain is outermost first; wrapping goes inside out.
+            for (const layoutLoader of [...layoutChain].reverse()) {
                 const layoutMod = await layoutLoader();
                 const childHtml = html;
                 // The snippet MUST render a single wrapper element: the server
@@ -241,9 +299,9 @@ export function shell(options = {}) {
                 // is hydration-safe (hydrate reuses SSR DOM).
                 const childSnippet = createRawSnippet(() => ({ render: () => `<div>${childHtml}</div>` }));
                 const wrapped = render(layoutMod.default, {
-                    ...(pageData !== undefined ? { props: pageData } : {}),
-                    props: { ...(pageData ?? {}), children: childSnippet },
+                    props: { ...pageData, children: childSnippet },
                     ...(nonce ? { csp: { nonce } } : {}),
+                    context: pageContext(page),
                 });
                 html = wrapped.html ?? wrapped.body ?? "";
                 const layoutHead = typeof wrapped.head === "function" ? wrapped.head() : (wrapped.head ?? "");
@@ -252,7 +310,18 @@ export function shell(options = {}) {
         }
         return { html, head: headValue };
     }
-    async function inner(c, next) {
+    // The context param stays `any` ON PURPOSE — validated empirically:
+    // typing it (MiddlewareHandler / Context / generics) works with a single
+    // hono copy and even with duplicate copies of the SAME version, but breaks
+    // when the consumer's resolution picks a hono copy with a different version
+    // than the one this package's d.ts resolves to (file:/npm-link/monorepo
+    // topologies — e.g. app hono 4.13.7 vs package types 4.13.8 fail with
+    // `[GET_MATCH_RESULT]`-symbol mismatches). A d.ts free of hono type
+    // references is immune to any copy/version layout. The
+    // render/setRenderer boundary needs casts regardless (hono's default
+    // Renderer only accepts string content), so `any` here costs no real
+    // type safety — the casts carry the correctness burden.
+    const inner = async (c, next) => {
         c.setRenderer(async (entryName, props) => {
             if (!isValidEntryName(entryName)) {
                 throw new Error(`hono-svelte: invalid entryName: ${JSON.stringify(entryName)}`);
@@ -265,7 +334,7 @@ export function shell(options = {}) {
             const chain = layoutChainFor(entryName)
                 .map((l) => ssrLayouts[l])
                 .filter((l) => l !== undefined);
-            const isSsr = loader !== undefined && !hasClientEntry(entryName);
+            let isSsr = loader !== undefined && !hasClientEntry(entryName);
             if (strict && !isSsr) {
                 const known = availableEntries();
                 if (known && !known.includes(entryName)) {
@@ -273,19 +342,29 @@ export function shell(options = {}) {
                 }
             }
             const ids = getIds(entryName);
-            const title = props?.title ?? titleDefault;
+            const page = { path: c.req.path, route: c.req.routePath ?? c.req.path };
             const isProd = options.isProd ?? detectProd();
             const nonce = resolveNonce(c);
             const nAttr = nonceAttr(nonce);
-            const stylesHref = resolveStyles(isProd) ?? (isProd ? "/static/styles.css" : "/src/styles.css");
-            const { html: dataHtml } = serializePageData(props?.data, ids.dataId, dataLimit);
+            const stylesHref = resolveStyles(isProd) ?? defaultStylesHref(isProd);
+            const { html: dataHtml } = serializePageData(entryName, props?.data, ids.dataId, dataLimit);
             const lt = String.fromCharCode(60);
             let bodyHtml = "";
             let ssrHead = "";
             if (isSsr) {
-                const rendered = await renderSsrBody(loader, props?.data, nonce, chain);
-                bodyHtml = rendered.html;
-                ssrHead = rendered.head;
+                try {
+                    const rendered = await renderSsrBody(loader, props?.data, nonce, chain, page);
+                    bodyHtml = rendered.html;
+                    ssrHead = rendered.head;
+                }
+                catch (err) {
+                    if (!ssrFallback)
+                        throw err;
+                    console.error(`[hono-svelte] SSR failed for "${entryName}" — falling back to client rendering:`, err);
+                    bodyHtml = "";
+                    ssrHead = "";
+                    isSsr = false;
+                }
             }
             const resolveUrl = (entry) => isProd ? resolveAssetUrl(assetsOpt, assetsBase, entry) : devEntryUrl(entry);
             let scriptHtml = "";
@@ -293,7 +372,8 @@ export function shell(options = {}) {
             let prefetchHtml = "";
             if (!isSsr) {
                 const src = resolveUrl(entryName);
-                scriptHtml = lt + `script type="module" src="${escapeAttr(src)}"${nAttr}>` + lt + "/script>";
+                scriptHtml =
+                    lt + `script type="module" src="${escapeAttr(src)}"${nAttr}>` + lt + "/script>";
                 const shouldPreload = options.preload ?? isProd;
                 const manifest = isProd ? manifestFor(assetsOpt) : undefined;
                 if (shouldPreload) {
@@ -309,20 +389,21 @@ export function shell(options = {}) {
                         .join("");
                 }
                 if (isProd && options.prefetch) {
-                    const known = availableEntries();
+                    // Only client entries have a JS chunk; static pages are SSR-only.
+                    const known = availableEntries()?.filter((e) => e !== entryName && (hasClientEntry(e) || ssrPages[e] === undefined));
                     if (options.prefetch === "all" && known) {
                         for (const u of prefetchUrls("all", entryName, known, resolveUrl)) {
-                            prefetchHtml += lt + `link rel="prefetch" href="${escapeAttr(u)}"${nAttr} />`;
+                            prefetchHtml += lt + `link rel="modulepreload" href="${escapeAttr(u)}"${nAttr} />`;
                         }
                     }
                     else if (options.prefetch === "hover" && known) {
-                        const others = known.filter((e) => e !== entryName && ssrPages[e] === undefined);
+                        const others = known;
                         prefetchHtml = prefetchHoverScript(nonce, ids.dataId, others.map((e) => ({ entry: e, url: resolveUrl(e) })));
                     }
                 }
             }
             const status = props?.status ?? defaultStatus;
-            const headers = { ...defaultHeaders, ...(props?.headers ?? {}) };
+            const headers = { ...defaultHeaders, ...props?.headers };
             const pageHead = props?.head !== undefined ? renderHead(props.head) : "";
             const manifestNow = isProd ? manifestFor(assetsOpt) : undefined;
             const cssLinks = (manifestNow ? manifestCssFor(manifestNow, entryName) : [])
@@ -331,27 +412,31 @@ export function shell(options = {}) {
                 extraStyles
                     .map((href) => lt + `link rel="stylesheet" href="${escapeAttr(href)}"${nAttr} />`)
                     .join("");
-            return c.html(`<!doctype html><html lang="${escapeAttr(lang)}"><head><title>${escapeAttr(title)}</title>` +
+            const resolvedHead = resolveHeadConflicts({
+                shellTitle: titleDefault,
+                explicitTitle: props?.title,
+                shellHead: head,
+                ssrHead,
+                pageHead,
+            });
+            return c.html(`<!doctype html><html lang="${escapeAttr(lang)}"${htmlAttributes(c)}><head>${resolvedHead.title}` +
                 `<meta charset="utf-8" /><meta content="width=device-width, initial-scale=1" name="viewport" />` +
-                (head ? head : "") +
+                resolvedHead.shellHead +
                 `<link rel="stylesheet" href="${escapeAttr(stylesHref)}"${nAttr} />` +
                 cssLinks +
-                ssrHead +
+                resolvedHead.ssrHead +
                 pageHead +
                 preloadHtml +
                 prefetchHtml +
                 scriptHtml +
                 `</head>` +
-                `<body class="bg-base-200 min-h-screen text-base-content"><div id="${ids.rootId}">${bodyHtml}</div>` +
+                `<body><div id="${ids.rootId}" ${PAGE_ATTRIBUTES.path}="${escapeAttr(page.path)}" ${PAGE_ATTRIBUTES.route}="${escapeAttr(page.route)}">${bodyHtml}</div>` +
                 dataHtml +
                 `</body></html>`, status, headers);
         });
         await next();
-    }
-    async function shellMiddleware(c, next) {
-        return inner(c, next);
-    }
-    const mw = shellMiddleware;
+    };
+    const mw = inner;
     mw.availableEntries = availableEntries;
     return mw;
 }