create-pracht 0.7.0 → 0.7.2

package/skills/migrate-nextjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-nextjs
-version: 1.7.0
+version: 1.8.1
 description: |
   Migrate a Next.js app to pracht: App or Pages Router pages, layouts, middleware,
   API routes, data fetching, and metadata — plus React→Preact, `className`→`class`,
@@ -74,7 +74,7 @@ automatic**:
 | ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------- |
 | `pages/` directory              | `pagesDir` plugin option                                        | Auto-discovers routes from the file system                            |
 | `app/page.tsx`                  | `src/routes/*.tsx` + `route()` in manifest                      | File is a module; wiring is explicit                                  |
-| `app/layout.tsx`                | `src/shells/*.tsx` + `shells` in `defineApp` (pages: `_app.tsx` per directory) | Named shells; a directory `_app` replaces its parent instead of nesting |
+| `app/layout.tsx`                | `src/shells/*.tsx` + `shells` in `defineApp` (pages: `_app.tsx` per directory) | Named shells; a directory `_app` replaces its parent. Layout data: shell `loader` + `useShellData()` |
 | `app/loading.tsx`               | `Loading` export on the shell                                   | SSR placeholder for SPA routes until the client router takes over     |
 | `app/error.tsx`                 | `ErrorBoundary` export in route module                          | Same concept, different wiring                                        |
 | `app/not-found.tsx`             | `notFound:` in `defineApp` (or `pages/404.tsx` in pagesDir mode) | Not a route — never matches a URL, so it cannot shadow static assets  |
@@ -87,7 +87,7 @@ automatic**:
 | `"use client"` (few, mostly-server app) | `hydration: "islands"` + `src/islands/`                 | Only islands ship JS; see Phase 4                                     |
 | `revalidatePath` / `res.revalidate()` | `webhookRevalidate()` + `POST /__pracht/revalidate`       | On-demand ISG; combinable with `timeRevalidate(seconds)`              |
 | `useRouter()` (next/navigation) | `useNavigate()`                                                 | Takes a path, or `{ route: "id" }` after `pracht typegen`             |
-| `useSearchParams()`             | `useSearchParams()`                                             | Reactive read-only params; SSG gets the browser query after hydration, loaders use `url.searchParams` |
+| `useSearchParams()`             | `useSearchParams()`                                             | Reactive read-only params; SSG gets the browser query after hydration. For validated, typed values export a `search` schema and read `args.search` / `useSearch()` |
 | `useParams()`                   | `useParams()`                                                   | Direct equivalent; also `params` in loader args                       |
 | `next/link` `<Link>`            | `<Link route="..." params={{…}}>` or plain `<a>`               | Prefer typed `<Link>` after `pracht typegen`; the router intercepts same-origin anchors |
 | `next/link` `prefetch={false}`  | `<Link prefetch="none">`                                        | Default `"intent"` (hover/focus); also `"viewport"`, `"render"`       |
@@ -337,8 +337,8 @@ and fix errors iteratively.
 | `next`          | `@pracht/core` + `@pracht/cli` + `@pracht/vite-plugin` + a target adapter    |
 | `next/image`    | `@pracht/image`                                                              |
 | `react`, `react-dom` | `preact`                                                                |
-| `next/font/local` | `defineFont()` from `@pracht/core` — register via `head() { return { fonts: [font] } }`, use `font.className`/`font.style` |
-| `next/font/google` | Download the woff2 files into `public/fonts/` (e.g. via google-webfonts-helper), then `defineFont()` — pracht never fetches fonts at build time |
+| `next/font/local` | Import WOFF2 with `?url&no-inline` into [`defineFont()`](https://pracht.resynapse.dev/docs/fonts); register `head().fonts`, apply `font.className`/`font.style` |
+| `next/font/google` | Self-host WOFF2 in `src/fonts/`, then follow `next/font/local`; pracht never fetches fonts at build time |
 | `@next/mdx`     | `@mdx-js/rollup` (Vite plugin)                                               |
 | `next-auth`     | Direct integration in middleware/loaders                                     |
 | `next/og`       | `@vercel/og` or a custom solution                                            |

package/skills/pracht-debug/SKILL.md

@@ -36,6 +36,7 @@ Reach for these before deep manual inspection:
 | `pracht inspect routes\|api\|build --json` | The resolved graph — never reconstruct it from source |
 | `GET /_pracht` (JSON at `/_pracht.json`) | Same graph from a running dev server, no CLI needed |
 | `Server-Timing` on dev SSR responses | `mw` / `loader` / `render` durations in ms — which phase is slow |
+| `pracht_*` WebMCP page tools in the open tab | Tab-scoped view from an agent-driven browser: `pracht_route`, `pracht_loader_data`, `pracht_islands`, `pracht_last_error`, `pracht_page_tools` |
 
 `pracht inspect` needs the pracht plugin in the vite config; `inspect build`
 needs a prior `pracht build`. Under a Vite deploy base, prefix `/_pracht` with
@@ -44,6 +45,18 @@ pracht MCP server is registered (docs/MCP.md), prefer the
 `inspect_routes`/`inspect_api`/`doctor`/`verify` MCP tools — same payloads,
 structured results.
 
+When you are driving a browser against `pracht dev` with a WebMCP-compatible
+test harness or host, ask the tab before reading logs: every dev document registers read-only
+`pracht_*` page tools with `document.modelContext`. `pracht_route` gives the
+matched route, files, render/hydration mode, and middleware; `pracht_loader_data`
+the data the page holds now (`{ path: "a.0.b" }` narrows it; islands/none routes
+answer with the route-state request to make instead); `pracht_islands` each
+island's file, strategy, props, and hydration status; `pracht_last_error` the
+structured server error behind an overlay or `ErrorBoundary` plus recent client
+errors; `pracht_page_tools` the app's active WebMCP tools on the route. All
+resolve to `{ ok, data }` / `{ ok: false, error }` envelopes and follow client
+navigation.
+
 ## Checklist
 
 Work in order; stop at the root cause.
@@ -79,7 +92,9 @@ Work in order; stop at the root cause.
 ### 3. Loader / API errors
 
 - On slow pages, read `Server-Timing` before reading code.
-- Loaders must return serializable data — no functions, no circular refs.
+- Loaders must return serializable data — no functions, no circular refs. A
+  `Date` arrives as a string unless `pracht({ client: { richData: true } })` is
+  set; with it, an unsupported value fails with an error naming its path.
 - API handlers must return `Response` objects, and a default export must branch
   on `request.method`.
 - Look for unhandled rejections or thrown errors.
@@ -94,7 +109,10 @@ Work in order; stop at the root cause.
   component (via Preact's `options.__m` hook). Compare server HTML against
   client output. Usual causes: date/time differences, browser-only APIs during
   SSR (`window`, `document`, `localStorage`), conditional rendering on client
-  state — or two copies of `@pracht/core` in the SSR module graph. The tell for
+  state — or, on Preact 10, a suspending boundary resolving to zero or multiple
+  DOM nodes. Preact 11 supports those boundary shapes, so Pracht skips that
+  legacy diagnostic there. Another cause is two copies of `@pracht/core` in
+  the SSR module graph. The tell for
   that last one: in the server-rendered HTML of *every* page, `useLocation()`
   returns `/`, `useParams()` returns `{}`, and `useRouteData()` returns
   `undefined`, while the hydrated client is correct — provider and hooks hold

package/skills/pracht-deploy/SKILL.md

@@ -75,6 +75,14 @@ step (`--port <n>`, `--skip-build` to reuse a build).
   `Accept-Encoding`, streaming for dynamic bodies, an in-memory LRU for static
   assets). Behind a proxy or CDN that already compresses, set
   `nodeAdapter({ compression: false })` to avoid doing it twice.
+- The generated server drains on `SIGTERM`/`SIGINT`: it stops accepting
+  connections and waits for in-flight requests and `args.waitUntil()` work up
+  to `nodeAdapter({ shutdownTimeoutMs })` (default 10s). Keep it below the
+  process manager's kill grace period. A custom `createNodeRequestHandler()`
+  server calls `await handler.drain(ms)` after `server.close()` instead.
+- Background work after the response is `args.waitUntil(promise)` on every
+  adapter — do not wire `executionContext.waitUntil` (Cloudflare) or the
+  platform context yourself.
 
 Docker:
 
@@ -280,8 +288,11 @@ SSG loaders run only at build time and must produce HTML plus valid JSON route
 state; dynamic SSG routes must export `getStaticPaths()`. Only
 manifest-registered capabilities participate, and every registered capability
 module must load successfully so exposure validation fails closed. The
-`notFound` page must use full hydration (the default) because the shared
-`404.html` needs the client router to adopt the visitor's actual URL.
+`notFound` page may set `hydration: "islands"` or `"none"` to keep the client
+router out of `404.html` — the router is there only to replace the build URL
+with the visitor's, so a 404 that does not name the requested URL pays nothing
+for it. `staticAdapter({ fallback })` still requires full hydration there,
+because that document is built from the not-found page's route state.
 
 **Deploy base.** Sub-path deploys (GitHub Pages *project* sites, S3 key
 prefixes) set Vite `base` to that path. CDN and document-relative bases (`""`,

package/skills/pracht-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pracht-scaffold
-version: 1.4.0
+version: 1.5.0
 description: |
   Scaffold pracht code with the native generators (`pracht generate
   route|shell|middleware|api`), falling back to manual edits only when the CLI
@@ -49,7 +49,9 @@ If the CLI can express the request, do not reimplement the scaffold by hand.
 | `--revalidate`      | ISG window in seconds (`isg` only, default 3600)                             |
 | `--json`            | Machine-readable output                                                      |
 
-`generate shell` and `generate middleware` take `--name`; `generate api` takes
+`generate shell` and `generate middleware` take `--name`; `generate shell
+--loader` adds a shell `loader` export read in the shell with `useShellData()`
+(layout-level data such as the signed-in user). `generate api` takes
 `--path` and `--methods`. All subcommands accept `--json` — use it when another
 agent or tool consumes the output. When the pracht MCP server is registered
 (docs/MCP.md), call the `generate_route`/`generate_shell`/`generate_middleware`/
@@ -82,8 +84,8 @@ agent or tool consumes the output. When the pracht MCP server is registered
 
 | Kind       | Directory         | Key exports                                                                      |
 | ---------- | ----------------- | -------------------------------------------------------------------------------- |
-| Route      | `src/routes/`     | `loader`, `head`, `Component`, `ErrorBoundary`, `getStaticPaths`                 |
-| Shell      | `src/shells/`     | `Shell`, `head`                                                                  |
+| Route      | `src/routes/`     | `loader`, `head`, `Component`, `ErrorBoundary`, `getStaticPaths`, `search`       |
+| Shell      | `src/shells/`     | `Shell`, `loader` (read with `useShellData()`), `head`, `headers`, `Loading`, `ErrorBoundary` |
 | Middleware | `src/middleware/` | `middleware`                                                                     |
 | API route  | `src/api/`        | Named method handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) or one default dispatcher |
 

package/skills/pre-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pre-deploy
-version: 1.4.0
+version: 1.5.0
 description: |
   Adapter-aware pre-deployment checklist (Node, Cloudflare Workers, Vercel, static)
   for the failures that only surface in production: missing env vars, Node-only
@@ -55,6 +55,20 @@ reports errors, stop here**; the remaining checks will be noisy false
 positives. Stale generated typed-route files block deployment; if the app does
 not use them yet, note that `typegen --check` is optional.
 
+If `pracht inspect agents --json` reports any WebMCP exposure, run the live
+browser boundary too. Point it at the already-started preview, or let it own the
+server lifecycle:
+
+```bash
+pracht verify webmcp --start "pracht preview" --json
+```
+
+CI must install a pinned Chrome 150+ build and pass its executable with
+`--browser`; the verifier never silently downloads one. Treat unsupported API,
+startup/registration failure, and graph drift as deployment errors. Do not add
+`--scenario` unless the repository already supplies an explicitly safe WebMCP
+eval scenario.
+
 For a PR deploy, `pracht report --base origin/main` produces a markdown summary
 (graph diff + verify + budgets) worth attaching.
 
@@ -79,6 +93,14 @@ For a PR deploy, `pracht report --base origin/main` produces a markdown summary
   true })` is set; application code should still observe the public base in
   `request.url`, and the proxy must own the bare-base redirect (`/app` →
   `/app/`).
+- If the app registers background work with `args.waitUntil()`, the process
+  manager sends `SIGTERM` (not `SIGKILL`) on stop and its grace period exceeds
+  `nodeAdapter({ shutdownTimeoutMs })` (default 10s); otherwise that work is
+  cut off on every deploy. A custom server entry must call `handler.drain()`
+  itself.
+- Background work still reaching for `context.executionContext.waitUntil` or a
+  platform context should move to the portable `args.waitUntil()` — the
+  platform-specific call is undefined on every other adapter.
 
 ### Cloudflare Workers (`@pracht/adapter-cloudflare`)
 

package/skills/tune-render-mode/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tune-render-mode
-version: 1.1.1
+version: 1.2.0
 description: |
   Recommend the right render mode (ssg, isg, ssr, spa) per route from what each
   loader actually does, then apply the change after confirmation.
@@ -53,6 +53,18 @@ For each route:
    anything personalized** → **`ssr`**
    - Auth dashboards, anything user-specific, anything that varies by user
      identity at request time.
+   - **Unless only a small part of the page is personal** (a cart count,
+     "signed in as …", a recommendation strip) and the rest is shared: then
+     recommend **`ssg`/`isg`** for the route plus a **server island** for
+     the personal part (see branch 5b).
+
+5b. **Personal data is confined to a small, self-contained part of the page**
+   → keep the route **`ssg`/`isg`** and move that part into `src/server-islands/`:
+   a default-export component plus a `loader` that reads `context` instead of
+   the page loader, used as JSX with a `fallback`. See
+   <https://pracht.resynapse.dev/docs/server-islands>. Not available on the static
+   adapter. Server island props are untrusted input — the server island loader must
+   authorize from `context` itself.
 
 6. **Heavy client interactivity, no SEO need, auth-gated** → **`spa`**
    - Internal admin tools, post-login dashboards where the first paint can be a
@@ -108,6 +120,9 @@ Examples of recommendations:
   request — cannot be prerendered." (`error`)
 - `spa` → `ssr` when route has SEO-relevant `head()` and unauthenticated
   visitors should see content. (`warn`)
+- `ssr` → `isg(600)` + server island when the loader reads the session only for a
+  header greeting or cart badge: "move the personal part into
+  `src/server-islands/`; the page itself is shared." (`info`)
 
 ## Step 3b: Consider the hydration mode too
 
@@ -124,7 +139,8 @@ field (absent from the JSON), grep the manifest for `hydration:` (pages apps:
   box, newsletter form) → `hydration: "islands"` with the widgets moved to
   `src/islands/`.
 - Caveats: islands routes use MPA-style full-document navigation (no client
-  router), island props must be JSON-serializable, and `render: "spa"` cannot
+  router) unless `client.islandsNavigation` swaps islands pages in place,
+  island props must be JSON-serializable, and `render: "spa"` cannot
   combine with `"islands"`/`"none"`.
 
 ## Step 3c: Consider streaming for slow SSR routes
@@ -190,6 +206,8 @@ Apply the edits only after the user confirms.
 1. Never silently change render modes. Always present the recommendation and
    the exact diff first; apply only after explicit user approval.
 2. If a route uses `auth` middleware, default to `ssr` — auth implies cookies.
+   The exception is middleware that only *reads* the session for a small
+   personal part of an otherwise public page: that is the server island case (5b).
 3. All three adapters support ISG — the mechanisms differ. Confirm which
    adapter is in play, then use this capability table:
 

package/skills/typed-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typed-routes
-version: 1.1.1
+version: 1.3.0
 description: |
   Add or maintain pracht typed routes: run typegen, adopt route-id based links and
   navigation, and replace hard-coded hrefs with generated helpers.
@@ -79,6 +79,10 @@ when `src/pracht.d.ts` does not exist. In CI, prefer:
 pracht typegen --check
 ```
 
+The check compares declarations, not bytes, so generated files reformatted by
+the project's formatter still read as up to date and regenerating leaves them
+formatted. Do not add them to a formatter ignore list on that account.
+
 ## Step 3: Replace string navigation where it matters
 
 ### Components
@@ -149,6 +153,46 @@ loader type their data as `undefined`. The id must be the active route: a
 mismatch throws (with a descriptive message in dev), so a shell or island that
 needs another route's data must receive it as props instead.
 
+Shell loaders register the same way: `useShellData("app")` types the result
+from the `app` shell's `loader` for every shell a route renders under. It is
+typed `| undefined` because the shell can render without its data (the SPA
+loading state), and naming a shell the active route does not use throws.
+
+### Search params
+
+A route that reads its query string should export a `search` schema (any
+Standard Schema validator) instead of parsing `url.searchParams` by hand.
+Typegen then types `search` on `<Link>`, `navigate()`, and `href()` from the
+schema's input, and `useSearch(routeId)` returns its output:
+
+```tsx
+import { Link, useSearch, type LoaderArgs, type SearchArgs } from "@pracht/core";
+import * as z from "zod";
+
+export const search = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  q: z.string().optional(),
+});
+
+export async function loader(args: LoaderArgs & SearchArgs<typeof search>) {
+  return listProducts(args.search); // { page: number; q?: string }
+}
+
+export function Component() {
+  const { page, q } = useSearch("products");
+  return <Link route="products" search={{ page: page + 1, q }}>Next</Link>;
+}
+```
+
+- Values arrive as strings (arrays for repeated keys): coerce with
+  `z.coerce.*`, and give optional params defaults so the bare URL is valid. A
+  key that may repeat is a plain string when it appears once — accept both.
+- A rejected query answers 400 and renders the route's `ErrorBoundary` with
+  `error.issues`; client navigation does the same.
+- SSG/ISG routes are prerendered with an empty query, so the schema must
+  accept one; loaders there only ever see the defaults.
+- Keep `useSearchParams()` for raw access; it is unchanged.
+
 ### API routes
 
 After typegen, `apiFetch()` type-checks API calls end to end — paths,
@@ -182,8 +226,11 @@ Generated param types accept `RouteParamInput = string | number | boolean`
 - `:path*` requires `params: { path: RouteParamInput }`.
 - Routes with no dynamic segments should omit `params`.
 - Missing and extra params should fail at typecheck time.
-- `search` currently accepts `string`, `URLSearchParams`, or an object of
-  primitive values/arrays; route-specific search schemas can be added later.
+- `search` is typed by the route module's `search` schema input when it
+  exports one: unknown keys and wrong value types fail, keys whose input
+  cannot come from a string (`z.number()`) fail, and a required key makes
+  `search` itself required. Routes without a schema accept `string`,
+  `URLSearchParams`, or an object of primitive values/arrays.
 
 ## Step 5: Verify
 

package/skills/upgrade-pracht/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: upgrade-pracht
-version: 1.1.0
+version: 1.2.0
 description: |
   Upgrade the `@pracht/*` packages safely: inventory installed versions, read the
   changelogs between installed and target, map breaking changes to real usage,
@@ -130,12 +130,17 @@ pracht doctor --json          # wiring still valid
 pracht typegen --check        # generated route types up to date?
 pracht typegen                # regenerate if --check failed or routes changed
 pracht verify --json          # framework-aware checks
+pnpm typecheck                # both tsconfig programs, if the app has the script
 pracht build                  # full production build (budgets included)
 pnpm test                     # the app's own suite
 ```
 
 `pracht doctor`, `verify`, and `typegen --check` exit non-zero on failure, so
-they gate CI cleanly.
+they gate CI cleanly. Act on doctor *warnings* too: `pnpm up` never touches
+files `create-pracht` wrote, so a warning is how an older scaffold learns it
+needs a config change — for example adding `"src/**/*.d.ts"` to the
+`include` of `tsconfig.client.json`, without which typed route hooks are
+`unknown` in client code and `<Link route>` accepts any string.
 
 ## Step 7: Rollback note
 

package/src/index.js

@@ -5,6 +5,8 @@ import { basename, dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
+import { loadFallbackVersionRanges } from "./versions.js";
+
 export class ValidationError extends Error {
   constructor(message) {
     super(message);
@@ -12,22 +14,6 @@ export class ValidationError extends Error {
   }
 }
 
-const FALLBACK_VERSION_RANGES = {
-  "@pracht/adapter-cloudflare": "^0.5.8",
-  "@pracht/adapter-netlify": "^0.1.0",
-  "@pracht/adapter-node": "^0.3.8",
-  "@pracht/adapter-static": "^0.1.0",
-  "@pracht/adapter-vercel": "^0.2.8",
-  "@pracht/cli": "^1.11.0",
-  "@pracht/core": "^0.14.0",
-  "@pracht/vite-plugin": "^0.9.0",
-  "@tailwindcss/vite": "^4.1.0",
-  "netlify-cli": "^21.6.0",
-  tailwindcss: "^4.1.0",
-  typescript: "^6.0.0",
-  vercel: "^56.5.0",
-};
-
 /**
  * Cloudflare `compatibility_date` for scaffolded apps.
  *
@@ -105,6 +91,24 @@ function readFileSyncSafe(path) {
 
 const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 
+// Used only when the registry lookup fails. The `@pracht/*` ranges are the
+// versions this create-pracht was built alongside (see src/versions.js).
+const FALLBACK_VERSION_RANGES = {
+  "@tailwindcss/vite": "^4.1.0",
+  "netlify-cli": "^21.6.0",
+  tailwindcss: "^4.1.0",
+  typescript: "^6.0.0",
+  vercel: "^56.5.0",
+  ...loadFallbackVersionRanges(PACKAGE_ROOT),
+};
+
+// The Node floor every pracht package declares, read from this package's own
+// engines field so a bump lands in scaffolded apps without a second edit.
+const NODE_MINIMUM = (
+  JSON.parse(readFileSyncSafe(resolve(PACKAGE_ROOT, "package.json"))).engines?.node ?? ">=22.18"
+).replace(/^\D*/, "");
+const NODE_MAJOR = NODE_MINIMUM.split(".")[0];
+
 // The published package bundles a copy of the repo skills (see
 // scripts/sync-skills.js); inside the monorepo we fall back to the source.
 const SKILL_DIRS = [resolve(PACKAGE_ROOT, "skills"), resolve(PACKAGE_ROOT, "../../skills")];
@@ -225,7 +229,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const { pnpmWorkspaceNotice } = await scaffoldProject({
+  const { pnpmWorkspaceNotice, versionFallbacks } = await scaffoldProject({
     adapter: ADAPTERS[resolvedAdapter],
     agentSkills,
     agentTools: resolvedAgentTools,
@@ -289,6 +293,7 @@ export async function run(argv = process.argv.slice(2)) {
         pnpmWorkspaceNotice,
         router: resolvedRouter,
         tailwind: resolvedTailwind,
+        versionFallbacks,
       }),
     );
   } else {
@@ -303,6 +308,7 @@ export async function run(argv = process.argv.slice(2)) {
       router: resolvedRouter,
       skipInstall: options.skipInstall,
       tailwind: resolvedTailwind,
+      versionFallbacks,
     });
   }
 }
@@ -319,7 +325,7 @@ export async function scaffoldProject({
   targetDir,
 }) {
   const packageName = toPackageName(basename(targetDir));
-  const { files, pnpmWorkspaceNotice } = await buildProjectFiles({
+  const { files, pnpmWorkspaceNotice, versionFallbacks } = await buildProjectFiles({
     adapter,
     agentSkills,
     agentTools,
@@ -347,7 +353,7 @@ export async function scaffoldProject({
   // AGENTS.md (and the CLAUDE.md alias pointing at it) are agent tooling too —
   // `--no-agent-tools` means a project with none of it, not "all of it except
   // the instruction files". README.md carries the same commands for humans.
-  if (!agentTools) return { pnpmWorkspaceNotice };
+  if (!agentTools) return { pnpmWorkspaceNotice, versionFallbacks };
 
   try {
     await symlink("AGENTS.md", resolve(targetDir, "CLAUDE.md"));
@@ -359,7 +365,7 @@ export async function scaffoldProject({
     }
   }
 
-  return { pnpmWorkspaceNotice };
+  return { pnpmWorkspaceNotice, versionFallbacks };
 }
 
 export function getPackageManager(userAgent = process.env.npm_config_user_agent ?? "") {
@@ -676,7 +682,13 @@ function normalizeAdapter(value) {
   return null;
 }
 
+/**
+ * Latest published ranges for `packageNames`. `fallbacks` lists the packages
+ * whose registry lookup failed and got the bundled range instead; a scaffold
+ * that asked for no lookup (`remote: false`) reports none.
+ */
 async function resolveVersions(packageNames, { remote = true } = {}) {
+  const fallbacks = [];
   const entries = await Promise.all(
     packageNames.map(async (name) => {
       const fallback = FALLBACK_VERSION_RANGES[name] ?? "latest";
@@ -684,11 +696,13 @@ async function resolveVersions(packageNames, { remote = true } = {}) {
       try {
         return [name, `^${await fetchLatestVersion(name)}`];
       } catch {
+        fallbacks.push(name);
         return [name, fallback];
       }
     }),
   );
-  return Object.fromEntries(entries);
+  const versions = Object.fromEntries(entries);
+  return { fallbacks: fallbacks.sort().map((name) => `${name}@${versions[name]}`), versions };
 }
 
 async function buildProjectFiles({
@@ -720,7 +734,9 @@ async function buildProjectFiles({
     packagesToResolve.push("tailwindcss", "@tailwindcss/vite");
   }
 
-  const versions = await resolveVersions(packagesToResolve, { remote: resolveRemoteVersions });
+  const { fallbacks: versionFallbacks, versions } = await resolveVersions(packagesToResolve, {
+    remote: resolveRemoteVersions,
+  });
   const policyMajor = pnpmMajor ?? 11;
   const ancestorWorkspace =
     targetDir && packageManager === "pnpm" ? findAncestorPnpmWorkspace(targetDir) : null;
@@ -733,6 +749,11 @@ async function buildProjectFiles({
     : null;
 
   const files = {
+    // Build images (Cloudflare Pages, Netlify, most CI) pick a Node version
+    // from this file; without it they choose their own default, which is
+    // routinely older than pracht's `engines.node` and fails the build on a
+    // missing modern built-in rather than on a version mismatch.
+    ".nvmrc": `${NODE_MAJOR}\n`,
     ".gitignore":
       "dist\nnode_modules\n.netlify\n.wrangler\n.vercel\n.env*\n!.env.example\n.dev.vars\n# Keep .pracht/app-graph.json committed — it is the `pracht plan` snapshot.\n",
     "README.md": createReadme({
@@ -754,6 +775,7 @@ async function buildProjectFiles({
     }),
     "vite.config.ts": createViteConfig(adapter, router, tailwind),
     "tsconfig.json": createBaseTSConfig(adapter),
+    "tsconfig.client.json": createClientTSConfig(router),
   };
 
   // A static export has no server, so an API route would be a hard build
@@ -820,7 +842,7 @@ async function buildProjectFiles({
     files["pnpm-workspace.yaml"] = createPnpmWorkspaceConfig(adapter, tailwind, policyMajor);
   }
 
-  return { files, pnpmWorkspaceNotice };
+  return { files, pnpmWorkspaceNotice, versionFallbacks };
 }
 
 function createMcpConfig() {
@@ -871,7 +893,7 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
   const scripts = {
     build: "pracht build",
     dev: "pracht dev",
-    typecheck: "tsc --noEmit",
+    typecheck: "tsc --noEmit && tsc --noEmit --project tsconfig.client.json",
   };
 
   if (adapter.id === "node") {
@@ -887,7 +909,8 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
     "@pracht/cli": versions["@pracht/cli"],
     "@pracht/vite-plugin": versions["@pracht/vite-plugin"],
     preact: "^10.26.9",
-    "preact-render-to-string": "^6.5.13",
+    // At least @pracht/core's peer floor, or the first install warns.
+    "preact-render-to-string": "^6.7.0",
     typescript: versions["typescript"],
     vite: "^8.0.0",
   };
@@ -922,6 +945,10 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
       version: "0.0.0",
       private: true,
       type: "module",
+      // Matches every pracht package. Vercel reads this to choose a Node
+      // version; the `.nvmrc` next to it covers the hosts that read that
+      // instead.
+      engines: { node: `>=${NODE_MINIMUM}` },
       scripts,
       dependencies: {
         [adapter.packageName]: versions[adapter.packageName],
@@ -1020,6 +1047,7 @@ function createShellFile(projectName, tailwind = false) {
     "",
     "export function head() {",
     "  return {",
+    '    lang: "en",',
     '    meta: [{ content: "width=device-width, initial-scale=1", name: "viewport" }],',
     `    title: ${JSON.stringify(projectName)},`,
     "  };",
@@ -1164,6 +1192,30 @@ function createBaseTSConfig(_adapter) {
   return `${JSON.stringify(config, null, 2)}\n`;
 }
 
+function createClientTSConfig(router) {
+  const config = {
+    extends: "./tsconfig.json",
+    compilerOptions: {
+      customConditions: ["browser"],
+    },
+    // Declaration files carry the generated route/capability types and the
+    // app's `Register` augmentations; without them the client program sees
+    // `useRouteData()` as `unknown` and accepts any `<Link route>`.
+    include:
+      router === "pages"
+        ? ["src/pages/**/*", "src/islands/**/*", "src/**/*.d.ts"]
+        : ["src/routes/**/*", "src/shells/**/*", "src/islands/**/*", "src/**/*.d.ts"],
+  };
+
+  // Pages route modules are shared with the browser, but these two convention
+  // files are server-only. The base program still checks the whole project.
+  if (router === "pages") {
+    config.exclude = ["src/pages/**/_app.config.*", "src/pages/**/_middleware.*"];
+  }
+
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
 function createHealthRoute(adapter) {
   return [
     "export function GET() {",
@@ -1606,6 +1658,10 @@ function createAgentInstructions({
     lines.push("- `src/api/` — API route handlers");
   }
   lines.push(`- \`vite.config.ts\` — Vite config with the ${adapter.label} adapter`);
+  lines.push("- `tsconfig.json` — server-capable whole-project TypeScript checks");
+  lines.push(
+    "- `tsconfig.client.json` — browser-conditioned checks for routes, shells, islands, and their imports",
+  );
 
   if (tailwind) {
     lines.push("- `src/styles/global.css` — Tailwind CSS entry stylesheet, imported by the shell");
@@ -1781,6 +1837,11 @@ function createReadme({
     lines.push("- `src/api/health.ts` is a sample API route.");
   }
 
+  lines.push("- `tsconfig.json` — server-capable whole-project TypeScript checks.");
+  lines.push(
+    "- `tsconfig.client.json` — browser-conditioned checks for routes, shells, islands, and their imports.",
+  );
+
   if (tailwind) {
     lines.push("- `src/styles/global.css` is the Tailwind CSS entry, imported by the shell.");
   }
@@ -1953,6 +2014,7 @@ function printNextSteps({
   router,
   skipInstall,
   tailwind,
+  versionFallbacks = [],
 }) {
   const installCommand = packageManager === "npm" ? "npm install" : `${packageManager} install`;
   const devCommand = packageManager === "npm" ? "npm run dev" : `${packageManager} dev`;
@@ -1996,6 +2058,18 @@ function printNextSteps({
     console.log("Dependency installation did not complete. The project files were still created.");
   }
 
+  if (versionFallbacks.length > 0) {
+    console.log("");
+    console.log(
+      "Could not look up the latest versions on the npm registry, so package.json uses\n" +
+        "the ranges this create-pracht was released with. Check for newer versions once\n" +
+        "you are online:",
+    );
+    for (const entry of versionFallbacks) {
+      console.log(`  ${entry}`);
+    }
+  }
+
   if (pnpmWorkspaceNotice) {
     console.log("");
     console.log(