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

package/templates/blank/wrangler.jsonc.tmpl

@@ -0,0 +1,9 @@
+// Your Cloudflare config for `bun run dev:cf` / `bun run deploy:cf`.
+// `brust build --target cloudflare` merges this file into dist/cf/wrangler.jsonc and owns these keys:
+// main, assets (the ASSETS binding), compatibility_date, no_bundle, build, rules, site.
+{
+  "name": "__PROJECT_NAME__"
+  // "d1_databases": [{ "binding": "DB", "database_name": "__PROJECT_NAME__", "database_id": "<id>" }],
+  // "kv_namespaces": [{ "binding": "KV", "id": "<id>" }],
+  // "vars": { "GREETING": "hello" }
+}

package/templates/pokedex/README.md.tmpl

@@ -0,0 +1,59 @@
+# __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 dev routes.tsx (hot reload)  ->  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` (the team interface: sqlite natively, D1 on Cloudflare via `[cloudflare.alias]`; 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.
+
+## Cloudflare Workers (preview)
+
+```bash
+bun run cf:migrate:local   # create the local D1 table (state in .wrangler/)
+bun run dev:cf             # build for Workers and run `wrangler dev` (rebuilds on change)
+```
+
+`brust build --target cloudflare` swaps `lib/team-db.ts` for the D1 version (`lib/team-db.d1.ts`) through `[cloudflare.alias]`
+in `brust.toml`; your bindings live in `wrangler.jsonc`. To deploy: `wrangler d1 create __PROJECT_NAME__-team`, paste the
+`database_id` into the **app-root** `wrangler.jsonc` (not `dist/cf/`, which is regenerated), `bun run cf:migrate:remote`,
+then `bun run deploy:cf`.
+
+Preview note: a team change refreshes cached team pages only in the isolate that served the action; other isolates catch up
+within the route `ttl` (60 s for `/pokemon/*`, 1 h for `/type-chart`) until the cross-isolate invalidation lands.
+
+## 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/main/docs/actions.md
+- The unified store: https://github.com/AssetsArt/brust/blob/main/docs/store.md

package/templates/pokedex/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+data/team.sqlite*
+.wrangler/
+.dev.vars*

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 = async () => ({ team: await 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 }) }) }, async ({ body }) => {
+      const p = pokemonById(body.id)
+      if (!p) return problem(404, { title: 'UnknownPokemon', detail: `no Pokémon #${body.id}` })
+      const r = await 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 }) }) }, async ({ params }) => {
+      if (await 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,28 @@
+[server]
+address = "127.0.0.1"
+port = 1337
+
+[build]
+server_only = ["lib/team-db"]
+
+[actions]
+
+# `brust build --target cloudflare` swaps the sqlite roster for the D1 one (the whole facade module).
+[cloudflare.alias]
+"lib/team-db.ts" = "lib/team-db.d1.ts"
+
+# A shared second cache tier (needs `bun add @brust/cache-redis`; see the brust docs, "Redis / Dragonfly"):
+# [cache]
+# adapter = "redis"   # or "dragonfly"
+# [cache.redis]
+# url = "env:REDIS_URL"
+
+# Or, on Cloudflare Workers: a shared second cache tier (KV bodies + a Durable Object invalidation broadcast). Off by default.
+# Needs: bun add @brust/cache-cloudflare, plus the KV and Durable Object bindings in wrangler.jsonc (see the comment there).
+# [cache]
+# adapter = "cloudflare-kv"
+# broadcast = "cloudflare-do"
+# epoch_interval_ms = 5000
+#
+# [cache.cloudflare]
+# kv_min_ttl_s = 300

package/templates/pokedex/components/AddToTeamButton.tsx

@@ -0,0 +1,37 @@
+// components/AddToTeamButton.tsx — NATIVE (M3-F D7). Render reads the team store through useStore: the server paints
+// __store.team.*, the chunk reads team.members() live. Writes go through lib/team-client (handlers only, compiler rule
+// store-write-in-render).
+import { useStore } from '@brust/core/store/react'
+import { useState } from 'react'
+import { toggleMember } from '../lib/team-client'
+import { team } from '../stores/team'
+
+export default function AddToTeamButton({ id }: { id: number }) {
+  const s = useStore(team)
+  const [busy, setBusy] = useState(false)
+  const inTeam = s.members.some((m) => m.id === id)
+  const full = !inTeam && s.members.length >= s.max
+  return (
+    <button
+      type="button"
+      data-testid="add-to-team"
+      data-in-team={inTeam ? 'true' : 'false'}
+      disabled={busy || full}
+      className={
+        inTeam
+          ? 'inline-flex w-full items-center justify-center rounded-lg bg-slate-200 px-4 py-2.5 text-sm font-semibold text-slate-700 transition-colors disabled:opacity-50 dark:bg-slate-700 dark:text-slate-100'
+          : 'inline-flex w-full items-center justify-center rounded-lg bg-brand-500 px-4 py-2.5 text-sm font-semibold text-white transition-colors hover:bg-brand-600 disabled:opacity-50'
+      }
+      onClick={async () => {
+        setBusy(true)
+        try {
+          await toggleMember(id, inTeam)
+        } finally {
+          setBusy(false)
+        }
+      }}
+    >
+      {inTeam ? 'In your team' : full ? 'Team Full' : 'Add to team'}
+    </button>
+  )
+}

package/templates/pokedex/components/AppLayout.tsx

@@ -0,0 +1,32 @@
+// components/AppLayout.tsx — the document (S9): plain <html>, <Outlet/> for the leaf, TeamBuilder as a react child.
+import { Outlet } from '@brust/core/routes'
+import type { NavItem } from '../lib/types'
+import NavLink from './NavLink'
+import TeamBuilder from './TeamBuilder'
+import ThemeToggle from './ThemeToggle'
+
+export default function AppLayout(props: { title: string; mode: 'dark' | 'light'; nav: NavItem[] }) {
+  return (
+    <html lang="en" data-mode={props.mode}>
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>{props.title}</title>
+        <link rel="icon" href="/public/favicon.svg" />
+        <link rel="stylesheet" href="/public/app.css" />
+      </head>
+      <body className="min-h-screen bg-slate-50 text-slate-900 dark:bg-slate-950 dark:text-slate-100">
+        <header className="sticky top-0 z-50 border-b border-slate-200 bg-white/80 dark:border-slate-800 dark:bg-slate-950/80">
+          <nav className="mx-auto flex h-16 max-w-6xl items-center gap-2 px-4">
+            <a href="/" className="mr-2 flex items-center gap-2 no-underline"><span className="grid h-8 w-8 place-items-center rounded-lg bg-brand-500 text-sm font-extrabold text-white">P</span><span className="text-base font-extrabold">PokéDex</span></a>
+            {props.nav.map((n) => <NavLink key={n.href} href={n.href} label={n.label} active={n.active} />)}
+            <div className="ml-auto"><ThemeToggle mode={props.mode} /></div>
+          </nav>
+        </header>
+        <main className="mx-auto max-w-6xl px-4 py-8"><Outlet /></main>
+        <footer className="border-t border-slate-200 py-6 text-center text-xs text-slate-400 dark:border-slate-800">Built with brust · data: PokeAPI snapshot</footer>
+        <TeamBuilder />
+      </body>
+    </html>
+  )
+}

package/templates/pokedex/components/Breadcrumb.tsx

@@ -0,0 +1,4 @@
+// components/Breadcrumb.tsx — static (no nav store in M2).
+export default function Breadcrumb(props: { crumb: string }) {
+  return <b className="text-slate-600 dark:text-slate-300">{props.crumb}</b>
+}

package/templates/pokedex/components/DexCard.tsx

@@ -0,0 +1,11 @@
+// components/DexCard.tsx — static per-row child (props only, no job: its list is state-derived, D4).
+import type { DexCard as Card } from '../lib/types'
+export default function DexCard(props: { card: Card }) {
+  return (
+    <a href={props.card.detailHref} data-dex={props.card.num} className="group flex flex-col items-center rounded-2xl border border-slate-200 bg-white p-3 no-underline shadow-sm dark:border-slate-800 dark:bg-slate-900">
+      <span className="self-start text-[11px] font-semibold tabular-nums text-slate-400">{props.card.num}</span>
+      <img src={props.card.artwork} alt={props.card.displayName} loading="lazy" className="h-24 w-24 object-contain" />
+      <div className="mt-1 text-sm font-semibold">{props.card.displayName}</div>
+    </a>
+  )
+}

package/templates/pokedex/components/DexFilter.tsx

@@ -0,0 +1,26 @@
+// components/DexFilter.tsx — useState filter/sort; `filterSort` is a module helper so the first paint is a
+// precompute job seeded with the initial state and the client recomputes on change (battery e-precompute-state).
+import { useState } from 'react'
+import { filterSort } from '../lib/filter'
+import type { DexCard as Card } from '../lib/types'
+import DexCard from './DexCard'
+export default function DexFilter(props: { items: Card[] }) {
+  const [q, setQ] = useState('')
+  const [az, setAz] = useState(false)
+  const shown = filterSort(props.items, q, az)
+  return (
+    <section>
+      <div className="mb-6 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <input type="search" placeholder="Search Pokémon…" value={q} onChange={(e) => setQ(e.target.value)} className="w-full rounded-xl border border-slate-200 bg-white px-4 py-2.5 text-sm sm:max-w-xs dark:border-slate-700 dark:bg-slate-900" />
+        <div className="flex items-center gap-3">
+          <button type="button" onClick={() => setAz(false)} className="rounded-l-xl border border-slate-200 px-3 py-1.5 text-sm dark:border-slate-700">Dex#</button>
+          <button type="button" onClick={() => setAz(true)} className="rounded-r-xl border border-slate-200 px-3 py-1.5 text-sm dark:border-slate-700">A–Z</button>
+          <span data-testid="count" className="rounded-full bg-slate-100 px-3 py-1 text-xs font-semibold tabular-nums dark:bg-slate-800">{shown.length} / {props.items.length}</span>
+        </div>
+      </div>
+      <div className="grid grid-cols-2 gap-3 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-6">
+        {shown.map((c) => <DexCard key={c.id} card={c} />)}
+      </div>
+    </section>
+  )
+}

package/templates/pokedex/components/HeroSearch.tsx

@@ -0,0 +1,14 @@
+// components/HeroSearch.tsx — controlled input + useId; a plain GET form to /pokedex?q= (no SPA navigate).
+import { useId, useState } from 'react'
+export default function HeroSearch() {
+  const id = useId()
+  const [q, setQ] = useState('')
+  return (
+    <form action="/pokedex" method="get" className="mx-auto mt-8 flex w-full max-w-md items-center gap-2 rounded-2xl bg-white/95 p-2 shadow-lg dark:bg-slate-900/90">
+      <label htmlFor={id} className="sr-only">Search the Pokédex</label>
+      <input id={id} name="q" type="search" placeholder="Search the Pokédex…" value={q} onChange={(e) => setQ(e.target.value)}
+        className="min-w-0 flex-1 rounded-xl bg-transparent px-3 py-2 text-sm text-slate-900 dark:text-white" />
+      <button type="submit" className="rounded-xl bg-brand-500 px-4 py-2 text-sm font-semibold text-white">Search</button>
+    </form>
+  )
+}

package/templates/pokedex/components/NavLink.tsx

@@ -0,0 +1,6 @@
+// components/NavLink.tsx — static; `active` is computed in the loader from `path` (no client nav in M2).
+const BASE = 'inline-flex items-center rounded-lg px-3 py-1.5 text-sm font-medium text-slate-600 hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-800'
+const ACTIVE = 'inline-flex items-center rounded-lg px-3 py-1.5 text-sm font-semibold text-brand-600 bg-brand-50 dark:text-brand-50 dark:bg-brand-600/20'
+export default function NavLink(props: { href: string; label: string; active: boolean }) {
+  return <a href={props.href} data-active={props.active ? '1' : '0'} className={props.active ? ACTIVE : BASE}>{props.label}</a>
+}

package/templates/pokedex/components/TeamBuilder.tsx

@@ -0,0 +1,32 @@
+// components/TeamBuilder.tsx — react tier on purpose (useReducer for `open`): SSR + idle hydration (S12). The roster is the
+// unified `team` store: the SSR scope is seeded from the snapshot, so the first client snapshot equals the server paint (D8).
+import { useStore } from '@brust/core/store/react'
+import { useReducer } from 'react'
+import { removeMember } from '../lib/team-client'
+import { team } from '../stores/team'
+
+const flip = (open: boolean): boolean => !open
+
+export default function TeamBuilder() {
+  const { members, max } = useStore(team)
+  const [open, toggle] = useReducer(flip, false)
+  return (
+    <div className="fixed bottom-5 right-5 z-[200]">
+      {open && (
+        <div data-testid="team-panel" className="mb-3 w-80 overflow-hidden rounded-xl border border-slate-200 bg-white shadow-2xl dark:border-slate-700 dark:bg-slate-900">
+          <div className="flex items-center gap-2 border-b border-slate-100 px-4 py-3 dark:border-slate-800"><span className="text-sm font-extrabold">My team</span><span className="ml-auto text-xs font-semibold">{members.length} / {max}</span></div>
+          {members.length === 0 ? <div className="px-5 py-7 text-center text-xs text-slate-400">No Pokémon on your team yet.</div> : members.map((m) => (
+            <div key={m.id} className="flex items-center gap-2.5 border-b border-slate-100 px-3.5 py-2.5 dark:border-slate-800">
+              <img src={m.artwork} alt={m.displayName} className="h-7 w-7 object-contain" />
+              <a href={`/pokemon/${m.name}`} className="min-w-0 flex-1 text-xs font-semibold no-underline">{m.displayName}</a>
+              <button type="button" aria-label="Remove" onClick={() => removeMember(m.id)} className="rounded p-1 text-slate-400">×</button>
+            </div>
+          ))}
+        </div>
+      )}
+      <button type="button" onClick={() => toggle()} className="inline-flex items-center gap-1.5 rounded-full bg-brand-500 px-5 py-2.5 text-sm font-semibold text-white shadow-lg">
+        My team <span data-testid="team-count" className="rounded-full bg-white/25 px-2 py-0.5 text-xs font-extrabold">{members.length}</span>
+      </button>
+    </div>
+  )
+}

package/templates/pokedex/components/ThemeToggle.tsx

@@ -0,0 +1,16 @@
+// components/ThemeToggle.tsx — useState + useEffect (spec §9 example). No cookie write (actions are M3): the
+// loader still reads `mode` from the cookie for the first paint; the toggle is per page view.
+import { useEffect, useId, useState } from 'react'
+export default function ThemeToggle(props: { mode: 'dark' | 'light' }) {
+  // `useId` makes this instance server-fed, which is what puts its client chunk in the manifest's
+  // `children[]` (ledger F66: a native child with no job and no useId never gets its chunk linked).
+  const id = useId()
+  const [mode, setMode] = useState(props.mode)
+  useEffect(() => { document.documentElement.dataset.mode = mode }, [mode])
+  return (
+    <button type="button" id={id} aria-label="Toggle theme" data-testid="theme-toggle" onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}
+      className="inline-flex items-center gap-1.5 rounded-lg border border-slate-200 px-3 py-1.5 text-sm font-medium dark:border-slate-700">
+      {mode === 'dark' ? 'Light' : 'Dark'}
+    </button>
+  )
+}

package/templates/pokedex/components/TypeBadge.tsx

@@ -0,0 +1,5 @@
+// components/TypeBadge.tsx — one helper-backed job; rendered per row on HomePage AND DetailPage (D4).
+import { label, tint } from '../lib/format'
+export default function TypeBadge(props: { type: string }) {
+  return <span data-type={props.type} style={{ background: tint(props.type) }} className="rounded-full px-3 py-1 text-xs font-semibold uppercase tracking-wide text-white">{label(props.type)}</span>
+}

package/templates/pokedex/components/UnifiedIsland.tsx

@@ -0,0 +1,28 @@
+// components/UnifiedIsland.tsx — React island (SSR + hydration). `useStore` alone compiles native, so the "clicks from
+// React" tally (useReducer) is what puts this on the react tier (D10 asks for an island).
+import { useStore } from '@brust/core/store/react'
+import { useReducer } from 'react'
+import { unified } from '../stores/unified'
+
+const tick = (n: number): number => n + 1
+
+export default function UnifiedIsland() {
+  const { count } = useStore(unified)
+  const [mine, tally] = useReducer(tick, 0)
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <p data-testid="unified-island-count" className="text-4xl font-bold tabular-nums">{count}</p>
+      <button
+        type="button"
+        data-testid="unified-island-inc"
+        onClick={() => {
+          tally()
+          unified.count.set(count + 1)
+        }}
+        className="inline-flex h-10 items-center rounded-lg bg-brand-500 px-4 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+      >
+        Increment from React ({mine})
+      </button>
+    </div>
+  )
+}

package/templates/pokedex/components/UnifiedNative.tsx

@@ -0,0 +1,20 @@
+// components/UnifiedNative.tsx — NATIVE (0 jobs): render reads the `unified` store, the handler writes it. The chunk ships zero React.
+import { useStore } from '@brust/core/store/react'
+import { unified } from '../stores/unified'
+
+export default function UnifiedNative() {
+  const s = useStore(unified)
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <p data-testid="unified-native-count" className="text-4xl font-bold tabular-nums">{s.count}</p>
+      <button
+        type="button"
+        data-testid="unified-native-inc"
+        onClick={() => unified.count.set(s.count + 1)}
+        className="inline-flex h-10 items-center rounded-lg border border-slate-300 px-4 text-sm font-semibold transition-colors hover:border-slate-500 dark:border-slate-600"
+      >
+        Increment — zero React
+      </button>
+    </div>
+  )
+}

package/templates/pokedex/components/UnifiedStoreNode.tsx

@@ -0,0 +1,14 @@
+// components/UnifiedStoreNode.tsx — the centre node: a read-only native view of the same store both panels write (0 jobs).
+import { useStore } from '@brust/core/store/react'
+import { unified } from '../stores/unified'
+
+export default function UnifiedStoreNode() {
+  const { count } = useStore(unified)
+  return (
+    <div className="flex min-w-36 flex-col items-center gap-1 rounded-2xl border-2 border-brand-500 px-6 py-5 text-center">
+      <span className="text-sm font-semibold">one store</span>
+      <span data-testid="unified-node-count" className="text-3xl font-bold tabular-nums text-brand-500">{count}</span>
+      <code className="text-sm text-slate-500 dark:text-slate-400">unified</code>
+    </div>
+  )
+}