create-top-secret-starter 0.0.1 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-top-secret-starter",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Scaffold a Vite + React 19 + TypeScript + shadcn starter with TanStack Router",
   "keywords": [
     "create",

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

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

package/templates/template-start/.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-start/.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-start/_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-start/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-start/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",
+    "@tanstack/react-start": "^1.168.0",
+    "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",
+    "@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-start/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-start/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-start/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-start/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-start/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-start/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-start/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()
+  })
+}

package/templates/template-start/src/api/auth/schema.ts

@@ -0,0 +1,20 @@
+import * as z from 'zod/mini'
+
+export const TokensSchema = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string()
+})
+export type Tokens = z.infer<typeof TokensSchema>
+
+// TODO: match your backend's user shape
+export const UserSchema = z.object({
+  id: z.string(),
+  email: z.email()
+})
+export type User = z.infer<typeof UserSchema>
+
+export const SessionSchema = z.object({
+  ...TokensSchema.shape,
+  user: UserSchema
+})
+export type Session = z.infer<typeof SessionSchema>

package/templates/template-start/src/api/auth/session-store.test.ts

@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { Session } from '@/api/auth/schema'
+
+// session-store reads localStorage once at module load, so every case needs a
+// fresh module instance seeded before the import.
+const load = async () => {
+  vi.resetModules()
+  return (await import('@/api/auth/session-store')).sessionStore
+}
+
+const session: Session = {
+  user: { id: 'u_1', email: 'a@b.com' },
+  accessToken: 'access',
+  refreshToken: 'refresh'
+}
+
+beforeEach(() => localStorage.clear())
+
+describe('reading persisted state', () => {
+  it('returns null for unparsable JSON instead of throwing at boot', async () => {
+    localStorage.setItem('session:v1', 'not json at all')
+    const store = await load()
+    expect(store.get()).toBeNull()
+  })
+
+  it('returns null when the shape no longer matches the schema', async () => {
+    // the shape a previous release wrote, or a renamed field
+    localStorage.setItem('session:v1', JSON.stringify({ token: 'access', user: { id: 'u_1' } }))
+    const store = await load()
+    expect(store.get()).toBeNull()
+  })
+})
+
+describe('cross-tab sync', () => {
+  it('adopts a session written by another tab', async () => {
+    const store = await load()
+    const listener = vi.fn()
+    store.subscribe(listener)
+
+    window.dispatchEvent(
+      new StorageEvent('storage', { key: 'session:v1', newValue: JSON.stringify(session) })
+    )
+
+    expect(store.get()?.user.id).toBe('u_1')
+    expect(listener).toHaveBeenCalledWith(expect.objectContaining({ accessToken: 'access' }))
+  })
+
+  it('drops the session when another tab signs out', async () => {
+    localStorage.setItem('session:v1', JSON.stringify(session))
+    const store = await load()
+
+    window.dispatchEvent(new StorageEvent('storage', { key: 'session:v1', newValue: null }))
+
+    expect(store.get()).toBeNull()
+  })
+
+  it('treats a corrupt cross-tab write as a sign-out, not a crash', async () => {
+    localStorage.setItem('session:v1', JSON.stringify(session))
+    const store = await load()
+
+    window.dispatchEvent(new StorageEvent('storage', { key: 'session:v1', newValue: '{{{' }))
+
+    expect(store.get()).toBeNull()
+  })
+
+  it('ignores writes to unrelated keys', async () => {
+    localStorage.setItem('session:v1', JSON.stringify(session))
+    const store = await load()
+
+    window.dispatchEvent(new StorageEvent('storage', { key: 'theme', newValue: 'dark' }))
+
+    expect(store.get()?.user.id).toBe('u_1')
+  })
+})
+
+describe('writing', () => {
+  it('refuses to update tokens with no active session', async () => {
+    const store = await load()
+    expect(() => store.updateTokens({ accessToken: 'a', refreshToken: 'r' })).toThrow(
+      /no active session/i
+    )
+  })
+
+  it('keeps the user when rotating tokens', async () => {
+    const store = await load()
+    store.set(session)
+    store.updateTokens({ accessToken: 'a2', refreshToken: 'r2' })
+
+    expect(store.get()).toEqual({ ...session, accessToken: 'a2', refreshToken: 'r2' })
+    expect(JSON.parse(localStorage.getItem('session:v1')!).accessToken).toBe('a2')
+  })
+
+  it('removes the key on clear so a reload starts signed out', async () => {
+    const store = await load()
+    store.set(session)
+    store.clear()
+
+    expect(localStorage.getItem('session:v1')).toBeNull()
+  })
+})

package/templates/template-start/src/api/auth/session-store.ts

@@ -0,0 +1,56 @@
+import { useSyncExternalStore } from 'react'
+
+import { SessionSchema, type Session, type Tokens } from '@/api/auth/schema'
+
+// Versioned: bumping the suffix discards every persisted session at once, which is
+// what you want after changing the shape or revoking tokens. Reading is already
+// shape-safe via zod, so this is about deliberate invalidation, not crash safety.
+const KEY = 'session:v1'
+
+type Listener = (session: Session | null) => void
+
+const parseRaw = (raw: string | null): Session | null => {
+  try {
+    return raw ? SessionSchema.parse(JSON.parse(raw)) : null
+  } catch {
+    return null
+  }
+}
+
+let current = parseRaw(localStorage.getItem(KEY))
+const listeners = new Set<Listener>()
+
+const notify = () => listeners.forEach(l => l(current))
+
+const commit = (next: Session | null) => {
+  current = next
+  if (next) localStorage.setItem(KEY, JSON.stringify(next))
+  else localStorage.removeItem(KEY)
+  notify()
+}
+
+window.addEventListener('storage', e => {
+  if (e.key !== KEY) return
+  current = parseRaw(e.newValue)
+  notify()
+})
+
+export const sessionStore = {
+  get: () => current,
+  set: (next: Session) => commit(next),
+  clear: () => commit(null),
+  updateTokens: (tokens: Tokens) => {
+    if (!current) throw new Error('Cannot update tokens: no active session')
+    commit({ ...current, ...tokens })
+  },
+  subscribe: (listener: Listener) => {
+    listeners.add(listener)
+    return () => {
+      listeners.delete(listener)
+    }
+  }
+}
+
+// The React binding of the store's subscribe contract lives with the store: one
+// concept, one file. Components use this; route guards use @/api/auth/guards.
+export const useSession = () => useSyncExternalStore(sessionStore.subscribe, sessionStore.get)