alexpricedev · alexpricedev · Aug 4, 2026 · Aug 4, 2026
diff --git a/.claude/skills/adding-a-feature/references/page.md b/.claude/skills/adding-a-feature/references/page.md
@@ -20,8 +20,10 @@ Takes fully resolved data as props, wrapped in the layout:
 `name` sets `data-page` on `<body>`, which is what dispatches the client script in step 6. Any
 form that POSTs needs `<CsrfField token={csrfToken} />`.
 
-This compiles with React's JSX runtime and renders once on the server — it never hydrates. Don't
-reach for `useState` here.
+This renders once on the server and never hydrates, so don't reach for `useState` here — it's the
+same Preact runtime the islands use, but the output is a string. Write SVG attributes in kebab-case
+(`stroke-width`, not `strokeWidth`); Preact passes camelCase through verbatim and the browser
+ignores it.
 
 ## 3. Controller — `src/server/controllers/app/dashboard.tsx`
 

diff --git a/.claude/skills/writing-tests/references/client.md b/.claude/skills/writing-tests/references/client.md
@@ -39,8 +39,7 @@ The fixture has to match what the server actually renders — the same ids, clas
 
 Render into a container and assert on the output:
 
-```ts
-/** @jsxImportSource preact */
+```tsx
 import { render } from "preact";
 
 const container = document.createElement("div");
@@ -49,8 +48,8 @@ render(<ProjectSearch projects={[{ id: 1, title: "Test" }]} />, container);
 expect(container.textContent).toContain("Test");
 ```
 
-The `/** @jsxImportSource preact */` pragma on line 1 is required — without it the file compiles
-against React's runtime and the render fails.
+Preact is the project-wide JSX runtime, so no pragma is needed. The file must be `.tsx` for the
+JSX to compile.
 
 Islands here reach outside their own tree (`ProjectSearch` toggles rows in the server-rendered
 table by id), so the fixture usually needs that surrounding markup in `document.body` too.

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,14 @@
+## What & why
+
+<!-- The change, and the problem it solves. Link the issue or runbook section if there is one. -->
+
+## Checks CI can't run
+
+<!-- Delete the lines that don't apply. -->
+
+- [ ] Verified in the browser — CI has none (screenshots welcome for UI changes)
+- [ ] New third-party script has a CSP entry, an SRI `integrity` hash, and a `preconnect` in `layouts.tsx`
+- [ ] New page is registered in `client/main.ts` and its CSS `@import`ed in `client/style.css`
+- [ ] New table is added to `cleanupTestData` in `test-utils/helpers.ts`
+- [ ] Changed headers, cookies, metadata, or email delivery → the matching `runbooks/` doc is updated
+- [ ] Renamed or deleted files that `START_PROMPT.md` lists → that file still matches reality
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -17,18 +17,24 @@ spec for everything else. This file is for the things you can't learn by reading
 
 ## Gotchas
 
-### Two JSX runtimes, no hydration
-
-Server templates and `src/server/components/` compile with React's runtime (`jsxImportSource: react`
-in `tsconfig.json`) and render once through `renderToString()` in `src/server/utils/response.ts`.
-None of it hydrates — there is no React on the client, and `useState` in a server component does
-nothing.
-
-Client interactivity is Preact islands. A client component opts in per-file with a
-`/** @jsxImportSource preact */` pragma on line 1, and the page script mounts it with
-`render()` from `preact`. Preact is marked `--external` in the build scripts and resolved at
-runtime from the import map in `src/server/components/layouts.tsx`, so the version pinned there
-must stay in step with `package.json`.
+### One JSX runtime, two execution models
+
+Everything compiles with Preact (`jsxImportSource: preact` in `tsconfig.json`) — there is no React
+in this project. What differs is *when* the JSX runs, and the `src/server/` vs `src/client/` split
+is the signal:
+
+- **`src/server/`** renders once through `renderToString()` from `preact-render-to-string` and ships
+  as HTML. It never hydrates, so `useState` in a server template does nothing.
+- **`src/client/`** mounts into the live DOM with `render()` from `preact` and is fully interactive.
+
+`preact` is a runtime **dependency**, not a devDependency — the server imports its JSX runtime, so a
+production install without it won't boot. The client bundle marks it `--external` and resolves it
+from the import map in `src/server/components/layouts.tsx`, so the version pinned there must stay in
+step with `package.json`.
+
+**Write SVG attributes in kebab-case** (`stroke-width`, not `strokeWidth`). Preact passes camelCase
+attribute names through verbatim, and the HTML parser doesn't recognise `strokeWidth` — the stroke
+silently renders at the default width. React used to rewrite these; nothing does now.
 
 No Web Components. Shadow DOM and custom-element lifecycles need browser infrastructure to test;
 pure functions and Preact islands are both testable under `bun:test`.

diff --git a/README.md b/README.md
@@ -108,7 +108,7 @@ Run the full suite: `bun run test`
 
 ### Frontend
 
-- **React JSX as a template engine** — server-side only, no client-side React, no virtual DOM, no hydration
+- **Preact JSX as a template engine** — server-rendered to a string, no hydration, no client-side framework runtime on the page by default. One JSX runtime across server and client, so there's no second React toolchain to reason about
 - **Bun CSS bundler** with `@import` resolution, CSS nesting, and minification — no external CSS tooling needed
 - **Opt-in interactivity** — sprinkle in any client-side framework per page (ships with a Preact island example loaded via CDN import map)
 - **Page lifecycle system** — `registerPage()` / `PageController` pattern with `init()` and `cleanup()` for per-page JS

diff --git a/bun.lock b/bun.lock
diff --git a/package.json b/package.json
@@ -31,16 +31,13 @@
     "@biomejs/biome": "2.0.5",
     "@happy-dom/global-registrator": "^20.8.3",
     "@types/bun": "1.3.0",
-    "@types/react": "^19.1.12",
-    "@types/react-dom": "19.1.9",
     "happy-dom": "^20.8.3",
     "husky": "9.1.7",
-    "preact": "^10.28.4",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "preact": "^10.28.4",
+    "preact-render-to-string": "^6.7.0",
     "resend": "^6.9.4"
   }
 }
diff --git a/src/client/components/project-search.test.tsx b/src/client/components/project-search.test.tsx
@@ -1,4 +1,3 @@
-/** @jsxImportSource preact */
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { render } from "preact";
 import { ProjectSearch } from "./project-search";

diff --git a/src/client/components/project-search.tsx b/src/client/components/project-search.tsx
@@ -1,4 +1,3 @@
-/** @jsxImportSource preact */
 import { useEffect, useState } from "preact/hooks";
 
 interface ProjectItem {

diff --git a/src/server/components/badge.tsx b/src/server/components/badge.tsx
@@ -1,6 +1,8 @@
+import type { ComponentChildren } from "preact";
+
 interface BadgeProps {
   variant: "admin" | "user";
-  children: React.ReactNode;
+  children: ComponentChildren;
 }
 
 export const Badge = ({ variant, children }: BadgeProps) => (

diff --git a/src/server/components/captcha-widget.test.tsx b/src/server/components/captcha-widget.test.tsx
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { renderToString } from "react-dom/server";
+import { renderToString } from "preact-render-to-string";
 import { CaptchaWidget } from "./captcha-widget";
 
 const challenge = {

diff --git a/src/server/components/captcha-widget.tsx b/src/server/components/captcha-widget.tsx
@@ -1,4 +1,4 @@
-import type { JSX } from "react";
+import type { JSX } from "preact";
 import { getAssetUrl } from "../services/assets";
 import {
   CAPTCHA_SOLUTION_FIELD,

diff --git a/src/server/components/csrf-field.tsx b/src/server/components/csrf-field.tsx
@@ -1,4 +1,4 @@
-import type { JSX } from "react";
+import type { JSX } from "preact";
 
 interface CsrfFieldProps {
   token: string | null;

diff --git a/src/server/components/data-table.tsx b/src/server/components/data-table.tsx
@@ -1,5 +1,7 @@
+import type { ComponentChildren } from "preact";
+
 interface DataTableProps {
-  children: React.ReactNode;
+  children: ComponentChildren;
   className?: string;
   // A caption names the table for screen readers. It's visually hidden by
   // default (pages usually have a visible heading already); pass

diff --git a/src/server/components/flash.tsx b/src/server/components/flash.tsx
@@ -1,6 +1,8 @@
+import type { ComponentChildren } from "preact";
+
 interface FlashProps {
   type: "success" | "error" | "warning";
-  children: React.ReactNode;
+  children: ComponentChildren;
 }
 
 const CLASS_NAMES = {

diff --git a/src/server/components/form-field.tsx b/src/server/components/form-field.tsx
@@ -1,7 +1,9 @@
+import type { ComponentChildren } from "preact";
+
 interface FormFieldProps {
   label: string;
   id: string;
-  children: React.ReactNode;
+  children: ComponentChildren;
 }
 
 export const FormField = ({ label, id, children }: FormFieldProps) => (

diff --git a/src/server/components/layouts.tsx b/src/server/components/layouts.tsx
@@ -1,4 +1,4 @@
-import type React from "react";
+import type { ComponentChildren } from "preact";
 
 import { getAssetUrl } from "../services/assets";
 import {
@@ -73,7 +73,7 @@ function HeadMeta({
 interface LayoutProps {
   title: string;
   name: string;
-  children: React.ReactNode;
+  children: ComponentChildren;
   user?: User | null;
   csrfToken?: string;
   description?: string;
@@ -180,7 +180,7 @@ function SiteFooter() {
 
 interface ErrorLayoutProps {
   title: string;
-  children: React.ReactNode;
+  children: ComponentChildren;
   nav?: boolean;
 }
 
@@ -213,7 +213,7 @@ export function ErrorLayout({ title, children, nav = true }: ErrorLayoutProps) {
 
 interface BaseLayoutProps {
   title: string;
-  children: React.ReactNode;
+  children: ComponentChildren;
   description?: string;
   canonicalPath?: string;
   noindex?: boolean;

diff --git a/src/server/components/logo.tsx b/src/server/components/logo.tsx
@@ -7,9 +7,9 @@ export function Logo() {
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
       aria-hidden="true"
     >
       <path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z" />

diff --git a/src/server/controllers/auth/login.test.ts b/src/server/controllers/auth/login.test.ts
@@ -98,7 +98,7 @@ describe("Login Controller", () => {
       const html = await response.text();
 
       expect(html).toContain("Check your email!");
-      expect(html).toContain("We&#x27;ve sent you a magic link");
+      expect(html).toContain("We've sent you a magic link");
     });
 
     test("shows error message when error is provided", async () => {

diff --git a/src/server/templates/home.tsx b/src/server/templates/home.tsx
@@ -31,9 +31,9 @@ export const Home = ({ user, csrfToken }: HomeProps) => (
           viewBox="0 0 24 24"
           fill="none"
           stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-          strokeLinejoin="round"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
           aria-hidden="true"
         >
           <path d="M12 3q1 4 4 6.5t3 5.5a1 1 0 0 1-14 0 5 5 0 0 1 1-3 1 1 0 0 0 5 0c0-2-1.5-3-1.5-5q0-2 2.5-4" />
@@ -201,9 +201,9 @@ export const Home = ({ user, csrfToken }: HomeProps) => (
           viewBox="0 0 24 24"
           fill="none"
           stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-          strokeLinejoin="round"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
           aria-hidden="true"
         >
           <path d="M12 21V7" />

diff --git a/src/server/templates/projects.tsx b/src/server/templates/projects.tsx
@@ -1,4 +1,4 @@
-import type { JSX } from "react";
+import type { JSX } from "preact";
 import { CsrfField } from "../components/csrf-field";
 import { DataTable } from "../components/data-table";
 import { Flash } from "../components/flash";

diff --git a/src/server/utils/errors.tsx b/src/server/utils/errors.tsx
@@ -1,5 +1,5 @@
-import type { JSX } from "react";
-import { renderToString } from "react-dom/server";
+import type { JSX } from "preact";
+import { renderToString } from "preact-render-to-string";
 import { ErrorPage } from "../templates/error";
 
 // Renders an error template to a bare HTML Response. Callers pass it through

diff --git a/src/server/utils/response.ts b/src/server/utils/response.ts
@@ -1,5 +1,5 @@
-import type { JSX } from "react";
-import { renderToString } from "react-dom/server";
+import type { JSX } from "preact";
+import { renderToString } from "preact-render-to-string";
 
 // Security headers are applied centrally to every response — see
 // `secureRoutes` and the `fetch` fallback in main.ts — so producers here only

diff --git a/tsconfig.json b/tsconfig.json
@@ -3,7 +3,7 @@
     "target": "ESNext",
     "module": "ESNext",
     "jsx": "react-jsx",
-    "jsxImportSource": "react",
+    "jsxImportSource": "preact",
     "moduleResolution": "Node",
     "strict": true,
     "noUnusedLocals": true,