@barefootjs/hono 0.1.0

package/src/adapter/index.ts

@@ -0,0 +1,6 @@
+/**
+ * BarefootJS Hono Adapter
+ */
+
+export { HonoAdapter, honoAdapter } from './hono-adapter'
+export type { HonoAdapterOptions } from './hono-adapter'

package/src/app.ts

@@ -0,0 +1,220 @@
+/**
+ * BarefootJS Hono integration
+ *
+ * Runtime-agnostic by design — no `node:fs`, no `process.env`, no
+ * implicit conventions about URL paths or the dev-reload gate. The
+ * caller hands every component / middleware its configuration
+ * explicitly so the same module works under Node, Bun, Workers, and
+ * Deno without surprises.
+ *
+ * Two pieces:
+ *
+ *   - **JSX components** (`<BfImportMap />`, `<BfScripts />`,
+ *     `<BfDevReload />`) — return raw HTML the caller composes inside
+ *     the Layout passed to Hono's `jsxRenderer`. All URL/data inputs
+ *     are required props.
+ *
+ *   - **Middleware** (`barefootDevReload`) — registers the SSE endpoint
+ *     paired with `<BfDevReload />`. Both `endpoint` and `enabled` are
+ *     required so the runtime gate happens in the caller's code, not
+ *     here.
+ *
+ * Components are defined as plain functions returning
+ * `HtmlEscapedString` (via `html`/`raw` from `hono/html`) so this file
+ * stays `.ts` — `tsx`'s per-file `@jsxImportSource` pragma doesn't
+ * always propagate when transpiling `.tsx` from `node_modules` and
+ * would otherwise crash with `ReferenceError: React is not defined`.
+ */
+
+import type { MiddlewareHandler } from 'hono'
+import { html, raw } from 'hono/html'
+import type { HtmlEscapedString } from 'hono/utils/html'
+import { useRequestContext } from 'hono/jsx-renderer'
+import { createDevReloader } from './dev-worker'
+
+const DEV_RELOAD_ENDPOINT_KEY = 'bfDevReloadEndpoint'
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Build manifest shape produced by `bf build`. Each compiled
+ * component is keyed by its manifest name; `__barefoot__` is the
+ * runtime entry. `clientJs` is a path under `dist/`, e.g.
+ * `"components/Counter.client.js"`.
+ *
+ * `stubDeps` lists the manifest keys of every `'use client'` sibling
+ * this bundle reaches via a stub rewrite (i.e. via an imperative
+ * `createComponent(name, ...)` call rather than a JSX render). The
+ * per-page script collector follows these edges so pages that only
+ * touch a child through a stub still ship its `.client.js`. See
+ * issue #1243.
+ *
+ * Note: the entries are manifest keys (e.g. `"ui/button/index"` for
+ * `ui/button/index.tsx`), not the runtime registry name passed to
+ * `createComponent(...)` (e.g. `"Button"`). For top-level
+ * single-component files the two coincide; for nested layouts they
+ * differ. `build.ts` does the path → manifest-key conversion before
+ * writing this field.
+ */
+export interface BarefootBuildManifest {
+  __barefoot__?: { clientJs?: string }
+  [componentName: string]: { clientJs?: string; stubDeps?: string[] } | undefined
+}
+
+/**
+ * Turn a build manifest into the ordered list of script URLs the page
+ * should load — runtime first, then each component. Pure: same input
+ * gives same output, no I/O.
+ */
+export function manifestToScriptUrls(
+  manifest: BarefootBuildManifest,
+  base: string,
+): string[] {
+  const out: string[] = []
+  const prefix = `${base.replace(/\/$/, '')}/`
+  if (manifest.__barefoot__?.clientJs) {
+    out.push(prefix + relPathFromComponentsBase(manifest.__barefoot__.clientJs))
+  }
+  for (const [name, entry] of Object.entries(manifest)) {
+    if (name === '__barefoot__') continue
+    if (entry?.clientJs) out.push(prefix + relPathFromComponentsBase(entry.clientJs))
+  }
+  return out
+}
+
+export function relPathFromComponentsBase(p: string): string {
+  return p.startsWith('components/') ? p.slice('components/'.length) : p
+}
+
+// ── JSX components ─────────────────────────────────────────────────────────
+
+export interface BfImportMapProps {
+  /** Base URL where the runtime + component bundles are served. */
+  base: string
+}
+
+/**
+ * Emits the `<script type="importmap">` that maps the bare
+ * `@barefootjs/client` / `@barefootjs/client/runtime` specifiers to
+ * the runtime bundle. Place in `<head>`.
+ */
+export function BfImportMap(props: BfImportMapProps): HtmlEscapedString | Promise<HtmlEscapedString> {
+  const base = props.base.replace(/\/$/, '')
+  const json = JSON.stringify({
+    imports: {
+      '@barefootjs/client': `${base}/barefoot.js`,
+      '@barefootjs/client/runtime': `${base}/barefoot.js`,
+    },
+  })
+  return html`<script type="importmap">${raw(json)}</script>`
+}
+
+export interface BfScriptsProps {
+  /** Base URL where the runtime + component bundles are served. */
+  base: string
+  /** Build manifest (from `dist/components/manifest.json`). */
+  manifest: BarefootBuildManifest
+}
+
+// Emit the empty-manifest warning at most once per server process so
+// repeated requests don't spam the console. Reset by reloading the
+// process (which is what tsx watch does whenever the manifest is
+// regenerated, so a real build clears the warning naturally).
+let __bfEmptyManifestWarned = false
+
+/**
+ * Emits one `<script type="module" src=...>` per entry in the build
+ * manifest, runtime first. Place at the end of `<body>`.
+ *
+ * Logs a one-time warning when the manifest is empty — a strong
+ * signal the user is running the server before `bf build` has
+ * produced anything, which would otherwise present as a silent
+ * "page renders but nothing is interactive."
+ */
+export function BfScripts(props: BfScriptsProps): HtmlEscapedString | Promise<HtmlEscapedString> {
+  const urls = manifestToScriptUrls(props.manifest, props.base)
+  if (urls.length === 0 && !__bfEmptyManifestWarned) {
+    __bfEmptyManifestWarned = true
+    console.warn(
+      '[barefootjs] BfScripts: manifest is empty — no <script> tags emitted. ' +
+        'Run `bf build` to compile components and rebuild the manifest.',
+    )
+  }
+  const tags = urls
+    .map((src) => `<script type="module" src="${src}"></script>`)
+    .join('')
+  return html`${raw(tags)}`
+}
+
+export interface BfDevReloadProps {
+  /**
+   * Override the SSE endpoint published by `barefootDevReload`. Almost
+   * always omitted: the middleware sets the endpoint on the request
+   * context and `<BfDevReload />` reads it. Setting this prop forces
+   * the snippet to point at the given endpoint regardless of whether
+   * the middleware is mounted.
+   */
+  endpoint?: string
+}
+
+/**
+ * Emits the inline EventSource snippet that connects to the SSE
+ * endpoint served by `barefootDevReload`. Renders nothing when the
+ * middleware isn't mounted (or is mounted with `enabled: false`),
+ * so the dev-reload script never lands on production pages — no
+ * "two gates to keep in sync" problem in the renderer.
+ */
+export function BfDevReload(props: BfDevReloadProps = {}): HtmlEscapedString | null {
+  let endpoint = props.endpoint
+  if (!endpoint) {
+    try {
+      endpoint = useRequestContext().get(DEV_RELOAD_ENDPOINT_KEY) as string | undefined
+    } catch {
+      // No request context (e.g. static rendering) and no explicit prop.
+    }
+  }
+  if (!endpoint) return null
+  const ep = JSON.stringify(endpoint)
+  const snippet = `(()=>{if(window.__bfDevReload)return;window.__bfDevReload=1;try{var s=sessionStorage.getItem('__bf_devreload_scroll');if(s){sessionStorage.removeItem('__bf_devreload_scroll');var y=parseInt(s,10);if(!isNaN(y)){var restore=function(){window.scrollTo(0,y)};if(document.readyState==='loading'){addEventListener('DOMContentLoaded',restore,{once:true})}else{restore()}}}}catch(e){}var es=new EventSource(${ep});es.addEventListener('reload',function(){try{sessionStorage.setItem('__bf_devreload_scroll',String(window.scrollY))}catch(e){}location.reload()});es.addEventListener('error',function(){})})();`
+  // Tagged-template return type is a union with Promise; the `script`
+  // tag has no async children so the actual value is sync.
+  return html`<script>${raw(snippet)}</script>` as HtmlEscapedString
+}
+
+// ── middleware ─────────────────────────────────────────────────────────────
+
+export interface BarefootDevReloadOptions {
+  /** SSE endpoint path. */
+  endpoint: string
+  /**
+   * Whether to wire the endpoint up. When `false` the middleware is a
+   * complete no-op — no SSE handler, no context publishing — and
+   * `<BfDevReload />` (which reads the endpoint off the context) also
+   * renders nothing. The runtime gate (e.g. `NODE_ENV !== 'production'`)
+   * lives in the caller.
+   */
+  enabled: boolean
+}
+
+/**
+ * Hono middleware that serves the dev-reload SSE stream and publishes
+ * its endpoint on the request context so `<BfDevReload />` knows
+ * whether and where to wire up. Mount at the root; place
+ * `<BfDevReload />` somewhere in `<body>`. There's no separate
+ * "render the snippet?" gate to keep in sync — toggling `enabled`
+ * controls both.
+ */
+export function barefootDevReload(opts: BarefootDevReloadOptions): MiddlewareHandler {
+  if (!opts.enabled) {
+    return async (_c, next) => next()
+  }
+  const reloader = createDevReloader()
+  const endpoint = opts.endpoint
+  return async (c, next) => {
+    c.set(DEV_RELOAD_ENDPOINT_KEY, endpoint)
+    if (c.req.method === 'GET' && c.req.path === endpoint) {
+      return reloader(c as never)
+    }
+    await next()
+  }
+}

package/src/async.tsx

@@ -0,0 +1,55 @@
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+//
+// Pragmas must be line-comments at the very top of the file (above
+// any JSDoc) so esbuild honours them when this module is bundled into
+// a downstream project. See packages/adapter-hono/src/scripts.tsx for
+// the full rationale.
+
+/**
+ * BfAsync - Streaming async boundary for Hono
+ *
+ * Wraps Hono's Suspense for streaming SSR with BarefootJS integration.
+ * When the renderer uses `{ stream: true }`, this leverages Hono's native
+ * Suspense/streaming. The BarefootJS hydration runtime automatically picks
+ * up components rendered inside async boundaries via requestAnimationFrame.
+ *
+ * Usage:
+ * ```tsx
+ * import { BfAsync } from '@barefootjs/hono/async'
+ *
+ * app.get('/products/:id', (c) => {
+ *   return c.render(
+ *     <BfAsync fallback={<ProductSkeleton />}>
+ *       <ProductDetail id={c.req.param('id')} />
+ *     </BfAsync>
+ *   )
+ * })
+ * ```
+ *
+ * Requires the renderer to be configured with `{ stream: true }`.
+ */
+
+import { Suspense } from 'hono/jsx/streaming'
+import type { Child } from 'hono/jsx'
+
+export interface BfAsyncProps {
+  /** Content to display while the async children are loading. */
+  fallback: Child
+  /** Async children that will be streamed when resolved. */
+  children: Child
+}
+
+/**
+ * Async streaming boundary component.
+ *
+ * Renders fallback content immediately (sent in the initial HTTP response
+ * for fast TTFB), then streams the resolved children when ready.
+ */
+export function BfAsync(props: BfAsyncProps) {
+  return (
+    <Suspense fallback={props.fallback}>
+      {props.children}
+    </Suspense>
+  )
+}

package/src/build.ts

@@ -0,0 +1,230 @@
+// Hono build config factory for barefoot.config.ts
+
+import type { BuildOptions } from '@barefootjs/jsx'
+import { HonoAdapter } from './adapter'
+import type { HonoAdapterOptions } from './adapter'
+
+export interface HonoBuildOptions extends BuildOptions {
+  /** Inject Hono script collection wrapper (default: true) */
+  scriptCollection?: boolean
+  /** Base path for client JS script URLs (default: '/static/components/') */
+  scriptBasePath?: string
+  /** Adapter-specific options passed to HonoAdapter */
+  adapterOptions?: HonoAdapterOptions
+}
+
+/**
+ * Create a BarefootBuildConfig for Hono projects.
+ *
+ * Uses structural typing — does not import BarefootBuildConfig to avoid
+ * circular dependency between @barefootjs/hono and @barefootjs/cli.
+ */
+export function createConfig(options: HonoBuildOptions = {}) {
+  const useScriptCollection = options.scriptCollection ?? true
+
+  return {
+    adapter: new HonoAdapter(options.adapterOptions),
+    paths: options.paths,
+    components: options.components,
+    outDir: options.outDir,
+    minify: options.minify,
+    contentHash: options.contentHash,
+    externals: options.externals,
+    externalsBasePath: options.externalsBasePath,
+    bundleEntries: options.bundleEntries,
+    localImportPrefixes: options.localImportPrefixes,
+    transformMarkedTemplate: useScriptCollection
+      ? (content: string, componentId: string, clientJsPath: string) =>
+          addScriptCollection(content, componentId, clientJsPath, options.scriptBasePath)
+      : undefined,
+  }
+}
+
+/**
+ * Add Hono script collection wrapper to an SSR marked template.
+ * Injects imports, a helper function, and script collector into each
+ * exported component function.
+ */
+export function addScriptCollection(content: string, componentId: string, clientJsPath: string, scriptBasePath: string = '/static/components/'): string {
+  const basePath = scriptBasePath.endsWith('/') ? scriptBasePath : scriptBasePath + '/'
+  const importStatement = "import { useRequestContext } from 'hono/jsx-renderer'\nimport { Fragment } from 'hono/jsx'\n"
+
+  // Find the last import statement and add our import after it
+  const importMatch = content.match(/^([\s\S]*?)((?:import[^\n]+\n)*)/m)
+  if (!importMatch) {
+    return content
+  }
+
+  const beforeImports = importMatch[1]
+  const existingImports = importMatch[2]
+  const restOfFile = content.slice(importMatch[0].length)
+
+  // Helper function to wrap JSX with inline script tags (for Suspense streaming)
+  const helperFn = `
+function __bfWrap(jsx: any, scripts: string[]) {
+  if (scripts.length === 0) return jsx
+  return <Fragment>{jsx}{scripts.map(s => <script type="module" src={s} />)}</Fragment>
+}
+`
+
+  // Script collection code to insert at the start of each component function.
+  // When BfScripts has already rendered (e.g., inside Suspense boundaries),
+  // scripts are output inline instead of being collected.
+  const scriptCollector = `
+  let __bfInlineScripts: string[] = []
+  // Script collection for client JS hydration
+  try {
+    const __c = useRequestContext()
+    const __scripts: { src: string }[] = __c.get('bfCollectedScripts') || []
+    const __outputScripts: Set<string> = __c.get('bfOutputScripts') || new Set()
+    const __bfRendered = __c.get('bfScriptsRendered')
+    if (!__outputScripts.has('__barefoot__')) {
+      __outputScripts.add('__barefoot__')
+      if (__bfRendered) __bfInlineScripts.push('${basePath}barefoot.js')
+      else __scripts.push({ src: '${basePath}barefoot.js' })
+    }
+    if (!__outputScripts.has('${componentId}')) {
+      __outputScripts.add('${componentId}')
+      if (__bfRendered) __bfInlineScripts.push('${basePath}${clientJsPath}')
+      else __scripts.push({ src: '${basePath}${clientJsPath}' })
+    }
+    __c.set('bfCollectedScripts', __scripts)
+    __c.set('bfOutputScripts', __outputScripts)
+  } catch {}
+`
+
+  // Insert script collector at the start of each component function body.
+  // Matches both exported and non-exported PascalCase components (#786).
+  // Uses paren counting instead of regex to correctly handle nested
+  // delimiters in destructured params (e.g. `onInput = () => {}`).
+  //
+  // The regex matches against a comment-masked copy so a docstring
+  // example like `function MyNode(this: HTMLElement, props)` is NOT
+  // misread as a real function declaration (#1236). The paren counter
+  // still walks the ORIGINAL `restOfFile` and keeps the quote-skip
+  // logic — TS parameter type annotations contain balanced strings
+  // (e.g. `"data-key"?: string`) that the skip handles correctly.
+  let modifiedRest = restOfFile
+  const maskedRest = maskComments(restOfFile)
+  const exportFuncPattern = /(?:export )?function ([A-Z]\w*)\s*\(/g
+  const insertions: Array<{ index: number; text: string }> = []
+  let efMatch: RegExpExecArray | null
+  while ((efMatch = exportFuncPattern.exec(maskedRest)) !== null) {
+    const openParenPos = efMatch.index + efMatch[0].length - 1
+    // Count parens to find matching ')'
+    let depth = 1
+    let i = openParenPos + 1
+    while (i < restOfFile.length && depth > 0) {
+      const ch = restOfFile[i]
+      if (ch === "'" || ch === '"' || ch === '`') {
+        i++
+        while (i < restOfFile.length) {
+          if (restOfFile[i] === '\\') { i += 2; continue }
+          if (restOfFile[i] === ch) { i++; break }
+          i++
+        }
+        continue
+      }
+      if (ch === '(') depth++
+      else if (ch === ')') depth--
+      i++
+    }
+    // i is now right after matching ')'; find the next '{' for function body
+    while (i < restOfFile.length && restOfFile[i] !== '{') i++
+    if (i < restOfFile.length) {
+      insertions.push({ index: i + 1, text: scriptCollector })
+    }
+  }
+  // Apply insertions from back to front to preserve indices
+  for (let ii = insertions.length - 1; ii >= 0; ii--) {
+    const ins = insertions[ii]
+    modifiedRest = modifiedRest.slice(0, ins.index) + ins.text + modifiedRest.slice(ins.index)
+  }
+
+  // Wrap each return (...) with __bfWrap((...), __bfInlineScripts).
+  //
+  // Intentionally NO comment/string masking here. JSX bodies routinely
+  // contain unbalanced apostrophes in text content (`Hey! How's it
+  // going`) which a string-aware scanner misreads as an open quote and
+  // ends up blanking everything until the next stray `'`, breaking
+  // paren counting. Plain `(` / `)` counting works for JSX returns
+  // because JSX text cannot contain literal parens — those only appear
+  // inside `{expr}` slots, which are balanced JS.
+  const returnPattern = /return\s*\(/g
+  const returnMatches: Array<{ index: number; length: number }> = []
+  let m: RegExpExecArray | null
+  while ((m = returnPattern.exec(modifiedRest)) !== null) {
+    returnMatches.push({ index: m.index, length: m[0].length })
+  }
+  // Process from last to first to keep earlier offsets valid
+  for (let ri = returnMatches.length - 1; ri >= 0; ri--) {
+    const rm = returnMatches[ri]
+    const afterOpen = rm.index + rm.length // position after 'return ('
+    let depth = 1
+    let ci = afterOpen
+    while (ci < modifiedRest.length && depth > 0) {
+      if (modifiedRest[ci] === '(') depth++
+      else if (modifiedRest[ci] === ')') depth--
+      ci++
+    }
+    // ci is right after the matching ')'; insert wrap closing there
+    modifiedRest = modifiedRest.slice(0, ci) + ', __bfInlineScripts)' + modifiedRest.slice(ci)
+    // Replace 'return (' with 'return __bfWrap(('
+    modifiedRest = modifiedRest.slice(0, rm.index) + 'return __bfWrap((' + modifiedRest.slice(rm.index + rm.length)
+  }
+
+  return beforeImports + existingImports + importStatement + helperFn + modifiedRest
+}
+
+/**
+ * Replace comment contents with spaces (preserving length and newlines
+ * so indices computed against the masked text are valid in the
+ * original). Used by `addScriptCollection` so its `function Foo(`
+ * regex ignores JSDoc / inline comments — a docstring example like
+ * `function MyNode(this: HTMLElement, props)` previously masqueraded
+ * as a real function declaration (#1236).
+ *
+ * Handles `//` line comments and `/* ... *\/` block comments (incl.
+ * JSDoc). String literals are intentionally NOT masked: JSX text
+ * content routinely contains unbalanced apostrophes (`How's`) that a
+ * string-aware masker would misread as an open quote, blanking the
+ * rest of the file and hiding later function declarations.
+ *
+ * Strings inside comments are handled implicitly: the whole comment
+ * (including any quotes it contains) is blanked.
+ *
+ * **Known limitation**: this function does NOT track string
+ * boundaries, so a `//` or `/*` appearing INSIDE a string literal is
+ * still treated as a comment delimiter. Example: in
+ * `const u = "https://x.y" ; export function Foo() {}` the `//` in
+ * `https://` is misread as a line comment and the rest of the line is
+ * blanked — a `function Foo()` on that same line would be hidden from
+ * the regex. SSR template output (the only caller) does not embed
+ * such cases in practice. If a future caller can produce them, swap
+ * in a real lexer rather than extending this helper.
+ */
+export function maskComments(s: string): string {
+  let out = ''
+  let i = 0
+  while (i < s.length) {
+    const ch = s[i]
+    const next = s[i + 1]
+    if (ch === '/' && next === '*') {
+      const end = s.indexOf('*/', i + 2)
+      const stop = end === -1 ? s.length : end + 2
+      for (let j = i; j < stop; j++) out += s[j] === '\n' ? '\n' : ' '
+      i = stop
+      continue
+    }
+    if (ch === '/' && next === '/') {
+      const end = s.indexOf('\n', i + 2)
+      const stop = end === -1 ? s.length : end
+      for (let j = i; j < stop; j++) out += ' '
+      i = stop
+      continue
+    }
+    out += ch
+    i++
+  }
+  return out
+}

package/src/client-shim.ts

@@ -0,0 +1,164 @@
+/**
+ * SSR shim for `@barefootjs/client` when targeting the Hono adapter.
+ *
+ * The compiler rewrites `@barefootjs/client` imports inside SSR templates to
+ * this module. The shim provides:
+ *
+ *   - `useContext` / `provideContext` bridged to Hono's per-render context
+ *     stack, so context values flow through `<Context.Provider value=...>`
+ *     during SSR. The compiler emits provider IR via `provideContextSSR`.
+ *   - Pure helpers (`createContext`, `splitProps`, `forwardProps`, `unwrap`,
+ *     `__slot`) re-exported from `@barefootjs/client`.
+ *   - Reactive primitives (`createSignal`, `createMemo`, etc.) replaced with
+ *     stubs that throw if called — the compiler is expected to rewrite all
+ *     reachable call sites to plain values during SSR codegen.
+ *   - Portal helpers as no-ops; portals are realized at hydration time.
+ */
+
+/** @jsxImportSource hono/jsx */
+
+import { createContext as honoCreateContext, useContext as honoUseContext, jsx } from 'hono/jsx'
+import type { Context as HonoContext } from 'hono/jsx'
+import type { Context } from '@barefootjs/client'
+
+export {
+  createContext,
+  splitProps,
+  forwardProps,
+  unwrap,
+  __slot,
+} from '@barefootjs/client'
+
+export type {
+  Context,
+  Reactive,
+  Signal,
+  Memo,
+  CleanupFn,
+  EffectFn,
+  SlotMarker,
+  Portal,
+  PortalChildren,
+  PortalOptions,
+  Renderable,
+} from '@barefootjs/client'
+
+// ---------------------------------------------------------------------------
+// Context bridge: BarefootJS Context → Hono Context
+// ---------------------------------------------------------------------------
+
+const honoCtxBridge = new WeakMap<Context<unknown>, HonoContext<unknown>>()
+
+/**
+ * Lazily map a BarefootJS Context object to a Hono context. The mapping is
+ * stable (WeakMap keyed by the Context object itself), so providers and
+ * consumers in the same render see the same Hono context.
+ */
+export function getHonoContext<T>(bfCtx: Context<T>): HonoContext<T | undefined> {
+  let hc = honoCtxBridge.get(bfCtx as Context<unknown>) as HonoContext<T | undefined> | undefined
+  if (!hc) {
+    hc = honoCreateContext<T | undefined>(bfCtx.defaultValue)
+    honoCtxBridge.set(bfCtx as Context<unknown>, hc as HonoContext<unknown>)
+  }
+  return hc
+}
+
+/**
+ * SSR `useContext`: read from Hono's per-render stack, falling back to the
+ * BarefootJS Context's default value, then to `undefined`. Mirrors client
+ * semantics — no provider returns `undefined` rather than throwing.
+ */
+export function useContext<T>(bfCtx: Context<T>): T {
+  const hc = getHonoContext(bfCtx)
+  const v = honoUseContext(hc) as T | undefined
+  if (v !== undefined) return v
+  return bfCtx.defaultValue as T
+}
+
+/**
+ * SSR `provideContext`: imperative provider calls inside init code are
+ * unreachable from SSR templates (they live in client JS). At SSR, the
+ * `<Context.Provider value=...>` JSX is compiled to `provideContextSSR`
+ * instead, which uses Hono's stack-scoped Provider.
+ */
+export function provideContext<T>(_bfCtx: Context<T>, _value: T): void {
+  // intentional no-op
+}
+
+/**
+ * Compiler-emitted helper for `<Context.Provider value=...>{children}</...>`
+ * at SSR. Wraps children with the bridged Hono Provider so that descendants
+ * resolving the same BarefootJS Context via `useContext` see this value.
+ */
+export function provideContextSSR<T>(
+  bfCtx: Context<T>,
+  value: T,
+  children: unknown,
+): unknown {
+  const HonoCtx = getHonoContext(bfCtx)
+  return jsx(HonoCtx.Provider as unknown as Function, { value, children })
+}
+
+// ---------------------------------------------------------------------------
+// Reactive primitives — never reached at SSR (compiler rewrites call sites)
+// ---------------------------------------------------------------------------
+
+function calledAtSSR(name: string): never {
+  throw new Error(
+    `[barefootjs] ${name}() reached SSR. The compiler should have rewritten this call site — please report a bug.`,
+  )
+}
+
+export function createSignal<T>(_initial?: T): never {
+  return calledAtSSR('createSignal')
+}
+export function createMemo<T>(_fn: () => T): never {
+  return calledAtSSR('createMemo')
+}
+export function createEffect(_fn: () => void): never {
+  return calledAtSSR('createEffect')
+}
+export function createDisposableEffect(_fn: () => void): never {
+  return calledAtSSR('createDisposableEffect')
+}
+export function createRoot<T>(_fn: (dispose: () => void) => T): never {
+  return calledAtSSR('createRoot')
+}
+
+export function onMount(_fn: () => void): void {
+  // no-op at SSR
+}
+export function onCleanup(_fn: () => void): void {
+  // no-op at SSR
+}
+
+export function untrack<T>(fn: () => T): T {
+  return fn()
+}
+export function batch<T>(fn: () => T): T {
+  return fn()
+}
+
+// ---------------------------------------------------------------------------
+// Portal stubs — portals are realized at hydration time, not at SSR
+// ---------------------------------------------------------------------------
+
+export function createPortal(
+  _children: unknown,
+  _container?: unknown,
+  _options?: unknown,
+): never {
+  return calledAtSSR('createPortal')
+}
+
+export function isSSRPortal(_element: unknown): boolean {
+  return false
+}
+
+export function findSiblingSlot(_el: unknown, _slotSelector: string): null {
+  return null
+}
+
+export function cleanupPortalPlaceholder(_portalId: string): void {
+  // no-op
+}