@brust/create-app 0.0.0-stage → 2.0.0-alpha.1

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @brust/create-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffold a [brust](https://github.com/AssetsArt/brust) v2 app.
+
+```bash
+bun create @brust/app my-app      # --template blank (default) | pokedex
+cd my-app && bun install
+bun run dev                       # http://127.0.0.1:1337
+```
+
+| Option | Meaning |
+|---|---|
+| `--template blank\|pokedex` | The starting point (default `blank`; a terminal asks when omitted). |
+| `--dir <path>` | Target directory (default `./<name>`; it must be empty). |
+| `--yes` | Accept defaults, never prompt. |
+| `--brust-dep <spec>` | The `@brust/core` spec to write (CI and tarball tests). |
+
+`bun create` rejects `-t` and `-y`; use the long flags (the short ones work with `bunx @brust/create-app`).
+
+Full guide: [docs/create-app.md](https://github.com/AssetsArt/brust/blob/v2/docs/create-app.md).

package/bin/create-app.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+// `bun create @brust/app <name> …` runs this bin (bunx @brust/create-app) with the remaining argv.
+import { main } from '../src/cli.ts'
+await main(process.argv.slice(2))

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@brust/create-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-alpha.1",
+  "description": "Scaffold a brust v2 app — bun create @brust/app <name>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AssetsArt/brust.git",
+    "directory": "packages/create-app"
+  },
+  "type": "module",
+  "bin": {
+    "create-app": "./bin/create-app.ts"
+  },
+  "files": ["bin", "src", "templates", "README.md"],
+  "scripts": {
+    "build": "bun scripts/sync-template.ts",
+    "prepack": "bun scripts/sync-template.ts",
+    "test": "bun test",
+    "typecheck": "bun check"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/args.ts

@@ -0,0 +1,56 @@
+// Argument parsing — a port of 0.1.x `brust new` (runtime/cli/new.ts:12-69).
+// Note: `bun create` itself rejects the short flags -t and -y before this bin runs; they work under `bunx @brust/create-app`.
+import { isAbsolute, resolve } from 'node:path'
+
+const NAME_RE = /^[a-z0-9][a-z0-9_-]*$/
+const MAX_NAME_LEN = 50
+
+export const USAGE = 'usage: bun create @brust/app <name> [--template blank|pokedex] [--dir <path>] [--yes] [--brust-dep <spec>]'
+
+export interface ParsedArgs {
+  projectName: string
+  targetDir: string
+  template?: string
+  yes: boolean
+  brustDep?: string
+  help: boolean
+}
+
+export function parseArgs(args: string[]): ParsedArgs {
+  let name: string | undefined
+  let dir: string | undefined
+  let template: string | undefined
+  let brustDep: string | undefined
+  let yes = false
+  let help = false
+  const need = (flag: string, v: string | undefined): string => {
+    if (!v) throw new Error(`create-app: ${flag} requires a value`)
+    return v
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (a === '--') continue
+    if (a === '--help' || a === '-h') help = true
+    else if (a === '--dir') dir = need('--dir', args[++i])
+    else if (a.startsWith('--dir=')) dir = need('--dir', a.slice('--dir='.length))
+    else if (a === '--template' || a === '-t') template = need('--template', args[++i])
+    else if (a.startsWith('--template=')) template = need('--template', a.slice('--template='.length))
+    else if (a === '--brust-dep') brustDep = need('--brust-dep', args[++i])
+    else if (a.startsWith('--brust-dep=')) brustDep = need('--brust-dep', a.slice('--brust-dep='.length))
+    else if (a === '--yes' || a === '-y') yes = true
+    else if (a.startsWith('-')) throw new Error(`create-app: unknown flag "${a}"`)
+    else if (name === undefined) name = a
+    else throw new Error(`create-app: unexpected positional argument "${a}"`)
+  }
+
+  if (help) return { projectName: name ?? '', targetDir: '', template, yes, brustDep, help }
+  if (!name) throw new Error(`create-app: missing project name. ${USAGE}`)
+  if (name.length > MAX_NAME_LEN) throw new Error(`create-app: project name too long (max ${MAX_NAME_LEN} chars)`)
+  if (!NAME_RE.test(name)) {
+    throw new Error(`create-app: invalid project name "${name}" — use lowercase letters, digits, hyphens, underscores; must start with a letter or digit`)
+  }
+  const cwd = process.cwd()
+  const targetDir = dir ? (isAbsolute(dir) ? dir : resolve(cwd, dir)) : resolve(cwd, name)
+  return { projectName: name, targetDir, template, yes, brustDep, help }
+}

package/src/cli.ts

@@ -0,0 +1,58 @@
+// `create-app` main — a port of 0.1.x runNew (runtime/cli/new.ts:221-294) with the v2 dependency resolution.
+import { existsSync } from 'node:fs'
+import { readdir, rm } from 'node:fs/promises'
+import { copyTemplate } from './copy.ts'
+import { parseArgs, USAGE } from './args.ts'
+import { applyOverrides, monorepoRoot, resolveBrustDep } from './dep.ts'
+import { selectTemplate } from './templates.ts'
+
+const fail = (msg: string): never => {
+  console.error(msg)
+  process.exit(1)
+}
+const msg = (e: unknown): string => (e instanceof Error ? e.message : String(e))
+
+export async function main(argv: string[]): Promise<void> {
+  let parsed: ReturnType<typeof parseArgs>
+  try { parsed = parseArgs(argv) } catch (e) { return fail(msg(e)) }
+  if (parsed.help) {
+    console.log(USAGE)
+    return
+  }
+  const { projectName, targetDir } = parsed
+
+  const targetExisted = existsSync(targetDir)
+  if (targetExisted && (await readdir(targetDir)).length > 0) return fail(`create-app: target directory "${targetDir}" is not empty`)
+
+  let tmpl: ReturnType<typeof selectTemplate>
+  try { tmpl = selectTemplate({ explicit: parsed.template, yes: parsed.yes, isTTY: Boolean(process.stdin.isTTY) }) } catch (e) { return fail(msg(e)) }
+  const dep = resolveBrustDep({ explicit: parsed.brustDep, targetDir })
+
+  try {
+    // R5: from a brust checkout the generated template is rebuilt first, so a developer never copies a stale one.
+    if (tmpl.generated && monorepoRoot() && !process.env.CREATE_APP_TEMPLATES_DIR) {
+      const { syncTemplate } = await import('../scripts/sync-template.ts')
+      syncTemplate()
+    }
+    await copyTemplate({
+      templateDir: tmpl.dir,
+      targetDir,
+      substitutions: { __PROJECT_NAME__: projectName, __BRUST_DEP__: JSON.stringify(dep.spec) },
+    })
+    if (dep.overrides) applyOverrides(targetDir, dep.overrides)
+  } catch (e) {
+    if (!targetExisted) await rm(targetDir, { recursive: true, force: true }).catch(() => {})
+    return fail(`create-app: failed to scaffold (${msg(e)})`)
+  }
+  printNextSteps(projectName, targetDir, tmpl.name, dep.kind === 'workspace')
+}
+
+function printNextSteps(name: string, targetDir: string, template: string, workspace: boolean): void {
+  const cwd = process.cwd()
+  const displayPath = targetDir.startsWith(`${cwd}/`) ? `./${targetDir.slice(cwd.length + 1)}` : targetDir
+  console.log(`Created ${name} at ${targetDir} (template: ${template})\n`)
+  console.log('Next:')
+  console.log(`  cd ${displayPath}`)
+  console.log(workspace ? '  bun install   # run it at the brust repo root: this app is a workspace member' : '  bun install')
+  console.log('  bun run dev')
+}

package/src/copy.ts

@@ -0,0 +1,44 @@
+// copyTemplate — a port of 0.1.x runtime/cli/new.ts:100-163. `*.tmpl` files are substituted and lose the suffix, `_gitignore`
+// becomes `.gitignore` (npm silently drops a nested .gitignore from a tarball), everything else is copied byte-for-byte.
+// Symlinks are skipped, as in 0.1.x.
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export interface CopyTemplateOpts {
+  templateDir: string
+  targetDir: string
+  substitutions: Record<string, string>
+}
+
+export async function copyTemplate(opts: CopyTemplateOpts): Promise<void> {
+  if (!existsSync(opts.templateDir)) {
+    throw new Error(`create-app: template directory not found at ${opts.templateDir}; this is a @brust/create-app installation bug`)
+  }
+  await copyDir(opts.templateDir, opts.targetDir, opts.substitutions)
+}
+
+async function copyDir(src: string, dst: string, subs: Record<string, string>): Promise<void> {
+  await mkdir(dst, { recursive: true })
+  for (const ent of await readdir(src, { withFileTypes: true })) {
+    const srcPath = join(src, ent.name)
+    const dstPath = join(dst, renameForEmit(ent.name))
+    if (ent.isDirectory()) await copyDir(srcPath, dstPath, subs)
+    else if (ent.isFile()) {
+      if (ent.name.endsWith('.tmpl')) await writeFile(dstPath, applySubstitutions(await readFile(srcPath, 'utf8'), subs))
+      else await writeFile(dstPath, await readFile(srcPath))
+    }
+  }
+}
+
+function renameForEmit(name: string): string {
+  if (name.endsWith('.tmpl')) return name.slice(0, -'.tmpl'.length)
+  if (name === '_gitignore') return '.gitignore'
+  return name
+}
+
+function applySubstitutions(text: string, subs: Record<string, string>): string {
+  let out = text
+  for (const [key, value] of Object.entries(subs)) out = out.split(key).join(value)
+  return out
+}

package/src/dep.ts

@@ -0,0 +1,60 @@
+// Resolves the `@brust/core` spec written into a scaffolded package.json (`__BRUST_DEP__`, M3-F rulings R2/R3).
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+
+/** = scripts/release-bump.ts PLATS. */
+export const PLATS = ['darwin-x64', 'darwin-arm64', 'linux-x64-gnu', 'linux-arm64-gnu', 'linux-x64-musl', 'linux-arm64-musl'] as const
+
+export interface BrustDep {
+  kind: 'explicit' | 'version' | 'workspace' | 'file'
+  spec: string
+  overrides?: Record<string, string>
+}
+
+export const packageRoot = (): string => resolve(import.meta.dir, '..')
+
+const readJson = (p: string): Record<string, unknown> | null => {
+  try { return JSON.parse(readFileSync(p, 'utf8')) as Record<string, unknown> } catch { return null }
+}
+
+/** The brust checkout this package lives in, or null. Exact markers two levels up, no walking: a bunx cache can never match. */
+export function monorepoRoot(pkgRoot = packageRoot()): string | null {
+  const root = resolve(pkgRoot, '../..')
+  const rootPkg = readJson(join(root, 'package.json'))
+  if (rootPkg?.name !== 'brust-v2' || !Array.isArray(rootPkg.workspaces)) return null
+  if (readJson(join(root, 'packages/brust/package.json'))?.name !== '@brust/core') return null
+  if (!existsSync(join(root, 'examples/pokedex/routes.tsx'))) return null
+  return root
+}
+
+/** `x/*` matches a direct child of `<root>/x`; a literal `x` matches `<root>/x` itself. */
+function inWorkspace(root: string, target: string): boolean {
+  const rootPkg = readJson(join(root, 'package.json'))
+  const globs = (rootPkg?.workspaces as string[] | undefined) ?? []
+  const rel = relative(root, resolve(target))
+  if (rel.startsWith('..') || rel === '') return false
+  return globs.some((g) => (g.endsWith('/*') ? dirname(rel) === g.slice(0, -2) : rel === g))
+}
+
+export function resolveBrustDep(o: { explicit?: string; targetDir: string; pkgRoot?: string }): BrustDep {
+  if (o.explicit) return { kind: 'explicit', spec: o.explicit }
+  const pkgRoot = o.pkgRoot ?? packageRoot()
+  const root = monorepoRoot(pkgRoot)
+  if (root) {
+    if (inWorkspace(root, o.targetDir)) return { kind: 'workspace', spec: 'workspace:*' }
+    // `file:` alone fails: core's own workspace:* deps do not resolve outside the workspace globs, so override them.
+    const overrides: Record<string, string> = { '@brust/runtime-dom': `file:${root}/packages/runtime-dom` }
+    for (const p of PLATS) overrides[`@brust/native-${p}`] = `file:${root}/npm/${p}`
+    return { kind: 'file', spec: `file:${root}/packages/brust`, overrides }
+  }
+  const version = (readJson(join(pkgRoot, 'package.json'))?.version as string | undefined) ?? '0.0.0'
+  return { kind: 'version', spec: `^${version}` }
+}
+
+/** Merge `overrides` into <appDir>/package.json (2-space JSON + trailing newline). */
+export function applyOverrides(appDir: string, overrides: Record<string, string>): void {
+  const p = join(appDir, 'package.json')
+  const pkg = JSON.parse(readFileSync(p, 'utf8')) as Record<string, unknown>
+  pkg.overrides = { ...(pkg.overrides as Record<string, string> | undefined), ...overrides }
+  writeFileSync(p, `${JSON.stringify(pkg, null, 2)}\n`)
+}

package/src/templates.ts

@@ -0,0 +1,64 @@
+// Template registry + selection (port of 0.1.x new.ts:165-220). `blank` is committed; `pokedex` is GENERATED from
+// examples/pokedex by scripts/sync-template.ts (prepack, monorepo runs, tests) and gitignored.
+import { join, resolve } from 'node:path'
+
+export interface TemplateDef {
+  name: string
+  description: string
+  dir: string
+  /** true → produced by scripts/sync-template.ts, never hand-edited. */
+  generated: boolean
+}
+
+export const DEFAULT_TEMPLATE = 'blank'
+
+/** Test-only hook: point both templates at another directory (CREATE_APP_TEMPLATES_DIR) to exercise the copy-failure rollback. */
+const templatesDir = (): string => process.env.CREATE_APP_TEMPLATES_DIR || resolve(import.meta.dir, '../templates')
+
+export function listTemplates(): TemplateDef[] {
+  const root = templatesDir()
+  return [
+    { name: 'blank', description: 'One page, a native counter, an Elysia hello action', dir: join(root, 'blank'), generated: false },
+    { name: 'pokedex', description: 'The v2 Pokédex: loaders, L1 cache, native + island, the team store on Elysia actions + SQLite', dir: join(root, 'pokedex'), generated: true },
+  ]
+}
+
+export interface SelectTemplateOpts {
+  explicit?: string
+  yes: boolean
+  isTTY: boolean
+  read?: (label: string) => string | null
+  print?: (s: string) => void
+}
+
+export function selectTemplate(opts: SelectTemplateOpts): TemplateDef {
+  const templates = listTemplates()
+  if (opts.explicit !== undefined) {
+    const t = templates.find((x) => x.name === opts.explicit)
+    if (!t) throw new Error(`create-app: unknown template "${opts.explicit}" — choose one of: ${templates.map((x) => x.name).join(', ')}`)
+    return t
+  }
+  if (opts.yes || !opts.isTTY) return templates.find((t) => t.name === DEFAULT_TEMPLATE) ?? templates[0]!
+  const read = opts.read ?? ((label: string) => prompt(label))
+  const print = opts.print ?? ((s: string) => process.stdout.write(s))
+  return promptPicker(templates, read, print)
+}
+
+function promptPicker(templates: TemplateDef[], read: (label: string) => string | null, print: (s: string) => void): TemplateDef {
+  const def = templates.find((t) => t.name === DEFAULT_TEMPLATE) ?? templates[0]!
+  const defIndex = templates.indexOf(def) + 1
+  for (let attempt = 0; attempt < 3; attempt++) {
+    print('Select a template:\n')
+    for (let i = 0; i < templates.length; i++) print(`  ${i + 1}) ${templates[i]!.name} — ${templates[i]!.description}\n`)
+    const raw = read(`Template [${defIndex}]: `)
+    if (raw === null) return def
+    const input = raw.trim()
+    if (input === '') return def
+    const asNum = Number.parseInt(input, 10)
+    if (!Number.isNaN(asNum) && asNum >= 1 && asNum <= templates.length) return templates[asNum - 1]!
+    const byName = templates.find((t) => t.name === input)
+    if (byName) return byName
+    print(`Invalid selection "${input}". Try again.\n`)
+  }
+  return def
+}

package/templates/blank/README.md.tmpl

@@ -0,0 +1,42 @@
+# __PROJECT_NAME__
+
+A [brust](https://github.com/AssetsArt/brust) app: React components compiled ahead of time, served by Rust.
+
+## Run
+
+```bash
+bun install
+bun run dev        # brust build routes.tsx && brust start  ->  http://127.0.0.1:1337
+```
+
+Scripts: `dev` (build then start), `build`, `start`, `typecheck`.
+
+## Layout
+
+- `routes.tsx` — `defineRoutes`: one layout, one page.
+- `components/Layout.tsx` — the document root (`<html>` + `<Outlet/>`).
+- `components/Counter.tsx` — a `useState` counter; the compiler makes it a native component (no React in the browser).
+- `actions.ts` — an Elysia 2 app on `brust()`, served by Rust under `/_brust/action` (enabled by `[actions]` in `brust.toml`).
+- `public/` — static files, served at `/public/...`.
+
+## The hello action
+
+```bash
+curl 'http://127.0.0.1:1337/_brust/action/hello?name=ash'
+# {"message":"Hello, ash!"}
+```
+
+From the browser, use the typed client:
+
+```ts
+import { client } from '@brust/core/client'
+import type { App } from './actions'
+
+const api = client<App>()
+const { data } = await api.hello.get({ query: { name: 'ash' } })
+```
+
+## Docs
+
+- Actions: https://github.com/AssetsArt/brust/blob/v2/docs/actions.md
+- The unified store: https://github.com/AssetsArt/brust/blob/v2/docs/store.md

package/templates/blank/_gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

package/templates/blank/actions.ts

@@ -0,0 +1,13 @@
+import { brust } from '@brust/core/elysia'
+import { Elysia, t } from 'elysia'
+
+// One Elysia 2 app, served by the Rust server under /_brust/action (brust.toml [actions]).
+// Elysia 2 takes (path, hook, handler). Never call app.listen(): Rust owns HTTP.
+const app = new Elysia({ adapter: brust() }).get(
+  '/hello',
+  { query: t.Object({ name: t.Optional(t.String()) }) },
+  ({ query }) => ({ message: `Hello, ${query.name ?? 'world'}!` }),
+)
+
+export default app
+export type App = typeof app

package/templates/blank/brust.toml

@@ -0,0 +1,6 @@
+[server]
+address = "127.0.0.1"
+port = 1337
+
+# Elysia actions (docs/actions.md). Defaults: entry = "actions.ts", prefix = "/_brust/action", max_body_bytes = 262144
+[actions]

package/templates/blank/components/Counter.tsx

@@ -0,0 +1,11 @@
+// useState only, so the compiler lowers this to a native component: a signal in the browser, no React shipped.
+import { useState } from 'react'
+
+export default function Counter() {
+  const [count, setCount] = useState(0)
+  return (
+    <button type="button" onClick={() => setCount(count + 1)}>
+      count is {count}
+    </button>
+  )
+}

package/templates/blank/components/Layout.tsx

@@ -0,0 +1,21 @@
+// The document root: a plain <html> with <Outlet/> for the page. Static files are served from /public.
+import { Outlet } from '@brust/core/routes'
+
+export default function Layout() {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>brust app</title>
+        <link rel="icon" href="/public/favicon.svg" />
+        <link rel="stylesheet" href="/public/app.css" />
+      </head>
+      <body>
+        <main>
+          <Outlet />
+        </main>
+      </body>
+    </html>
+  )
+}

package/templates/blank/package.json.tmpl

@@ -0,0 +1,24 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "brust build routes.tsx && brust start",
+    "build": "brust build routes.tsx",
+    "start": "brust start",
+    "typecheck": "bun check"
+  },
+  "dependencies": {
+    "@brust/core": __BRUST_DEP__,
+    "@elysia/eden": "2.0.0-beta.6",
+    "elysia": "2.0.0-beta.30",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "@types/react": "^19.2.0",
+    "typescript": "^7.0.2"
+  }
+}

package/templates/blank/pages/HomePage.tsx

@@ -0,0 +1,11 @@
+import Counter from '../components/Counter'
+
+export default function HomePage() {
+  return (
+    <section>
+      <h1>Hello from brust</h1>
+      <p>Edit pages/HomePage.tsx, then run bun run dev again.</p>
+      <Counter />
+    </section>
+  )
+}

package/templates/blank/public/app.css

@@ -0,0 +1,14 @@
+:root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+body { margin: 0; }
+main { max-width: 40rem; margin: 4rem auto; padding: 0 1.5rem; line-height: 1.5; }
+h1 { font-size: 2rem; margin: 0 0 0.5rem; }
+button {
+  cursor: pointer;
+  font: inherit;
+  padding: 0.5rem 1rem;
+  border: 1px solid currentColor;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: inherit;
+}
+button:hover { opacity: 0.8; }

package/templates/blank/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><circle cx="16" cy="16" r="15" fill="#ef4444"/><rect x="1" y="14" width="30" height="4" fill="#111"/><circle cx="16" cy="16" r="5" fill="#fff" stroke="#111" stroke-width="2"/></svg>

package/templates/blank/routes.tsx

@@ -0,0 +1,5 @@
+import { defineRoutes } from '@brust/core/routes'
+import Layout from './components/Layout'
+import HomePage from './pages/HomePage'
+
+export const routes = defineRoutes([{ Component: Layout, children: [{ path: '/', Component: HomePage }] }])

package/templates/blank/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": [
+      "ESNext",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "types": [
+      "bun"
+    ],
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/templates/pokedex/README.md.tmpl

@@ -0,0 +1,44 @@
+# __PROJECT_NAME__
+
+A [brust](https://github.com/AssetsArt/brust) Pokédex: loaders over an offline dataset, L1 page cache, native components,
+React islands, and a persistent team built with Elysia actions + SQLite and one unified store.
+
+## Run
+
+```bash
+bun install
+bun run dev        # brust build routes.tsx && brust start  ->  http://127.0.0.1:1337
+```
+
+Scripts: `dev` (build then start), `build`, `start`, `typecheck`, `snapshot` (needs network; rewrites `data/pokedex.json`).
+
+## The team
+
+The team lives in `data/team.sqlite` (created on first use, gitignored). Delete the file to reset it, or set
+`POKEDEX_TEAM_DB=/path/to/team.sqlite` to put it elsewhere. A fresh database is empty.
+
+The actions are served by Rust under `/_brust/action` (`GET /team`, `POST /team {id}`, `DELETE /team/:id`); the team holds
+at most 6 members and a seventh add answers `409` (`TeamFull`). The team store (`stores/team.ts`) is read by the native
+`AddToTeamButton` and the `TeamBuilder` island, and seeded by the layout loader, so the first paint is already right.
+`/unified` shows the same idea with a counter (`/unified?start=5` seeds it on the server).
+
+## Layout
+
+- `routes.tsx` — `/`, `/pokedex`, `/pokemon/{name}` (L1 60 s, `?nocache` bypass), `/type-chart` (L1 1 h), `/unified`, and a
+  root-level `*` 404 outside the layout. Pages that show the team carry the cache tag `team`.
+- `lib/` — loaders over the snapshot, `team-db.ts` (sqlite, server-only), `team-client.ts` + `api.ts` (the typed actions client).
+- `actions.ts` — the Elysia 2 team app on `brust()`; `stores/` — `team` and `unified` (`defineStore`).
+- `components/`, `pages/` — plain React functions.
+
+## Regenerating the stylesheet (never hand-edit `public/app.css`)
+
+```bash
+bunx @tailwindcss/cli@4 -i styles/app.css -o public/app.css --minify
+```
+
+(Tailwind must resolve from the input's directory: install `tailwindcss` in the project first.)
+
+## Docs
+
+- Actions: https://github.com/AssetsArt/brust/blob/v2/docs/actions.md
+- The unified store: https://github.com/AssetsArt/brust/blob/v2/docs/store.md

package/templates/pokedex/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+data/team.sqlite*

package/templates/pokedex/actions.ts

@@ -0,0 +1,37 @@
+// examples/pokedex/actions.ts — the team RPC surface (M3-F E7). One Elysia 2 app behind the Rust server
+// (brust.toml [actions]); never imported by browser code except as `import type { App }`.
+import { cache, type InvalidateArgs } from '@brust/core'
+import { brust } from '@brust/core/elysia'
+import { Elysia, problem, t } from 'elysia'
+import { pokemonById } from './lib/pokeapi'
+import { MAX_TEAM } from './lib/team'
+import { type TeamDb, teamDb } from './lib/team-db'
+
+export interface TeamDeps {
+  db: () => TeamDb
+  invalidate: (a: InvalidateArgs) => unknown
+}
+
+export function teamApp({ db, invalidate }: TeamDeps = { db: teamDb, invalidate: cache.invalidate }) {
+  const reply = () => ({ team: db().list(), max: MAX_TEAM })
+  // R5: cached pages that render the team carry the tag `team`; drop them after a real change.
+  const changed = () => invalidate({ tags: ['team'] })
+  return new Elysia({ adapter: brust() })
+    .get('/team', () => reply())
+    .post('/team', { body: t.Object({ id: t.Integer({ minimum: 1 }) }) }, ({ body }) => {
+      const p = pokemonById(body.id)
+      if (!p) return problem(404, { title: 'UnknownPokemon', detail: `no Pokémon #${body.id}` })
+      const r = db().add(p)
+      if (r === 'full') return problem(409, { title: 'TeamFull', detail: `the team already has ${MAX_TEAM} members`, max: MAX_TEAM })
+      if (r === 'added') changed()
+      return reply()
+    })
+    .delete('/team/:id', { params: t.Object({ id: t.Integer({ minimum: 1 }) }) }, ({ params }) => {
+      if (db().remove(params.id)) changed()
+      return reply()
+    })
+}
+
+const app = teamApp()
+export default app
+export type App = typeof app

package/templates/pokedex/brust.toml

@@ -0,0 +1,8 @@
+[server]
+address = "127.0.0.1"
+port = 1337
+
+[build]
+server_only = ["lib/team-db.ts"]
+
+[actions]