brustjs 0.1.23-alpha → 0.1.24-alpha

package/example/pokedex/actions.ts

@@ -6,7 +6,7 @@
 //   api.team({ id }).delete()      → DELETE /_brust/action/team/{id}
 
 import { z } from 'zod'
-import { defineActions } from 'brustjs'
+import { defineActions, ActionError } from 'brustjs'
 import { MAX_TEAM, teamStore } from './lib/team-store'
 
 const TeamMemberInput = z.object({
@@ -23,12 +23,10 @@ export const actions = defineActions()
   .post(
     '/team',
     ({ body }) => {
-      const ok = teamStore.add(body)
-      // GAP S7: a domain error (team full) cannot throw a typed non-2xx across
-      // the treaty boundary, so it rides back inside the success payload as a
-      // `full` flag. The client therefore checks two places (transport `error`
-      // AND `data.full`). See ./FRAMEWORK-GAPS.md S7.
-      return { team: teamStore.list(), max: MAX_TEAM, full: !ok }
+      if (!teamStore.add(body)) {
+        throw new ActionError(409, 'TEAM_FULL', { data: { max: MAX_TEAM } })
+      }
+      return { team: teamStore.list(), max: MAX_TEAM }
     },
     { body: TeamMemberInput },
   )

package/example/pokedex/components/AddToTeamButton.tsx

@@ -8,6 +8,7 @@
 // The behavior is react-free: `signal`/`computed` from brustjs/store (the window
 // singleton on the client), `client` from brustjs/client (the treaty action
 // client — also react-free), and the shared teamStore. NO react imports.
+import type { ActionErrorBody } from 'brustjs'
 import { client } from 'brustjs/client'
 import { computed, signal } from 'brustjs/store'
 import type { Actions } from '../actions'
@@ -24,9 +25,10 @@ export const behavior = ({ props }: { props: AddToTeamProps }) => {
   // TeamBuilder island — they resolve the same window singleton. A native
   // x-on-click mutation is therefore seen reactively by a React island.
   const busy = signal(false)
+  const full = signal(false)
   const inTeam = computed(() => (teamStore.members() ?? []).some((m) => m.id === props.id))
   const label = computed(() =>
-    inTeam() ? '✓ In your team' : disabled() ? 'Team Full' : '＋ Add to team',
+    inTeam() ? '✓ In your team' : disabled() || full() ? 'Team Full' : '＋ Add to team',
   )
   const btnClass = computed(() => `aa-btn aa-btn--full${inTeam() ? ' aa-btn--secondary' : ''}`)
   const disabled = computed(() => busy() || ((teamStore.members()?.length ?? 0) >= 6 && !inTeam()))
@@ -44,7 +46,7 @@ export const behavior = ({ props }: { props: AddToTeamProps }) => {
         const { data } = await api.team({ id: props.id }).delete()
         if (data) teamStore.members.set(data.team)
       } else {
-        const { data } = await api.team.post({
+        const { data, error } = await api.team.post({
           id: props.id,
           name: props.name,
           displayName: props.displayName,
@@ -52,8 +54,11 @@ export const behavior = ({ props }: { props: AddToTeamProps }) => {
           types: props.types,
           artwork: props.artwork,
         })
-        if (data && !data?.full) {
+        if (data) {
+          full.set(false)
           teamStore.members.set(data.team)
+        } else if ((error?.value as ActionErrorBody)?.code === 'TEAM_FULL') {
+          full.set(true) // server rejected — team full; surface instead of silent no-op
         }
       }
     } finally {
@@ -61,7 +66,7 @@ export const behavior = ({ props }: { props: AddToTeamProps }) => {
     }
   }
 
-  return { init, label, btnClass, toggle, disabled }
+  return { init, label, btnClass, toggle, disabled, full }
 }
 
 // default → jinja (server). The x-* directives are static string attributes the

package/example/pokedex/components/{PageLayout.tsx → AppLayout.tsx}

@@ -1,29 +1,33 @@
-// Shared native layout shell. INLINED into each route at build time (T6): the
-// route's root is <PageLayout native …>, whose expansion roots in <BrustPage>,
-// which the compiler now promotes to the document shell. Pages supply only
-// title/active/crumb + their aa-content inner.
+// Router-level native layout (Approach a: nested routes + <Outlet/>). Written
+// ONCE and nested as the parent of every page route in routes.tsx. The synth
+// wrapper the compiler builds is `<AppLayout native><Leaf native/></AppLayout>`
+// — AppLayout receives NO props at the call site, so the chrome data it renders
+// (title / active / crumb / teamProps) comes from the MERGED LOADER CONTEXT
+// instead (F5 chrome-prop migration). Each leaf loader returns those fields and
+// the chain-loader merge folds them into one flat jinja context; the names
+// below are destructured so the native compiler resolves them as member-paths
+// ({{ title }}, active === 'list', <TeamBuilder props={teamProps}/>).
 //
 // MUST stay single-return with no local bindings above it — a local `const`
 // would make the compiler soft-fall-back to an SSR component (no <html> shell).
 // active-nav uses conditional ELEMENTS (S11), not a className ternary
-// (unsupported). See ../FRAMEWORK-GAPS.md.
-import { BrustPage, Island } from 'brustjs'
-import type { ReactNode } from 'react'
+// (unsupported). AppLayout owns the single <main> (leaves are fragments in the
+// <Outlet/> slot) — a leaf adding its own <main> breaks SPA-nav extraction.
+// See ../FRAMEWORK-GAPS.md.
+import { BrustPage, Island, Outlet } from 'brustjs'
 import type { TeamMember } from '../lib/types'
 import TeamBuilder from './TeamBuilder'
 
-export default function PageLayout({
+export default function AppLayout({
   title,
   active,
   crumb,
   teamProps,
-  children,
 }: {
   title: string
   active: 'list' | 'typechart'
   crumb: string
   teamProps: { teamInitial: TeamMember[] }
-  children: ReactNode
 }) {
   return (
     <BrustPage
@@ -85,7 +89,9 @@ export default function PageLayout({
             </div>
           </header>
 
-          <div className="aa-content">{children}</div>
+          <div className="aa-content">
+            <Outlet />
+          </div>
         </main>
 
         <Island component={TeamBuilder} props={teamProps} ssr hydrate="load" />

package/example/pokedex/lib/loaders.ts

@@ -81,6 +81,11 @@ export async function listLoader({ req }: LoaderCtx): Promise<ListData> {
     hasNext,
     prevHref: hasPrev ? (prevOffset > 0 ? `/?offset=${prevOffset}` : '/') : '#',
     nextHref: hasNext ? `/?offset=${offset + PAGE}` : '#',
+    // Chrome fields (ChromeData) — merged into the flat jinja context and read by
+    // the router-level AppLayout (Approach a: native <Outlet/> nesting).
+    title: 'PokéDex · brust example',
+    active: 'list',
+    crumb: 'All Pokémon',
     teamProps: { teamInitial: teamStore.list() },
   }
 }
@@ -144,7 +149,10 @@ export async function detailLoader({ params }: LoaderCtx): Promise<DetailData |
 
   return {
     notFound: false,
-    pageTitle: `${cap(p.name)} · PokéDex`,
+    // Chrome fields (ChromeData) read by AppLayout from the merged context.
+    title: `${cap(p.name)} · PokéDex`,
+    active: 'list',
+    crumb: cap(p.name),
     name: p.name,
     id: p.id,
     displayName: cap(p.name),
@@ -181,7 +189,10 @@ export async function detailLoader({ params }: LoaderCtx): Promise<DetailData |
 function emptyDetail(name: string): DetailData {
   return {
     notFound: true,
-    pageTitle: `${cap(name)} · PokéDex`,
+    // Chrome fields (ChromeData) read by AppLayout from the merged context.
+    title: `${cap(name)} · PokéDex`,
+    active: 'list',
+    crumb: cap(name),
     name,
     id: 0,
     displayName: cap(name),
@@ -311,6 +322,10 @@ export async function typeChartLoader(): Promise<TypeChartData> {
 
   return {
     rows,
+    // Chrome fields (ChromeData) read by AppLayout from the merged context.
+    title: 'PokéDex · type chart',
+    active: 'typechart',
+    crumb: 'Type chart',
     teamProps: { teamInitial: teamStore.list() },
   }
 }

package/example/pokedex/lib/types.ts

@@ -7,6 +7,19 @@
 // multi-property style strings (templates have no template-literals / arithmetic
 // / helper calls). See ../FRAMEWORK-GAPS.md.
 
+/** Chrome view-model the router-level AppLayout reads from the MERGED loader
+ *  context (Approach a — native <Outlet/> nesting). AppLayout takes NO props at
+ *  its call site (`<AppLayout native>`), so each leaf loader returns these
+ *  fields and the chain-loader merge folds them into the one flat jinja context
+ *  AppLayout's template reads ({{ title }}, active === 'list', teamProps). The
+ *  key names are chosen NOT to collide with any page-data field. */
+export interface ChromeData {
+  title: string // dynamic <title> + nav header, via AppLayout's <BrustPage title={title}>
+  active: 'list' | 'typechart' // which sidebar nav item gets is-active (S11 conditional)
+  crumb: string // topbar breadcrumb leaf label
+  teamProps: { teamInitial: TeamMember[] } // floating team-dock island initial state
+}
+
 /** A single list cell — derived from the list endpoint alone (no detail fetch,
  *  see FRAMEWORK-GAPS.md S2 / N+1 avoidance). */
 export interface CardVM {
@@ -18,7 +31,7 @@ export interface CardVM {
   detailHref: string // "/pokemon/bulbasaur"
 }
 
-export interface ListData {
+export interface ListData extends ChromeData {
   items: CardVM[]
   total: number
   totalLabel: string // "1,302"
@@ -32,7 +45,6 @@ export interface ListData {
   prevHref: string
   nextHref: string
   offsetLabel: string // raw offset for the loader-echo line
-  teamProps: { teamInitial: TeamMember[] }
 }
 
 export interface TypeBadgeVM {
@@ -70,12 +82,13 @@ export interface EvolutionStageVM {
 }
 
 /** The full view-model handed to DetailPage. Every field is render-ready. */
-export interface DetailData {
+export interface DetailData extends ChromeData {
   notFound: boolean
   // Native routes now branch with `{notFound ? <NotFound/> : <Content/>}` (S11),
   // so the content and 404 block are mutually exclusive at render time rather
   // than both emitted with one hidden via a precomputed class.
-  pageTitle: string // dynamic <title> via `<BrustPage title={d.pageTitle}>` (S8)
+  // The dynamic <title> is `title` (ChromeData), read by AppLayout's
+  // <BrustPage title={title}> — no separate pageTitle field.
   name: string
   // present only when notFound === false:
   id: number
@@ -99,7 +112,6 @@ export interface DetailData {
   // object literals). addProps is the loader-precomputed JSON string handed to
   // <AddToTeamButton data={addProps} /> → x-props (Spec B native directives).
   addProps: string
-  teamProps: { teamInitial: TeamMember[] }
 }
 
 /** Shape of the AddToTeamButton native behavior's `props` (JSON-parsed from
@@ -129,9 +141,8 @@ export interface TypeChartRowVM {
   cells: TypeChartCellVM[] // 19 cells (1 head + 18)
 }
 
-export interface TypeChartData {
+export interface TypeChartData extends ChromeData {
   rows: TypeChartRowVM[] // 19 rows (1 header + 18), each 19 cells
-  teamProps: { teamInitial: TeamMember[] }
 }
 
 /** In-process team store member. */

package/example/pokedex/pages/DetailPage.tsx

@@ -1,5 +1,7 @@
-// Route "/pokemon/{name}" — NATIVE detail page. Per the decision to push native
-// as far as possible, the evolution chain is loaded BLOCKING in the loader (a
+// Route "/pokemon/{name}" — NATIVE detail leaf route, rendered into AppLayout's
+// <Outlet/> slot (chrome lives in AppLayout). Returns JUST its inner aa-content
+// fragment — no <BrustPage>, no <main>. Per the decision to push native as far
+// as possible, the evolution chain is loaded BLOCKING in the loader (a
 // native/jinja route has no React tree, so <Suspense> streaming is impossible —
 // see ../FRAMEWORK-GAPS.md S3).
 //
@@ -7,15 +9,14 @@
 // `{notFound ? <NotFound/> : <Content/>}` branch, `{hasAbilities && …}` /
 // `{hasEvolution && …}` sections, and per-item `{!s.isFirst && <Arrow/>}` /
 // `{s.showLevel && <Level/>}` separators — no more loader-computed hide-classes.
-// The <title> is dynamic via `<BrustPage title={pageTitle}>` (S8) and inline
-// styles use `style={{…}}` objects (S1).
+// The <title> is dynamic via AppLayout's `<BrustPage title={title}>` (S8, the
+// loader merges `title` into the shared context) and inline styles use
+// `style={{…}}` objects (S1).
 import AddToTeamButton from '../components/AddToTeamButton'
-import PageLayout from '../components/PageLayout'
 import type { DetailData } from '../lib/types'
 
 export default function DetailPage({
   notFound,
-  pageTitle,
   hasAbilities,
   hasEvolution,
   displayName,
@@ -33,10 +34,9 @@ export default function DetailPage({
   abilities,
   evolution,
   addProps,
-  teamProps,
 }: DetailData) {
   return (
-    <PageLayout native title={pageTitle} active="list" crumb={displayName} teamProps={teamProps}>
+    <>
       <a className="aa-btn aa-btn--ghost aa-btn--sm dex-back" href="/">
         ‹ Pokédex
       </a>
@@ -161,6 +161,6 @@ export default function DetailPage({
           )}
         </>
       )}
-    </PageLayout>
+    </>
   )
 }

package/example/pokedex/pages/ListPage.tsx

@@ -1,12 +1,12 @@
-// Route "/" — the Pokédex list. NATIVE route: this whole tree is compiled to a
-// minijinja template and rendered in Rust (no React on the server). The only
-// non-host tags are <BrustPage> (the document shell) and <Island> (the floating
-// team dock) — both intercepted by the compiler.
+// Route "/" — the Pokédex list. NATIVE leaf route: compiled to a minijinja
+// template and rendered into AppLayout's <Outlet/> slot (chrome lives in
+// AppLayout, nested as the parent in routes.tsx). The page therefore returns
+// JUST its inner aa-content fragment — no <BrustPage>, no <main>: AppLayout owns
+// the document shell and the single <main>.
 //
 // Native route components support `.map()` AND conditionals (S11): pagination
 // "disabled" state is a real `{hasPrev ? <a/> : <span/>}` branch, not a
 // precomputed hide-class. See ../FRAMEWORK-GAPS.md S11.
-import PageLayout from '../components/PageLayout'
 import type { ListData } from '../lib/types'
 
 export default function ListPage({
@@ -19,16 +19,9 @@ export default function ListPage({
   hasNext,
   prevHref,
   nextHref,
-  teamProps,
 }: ListData) {
   return (
-    <PageLayout
-      native
-      title="PokéDex · brust example"
-      active="list"
-      crumb="All Pokémon"
-      teamProps={teamProps}
-    >
+    <>
       <div className="aa-page-header">
         <div>
           <h1 className="aa-page-header__title">Pokédex</h1>
@@ -78,6 +71,6 @@ export default function ListPage({
           )}
         </div>
       </div>
-    </PageLayout>
+    </>
   )
 }

package/example/pokedex/pages/TypeChart.tsx

@@ -1,19 +1,14 @@
-// Route "/type-chart" — NATIVE route. A static 18×18 type-effectiveness matrix:
-// pure read-only data, the ideal native page (compiled to jinja, rendered in
-// Rust, zero React on the server). The 19×19 grid uses nested `.map()` on the
-// native path: rows.map(r => r.cells.map(c => …)) into a CSS grid.
-import PageLayout from '../components/PageLayout'
+// Route "/type-chart" — NATIVE leaf route, rendered into AppLayout's <Outlet/>
+// slot (chrome lives in AppLayout). Returns JUST its inner aa-content fragment.
+// A static 18×18 type-effectiveness matrix: pure read-only data, the ideal
+// native page (compiled to jinja, rendered in Rust, zero React on the server).
+// The 19×19 grid uses nested `.map()` on the native path: rows.map(r =>
+// r.cells.map(c => …)) into a CSS grid.
 import type { TypeChartData } from '../lib/types'
 
-export default function TypeChart({ rows, teamProps }: TypeChartData) {
+export default function TypeChart({ rows }: TypeChartData) {
   return (
-    <PageLayout
-      native
-      title="PokéDex · type chart"
-      active="typechart"
-      crumb="Type chart"
-      teamProps={teamProps}
-    >
+    <>
       <div className="aa-page-header">
         <div>
           <h1 className="aa-page-header__title">Type chart</h1>
@@ -49,6 +44,6 @@ export default function TypeChart({ rows, teamProps }: TypeChartData) {
           ))}
         </div>
       </div>
-    </PageLayout>
+    </>
   )
 }

package/example/pokedex/routes.tsx

@@ -1,4 +1,5 @@
 import { defineRoutes } from 'brustjs/routes'
+import AppLayout from './components/AppLayout'
 import { detailLoader, listLoader, typeChartLoader } from './lib/loaders'
 import DetailPage from './pages/DetailPage'
 import ListPage from './pages/ListPage'
@@ -9,13 +10,27 @@ import TypeChart from './pages/TypeChart'
 // runs in a Bun worker and its return value becomes the template scope. The only
 // React that ever boots in the browser is the islands (TeamBuilder /
 // AddToTeamButton). See ./FRAMEWORK-GAPS.md for what this costs.
+//
+// ROUTER-LEVEL LAYOUT (Approach a): the chrome (sidebar / topbar / team-dock) is
+// written ONCE in AppLayout, nested as the parent of the three leaf routes. Each
+// leaf renders into AppLayout's <Outlet/> slot. The compiler builds the synth
+// wrapper `<AppLayout native><Leaf native/></AppLayout>` per leaf and runs the
+// chain loaders top-down, shallow-merging into one flat jinja context. The leaf
+// loaders therefore also return the chrome fields (title/active/crumb/teamProps)
+// that AppLayout reads — see lib/loaders.ts and components/AppLayout.tsx.
 export const routes = defineRoutes([
-  // List + pagination (query string via req.search, validated by hand in the loader).
-  { path: '/', Component: ListPage, native: true, loader: listLoader },
+  {
+    Component: AppLayout,
+    native: true,
+    children: [
+      // List + pagination (query string via req.search, validated by hand in the loader).
+      { path: '/', Component: ListPage, native: true, loader: listLoader },
 
-  // Dynamic param {name} + a (non-streamed) evolution chain loaded in the loader.
-  { path: '/pokemon/{name}', Component: DetailPage, native: true, loader: detailLoader },
+      // Dynamic param {name} + a (non-streamed) evolution chain loaded in the loader.
+      { path: '/pokemon/{name}', Component: DetailPage, native: true, loader: detailLoader },
 
-  // Static 18×18 effectiveness matrix — the ideal native page.
-  { path: '/type-chart', Component: TypeChart, native: true, loader: typeChartLoader },
+      // Static 18×18 effectiveness matrix — the ideal native page.
+      { path: '/type-chart', Component: TypeChart, native: true, loader: typeChartLoader },
+    ],
+  },
 ])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.23-alpha",
+  "version": "0.1.24-alpha",
   "description": "Bun + Rust SSR framework — React on the server, Rust everywhere else (napi cdylib + per-worker SharedArrayBuffer).",
   "license": "MIT",
   "repository": {
@@ -40,12 +40,12 @@
     "typescript": "^6.0.3"
   },
   "optionalDependencies": {
-    "brustjs-darwin-x64": "0.1.23-alpha",
-    "brustjs-darwin-arm64": "0.1.23-alpha",
-    "brustjs-linux-x64-gnu": "0.1.23-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.23-alpha",
-    "brustjs-linux-x64-musl": "0.1.23-alpha",
-    "brustjs-linux-arm64-musl": "0.1.23-alpha"
+    "brustjs-darwin-x64": "0.1.24-alpha",
+    "brustjs-darwin-arm64": "0.1.24-alpha",
+    "brustjs-linux-x64-gnu": "0.1.24-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.24-alpha",
+    "brustjs-linux-x64-musl": "0.1.24-alpha",
+    "brustjs-linux-arm64-musl": "0.1.24-alpha"
   },
   "peerDependencies": {
     "react": "^19.2.6",

package/runtime/action-error.ts

@@ -0,0 +1,31 @@
+// Typed domain error for treaty actions. `throw new ActionError(status, code, { data })`
+// from a handler (or nested business logic) → dispatchAction maps it to an HTTP
+// non-2xx with a flat body `{ code, message, data }`. Branded with Symbol.for so the
+// guard survives the class being duplicated across bundles (user code → framework).
+const ACTION_ERROR: unique symbol = Symbol.for('brust.actionError')
+
+export interface ActionErrorBody {
+  code: string
+  message: string
+  data?: unknown
+}
+
+export class ActionError extends Error {
+  readonly [ACTION_ERROR] = true as const
+  readonly status: number
+  readonly code: string
+  readonly data?: unknown
+  constructor(status: number, code: string, opts?: { message?: string; data?: unknown }) {
+    super(opts?.message ?? code)
+    this.name = 'ActionError'
+    this.status = status
+    this.code = code
+    this.data = opts?.data
+  }
+}
+
+export function isActionError(v: unknown): v is ActionError {
+  return (
+    typeof v === 'object' && v !== null && (v as Record<symbol, unknown>)[ACTION_ERROR] === true
+  )
+}

package/runtime/cli/build.ts

@@ -328,7 +328,10 @@ export async function runBuild(args: string[]): Promise<void> {
     // an empty importMap (no native routes to emit anyway).
     await emitNativeTemplates({
       entryFile: existsSync(routesFile) ? routesFile : entry,
-      flatRoutes: (loadedRoutes ?? []) as { nativeTemplate?: string }[],
+      flatRoutes: (loadedRoutes ?? []) as {
+        nativeTemplate?: string
+        chain?: Array<{ Component?: { name?: string } }>
+      }[],
       outDir: jinjaDir,
       repoRoot: REPO_ROOT,
     })

package/runtime/cli/dev.ts

@@ -82,7 +82,10 @@ export async function runDev(args: string[]): Promise<void> {
   const jinjaDir = path.join(process.cwd(), '.brust/jinja')
   const emitOpts = {
     entryFile: existsSync(routesFile) ? routesFile : entry,
-    flatRoutes: loadedRoutes as { nativeTemplate?: string }[],
+    flatRoutes: loadedRoutes as {
+      nativeTemplate?: string
+      chain?: Array<{ Component?: { name?: string } }>
+    }[],
     outDir: jinjaDir,
     repoRoot: REPO_ROOT,
   }