brustjs 0.1.20-alpha → 0.1.22-alpha

package/README.md

@@ -87,6 +87,17 @@ brustjs new   <name>              # scaffold a project (partial — see Status)
   `renderToString` runs once per key, then serves a frozen pair from Rust.
 - **`native: true` routes** — JSX compiled to a jinja template at build time and
   rendered Rust-side (`minijinja`), skipping React on the server entirely.
+- **Native interactivity without islands** — Alpine.js-style `x-*` DOM directives
+  (`x-data`/`x-text`/`x-show`/`x-bind-*`/`x-on-*`/`x-for`) on a `native` page,
+  bound to the store by a small react-free runtime. Logic lives in a co-located
+  `export const behavior` (single-file component); each component's JS is a
+  separate chunk loaded **on demand** — a page never downloads a component it
+  doesn't render.
+- **Isomorphic store** — `brustjs/store`: `signal`/`computed`/`effect` +
+  `defineStore(name, factory)`. One `window` singleton per name on the client (so
+  separate island/directive chunks share state), a per-request `AsyncLocalStorage`
+  instance on the server. `useStore` adapter for React islands; a native directive
+  button and a React island reactively share the same store.
 - **Typed actions** — `defineActions().get/post/put/patch/delete/head(path, ctx => R, { body, query })`
   on the server; `client<typeof actions>()` is an Eden-Treaty-style proxy that
   infers the whole API from the server types (no codegen) and returns
@@ -119,7 +130,7 @@ bun test tests/integration.test.ts   # integration (real server)
 ```
 crates/brust/             Rust: accept loop, worker pool, napi exports, SAB
 crates/jsx-rust-compiler/ JSX → jinja compiler for native: true routes
-runtime/                  Bun-side: routing, render, actions, CLI
+runtime/                  Bun-side: routing, render, actions, store, native directives, CLI
 example/                  pokedex native-first demo
 bench/ · docs/ · architecture.md
 ```

package/example/pokedex/components/AddToTeamButton.tsx

@@ -1,93 +1,87 @@
-// ISLAND — the "Add to team / In your team" toggle on the detail page.
+// NATIVE INTERACTIVE COMPONENT (Spec B dogfood) — the "Add to team / In your
+// team" toggle on the detail page. Formerly a React island; now a single-file
+// native directive component: a co-located `export const behavior` (client
+// logic, react-free) + a JSX `default` export (the native template the compiler
+// lowers to minijinja). The build bundles ONLY `behavior` into _directives.js;
+// the JSX default is tree-shaken out so react never leaks into the client bundle.
 //
-// Islands run REAL React in the browser (and, when `ssr`, in a Bun worker too),
-// so unlike the native page shells they have NO jinja constraints: hooks, inline
-// `style={{…}}`, event handlers all work normally.
-import { useEffect, useState } from 'react'
+// 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 { client } from 'brustjs/client'
+import { computed, signal } from 'brustjs/store'
 import type { Actions } from '../actions'
-import type { AddToTeamProps, TeamMember } from '../lib/types'
-import { emitTeam, onTeam } from './team-bus'
+import type { AddToTeamProps } from '../lib/types'
+import { teamStore } from '../stores/team'
 
 const api = client<Actions>()
 
-export default function AddToTeamButton(p: AddToTeamProps) {
-  const [team, setTeam] = useState<TeamMember[]>([])
-  const [busy, setBusy] = useState(false)
-  const [toast, setToast] = useState<string | null>(null)
-
-  useEffect(() => {
-    api.team.get().then((r) => {
-      if (r.data) setTeam(r.data.team)
-    })
-    return onTeam(setTeam)
-  }, [])
+// behavior → client bundle, registered as "addToTeamButton" (camelCase filename).
+// `props` is the JSON parsed out of the element's x-props attribute (precomputed
+// by the loader as a JSON string — native templates can't call JSON.stringify).
+export const behavior = ({ props }: { props: AddToTeamProps }) => {
+  // Shared store (GAP S4): writing teamStore.members here is observed by the
+  // 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 inTeam = computed(() => (teamStore.members() ?? []).some((m) => m.id === props.id))
+  const label = computed(() =>
+    inTeam() ? '✓ In your team' : disabled() ? '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()))
 
-  const inTeam = team.some((m) => m.id === p.id)
+  async function init() {
+    const r = await api.team.get()
+    if (r.data) teamStore.members.set(r.data.team)
+  }
 
   async function toggle() {
-    setBusy(true)
+    busy.set(true)
     try {
-      if (inTeam) {
-        // NOTE: `.delete({})` — passing an empty body is REQUIRED. A bodyless
-        // DELETE from the browser sends no Content-Length, and brust's action
-        // dispatch returns 411 on non-GET/HEAD without one. See GAPS S12.
-        const { data } = await api.team({ id: p.id }).delete({})
-        if (data) emitTeam(data.team)
+      if (inTeam()) {
+        // Bodyless DELETE is OK now (GAPS S12 fixed) — no more `.delete({})`.
+        const { data } = await api.team({ id: props.id }).delete()
+        if (data) teamStore.members.set(data.team)
       } else {
         const { data } = await api.team.post({
-          id: p.id,
-          name: p.name,
-          displayName: p.displayName,
-          num: p.num,
-          types: p.types,
-          artwork: p.artwork,
+          id: props.id,
+          name: props.name,
+          displayName: props.displayName,
+          num: props.num,
+          types: props.types,
+          artwork: props.artwork,
         })
-        if (data?.full) {
-          setToast('ทีมเต็มแล้ว · สูงสุด 6 ตัว')
-          setTimeout(() => setToast(null), 2200)
-        } else if (data) {
-          emitTeam(data.team)
+        if (data && !data?.full) {
+          teamStore.members.set(data.team)
         }
       }
     } finally {
-      setBusy(false)
+      busy.set(false)
     }
   }
 
+  return { init, label, btnClass, toggle, disabled }
+}
+
+// default → jinja (server). The x-* directives are static string attributes the
+// native compiler passes straight through; the directive runtime binds them to
+// the behavior instance on the client. `data` is the loader-precomputed JSON
+// string, emitted by the compiler as x-props="{{ (data) | e }}" (XSS-safe).
+export default function AddToTeamButton({ data }: { data: string }) {
   return (
-    <div style={{ position: 'relative' }}>
+    <div x-data="addToTeamButton" x-props={data} style={{ position: 'relative' }}>
       <button
         type="button"
-        className={`aa-btn aa-btn--full${inTeam ? ' aa-btn--secondary' : ''}`}
+        x-text="label"
+        x-bind-class="btnClass"
+        x-bind-disabled="disabled"
+        x-on-click="toggle"
+        className="aa-btn aa-btn--full"
         style={{ width: '100%' }}
-        onClick={toggle}
-        disabled={busy}
       >
-        {inTeam ? '✓ In your team' : '＋ Add to team'}
+        ＋ Add to team
       </button>
-      {toast && (
-        <div
-          style={{
-            position: 'absolute',
-            top: 'calc(100% + 8px)',
-            left: 0,
-            right: 0,
-            zIndex: 50,
-            padding: '8px 12px',
-            borderRadius: 'var(--radius-md)',
-            background: 'var(--danger-50)',
-            color: 'var(--danger-700)',
-            border: '1px solid rgba(212,28,89,0.25)',
-            fontSize: 'var(--text-xs)',
-            fontWeight: 600,
-            textAlign: 'center',
-            boxShadow: 'var(--shadow-md)',
-          }}
-        >
-          {toast}
-        </div>
-      )}
     </div>
   )
 }

package/example/pokedex/components/TeamBuilder.tsx

@@ -2,33 +2,43 @@
 //
 // Rendered with `ssr` so the initial team (from the loader) ships in the HTML
 // and the dock count is correct on first paint, then hydrates. Stays in sync
-// with AddToTeamButton through the window-event bus (see team-bus.ts / GAPS S4).
+// with AddToTeamButton through the shared `teamStore` (one window singleton — see
+// ../stores/team.ts / GAPS S4; replaced the old window-event bus).
 import { useEffect, useState } from 'react'
-import { client } from 'brustjs/client'
+import { client, useStore } from 'brustjs/client'
 import type { Actions } from '../actions'
 import type { TeamMember } from '../lib/types'
-import { emitTeam, onTeam } from './team-bus'
+import { teamStore } from '../stores/team'
 
 const api = client<Actions>()
 const MAX = 6
 
 export default function TeamBuilder({ teamInitial }: { teamInitial: TeamMember[] }) {
-  const [team, setTeam] = useState<TeamMember[]>(teamInitial ?? [])
+  // Shared store (GAP S4): in sync with AddToTeamButton via one window singleton.
+  const { members } = useStore(teamStore)
+  const [mounted, setMounted] = useState(false)
   const [open, setOpen] = useState(false)
 
+  // This island is `ssr`, but Spec A does not server-seed native client state, so
+  // the store is empty during SSR. Drive the first render (server + client) from
+  // the `teamInitial` prop so the dock count is correct on first paint AND the
+  // hydration markup matches; switch to the live store once mounted. (Full
+  // server-seeded native snapshot is Spec B.)
+  const team = mounted ? (members ?? []) : (teamInitial ?? [])
+
   useEffect(() => {
-    // Re-sync from the server on mount (the SSR snapshot may be stale by now),
-    // then subscribe to mutations from the other island.
+    if (teamInitial?.length) teamStore.members.set(teamInitial)
+    setMounted(true)
+    // Re-sync from the server on mount (the SSR snapshot may be stale by now).
     api.team.get().then((r) => {
-      if (r.data) setTeam(r.data.team)
+      if (r.data) teamStore.members.set(r.data.team)
     })
-    return onTeam(setTeam)
-  }, [])
+  }, [teamInitial])
 
   async function remove(id: number) {
     // `.delete({})` — empty body is required (bodyless DELETE → 411). See GAPS S12.
     const { data } = await api.team({ id }).delete({})
-    if (data) emitTeam(data.team)
+    if (data) teamStore.members.set(data.team)
   }
 
   const coverage = [...new Set(team.flatMap((m) => m.types))]

package/example/pokedex/lib/loaders.ts

@@ -163,14 +163,17 @@ export async function detailLoader({ params }: LoaderCtx): Promise<DetailData |
     hasAbilities: abilities.length > 0,
     evolution,
     hasEvolution,
-    addProps: {
+    // Native templates can't call JSON.stringify, so precompute the x-props JSON
+    // here. The compiler emits it as x-props="{{ (addProps) | e }}" (XSS-safe);
+    // the directive runtime JSON.parses it back into the behavior's `props`.
+    addProps: JSON.stringify({
       id: p.id,
       name: p.name,
       displayName: cap(p.name),
       num: pad(p.id),
       types: p.types,
       artwork: p.artwork,
-    },
+    }),
     teamProps: { teamInitial: teamStore.list() },
   }
 }
@@ -197,7 +200,14 @@ function emptyDetail(name: string): DetailData {
     hasAbilities: false,
     evolution: [],
     hasEvolution: false,
-    addProps: { id: 0, name, displayName: cap(name), num: '', types: [], artwork: '' },
+    addProps: JSON.stringify({
+      id: 0,
+      name,
+      displayName: cap(name),
+      num: '',
+      types: [],
+      artwork: '',
+    }),
     teamProps: { teamInitial: teamStore.list() },
   }
 }

package/example/pokedex/lib/types.ts

@@ -95,12 +95,15 @@ export interface DetailData {
   hasAbilities: boolean
   evolution: EvolutionStageVM[]
   hasEvolution: boolean
-  // island props (a single path each — native island props can't be object literals):
-  addProps: AddToTeamProps
+  // native interactive props: a single string path each (native props can't be
+  // 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[] }
 }
 
-/** Props for the AddToTeamButton island (raw types kept for the action body). */
+/** Shape of the AddToTeamButton native behavior's `props` (JSON-parsed from
+ *  x-props). Matches the action body fields so toggle() can post it directly. */
 export interface AddToTeamProps {
   id: number
   name: string

package/example/pokedex/pages/DetailPage.tsx

@@ -9,7 +9,6 @@
 // `{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).
-import { Island } from 'brustjs'
 import AddToTeamButton from '../components/AddToTeamButton'
 import PageLayout from '../components/PageLayout'
 import type { DetailData } from '../lib/types'
@@ -71,7 +70,7 @@ export default function DetailPage({
                   </span>
                 ))}
               </div>
-              <Island component={AddToTeamButton} props={addProps} hydrate="load" />
+              <AddToTeamButton native data={addProps} />
             </div>
 
             <div className="dex-detail-right">

package/example/pokedex/stores/team.ts

@@ -0,0 +1,14 @@
+// Shared team store — GAP S4 dogfood.
+//
+// AddToTeamButton and TeamBuilder are two SEPARATE island bundles. A plain
+// module-scope store imported by both would be duplicated into two instances
+// that never sync. `defineStore` resolves both bundles to ONE instance on
+// `window.__BRUST_STORES__['pokedex.team']`, so a write in one island is seen by
+// the other — no hand-rolled CustomEvent bus. (Replaces the old components/team-bus.ts.)
+import { defineStore, signal } from 'brustjs/store'
+import type { TeamMember } from '../lib/types'
+
+export const teamStore = defineStore('pokedex.team', () => {
+  const members = signal<TeamMember[]>([])
+  return { members }
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.20-alpha",
+  "version": "0.1.22-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.20-alpha",
-    "brustjs-darwin-arm64": "0.1.20-alpha",
-    "brustjs-linux-x64-gnu": "0.1.20-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.20-alpha",
-    "brustjs-linux-x64-musl": "0.1.20-alpha",
-    "brustjs-linux-arm64-musl": "0.1.20-alpha"
+    "brustjs-darwin-x64": "0.1.22-alpha",
+    "brustjs-darwin-arm64": "0.1.22-alpha",
+    "brustjs-linux-x64-gnu": "0.1.22-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.22-alpha",
+    "brustjs-linux-x64-musl": "0.1.22-alpha",
+    "brustjs-linux-arm64-musl": "0.1.22-alpha"
   },
   "peerDependencies": {
     "react": "^19.2.6",
@@ -67,7 +67,9 @@
     ".": "./runtime/index.ts",
     "./routes": "./runtime/routes.ts",
     "./client": "./runtime/client/index.ts",
-    "./create": "./runtime/create.ts"
+    "./create": "./runtime/create.ts",
+    "./store": "./runtime/store/index.ts",
+    "./native": "./runtime/native/index.ts"
   },
   "files": [
     "runtime",

package/runtime/cli/build.ts

@@ -248,6 +248,47 @@ export async function runBuild(args: string[]): Promise<void> {
     console.log('[brust build] islands: skipped (no <Island> usage)')
   }
 
+  // 3.5. Build the directive runtime bundle (if any native interactive component —
+  // a file with `export const behavior` — is reachable from the routes graph).
+  // MUST run AFTER buildIslands: buildIslands does `rm -rf outDir/islands`, so
+  // running this first would wipe _directives.js. This block creates the islands
+  // dir itself (the islands block is skipped when there are no <Island> usages).
+  {
+    const { scanDirectiveComponents, buildDirectives } = await import('../native/build.ts')
+    let directiveComponents = new Map<string, string>()
+    if (existsSync(routesFile)) {
+      try {
+        directiveComponents = scanDirectiveComponents(routesFile)
+      } catch (err) {
+        // e.g. two files derive the same directive register name — surface a clean
+        // message instead of an unformatted stack out of `brust build`.
+        console.error(`[brust build] directives: ${(err as Error).message}`)
+        process.exit(1)
+      }
+    }
+    if (directiveComponents.size > 0) {
+      const islandsOutDir = path.join(outDir, 'islands')
+      const result = await buildDirectives(directiveComponents, { outDir: islandsOutDir })
+      console.log(
+        `[brust build] directives: runtime + ${result.count} component chunk(s) → ${islandsOutDir}`,
+      )
+
+      // Mirror every directive file (_directives.js + each <name>.directive.js) into
+      // cwd/.brust/islands for the source runtime (the islands block's whole-dir mirror
+      // ran before these existed, so copy them explicitly). Create the dir in case the
+      // islands block was skipped.
+      const localIslandsDir = path.join(process.cwd(), '.brust', 'islands')
+      if (path.resolve(localIslandsDir) !== path.resolve(islandsOutDir)) {
+        await mkdir(localIslandsDir, { recursive: true })
+        for (const f of result.files) {
+          await cp(path.join(islandsOutDir, f), path.join(localIslandsDir, f))
+        }
+      }
+    } else {
+      console.log('[brust build] directives: skipped (no export-const-behavior components)')
+    }
+  }
+
   // 4. MCP manifest (if routes.tsx exists).
   let loadedRoutes: any[] | undefined
   if (existsSync(routesFile)) {

package/runtime/cli/native-routes-emit.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { buildDevClientTag } from '../dev/client.ts'
-import { ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
+import { DIRECTIVES_BOOTSTRAP, ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
 
 /** Gather transitive component sources starting from a page source file.
  *
@@ -104,6 +104,20 @@ function injectDevClientIntoTemplate(template: string): string {
   return template + tag
 }
 
+/** Bake the directive runtime loader into a native template iff it uses any
+ * x-data directive. Idempotent. Wrapped in {% raw %} for symmetry with the islands
+ * bootstrap bake (the tag has no {{ }} but the wrap is harmless + consistent). */
+export function bakeDirectivesIfUsed(template: string, force = false): string {
+  // `force` (app has ≥1 directive component) bakes on EVERY native page so the
+  // runtime is live to catch SPA-nav swaps into a directive page. Otherwise
+  // attribute-anchored (`x-data=`) so a literal "x-data" in text/content can't
+  // trigger a stray <script> that would 404 (no bundle built for that route).
+  if (!force && !/x-data=/.test(template)) return template
+  const baked = `{% raw %}${DIRECTIVES_BOOTSTRAP}{% endraw %}`
+  if (template.includes(baked)) return template
+  return template + baked
+}
+
 /** Sub-project J — build pass that turns user's `pages/<Name>.tsx` files into
  * `.brust/jinja/<Name>.jinja` templates. Invoked from `brust build` and
  * `brust dev` after the user's routes are flattened.
@@ -327,6 +341,17 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
   const importMap =
     nativeRoutes.length > 0 ? scanImports(opts.entryFile) : new Map<string, string>()
 
+  // App-wide directive presence: if ANY native interactive component exists, the
+  // directive runtime (`_directives.js`) must load on EVERY native page — not just
+  // pages whose own template uses x-data. SPA nav (owned by the islands bootstrap)
+  // swaps <main> but does NOT execute <script> tags in the swapped HTML, so the
+  // runtime must already be live on the page you navigate FROM for its
+  // MutationObserver to mount the incoming x-data. Dynamic import = call-time
+  // (avoids a module-eval cycle with native/build.ts → scanImports here).
+  const hasDirectives =
+    nativeRoutes.length > 0 &&
+    (await import('../native/build.ts')).scanDirectiveComponents(opts.entryFile).size > 0
+
   const built: string[] = []
   for (const r of nativeRoutes) {
     const name = r.nativeTemplate!
@@ -357,10 +382,9 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
     // Dev-only: native routes don't pass through the React renderer's dev-client
     // injection, so splice the /_brust/dev WS script in here. reEmitJinja() runs
     // this on every hot reload, so the script is always present in dev.
+    const withDirectives = bakeDirectivesIfUsed(compiled.template, hasDirectives)
     const template =
-      process.env.BRUST_DEV === '1'
-        ? injectDevClientIntoTemplate(compiled.template)
-        : compiled.template
+      process.env.BRUST_DEV === '1' ? injectDevClientIntoTemplate(withDirectives) : withDirectives
     writeFileSync(outPath, template)
     built.push(name)
 

package/runtime/client/index.ts

@@ -20,3 +20,9 @@ export class BrustActionError extends Error {
 
 export { client } from '../treaty.ts'
 export type { TreatyResponse, ClientOptions } from '../treaty.ts'
+
+// Store view-layer adapter for islands. Lives here (the browser/island entry),
+// NOT in the brustjs main entry — that pulls the native addon + server-only
+// surface and cannot be bundled for the browser. react.ts → define-store.ts is
+// browser-safe (no node:async_hooks; the server resolver is injected separately).
+export { useStore } from '../store/react.ts'