create-top-secret-starter 0.0.1

package/index.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts'
+
+// lesson 001: the package manager that launched us sets npm_config_user_agent
+const agent = process.env.npm_config_user_agent ?? ''
+const detectedPm = agent.split('/')[0] || 'npm'
+
+const PMS = ['bun', 'pnpm', 'npm']
+const ROUTERS = ['router', 'start']
+const NAME_RE = /^[a-z0-9][a-z0-9._-]*$/
+
+// lesson 002 §6: flags bypass prompts so the CLI works in CI
+const { values: flags, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  allowPositionals: true,
+  options: {
+    pm: { type: 'string' },
+    router: { type: 'string' }
+  }
+})
+
+function must(value) {
+  if (isCancel(value)) {
+    cancel('Cancelled.')
+    process.exit(0)
+  }
+  return value
+}
+
+function validateName(v) {
+  if (!v) return 'Project name is required'
+  if (!NAME_RE.test(v)) return 'Lowercase letters, digits, . _ - only (npm package name rules)'
+}
+
+intro('create-top-secret-starter')
+
+let name = positionals[0]
+if (name && validateName(name)) {
+  cancel(`Invalid project name "${name}": ${validateName(name)}`)
+  process.exit(1)
+}
+name ??= must(
+  await text({
+    message: 'Project name?',
+    placeholder: 'my-ai-app',
+    validate: validateName
+  })
+)
+
+let pm = flags.pm
+if (pm && !PMS.includes(pm)) {
+  cancel(`Unknown package manager "${pm}". Expected: ${PMS.join(', ')}`)
+  process.exit(1)
+}
+pm ??= must(
+  await select({
+    message: 'Package manager?',
+    initialValue: PMS.includes(detectedPm) ? detectedPm : 'npm',
+    options: PMS.map(value => ({ value, label: value }))
+  })
+)
+
+let router = flags.router
+if (router && !ROUTERS.includes(router)) {
+  cancel(`Unknown router "${router}". Expected: ${ROUTERS.join(', ')}`)
+  process.exit(1)
+}
+router ??= must(
+  await select({
+    message: 'Routing?',
+    options: [
+      { value: 'router', label: 'TanStack Router', hint: 'SPA' },
+      { value: 'start', label: 'TanStack Start', hint: 'SSR, full-stack' }
+    ]
+  })
+)
+
+const targetDir = path.resolve(process.cwd(), name)
+if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+  cancel(`Directory "${name}" already exists and is not empty.`)
+  process.exit(1)
+}
+
+// lesson 003 §4: variant A — one full template per router choice
+const templateDir = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'templates',
+  `template-${router}`
+)
+if (!fs.existsSync(templateDir)) {
+  cancel(`The ${router === 'start' ? 'TanStack Start' : router} template is not available yet.`)
+  process.exit(1)
+}
+fs.cpSync(templateDir, targetDir, { recursive: true })
+
+// lesson 003 §2: npm strips .gitignore from packages, so it ships as _gitignore
+const renameFiles = { _gitignore: '.gitignore' }
+for (const [from, to] of Object.entries(renameFiles)) {
+  const src = path.join(targetDir, from)
+  if (fs.existsSync(src)) fs.renameSync(src, path.join(targetDir, to))
+}
+
+const pkgPath = path.join(targetDir, 'package.json')
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+pkg.name = name
+fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+
+outro(`✔ ${name} created (${router === 'start' ? 'TanStack Start' : 'TanStack Router'})
+
+Next steps:
+  cd ${name}
+  ${pm} install
+  ${pm} run dev`)

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-top-secret-starter",
+  "version": "0.0.1",
+  "description": "Scaffold a Vite + React 19 + TypeScript + shadcn starter with TanStack Router",
+  "keywords": [
+    "create",
+    "react",
+    "shadcn",
+    "starter",
+    "tanstack",
+    "template",
+    "vite"
+  ],
+  "license": "MIT",
+  "bin": {
+    "create-top-secret-starter": "index.js"
+  },
+  "files": [
+    "index.js",
+    "templates"
+  ],
+  "type": "module",
+  "scripts": {
+    "sync": "node sync-template.mjs",
+    "sync:verify": "node sync-template.mjs --verify"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/template-router/.env.example

@@ -0,0 +1 @@
+VITE_API_URL=/api/

package/templates/template-router/.oxfmtrc.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "singleQuote": true,
+  "jsxSingleQuote": true,
+  "semi": false,
+  "trailingComma": "none",
+  "arrowParens": "avoid",
+  "sortTailwindcss": { "functions": ["clsx", "cva", "cn", "twMerge"] },
+  "ignorePatterns": ["**/dist", "src/routeTree.gen.ts"]
+}

package/templates/template-router/.oxlintrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "oxc"],
+  "ignorePatterns": ["**/dist", "src/routeTree.gen.ts"],
+  "rules": {
+    "react/rules-of-hooks": "error"
+  }
+}

package/templates/template-router/_gitignore

@@ -0,0 +1,39 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Env
+.env
+.env.*
+!.env.example
+
+# Skill artifacts
+.agents/
+
+# Playwright
+/test-results
+/playwright-report
+/blob-report
+/playwright/.cache
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/templates/template-router/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/templates/template-router/index.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>top-secret</title>
+    <script>
+      ;(function () {
+        try {
+          var t = localStorage.getItem('ui-theme') || 'system'
+          var dark =
+            t === 'dark' ||
+            (t === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches)
+          document.documentElement.classList.toggle('dark', dark)
+        } catch (e) {}
+      })()
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/template-router/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "PLACEHOLDER",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.7.0",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@hookform/resolvers": "^5.9.1",
+    "@tanstack/react-query": "^5.102.8",
+    "@tanstack/react-router": "^1.170.32",
+    "class-variance-authority": "^0.7.1",
+    "cnfast": "^0.1.0",
+    "ky": "^2.1.0",
+    "lucide-react": "^1.35.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-hook-form": "^7.86.0",
+    "sonner": "^2.0.8",
+    "tw-animate-css": "^1.4.0",
+    "zod": "^4.5.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^8.0.1",
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/router-plugin": "^1.168.35",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.6",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^26.4.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "@vitejs/plugin-react": "^6.1.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "happy-dom": "^20.11.13",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "shadcn": "^4.19.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "vite": "8.1.4",
+    "vitest": "^4.1.11"
+  },
+  "trustedDependencies": []
+}

package/templates/template-router/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="46" fill="none" viewBox="0 0 48 46"><path fill="#863bff" d="M25.946 44.938c-.664.845-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.287c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.497 0-3.578-1.842-3.578H1.237c-.92 0-1.456-1.04-.92-1.788L10.013.474c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.579 1.842 3.579h11.377c.943 0 1.473 1.088.89 1.83L25.947 44.94z" style="fill:#863bff;fill:color(display-p3 .5252 .23 1);fill-opacity:1"/><mask id="a" width="48" height="46" x="0" y="0" maskUnits="userSpaceOnUse" style="mask-type:alpha"><path fill="#000" d="M25.842 44.938c-.664.844-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.183c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.498 0-3.579-1.842-3.579H1.133c-.92 0-1.456-1.04-.92-1.787L9.91.473c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.578 1.842 3.578h11.377c.943 0 1.473 1.088.89 1.832L25.843 44.94z" style="fill:#000;fill-opacity:1"/></mask><g mask="url(#a)"><g filter="url(#b)"><ellipse cx="5.508" cy="14.704" fill="#ede6ff" rx="5.508" ry="14.704" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -4.47 31.516)"/></g><g filter="url(#c)"><ellipse cx="10.399" cy="29.851" fill="#ede6ff" rx="10.399" ry="29.851" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -39.328 7.883)"/></g><g filter="url(#d)"><ellipse cx="5.508" cy="30.487" fill="#7e14ff" rx="5.508" ry="30.487" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -25.913 -14.639)scale(1 -1)"/></g><g filter="url(#e)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -32.644 -3.334)scale(1 -1)"/></g><g filter="url(#f)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -34.34 30.47)"/></g><g filter="url(#g)"><ellipse cx="14.072" cy="22.078" fill="#ede6ff" rx="14.072" ry="22.078" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="rotate(93.35 24.506 48.493)scale(-1 1)"/></g><g filter="url(#h)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#i)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#j)"><ellipse cx=".387" cy="8.972" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(39.51 .387 8.972)"/></g><g filter="url(#k)"><ellipse cx="47.523" cy="-6.092" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 47.523 -6.092)"/></g><g filter="url(#l)"><ellipse cx="41.412" cy="6.333" fill="#47bfff" rx="5.971" ry="9.665" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 41.412 6.333)"/></g><g filter="url(#m)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#n)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#o)"><ellipse cx="35.651" cy="29.907" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 35.651 29.907)"/></g><g filter="url(#p)"><ellipse cx="38.418" cy="32.4" fill="#47bfff" rx="5.971" ry="15.297" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 38.418 32.4)"/></g></g><defs><filter id="b" width="60.045" height="41.654" x="-19.77" y="16.149" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="c" width="90.34" height="51.437" x="-54.613" y="-7.533" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="d" width="79.355" height="29.4" x="-49.64" y="2.03" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="e" width="79.579" height="29.4" x="-45.045" y="20.029" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="f" width="79.579" height="29.4" x="-43.513" y="21.178" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="g" width="74.749" height="58.852" x="15.756" y="-17.901" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="h" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="i" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="j" width="56.045" height="63.649" x="-27.636" y="-22.853" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="k" width="54.814" height="64.646" x="20.116" y="-38.415" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="l" width="33.541" height="35.313" x="24.641" y="-11.323" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="m" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="n" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="o" width="54.814" height="64.646" x="8.244" y="-2.416" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="p" width="39.409" height="43.623" x="18.713" y="10.588" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter></defs></svg>

package/templates/template-router/src/api/auth/auth.test.ts

@@ -0,0 +1,46 @@
+import { afterAll, afterEach, beforeAll } from 'vitest'
+
+import { fetchMe, login, logout } from '@/api/auth'
+import { sessionStore } from '@/api/auth/session-store'
+import { installMockServer } from '@/mocks/mock-server'
+
+const creds = { email: 'demo@example.com', password: 'demo1234' }
+
+let uninstall: () => void
+
+beforeAll(() => {
+  uninstall = installMockServer()
+})
+afterAll(() => uninstall())
+afterEach(() => {
+  sessionStore.clear()
+  localStorage.clear()
+})
+
+it('logs in and persists the session', async () => {
+  const session = await login(creds)
+  expect(session.user.email).toBe(creds.email)
+  expect(sessionStore.get()?.user.email).toBe(creds.email)
+})
+
+it('rejects bad credentials without touching the session', async () => {
+  await expect(login({ ...creds, password: 'wrong' })).rejects.toThrow()
+  expect(sessionStore.get()).toBeNull()
+})
+
+it('transparently refreshes when the access token is rejected', async () => {
+  await login(creds)
+  const session = sessionStore.get()!
+  sessionStore.set({ ...session, accessToken: 'expired' })
+
+  const me = await fetchMe()
+
+  expect(me.email).toBe(creds.email)
+  expect(sessionStore.get()?.accessToken).not.toBe('expired')
+})
+
+it('clears the session on logout', async () => {
+  await login(creds)
+  await logout()
+  expect(sessionStore.get()).toBeNull()
+})

package/templates/template-router/src/api/auth/guards.ts

@@ -0,0 +1,18 @@
+import { redirect } from '@tanstack/react-router'
+
+import { sessionStore } from '@/api/auth/session-store'
+
+// The one place that reads the session synchronously: `beforeLoad` runs outside
+// React, so it can't use useSession(). Components use useSession(); React Query
+// never mirrors the session. Guards get these helpers so the redirect contract
+// (`search.redirect` carries where to return after sign-in) lives in one module.
+
+export const requireSession = (location: { href: string }) => {
+  if (!sessionStore.get()) {
+    throw redirect({ to: '/sign-in', search: { redirect: location.href } })
+  }
+}
+
+export const redirectIfAuthenticated = (search: { redirect?: string }) => {
+  if (sessionStore.get()) throw redirect({ to: search.redirect ?? '/' })
+}

package/templates/template-router/src/api/auth/index.ts

@@ -0,0 +1,46 @@
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+import { api } from '@/api'
+import { SessionSchema, UserSchema } from '@/api/auth/schema'
+import { sessionStore } from '@/api/auth/session-store'
+
+export type Credentials = { email: string; password: string }
+
+export const login = (credentials: Credentials) =>
+  api
+    .post('auth/login', { json: credentials })
+    .json()
+    .then(data => SessionSchema.parse(data))
+    .then(session => {
+      sessionStore.set(session)
+      return session
+    })
+
+export const logout = async () => {
+  try {
+    await api.post('auth/logout')
+  } catch {}
+  sessionStore.clear()
+}
+
+export const fetchMe = () =>
+  api
+    .get('auth/me')
+    .json()
+    .then(data => UserSchema.parse(data))
+
+export const useLogin = () => {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: login,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['me'] })
+  })
+}
+
+export const useLogout = () => {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: logout,
+    onSuccess: () => queryClient.clear()
+  })
+}

package/templates/template-router/src/api/auth/refresh.test.ts

@@ -0,0 +1,89 @@
+import { afterAll, afterEach, beforeAll, expect, it, vi } from 'vitest'
+
+import { fetchMe, login } from '@/api/auth'
+import { sessionStore } from '@/api/auth/session-store'
+import { installMockServer } from '@/mocks/mock-server'
+
+const creds = { email: 'demo@example.com', password: 'demo1234' }
+
+let uninstall: () => void
+
+beforeAll(() => {
+  uninstall = installMockServer()
+})
+afterAll(() => uninstall())
+afterEach(() => {
+  sessionStore.clear()
+  localStorage.clear()
+})
+
+it('clears the session and stops when the refresh token is rejected', async () => {
+  await login(creds)
+  const session = sessionStore.get()!
+  // both tokens dead: the access token forces a 401, the refresh token can't fix it
+  sessionStore.set({
+    ...session,
+    accessToken: 'expired',
+    refreshToken: 'mock.refresh.u_demo.stale'
+  })
+
+  const spy = vi.spyOn(globalThis, 'fetch')
+  await expect(fetchMe()).rejects.toThrow()
+
+  expect(sessionStore.get()).toBeNull()
+  // auth/me (401) + auth/refresh (401). A third call means the retry guard broke.
+  expect(spy).toHaveBeenCalledTimes(2)
+})
+
+it('collapses concurrent 401s into a single refresh call', async () => {
+  await login(creds)
+  const session = sessionStore.get()!
+  sessionStore.set({ ...session, accessToken: 'expired' })
+
+  const spy = vi.spyOn(globalThis, 'fetch')
+  await Promise.all([fetchMe(), fetchMe(), fetchMe()])
+
+  const refreshCalls = spy.mock.calls.filter(([input]) =>
+    String(input instanceof Request ? input.url : input).includes('auth/refresh')
+  )
+  expect(refreshCalls).toHaveLength(1)
+})
+
+// The retryCount guard only matters when the RETRIED request is also rejected —
+// mock-server never does that, so this case needs a purpose-built backend.
+it('stops after one refresh when the fresh token is also rejected', async () => {
+  sessionStore.set({
+    user: { id: 'u_demo', email: creds.email },
+    accessToken: 'stale',
+    refreshToken: 'stale'
+  })
+
+  let refreshCalls = 0
+  const stub = vi.fn(async (input: RequestInfo | URL) => {
+    const url = String(input instanceof Request ? input.url : input)
+    if (url.includes('auth/refresh')) {
+      refreshCalls += 1
+      return new Response(JSON.stringify({ accessToken: 'new', refreshToken: 'new' }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' }
+      })
+    }
+    return new Response(JSON.stringify({ message: 'Unauthorized' }), { status: 401 })
+  })
+  const original = globalThis.fetch
+  globalThis.fetch = stub as unknown as typeof fetch
+
+  try {
+    await expect(fetchMe()).rejects.toThrow()
+    // without the `retryCount > 0` guard the retried 401 triggers another refresh
+    expect(refreshCalls).toBe(1)
+  } finally {
+    globalThis.fetch = original
+  }
+})
+
+it('refuses to refresh with no session at all', async () => {
+  sessionStore.clear()
+  await expect(fetchMe()).rejects.toThrow()
+  expect(sessionStore.get()).toBeNull()
+})

package/templates/template-router/src/api/auth/router-bridge.test.ts

@@ -0,0 +1,74 @@
+import { expect, it, vi } from 'vitest'
+
+import { bindSessionToRouter } from '@/api/auth/router-bridge'
+import type { Session } from '@/api/auth/schema'
+
+const session = (accessToken: string): Session => ({
+  accessToken,
+  refreshToken: 'r1',
+  user: { id: 'u_demo', email: 'demo@example.com' }
+})
+
+// A hand-rolled store instead of the real sessionStore: the bridge's interface
+// is (get, subscribe), and testing through it avoids localStorage + module reset.
+const fakeStore = (initial: Session | null) => {
+  let current = initial
+  const listeners = new Set<(s: Session | null) => void>()
+  return {
+    get: () => current,
+    subscribe: (l: (s: Session | null) => void) => {
+      listeners.add(l)
+      return () => {
+        listeners.delete(l)
+      }
+    },
+    emit: (next: Session | null) => {
+      current = next
+      listeners.forEach(l => l(next))
+    }
+  }
+}
+
+const router = () => ({ invalidate: vi.fn(() => Promise.resolve()) })
+
+it('invalidates when a session appears', () => {
+  const store = fakeStore(null)
+  const r = router()
+  bindSessionToRouter(r, store)
+
+  store.emit(session('a1'))
+
+  expect(r.invalidate).toHaveBeenCalledTimes(1)
+})
+
+it('invalidates when the session disappears', () => {
+  const store = fakeStore(session('a1'))
+  const r = router()
+  bindSessionToRouter(r, store)
+
+  store.emit(null)
+
+  expect(r.invalidate).toHaveBeenCalledTimes(1)
+})
+
+it('does not invalidate on token rotation — loaders must not restart every refresh', () => {
+  const store = fakeStore(session('a1'))
+  const r = router()
+  bindSessionToRouter(r, store)
+
+  store.emit(session('a2'))
+  store.emit(session('a3'))
+
+  expect(r.invalidate).not.toHaveBeenCalled()
+})
+
+it('stops reacting after unsubscribe', () => {
+  const store = fakeStore(null)
+  const r = router()
+  const unsubscribe = bindSessionToRouter(r, store)
+
+  unsubscribe()
+  store.emit(session('a1'))
+
+  expect(r.invalidate).not.toHaveBeenCalled()
+})

package/templates/template-router/src/api/auth/router-bridge.ts

@@ -0,0 +1,26 @@
+import type { Session } from '@/api/auth/schema'
+import { sessionStore } from '@/api/auth/session-store'
+
+type SessionSource = {
+  get: () => Session | null
+  subscribe: (listener: (session: Session | null) => void) => () => void
+}
+
+type Invalidatable = { invalidate: () => Promise<void> }
+
+// Route guards live in `beforeLoad`, which only runs on navigation. When the
+// session appears or disappears without one — signing in or out in another tab,
+// or a refresh failure clearing the store — that tab would keep rendering the
+// wrong side of the guard. Invalidating re-runs the guards in place.
+//
+// Only presence transitions matter. Token rotation also notifies subscribers,
+// and invalidating on every refresh would restart every loader ~every 15 min.
+export const bindSessionToRouter = (router: Invalidatable, store: SessionSource = sessionStore) => {
+  let hadSession = store.get() !== null
+  return store.subscribe(session => {
+    const hasSession = session !== null
+    if (hasSession === hadSession) return
+    hadSession = hasSession
+    void router.invalidate()
+  })
+}