@barefootjs/hono 0.1.0

package/src/dev-worker.ts

@@ -0,0 +1,93 @@
+/**
+ * BarefootJS Dev Reloader for Cloudflare Workers / other edge runtimes.
+ *
+ * Unlike `./dev`'s `createDevReloader`, this variant does not watch the local
+ * filesystem — it generates a fresh boot ID on every cold start and relies on
+ * the standard SSE `Last-Event-ID` reconnection protocol to detect restarts:
+ *
+ *   1. First connect       → send `event: hello`, `id: <BOOT_ID>`.
+ *   2. Worker restart      → SSE stream drops, client reconnects with
+ *      `Last-Event-ID: <old BOOT_ID>`.
+ *   3. Server sees mismatch → send `event: reload`, client refreshes.
+ *
+ * Pair with `BfDevReload` from `@barefootjs/hono/dev-reload`.
+ */
+
+import type { Context } from 'hono'
+
+export interface CreateDevReloaderOptions {
+  /** Override the dev gate. Defaults to `process.env.NODE_ENV !== 'production'`. */
+  enabled?: boolean
+}
+
+const HEARTBEAT_MS = 5000
+
+// Generated once per Worker isolate. A cold start or code change rotates this,
+// which is exactly the signal we want to surface to the browser.
+const BOOT_ID = generateBootId()
+
+function generateBootId(): string {
+  try {
+    return crypto.randomUUID()
+  } catch {
+    return Date.now().toString(36) + Math.random().toString(36).slice(2, 10)
+  }
+}
+
+function isDevDefault(): boolean {
+  return process.env.NODE_ENV !== 'production'
+}
+
+/**
+ * Hono route handler that streams Server-Sent Events. Returns 404 in
+ * production (`NODE_ENV=production`) unless `enabled` is set explicitly.
+ */
+export function createDevReloader(
+  options: CreateDevReloaderOptions = {},
+): (c: Context) => Response | Promise<Response> {
+  const { enabled = isDevDefault() } = options
+
+  return (c: Context) => {
+    if (!enabled) return c.notFound()
+
+    const lastEventId = (c.req.header('Last-Event-ID') ?? '').trim()
+    const signal = c.req.raw.signal
+
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        const encoder = new TextEncoder()
+        const send = (chunk: string) => {
+          try {
+            controller.enqueue(encoder.encode(chunk))
+          } catch {
+            // Stream already closed (client disconnected).
+          }
+        }
+
+        send(`retry: 1000\n\n`)
+        // On reconnect with a different boot id, the Worker restarted (or was
+        // evicted from the isolate cache) while the client was disconnected —
+        // signal a reload so the browser picks up any new code + assets.
+        const event = lastEventId && lastEventId !== BOOT_ID ? 'reload' : 'hello'
+        send(`event: ${event}\nid: ${BOOT_ID}\ndata: ${BOOT_ID}\n\n`)
+
+        const heartbeat = setInterval(() => send(`: hb\n\n`), HEARTBEAT_MS)
+        const onAbort = () => {
+          clearInterval(heartbeat)
+          try { controller.close() } catch { /* already closed */ }
+        }
+        if (signal.aborted) onAbort()
+        else signal.addEventListener('abort', onAbort, { once: true })
+      },
+    })
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+      },
+    })
+  }
+}

package/src/dev.tsx

@@ -0,0 +1,146 @@
+/**
+ * BarefootJS Dev Reloader (Hono, Node-side)
+ *
+ * `createDevReloader` turns `bf build --watch`'s sentinel file
+ * (`<distDir>/.dev/build-id`) into an SSE stream:
+ *
+ *   [bf build --watch] → writes `<distDir>/.dev/build-id` after each successful build
+ *   [createDevReloader]      → watches that file, streams SSE `event: reload`
+ *
+ * Mount it on a Hono route in the generated app; the matching browser-
+ * side subscriber (`<DevReload />`) lives in the project itself (see
+ * the hono-node scaffold's `dev-reload.tsx`) so its endpoint URL and
+ * reconnect behavior are an in-tree edit.
+ *
+ * ```ts
+ * // factory.ts
+ * import { createDevReloader } from '@barefootjs/hono/dev'
+ * app.get('/_bf/reload', createDevReloader({ distDir: './dist' }))
+ * ```
+ *
+ * Disabled (404) when `NODE_ENV === 'production'` unless `enabled: true`
+ * is passed explicitly.
+ */
+
+import type { Context } from 'hono'
+import { mkdir, readFile, watch } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+export interface CreateDevReloaderOptions {
+  /** Directory that `bf build` writes output into (contains `.dev/build-id`). */
+  distDir: string
+  /** Override the dev gate. Defaults to `process.env.NODE_ENV !== 'production'`. */
+  enabled?: boolean
+}
+
+// Sentinel path contract with `@barefootjs/cli`. These values must match
+// `DEV_SENTINEL_SUBDIR` / `DEV_SENTINEL_FILENAME` in `packages/cli/src/lib/build.ts`
+// — duplicated intentionally to avoid a runtime dep on the CLI.
+const DEV_SUBDIR = '.dev'
+const BUILD_ID_FILE = 'build-id'
+/**
+ * Heartbeat interval for idle keepalive. Must stay comfortably under Bun's
+ * default 10s idleTimeout — otherwise the server would close a quiet SSE
+ * stream and the browser would EventSource-reconnect every cycle, which can
+ * lose a rebuild event emitted in the gap between close and reconnect.
+ */
+const HEARTBEAT_MS = 5000
+
+function isDevDefault(): boolean {
+  return process.env.NODE_ENV !== 'production'
+}
+
+/**
+ * Hono route handler that streams Server-Sent Events and emits `reload` every
+ * time `<distDir>/.dev/build-id` is written. Disabled (404) in production.
+ */
+export function createDevReloader(
+  options: CreateDevReloaderOptions,
+): (c: Context) => Response | Promise<Response> {
+  const { distDir, enabled = isDevDefault() } = options
+
+  return async (c: Context) => {
+    if (!enabled) return c.notFound()
+
+    const devDir = resolve(distDir, DEV_SUBDIR)
+    // Ensure the directory exists so fs.watch doesn't ENOENT before the first build.
+    await mkdir(devDir, { recursive: true })
+
+    const buildIdPath = resolve(devDir, BUILD_ID_FILE)
+    const signal = c.req.raw.signal
+    // If the client reconnects with Last-Event-ID (the build-id it last saw)
+    // and the current build-id is newer, a rebuild happened while it was
+    // disconnected — recover by firing `reload` immediately instead of `hello`.
+    const lastEventId = (c.req.header('Last-Event-ID') ?? '').trim()
+
+    const readBuildId = async (): Promise<string> => {
+      try {
+        return (await readFile(buildIdPath, 'utf8')).trim()
+      } catch {
+        return ''
+      }
+    }
+
+    const stream = new ReadableStream<Uint8Array>({
+      async start(controller) {
+        const encoder = new TextEncoder()
+        const send = (chunk: string) => {
+          try {
+            controller.enqueue(encoder.encode(chunk))
+          } catch {
+            // Stream already closed (client disconnected).
+          }
+        }
+
+        send(`retry: 1000\n\n`)
+        let lastSentId = ''
+        const initialId = await readBuildId()
+        if (initialId) {
+          lastSentId = initialId
+          const event = lastEventId && lastEventId !== initialId ? 'reload' : 'hello'
+          send(`event: ${event}\nid: ${initialId}\ndata: ${initialId}\n\n`)
+        }
+
+        // Heartbeat keeps the connection under Bun's idleTimeout so that a
+        // silent period between builds doesn't close the socket (which would
+        // otherwise race with in-flight rebuilds and drop `reload` events).
+        const heartbeat = setInterval(() => send(`: hb\n\n`), HEARTBEAT_MS)
+
+        try {
+          // Watch the parent directory: the build-id file may not exist yet,
+          // and `fs.watch` on a missing path throws.
+          const iter = watch(devDir, { signal })
+          for await (const event of iter) {
+            if (event.filename !== BUILD_ID_FILE) continue
+            const id = await readBuildId()
+            if (!id || id === lastSentId) continue
+            lastSentId = id
+            send(`event: reload\nid: ${id}\ndata: ${id}\n\n`)
+          }
+        } catch (err) {
+          const name = (err as { name?: string } | undefined)?.name
+          if (name !== 'AbortError') {
+            const message = (err as Error).message ?? 'watch error'
+            send(`event: error\ndata: ${JSON.stringify(message)}\n\n`)
+          }
+        } finally {
+          clearInterval(heartbeat)
+          try { controller.close() } catch { /* already closed */ }
+        }
+      },
+      cancel() {
+        // Client disconnected; fs.watch will unwind via `signal`.
+      },
+    })
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+      },
+    })
+  }
+}
+

package/src/dialog-context.tsx

@@ -0,0 +1,44 @@
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+//
+// Pragmas as line-comments above the JSDoc; see scripts.tsx for the rationale.
+
+/**
+ * Dialog Context
+ *
+ * Provides scopeId sharing between Dialog components.
+ * DialogRoot sets the context, child components (DialogOverlay, DialogContent) read it.
+ *
+ * Usage:
+ * ```tsx
+ * import { DialogContext, useDialogContext } from '@barefootjs/hono'
+ *
+ * // In DialogRoot
+ * <DialogContext.Provider value={{ scopeId }}>
+ *   {children}
+ * </DialogContext.Provider>
+ *
+ * // In DialogOverlay/DialogContent
+ * const ctx = useDialogContext()
+ * <Portal scopeId={ctx?.scopeId}>...</Portal>
+ * ```
+ */
+
+import { createContext, useContext } from 'hono/jsx'
+
+export type DialogContextValue = {
+  scopeId: string
+}
+
+/**
+ * Context for sharing scopeId between Dialog components.
+ */
+export const DialogContext = createContext<DialogContextValue | null>(null)
+
+/**
+ * Hook to access Dialog context.
+ * Returns null if not inside a DialogRoot.
+ */
+export function useDialogContext(): DialogContextValue | null {
+  return useContext(DialogContext)
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * BarefootJS Hono Integration
+ *
+ * Provides Hono-specific adapters and utilities for BarefootJS.
+ */
+
+// Hono Adapter for JSX compilation
+export { HonoAdapter, honoAdapter } from './adapter'
+export type { HonoAdapterOptions } from './adapter'
+
+// BfScripts is exported from a separate entry point to avoid JSX runtime issues in tests
+// Usage: import { BfScripts } from '@barefootjs/hono/scripts'
+export type { CollectedScript } from './scripts'
+
+// Portal components for SSR
+// Usage: import { BfPortals, Portal } from '@barefootjs/hono/portals'
+export type { CollectedPortal } from './portals'
+export type { PortalProps } from './portal-ssr'
+
+// Async streaming boundary
+// Usage: import { BfAsync } from '@barefootjs/hono/async'
+export type { BfAsyncProps } from './async'
+
+// Dialog context for scopeId sharing
+// Usage: import { DialogContext, useDialogContext } from '@barefootjs/hono/dialog-context'
+export type { DialogContextValue } from './dialog-context'

package/src/jsx/jsx-dev-runtime/index.ts

@@ -0,0 +1,9 @@
+/**
+ * BarefootJS Hono JSX Extension - Development Runtime
+ *
+ * Re-exports `jsxDEV` / `Fragment` from hono/jsx and surfaces the same
+ * JSX namespace as the production runtime so dev builds see identical types.
+ */
+
+export { jsxDEV, Fragment } from 'hono/jsx/jsx-dev-runtime'
+export type { JSX } from '../jsx-runtime'

package/src/jsx/jsx-runtime/index.ts

@@ -0,0 +1,40 @@
+/**
+ * BarefootJS Hono JSX Extension
+ *
+ * Combines hono/jsx runtime with @barefootjs/jsx type definitions.
+ * - Runtime functions from hono/jsx
+ * - Typed event handlers and IntrinsicElements from @barefootjs/jsx
+ * - JSX.Element from hono/jsx (for Suspense/streaming support)
+ *
+ * Usage in tsconfig.json:
+ *   "jsxImportSource": "@barefootjs/hono/jsx"
+ */
+
+// Runtime functions from hono/jsx.
+export { jsx, jsxs, Fragment, jsxAttr, jsxEscape, jsxTemplate } from 'hono/jsx/jsx-runtime'
+
+// Re-export JSX namespace from @barefootjs/jsx, but override Element type for Hono.
+import type { JSX as BaseJSX } from '@barefootjs/jsx/jsx-runtime'
+
+export declare namespace JSX {
+  // Use Hono's Element type for Suspense/streaming compatibility.
+  type Element = import('hono/jsx/jsx-runtime').JSX.Element
+
+  // Re-use types from @barefootjs/jsx.
+  type IntrinsicElements = BaseJSX.IntrinsicElements
+  type IntrinsicAttributes = BaseJSX.IntrinsicAttributes
+  type ElementChildrenAttribute = BaseJSX.ElementChildrenAttribute
+}
+
+/**
+ * BarefootJS compiler built-in: streaming async boundary.
+ *
+ * The compiler intercepts `<Async fallback={...}>` in JSX source and emits it
+ * as a `<Suspense>` node in the Hono adapter output (IRAsync → renderAsync).
+ * This declaration provides TypeScript types for source files; no runtime
+ * implementation is needed because the compiler replaces it before execution.
+ */
+export declare function Async(props: {
+  fallback: JSX.Element
+  children: JSX.Element | JSX.Element[] | null | undefined
+}): JSX.Element

package/src/portal-ssr.tsx

@@ -0,0 +1,92 @@
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+//
+// Pragmas as line-comments above the JSDoc; see scripts.tsx for the rationale.
+
+/**
+ * Portal Component for SSR
+ *
+ * Renders children to document.body during SSR via BfPortals collection.
+ * On client-side, renders children normally (to be moved by createPortal).
+ *
+ * Usage:
+ * ```tsx
+ * import { Portal } from '@barefootjs/hono'
+ *
+ * function MyDialog({ scopeId }: { scopeId: string }) {
+ *   return (
+ *     <Portal scopeId={scopeId}>
+ *       <div class="dialog">Dialog content</div>
+ *     </Portal>
+ *   )
+ * }
+ * ```
+ */
+
+import { useRequestContext } from 'hono/jsx-renderer'
+import { Fragment } from 'hono/jsx'
+import type { Child } from 'hono/jsx'
+import { collectPortal, isPortalsRendered } from './portals'
+
+let portalCounter = 0
+
+/**
+ * Generate unique portal ID for SSR/hydration matching.
+ * Counter resets per request in production (new context per request).
+ */
+function generatePortalId(): string {
+  return `bf-portal-${++portalCounter}`
+}
+
+/**
+ * Reset portal counter (for testing or explicit reset).
+ */
+export function resetPortalCounter(): void {
+  portalCounter = 0
+}
+
+export interface PortalProps {
+  children: Child
+  scopeId?: string
+}
+
+/**
+ * Portal component that moves children to document.body during SSR.
+ *
+ * During SSR:
+ * - Collects content for BfPortals output (before BfPortals renders)
+ * - Returns placeholder <template> for hydration matching
+ * - If BfPortals already rendered (Suspense), outputs inline
+ *
+ * On client:
+ * - Renders children normally (createPortal moves them later)
+ */
+export function Portal(props: PortalProps) {
+  const portalId = generatePortalId()
+
+  try {
+    // Check if we're in SSR context (will throw if not)
+    useRequestContext()
+
+    if (isPortalsRendered()) {
+      // BfPortals already rendered (e.g., inside Suspense boundary)
+      // Output portal content inline
+      return (
+        <div bf-pi={portalId} bf-po={props.scopeId || ''}>
+          {props.children}
+        </div>
+      )
+    }
+
+    // Collect portal content for BfPortals output
+    collectPortal(portalId, props.scopeId || '', props.children)
+
+    // Return placeholder for hydration matching
+    // Client will find this and know the portal content is at body end
+    return <template bf-pp={portalId} />
+  } catch {
+    // Outside request context (client-side rendering)
+    // Render children normally - they will be moved by createPortal on mount
+    return <Fragment>{props.children}</Fragment>
+  }
+}

package/src/portals.tsx

@@ -0,0 +1,98 @@
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+//
+// Pragmas as line-comments above the JSDoc; see scripts.tsx for the rationale.
+
+/**
+ * BfPortals Component
+ *
+ * Renders collected portal content at the end of the document body.
+ * BarefootJS Portal components collect their content during SSR render,
+ * and this component outputs them all at once to ensure correct positioning.
+ *
+ * Usage:
+ * ```tsx
+ * import { BfPortals } from '@barefootjs/hono'
+ *
+ * <html>
+ *   <body>
+ *     {children}
+ *     <BfPortals />
+ *     <BfScripts />
+ *   </body>
+ * </html>
+ * ```
+ */
+
+import { useRequestContext } from 'hono/jsx-renderer'
+import { Fragment } from 'hono/jsx'
+import type { Child } from 'hono/jsx'
+
+export type CollectedPortal = {
+  id: string
+  scopeId: string
+  content: Child
+}
+
+/**
+ * Collect portal content for SSR output.
+ * Called by Portal component during SSR rendering.
+ */
+export function collectPortal(id: string, scopeId: string, content: Child): void {
+  try {
+    const c = useRequestContext()
+    const portals: CollectedPortal[] = c.get('bfCollectedPortals') || []
+    portals.push({ id, scopeId, content })
+    c.set('bfCollectedPortals', portals)
+  } catch {
+    // Outside request context (client-side) - no-op
+  }
+}
+
+/**
+ * Check if BfPortals has already been rendered.
+ * Used by Portal component to determine if it should output inline.
+ */
+export function isPortalsRendered(): boolean {
+  try {
+    const c = useRequestContext()
+    return c.get('bfPortalsRendered') ?? false
+  } catch {
+    // Outside request context (client-side)
+    return true
+  }
+}
+
+/**
+ * Renders all collected portal content.
+ * Place this component at the end of your <body> element, before BfScripts.
+ *
+ * After rendering, sets 'bfPortalsRendered' flag to true.
+ * Portal components rendered after BfPortals (e.g., inside Suspense boundaries)
+ * will check this flag and output their content inline instead.
+ */
+export function BfPortals() {
+  try {
+    const c = useRequestContext()
+
+    // Mark that BfPortals has been rendered.
+    // Portal components rendered after this point (e.g., inside Suspense)
+    // should output their content inline.
+    c.set('bfPortalsRendered', true)
+
+    const portals: CollectedPortal[] = c.get('bfCollectedPortals') || []
+
+    return (
+      <Fragment>
+        {portals.map(({ id, scopeId, content }) => (
+          <div key={id} bf-pi={id} bf-po={scopeId}>
+            {content}
+          </div>
+        ))}
+      </Fragment>
+    )
+  } catch {
+    // Context unavailable (e.g., not using jsxRenderer)
+    return null
+  }
+}