@barefootjs/client 0.1.0

package/dist/runtime/streaming.d.ts

@@ -0,0 +1,36 @@
+/**
+ * BarefootJS - Out-of-Order Streaming
+ *
+ * Client-side resolver for OOS (Out-of-Order Streaming) SSR.
+ * Handles swapping fallback content with resolved content that arrives
+ * via chunked HTTP responses.
+ *
+ * Protocol:
+ * 1. Server sends HTML with fallback placeholders: <div bf-async="a0">...</div>
+ * 2. As async data resolves, server appends chunks:
+ *    <template bf-async-resolve="a0">...resolved...</template>
+ *    <script>__bf_swap("a0")</script>
+ * 3. This module swaps fallback → resolved content and triggers hydration.
+ */
+/**
+ * Swap a streaming fallback placeholder with its resolved content.
+ *
+ * Finds the placeholder element (`[bf-async="<id>"]`) and the resolve
+ * template (`<template bf-async-resolve="<id>">`), replaces the placeholder's
+ * children with the resolved content, then triggers hydration.
+ *
+ * @param id - The async boundary ID (e.g., "a0")
+ */
+export declare function __bf_swap(id: string): void;
+/**
+ * Install the global streaming resolver.
+ *
+ * Makes `__bf_swap` available as `window.__bf_swap` so that inline
+ * `<script>__bf_swap("a0")</script>` tags in streaming chunks can call it.
+ *
+ * Also exposes `window.__bf_hydrate` for manual re-hydration triggers.
+ *
+ * Call this once, early in the page (before any streaming chunks arrive).
+ */
+export declare function setupStreaming(): void;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/runtime/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/runtime/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAmB1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAMrC"}

package/dist/runtime/style.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Style attribute helpers for client-side DOM updates.
+ */
+/**
+ * Convert a style value (string or object) to a CSS string, or null to remove the attribute.
+ *
+ * - null/undefined → null (remove the attribute)
+ * - string → the string as-is
+ * - object → camelCase keys converted to kebab-case, joined with semicolons
+ *
+ * @example
+ * styleToCss({ backgroundColor: 'red', fontSize: '16px' }) // "background-color:red;font-size:16px"
+ * styleToCss('color:red')   // "color:red"
+ * styleToCss(null)          // null
+ */
+export declare function styleToCss(value: unknown): string | null;
+//# sourceMappingURL=style.d.ts.map

package/dist/runtime/style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style.d.ts","sourceRoot":"","sources":["../../src/runtime/style.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUxD"}

package/dist/runtime/template.d.ts

@@ -0,0 +1,39 @@
+/**
+ * BarefootJS - Template Registry
+ *
+ * Stores template functions for client-side component creation.
+ * Templates generate HTML strings from props, used by createComponent().
+ */
+/**
+ * Template function type - generates HTML string from props
+ */
+export type TemplateFn = (props: Record<string, unknown>) => string;
+/**
+ * Register a template function for a component.
+ *
+ * @param name - Component name (e.g., 'TodoItem')
+ * @param templateFn - Function that generates HTML from props
+ *
+ * @example
+ * registerTemplate('TodoItem', (props) => `
+ *   <li class="${props.done ? 'done' : ''}">
+ *     <span>${props.text}</span>
+ *   </li>
+ * `)
+ */
+export declare function registerTemplate(name: string, templateFn: TemplateFn): void;
+/**
+ * Get a registered template function by component name.
+ *
+ * @param name - Component name
+ * @returns Template function or undefined if not registered
+ */
+export declare function getTemplate(name: string): TemplateFn | undefined;
+/**
+ * Check if a template is registered for a component.
+ *
+ * @param name - Component name
+ * @returns true if template is registered
+ */
+export declare function hasTemplate(name: string): boolean;
+//# sourceMappingURL=template.d.ts.map

package/dist/runtime/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/runtime/template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAA;AAOnE;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/dist/runtime/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * BarefootJS - Core Types
+ *
+ * Shared type definitions for component initialization and registration.
+ */
+/**
+ * Component init function type.
+ * Takes the scope element and props, initializes the component
+ * by setting up event handlers, effects, and reactive bindings.
+ */
+export type InitFn = (scope: Element, props: Record<string, unknown>) => void;
+/**
+ * Component definition.
+ * Bundles the init function with optional template and scope metadata.
+ */
+export interface ComponentDef {
+    /** Component name (e.g., 'Counter'). Used for scope ID generation. */
+    name?: string;
+    /** Init function that hydrates a scope element */
+    init: InitFn;
+    /** Template function for client-side component creation */
+    template?: (props: Record<string, unknown>) => string;
+    /** When true, use comment-based scope hydration (fragment roots) */
+    comment?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;AAE7E;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAA;IACrD,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB"}

package/dist/shims.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Browser-only API shims.
+ *
+ * These functions have real implementations in `./runtime/` that the
+ * compiler emits for `'use client'` components. The exports here exist
+ * for type-checking in user source files.
+ *
+ * If one of these ever runs, it means a `'use client'` component was
+ * executed without going through the compiler — or a non-client file
+ * slipped past the `MISSING_USE_CLIENT` check. Either way, it's a bug.
+ */
+import type { Context } from './context';
+import type { Portal, PortalChildren, PortalOptions } from './runtime/portal';
+export type { Portal, PortalChildren, PortalOptions, Renderable } from './runtime/portal';
+export declare function useContext<T>(_context: Context<T>): T;
+export declare function provideContext<T>(_context: Context<T>, _value: T): void;
+export declare function createPortal(_children: PortalChildren, _container?: Element, _options?: PortalOptions): Portal;
+export declare function isSSRPortal(_element: HTMLElement): boolean;
+export declare function findSiblingSlot(_el: HTMLElement, _slotSelector: string): HTMLElement | null;
+export declare function cleanupPortalPlaceholder(_portalId: string): void;
+//# sourceMappingURL=shims.d.ts.map

package/dist/shims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../src/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAE7E,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AASzF,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAErD;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAEvE;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,UAAU,CAAC,EAAE,OAAO,EACpB,QAAQ,CAAC,EAAE,aAAa,GACvB,MAAM,CAER;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAE1D;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,WAAW,EAChB,aAAa,EAAE,MAAM,GACpB,WAAW,GAAG,IAAI,CAEpB;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEhE"}

package/dist/slot.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Slot marker for JSX props that contain components.
+ *
+ * When a caller passes `<Button />` inside a JSX prop, the compiler wraps
+ * the value with `__slot()`. The callee's text effect checks `__isSlot`
+ * and skips the destructive `nodeValue = String(...)` update, preserving
+ * the server-rendered DOM for hydration.
+ */
+export interface SlotMarker {
+    __isSlot: true;
+    toString(): string;
+}
+export declare function __slot(thunk: () => unknown): SlotMarker;
+//# sourceMappingURL=slot.d.ts.map

package/dist/slot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot.d.ts","sourceRoot":"","sources":["../src/slot.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,IAAI,CAAA;IACd,QAAQ,IAAI,MAAM,CAAA;CACnB;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,OAAO,GAAG,UAAU,CAQvD"}

package/dist/split-props.d.ts

@@ -0,0 +1,26 @@
+/**
+ * BarefootJS - splitProps
+ *
+ * SolidJS-compatible utility for splitting a props object into local and rest.
+ * Uses Proxy to preserve getter-based reactivity.
+ *
+ * @example
+ * ```tsx
+ * import { splitProps } from '@barefootjs/client'
+ *
+ * function Checkbox(props: CheckboxProps) {
+ *   const [local, rest] = splitProps(props, ['checked', 'onCheckedChange'])
+ *   return <button {...rest} aria-checked={local.checked} />
+ * }
+ * ```
+ */
+/**
+ * Split a props object into two: one with the specified keys, one with the rest.
+ * Both returned objects use Proxy to defer reads, preserving reactive tracking.
+ *
+ * @param props - The source props object
+ * @param keys - Keys to extract into the first (local) object
+ * @returns A tuple [local, rest] where local has the specified keys and rest has everything else
+ */
+export declare function splitProps<T extends Record<string, unknown>, K extends (keyof T)[]>(props: T, keys: K): [Pick<T, K[number]>, Omit<T, K[number]>];
+//# sourceMappingURL=split-props.d.ts.map

package/dist/split-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split-props.d.ts","sourceRoot":"","sources":["../src/split-props.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAErB,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,CAAC,GACN,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAsD1C"}

package/dist/unwrap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * BarefootJS - Unwrap Utility
+ *
+ * Unwrap a prop value that may be a getter function.
+ * When props are passed from parent to child components, reactive values
+ * are wrapped as getter functions to maintain reactivity.
+ * This helper unwraps them transparently.
+ */
+/**
+ * Unwrap a prop value that may be a getter function.
+ *
+ * @param prop - The prop value (may be a value or a getter function)
+ * @returns The unwrapped value
+ */
+export declare function unwrap<T>(prop: T | (() => T)): T;
+//# sourceMappingURL=unwrap.d.ts.map

package/dist/unwrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unwrap.d.ts","sourceRoot":"","sources":["../src/unwrap.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAEhD"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@barefootjs/client",
+  "version": "0.1.0",
+  "description": "BarefootJS client package: reactive primitives (SSR-safe) plus browser runtime under the `/runtime` subpath (compiler target)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./reactive": {
+      "types": "./dist/reactive.d.ts",
+      "import": "./dist/reactive.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./runtime/standalone": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/standalone.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/reactive.ts --outdir ./dist --format esm && bun build ./src/index.ts --outdir ./dist --format esm --external '@barefootjs/client/reactive' && bun build ./src/runtime/index.ts --outdir ./dist/runtime --format esm --external '@barefootjs/client/reactive' && bun build ./src/runtime/index.ts --outfile ./dist/runtime/standalone.js --format esm && bun build ./src/build.ts --outdir ./dist --format esm --external '@barefootjs/jsx'",
+    "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
+    "test": "bun test",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "reactive",
+    "signals",
+    "dom",
+    "runtime",
+    "barefoot"
+  ],
+  "author": "kobaken <kentafly88@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/piconic-ai/barefootjs",
+    "directory": "packages/client"
+  },
+  "dependencies": {
+    "@barefootjs/shared": "workspace:*"
+  },
+  "peerDependencies": {
+    "@barefootjs/jsx": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@barefootjs/jsx": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@barefootjs/jsx": "workspace:*",
+    "@happy-dom/global-registrator": "^20.0.11",
+    "typescript": "^5.0.0"
+  }
+}

package/src/build.ts

@@ -0,0 +1,92 @@
+// CSR build config factory for `barefoot.config.ts`.
+//
+// CSR (client-side rendering) projects emit client JS only — no marked
+// templates, no SSR. Pair this config with `render()` from
+// `@barefootjs/client/runtime` on the page.
+//
+// The compiler still needs a `TemplateAdapter` to drive IR→client-JS
+// codegen (the analyzer consults `acceptsTemplateCall` when deciding
+// template-scope vs init-scope placement). The marked templates the
+// adapter would produce are simply not written to disk. The default
+// `CSRAdapter` is the minimum that satisfies the interface — its
+// `generate()` returns an empty `AdapterOutput` and the build
+// pipeline drops the empty marked-template file at the
+// `clientOnly` gate.
+//
+// (Pre-1.0 this was `HonoAdapter` from `@barefootjs/hono/adapter`,
+// which pulled the entire Hono package into a CSR app's
+// `node_modules` for output that was always thrown away. See
+// `csr-adapter.ts` for the rationale on the new in-package adapter.)
+
+import type {
+  BarefootPaths,
+  BundleEntry,
+  ExternalSpec,
+  OutputLayout,
+  PostBuildContext,
+  TemplateAdapter,
+} from '@barefootjs/jsx'
+import { CSRAdapter } from './csr-adapter'
+import type { CSRAdapterOptions } from './csr-adapter'
+
+export interface CSRBuildOptions {
+  /** Project layout paths consumed by registry tooling. */
+  paths?: BarefootPaths
+  /** Source component directories relative to the config file. */
+  components?: string[]
+  /** Output directory relative to the config file. */
+  outDir?: string
+  /** Minify client JS output. */
+  minify?: boolean
+  /** Add content hash to client JS filenames. */
+  contentHash?: boolean
+  /** Custom output directory layout. */
+  outputLayout?: OutputLayout
+  /** Post-build hook called after minification, before manifest write. */
+  postBuild?: (ctx: PostBuildContext) => Promise<void> | void
+  /** Vendor packages to split out as separately-cached browser chunks. */
+  externals?: Record<string, ExternalSpec>
+  /** URL base path for vendor chunks in the emitted importmap. */
+  externalsBasePath?: string
+  /** Additional entry points to bundle with esbuild directly. */
+  bundleEntries?: BundleEntry[]
+  /**
+   * Override the compiler adapter. The marked templates this adapter
+   * generates are discarded in CSR mode — set this only if you need
+   * a different `TemplateAdapter` (e.g. a custom test adapter).
+   */
+  adapter?: TemplateAdapter
+  /** Options forwarded to the default `CSRAdapter`. Ignored when `adapter` is set. */
+  adapterOptions?: CSRAdapterOptions
+}
+
+/**
+ * Create a BarefootBuildConfig for CSR projects.
+ *
+ * Uses structural typing — does not import `BarefootBuildConfig` to avoid
+ * a circular dependency between `@barefootjs/client` and `@barefootjs/cli`.
+ */
+export function createConfig(options: CSRBuildOptions = {}) {
+  // `name` defaults to `'csr'` inside `CSRAdapter`; a caller-supplied
+  // `adapterOptions.name` (or a fully-custom `adapter`) wins, matching
+  // the pre-decoupling behaviour where `bf build`'s `Adapter: …`
+  // banner reflected the option override.
+  const adapter = options.adapter ?? new CSRAdapter(options.adapterOptions)
+  return {
+    adapter,
+    paths: options.paths,
+    components: options.components,
+    outDir: options.outDir,
+    minify: options.minify,
+    contentHash: options.contentHash,
+    clientOnly: true,
+    externals: options.externals,
+    externalsBasePath: options.externalsBasePath,
+    bundleEntries: options.bundleEntries,
+    outputLayout: options.outputLayout,
+    postBuild: options.postBuild,
+  }
+}
+
+export { CSRAdapter } from './csr-adapter'
+export type { CSRAdapterOptions } from './csr-adapter'

package/src/context.ts

@@ -0,0 +1,33 @@
+/**
+ * Context API: pure metadata portion.
+ *
+ * `createContext` is DOM-free and safe to use anywhere (including SSR).
+ * The DOM-bound operations (`useContext`, `provideContext`) live in
+ * `./runtime/context.ts` and are emitted by the compiler for `'use client'`
+ * components.
+ */
+
+export type Context<T> = {
+  readonly id: symbol
+  readonly defaultValue: T | undefined
+  /** JSX Provider component. Compiled to provideContext() by the compiler. */
+  readonly Provider: (props: { value: T; children?: unknown }) => unknown
+}
+
+/**
+ * Create a new context with an optional default value.
+ *
+ * `useContext()` returns the nearest provider value, then the default,
+ * then `undefined`. It never throws — guard with optional chaining.
+ */
+export function createContext<T>(defaultValue?: T): Context<T> {
+  return {
+    id: Symbol(),
+    defaultValue,
+    // Provider is compiled away by the JSX compiler into provideContext() calls.
+    // This runtime stub exists only for TypeScript type checking.
+    Provider: (() => {
+      throw new Error('Context.Provider should be compiled away')
+    }) as Context<T>['Provider'],
+  }
+}

package/src/csr-adapter.ts

@@ -0,0 +1,134 @@
+// Minimal `TemplateAdapter` used by `@barefootjs/client/build`'s
+// `createConfig` for CSR projects.
+//
+// CSR builds emit client JS only — the marked-template output the
+// `TemplateAdapter` contract requires is discarded by the build
+// pipeline when `clientOnly: true` (see `cli/src/lib/build.ts`, the
+// `!config.clientOnly && markedTemplates.length > 0` gate). All this
+// adapter has to do is satisfy the interface so the compiler's
+// pass-2 loop can call `adapter.generate()` without crashing.
+//
+// Historically `createConfig` reused `HonoAdapter` from
+// `@barefootjs/hono/adapter` here as a "broad-acceptance JS template
+// runtime". That pulled the entire Hono package into a CSR app's
+// `node_modules` for an adapter whose every output was thrown away
+// — confusing for users who picked CSR specifically to avoid an SSR
+// framework dependency. Replacing it with this in-package adapter
+// deletes the transitive Hono dep and keeps the analyzer-side
+// behaviour identical (`acceptsTemplateCall: () => true`).
+//
+// What we still need from a "template adapter" in CSR mode:
+//
+//   - `acceptsTemplateCall: () => true`. This is consulted by the
+//     IR analyzer + relocate pipeline (#1187 phase 3) when
+//     deciding whether a call expression can live at template
+//     scope vs init scope. The CSR "template" runs in the browser
+//     via `@barefootjs/client/runtime`, so any synchronous JS call
+//     is valid there — same contract as Hono SSR, where the broad
+//     predicate originally lived. Without this the analyzer would
+//     conservatively force calls into init scope and emit different
+//     (less efficient) client JS.
+//
+//   - Sentinel `generate()` returning an empty `AdapterOutput`. The
+//     compiler's pass-2 unconditionally calls `adapter.generate()`
+//     to assemble the marked-template module string; in CSR mode
+//     every field of that string is discarded before write, so we
+//     just hand back empty strings and let the pipeline drop the
+//     empty `markedTemplate` file at the gate.
+//
+//   - No-op render methods. The `TemplateAdapter` interface lists
+//     them (`renderNode`, `renderElement`, etc.) but they are only
+//     ever invoked from inside an adapter's own `generate()`. Since
+//     ours returns early, these are never reached at runtime — they
+//     exist purely to satisfy the contract.
+//
+// Everything else (`clientShimSource`, `templatePrimitives`,
+// `generateSignalInitializers`, ...) is optional on `TemplateAdapter`
+// and intentionally omitted: CSR has no SSR templates to shim into,
+// no DSL-side primitive registry, and no init block to emit.
+
+import type { AdapterOutput, TemplateSections } from '@barefootjs/jsx'
+import { BaseAdapter } from '@barefootjs/jsx'
+
+export interface CSRAdapterOptions {
+  /**
+   * Display name surfaced through `TemplateAdapter.name` — read by
+   * `bf build` for its `Adapter: …` banner. Defaults to `'csr'`.
+   */
+  name?: string
+}
+
+// Frozen so a single shared sentinel can be returned from every
+// `generate()` call without risking that a downstream consumer
+// mutates it and bleeds state across compilations. `Object.freeze`
+// is shallow, so we freeze both the outer `AdapterOutput` and the
+// nested `sections` object — those are the two objects callers
+// could write to (string/extension fields are primitives).
+const EMPTY_SECTIONS: TemplateSections = Object.freeze({
+  imports: '',
+  types: '',
+  component: '',
+  defaultExport: '',
+})
+
+const EMPTY_OUTPUT: AdapterOutput = Object.freeze({
+  template: '',
+  sections: EMPTY_SECTIONS,
+  extension: '.tsx',
+})
+
+export class CSRAdapter extends BaseAdapter {
+  name: string
+  extension = '.tsx'
+
+  // Broad acceptance — matches Hono's contract, see the comment at
+  // the top of this file for why CSR shares it.
+  acceptsTemplateCall = (): boolean => true
+
+  constructor(options: CSRAdapterOptions = {}) {
+    super()
+    this.name = options.name ?? 'csr'
+  }
+
+  // Sentinel: the marked-template is discarded in clientOnly mode,
+  // so a single shared empty `AdapterOutput` (frozen — see
+  // `EMPTY_OUTPUT` above) is enough. Re-creating per call would just
+  // allocate garbage.
+  generate(): AdapterOutput {
+    return EMPTY_OUTPUT
+  }
+
+  // The render methods below would only ever be called from inside
+  // an adapter's own `generate()`; since ours returns early, none of
+  // them run at compile time. They exist purely to satisfy
+  // `BaseAdapter`'s abstract surface. `BaseAdapter` already provides
+  // a sensible default `renderAsync` that delegates to `renderNode`
+  // + `renderChildren`, so we inherit that for free.
+  renderNode(): string {
+    return ''
+  }
+  renderElement(): string {
+    return ''
+  }
+  renderExpression(): string {
+    return ''
+  }
+  renderConditional(): string {
+    return ''
+  }
+  renderLoop(): string {
+    return ''
+  }
+  renderComponent(): string {
+    return ''
+  }
+  renderScopeMarker(): string {
+    return ''
+  }
+  renderSlotMarker(): string {
+    return ''
+  }
+  renderCondMarker(): string {
+    return ''
+  }
+}

package/src/forward-props.ts

@@ -0,0 +1,43 @@
+/**
+ * BarefootJS - Forward Props Helper
+ *
+ * Forwards spread props to child components using getter delegation
+ * to preserve reactivity. Used by compiler-generated code for
+ * components with {...rest} spread on child components.
+ */
+
+/**
+ * Create a props object that merges explicit overrides with forwarded source props.
+ * Preserves getter-based reactivity from both overrides and source.
+ *
+ * @param source - The parent props object (reads are deferred via getters)
+ * @param overrides - Object literal with getters/values that override source props
+ * @param excludeKeys - Keys from source to exclude (already destructured)
+ */
+export function forwardProps<T extends Record<string, unknown>>(
+  source: T,
+  overrides: Record<string, unknown>,
+  excludeKeys: string[]
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  const exclude = new Set(excludeKeys)
+
+  // Copy overrides preserving getter descriptors
+  const descs = Object.getOwnPropertyDescriptors(overrides)
+  for (const key of Object.keys(descs)) {
+    Object.defineProperty(result, key, { ...descs[key], enumerable: true, configurable: true })
+  }
+
+  // Forward remaining source props via getters (deferred read = reactive)
+  for (const key of Object.keys(source)) {
+    if (exclude.has(key) || key in result) continue
+    const k = key
+    Object.defineProperty(result, k, {
+      get: () => (source as Record<string, unknown>)[k],
+      enumerable: true,
+      configurable: true,
+    })
+  }
+
+  return result
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+// Reactive primitives live at the shared `@barefootjs/client/reactive`
+// subpath so main and the `/runtime` entry point reference a single
+// physical module — see src/runtime/index.ts for the rationale.
+export {
+  createSignal,
+  createEffect,
+  createDisposableEffect,
+  createMemo,
+  createRoot,
+  onCleanup,
+  onMount,
+  untrack,
+  batch,
+  type Reactive,
+  type Signal,
+  type Memo,
+  type CleanupFn,
+  type EffectFn,
+} from '@barefootjs/client/reactive'
+
+export { splitProps } from './split-props'
+
+export { __slot, type SlotMarker } from './slot'
+
+export { forwardProps } from './forward-props'
+
+export { unwrap } from './unwrap'
+
+export { createContext, type Context } from './context'
+
+export {
+  useContext,
+  provideContext,
+  createPortal,
+  isSSRPortal,
+  findSiblingSlot,
+  cleanupPortalPlaceholder,
+  type Portal,
+  type PortalChildren,
+  type PortalOptions,
+  type Renderable,
+} from './shims'