brustjs 0.1.0-alpha

package/runtime/islands/bootstrap.ts

@@ -0,0 +1,241 @@
+// Brust client-side hydration bootstrap.
+// Built once at boot into .brust/islands/_bootstrap.js and served at
+// /_brust/islands/_bootstrap.js. Loaded by makeRenderer-injected <script>.
+//
+// Responsibilities:
+//   1. Hydrate every <... data-brust-island="<id>" ...> marker under a
+//      given root (default: document.body) — exposed as hydrateMarkersIn
+//      so the navigation interceptor can re-run it on the new <main>
+//      after a navigation swap.
+//   2. Intercept internal <a href> clicks → fetch /_brust/page/{path} →
+//      swap <main> in place → update title → re-hydrate islands →
+//      history.pushState. Any failure falls back to a full reload.
+//   3. Listen for popstate (back / forward) and run the same swap path
+//      without pushing a new entry.
+
+import { createRoot, hydrateRoot, type Root } from 'react-dom/client'
+import { createElement } from 'react'
+
+// Track React roots created by hydrateOne so we can unmount them before
+// removing their DOM in swapMainContent. Without this, removing the DOM
+// out from under a live root causes React's scheduler to keep posting
+// work to a detached subtree, which manifests as a hung tab.
+const islandRoots = new WeakMap<HTMLElement, Root>()
+
+type Trigger = 'load' | 'idle' | 'visible' | 'interaction'
+
+function registerTrigger(el: HTMLElement, trigger: Trigger, fire: () => void): void {
+  switch (trigger) {
+    case 'load': {
+      fire()
+      return
+    }
+    case 'idle': {
+      const rIC = (globalThis as { requestIdleCallback?: (cb: () => void) => void })
+        .requestIdleCallback
+      if (typeof rIC === 'function') {
+        rIC(fire)
+      } else {
+        setTimeout(fire, 0)
+      }
+      return
+    }
+    case 'visible': {
+      if (typeof IntersectionObserver === 'undefined') {
+        fire()
+        return
+      }
+      const io = new IntersectionObserver((entries, obs) => {
+        for (const e of entries) {
+          if (e.isIntersecting) {
+            obs.disconnect()
+            fire()
+            return
+          }
+        }
+      })
+      io.observe(el)
+      return
+    }
+    case 'interaction': {
+      const onceFire = () => {
+        el.removeEventListener('pointerdown', onceFire)
+        el.removeEventListener('keydown', onceFire)
+        el.removeEventListener('focusin', onceFire)
+        fire()
+      }
+      el.addEventListener('pointerdown', onceFire, { once: false })
+      el.addEventListener('keydown', onceFire, { once: false })
+      el.addEventListener('focusin', onceFire, { once: false })
+      return
+    }
+  }
+}
+
+// Exported for unit testing — the public entry is hydrateMarkersIn, but the
+// createRoot/hydrateRoot auto-detect branch is cleanest to assert by driving
+// hydrateOne directly (the `load` trigger fires it as a detached microtask).
+export async function hydrateOne(el: HTMLElement): Promise<void> {
+  const id = el.getAttribute('data-brust-island')
+  if (!id) return
+  const propsJson = el.getAttribute('data-brust-props') ?? '{}'
+  let props: Record<string, unknown>
+  try {
+    props = JSON.parse(propsJson)
+  } catch (e) {
+    console.error(`[brust] island "${id}": invalid data-brust-props JSON`, e)
+    return
+  }
+  try {
+    const mod = await import(`/_brust/islands/${id}.js`)
+    const Component = (mod.default ?? mod) as React.ComponentType<Record<string, unknown>>
+    if (typeof Component !== 'function') {
+      console.error(`[brust] island "${id}": chunk has no default-exported component`)
+      return
+    }
+    let root: Root
+    if (el.hasAttribute('data-brust-csr')) {
+      // Client-only island: the native compiler emits an EMPTY mount (no
+      // server markup) tagged data-brust-csr. hydrateRoot on an empty mount
+      // is a React 19 hydration mismatch, so spin up a fresh client root.
+      root = createRoot(el)
+      root.render(createElement(Component, props))
+    } else {
+      // Server island (or React-path island): server markup is present in the
+      // mount, so hydrate it in place to attach handlers without re-rendering.
+      root = hydrateRoot(el, createElement(Component, props))
+    }
+    // createRoot and hydrateRoot both return a Root with .unmount(), so
+    // islandRoots / unmountIslandsIn handle either uniformly — no extra work.
+    islandRoots.set(el, root)
+  } catch (e) {
+    console.error(`[brust] island "${id}": hydration failed`, e)
+  }
+}
+
+/** Unmount any React roots that live inside `root`. Must run BEFORE
+ * removing or replacing their DOM, otherwise React's scheduler keeps
+ * posting work to detached nodes and the tab hangs. Exported for unit
+ * testing the createRoot/hydrateRoot unmount parity. */
+export function unmountIslandsIn(root: ParentNode): void {
+  const markers = root.querySelectorAll<HTMLElement>('[data-brust-island]')
+  for (const el of Array.from(markers)) {
+    const r = islandRoots.get(el)
+    if (r) {
+      try {
+        r.unmount()
+      } catch (e) {
+        console.warn('[brust] island unmount failed', e)
+      }
+      islandRoots.delete(el)
+    }
+  }
+}
+
+/** Scan `root` for un-hydrated island markers and register their hydration
+ * triggers. Exposed so the navigation interceptor can call it on the
+ * freshly-swapped <main> subtree after a SPA navigation. The
+ * `data-brust-hydrated` attribute on each marker is the idempotence guard
+ * — a second call on the same root no-ops for already-hydrated markers. */
+export function hydrateMarkersIn(root: ParentNode = document.body): void {
+  const markers = root.querySelectorAll<HTMLElement>(
+    '[data-brust-island]:not([data-brust-hydrated])',
+  )
+  for (const el of Array.from(markers)) {
+    el.setAttribute('data-brust-hydrated', '1')
+    const trig = (el.getAttribute('data-brust-hydrate') ?? 'load') as Trigger
+    registerTrigger(el, trig, () => {
+      void hydrateOne(el)
+    })
+  }
+}
+
+/** Replace `main`'s children with HTML from a trusted Brust server
+ * response. The trust boundary: the HTML originates from the same Brust
+ * server that produced the initial page load. We use DOMParser (not
+ * Range.createContextualFragment) because DOMParser produces an INERT
+ * document — <script> tags are parsed but never executed. */
+export function swapMainContent(main: HTMLElement, html: string): void {
+  const parsed = new DOMParser().parseFromString(`<body>${html}</body>`, 'text/html')
+  while (main.firstChild) main.removeChild(main.firstChild)
+  // Snapshot children before iterating: importNode clones (does NOT remove
+  // from source), so iterating on parsed.body.firstChild directly would
+  // infinite-loop. Array.from gives a fixed-length live snapshot to walk.
+  for (const node of Array.from(parsed.body.childNodes)) {
+    main.appendChild(document.importNode(node, true))
+  }
+}
+
+/** Classifier — true iff the event should be intercepted as a SPA
+ * navigation. Exported for unit testing. */
+export function isInternalLink(a: HTMLAnchorElement, event: MouseEvent): boolean {
+  if (event.defaultPrevented) return false
+  if (event.button !== 0) return false
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false
+  if (a.target && a.target !== '_self') return false
+  if (a.hasAttribute('download')) return false
+  if (a.dataset.brustNoIntercept !== undefined) return false
+  const url = new URL(a.href, location.href)
+  if (url.origin !== location.origin) return false
+  // Same-pathname links: hash-only changes use the browser's native scroll;
+  // hash-absent same-URL clicks (e.g., logo back to current page) are
+  // redundant — let the browser handle them as no-ops (no SPA refetch).
+  if (url.pathname === location.pathname && url.search === location.search) return false
+  if (url.pathname.startsWith('/_brust/')) return false
+  return true
+}
+
+let inFlight: AbortController | null = null
+
+async function navigate(url: URL, push: boolean): Promise<void> {
+  inFlight?.abort()
+  const ac = new AbortController()
+  inFlight = ac
+  try {
+    const resp = await fetch(`/_brust/page${url.pathname}${url.search}`, {
+      signal: ac.signal,
+      headers: { Accept: 'application/json' },
+    })
+    if (!resp.ok) throw new Error(`navigation: status ${resp.status}`)
+    const { html, title } = (await resp.json()) as { html: string; title: string }
+    const main = document.querySelector('main')
+    if (!main) throw new Error('navigation: no <main> element')
+    unmountIslandsIn(main as HTMLElement)
+    swapMainContent(main as HTMLElement, html)
+    if (title) document.title = title
+    if (push) history.pushState({}, '', url.href)
+    window.scrollTo(0, 0)
+    hydrateMarkersIn(main as HTMLElement)
+  } catch (err) {
+    if ((err as Error).name === 'AbortError') return
+    console.warn('[brust] SPA navigation failed, falling back to full reload:', err)
+    location.href = url.href
+  } finally {
+    if (inFlight === ac) inFlight = null
+  }
+}
+
+function installInterceptor(): void {
+  document.addEventListener('click', (e) => {
+    const target = e.target as HTMLElement | null
+    const a = target?.closest('a') as HTMLAnchorElement | null
+    if (!a || !isInternalLink(a, e)) return
+    e.preventDefault()
+    void navigate(new URL(a.href, location.href), /* push */ true)
+  })
+  window.addEventListener('popstate', () => {
+    void navigate(new URL(location.href), /* push */ false)
+  })
+}
+
+if (typeof document !== 'undefined') {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => {
+      hydrateMarkersIn(document.body)
+      installInterceptor()
+    })
+  } else {
+    hydrateMarkersIn(document.body)
+    installInterceptor()
+  }
+}

package/runtime/islands/build.ts

@@ -0,0 +1,141 @@
+import { readFileSync } from 'node:fs'
+import { mkdir, rm } from 'node:fs/promises'
+import { isAbsolute, resolve } from 'node:path'
+import { scanImports } from '../cli/native-routes-emit.ts'
+
+export interface IslandsBuildResult {
+  /** Absolute path to the output directory passed to brust's Rust side. */
+  outDir: string
+  /** Number of island chunks emitted (excludes runtime + bootstrap). */
+  islandCount: number
+}
+
+export interface BuildIslandsOptions {
+  /** Override the output directory. Default: `<cwd>/.brust/islands`. */
+  outDir?: string
+}
+
+/** Scan a routes entry file for `<Island component={X} />` usage and derive the
+ * island chunk list (componentName → absolute source path). Replaces the old
+ * static config-file lookup — the chunk set is derived from source.
+ *
+ * 1. Resolve the entry's page imports via {@link scanImports}.
+ * 2. For each page, slice every `<Island … />` tag and capture its
+ *    `component={Ident}`. A tag with no `component` is a hard error (F3:
+ *    never silently skip an island).
+ * 3. Resolve each captured ident through that page's OWN imports.
+ * 4. Dedup islands that reuse the same component+path; throw on two different
+ *    files whose island components share a name (ids must be app-unique).
+ */
+export function scanIslandChunks(routesEntryFile: string): Map<string, string> {
+  const pages = scanImports(routesEntryFile)
+  const chunks = new Map<string, string>()
+
+  for (const pagePath of pages.values()) {
+    const source = readFileSync(pagePath, 'utf8')
+    const pageImports = scanImports(pagePath)
+
+    const tags = source.match(/<Island\b[\s\S]*?\/>/g) ?? []
+    for (const tag of tags) {
+      const compMatch = tag.match(/component=\{\s*(\w+)\s*\}/)
+      if (!compMatch) {
+        throw new Error(`<Island> tag in ${pagePath} has no \`component={...}\` prop: ${tag}`)
+      }
+      const ident = compMatch[1]!
+      const src = pageImports.get(ident)
+      if (!src) {
+        throw new Error(
+          `<Island component={${ident}}> in ${pagePath} has no matching import ` +
+            `(expected \`import ${ident} from "..."\`)`,
+        )
+      }
+      const existing = chunks.get(ident)
+      if (existing === undefined) {
+        chunks.set(ident, src)
+      } else if (existing !== src) {
+        throw new Error(
+          `island component name "${ident}" is used by two different files ` +
+            `(${existing} and ${src}); island component names must be app-unique`,
+        )
+      }
+      // existing === src → same component reused; dedupe (skip).
+    }
+  }
+
+  return chunks
+}
+
+/** Build the runtime chunks + all island chunks + bootstrap. Returns the
+ * absolute output directory; caller passes it to `brust.configureIslandsDir`. */
+export async function buildIslands(
+  islands: Map<string, string>,
+  options: BuildIslandsOptions = {},
+): Promise<IslandsBuildResult> {
+  const outDir = options.outDir
+    ? isAbsolute(options.outDir)
+      ? options.outDir
+      : resolve(process.cwd(), options.outDir)
+    : resolve(process.cwd(), '.brust/islands')
+  await rm(outDir, { recursive: true, force: true })
+  await mkdir(outDir, { recursive: true })
+
+  // import.meta.dir points to runtime/islands/.
+  const entriesDir = resolve(import.meta.dir, '_entries')
+
+  // 1. Combined react + react/jsx-runtime (no externals — bundles React).
+  await buildOne([`${entriesDir}/react.ts`], outDir, '_react.js', [])
+
+  // 2. react-dom/client (react external; consumes _react.js via importmap).
+  await buildOne([`${entriesDir}/react-dom.ts`], outDir, '_react-dom.js', ['react'])
+
+  // 3. Per-island chunks (all 3 runtime specifiers external).
+  const externals = ['react', 'react/jsx-runtime', 'react-dom/client']
+  let count = 0
+  for (const [id, entry] of islands) {
+    if (!isValidIslandId(id)) {
+      throw new Error(
+        `island id ${JSON.stringify(id)} contains invalid characters; ` +
+          `allowed: [A-Za-z0-9_-]+ (matches the server's filename safety check)`,
+      )
+    }
+    await buildOne([entry], outDir, `${id}.js`, externals)
+    count++
+  }
+
+  // 4. Bootstrap (react + react-dom/client external; uses importmap).
+  const bootstrapSrc = resolve(import.meta.dir, 'bootstrap.ts')
+  await buildOne([bootstrapSrc], outDir, '_bootstrap.js', externals)
+
+  return { outDir, islandCount: count }
+}
+
+async function buildOne(
+  entrypoints: string[],
+  outdir: string,
+  naming: string,
+  external: string[],
+): Promise<void> {
+  const result = await Bun.build({
+    entrypoints,
+    outdir,
+    naming,
+    format: 'esm',
+    target: 'browser',
+    external,
+    minify: true,
+    define: {
+      'process.env.NODE_ENV': '"production"',
+    },
+  })
+  if (!result.success) {
+    const messages = result.logs.map((l) => String(l)).join('\n')
+    throw new Error(`Bun.build failed for ${entrypoints.join(', ')}:\n${messages}`)
+  }
+}
+
+/** Mirrors `is_safe_island_filename` in src/server.rs — keep in sync.
+ * Allows [A-Za-z0-9_-]+ only (no dots in the id; dot is for the extension). */
+function isValidIslandId(id: string): boolean {
+  if (id.length === 0) return false
+  return /^[A-Za-z0-9_-]+$/.test(id)
+}

package/runtime/islands/importmap.ts

@@ -0,0 +1,17 @@
+// Importmap + bootstrap script tags injected into HTML responses that
+// use <Island>. Extracted from runtime/routes.ts so renderBranchStreaming
+// can prepend it during the buffering-sink final assembly.
+export const ISLANDS_IMPORTMAP_AND_BOOTSTRAP =
+  '<script type="importmap">' +
+  JSON.stringify({
+    imports: {
+      // Both react and react/jsx-runtime resolve to the SAME chunk; the
+      // chunk re-exports both surfaces. Browser fetches it once and slices
+      // different named exports for each import statement.
+      react: '/_brust/islands/_react.js',
+      'react/jsx-runtime': '/_brust/islands/_react.js',
+      'react-dom/client': '/_brust/islands/_react-dom.js',
+    },
+  }) +
+  '</script>' +
+  '<script type="module" src="/_brust/islands/_bootstrap.js" defer></script>'

package/runtime/islands/island.tsx

@@ -0,0 +1,58 @@
+import { createElement, type ComponentType, type ReactNode } from 'react'
+
+/** Triggers that activate hydration of an island marker. */
+export type HydrateTrigger = 'load' | 'idle' | 'visible' | 'interaction'
+
+export interface IslandProps<P> {
+  /** Component rendered server-side INSIDE the marker. Same component
+   * the client chunk default-exports — SSR HTML must match the post-hydrate
+   * tree to avoid React reconciliation warnings. Its `Component.name` is the
+   * island id: it names the chunk (`<name>.js`) and the `data-brust-island`
+   * marker the client bootstrap reads, so it must be a stable, named
+   * component (no anonymous default export). */
+  component: ComponentType<P>
+  /** Props passed to the component on both server and client. Must be
+   * JSON-serializable (no functions, classes, DOM nodes, etc.). */
+  props: P
+  /** When to hydrate. Default 'load'. */
+  hydrate?: HydrateTrigger
+}
+
+/** Module-scope flag flipped by every `<Island>` render. `makeRenderer`
+ * reads + resets it once per render to decide whether to prepend the
+ * importmap + bootstrap script. */
+let __used = false
+
+/** Internal — flipped by Island, read by makeRenderer. */
+export function consumeIslandUsedFlag(): boolean {
+  const v = __used
+  __used = false
+  return v
+}
+
+export function Island<P extends Record<string, unknown>>({
+  component: Component,
+  props,
+  hydrate = 'load',
+}: IslandProps<P>): ReactNode {
+  __used = true
+  const resolvedId = Component.name
+  if (!resolvedId) {
+    throw new Error(
+      '<Island> component has no `.name`; the island id is derived from ' +
+        '`Component.name`. Use a stable named component (e.g. ' +
+        '`export default function Counter() {…}`), not an anonymous default ' +
+        'export or a minified/inlined function.',
+    )
+  }
+  const propsJson = JSON.stringify(props)
+  return createElement(
+    'div',
+    {
+      'data-brust-island': resolvedId,
+      'data-brust-props': propsJson,
+      'data-brust-hydrate': hydrate,
+    },
+    createElement(Component, props),
+  )
+}

package/runtime/islands/native-render.ts

@@ -0,0 +1,153 @@
+// Native-jinja island plumbing (Sub-project J / T7).
+//
+// When a native (minijinja) route has an islands manifest, the loader's
+// return value is augmented with per-island context variables before the
+// JSON is shipped into the SAB for napi_render_jinja. Each island i
+// contributes `island_<instance>_props` — the island's props, resolved out of
+// the loader data via a dotted path, JSON-stringified, and HTML-entity-encoded
+// so the value is safe to substitute RAW into a double-quoted attribute (brust's
+// minijinja env has NO autoescape).
+//
+// T9 SCOPE: ssr islands ALSO contribute `island_<instance>_html` — the island's
+// SOURCE component, imported by absolute path and renderToString'd server-side.
+// Client-only islands (ssr:false) still contribute only `_props`. This makes
+// resolveIslandContext async (it awaits the dynamic import of each ssr source).
+
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+// .node build: keep a single react-dom/server build loaded across the runtime
+// (the streaming paths need server.node's renderToPipeableStream). See routes.ts.
+import { renderToString } from 'react-dom/server.node'
+import { createElement } from 'react'
+
+/** One entry of a `<template>.islands.json` manifest (enriched by T6). */
+export interface NativeIslandEntry {
+  component: string
+  instance: number
+  propsPath: string
+  ssr: boolean
+  hydrate: string
+  sourcePath: string
+}
+
+/** Walk a dotted path into `data`. Each segment must be an OWN enumerable
+ * property — inherited keys (`constructor`, `__proto__`, `toString`, …) yield
+ * `undefined` rather than traversing the prototype chain. This blocks both
+ * prototype-pollution-style reads AND the downstream crash where a resolved
+ * function (`Object`) makes `JSON.stringify` return `undefined`. A missing
+ * segment, a nullish/primitive cursor, or a non-own key all yield `undefined`.
+ * An empty path returns `data` itself. */
+export function pathInto(data: unknown, propsPath: string): unknown {
+  if (propsPath === '') return data
+  let cur: unknown = data
+  for (const seg of propsPath.split('.')) {
+    if (cur == null || typeof cur !== 'object' || !Object.hasOwn(cur, seg)) {
+      return undefined
+    }
+    cur = (cur as Record<string, unknown>)[seg]
+  }
+  return cur
+}
+
+/** HTML-entity-encode a string for a double-quoted attribute value. Order is
+ * load-bearing: `&` MUST be replaced first so the entities introduced by the
+ * later replacements aren't themselves double-encoded. Matches the compiler's
+ * `push_attr_escaped` charset (& < > ") so server-rendered markup and these
+ * props attrs stay consistent. */
+export function entityEncode(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+// Manifests are boot-only/immutable (same as the Rust template registry), so
+// cache by absolute path. We cache BOTH hits and misses (null): a native
+// route with no islands would otherwise pay a throw-and-catch readFileSync on
+// every request, and the immutability guarantee means a missing file won't
+// appear later at runtime. `null` is a valid cache value, so the cache must be
+// keyed on `has()`, not `get() !== undefined`.
+const manifestCache = new Map<string, NativeIslandEntry[] | null>()
+
+/** Read `<jinjaDir>/<templateName>.islands.json` and return the parsed entry
+ * array, or `null` if the file doesn't exist. `jinjaDir` defaults to
+ * `process.cwd()/.brust/jinja`; tests pass a temp dir. Both hits and misses
+ * are cached by absolute path. */
+export function loadIslandManifest(
+  templateName: string,
+  jinjaDir?: string,
+): NativeIslandEntry[] | null {
+  const dir = jinjaDir ?? path.resolve(process.cwd(), '.brust/jinja')
+  const abs = path.resolve(dir, `${templateName}.islands.json`)
+  if (manifestCache.has(abs)) return manifestCache.get(abs)!
+  let parsed: NativeIslandEntry[] | null
+  try {
+    // JSON.parse is INSIDE the try: a present-but-malformed manifest must
+    // degrade to null (cached), not throw out of the fast-lane native branch
+    // (which runs past the request try/catch — an unguarded throw there is an
+    // unhandled rejection that hangs the request instead of a clean fallback).
+    parsed = JSON.parse(readFileSync(abs, 'utf8')) as NativeIslandEntry[]
+  } catch {
+    manifestCache.set(abs, null)
+    return null
+  }
+  manifestCache.set(abs, parsed)
+  return parsed
+}
+
+// Cache imported island modules by sourcePath (Bun caches the import anyway;
+// this avoids repeated default-export resolution).
+const componentCache = new Map<string, unknown>()
+
+/** Build the per-island context additions for a manifest. Each entry
+ * contributes `island_<instance>_props` — the resolved props, JSON-stringified
+ * (undefined → null so it stays valid JSON) and entity-encoded. SSR entries
+ * (`ssr:true`) ALSO contribute `island_<instance>_html` — the island source
+ * component imported by absolute path and renderToString'd. The `instance` is a
+ * per-occurrence integer, so it's a safe key fragment. */
+export async function resolveIslandContext(
+  manifest: NativeIslandEntry[],
+  data: unknown,
+): Promise<Record<string, string>> {
+  const out: Record<string, string> = {}
+  for (const entry of manifest) {
+    const props = pathInto(data, entry.propsPath)
+    // `?? null` handles undefined props; the `?? 'null'` belt-and-braces covers
+    // the case where JSON.stringify itself returns undefined (e.g. a function
+    // value), so entityEncode never receives undefined.
+    out['island_' + entry.instance + '_props'] = entityEncode(
+      JSON.stringify(props ?? null) ?? 'null',
+    )
+    if (!entry.ssr) continue
+    try {
+      let Component = componentCache.get(entry.sourcePath)
+      if (Component === undefined) {
+        const mod = await import(entry.sourcePath)
+        Component = mod.default ?? mod
+        componentCache.set(entry.sourcePath, Component)
+      }
+      if (typeof Component !== 'function') {
+        throw new Error(`island "${entry.component}" source has no default-exported component`)
+      }
+      // Render from the SAME (roundtripped) props value the client gets via
+      // JSON.parse(data-brust-props) — byte-identity guarantees no hydration
+      // mismatch. props ?? undefined: pass the actual value (or undefined) to
+      // the component, NOT the `null` sentinel used for the props string.
+      out['island_' + entry.instance + '_html'] = renderToString(
+        createElement(Component as any, (props ?? undefined) as any),
+      )
+    } catch (e) {
+      // CONTAINED FAILURE (spec invariant): a throwing ssr island degrades to
+      // an empty mount (no _html) + logged warning, rather than 500-ing the
+      // page. The mount has no data-brust-csr, so the client will client-render
+      // it via hydrateRoot's React-19 mismatch recovery (noisy but functional).
+      console.error(
+        `[brust] ssr island "${entry.component}" renderToString failed; degrading to client-only:`,
+        e,
+      )
+      // leave _html unset → empty mount
+    }
+  }
+  return out
+}