@barefootjs/jsx 0.30.6 → 0.31.0

package/src/__tests__/bf050-single-multi-symmetry.test.ts

@@ -0,0 +1,118 @@
+/**
+ * BF050 single/multi symmetry (#2537).
+ *
+ * BF050 ("shared ts.Program required") exists so strict builds fail loudly
+ * instead of silently relying on the per-file Program fallback, whose
+ * virtual host can fail module resolution and collapse Reactive<T> brands
+ * to `any`. The single-component path always emitted it for a
+ * brand-package import compiled without `options.program` — but the
+ * multi-component path pre-builds a per-file Program to amortize it across
+ * siblings and passed it down as if it were shared, suppressing the
+ * diagnostic. Same import, opposite verdicts, decided by how many
+ * components share the file.
+ *
+ * Post-fix, BF050 keys off whether the CALLER supplied `options.program`
+ * (`analyzeComponent`'s `programIsShared`), in both paths — and a
+ * multi-component file reports it once, not once per sibling.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import ts from 'typescript'
+import path from 'node:path'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+const MULTI_SOURCE = `
+  'use client'
+  import { createForm } from '@barefootjs/form'
+
+  export function ProfileForm() {
+    const form = createForm()
+    return <form><input /></form>
+  }
+
+  export function AccountForm() {
+    const form = createForm()
+    return <form><button>Save</button></form>
+  }
+`
+
+const SINGLE_SOURCE = `
+  'use client'
+  import { createForm } from '@barefootjs/form'
+
+  export function ProfileForm() {
+    const form = createForm()
+    return <form><input /></form>
+  }
+`
+
+function bf050s(source: string, program?: ts.Program) {
+  const result = compileJSX(source, '/virtual/forms.tsx', { adapter, program })
+  return result.errors.filter(e => e.code === 'BF050')
+}
+
+/**
+ * A minimal Program whose roots include the component file — enough for
+ * `analyzeComponent` to accept it as the shared Program (text must match).
+ * Brand resolution isn't the point here (the import won't resolve from
+ * /virtual); BF050 only keys off whether a shared Program was supplied.
+ */
+function inMemoryProgram(source: string): ts.Program {
+  const filePath = path.resolve('/virtual/forms.tsx')
+  const compilerOptions: ts.CompilerOptions = {
+    target: ts.ScriptTarget.Latest,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    jsx: ts.JsxEmit.ReactJSX,
+    strict: true,
+    skipLibCheck: true,
+    noEmit: true,
+  }
+  const defaultHost = ts.createCompilerHost(compilerOptions)
+  const host: ts.CompilerHost = {
+    ...defaultHost,
+    getSourceFile(fileName, languageVersion) {
+      if (path.resolve(fileName) === filePath) {
+        return ts.createSourceFile(fileName, source, languageVersion, true, ts.ScriptKind.TSX)
+      }
+      return defaultHost.getSourceFile(fileName, languageVersion)
+    },
+    fileExists(fileName) {
+      return path.resolve(fileName) === filePath || defaultHost.fileExists(fileName)
+    },
+    readFile(fileName) {
+      if (path.resolve(fileName) === filePath) return source
+      return defaultHost.readFile(fileName)
+    },
+  }
+  return ts.createProgram([filePath], compilerOptions, host)
+}
+
+describe('BF050 fires symmetrically for single- and multi-component files', () => {
+  test('single-component brand import without options.program: BF050', () => {
+    expect(bf050s(SINGLE_SOURCE)).toHaveLength(1)
+  })
+
+  test('multi-component brand import without options.program: BF050 — the per-file amortization no longer masks it', () => {
+    expect(bf050s(MULTI_SOURCE)).toHaveLength(1)
+  })
+
+  test('multi-component: exactly ONE BF050 for the file, not one per sibling component', () => {
+    // Covered by the length assertion above, but pinned separately so a
+    // future "just push ctx.errors" refactor that reintroduces per-sibling
+    // duplicates fails a test whose NAME says what broke.
+    const errors = bf050s(MULTI_SOURCE)
+    expect(errors.length).toBeLessThanOrEqual(1)
+  })
+
+  test('single-component with a caller-supplied shared Program: no BF050', () => {
+    expect(bf050s(SINGLE_SOURCE, inMemoryProgram(SINGLE_SOURCE))).toHaveLength(0)
+  })
+
+  test('multi-component with a caller-supplied shared Program: no BF050', () => {
+    expect(bf050s(MULTI_SOURCE, inMemoryProgram(MULTI_SOURCE))).toHaveLength(0)
+  })
+})

package/src/__tests__/client-js-generation.test.ts

@@ -2845,7 +2845,11 @@ describe('Client JS generation', () => {
       const result = compileJSX(source, 'Probe.tsx', { adapter })
       expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
       const js = result.files.find(f => f.type === 'clientJs')!.content
-      expect(js).toContain('const size = _p.size ?? 5')
+      // The destructure default rides the signal seed (and its controlled
+      // effect) — the standalone `const size = …` extraction is pruned when
+      // nothing else in the init reads it.
+      expect(js).toContain('_p.size ?? 5')
+      expect(js).not.toContain('_p.size ?? 0')
     })
   })
 })

package/src/__tests__/doc-examples.test.ts

@@ -304,7 +304,11 @@ const PAGES: PageSpec[] = [
   { path: 'core/adapters/hono-adapter.md' },
   { path: 'core/adapters/go-template-adapter.md' },
   { path: 'core/adapters/custom-adapter.md' },
-  { path: 'core/advanced/code-splitting.md' },
+  // `core/advanced/code-splitting.md` is deliberately absent: it documents
+  // stock Vite/Rollup build config (`manualChunks`) and carries no
+  // component code, while this extractor only reads ```tsx fences. Adding
+  // a token component there purely to keep the page listed here would
+  // hollow out the check rather than extend it.
   { path: 'core/advanced/compiler-internals.md' },
   // `core/advanced/error-codes.md` is handled by the per-BFxxx
   // matcher (see bottom of file) rather than the general extractor:

package/src/__tests__/prune-unused-prop-extractions.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Regression: the init body must not eagerly read props it never uses.
+ *
+ * Props arrive as getters over the parent's reactive state, and a
+ * slot-children getter instantiates child components when read — so a
+ * stray `const children = _p.children` in a wrapper's init creates a
+ * SECOND child instance next to the parent's own `upsertChild` wiring
+ * (double event listeners; a Checkbox toggle that cancels itself out).
+ * Surfaced by #2537's site migration on site/ui's form-builder, where
+ * `<Label><Checkbox onCheckedChange={…}/></Label>` stopped toggling:
+ * Vite's ESM import order registers child components before the parent's
+ * init runs, so the eager getter read instantiated eagerly instead of
+ * hitting the legacy pipeline's pending-init queue.
+ */
+import { describe, expect, test } from 'bun:test'
+import { compileJSX } from '../index.ts'
+import { HonoAdapter } from '../../../adapter-hono/src/adapter/index.ts'
+
+function clientJsOf(source: string, path: string): string {
+  const result = compileJSX(source, path, { adapter: new HonoAdapter() })
+  const errors = result.errors.filter(e => e.severity === 'error')
+  expect(errors).toEqual([])
+  return result.files.find(f => f.type === 'clientJs')?.content ?? ''
+}
+
+describe('unused prop extractions are pruned from init', () => {
+  test('template-only children/className props are not extracted', () => {
+    // Label's real shape: className feeds a reactive class effect (read
+    // via `_p.className` inside the effect), children render only in the
+    // SSR-adopted template — neither local binding is used by init.
+    const js = clientJsOf(
+      `"use client"
+
+interface WrapProps {
+  className?: string
+  children?: unknown
+}
+
+function Wrap({ className = '', children, ...props }: WrapProps) {
+  return (
+    <label data-slot="wrap" className={\`base \${className}\`} {...props}>
+      {children}
+    </label>
+  )
+}
+
+export { Wrap }
+`,
+      '/virtual/wrap.tsx',
+    )
+    expect(js).toContain('export function initWrap')
+    expect(js).not.toContain('const children = _p.children')
+  })
+
+  test('props the init genuinely reads keep their extraction', () => {
+    // `config` is read by a handler, `items` by an init-scope constant —
+    // both local bindings are real and must survive the prune.
+    const js = clientJsOf(
+      `"use client"
+
+import { createSignal } from '@barefootjs/client'
+
+interface P { config?: { startOpen?: boolean }, items?: string[] }
+
+function Widget({ config = {}, items = [] }: P) {
+  const [open, setOpen] = createSignal(false)
+  const first = items.length > 0 ? items[0] : 'none'
+  return <button onClick={() => setOpen(!!config.startOpen)}>{open() ? first : 'closed'}</button>
+}
+
+export { Widget }
+`,
+      '/virtual/widget.tsx',
+    )
+    expect(js).toContain('const config = _p.config ?? {}')
+    expect(js).toContain('const items = _p.items ?? []')
+  })
+})

package/src/adapters/interface.ts

@@ -78,6 +78,67 @@ export interface AdapterGenerateOptions {
    * incidentals are unaffected.
    */
   rewriteRelativeImport?: (importPath: string) => string
+  /**
+   * Ordered list of fully-resolved, absolute URLs to emit as ES module
+   * script registrations, in array order. When present (including the
+   * empty array `[]`), this **fully supersedes** the adapter-computed
+   * `clientJsBasePath` / `barefootJsPath` / `scriptBaseName` computation
+   * that adapters otherwise use to bake exactly two script URLs (the
+   * shared runtime, then the component's own `.client.js`) at codegen
+   * time.
+   *
+   * Exists for callers — chiefly the Vite plugin — that only learn the
+   * real script URLs after bundling: under Vite, filenames are content-
+   * hashed, the runtime is not a separately-registered script (it
+   * arrives as an ESM import of a shared chunk pulled in by the
+   * component's own entry), and the number of scripts a component needs
+   * is not fixed at two. The caller is responsible for all of that
+   * resolution — including any dev-server client script and the
+   * component's own entry — and hands the adapter a plain, ordered URL
+   * list to register verbatim.
+   *
+   * `undefined` (the default) means "fall back to the adapter-computed
+   * paths" — this is a purely additive option; every existing caller
+   * that never sets it keeps byte-identical output. An empty array is
+   * semantically distinct from `undefined`: it means "this component
+   * needs no script registrations at all" (e.g. the caller determined
+   * the component has no client interactivity), whereas `undefined`
+   * means "adapter, please decide using the computed path options."
+   *
+   * `skipScriptRegistration: true` still wins over this unconditionally
+   * — it means "a parent/caller will register scripts for me", which
+   * takes precedence regardless of what `scriptAssets` says.
+   */
+  scriptAssets?: string[]
+  /**
+   * Ordered list of fully-resolved, absolute URLs to emit as
+   * `<link rel="modulepreload">` hints, in array order, alongside the
+   * `<script type="module">` registrations driven by `scriptAssets`.
+   *
+   * These are the chunks the entry pulls in **transitively** — not the
+   * entry's own file, which is already covered by `scriptAssets`. Under
+   * Vite, a component's entry chunk is rarely a leaf: it imports the
+   * shared `@barefootjs/client` runtime chunk and, for a parent that
+   * renders a child island, the child's own entry chunk. Left alone, the
+   * browser only discovers those imports after it has fetched and parsed
+   * the entry — a second sequential round trip before the component can
+   * hydrate. A preload hint issued up front collapses that into one wave.
+   *
+   * `undefined` (the default) means "the caller has no preload
+   * information" — adapters emit nothing, exactly like the
+   * `clientJsBasePath`-computed path never emitted preloads before this
+   * option existed. An empty array is semantically distinct: it means
+   * "resolved, and there is nothing to preload" (e.g. the entry is a
+   * leaf with no transitive imports) — also emits nothing, but for a
+   * different reason, mirroring the `undefined`/`[]` distinction on
+   * `scriptAssets`.
+   *
+   * Only meaningful alongside a non-empty `scriptAssets` — there is
+   * nothing to preload ahead of if nothing is being registered.
+   * `skipScriptRegistration: true` still wins over this unconditionally,
+   * exactly as it does over `scriptAssets`.
+   */
+  preloadAssets?: string[]
 }
 
 /**
@@ -170,26 +231,6 @@ export interface TemplateAdapter {
    * Required for adapters that look up templates by filename (e.g. Mojolicious).
    */
   templatesPerComponent?: boolean
-  /**
-   * How the application author injects the externals importmap (and any
-   * `<link rel="modulepreload">` hints) into the page `<head>` when
-   * `externals` / `bundleEntries` are configured.
-   *
-   * - `'component'` — the adapter ships a render-time component (e.g. Hono's
-   *   `BfImportMap`) that reads `barefoot-externals.json`; `bf build` emits no
-   *   static snippet.
-   * - `'html-snippet'` — the adapter targets a template-string language (Go
-   *   html/template, Mojolicious EP) with no component layer, so `bf build`
-   *   writes a ready-to-include `barefoot-importmap.html` alongside
-   *   `barefoot-externals.json` (via `renderImportMapHtml`).
-   *
-   * Optional only for backward compatibility (and internal-only adapters like
-   * the CSR test adapter). Every *shipping* adapter must set it — the
-   * adapter-tests importmap-injection contract enforces this so a new adapter
-   * cannot silently leave configured `externals` with no injection point.
-   * See issue #1644.
-   */
-  importMapInjection?: 'component' | 'html-snippet'
   /**
    * Module specifier of the SSR shim for `@barefootjs/client` (and
    * `/runtime`). When set, the compiler rewrites client-package imports in

package/src/analyzer.ts

@@ -160,15 +160,26 @@ export function analyzeComponent(
   filePath: string,
   targetComponentName?: string,
   program?: ts.Program,
-  acceptsCallbackBody?: CallbackBodyAcceptor
+  acceptsCallbackBody?: CallbackBodyAcceptor,
+  programIsShared?: boolean
 ): AnalyzerContext {
   incrementCounter('filesAnalyzed')
-  // Track whether the caller supplied a shared ts.Program. Used downstream
+  // Track whether a shared ts.Program is genuinely in scope. Used downstream
   // to decide whether the silent per-file fallback should also emit a
   // BF050 diagnostic (issue #1248): when the source needs type-based
-  // detection but no shared Program is in scope, the regex fallback may
-  // misclassify library-getter reactivity.
-  const hadSharedProgram = program !== undefined
+  // detection but no shared Program is in scope, the per-file fallback may
+  // misclassify library-getter reactivity (its virtual host can fail module
+  // resolution, silently collapsing brand types to `any`).
+  //
+  // `programIsShared` lets the caller distinguish "the build supplied a
+  // shared corpus Program" from "the compiler pre-built a per-file Program
+  // to amortize it across sibling components" — the latter is exactly the
+  // fallback BF050 exists to flag, so it must NOT suppress the diagnostic
+  // (the old `program !== undefined` inference did, making the same brand
+  // import fail in a single-component file but pass in a multi-component
+  // one). Defaults to that inference for direct callers who pass a genuine
+  // shared Program (tests, site builds).
+  const hadSharedProgram = programIsShared ?? program !== undefined
   // Pre-pass: inline calls to same-file reactive factory helpers so the
   // downstream analyzer sees ordinary `createSignal(...)` declarations
   // instead of `const [a, b] = customFactory(...)` (#931). Skipped when

package/src/compiler.ts

@@ -26,6 +26,7 @@ import { preprocessInlineJsxCallbacks } from './preprocess-inline-jsx-callbacks.
 import { extractSsrDefaults } from './ssr-defaults.ts'
 import { computeSsrSeedPlan } from './ssr-seed-plan.ts'
 import { checkRichTypeMethodCalls } from './rich-type-refusal.ts'
+import { ErrorCodes } from './errors.ts'
 
 /**
  * Extended compile options with required adapter
@@ -116,11 +117,28 @@ function compileMultipleComponents(
   // --- Pass 1: analyze + jsxToIR for ALL components ---
   const entries: { componentIR: ComponentIR; ctx: ReturnType<typeof analyzeComponent> }[] = []
 
-  // Create ts.Program only when the file needs type-based reactivity detection
-  const program = options.program ?? (needsTypeBasedDetection(source) ? createProgramForFile(source, filePath)?.program : undefined)
+  // Create ts.Program only when the file needs type-based reactivity
+  // detection. A caller-supplied Program is only usable while its cached
+  // SourceFile still matches `source` — after an upstream rewrite
+  // (preprocessInlineJsxCallbacks), the analyzer would silently discard
+  // the stale Program PER COMPONENT and rebuild a per-file one each time
+  // (measured: 14 rebuilds ≈ 30 s on site/ui's xyflow-demo.tsx, #2537).
+  // Detect the staleness here instead, so the rewritten source gets ONE
+  // per-file Program shared by every sibling component.
+  const callerProgram =
+    options.program?.getSourceFile(filePath)?.text === source ? options.program : undefined
+  const program = callerProgram ?? (needsTypeBasedDetection(source) ? createProgramForFile(source, filePath)?.program : undefined)
+  // Whether a SHARED Program was genuinely supplied by the caller, as
+  // opposed to the per-file amortization built on the line above. The
+  // distinction feeds BF050: the per-file build is precisely the fallback
+  // that diagnostic exists to flag, so it must not suppress it the way a
+  // caller-supplied corpus Program does. See `analyzeComponent`'s
+  // `programIsShared` docstring — the single-component path gets the same
+  // verdict via its default inference from `options.program`.
+  const programIsShared = options.program !== undefined
 
   for (const componentName of componentNames) {
-    const ctx = analyzeComponent(source, filePath, componentName, program, adapter.acceptsCallbackBody)
+    const ctx = analyzeComponent(source, filePath, componentName, program, adapter.acceptsCallbackBody, programIsShared)
 
     if (!ctx.jsxReturn) {
       errors.push(...ctx.errors)
@@ -152,6 +170,22 @@ function compileMultipleComponents(
     entries.push({ componentIR, ctx })
   }
 
+  // BF050 is a per-FILE diagnostic (it points at the brand-package import
+  // line), but pass 1 runs the analyzer once per component, so a
+  // multi-component file accumulates one identical copy per sibling.
+  // Keep the first.
+  {
+    let seenBf050 = false
+    const deduped = errors.filter(e => {
+      if (e.code !== ErrorCodes.SHARED_PROGRAM_REQUIRED) return true
+      if (seenBf050) return false
+      seenBf050 = true
+      return true
+    })
+    errors.length = 0
+    errors.push(...deduped)
+  }
+
   // Emit IR files per component when requested. The contract is "if the
   // user asks for IR, they get IR" regardless of `isClientComponent` or
   // adapter (#1297). Single-component files emit `<base>.ir.json`; multi-
@@ -230,6 +264,8 @@ function compileMultipleComponents(
       scriptBaseName,
       siblingTemplatesRegistered: options.siblingTemplatesRegistered,
       rewriteRelativeImport: options.rewriteRelativeImport,
+      scriptAssets: options.scriptAssets,
+      preloadAssets: options.preloadAssets,
     })
     const moduleExports = generateModuleExports(
       componentIR,
@@ -671,6 +707,8 @@ export function compileJSX(
     scriptBaseName: options.scriptBaseName,
     siblingTemplatesRegistered: options.siblingTemplatesRegistered,
     rewriteRelativeImport: options.rewriteRelativeImport,
+    scriptAssets: options.scriptAssets,
+    preloadAssets: options.preloadAssets,
   })
 
   // `templatesPerComponent` adapters (Mojolicious) emit non-JS template files

package/src/index.ts

@@ -141,20 +141,6 @@ export type { SourceMapV3 } from './ir-to-client-js/source-map.ts'
 // Client JS Combiner (for build scripts)
 export { combineParentChildClientJs } from './combine-client-js.ts'
 
-// Externals manifest + importmap snippet renderer (shared by adapters and CLI)
-export { renderImportMapHtml } from './import-map.ts'
-export type { ExternalsManifest, ImportMapManifest } from './import-map.ts'
-
-// Build options (shared by adapters and CLI)
-export interface OutputLayout {
-  /** Subdirectory for marked templates (default: 'components') */
-  templates: string
-  /** Subdirectory for client JS files (default: 'components') */
-  clientJs: string
-  /** Subdirectory for runtime (barefoot.js) (default: same as clientJs) */
-  runtime: string
-}
-
 export interface PostBuildContext {
   /** Collected types: componentName → types content */
   types: Map<string, string>
@@ -179,42 +165,6 @@ export interface PostBuildContext {
   markChanged?: () => void
 }
 
-/**
- * Vendor code-splitting spec for a single package.
- *
- * - `true` / `{ chunk: true }` — locate the package's browser-ready entry
- *   (umd → unpkg → jsdelivr → import condition) and copy it to the output dir.
- * - `{ url }` — CDN passthrough: skip local copy, use the URL as-is in the importmap.
- * - `preload: true` — emit a `<link rel="modulepreload">` hint for this entry.
- * - `rebundle: true` — re-bundle the resolved entry with esbuild into a self-contained
- *   ESM file, inlining all dependencies. Useful for packages (e.g. `yjs`) whose
- *   `dist/*.mjs` files still contain bare external imports that browsers cannot resolve.
- */
-export type ExternalSpec =
-  | true
-  | { chunk?: true; preload?: boolean; rebundle?: boolean }
-  | { url: string; preload?: boolean }
-
-/**
- * An entry point to bundle directly with esbuild.
- * Externals declared in `BuildOptions.externals` are applied automatically.
- * `@barefootjs/client`, `@barefootjs/client/runtime`, and
- * `@barefootjs/client/reactive` are always kept external, so you never need
- * to list them here. They resolve through the page's import map to the shared
- * `barefoot.js` runtime; inlining them would fork the reactive runtime and
- * duplicate signals (#927).
- * Use this for modules that are not barefoot components (e.g. plain TS entry
- * points that import external vendor packages).
- */
-export interface BundleEntry {
-  /** Entry file path relative to the config file */
-  entry: string
-  /** Output filename placed in the client JS output directory */
-  outfile: string
-  /** Additional packages to mark as external beyond those in `externals` */
-  externals?: string[]
-}
-
 /**
  * Project layout paths used by registry tooling (`bf add`, `search`,
  * `meta:extract`, `tokens`, `inspect`, etc.). These are consumed only by
@@ -230,79 +180,6 @@ export interface BarefootPaths {
   meta: string
 }
 
-export interface BuildOptions {
-  /**
-   * Project layout paths. Consumed by registry tooling, not the build pipeline.
-   * Defaults to `{ components: 'components/ui', tokens: 'tokens', meta: 'meta' }`
-   * when omitted.
-   */
-  paths?: BarefootPaths
-  /** Source component directories relative to config file */
-  components?: string[]
-  /** Output directory relative to 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.
-   * The CLI copies each package's browser-ready bundle to the output dir,
-   * then emits `dist/barefoot-externals.json` with the importmap and
-   * `--external` flag list for use in the app's own `bun build`.
-   *
-   * `@barefootjs/client*` dedup entries are added automatically whenever
-   * this field is non-empty, preventing reactive-primitive duplication (#927).
-   */
-  externals?: Record<string, ExternalSpec>
-  /**
-   * URL base path for vendor chunks in the emitted importmap.
-   * Defaults to `/<runtimeSubdir>/` (e.g., `/static/components/`).
-   */
-  externalsBasePath?: string
-  /**
-   * Additional entry points to bundle with esbuild directly, bypassing the
-   * barefoot component compiler. Useful for plain TS/TSX modules (e.g. canvas
-   * init entry points) that import vendor packages listed in `externals`.
-   * Each entry is bundled as ESM with all `externals` automatically excluded.
-   */
-  bundleEntries?: BundleEntry[]
-  /**
-   * Import prefixes resolved at build time rather than left as bare
-   * specifiers in the emitted client JS. Use this for tsconfig `paths`
-   * aliases like `@/`, `@ui/`, `@app/` so the compiler does not emit
-   * them as browser imports.
-   *
-   * Forwarded to `compileJSX` as `CompileOptions.localImportPrefixes`.
-   */
-  localImportPrefixes?: string[]
-  /**
-   * How the CLI produces `barefoot.js` (the client runtime bundle):
-   *   - `'treeshake'` (default) — bundle only the runtime exports this
-   *     project's compiled client JS actually imports, plus a small
-   *     always-kept public mount API (`render`, `hydrate`, etc.).
-   *   - `'treeshake-exact'` — same collection, but without the always-kept
-   *     set. Smaller output; a hand-written page script the CLI never
-   *     compiles must list any runtime names it calls directly in
-   *     `runtimeKeep`, or they're silently dropped.
-   *   - `'full'` — copy the entire prebuilt runtime bundle verbatim.
-   * See `@barefootjs/cli`'s `runtime-treeshake.ts` for the collector and
-   * `ALWAYS_KEEP_RUNTIME_EXPORTS` for the always-kept names.
-   */
-  runtimeBundle?: 'treeshake' | 'treeshake-exact' | 'full'
-  /**
-   * Extra `@barefootjs/client*` export names to force-keep in `barefoot.js`
-   * under `runtimeBundle: 'treeshake'` or `'treeshake-exact'` — for names
-   * only ever referenced from hand-written page scripts the CLI never
-   * compiles.
-   */
-  runtimeKeep?: string[]
-}
-
 // AttrValue constructors
 export { AttrValueOf } from './types.ts'
 

package/src/ir-to-client-js/emit-registration.ts

@@ -182,6 +182,15 @@ export function emitRegistrationAndHydration(
   }
 
   const registryKey = nameForRegistryRef(name)
+  // When the registry key was file-scoped (`Name__<8hex>`, for a
+  // non-exported component — see `component-scope.ts`), carry the plain
+  // name in the def so the runtime has something to build scope IDs from.
+  // The key is an internal disambiguator; `bf-s` is a documented contract
+  // (`Name_abc123`) that the SSR adapters honour, and without this the CSR
+  // path stamps the hashed key into the attribute instead (#2518).
+  if (registryKey !== name) {
+    defParts.push(`name: '${name}'`)
+  }
   const hydrateLine = `hydrate('${registryKey}', { ${defParts.join(', ')} })`
 
   // Emit a callable shim with the original component name so consumers

package/src/ir-to-client-js/generate-init.ts

@@ -19,6 +19,7 @@ import { computeDeferredChildSlots } from './html-template.ts'
 import { emitChildComponentImports } from './child-components.ts'
 import { classifyLocalDeclarations } from './init-declarations.ts'
 import { emitModuleLevelDeclarations, resolveFinalImports } from './emit-module-level.ts'
+import { pruneUnusedPropExtractions } from './prune-unused-prop-extractions.ts'
 import { buildPhaseCtx, PHASES, runPhases } from './phases.ts'
 import { rewritePropsObjectRef } from './rewrite-props-object.ts'
 import { buildInlinableConstants } from './emit-registration.ts'
@@ -113,7 +114,9 @@ export function generateInitFunction(
   // Replacer-function form: a plain replacement string would let literal
   // `$&`/`$1`/`$$` sequences in user helper bodies or import paths be
   // reinterpreted by `String.replace`'s special-pattern handling.
-  const codeWithModuleConstants = generatedCode.replace(MODULE_CONSTANTS_PLACEHOLDER, () => moduleConstantsCode)
+  const codeWithModuleConstants = pruneUnusedPropExtractions(
+    generatedCode.replace(MODULE_CONSTANTS_PLACEHOLDER, () => moduleConstantsCode),
+  )
   const allImportLines = resolveFinalImports(codeWithModuleConstants, ir, localImportPrefixes)
 
   return codeWithModuleConstants.replace(IMPORT_PLACEHOLDER, () => allImportLines)

package/src/ir-to-client-js/index.ts

@@ -283,7 +283,11 @@ function generateTemplateOnlyMount(ir: ComponentIR, ctx: ClientJsContext): strin
   lines.push('')
   lines.push(`function init${name}() {}`)
   lines.push('')
-  lines.push(`hydrate('${registryKey}', { init: init${name}, template: (${PROPS_PARAM}) => \`${templateHtml}\` })`)
+  // `name: '...'` only when the key was file-scoped — same reason as in
+  // `emitRegistrationAndHydration`: the hashed key must not reach `bf-s`
+  // (#2518).
+  const nameField = registryKey !== name ? `, name: '${name}'` : ''
+  lines.push(`hydrate('${registryKey}', { init: init${name}, template: (${PROPS_PARAM}) => \`${templateHtml}\`${nameField} })`)
   // See `emitRegistrationAndHydration` (./emit-registration.ts) for the
   // rationale on why the component is also emitted as a callable
   // shim. The same applies for template-only components since they