hono-svelte 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# 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

@@ -1,71 +1,302 @@
 # hono-svelte
 
-Shell server-side + paginas Svelte multi-entry para apps Hono, 100% in-memory
-(nenhum arquivo gerado em disco) e com zero-JS automatico para paginas estaticas.
-Zero config: o app nao importa nada alem de `shell()` e `pages()`.
-
-- `hono-svelte` — middleware `shell()`: registra `c.render(entry, { title?, data? })`.
-  - `data` (pequeno, publico, serializavel) vai embutido no HTML
-    (`<script type="application/json">` com id opaco) e chega na pagina via `$props()`.
-  - Dados privados, grandes ou mutaveis: buscar via RPC (`hc<AppType>`) apos o mount.
-  - Zero config: o shell descobre sozinho quais paginas sao estaticas e
-    renderiza no servidor via `svelte/server`, sem import nenhum no app.
-- `hono-svelte/vite` — plugin `pages()`: cada `*.svelte` em `pagesDir`
-  (exceto parciais) vira um entry virtual com `mount()` automatico.
-  Nada e escrito em disco.
-
-## Uso
+Render Svelte 5 pages in Hono apps with a single `c.render("page")` — no SPA, no build boilerplate.
+
+Each `.svelte` file becomes an independent page. Static pages reach the browser as ready-made HTML with **zero JavaScript**. Interactive pages receive only their own JS. Works in dev with HMR and in production with per-page bundles.
+
+## Why use it
+
+Real sites and dashboards mix simple pages (landing, login, terms) with interactive screens (panels, forms). In a traditional SPA, a landing visitor downloads the entire dashboard's JS. With hono-svelte:
+
+- **Static pages cost zero JS** — HTML arrives ready from the server;
+- **Interactive pages cost only their own JS** — independent bundles, no loading the rest of the app;
+- **Public initial data ships in the HTML** — the page mounts with content, no extra fetch;
+- **Sensitive data stays in the API** — typed end to end with the Hono client.
+
+## Installation
+
+Requires Node 22+, Hono 4, Svelte 5, and Vite 6/7/8.
+
+```sh
+npm install hono-svelte
+```
+
+## Quick start
+
+**1. Configure Vite** — add the pages plugin in every mode and use the entry list in the client build:
 
 ```ts
-// vite.config.ts
+import build from "@hono/vite-build/node";
+import devServer from "@hono/vite-dev-server";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
 import { pages } from "hono-svelte/vite";
-const appPages = pages(); // defaults: src/pages
-// input: { ...appPages.input(), styles: "src/styles.css" }
-// plugins: [tailwindcss(), svelte(), appPages, ...] em TODOS os modos
-// (client, serve e server build) - o modo server precisa de appPages para
-// o shell enxergar o manifesto in-memory.
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+
+const appPages = pages();
+
+export default defineConfig(({ command, mode }) => {
+  if (mode === "client") {
+    return {
+      plugins: [svelte(), appPages],
+      build: {
+        rollupOptions: {
+          input: { ...appPages.input(), styles: resolve("src/styles.css") },
+          output: {
+            entryFileNames: "static/[name].js",
+            chunkFileNames: "static/chunks/[name]-[hash].js",
+            assetFileNames: "static/[name][extname]",
+          },
+        },
+      },
+    };
+  }
+
+  if (command === "serve") {
+    return {
+      plugins: [svelte(), appPages, devServer({ entry: "src/routes/index.ts" })],
+    };
+  }
+
+  return {
+    plugins: [svelte(), appPages, build({ entry: "src/routes/index.ts", staticRoot: "./dist" })],
+  };
+});
 ```
 
+**2. Register the shell on the server:**
+
 ```ts
-// servidor
+import { Hono } from "hono";
 import { shell } from "hono-svelte";
 
-app.use("/*", shell({ title: "Meu App", lang: "pt-BR" }));
+const app = new Hono().use("/*", shell({ title: "My App", lang: "en" }));
+```
+
+**3. Create pages** in `src/pages` — one page per file:
+
+```svelte
+<!-- src/pages/home.svelte — no <script>: becomes plain HTML, zero JS -->
+<main>
+  <h1>Welcome</h1>
+  <a href="/dashboard">Sign in</a>
+</main>
+```
+
+```svelte
+<!-- src/pages/dashboard.svelte — has <script>: gets its own JS -->
+<script lang="ts">
+  import { hc } from "hono/client";
+  import type { AppType } from "../routes/api";
+
+  let { plan } = $props<{ plan: string }>();
+  const client = hc<AppType>("/");
+
+  let time = $state("--:--");
+  async function refresh() {
+    const res = await client.api.time.$get();
+    time = (await res.json()).time;
+  }
+</script>
+
+<main>
+  <h1>Dashboard — {plan} plan</h1>
+  <p>Server time: {time}</p>
+  <button onclick={refresh}>Refresh</button>
+</main>
+```
+
+**4. Render in routes:**
+
+```ts
+app.get("/", (c) => c.render("home"));
 app.get("/dashboard", (c) => c.render("dashboard", { data: { plan: "pro" } }));
 ```
 
+The rule is simple: **if the `.svelte` file has no `<script>`, the page ships as plain HTML. If it has one, it hydrates on the client** with initial data available via `$props()`.
+
+Files starting with `_` and `layout.svelte` are ignored (convention for partials and layouts).
+
+## Passing data to the page
+
+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
-<!-- pagina estatica: sem <script> => zero-JS, HTML vem pronto do servidor -->
-<main>...</main>
-```
-
-## Zero-JS automatico
-
-Pagina sem `<script>` no `.svelte` nao gera entry client: o `shell()` renderiza
-o HTML no servidor e nenhum `<script>` e enviado ao cliente. Para forcar client
-JS em uma pagina especifica: `pages({ alwaysClient: ["index"] })`.
-Para override manual do mapa de SSR: `shell({ ssrPages })` (opcional).
-
-## IDs
-
-`root`/`data` usam ids opacos derivados do `entryName` via `getIds(entryName)`
-(`r-` + hash). Servidor e client derivam o mesmo par sem config, sem disco, sem salt.
-
-## Repo
-
-- `/` — o pacote `hono-svelte` (src, test, dist)
-- `/examples/playground` — app Hono de demonstracao, consome o pacote via `file:../..`
-
-## Tipagem do `c.render`
-
-Augmente o `ContextRenderer` no SEU app (padrao do Hono) — crie um `env.d.ts`:
-
-```ts
-import type { RenderProps } from "hono-svelte";
-
-declare module "hono" {
-  interface ContextRenderer {
-    (entryName: string, props?: RenderProps): Response | Promise<Response>;
-  }
-}
+<!-- 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?, 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 (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?)`
+
+Vite plugin (`hono-svelte/vite`) that discovers pages and generates client entries.
+
+| Option | Default | Description |
+|---|---|---|
+| `pagesDir` | `"src/pages"` | Pages folder |
+| `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)`, `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`
+
+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";
+
+declare module "hono" {
+  interface ContextRenderer {
+    (entryName: string, props?: RenderProps): Response | Promise<Response>;
+  }
+}
+```
+
+`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
+
+- 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
+
+`examples/playground/` is a real Hono app using the package: static landing, login, and a dashboard with typed RPC and cookie session. To run it:
+
+```sh
+cd examples/playground && npm install && npm run build
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Changelog in [CHANGELOG.md](./CHANGELOG.md).
+
+Anything sensitive, large, or frequently changing stays in the API, fetched after mount with the typed Hono client (`hc<AppType>`) — with the session in an `HttpOnly` cookie as usual. Never put secrets in `data`: it is visible in the HTML.

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;