create-pracht 0.2.6 → 0.4.0

package/skills/migrate-nextjs/SKILL.md

@@ -0,0 +1,519 @@
+---
+name: migrate-nextjs
+version: 1.1.0
+description: |
+  Migrate a Next.js application to Pracht. Converts App Router pages, layouts,
+  middleware, API routes, data fetching, and metadata to pracht equivalents.
+  Handles React→Preact, className→class, server components→loaders, and
+  manifest wiring.
+  Use when asked to "migrate from next", "convert next.js app", "port from
+  next to pracht", "nextjs migration", or "switch from next".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Migrate Next.js to Pracht
+
+Systematically migrate a Next.js application (App Router or Pages Router) to pracht — a full-stack Preact framework built on Vite.
+
+## Step 0: Assess the source project
+
+Before touching any code, understand what you're migrating:
+
+1. Read `next.config.js` / `next.config.mjs` / `next.config.ts` for custom config.
+2. Read `package.json` for React/Next versions and dependencies.
+3. Scan the directory structure:
+   - `app/` → App Router (Next 13+)
+   - `pages/` → Pages Router (legacy)
+   - `middleware.ts` → edge middleware
+   - `app/api/` or `pages/api/` → API routes
+4. Identify rendering patterns in use:
+   - `"use client"` directives → client components
+   - `async` page/layout components → server components with data fetching
+   - `generateStaticParams` → static generation
+   - `generateMetadata` / `metadata` export → head management
+   - Server Actions (`"use server"`) → mutations
+5. Note third-party integrations (auth, CMS, DB, analytics).
+
+Ask the user to confirm the migration scope if the project is large (>20 routes).
+
+If the pracht MCP server is registered (docs/MCP.md), use the `generate_route`/`generate_shell`/`generate_middleware`/`generate_api` MCP tools for scaffolding and `inspect_routes`/`inspect_api`/`doctor`/`verify` to check migration progress, instead of Bash. (`pracht inspect` needs the pracht plugin in the vite config; `inspect_build` needs a prior `pracht build`.)
+
+## Fast Path: Pages Router Projects
+
+If the source Next.js project uses the **pages router** (`pages/` directory), pracht's `pagesDir` plugin option provides a near-drop-in migration:
+
+1. Set `pracht({ pagesDir: "/src/pages" })` in `vite.config.ts`
+2. Copy `pages/` to `src/pages/`
+3. Convert `_app.tsx` to pracht shell format (`Shell` export + `children` prop)
+4. Convert `getServerSideProps`/`getStaticProps` to `loader` exports
+5. Add `export const RENDER_MODE = "ssg"` to static pages, `"ssr"` for dynamic (default is `"ssr"`)
+6. Run dev server, iterate on errors
+7. Optionally run `generateRoutesFile` to eject to explicit manifest
+
+For pages router projects, you can **skip manual manifest wiring entirely** (Phase 7 below).
+
+## Concept Mapping
+
+| Next.js                         | Pracht                                                          | Notes                                                                 |
+| ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `pages/` directory              | `pagesDir` plugin option                                        | Auto-discovers routes from 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`                    | Shells are named, not directory-nested                                |
+| `app/loading.tsx`               | `Loading` export on the shell                                   | Rendered as 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  |
+| `middleware.ts`                 | `src/middleware/*.ts` + `middleware` in `defineApp`             | Named, applied per route/group                                        |
+| `app/api/*/route.ts`            | `src/api/*.ts` with `GET`/`POST` exports                        | Auto-discovered, no manifest entry                                    |
+| `generateStaticParams`          | `getStaticPaths()` export                                       | Returns `RouteParams[]` of param objects                              |
+| `generateMetadata`              | `head()` export                                                 | Returns `{ title, meta }`                                             |
+| Server Components               | `loader()` export                                               | Data fetching moves to loader; component is always a Preact component |
+| `"use server"` actions          | API routes + `<Form>` / `fetch`                                 | Mutations move to `src/api/*`; return `Response` objects              |
+| `"use client"` (few, in a mostly-server app) | `hydration: "islands"` + `src/islands/`            | Only islands ship JS; see the islands note in Phase 4                 |
+| `revalidatePath` / `res.revalidate()` | `webhookRevalidate()` + `POST /__pracht/revalidate`       | On-demand ISG regeneration; combinable with `timeRevalidate(seconds)` |
+| `useRouter()` (next/navigation) | `useNavigate()` from pracht                                     | Accepts paths or typed route targets after `pracht typegen`           |
+| `useSearchParams()`             | `useLocation()` from pracht                                     | Returns `{ pathname, search }`; loaders also receive `url` with searchParams |
+| `useParams()`                   | `useParams()` from pracht                                       | Direct equivalent; also available as `params` in loader args          |
+| `next/link` `<Link>`            | `<Link route="...">` or plain `<a>`                            | Prefer typed `<Link>` for known app routes after `pracht typegen`; plain anchors still work |
+| `next/link` `prefetch={false}`  | `<Link prefetch="none">`                                        | Pracht prefetches on hover/focus by default; also `"viewport"`, `"render"` |
+| `useLinkStatus()` / pending UI  | `useNavigation()`                                               | `{ state, location, formData }` — powers progress bars and optimistic UI |
+| `next/image`                    | Standard `<img>`                                                | Use `vite-imagetools` plugin if optimization needed                   |
+| `next/head` or Metadata API     | `head()` export on route/shell                                  | Per-route and per-shell head merging                                  |
+| `className`                     | `class`                                                         | Preact uses `class` attribute                                         |
+| `React.useState` etc.           | `import { useState } from "preact/hooks"`                       | Preact hooks API is compatible                                        |
+| `React.useEffect`               | `import { useEffect } from "preact/hooks"`                      | Same API                                                              |
+| `import React from "react"`     | Remove — no import needed                                       | Pracht's Vite plugin handles JSX automatically                        |
+
+## Migration Procedure
+
+### Phase 1: Project setup
+
+1. Initialize the pracht project structure:
+   ```
+   src/
+     routes.ts          # Route manifest
+     routes/            # Route modules
+     shells/            # Layout shells
+     middleware/         # Server-side middleware
+     api/               # API routes
+   ```
+2. Create `vite.config.ts`:
+
+   ```ts
+   import { defineConfig } from "vite";
+   import { pracht } from "@pracht/vite-plugin";
+
+   export default defineConfig({
+     plugins: [pracht()],
+   });
+   ```
+
+3. Update `package.json`:
+   - Replace `react`, `react-dom` → `preact`
+   - Replace `next` → `@pracht/core` (framework runtime), `@pracht/cli` (provides the `pracht` bin), `@pracht/vite-plugin`, and `@pracht/adapter-node` (or target adapter). There is no package named `pracht`.
+   - Update scripts: `dev` → `pracht dev`, `build` → `pracht build`, `start` → `node dist/server/server.js` (Node.js) or a platform-specific deploy command; add `preview` → `pracht preview` to serve the production build locally
+4. Remove Next.js config files: `next.config.*`, `next-env.d.ts`, `.next/`
+5. If `tsconfig.json` has `"jsx": "preserve"`, change to `"jsx": "react-jsx"` and add `"jsxImportSource": "preact"`.
+
+### Phase 2: Convert layouts → shells
+
+For each `layout.tsx`:
+
+**Next.js:**
+
+```tsx
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body className="root">{children}</body>
+    </html>
+  );
+}
+```
+
+**Pracht:**
+
+```tsx
+import type { ShellProps } from "@pracht/core";
+
+export function Shell({ children }: ShellProps) {
+  return (
+    <div class="root">
+      <main>{children}</main>
+    </div>
+  );
+}
+
+export function head() {
+  return { title: "My App" };
+}
+```
+
+Key differences:
+
+- Pracht shells do NOT render `<html>`, `<head>`, or `<body>` — the framework owns the HTML document.
+- Use `class` not `className`.
+- Register in `defineApp({ shells: { main: "./shells/main.tsx" } })`.
+
+### Phase 3: Convert pages → route modules
+
+For each `page.tsx`:
+
+**Next.js (Server Component with data):**
+
+```tsx
+async function getData() {
+  const res = await fetch("https://api.example.com/data");
+  return res.json();
+}
+
+export default async function Page() {
+  const data = await getData();
+  return <div className="page">{data.title}</div>;
+}
+
+export async function generateMetadata() {
+  const data = await getData();
+  return { title: data.title };
+}
+```
+
+**Pracht:**
+
+```tsx
+import type { LoaderArgs, RouteComponentProps } from "@pracht/core";
+
+export async function loader(_args: LoaderArgs) {
+  const res = await fetch("https://api.example.com/data");
+  return res.json();
+}
+
+export function head({ data }: { data: Awaited<ReturnType<typeof loader>> }) {
+  return { title: data.title };
+}
+
+export default function Page({ data }: RouteComponentProps<typeof loader>) {
+  return <div class="page">{data.title}</div>;
+}
+```
+
+Key transforms:
+
+- Server-side data fetching → `loader()` export
+- `generateMetadata` → `head()` export
+- Keep `export default function Page` as the page component
+- `className` → `class`
+- No `async` components — data comes via props from loader
+
+### Phase 4: Convert client components
+
+**Next.js:**
+
+```tsx
+"use client";
+import { useState } from "react";
+
+export default function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+
+**Pracht:**
+
+```tsx
+import { useState } from "preact/hooks";
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+
+Key transforms:
+
+- Remove `"use client"` directive — not needed in pracht
+- `import { ... } from "react"` → `import { ... } from "preact/hooks"` or `import { ... } from "preact/compat"`
+- `import { ... } from "react-dom"` → `import { ... } from "preact/compat"`
+
+**Islands note:** if the source app is mostly server components with only a handful of `"use client"` components, don't silently regress those pages to full-page hydration. Set `hydration: "islands"` on the route (or `export const HYDRATION = "islands"` in pages mode) and move the interactive components to `src/islands/` — the rest of the page renders as inert HTML and only the islands ship JavaScript. See `docs/ISLANDS.md`.
+
+### Phase 5: Convert API routes
+
+**Next.js (`app/api/users/route.ts`):**
+
+```ts
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(request: NextRequest) {
+  const users = await getUsers();
+  return NextResponse.json(users);
+}
+```
+
+**Pracht (`src/api/users.ts`):**
+
+```ts
+import type { ApiRouteArgs } from "@pracht/core";
+
+export async function GET({ request }: ApiRouteArgs) {
+  const users = await getUsers();
+  return Response.json(users);
+}
+```
+
+Key transforms:
+
+- `NextRequest` → standard `Request` (via `ApiRouteArgs`)
+- `NextResponse.json()` → `Response.json()` (Web standard)
+- Dynamic segments: `app/api/users/[id]/route.ts` → `src/api/users/[id].ts`
+- No manifest wiring needed — auto-discovered
+
+### Phase 6: Convert middleware
+
+**Next.js (`middleware.ts`):**
+
+```ts
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+export function middleware(request: NextRequest) {
+  const session = request.cookies.get("session");
+  if (!session) return NextResponse.redirect(new URL("/login", request.url));
+  return NextResponse.next();
+}
+
+export const config = { matcher: ["/dashboard/:path*"] };
+```
+
+**Pracht (`src/middleware/auth.ts`):**
+
+```ts
+import { redirect, type MiddlewareFn } from "@pracht/core";
+
+export const middleware: MiddlewareFn = async ({ request }, next) => {
+  const session = request.headers.get("cookie")?.includes("session");
+  if (!session) return redirect("/login", { request });
+  return next();
+};
+```
+
+Then apply it in the manifest:
+
+```ts
+group({ middleware: ["auth"] }, [
+  route("/dashboard", () => import("./routes/dashboard.tsx"), { render: "ssr" }),
+]);
+```
+
+Key transforms:
+
+- Path matching moves from `config.matcher` to manifest group/route assignment
+- `NextResponse.redirect()` → `return redirect("/path", { request })`
+- `NextResponse.next()` → `return next()`
+- Pracht middleware is **wrap-around** (Hono/Koa/Astro shape), so you can
+  also `await next()` and observe the response — useful for tracing.
+
+### Phase 7: Wire the route manifest
+
+**Note:** For pages router projects using `pagesDir`, this phase is automatic. Skip to Phase 8.
+
+Instead of hand-writing every entry, prefer `pracht generate route --path ... --render ...` (with `--shell`/`--middleware`/`--loader` as needed) per page: it creates a wired skeleton **and** updates `src/routes.ts` for you — then port the Next.js component/loader bodies into the generated files. Hand-write the manifest only for shapes the generator cannot express.
+
+Build `src/routes.ts` mapping every migrated page. Module references accept `() => import("./path")` (enables IDE navigation) or plain `"./path"` strings — both work:
+
+```ts
+import { defineApp, group, route } from "@pracht/core";
+
+export const app = defineApp({
+  shells: {
+    main: () => import("./shells/main.tsx"),
+  },
+  middleware: {
+    auth: () => import("./middleware/auth.ts"),
+  },
+  routes: [
+    group({ shell: "main" }, [
+      route("/", () => import("./routes/home.tsx"), { render: "ssg" }),
+      route("/about", () => import("./routes/about.tsx"), { render: "ssg" }),
+      route("/dashboard", () => import("./routes/dashboard.tsx"), {
+        render: "ssr",
+        middleware: ["auth"],
+      }),
+      route("/blog/:slug", () => import("./routes/blog-post.tsx"), { render: "isg" }),
+    ]),
+  ],
+  notFound: {
+    component: () => import("./routes/not-found.tsx"),
+    shell: "main",
+  },
+});
+```
+
+Choose render modes based on the Next.js original:
+
+- Static pages (no data fetching, or `generateStaticParams`) → `"ssg"`
+- Dynamic pages (`cookies()`, `headers()`, per-request data) → `"ssr"`
+- ISR pages (`revalidate` option) → `"isg"` with `timeRevalidate(seconds)`
+- On-demand ISR (`revalidatePath` / `res.revalidate()`) → add `webhookRevalidate()` (alone or as `[timeRevalidate(seconds), webhookRevalidate()]`) and trigger via `POST /__pracht/revalidate`
+- Client-only pages → `"spa"`
+
+### Phase 8: Handle common patterns
+
+#### `next/link` → typed `<Link>` or plain `<a>`
+
+After manifest wiring is in place, run `pracht typegen` and prefer route-id based links for known app routes:
+
+```tsx
+// Next.js
+import Link from "next/link";
+<Link href={`/products/${id}`}>Product</Link>
+
+// Pracht
+import { Link } from "@pracht/core";
+<Link route="product" params={{ id }}>Product</Link>
+```
+
+Plain anchors still work for simple, external, or user-provided URLs because the client router intercepts same-origin `<a>` clicks:
+
+```tsx
+<a href="/about">About</a>
+```
+
+`<Link>` also accepts navigation-behavior props: `prefetch` (`"none" | "intent" | "viewport" | "render"`, default `"intent"` on hover/focus — the equivalent of `next/link`'s `prefetch` tuning), `preserveScroll` (skip the scroll-to-top reset), and `viewTransition` (wrap the navigation in `document.startViewTransition()` where supported). Scroll restoration on back/forward works out of the box, like Next.js.
+
+#### `next/image` → `<img>`
+
+```tsx
+// Next.js
+import Image from "next/image";
+<Image src="/photo.jpg" width={500} height={300} alt="Photo" />
+
+// Pracht
+<img src="/photo.jpg" width={500} height={300} alt="Photo" />
+```
+
+#### `useRouter` → navigation
+
+```tsx
+// Next.js
+import { useRouter } from "next/navigation";
+const router = useRouter();
+router.push("/dashboard");
+
+// Pracht
+import { useNavigate } from "@pracht/core";
+const navigate = useNavigate();
+navigate("/dashboard");
+
+// After `pracht typegen`, prefer route ids for known routes
+navigate({ route: "dashboard" });
+```
+
+#### Server Actions → API routes
+
+```tsx
+// Next.js
+"use server";
+async function createPost(formData: FormData) {
+  await db.insert({ title: formData.get("title") });
+  revalidatePath("/posts");
+}
+
+// Pracht — API route handler
+import type { ApiRouteArgs } from "@pracht/core";
+
+export async function POST({ request }: ApiRouteArgs) {
+  const form = await request.formData();
+  await db.insert({ title: form.get("title") });
+  // revalidatePath("/posts") equivalent: regenerate the ISG page on demand
+  await fetch(new URL("/__pracht/revalidate", request.url), {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${process.env.PRACHT_REVALIDATE_TOKEN}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ paths: ["/posts"] }),
+  });
+  return new Response(null, {
+    status: 303,
+    headers: { location: "/posts" },
+  });
+}
+```
+
+For the revalidation call to take effect, the `/posts` route must be `render: "isg"` and opt in with `revalidate: webhookRevalidate()` (or `[timeRevalidate(seconds), webhookRevalidate()]`) in the manifest — import both from `@pracht/core` — and `PRACHT_REVALIDATE_TOKEN` must be set in the runtime environment. If `/posts` is a plain SSR route, skip the revalidation call; the redirect re-renders it fresh anyway.
+
+#### `cookies()` / `headers()` → loader args
+
+```tsx
+// Next.js
+import { cookies, headers } from "next/headers";
+const session = cookies().get("session");
+const ua = headers().get("user-agent");
+
+// Pracht — available in loader args
+export async function loader({ request }: LoaderArgs) {
+  const cookies = request.headers.get("cookie");
+  const ua = request.headers.get("user-agent");
+  return {
+    /* ... */
+  };
+}
+```
+
+### Phase 9: Clean up
+
+1. Remove all `"use client"` and `"use server"` directives.
+2. Remove all `next/*` imports (`next/link`, `next/image`, `next/navigation`, `next/headers`).
+3. Search for remaining `className` → replace with `class`.
+4. Search for remaining `react` imports → replace with `preact` equivalents.
+5. Remove `next.config.*`, `next-env.d.ts`, `.next/` directory.
+6. Run `pracht typegen` if route ids/paths changed or if you converted links/navigation to typed route ids.
+7. Run the dev server (`pracht dev`) and fix any remaining issues.
+
+## Dependency Mapping
+
+| Next.js package | Pracht equivalent                                                            |
+| --------------- | ---------------------------------------------------------------------------- |
+| `next`          | `@pracht/core` + `@pracht/cli` + `@pracht/vite-plugin` + `@pracht/adapter-node` (or target adapter) |
+| `react`         | `preact`                                                |
+| `react-dom`     | `preact`                                                |
+| `@next/font`    | CSS `@font-face` or `fontsource` packages               |
+| `@next/mdx`     | `@mdx-js/rollup` (Vite plugin)                          |
+| `next-auth`     | Direct integration in middleware/loaders                |
+| `next/og`       | `@vercel/og` or custom solution                         |
+
+## React Library Compatibility
+
+Many React libraries work with Preact via `preact/compat`. Add aliases in `vite.config.ts` if needed:
+
+```ts
+resolve: {
+  alias: {
+    "react": "preact/compat",
+    "react-dom": "preact/compat",
+    "react/jsx-runtime": "preact/jsx-runtime",
+  }
+}
+```
+
+Note: The pracht Vite plugin sets these aliases automatically. Only add manual aliases if a dependency doesn't resolve correctly.
+
+## Rules
+
+1. Always read the Next.js source before converting — understand what each file does.
+2. Migrate in phases: setup → shells → routes → API → middleware → manifest → cleanup.
+3. Prefer the simplest pracht equivalent. Don't over-engineer the migration.
+4. Identify React libraries that need `preact/compat` aliasing and flag them.
+5. After migration, run `pracht dev` to verify. Fix errors iteratively.
+6. If a Next.js feature has no pracht equivalent, explain the gap and suggest alternatives.
+7. Use Preact idioms: `class` not `className`, no `React` import needed, `preact/hooks` for hooks.
+
+$ARGUMENTS

package/skills/pracht-debug/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: pracht-debug
+version: 1.3.0
+description: |
+  Pracht framework-aware debugging. Systematically investigates route matching,
+  loader/API route errors, rendering issues, middleware, API routes, HMR, and build
+  problems. Uses pracht's architecture knowledge to find root causes fast.
+  Use when asked to "debug this", "fix this bug", "why is this broken",
+  "blank page", "hydration mismatch", or "404 on my route".
+  Proactively suggest when the user reports errors or unexpected behavior
+  in a pracht application.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Debug
+
+Framework-aware debugging for pracht applications — a full-stack Preact framework built on Vite.
+
+The user will describe a symptom (error, unexpected behavior, blank page, etc.). Investigate systematically using the checklist below, stopping when you find the root cause.
+
+Before deep manual inspection, prefer running `pracht verify` (add `--changed` to scope the checks to git-changed files) for a fast agent loop or `pracht doctor` when the problem could be caused by broader broken app wiring or missing files.
+When another agent/tool needs the framework's resolved graph, prefer `pracht inspect routes --json`, `pracht inspect api --json`, or `pracht inspect build --json` over reconstructing it from source files. Prerequisites: `pracht inspect` needs the pracht plugin registered in the project's vite config, and `pracht inspect build` needs a prior `pracht build`.
+If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_routes`/`inspect_api`/`doctor`/`verify` MCP tools over shelling out — same payloads, structured results.
+While the dev server is running, `GET /_pracht` serves a devtools page with the same resolved route/API graph (raw JSON at `/_pracht.json`) — useful when you have a browser or `curl` handy but no CLI access. Dev SSR responses also carry a `Server-Timing` header (`mw`, `loader`, `render` durations in ms) — check it in the browser Network panel or with `curl -sI` to see which phase makes a route slow.
+
+## Iron Law
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+## Debugging Checklist
+
+Work through these in order, stopping when you find the root cause:
+
+### 1. Route matching
+
+- Run `pracht verify --changed` first if you want a cheap changed-file confidence check.
+- Run `pracht doctor` if the route might be missing, miswired, or pointing at a missing module across the project.
+- For machine-readable route wiring, run `pracht inspect routes --json`. With a running dev server, `curl http://localhost:5173/_pracht.json` returns the same graph.
+- Read `src/routes.ts` — is the route defined? Is the path correct?
+- Check for typos in file paths (the manifest uses relative paths like `"./routes/home.tsx"`).
+- For dynamic segments, verify bracket syntax: `route("/users/:id", ...)` in manifest, `[id].ts` in filenames.
+- Grep for the route path across the manifest and check `matchAppRoute()` logic if needed.
+
+### 2. Typed route/link issues
+
+- If `<Link route="...">`, `href("...")`, or route-object `useNavigate()` fails to typecheck, run `pracht typegen --check` to detect stale generated files.
+- Run `pracht inspect routes --json` and confirm the route id exists. If it is a fallback id, remember path changes can rename it.
+- Check generated `src/pracht.d.ts` for inferred params. `:id`, `*`, and `:path*` params are required; extra params should fail at typecheck time.
+- If runtime navigation throws `Unknown pracht route id "..."`, in dev the error includes a `Did you mean "..."?` suggestion and the list of registered route ids (production builds tree-shake this and throw the bare error) — check for a typo first, then ensure `pracht typegen` was run and the component is rendered inside the pracht route tree.
+- For unexpected URLs, reproduce with `href(routeId, options)` and compare against the route's resolved path and params.
+
+### 3. Loader / API route errors
+
+- For slow pages, read the dev `Server-Timing` response header (`mw`/`loader`/`render` in ms) to see which phase dominates before reading code.
+- Read the route module's `loader` function or the matching API route handler.
+- Check that `loader` returns serializable data (no functions, no circular refs).
+- Check that API route handlers return `Response` objects and branch on `request.method` when using a default export.
+- Look for unhandled promise rejections or thrown errors.
+- Verify `LoaderArgs` destructuring matches what the framework provides: `{ request, params, context, signal, url, route }`.
+
+### 4. Rendering issues
+
+- **Blank page**: Check if the route has `render: "spa"` (no SSR content expected) vs `"ssr"`.
+- **Hydration mismatch**: In dev, pracht surfaces a fixed-position red banner at the top of the page listing each mismatched component (via Preact's `options.__m` hook). Compare server-rendered HTML vs client component output. Common causes:
+  - Date/time rendering differences
+  - Browser-only APIs used during SSR (`window`, `document`, `localStorage`)
+  - Conditional rendering based on client state
+- **Missing shell**: Referencing an unregistered shell name throws at manifest resolution — `Unknown shell "..." for route "...". Did you mean "..."? Registered shells: ...` — and shows up in the dev error overlay as soon as the server loads the manifest. Verify the shell is registered in `defineApp({ shells: { ... } })` and assigned to the route/group.
+- **404 page**: Route not matched — check manifest wiring (step 1). In `pracht dev`, unmatched navigations render a dev-only 404 page listing every registered route with its render mode; compare the requested path against that table. The route table is also printed on dev-server startup and available via `pracht inspect routes`. Apps that declare `defineApp({ notFound })` render their own 404 page instead (in dev and production alike), so the route table is not shown — check `pracht inspect routes` directly. A 404 on a URL you *do* expect to work usually means the loader threw `notFound()`, not that matching failed.
+
+### 5. Middleware issues
+
+- Verify middleware is registered in `defineApp({ middleware: { ... } })`. An
+  unregistered name (on a route, group, or `api.middleware`) throws at manifest
+  resolution — `Unknown middleware "..." for route "...". Did you mean "..."? Registered middleware: ...`
+- Verify middleware is applied to the route/group: `middleware: ["name"]`.
+- Middleware is wrap-around: it must always return a `Response`, either by
+  calling `await next()` (to continue down the chain) or short-circuiting.
+- Common bugs:
+  - Forgetting `return next()` → `Middleware "..." did not return a Response`
+  - Calling `next()` twice → `Middleware "..." called next() multiple times`
+  - Mutating a non-object `context` → mutations don't propagate; always pass
+    an object as the request context.
+- Middleware runs server-side only, wrapping loaders and API handlers.
+
+### 6. API route issues
+
+- API routes live in `src/api/` and are auto-discovered (no manifest entry needed).
+- For machine-readable API inventory, run `pracht inspect api --json`.
+- File path maps to URL: `src/api/health.ts` → `/api/health`, `src/api/users/[id].ts` → `/api/users/:id`.
+- Each file exports named HTTP method handlers (`GET`, `POST`, etc.) or one default handler.
+- Missing method handler → 405 response when there is no default handler.
+- Default handlers receive the same route args and can branch on `request.method`.
+- Handlers must return `Response` objects.
+
+### 7. Vite plugin / HMR issues
+
+- Check `vite.config.ts` — is `pracht()` plugin included?
+- Virtual modules: `virtual:pracht/client` (hydration), `virtual:pracht/server` (SSR), `virtual:pracht/islands-client` (islands hydration).
+- HMR: changes to `src/routes.ts` restart the dev server (`server.restart()`, not a browser-side full reload); changes to route/shell/middleware/API/server/islands files invalidate the server module.
+- If HMR seems broken, check that the file is in one of the watched directories (`src/routes/`, `src/shells/`, `src/middleware/`, `src/api/`, `src/server/`, `src/islands/`).
+
+### 8. Build / deployment issues
+
+- `pracht build` runs client + server builds, then prerenders SSG/ISG routes.
+- `pracht preview` builds and serves the production output locally (Node runs `dist/server/server.js`, Cloudflare delegates to `wrangler dev`).
+- `pracht inspect build --json` reports the resolved adapter target plus client/CSS/JS manifests from the latest build output (requires a prior `pracht build`).
+- Check `dist/client/` for client assets and `dist/server/` for server bundle.
+- ISG manifest: `dist/server/isg-manifest.json`. On Cloudflare the build also copies it to `dist/client/_pracht/isg.json` for the worker runtime to read via the assets binding.
+- Adapter mismatch: ensure `pracht({ adapter: nodeAdapter() })` or `cloudflareAdapter()` matches deployment target.
+
+## Key Files
+
+| File                  | Purpose                                               |
+| --------------------- | ----------------------------------------------------- |
+| `src/routes.ts`       | App manifest — all route/shell/middleware definitions |
+| `vite.config.ts`      | Vite config with `pracht()` plugin                    |
+| `src/routes/*.tsx`    | Route modules (loader, Component)                     |
+| `src/shells/*.tsx`    | Shell layout components                               |
+| `src/middleware/*.ts` | Server-side middleware                                |
+| `src/api/*.ts`        | API route handlers                                    |
+
+## Framework Internals
+
+- `handlePrachtRequest()` dispatches: API routes → middleware → loader → render → HTML assembly
+- Route state JSON: returned when `x-pracht-route-state-request` header is present (client-side navigation)
+- Hydration state: injected as `window.__PRACHT_STATE__` in the HTML
+- Client router: `initClientRouter()` intercepts link clicks and fetches route state JSON
+
+## Rules
+
+1. Always read the relevant source files before diagnosing.
+2. Start with the most likely cause based on the symptom, not a full audit.
+3. When you find the root cause, explain _why_ it breaks and fix it.
+4. If wiring looks suspicious, run `pracht verify` first, then `pracht doctor` if you need the full-project view. If running the dev server or tests would help, do so (`pracht dev`, `pnpm test`, `pnpm e2e`).
+5. After fixing, verify the fix works (run relevant test or check dev server output).
+6. Never say "this should fix it." Verify and prove it.
+
+$ARGUMENTS