hono-svelte 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,23 +1,67 @@
-# Changelog
-
-## 0.3.1
-
-- Package metadata: repository/homepage/author, publishConfig, LICENSE + CHANGELOG in files.
-- No code changes since 0.3.0.
-
-## 0.3.0
-
-- Fully in-memory package: entries and manifest are virtual modules (no files written to disk).
-- Automatic zero-JS: `.svelte` pages without `<script>` render on the server (`svelte/server`)
-  and download no JS on the client.
-- Deterministic opaque IDs derived from the entryName (no salt, no env, no disk).
-- Zero config: the shell resolves the SSR map on its own (relative import redirected by the plugin).
-- Test suite (vitest) and CI (typecheck + tests + build + publint).
-
-## 0.2.0
-
-- Opaque IDs (`r-` + hash) replace configurable `rootId`/`dataId`.
-
-## 0.1.0
-
+# Changelog
+
+## 0.4.0
+
+- **Typed `c.render` entries (opt-in)**: `pages({ dts })` writes a `.d.ts` file
+  with the entry union (`HonoSvelteEntries`) + `declare module "hono"`
+  augmentation. `true` writes `src/hono-svelte-entries.d.ts` (relative to the
+  Vite root); a string sets a custom path. Regenerated on `buildStart` and by
+  the dev watcher when entries change. `dtsPath()` / `writeDts()` exposed on
+  the plugin. The playground wires it (`pages({ dts: true })` +
+  `/// <reference path="./hono-svelte-entries.d.ts" />` in `env.d.ts`), so a
+  typo in `c.render("...")` fails `tsc` instead of 500ing at runtime.
+  `data` stays `Record<string, unknown>` (per-page payload types are a future
+  feature).
+- **Layouts, single source of truth**: `<dir>/layout.svelte` wraps pages
+  automatically (SSR inside-out + client hydrate, `layouts()` /
+  `layoutChain()` to inspect, `layouts: false` = legacy ignore). Pages must
+  NOT import their layout manually — the plugin fails fast at build time
+  (`manually imports ... but the layout is applied automatically`) instead of
+  rendering the layout twice. Layout props (`title`, `description`) come from
+  the route via `c.render(entry, { data })`, with `title = "Dashboard"`
+  fallback in the layout. Rule shared by plugin and shell: static means
+  "no `<script>`", layouts don't matter; `__clientEntries` travels in the
+  virtual manifest so the shell picks the SSR branch for static+layouts pages.
+- **Runtime fixes**: static `import.meta.env.PROD/DEV` access (Vite module
+  runner forbids dynamic access — dev 500 fixed); static
+  `createRawSnippet` import in layout entries (no duplicated Svelte runtime —
+  `Illegal invocation` fixed); layout children snippet renders `<div>` wrapper
+  (empty render broke hydration — `Cannot set properties of null` fixed);
+  bundled server defaults to prod so plain `node ./dist/index.js` works on
+  Windows with no `NODE_ENV` prefix.
+- `c.render(entry, { status, headers, head })`: per-render status/headers
+  (merged over shell defaults) and CSP-safe per-page head tags
+  (`description`, `canonical`, `og`, `twitter`, `meta`, `extra`).
+- SSR static pages now receive `data` as component props (plus the embedded JSON).
+- Strict entries: unknown entryNames throw a dev-friendly error (`Available pages: ...`, generic in prod); `shell({ strict: false })` disables; `availableEntries()` exposes the list.
+- `pages().types()` / `typeDeclarations()` generate the entry union + hono module snippet.
+- Nested layouts: `<dir>/layout.svelte` wraps pages (SSR inside-out, `layouts()`/`layoutChain()`, `layouts: false` = legacy).
+- `notFoundHandler()` / `errorHandler()` for conventional `404.svelte` / `500.svelte` pages.
+- `hono-svelte init|doctor` CLI (`bin`) with `--app` flag.
+- `pages().validateConfig()` fails fast on missing svelte plugin / pagesDir.
+- `shell({ assets })` accepts a Vite manifest (hashed URLs, CSS, shared-chunk preload) with fallback; `preload`/`prefetch` controls; `styles` extra CSS.
+- `shell({ nonce })` CSP support on shell tags; `svelte/server` CSP passthrough for SSR.
+- Cache helpers: `immutableHeaders()`, `CACHE_IMMUTABLE`, `CACHE_NO_STORE`.
+- `data` size one-time warning (`shell({ dataLimit })`, default 100KB).
+
+## 0.3.1
+
+- Package metadata: repository/homepage/author, publishConfig, LICENSE + CHANGELOG in files.
+- No code changes since 0.3.0.
+
+## 0.3.0
+
+- Fully in-memory package: entries and manifest are virtual modules (no files written to disk).
+- Automatic zero-JS: `.svelte` pages without `<script>` render on the server (`svelte/server`)
+  and download no JS on the client.
+- Deterministic opaque IDs derived from the entryName (no salt, no env, no disk).
+- Zero config: the shell resolves the SSR map on its own (relative import redirected by the plugin).
+- Test suite (vitest) and CI (typecheck + tests + build + publint).
+
+## 0.2.0
+
+- Opaque IDs (`r-` + hash) replace configurable `rootId`/`dataId`.
+
+## 0.1.0
+
 - First version: `shell()` middleware + `pages()` plugin with disk-generated entries.

package/README.md

@@ -119,26 +119,111 @@ Files starting with `_` and `layout.svelte` are ignored (convention for partials
 
 ## Passing data to the page
 
-Small, public initial data (plan name, title, preferences) goes in `data` and arrives via `$props()` — no extra request:
+Small, public initial data (plan name, title, preferences) goes in `data` and arrives via `$props()` — no extra request.
+Works for static (zero-JS) pages too: the shell passes `data` as SSR props **and** embeds the JSON for hydration:
 
 ```ts
 app.get("/dashboard", (c) => c.render("dashboard", { data: { plan: "pro" } }));
 ```
 
+Large payloads trigger a one-time `console.warn` (default limit 100KB, `shell({ dataLimit })`).
+Anything sensitive stays in the API (`hc<AppType>`, HttpOnly cookie). Never put secrets in `data`.
+
+## Status, headers and per-page head
+
+```ts
+app.get("/old", (c) => c.render("gone", { status: 410, headers: { "X-Gone": "1" } }));
+
+app.get("/post", (c) =>
+  c.render("post", {
+    head: {
+      description: "A post about islands",
+      canonical: "https://example.com/post",
+      og: { title: "Islands", image: "https://example.com/og.png" },
+      twitter: { card: "summary_large_image" },
+    },
+  }),
+);
+```
+
+`<svelte:head>` inside pages also works (shell forwards SSR `head`). Page `head` never emits executable inline scripts (CSP-safe; `extra` is for trusted raw HTML like fonts or JSON-LD).
+
+## Nested layouts
+
+`<dir>/layout.svelte` wraps every page under `<dir>/` (SSR inside-out, outermost first). A root `layout.svelte` wraps everything. Layouts receive `children` plus all page `data` as props — e.g. `title`/`description` passed via `c.render(entry, { data })`:
+
+```svelte
+<!-- src/pages/dashboard/layout.svelte -->
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  type Props = { title?: string; description?: string; children: Snippet };
+  let { title = "Dashboard", description = "", children }: Props = $props();
+</script>
+
+<div class="layout">
+  <h1>{title}</h1>
+  {@render children()}
+</div>
+```
+
+```ts
+// routes/dashboard/page1.ts — layout data comes from the route, not the page
+c.render("dashboard/page1", { data: { title: "Page 1", description: "..." } });
+```
+
+```svelte
+<!-- src/pages/dashboard/page1.svelte — content only, NO layout import -->
+<section class="card">Page 1 content</section>
+```
+
+> Pages must NOT import their layout manually — the shell applies it automatically. The plugin fails fast at build time (`manually imports ... but the layout is applied automatically`) instead of rendering `<main><div><main>` twice.
+
+Layouts never become entries (`pages().layouts()` / `layoutChain(entry)` inspect them; `layouts: false` restores legacy ignore).
+
+
+## Error pages
+
+```ts
+import { errorHandler, notFoundHandler } from "hono-svelte";
+
+app.notFound(notFoundHandler()); // renders `404.svelte` with status 404
+app.onError(errorHandler()); // renders `500.svelte` with status 500
+```
+
+## CLI
+
+```sh
+npx hono-svelte init                  # scaffold src/pages, vite.config.ts, env.d.ts
+npx hono-svelte doctor                # check dist, link and vite config
+npx hono-svelte doctor --app=./my-app # check another app directory
+```
 
 ## API
 
 ### `shell(options?)`
 
-Hono middleware that provides `c.render(entry, { title?, data? })` on every route.
+Hono middleware that provides `c.render(entry, { title?, data?, status?, headers?, head? })` on every route.
 
 | Option | Default | Description |
 |---|---|---|
 | `title` | `"App"` | Title used when the route doesn't provide one |
 | `lang` | `"en"` | `<html>` `lang` attribute |
-| `assetsBase` | `"/static"` | Prefix for JS files in production |
+| `assetsBase` | `"/static"` | Prefix for JS files in production (legacy; prefer `assets`) |
+| `assets` | `"/static"` | String prefix, Vite manifest object, or resolver `(entry) => url` (hashed files) |
+| `isProd` | auto | Force prod/dev asset behavior |
 | `stylesHref` | `"/static/styles.css"` in prod, `"/src/styles.css"` in dev | Global stylesheet (or an `(isProd) => string` function) |
+| `styles` | `[]` | Extra CSS hrefs emitted per response |
 | `head` | `""` | Extra HTML in `<head>` (fonts, meta tags) |
+| `nonce` | — | CSP nonce string or `(c) => string` (applied to shell `<script>`/`<link>`) |
+| `preload` | `true` in prod | `<link rel="modulepreload">` for the entry (+ manifest imports) |
+| `prefetch` | `false` | `"all"` prefetches other entries; `"hover"` injects a hover-prefetch script |
+| `dataLimit` | `102400` | Warn once above this many `data` bytes (`false` disables) |
+| `status` | `200` | Default response status |
+| `headers` | `{}` | Default response headers (per-render `headers` merge over them) |
+| `strict` | `true` | Unknown entries throw a dev-friendly error; `false` disables |
+| `knownEntries` | auto from manifest | Override the page list used by strict mode and prefetch |
+
+`shell()` also exposes `availableEntries()` for diagnostics.
 
 ### `pages(options?)`
 
@@ -147,14 +232,41 @@ Vite plugin (`hono-svelte/vite`) that discovers pages and generates client entri
 | Option | Default | Description |
 |---|---|---|
 | `pagesDir` | `"src/pages"` | Pages folder |
-| `ignore` | `["**/layout.svelte", "**/_*.svelte"]` | Ignored patterns |
+| `ignore` | `["**/_*.svelte"]` | Ignored patterns (`layout.svelte` is a layout, not a page) |
+| `layouts` | `true` | Nested `<dir>/layout.svelte` support (`false` = legacy ignore) |
+| `dts` | `false` | Typed `c.render` entries: `true` writes `src/hono-svelte-entries.d.ts`, a string sets a custom path |
 | `alwaysClient` | `[]` | Pages that always get JS, even without `<script>` |
 
-Handy methods: `input()` (client build entries), `entries()` (all pages), `staticEntries()` (static pages only), `hasClient(entry)`.
+Handy methods: `input()` (client build entries), `entries()` (all pages), `staticEntries()` (static pages only), `hasClient(entry)`, `layouts()`, `layoutChain(entry)`, `types()` (entry union), `typeDeclarations()` (hono module snippet), `dtsPath()` / `writeDts()` (generated `.d.ts`), `validateConfig()` (fail fast on bad Vite setup).
 
 ### Typing `c.render`
 
-So TypeScript accepts `c.render` in routes, declare once in the app:
+Opt-in typed entry names — a typo fails `tsc` instead of 500ing at runtime:
+
+```ts
+// vite.config.ts
+const appPages = pages({ dts: true }); // writes src/hono-svelte-entries.d.ts
+```
+
+```ts
+// src/env.d.ts — the generated file carries the `declare module "hono"`
+// augmentation, so this file is only a reference. Remove any manual
+// `(entryName: string)` declaration or it will swallow the union.
+ /// <reference path="./hono-svelte-entries.d.ts" />
+```
+
+```ts
+// generated src/hono-svelte-entries.d.ts (commit it — CI needs no Vite run)
+export type HonoSvelteEntries = "auth" | "dashboard/index" | "index";
+
+declare module "hono" {
+  interface ContextRenderer {
+    (entryName: HonoSvelteEntries, props?: import("hono-svelte").RenderProps): Response | Promise<Response>;
+  }
+}
+```
+
+`dts: "path/to/entries.d.ts"` sets a custom path (relative to the Vite root). The file regenerates on `buildStart` and via the dev watcher when entries change. Without `dts` (default `false`), declare the renderer manually with a plain `string`:
 
 ```ts
 import type { RenderProps } from "hono-svelte";
@@ -166,10 +278,13 @@ declare module "hono" {
 }
 ```
 
+`data` stays `Record<string, unknown>` — per-page payload types are a future feature. Programmatic access: `pages().types()` → `"admin" | "home"`, `pages().typeDeclarations()` for the snippet, `dtsPath()` / `writeDts()` for the file.
+
 ## Production tips
 
-- Serve hashed files with long cache and `immutable`; the stylesheet with short cache or a versioned name.
-- Works with `script-src 'self'` — there is no executable inline script on the page.
+- Pass the Vite manifest to `shell({ assets: manifest })` for hashed files; manifest CSS and shared chunks are emitted automatically (`modulepreload`).
+- Serve hashed files with long cache and `immutable` (`immutableHeaders()` / `CACHE_IMMUTABLE`); the HTML shell itself suits `CACHE_NO_STORE`.
+- CSP: pass `shell({ nonce })` (string or from `secureHeaders()` context) — shell tags carry the nonce. Without a nonce, static pages keep working with `script-src 'self'` (no executable inline script, except the opt-in `prefetch: "hover"` helper).
 - Run both client and server builds before serving; the example in `examples/playground/` shows the full setup.
 
 ## Example

package/dist/assets.d.ts

@@ -0,0 +1,26 @@
+export type ViteManifestChunk = {
+    file: string;
+    css?: string[];
+    imports?: string[];
+    isEntry?: boolean;
+};
+export type ViteManifest = Record<string, ViteManifestChunk>;
+export type AssetsResolver = (entryName: string) => string;
+export type ManifestAssetsOptions = {
+    /** Prefix for manifest file paths. @default "/" */
+    prefix?: string;
+    /** Fallback base when the entry is missing from the manifest. @default "/static" */
+    fallbackBase?: string;
+};
+/** Manifest keys tried for an entry (virtual ids first, bare entry last). */
+export declare function manifestKeysFor(entryName: string): string[];
+export declare function createManifestAssets(manifest: ViteManifest, opts?: ManifestAssetsOptions): AssetsResolver;
+/** Hashed CSS files for an entry, via the Vite manifest. */
+export declare function manifestCssFor(manifest: ViteManifest, entryName: string, prefix?: string): string[];
+/** Shared-chunk URLs (for `modulepreload`), via the Vite manifest. */
+export declare function manifestImportsFor(manifest: ViteManifest, entryName: string, prefix?: string): string[];
+/** Long-term caching for hashed `/static` files. */
+export declare const CACHE_IMMUTABLE = "public, max-age=31536000, immutable";
+/** Safe default for HTML shell responses. */
+export declare const CACHE_NO_STORE = "no-store";
+export declare function immutableHeaders(extra?: Record<string, string>): Record<string, string>;

package/dist/assets.js

@@ -0,0 +1,60 @@
+// Asset URL resolution (Vite manifest with hashed files) + cache helpers.
+//
+// Default behavior stays zero-config: `/static/<entry>.js` (unhashed names,
+// as in the README example). Pass a Vite manifest object to `shell({ assets })`
+// when the client build uses hashed file names.
+const NULL = String.fromCharCode(0);
+function joinPrefix(prefix, file) {
+    return prefix.replace(/\/$/, "") + "/" + file.replace(/^\//, "");
+}
+/** Manifest keys tried for an entry (virtual ids first, bare entry last). */
+export function manifestKeysFor(entryName) {
+    return [
+        NULL + "virtual:hono-svelte/entry/" + entryName,
+        "virtual:hono-svelte/entry/" + entryName,
+        entryName,
+    ];
+}
+function findChunk(manifest, entryName) {
+    for (const key of manifestKeysFor(entryName)) {
+        const chunk = manifest[key];
+        if (chunk)
+            return chunk;
+    }
+    return undefined;
+}
+export function createManifestAssets(manifest, opts = {}) {
+    const prefix = opts.prefix ?? "/";
+    const fallbackBase = (opts.fallbackBase ?? "/static").replace(/\/$/, "");
+    return (entryName) => {
+        const chunk = findChunk(manifest, entryName);
+        if (chunk?.file)
+            return joinPrefix(prefix, chunk.file);
+        return `${fallbackBase}/${entryName}.js`;
+    };
+}
+/** Hashed CSS files for an entry, via the Vite manifest. */
+export function manifestCssFor(manifest, entryName, prefix = "/") {
+    const chunk = findChunk(manifest, entryName);
+    return (chunk?.css ?? []).map((f) => joinPrefix(prefix, f));
+}
+/** Shared-chunk URLs (for `modulepreload`), via the Vite manifest. */
+export function manifestImportsFor(manifest, entryName, prefix = "/") {
+    const chunk = findChunk(manifest, entryName);
+    if (!chunk)
+        return [];
+    const out = [];
+    for (const imp of chunk.imports ?? []) {
+        const dep = manifest[imp];
+        if (dep?.file)
+            out.push(joinPrefix(prefix, dep.file));
+    }
+    return out;
+}
+/** Long-term caching for hashed `/static` files. */
+export const CACHE_IMMUTABLE = "public, max-age=31536000, immutable";
+/** Safe default for HTML shell responses. */
+export const CACHE_NO_STORE = "no-store";
+export function immutableHeaders(extra = {}) {
+    return { "Cache-Control": CACHE_IMMUTABLE, ...extra };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Thin CLI wrapper: `hono-svelte init` / `hono-svelte doctor`.
+// Compiled to `dist/cli.js` and invoked via the `hono-svelte` bin.
+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";
+const args = process.argv.slice(2);
+const command = args[0];
+function flagValue(name) {
+    const pref = `--${name}=`;
+    const hit = args.find((a) => a.startsWith(pref));
+    return hit ? hit.slice(pref.length) : undefined;
+}
+const appRoot = flagValue("app") ?? process.cwd();
+function init() {
+    for (const file of initFiles()) {
+        const dest = join(appRoot, file.path);
+        if (!isSafeAppPath(appRoot, dest)) {
+            console.error(`[hono-svelte] refusing to write outside ${appRoot}: ${file.path}`);
+            process.exitCode = 1;
+            continue;
+        }
+        if (file.skipIfExists && existsSync(dest)) {
+            console.log(`[hono-svelte] exists, skipping: ${file.path}`);
+            continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, file.content);
+        console.log(`[hono-svelte] wrote ${file.path}`);
+    }
+}
+function packageRootForCli() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function doctor() {
+    const packageRoot = packageRootForCli();
+    const issues = doctorChecks({ packageRoot, appRoot });
+    const linkIssue = checkAppLink(appRoot);
+    if (linkIssue)
+        issues.push(linkIssue);
+    if (issues.length === 0) {
+        console.log("[hono-svelte] doctor: all good!");
+        return;
+    }
+    for (const issue of issues) {
+        console.log(`[hono-svelte] ${issue.code}: ${issue.message}`);
+        console.log(`  fix: ${issue.fix}`);
+    }
+    process.exitCode = 1;
+}
+if (command === "init")
+    init();
+else if (command === "doctor")
+    doctor();
+else {
+    console.log("Usage: hono-svelte <init|doctor> [--app=<dir>]");
+    process.exitCode = 1;
+}

package/dist/handlers.d.ts

@@ -0,0 +1,16 @@
+import type { HeadProps } from "./head.js";
+export type ErrorPageOptions = {
+    /** Entry name. @default "404" (not-found) / "500" (error) */
+    entry?: string;
+    title?: string;
+    data?: Record<string, unknown>;
+    head?: string | HeadProps;
+};
+/** Hono `notFound` handler: `app.notFound(notFoundHandler())`. */
+export declare function notFoundHandler(opts?: ErrorPageOptions): (c: any) => any;
+export type ServerErrorHandlerOptions = ErrorPageOptions & {
+    /** Log the error. `true` = `console.error`. @default true */
+    log?: boolean | ((err: unknown) => void);
+};
+/** Hono `onError` handler: `app.onError(errorHandler())`. */
+export declare function errorHandler(opts?: ServerErrorHandlerOptions): (err: unknown, c: any) => any;

package/dist/handlers.js

@@ -0,0 +1,31 @@
+// Conventional error-page handlers: `404.svelte` / `500.svelte` pages
+// rendered with the matching HTTP status.
+/** 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,
+        });
+    };
+}
+/** Hono `onError` handler: `app.onError(errorHandler())`. */
+export function errorHandler(opts = {}) {
+    const entry = opts.entry ?? "500";
+    const log = opts.log ?? true;
+    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,
+        });
+    };
+}

package/dist/head.d.ts

@@ -0,0 +1,19 @@
+export type HeadMetaItem = {
+    name?: string;
+    property?: string;
+    httpEquiv?: string;
+    content: string;
+};
+export type HeadProps = {
+    description?: string;
+    canonical?: string;
+    themeColor?: string;
+    meta?: HeadMetaItem[];
+    /** Open Graph tags: `{ title, description, image }` -> `property="og:*"`. */
+    og?: Record<string, string>;
+    /** Twitter tags: `{ card, title }` -> `name="twitter:*"`. */
+    twitter?: Record<string, string>;
+    /** Raw HTML appended as-is (fonts, ld+json, verification tags). */
+    extra?: string;
+};
+export declare function renderHead(head: string | HeadProps | undefined): string;

package/dist/head.js

@@ -0,0 +1,42 @@
+// Per-page <head> tags (CSP-safe: meta/link tags plus an opt-in raw slot).
+// No executable inline scripts are ever emitted here.
+function escapeAttr(value) {
+    return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+export function renderHead(head) {
+    if (!head)
+        return "";
+    if (typeof head === "string")
+        return head;
+    const out = [];
+    if (head.description !== undefined) {
+        out.push(`<meta name="description" content="${escapeAttr(head.description)}" />`);
+    }
+    if (head.canonical !== undefined) {
+        out.push(`<link rel="canonical" href="${escapeAttr(head.canonical)}" />`);
+    }
+    if (head.themeColor !== undefined) {
+        out.push(`<meta name="theme-color" content="${escapeAttr(head.themeColor)}" />`);
+    }
+    for (const m of head.meta ?? []) {
+        const attr = m.name
+            ? `name="${escapeAttr(m.name)}"`
+            : m.property
+                ? `property="${escapeAttr(m.property)}"`
+                : m.httpEquiv
+                    ? `http-equiv="${escapeAttr(m.httpEquiv)}"`
+                    : null;
+        if (!attr)
+            continue;
+        out.push(`<meta ${attr} content="${escapeAttr(m.content)}" />`);
+    }
+    for (const [k, v] of Object.entries(head.og ?? {})) {
+        out.push(`<meta property="og:${escapeAttr(k)}" content="${escapeAttr(v)}" />`);
+    }
+    for (const [k, v] of Object.entries(head.twitter ?? {})) {
+        out.push(`<meta name="twitter:${escapeAttr(k)}" content="${escapeAttr(v)}" />`);
+    }
+    if (head.extra)
+        out.push(head.extra);
+    return out.join("");
+}

package/dist/index.d.ts

@@ -1,24 +1,89 @@
 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 type { DoctorIssue, DoctorOptions, InitFile } from "./scaffold.js";
 export type SsrPageLoader = () => Promise<{
     default: unknown;
 }>;
 export type RenderProps = {
     title?: string;
     data?: Record<string, unknown>;
+    /** HTTP status of the shell response. @default 200 */
+    status?: number;
+    /** Extra response headers merged into the shell response. */
+    headers?: Record<string, string>;
+    /** Per-page head tags, merged after the shell `head` option. */
+    head?: string | HeadProps;
 };
+export type PrefetchMode = false | "hover" | "all";
 export type ShellOptions = {
     title?: string;
     lang?: string;
     assetsBase?: string;
+    /**
+     * Resolve the client JS URL for an entry.
+     * - String: base prefix (`/static` -> `/static/<entry>.js`).
+     * - Vite manifest object or resolver function: hashed files.
+     * @default "/static"
+     */
+    assets?: string | ViteManifest | AssetsResolver;
+    /** Extra CSS links per HTML response. Strings are hrefs verbatim. */
+    styles?: string[];
     stylesHref?: string | ((isProd: boolean) => string);
+    /** Global head HTML (fonts, meta) — page `head` prop is appended after it. */
     head?: string;
-    /** Manual override of the entryName -> loader map (optional; otherwise the shell
-     *  resolves the map automatically via ssr-manifest). */
+    /**
+     * CSP nonce applied to `<script>`, `<link>` and `<style data-hs>` tags
+     * emitted by the shell. Pass a per-request nonce string or a function
+     * reading it from the Hono context (e.g. set by `secureHeaders()`).
+     */
+    nonce?: string | ((c: unknown) => string | undefined);
+    /**
+     * `<link rel="modulepreload">` for the current entry (+ its manifest
+     * imports). @default true in prod, false in dev.
+     */
+    preload?: boolean;
+    /** Prefetch other client entries. @default false */
+    prefetch?: PrefetchMode;
+    /**
+     * Warn once when serialized `data` exceeds this many bytes.
+     * @default 102400 (100KB). Set to `false` to disable.
+     */
+    dataLimit?: number | false;
+    /** Manual override of the entryName -> loader map (otherwise resolved via ssr-manifest). */
     ssrPages?: Record<string, SsrPageLoader>;
+    /**
+     * Known entry names. When set (or auto-detected from the manifest),
+     * unknown entries throw a dev-friendly error listing available pages.
+     * In production the error message is generic.
+     */
+    knownEntries?: string[];
+    /** `false` disables unknown-entry validation. @default true */
+    strict?: boolean;
+    /** Default status when `c.render(entry)` omits it. @default 200 */
+    status?: number;
+    /** Default headers merged into every shell response. */
+    headers?: Record<string, string>;
+    /**
+     * Force prod/dev asset behavior. Defaults to auto-detect
+     * (`import.meta.env.PROD`, else `NODE_ENV === "production"`).
+     */
+    isProd?: boolean;
 };
 export type ShellContext = {
     render: (entryName: string, props?: RenderProps) => Response | Promise<Response>;
 };
-export declare function shell(options?: ShellOptions): (c: any, next: Next) => Promise<void>;
+/** Visible for tests. */
+export declare function __resetDataLimitWarned(): void;
+export declare function shell(options?: ShellOptions): ((c: any, next: Next) => Promise<void>) & {
+    availableEntries: () => string[] | undefined;
+};