nerdsystem 0.0.3 → 0.0.4

package/dist/commands/init.js

@@ -104,4 +104,4 @@ export async function init(dir, args) {
     log.ok(`Ready. Next:\n  cd ${dir}\n  pnpm install\n  nerd dev\n\nThen open the folder in your coding agent and ask it to build the first feature; the nerdsystem skill walks it through.\nDeploys go to ${project.url}`);
 }
 // Kept in sync with packages/sdk/package.json by the release script.
-const SDK_VERSION = "0.0.3";
+const SDK_VERSION = "0.0.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nerdsystem",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "nerd: deploy apps to nerdsystem from the terminal or a coding agent.",
   "type": "module",
   "bin": {

package/template/.claude/skills/nerdsystem/SKILL.md

@@ -13,7 +13,7 @@ If this project still has the template's todo app (the `todos` table and `src/se
 
 1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
 2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
-3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. The template is a normal website: a public homepage at `/`, auth pages at `/login`, `/signup`, `/forgot-password`, `/reset-password`, and a signed-in area. Reshape it to the idea (a public landing page with sign-in in the header, a members-only area, an admin section) rather than forcing a login wall; the forms already work.
 4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
 5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
 6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
@@ -47,12 +47,13 @@ Once the repo is linked (`nerd github connect`, then `nerd github link owner/rep
 
 ## Auth and authorization
 
-The SDK handles sessions. There is no login code to write.
+The SDK handles sessions. There is no server-side login code to write; the client only decides where the forms appear.
 
 - `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
 - `requireAuth()` middleware returns 401 when signed out.
 - `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
-- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them, and `src/client/auth.tsx` turns them into drop-in components: `SignInForm`, `SignUpForm`, `ForgotPasswordForm`, `ResetPasswordForm`, plus `useUser()` for the current user anywhere in the tree and `RequireUser` to guard a screen (it sends signed-out visitors to `/login?next=...`). Put the forms wherever the design wants: their own pages, a modal, inline on the homepage. Password reset emails link to `/reset-password?token=...`; keep that route if you restructure the client.
+- Pages are public by default because they are static files. Guarding a screen with `RequireUser` is a courtesy to the visitor; the data is protected by `requireAuth()` / `requireRole()` on the API routes, which is what the platform checks.
 - Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
 - To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
 

package/template/.cursor/rules/nerdsystem.mdc

@@ -2,7 +2,7 @@
 description: How to build, run, and deploy this app on nerdsystem. Applies to server, database, auth, and deploy work.
 alwaysApply: true
 ---
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (2834c4c81f7f); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (ca70e3512072); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -14,7 +14,7 @@ If this project still has the template's todo app (the `todos` table and `src/se
 
 1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
 2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
-3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. The template is a normal website: a public homepage at `/`, auth pages at `/login`, `/signup`, `/forgot-password`, `/reset-password`, and a signed-in area. Reshape it to the idea (a public landing page with sign-in in the header, a members-only area, an admin section) rather than forcing a login wall; the forms already work.
 4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
 5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
 6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
@@ -48,12 +48,13 @@ Once the repo is linked (`nerd github connect`, then `nerd github link owner/rep
 
 ## Auth and authorization
 
-The SDK handles sessions. There is no login code to write.
+The SDK handles sessions. There is no server-side login code to write; the client only decides where the forms appear.
 
 - `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
 - `requireAuth()` middleware returns 401 when signed out.
 - `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
-- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them, and `src/client/auth.tsx` turns them into drop-in components: `SignInForm`, `SignUpForm`, `ForgotPasswordForm`, `ResetPasswordForm`, plus `useUser()` for the current user anywhere in the tree and `RequireUser` to guard a screen (it sends signed-out visitors to `/login?next=...`). Put the forms wherever the design wants: their own pages, a modal, inline on the homepage. Password reset emails link to `/reset-password?token=...`; keep that route if you restructure the client.
+- Pages are public by default because they are static files. Guarding a screen with `RequireUser` is a courtesy to the visitor; the data is protected by `requireAuth()` / `requireRole()` on the API routes, which is what the platform checks.
 - Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
 - To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
 

package/template/.github/copilot-instructions.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (2834c4c81f7f); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (ca70e3512072); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -10,7 +10,7 @@ If this project still has the template's todo app (the `todos` table and `src/se
 
 1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
 2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
-3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. The template is a normal website: a public homepage at `/`, auth pages at `/login`, `/signup`, `/forgot-password`, `/reset-password`, and a signed-in area. Reshape it to the idea (a public landing page with sign-in in the header, a members-only area, an admin section) rather than forcing a login wall; the forms already work.
 4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
 5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
 6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
@@ -44,12 +44,13 @@ Once the repo is linked (`nerd github connect`, then `nerd github link owner/rep
 
 ## Auth and authorization
 
-The SDK handles sessions. There is no login code to write.
+The SDK handles sessions. There is no server-side login code to write; the client only decides where the forms appear.
 
 - `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
 - `requireAuth()` middleware returns 401 when signed out.
 - `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
-- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them, and `src/client/auth.tsx` turns them into drop-in components: `SignInForm`, `SignUpForm`, `ForgotPasswordForm`, `ResetPasswordForm`, plus `useUser()` for the current user anywhere in the tree and `RequireUser` to guard a screen (it sends signed-out visitors to `/login?next=...`). Put the forms wherever the design wants: their own pages, a modal, inline on the homepage. Password reset emails link to `/reset-password?token=...`; keep that route if you restructure the client.
+- Pages are public by default because they are static files. Guarding a screen with `RequireUser` is a courtesy to the visitor; the data is protected by `requireAuth()` / `requireRole()` on the API routes, which is what the platform checks.
 - Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
 - To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
 

package/template/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (2834c4c81f7f); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (ca70e3512072); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -10,7 +10,7 @@ If this project still has the template's todo app (the `todos` table and `src/se
 
 1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
 2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
-3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. The template is a normal website: a public homepage at `/`, auth pages at `/login`, `/signup`, `/forgot-password`, `/reset-password`, and a signed-in area. Reshape it to the idea (a public landing page with sign-in in the header, a members-only area, an admin section) rather than forcing a login wall; the forms already work.
 4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
 5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
 6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
@@ -44,12 +44,13 @@ Once the repo is linked (`nerd github connect`, then `nerd github link owner/rep
 
 ## Auth and authorization
 
-The SDK handles sessions. There is no login code to write.
+The SDK handles sessions. There is no server-side login code to write; the client only decides where the forms appear.
 
 - `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
 - `requireAuth()` middleware returns 401 when signed out.
 - `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
-- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them, and `src/client/auth.tsx` turns them into drop-in components: `SignInForm`, `SignUpForm`, `ForgotPasswordForm`, `ResetPasswordForm`, plus `useUser()` for the current user anywhere in the tree and `RequireUser` to guard a screen (it sends signed-out visitors to `/login?next=...`). Put the forms wherever the design wants: their own pages, a modal, inline on the homepage. Password reset emails link to `/reset-password?token=...`; keep that route if you restructure the client.
+- Pages are public by default because they are static files. Guarding a screen with `RequireUser` is a courtesy to the visitor; the data is protected by `requireAuth()` / `requireRole()` on the API routes, which is what the platform checks.
 - Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
 - To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
 

package/template/CLAUDE.md

@@ -14,13 +14,13 @@ nerdsystem deploys this app to Cloudflare and provides authentication and author
 ## Layout
 
 - `src/server/index.ts` is the Worker entry. Build the API here with Hono; mount routers under `/api/...`.
-- `src/client/` is the React app, built by Vite and served as static assets for every path outside `/api`.
+- `src/client/` is the React app, built by Vite and served as static assets for every path outside `/api`. `App.tsx` routes by path (public homepage, `/login`, `/signup`, `/forgot-password`, `/reset-password`, a signed-in area); `auth.tsx` has the session hook and auth forms; `router.tsx` is a tiny pushState router you may replace.
 - `src/server/db/schema.ts` is the Drizzle schema for the app's D1 database (`c.env.DB`). Files go in `c.env.STORAGE` (R2).
 
 ## Rules the platform enforces
 
 1. Keep `createNerdApp()` from `@nerdsystem/sdk` as the app's root. Do not replace it with a bare Hono instance.
-2. Authentication is handled by the SDK. Do not write login, signup, password, or token code. Use `c.var.user`, `requireAuth()`, and `requireRole("admin")`.
+2. Authentication is handled by the SDK. Do not write server-side login, signup, password, or token code. Use `c.var.user`, `requireAuth()`, and `requireRole("admin")`. The sign-in, sign-up, and password forms in `src/client/auth.tsx` are plain components; place them wherever the design wants (pages, a modal, the homepage). Pages are public unless the data behind them is guarded on the server.
 3. Every table that stores user data carries a `user_id` column, and every query filters by `c.var.user.id`. Users must never see each other's rows.
 4. Database changes go through Drizzle migrations in `migrations/`. `nerd deploy` applies them.
 5. Keep every API route under `/api/`. Other paths are served from static assets and never reach the Worker.

package/template/GEMINI.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (2834c4c81f7f); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (ca70e3512072); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -10,7 +10,7 @@ If this project still has the template's todo app (the `todos` table and `src/se
 
 1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
 2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
-3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. The template is a normal website: a public homepage at `/`, auth pages at `/login`, `/signup`, `/forgot-password`, `/reset-password`, and a signed-in area. Reshape it to the idea (a public landing page with sign-in in the header, a members-only area, an admin section) rather than forcing a login wall; the forms already work.
 4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
 5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
 6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
@@ -44,12 +44,13 @@ Once the repo is linked (`nerd github connect`, then `nerd github link owner/rep
 
 ## Auth and authorization
 
-The SDK handles sessions. There is no login code to write.
+The SDK handles sessions. There is no server-side login code to write; the client only decides where the forms appear.
 
 - `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
 - `requireAuth()` middleware returns 401 when signed out.
 - `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
-- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them, and `src/client/auth.tsx` turns them into drop-in components: `SignInForm`, `SignUpForm`, `ForgotPasswordForm`, `ResetPasswordForm`, plus `useUser()` for the current user anywhere in the tree and `RequireUser` to guard a screen (it sends signed-out visitors to `/login?next=...`). Put the forms wherever the design wants: their own pages, a modal, inline on the homepage. Password reset emails link to `/reset-password?token=...`; keep that route if you restructure the client.
+- Pages are public by default because they are static files. Guarding a screen with `RequireUser` is a courtesy to the visitor; the data is protected by `requireAuth()` / `requireRole()` on the API routes, which is what the platform checks.
 - Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
 - To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
 

package/template/src/client/App.tsx

@@ -1,128 +1,79 @@
-import { useEffect, useRef, useState, type FormEvent } from "react";
-
-// Optional bot protection on signup: set VITE_TURNSTILE_SITE_KEY (client) and NERD_TURNSTILE_SECRET
-// (server, via `nerd secrets`) from a Cloudflare Turnstile widget. Without them, signup is open.
-const TURNSTILE_SITE_KEY = import.meta.env.VITE_TURNSTILE_SITE_KEY as string | undefined;
-
-function Turnstile({ onToken }: { onToken: (t: string) => void }) {
-  const ref = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    if (!TURNSTILE_SITE_KEY || !ref.current) return;
-    const w = window as unknown as { turnstile?: { render: (el: HTMLElement, opts: { sitekey: string; callback: (t: string) => void }) => void } };
-    const render = () => w.turnstile?.render(ref.current!, { sitekey: TURNSTILE_SITE_KEY, callback: onToken });
-    if (w.turnstile) render();
-    else {
-      const s = document.createElement("script");
-      s.src = "https://challenges.cloudflare.com/turnstile/v0/api.js";
-      s.async = true;
-      s.onload = render;
-      document.head.appendChild(s);
-    }
-  }, [onToken]);
-  return TURNSTILE_SITE_KEY ? <div ref={ref} /> : null;
-}
-import { api, auth, ApiError, type User } from "./api";
-
-interface Todo {
-  id: number;
-  title: string;
-  done: boolean;
-}
+// A normal website: a public homepage, auth pages, and a signed-in area. Pages are plain functions;
+// add one by adding a case in App(). Everyone can load every page (they are static files); what a
+// page can read is decided by the server routes it calls, which use requireAuth() and requireRole().
+import { useEffect, useState, type FormEvent, type ReactNode } from "react";
+import { api } from "./api";
+import { afterSignIn, ForgotPasswordForm, RequireUser, ResetPasswordForm, SignInForm, SignUpForm, useUser } from "./auth";
+import { Link, navigate, usePath } from "./router";
 
 export default function App() {
-  const [user, setUser] = useState<User | null | undefined>(undefined);
-
-  useEffect(() => {
-    auth.me().then((r) => setUser(r.user)).catch(() => setUser(null));
-  }, []);
-
-  if (user === undefined) return <main className="shell">Loading…</main>;
-  if (window.location.pathname === "/reset-password") return <ResetPassword onSignedIn={(u) => { window.history.replaceState(null, "", "/"); setUser(u); }} />;
-  if (!user) return <AuthScreen onSignedIn={setUser} />;
-  return <Todos user={user} onSignedOut={() => setUser(null)} />;
-}
-
-function AuthScreen({ onSignedIn }: { onSignedIn: (u: User) => void }) {
-  const [mode, setMode] = useState<"login" | "signup" | "forgot">("login");
-  const [error, setError] = useState<string | null>(null);
-  const [notice, setNotice] = useState<string | null>(null);
-  const [busy, setBusy] = useState(false);
-  const [turnstileToken, setTurnstileToken] = useState<string | undefined>(undefined);
-
-  async function submit(e: FormEvent<HTMLFormElement>) {
-    e.preventDefault();
-    const form = new FormData(e.currentTarget);
-    const email = String(form.get("email"));
-    const password = String(form.get("password"));
-    setBusy(true);
-    setError(null);
-    try {
-      if (mode === "forgot") {
-        await auth.forgot(email);
-        setNotice("If that email has an account, a reset link is on its way.");
-        return;
-      }
-      const r = mode === "login" ? await auth.login(email, password) : await auth.signup(email, password, String(form.get("name")), turnstileToken);
-      onSignedIn(r.user);
-    } catch (err) {
-      setError(err instanceof ApiError ? err.message : "Something went wrong");
-    } finally {
-      setBusy(false);
-    }
+  const path = usePath();
+  switch (path) {
+    case "/":
+      return <Home />;
+    case "/login":
+      return <Page title="Sign in"><SignInForm onSignedIn={() => navigate(afterSignIn("/todos"))} /><p className="muted"><Link href="/forgot-password">Forgot your password?</Link> · <Link href="/signup">Need an account?</Link></p></Page>;
+    case "/signup":
+      return <Page title="Create an account"><SignUpForm onSignedIn={() => navigate("/todos")} /><p className="muted"><Link href="/login">Have an account? Sign in</Link></p></Page>;
+    case "/forgot-password":
+      return <Page title="Reset your password"><ForgotPasswordForm /></Page>;
+    case "/reset-password": // password reset emails link here; keep this route
+      return <Page title="Choose a new password"><ResetPasswordForm onSignedIn={() => navigate("/todos", { replace: true })} /></Page>;
+    case "/todos":
+      return <Page title="Todos"><RequireUser><Todos /></RequireUser></Page>;
+    default:
+      return <Page title="Not found"><p className="muted">Nothing lives at {path}. <Link href="/">Go home</Link>.</p></Page>;
   }
+}
 
+/** Shared frame: the site name, navigation that knows whether you are signed in, and the page body. */
+function Page({ title, children }: { title: string; children: ReactNode }) {
+  const { user, signOut } = useUser();
   return (
     <main className="shell">
-      <h1>nerd-app</h1>
-      <form onSubmit={submit} className="card">
-        {mode === "signup" && <input name="name" placeholder="Your name" required />}
-        <input name="email" type="email" placeholder="Email" required />
-        {mode !== "forgot" && <input name="password" type="password" placeholder="Password (8+ characters)" minLength={8} required />}
-        {mode === "signup" && <Turnstile onToken={setTurnstileToken} />}
-        {error && <p className="error">{error}</p>}
-        {notice && <p className="muted">{notice}</p>}
-        <button disabled={busy}>{mode === "login" ? "Sign in" : mode === "signup" ? "Create account" : "Email me a reset link"}</button>
-        <button type="button" className="link" onClick={() => { setNotice(null); setMode(mode === "login" ? "signup" : "login"); }}>
-          {mode === "login" ? "Need an account? Sign up" : "Have an account? Sign in"}
-        </button>
-        {mode === "login" && (
-          <button type="button" className="link" onClick={() => { setNotice(null); setMode("forgot"); }}>Forgot your password?</button>
-        )}
-      </form>
+      <nav className="nav">
+        <Link href="/"><strong>nerd-app</strong></Link>
+        <span>
+          {user ? (
+            <>
+              <Link href="/todos">Todos</Link> · {user.name} · <button className="link" onClick={() => signOut().then(() => navigate("/"))}>Sign out</button>
+            </>
+          ) : user === null ? (
+            <>
+              <Link href="/login">Sign in</Link> · <Link href="/signup">Sign up</Link>
+            </>
+          ) : null}
+        </span>
+      </nav>
+      <h1>{title}</h1>
+      {children}
     </main>
   );
 }
 
-function ResetPassword({ onSignedIn }: { onSignedIn: (u: User) => void }) {
-  const token = new URLSearchParams(window.location.search).get("token") ?? "";
-  const [error, setError] = useState<string | null>(null);
-  const [busy, setBusy] = useState(false);
-  async function submit(e: FormEvent<HTMLFormElement>) {
-    e.preventDefault();
-    setBusy(true);
-    setError(null);
-    try {
-      const r = await auth.reset(token, String(new FormData(e.currentTarget).get("password")));
-      onSignedIn(r.user);
-    } catch (err) {
-      setError(err instanceof ApiError ? err.message : "Something went wrong");
-    } finally {
-      setBusy(false);
-    }
-  }
+/** Public. Replace this with the app's real landing page. */
+function Home() {
+  const { user } = useUser();
   return (
-    <main className="shell">
-      <h1>Choose a new password</h1>
-      <form onSubmit={submit} className="card">
-        <input name="password" type="password" placeholder="New password (8+ characters)" minLength={8} required autoFocus />
-        {error && <p className="error">{error}</p>}
-        <button disabled={busy || !token}>Set password and sign in</button>
-      </form>
-    </main>
+    <Page title="Welcome to nerd-app">
+      <p>This page is public. Anyone can read it without an account.</p>
+      {user ? (
+        <p><Link href="/todos">Open your todos</Link></p>
+      ) : (
+        <p><Link href="/signup">Create an account</Link> or <Link href="/login">sign in</Link> to keep a todo list.</p>
+      )}
+    </Page>
   );
 }
 
-function Todos({ user, onSignedOut }: { user: User; onSignedOut: () => void }) {
+interface Todo {
+  id: number;
+  title: string;
+  done: boolean;
+}
+
+/** Signed-in only: RequireUser above guards the screen, requireAuth() on /api/todos guards the data. */
+function Todos() {
   const [todos, setTodos] = useState<Todo[]>([]);
   const [title, setTitle] = useState("");
 
@@ -150,16 +101,7 @@ function Todos({ user, onSignedOut }: { user: User; onSignedOut: () => void }) {
   }
 
   return (
-    <main className="shell">
-      <header>
-        <h1>Todos</h1>
-        <span>
-          {user.name} · {user.roles.join(", ")}{" "}
-          <button className="link" onClick={() => auth.logout().then(onSignedOut)}>
-            Sign out
-          </button>
-        </span>
-      </header>
+    <>
       <form onSubmit={add} className="row">
         <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="What needs doing?" />
         <button>Add</button>
@@ -177,6 +119,6 @@ function Todos({ user, onSignedOut }: { user: User; onSignedOut: () => void }) {
         ))}
         {todos.length === 0 && <li className="muted">Nothing yet.</li>}
       </ul>
-    </main>
+    </>
   );
 }

package/template/src/client/auth.tsx

@@ -0,0 +1,163 @@
+// Sign-in, sign-up, and password forms as plain components. Put them wherever the design wants:
+// on their own pages (the default routes in App.tsx), inside a modal, or inline on the homepage.
+// They only call the platform's session endpoints through `auth` in ./api; access to data is
+// decided on the server with requireAuth() and requireRole(), never by which screen is showing.
+import { createContext, useContext, useEffect, useRef, useState, type FormEvent, type ReactNode } from "react";
+import { auth, ApiError, type User } from "./api";
+import { navigate } from "./router";
+
+// Optional bot protection on signup: set VITE_TURNSTILE_SITE_KEY (client) and NERD_TURNSTILE_SECRET
+// (server, via `nerd secrets`) from a Cloudflare Turnstile widget. Without them, signup is open.
+const TURNSTILE_SITE_KEY = import.meta.env.VITE_TURNSTILE_SITE_KEY as string | undefined;
+
+function Turnstile({ onToken }: { onToken: (t: string) => void }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!TURNSTILE_SITE_KEY || !ref.current) return;
+    const w = window as unknown as { turnstile?: { render: (el: HTMLElement, opts: { sitekey: string; callback: (t: string) => void }) => void } };
+    const render = () => w.turnstile?.render(ref.current!, { sitekey: TURNSTILE_SITE_KEY, callback: onToken });
+    if (w.turnstile) render();
+    else {
+      const s = document.createElement("script");
+      s.src = "https://challenges.cloudflare.com/turnstile/v0/api.js";
+      s.async = true;
+      s.onload = render;
+      document.head.appendChild(s);
+    }
+  }, [onToken]);
+  return TURNSTILE_SITE_KEY ? <div ref={ref} /> : null;
+}
+
+// ---- Session state, available anywhere with useUser() ----
+
+interface Session {
+  /** undefined while the first /api/auth/me call is in flight, null when signed out. */
+  user: User | null | undefined;
+  setUser: (u: User | null) => void;
+  signOut: () => Promise<void>;
+}
+
+const SessionContext = createContext<Session | null>(null);
+
+export function SessionProvider({ children }: { children: ReactNode }) {
+  const [user, setUser] = useState<User | null | undefined>(undefined);
+  useEffect(() => {
+    auth.me().then((r) => setUser(r.user)).catch(() => setUser(null));
+  }, []);
+  const signOut = () => auth.logout().then(() => setUser(null));
+  return <SessionContext.Provider value={{ user, setUser, signOut }}>{children}</SessionContext.Provider>;
+}
+
+export function useUser(): Session {
+  const s = useContext(SessionContext);
+  if (!s) throw new Error("useUser() needs <SessionProvider> above it (see main.tsx)");
+  return s;
+}
+
+/** Renders children only when signed in; otherwise sends the visitor to the sign-in page and back afterwards. */
+export function RequireUser({ children, to = "/login" }: { children: ReactNode; to?: string }) {
+  const { user } = useUser();
+  useEffect(() => {
+    if (user === null) navigate(`${to}?next=${encodeURIComponent(window.location.pathname + window.location.search)}`);
+  }, [user, to]);
+  if (!user) return <p className="muted">Loading…</p>;
+  return <>{children}</>;
+}
+
+/** Where to go after signing in: the `next` query parameter if present, otherwise the given fallback. */
+export function afterSignIn(fallback = "/"): string {
+  const next = new URLSearchParams(window.location.search).get("next");
+  return next && next.startsWith("/") && !next.startsWith("//") ? next : fallback;
+}
+
+// ---- Forms ----
+
+function useSubmit(run: (form: FormData) => Promise<void>) {
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  async function onSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    const form = new FormData(e.currentTarget);
+    setBusy(true);
+    setError(null);
+    try {
+      await run(form);
+    } catch (err) {
+      setError(err instanceof ApiError ? err.message : "Something went wrong");
+    } finally {
+      setBusy(false);
+    }
+  }
+  return { onSubmit, error, busy };
+}
+
+export function SignInForm({ onSignedIn }: { onSignedIn?: (u: User) => void }) {
+  const { setUser } = useUser();
+  const { onSubmit, error, busy } = useSubmit(async (form) => {
+    const r = await auth.login(String(form.get("email")), String(form.get("password")));
+    setUser(r.user);
+    onSignedIn?.(r.user);
+  });
+  return (
+    <form onSubmit={onSubmit} className="card">
+      <input name="email" type="email" placeholder="Email" autoComplete="email" required />
+      <input name="password" type="password" placeholder="Password" autoComplete="current-password" required />
+      {error && <p className="error">{error}</p>}
+      <button disabled={busy}>Sign in</button>
+    </form>
+  );
+}
+
+export function SignUpForm({ onSignedIn }: { onSignedIn?: (u: User) => void }) {
+  const { setUser } = useUser();
+  const [turnstileToken, setTurnstileToken] = useState<string | undefined>(undefined);
+  const { onSubmit, error, busy } = useSubmit(async (form) => {
+    const r = await auth.signup(String(form.get("email")), String(form.get("password")), String(form.get("name")), turnstileToken);
+    setUser(r.user);
+    onSignedIn?.(r.user);
+  });
+  return (
+    <form onSubmit={onSubmit} className="card">
+      <input name="name" placeholder="Your name" autoComplete="name" required />
+      <input name="email" type="email" placeholder="Email" autoComplete="email" required />
+      <input name="password" type="password" placeholder="Password (8+ characters)" autoComplete="new-password" minLength={8} required />
+      <Turnstile onToken={setTurnstileToken} />
+      {error && <p className="error">{error}</p>}
+      <button disabled={busy}>Create account</button>
+    </form>
+  );
+}
+
+export function ForgotPasswordForm() {
+  const [sent, setSent] = useState(false);
+  const { onSubmit, error, busy } = useSubmit(async (form) => {
+    await auth.forgot(String(form.get("email")));
+    setSent(true);
+  });
+  if (sent) return <p className="muted">If that email has an account, a reset link is on its way.</p>;
+  return (
+    <form onSubmit={onSubmit} className="card">
+      <input name="email" type="email" placeholder="Email" autoComplete="email" required />
+      {error && <p className="error">{error}</p>}
+      <button disabled={busy}>Email me a reset link</button>
+    </form>
+  );
+}
+
+/** Reads the token from `?token=`; password reset emails link to /reset-password?token=..., so keep that route. */
+export function ResetPasswordForm({ onSignedIn }: { onSignedIn?: (u: User) => void }) {
+  const { setUser } = useUser();
+  const token = new URLSearchParams(window.location.search).get("token") ?? "";
+  const { onSubmit, error, busy } = useSubmit(async (form) => {
+    const r = await auth.reset(token, String(form.get("password")));
+    setUser(r.user);
+    onSignedIn?.(r.user);
+  });
+  return (
+    <form onSubmit={onSubmit} className="card">
+      <input name="password" type="password" placeholder="New password (8+ characters)" autoComplete="new-password" minLength={8} required autoFocus />
+      {error && <p className="error">{error}</p>}
+      <button disabled={busy || !token}>Set password and sign in</button>
+    </form>
+  );
+}

package/template/src/client/main.tsx

@@ -1,10 +1,13 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import App from "./App";
+import { SessionProvider } from "./auth";
 import "./styles.css";
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <App />
+    <SessionProvider>
+      <App />
+    </SessionProvider>
   </StrictMode>,
 );

package/template/src/client/router.tsx

@@ -0,0 +1,42 @@
+// The smallest possible client-side router: a path, a way to change it, and links that use it.
+// Replace with react-router (or anything else) when the app outgrows it; nothing on the platform cares.
+import { useEffect, useState, type AnchorHTMLAttributes } from "react";
+
+const listeners = new Set<() => void>();
+
+export function navigate(to: string, { replace = false }: { replace?: boolean } = {}): void {
+  if (replace) window.history.replaceState(null, "", to);
+  else window.history.pushState(null, "", to);
+  listeners.forEach((l) => l());
+}
+
+/** The current pathname, re-rendering on navigate() and on back/forward. */
+export function usePath(): string {
+  const [path, setPath] = useState(window.location.pathname);
+  useEffect(() => {
+    const update = () => setPath(window.location.pathname);
+    listeners.add(update);
+    window.addEventListener("popstate", update);
+    return () => {
+      listeners.delete(update);
+      window.removeEventListener("popstate", update);
+    };
+  }, []);
+  return path;
+}
+
+/** An <a> that navigates without a full page load. External links and modified clicks fall through to the browser. */
+export function Link({ href, ...rest }: AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }) {
+  return (
+    <a
+      href={href}
+      {...rest}
+      onClick={(e) => {
+        rest.onClick?.(e);
+        if (e.defaultPrevented || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0 || !href.startsWith("/")) return;
+        e.preventDefault();
+        navigate(href);
+      }}
+    />
+  );
+}

package/template/src/client/styles.css

@@ -1,7 +1,9 @@
 :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
 body { margin: 0; }
 .shell { max-width: 32rem; margin: 4rem auto; padding: 0 1rem; }
-header { display: flex; justify-content: space-between; align-items: baseline; gap: 1rem; }
+header, .nav { display: flex; justify-content: space-between; align-items: baseline; gap: 1rem; }
+.nav { margin-bottom: 2rem; }
+.nav a { color: inherit; }
 h1 { margin: 0 0 1rem; }
 .card, .row { display: flex; flex-direction: column; gap: 0.5rem; }
 .row { flex-direction: row; }