brustjs 0.1.45-alpha → 0.1.47-alpha

package/runtime/islands/build.ts

@@ -201,7 +201,7 @@ export async function buildIslands(
   return { outDir, islandCount: count, chunks }
 }
 
-async function buildOne(
+export async function buildOne(
   entrypoints: string[],
   outdir: string,
   naming: string,

package/runtime/islands/fallback.ts

@@ -0,0 +1,198 @@
+// runtime/islands/fallback.ts — client takeover runtime for `fallback: 'client'`
+// SSG routes (Phase B of the ssg-dynamic-params design). A non-prerendered
+// dynamic path serves a placeholder shell whose leaf is
+// `<div data-brust-fallback-root data-brust-fallback="<pattern>">…</div>`;
+// this module matches the pattern against the live pathname, loads the
+// route's fallback chunk (`Component` + `clientLoader`), and client-renders
+// the real page into the container.
+//
+// Imported BY bootstrap.ts (Task B6): react / react-dom/client are static
+// imports on purpose — bootstrap bundles them as externals resolved via the
+// importmap, and this module rides the same bundle. Import-safe without a
+// DOM: nothing touches document/location at module top level.
+
+import { createElement } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+
+export interface FallbackEntry {
+  pattern: string
+  doc: string
+  payload: string
+  chunk: string
+}
+
+// React roots created by takeover, keyed by their container, so navigation
+// can unmount them before replacing the DOM (a detached live root keeps
+// React's scheduler posting work to dead nodes — hung tab). Same discipline
+// as bootstrap's islandRoots.
+const fallbackRoots = new WeakMap<HTMLElement, Root>()
+
+/** Match a route pattern (`/blog/{slug}`) against a concrete pathname.
+ * Segment-wise: lengths must agree, `{name}` segments capture one
+ * decodeURIComponent-decoded segment (malformed percent-encoding falls back
+ * to the raw segment; an EMPTY segment never matches a capture), everything
+ * else must compare literally. Returns the captured params, or null. */
+export function matchFallback(pattern: string, pathname: string): Record<string, string> | null {
+  const pat = pattern.split('/')
+  // Route-table patterns never carry a trailing slash; static hosts (CF Pages
+  // directory rewrites among them) may append one to the live pathname —
+  // normalize so '/blog/foo/' still matches '/blog/{slug}'.
+  const normalized = pathname.length > 1 ? pathname.replace(/\/+$/, '') : pathname
+  const path = normalized.split('/')
+  if (pat.length !== path.length) return null
+  const params: Record<string, string> = {}
+  for (let i = 0; i < pat.length; i++) {
+    const p = pat[i] as string
+    const seg = path[i] as string
+    if (p.startsWith('{') && p.endsWith('}') && p.length > 2) {
+      if (seg === '') return null // empty capture → no match
+      let value: string
+      try {
+        value = decodeURIComponent(seg)
+      } catch {
+        value = seg // malformed percent-encoding → raw segment
+      }
+      params[p.slice(1, -1)] = value
+    } else if (p !== seg) {
+      return null
+    }
+  }
+  return params
+}
+
+let manifestPromise: Promise<FallbackEntry[]> | null = null
+
+function isFallbackEntry(e: unknown): e is FallbackEntry {
+  if (typeof e !== 'object' || e === null) return false
+  const r = e as Record<string, unknown>
+  return (
+    typeof r.pattern === 'string' && typeof r.payload === 'string' && typeof r.chunk === 'string'
+  )
+}
+
+/** Fetch the static-export fallback manifest (`/_brust/routes.json`).
+ * Memoized for the document's lifetime — including the EMPTY result: a site
+ * with no fallback routes (404 / invalid / no `fallbacks` array) resolves []
+ * once and never refetches per navigation. Entries missing a string
+ * pattern/payload/chunk are filtered out. */
+export function loadFallbackManifest(): Promise<FallbackEntry[]> {
+  if (!manifestPromise) {
+    manifestPromise = fetch('/_brust/routes.json')
+      .then(async (resp) => {
+        if (!resp.ok) return []
+        const json = (await resp.json()) as { fallbacks?: unknown }
+        if (!Array.isArray(json.fallbacks)) return []
+        return json.fallbacks.filter(isFallbackEntry)
+      })
+      .catch(() => [])
+  }
+  return manifestPromise
+}
+
+function takeoverError(container: HTMLElement, message: string, err?: unknown): void {
+  if (err === undefined) console.error(`[brust] fallback: ${message}`)
+  else console.error(`[brust] fallback: ${message}`, err)
+  container.setAttribute('data-brust-fallback-error', '1')
+}
+
+/** Client-render a fallback route into its placeholder container.
+ *
+ * Reads the route pattern from `data-brust-fallback`, derives params from
+ * `location.pathname`, dynamic-imports the route's fallback chunk from the
+ * manifest, runs `clientLoader({ params, path })`, then replaces the
+ * placeholder children with `createRoot(container).render(<Component
+ * params path data />)` — the server prop shape minus `req`/`workerId`
+ * (those don't exist in a browser).
+ *
+ * On any failure (mismatched pattern, missing manifest entry, bad chunk,
+ * clientLoader throw) the container KEEPS its placeholder, gets a
+ * `data-brust-fallback-error` attribute, and the error is logged —
+ * author-level recovery is a catch inside clientLoader returning
+ * error-shaped data.
+ *
+ * CONTRACT: the caller must unmount any island roots inside the container
+ * FIRST (a placeholder may carry islands) — bootstrap's unmountIslandsIn
+ * does this before calling takeover. The call lives there, not here, to
+ * avoid a circular import between fallback.ts and bootstrap.ts.
+ *
+ * `signal`: a superseding navigation aborts it. Checked after every await and
+ * BEFORE createRoot — without that gate, a takeover resumed after the next
+ * navigation's swap would mount a React root into a DETACHED container that
+ * unmountFallbackRootsIn can never find again (hung-tab hazard). */
+export async function takeover(container: HTMLElement, signal?: AbortSignal): Promise<void> {
+  const pattern = container.getAttribute('data-brust-fallback')
+  if (pattern === null) {
+    console.error('[brust] fallback: container has no data-brust-fallback attribute')
+    return
+  }
+  const path = location.pathname
+  const params = matchFallback(pattern, path)
+  if (params === null) {
+    takeoverError(container, `pattern "${pattern}" does not match pathname "${path}"`)
+    return
+  }
+  const manifest = await loadFallbackManifest()
+  const entry = manifest.find((e) => e.pattern === pattern)
+  if (!entry) {
+    takeoverError(container, `no manifest entry for pattern "${pattern}"`)
+    return
+  }
+  let Component: React.ComponentType<Record<string, unknown>>
+  let clientLoader: (args: { params: Record<string, string>; path: string }) => unknown
+  try {
+    // Variable specifier → stays a runtime dynamic import in the bundle
+    // (same trick as bootstrap's islandChunkMap).
+    const chunkUrl = entry.chunk
+    const mod = (await import(chunkUrl)) as Record<string, unknown>
+    if (typeof mod.Component !== 'function' || typeof mod.clientLoader !== 'function') {
+      takeoverError(container, `chunk "${entry.chunk}" must export Component and clientLoader`)
+      return
+    }
+    Component = mod.Component as React.ComponentType<Record<string, unknown>>
+    clientLoader = mod.clientLoader as typeof clientLoader
+  } catch (e) {
+    takeoverError(container, `failed to load chunk "${entry.chunk}"`, e)
+    return
+  }
+  if (signal?.aborted) return
+  let data: unknown
+  try {
+    data = await clientLoader({ params, path })
+  } catch (e) {
+    takeoverError(container, `clientLoader threw for "${pattern}"`, e)
+    return
+  }
+  // Superseded while the data was loading → the newer navigation owns the
+  // DOM; mounting here would render into a detached container.
+  if (signal?.aborted) return
+  // Success: drop the placeholder, then mount a fresh client root.
+  while (container.firstChild) container.removeChild(container.firstChild)
+  const root = createRoot(container)
+  root.render(createElement(Component, { params, path, data }))
+  fallbackRoots.set(container, root)
+}
+
+/** Unmount any takeover roots inside `scope`. Must run BEFORE removing or
+ * replacing their DOM (same reason as bootstrap's unmountIslandsIn, which
+ * delegates here in Task B6 — islandRoots and fallbackRoots stay
+ * module-private to their owners). */
+export function unmountFallbackRootsIn(scope: ParentNode): void {
+  const containers = scope.querySelectorAll<HTMLElement>('[data-brust-fallback-root]')
+  for (const el of Array.from(containers)) {
+    const root = fallbackRoots.get(el)
+    if (root) {
+      try {
+        root.unmount()
+      } catch (e) {
+        console.warn('[brust] fallback root unmount failed', e)
+      }
+      fallbackRoots.delete(el)
+    }
+  }
+}
+
+// Test-only: drop the memoized manifest so the next loadFallbackManifest
+// refetches. (fallbackRoots is a WeakMap — nothing to clear.)
+export function __resetFallbackForTest(): void {
+  manifestPromise = null
+}

package/runtime/islands/page-cache.ts

@@ -0,0 +1,108 @@
+// runtime/islands/page-cache.ts — in-memory cache for SPA navigation payloads
+// (/_brust/page/*) plus the fetch/dedupe machinery behind hover prefetch.
+// Browser-only at call time (fetch/navigator), but import-safe anywhere.
+//
+// Lifetime: one document load. A full reload (dev rebuild WS, full-document
+// fallback, hard refresh) drops the whole cache with the JS heap, so dev never
+// serves stale pages across rebuilds.
+
+export interface PagePayload {
+  html: string
+  title: string
+  store?: Record<string, Record<string, unknown>>
+}
+
+/** Bound the cache so a long session can't grow memory unbounded (LRU evict). */
+export const PAGE_CACHE_MAX = 64
+/** Forward navigations reuse an entry for this long; back/forward (popstate)
+ * passes Infinity and reuses any entry regardless of age (bfcache-like). */
+export const PAGE_STALE_MS = 5 * 60_000
+
+interface Entry {
+  payload: PagePayload
+  at: number
+}
+
+const cache = new Map<string, Entry>()
+const inflight = new Map<string, Promise<PagePayload>>()
+
+export function pageCacheKey(url: URL): string {
+  return url.pathname + url.search
+}
+
+export function getCachedPage(key: string, maxAgeMs: number = PAGE_STALE_MS): PagePayload | null {
+  const e = cache.get(key)
+  if (!e) return null
+  if (Date.now() - e.at > maxAgeMs) {
+    cache.delete(key)
+    return null
+  }
+  // LRU bump: Map iteration order is insertion order, so re-inserting moves
+  // this key to the "most recently used" end.
+  cache.delete(key)
+  cache.set(key, e)
+  return e.payload
+}
+
+export function setCachedPage(key: string, payload: PagePayload): void {
+  cache.delete(key)
+  cache.set(key, { payload, at: Date.now() })
+  if (cache.size > PAGE_CACHE_MAX) {
+    const oldest = cache.keys().next().value
+    if (oldest !== undefined) cache.delete(oldest)
+  }
+}
+
+/** Fetch a nav payload and cache it on success. Shared by navigate (direct,
+ * abortable) and prefetch (deduped, signal-less). */
+export async function fetchPagePayload(url: URL, signal?: AbortSignal): Promise<PagePayload> {
+  const resp = await fetch(`/_brust/page${url.pathname}${url.search}`, {
+    signal,
+    headers: { Accept: 'application/json' },
+  })
+  if (!resp.ok) throw new Error(`navigation: status ${resp.status}`)
+  const payload = (await resp.json()) as PagePayload
+  setCachedPage(pageCacheKey(url), payload)
+  return payload
+}
+
+/** @internal — the in-flight prefetch for `key`, if any. navigate() awaits it
+ * instead of double-fetching when a click lands mid-prefetch. */
+export function inflightPage(key: string): Promise<PagePayload> | undefined {
+  return inflight.get(key)
+}
+
+function prefetchAllowed(): boolean {
+  if (typeof navigator === 'undefined') return false
+  const conn = (navigator as { connection?: { saveData?: boolean; effectiveType?: string } })
+    .connection
+  if (conn?.saveData) return false
+  if (typeof conn?.effectiveType === 'string' && conn.effectiveType.includes('2g')) return false
+  return true
+}
+
+/** Speculatively load a page into the cache (hover/touch intent). No-op when
+ * already cached fresh or when the connection asks not to (Save-Data, 2g).
+ * Failures are silent — the eventual click just fetches normally. */
+export function prefetchPage(url: URL): Promise<void> {
+  if (!prefetchAllowed()) return Promise.resolve()
+  const key = pageCacheKey(url)
+  if (getCachedPage(key) !== null) return Promise.resolve()
+  let p = inflight.get(key)
+  if (!p) {
+    p = fetchPagePayload(url).finally(() => {
+      inflight.delete(key)
+    })
+    inflight.set(key, p)
+  }
+  return p.then(
+    () => undefined,
+    () => undefined,
+  )
+}
+
+// Test-only: drop all entries and in-flight markers.
+export function __resetPageCacheForTest(): void {
+  cache.clear()
+  inflight.clear()
+}

package/runtime/render/stream.ts

@@ -51,6 +51,10 @@ export interface RenderBranchStreamingArgs {
    * `<script data-brust-store="…">` blob before `</head>` (buffering) or into
    * the streaming first-chunk prepend. Null/undefined → no injection. */
   storeSnapshot?: Record<string, Record<string, unknown>> | null
+  /** Inject the islands importmap + bootstrap even when no <Island> rendered.
+   * SSG fallback shells need the bootstrap (client takeover runtime) on pages
+   * that may have zero real islands. */
+  forceIslands?: boolean
 }
 
 const encoder = new TextEncoder()
@@ -167,7 +171,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
       async final(cb: (e?: Error | null) => void) {
         try {
           if (mode === 'buffering') {
-            const islandsUsed = islandUsedBox.used
+            const islandsUsed = islandUsedBox.used || (args.forceIslands ?? false)
             let body = concatBuffers(buffer, islandsUsed)
             const perRouteHrefs = args.routePath ? getCssHrefsForRoute(args.routePath) : []
             body = injectCssLink(body, [...getCssHrefs(), ...perRouteHrefs])

package/runtime/routes.ts

@@ -189,6 +189,23 @@ export interface RouteCacheConfig<Params = Record<string, string>> {
   tags?: string[]
 }
 
+/** SSG config — read ONLY by `brust build --ssg`. Live server / dev ignore it.
+ * See docs/superpowers/specs/2026-06-12-ssg-dynamic-params-design.md. */
+export interface RouteSsgConfig {
+  /** generateStaticParams: concrete param records to prerender. Each record
+   * must cover every `{name}` in the route's full path with a non-empty
+   * string. Sync or async. Values are URL-encoded into the crawl path. */
+  params?: () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>
+  /** What non-prerendered paths do on a static host. 'none' (default) = skip
+   * → host 404 (today's behavior). 'client' = client-loader takeover
+   * (Phase B; requires `export const clientLoader` in the leaf component
+   * file, leaf must be a DEFAULT import in routes.tsx, React routes only). */
+  fallback?: 'none' | 'client'
+  /** Server-rendered loading UI baked into the fallback shell (Phase B).
+   * Renders in the leaf position with NO data. */
+  placeholder?: ComponentType
+}
+
 /** Shape returned by a middleware or by the terminal `next()` (loader + render).
  * Middleware can short-circuit by returning a RouteResponse without calling next,
  * or call next() and mutate the returned response (status, headers). */
@@ -322,6 +339,9 @@ export interface Route<Params = Record<string, string>, Data = unknown> {
   /** Opt-in cache. Cache config from the leaf only — parent's cache is
    * ignored when the route is reached as part of a chain. */
   cache?: RouteCacheConfig
+  /** Opt-in SSG behavior for dynamic-param routes (`/blog/{slug}`). Only
+   * consulted by `brust build --ssg`. */
+  ssg?: RouteSsgConfig
   /** Per-route middleware chain. Runs in declaration order; concatenated
    * with parent middlewares (parent runs before child). Cache lookup
    * still happens BEFORE any middleware (existing rule). */
@@ -1105,10 +1125,13 @@ export function makeRenderer(
       // after loaders (buildRenderElement resolved) — that's where Spec A stores
       // are seeded — and threaded into the render for <script> injection.
       return await runInRequestContext(call.req?.cookies ?? {}, async () => {
+        // Computed ONCE and shared by buildRenderElement (leaf swap) and
+        // renderBranchStreaming (forceIslands) so the two can never diverge.
+        const shellMode = wantsSsgFallbackShell(flat, call)
         let element: ReactNode
         let errorBoundary: ComponentType<{ error: Error }>
         try {
-          element = await buildRenderElement(call, flat, opts.getWorkerId)
+          element = await buildRenderElement(call, flat, opts.getWorkerId, shellMode)
           errorBoundary =
             flat.errorBoundary ??
             (({ error }) => createElement('div', null, `Internal Server Error: ${error.message}`))
@@ -1142,6 +1165,9 @@ export function makeRenderer(
           headers: flushSetCookie(verdict.headers),
           routePath: flat.fullPath,
           storeSnapshot,
+          // SSG fallback shells have zero islands on the page but the
+          // client-loader runtime still needs the importmap + bootstrap.
+          forceIslands: shellMode,
         })
         // renderBranchStreaming wrote via the chunk channel.
         return 0
@@ -1363,8 +1389,17 @@ async function navigationBranch(
     } else {
       // Wrap loader run (inside buildRenderElement) + render in one store scope so
       // store reads resolve the per-request instance; collect after render.
+      // Shell mode here only swaps the leaf for the marker div — no bootstrap
+      // injection is needed in a NAV payload: the payload is swapped into a
+      // document that already booted the bootstrap (the navigator IS the
+      // bootstrap), and the takeover runtime imports its chunk itself.
       fullHtml = await runInRequestContext(call.req?.cookies ?? {}, async () => {
-        const element = await buildRenderElement(call as any, flat, getWorkerId)
+        const element = await buildRenderElement(
+          call as any,
+          flat,
+          getWorkerId,
+          wantsSsgFallbackShell(flat, call as any),
+        )
         if (!element) throw new Error('render setup failed')
         // Use renderToPipeableStream + onAllReady so pages with <Suspense> emit
         // their RESOLVED markup, not the fallback. renderToString would only
@@ -1498,6 +1533,33 @@ async function renderNativeRouteToHtml(
   return decoder.decode(view.subarray(2 + metaLen, len))
 }
 
+/** Param value the SSG build crawler substitutes for every `{param}` when it
+ * requests the fallback SHELL of an `ssg.fallback: 'client'` route. */
+const SSG_FALLBACK_SENTINEL = '__brust_fallback__'
+
+/** True when this render/navigation call is the SSG build crawler asking for
+ * the fallback shell: the leaf declares `ssg.fallback: 'client'`, the route
+ * has ≥1 param and EVERY param value is the literal sentinel, AND the request
+ * carries `x-brust-ssg: 1` (BrustRequest.headers is a plain lower-cased
+ * Record — see the type doc). Live traffic never sends the header, so the
+ * sentinel namespace is unreachable in production; a forged header yields a
+ * shell that renders LESS than a normal request (leaf loader skipped). */
+function wantsSsgFallbackShell(
+  flat: FlatRoute,
+  call: { params: Record<string, string>; req: BrustRequest },
+): boolean {
+  const leaf = flat.chain[flat.chain.length - 1]
+  if (leaf?.ssg?.fallback !== 'client') return false
+  const names = Object.keys(call.params ?? {})
+  // Parameterless routes can never be in shell mode — intentional, not a
+  // vacuous-truth bug: expandDynamicRoutes already rejects ssg config on
+  // routes without {param}, and a no-param route is always fully
+  // prerenderable.
+  if (names.length === 0) return false
+  if (!names.every((name) => call.params[name] === SSG_FALLBACK_SENTINEL)) return false
+  return call.req?.headers?.['x-brust-ssg'] === '1'
+}
+
 /** Build the React element for a render or navigation call: runs loaders
  * top-down, builds the element bottom-up wrapping in OutletContext.Provider
  * so nested routes receive the deeper element via <Outlet />. The caller
@@ -1505,6 +1567,12 @@ async function renderNativeRouteToHtml(
  * middleware chain BEFORE calling this — this helper assumes middleware
  * has already passed.
  *
+ * SSG fallback-shell mode (`wantsSsgFallbackShell`): parent loaders still run
+ * (layouts need their data) but the LEAF loader is skipped and the leaf
+ * Component is replaced by the marker div the client-loader runtime mounts
+ * into. Both the render branch and navigationBranch flow through here, so the
+ * shell swap covers full-document AND SPA-navigation payloads.
+ *
  * Throws on setup failure (loader throw, etc.). The caller synthesises a 500
  * in that case.
  */
@@ -1512,19 +1580,25 @@ async function buildRenderElement(
   call: Extract<RouteCall, { kind: 'render' }>,
   flat: FlatRoute,
   getWorkerId?: () => number | null,
+  // Computed ONCE by the caller (and reused there for forceIslands) so the
+  // shell decision and the bootstrap-injection decision can never diverge.
+  shellMode = false,
 ): Promise<ReactNode> {
   call.req.signal = NEVER_ABORTS
   const workerId = getWorkerId ? getWorkerId() : null
   const chainNodes = flat.chain
+  const leafIdx = chainNodes.length - 1
 
   // 1. Run loaders top-down (parent → leaf). Each Component receives ONLY
-  //    its own loader's data — no merge, no inheritance.
+  //    its own loader's data — no merge, no inheritance. Shell mode skips
+  //    the LEAF loader (its data comes from the clientLoader at runtime).
   const datas: unknown[] = new Array(chainNodes.length)
   for (let i = 0; i < chainNodes.length; i++) {
     const r = chainNodes[i]
-    datas[i] = r.loader
-      ? await r.loader({ params: call.params, path: call.path, req: call.req })
-      : undefined
+    datas[i] =
+      r.loader && !(shellMode && i === leafIdx)
+        ? await r.loader({ params: call.params, path: call.path, req: call.req })
+        : undefined
   }
 
   // 2. Build the React element bottom-up. Each level wraps the deeper level
@@ -1533,13 +1607,23 @@ async function buildRenderElement(
   let element: ReactNode = null
   for (let i = chainNodes.length - 1; i >= 0; i--) {
     const r = chainNodes[i]
-    const node = createElement(r.Component!, {
-      params: call.params,
-      path: call.path,
-      data: datas[i],
-      workerId,
-      req: call.req,
-    })
+    const node =
+      shellMode && i === leafIdx
+        ? createElement(
+            'div',
+            {
+              'data-brust-fallback-root': '',
+              'data-brust-fallback': flat.fullPath,
+            },
+            r.ssg?.placeholder ? createElement(r.ssg.placeholder) : null,
+          )
+        : createElement(r.Component!, {
+            params: call.params,
+            path: call.path,
+            data: datas[i],
+            workerId,
+            req: call.req,
+          })
     element = createElement(OutletContext.Provider, { value: element }, node)
   }
   return element