@barefootjs/vite 0.30.0

package/src/__tests__/relative-import-rewrite.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Regression: `rewriterFor`'s `outputPathGuess` (`plugin.ts`) MUST mirror
+ * `planEmits`'s actual on-disk output location — a same-directory sibling
+ * import must stay `./Sibling` after emission, not turn into a phantom
+ * `../blog/Sibling`-shaped path.
+ *
+ * Only an adapter whose templates carry real `import` syntax exercises
+ * this at all (`paths.ts`'s `buildRelativeImportRewriter` docstring) — Go/
+ * Mojo/etc. templates have no import syntax. `HonoAdapter` is that adapter
+ * here (mirrors `integrations/hono`'s real PageShell → Sidekick-shaped
+ * `ReaderToolbar` same-directory import).
+ *
+ * Fixture (`../../e2e-fixture-relimport`) reproduces the bug's precondition
+ * exactly: `app/` (the Vite root, empty of components) and `blog/` (a
+ * `components` dir that is a SIBLING of root, not a descendant — this
+ * monorepo's real layouts, see `plugin.ts`'s `configureServer` docstring).
+ * The root-relative guess and the component-dir-relative REAL output path
+ * only diverge when a component's dir isn't the root itself — a fixture
+ * with `components` under `root` would not reproduce this at all. Lives
+ * under `node_modules`-having `packages/vite/` (not a system tmpdir) so
+ * `@barefootjs/client` resolves through the monorepo's real workspace
+ * symlinks, same reason `e2e-fixture`/`e2e-fixture-dev` do.
+ */
+import { describe, test, expect, afterAll } from 'bun:test'
+import { build } from 'vite'
+import { mkdtemp, rm, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { HonoAdapter } from '@barefootjs/hono/adapter'
+import { barefoot } from '../plugin.ts'
+
+const FIXTURE_ROOT = resolve(import.meta.dirname, '../../e2e-fixture-relimport')
+const APP_ROOT = join(FIXTURE_ROOT, 'app')
+const BLOG_DIR = join(FIXTURE_ROOT, 'blog')
+
+describe('rewriteRelativeImport re-anchoring: a components dir outside the Vite root', () => {
+  let outDir: string
+  let templatesDir: string
+
+  afterAll(async () => {
+    await rm(outDir, { recursive: true, force: true })
+    await rm(templatesDir, { recursive: true, force: true })
+  })
+
+  test('a same-directory sibling import survives emission as `./Sidekick`, not a phantom `../blog/Sidekick`', async () => {
+    outDir = await mkdtemp(join(tmpdir(), 'barefoot-vite-relimport-dist-'))
+    templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-vite-relimport-views-'))
+
+    await build({
+      configFile: false,
+      root: APP_ROOT,
+      base: '/static/',
+      logLevel: 'warn',
+      build: { outDir, emptyOutDir: true },
+      plugins: [
+        barefoot({
+          adapter: new HonoAdapter(),
+          components: [BLOG_DIR],
+          templates: templatesDir,
+        }),
+      ],
+    })
+
+    const template = await readFile(join(templatesDir, 'PageShell.tsx'), 'utf8')
+    // The bug re-anchored this to a phantom `../blog/Sidekick`-shaped path
+    // (root-relative, guessing the file would land nested under
+    // `templatesDir/../blog/`) — but `planEmits` actually flattens every
+    // `components` dir's contents directly under `templatesDir`, so
+    // `Sidekick.tsx` is a FLAT sibling of `PageShell.tsx`.
+    expect(template).toContain("from './Sidekick'")
+    expect(template).not.toContain('../blog/Sidekick')
+    expect(template).not.toContain('../../blog/Sidekick')
+
+    // Also assert the emitted Sidekick template actually lives where
+    // PageShell's rewritten import now points.
+    const sidekick = await readFile(join(templatesDir, 'Sidekick.tsx'), 'utf8')
+    expect(sidekick).toContain('function Sidekick')
+  }, 60_000)
+})

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

@@ -0,0 +1,55 @@
+import { describe, test, expect, afterEach } from 'bun:test'
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { resolveClientJsSpecifier } from '../resolve-client-js.ts'
+
+describe('resolveClientJsSpecifier', () => {
+  let dir: string
+
+  afterEach(async () => {
+    if (dir) await rm(dir, { recursive: true, force: true })
+  })
+
+  test('maps a relative ./foo.client.js specifier back to ./foo.tsx', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'barefoot-resolve-'))
+    await writeFile(join(dir, 'signals.tsx'), '\'use client\'\nexport const x = 1')
+    const importer = join(dir, 'consumer.tsx')
+
+    const resolved = resolveClientJsSpecifier('./signals.client.js', importer)
+    expect(resolved).toBe(join(dir, 'signals.tsx'))
+  })
+
+  test('maps a ../ relative specifier from a nested importer', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'barefoot-resolve-'))
+    await mkdir(join(dir, 'nested'), { recursive: true })
+    await writeFile(join(dir, 'signals.tsx'), '\'use client\'\nexport const x = 1')
+    const importer = join(dir, 'nested', 'consumer.tsx')
+
+    const resolved = resolveClientJsSpecifier('../signals.client.js', importer)
+    expect(resolved).toBe(join(dir, 'signals.tsx'))
+  })
+
+  test('returns null when the target .tsx file does not exist on disk', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'barefoot-resolve-'))
+    const importer = join(dir, 'consumer.tsx')
+    expect(resolveClientJsSpecifier('./missing.client.js', importer)).toBeNull()
+  })
+
+  test('returns null for a non-.client.js specifier', () => {
+    expect(resolveClientJsSpecifier('./signals.ts', '/a/consumer.tsx')).toBeNull()
+    expect(resolveClientJsSpecifier('./signals', '/a/consumer.tsx')).toBeNull()
+  })
+
+  test('returns null for an alias (bare) specifier — Vite\'s resolve.alias handles it natively (R2)', () => {
+    expect(resolveClientJsSpecifier('@/components/signals.client.js', '/a/consumer.tsx')).toBeNull()
+  })
+
+  test('returns null for a bare package specifier', () => {
+    expect(resolveClientJsSpecifier('some-package/signals.client.js', '/a/consumer.tsx')).toBeNull()
+  })
+
+  test('returns null when there is no importer', () => {
+    expect(resolveClientJsSpecifier('./signals.client.js', undefined)).toBeNull()
+  })
+})

package/src/__tests__/templates-optional.test.ts

@@ -0,0 +1,139 @@
+/**
+ * `templates` is optional on `BarefootViteOptions` for an adapter whose
+ * `generate()` output is ALWAYS empty (CSR — see `@barefootjs/client`'s
+ * `CSRAdapter`). These tests pin both halves of that contract directly
+ * against `plugin.ts`'s hooks (no real Vite build — see
+ * `e2e-vite-build.test.ts` for that):
+ *
+ *   - a CSR-shaped project (CSRAdapter, `templates` omitted) builds clean:
+ *     no template files, no manifest.json, no thrown error — even for a
+ *     component whose `ssrDefaults` output IS real (proving the guard is
+ *     scoped to `markedTemplate` content specifically, not any adapter
+ *     output — see `plugin.ts`'s `assertNoRealTemplateOutput` docstring).
+ *   - a non-CSR adapter (one that actually emits template text) with
+ *     `templates` omitted refuses loudly instead of silently dropping that
+ *     output.
+ */
+import { describe, test, expect, afterEach } from 'bun:test'
+import { mkdtemp, rm, mkdir, writeFile, access } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { testAdapter } from '@barefootjs/jsx'
+import { CSRAdapter } from '@barefootjs/client/csr-adapter'
+import { barefoot } from '../plugin.ts'
+
+// biome-ignore lint: hooks are called directly, bypassing Vite's own
+// dispatch/typing — casting to `any` is the standard way to unit-test a
+// Vite plugin's hooks in isolation.
+type AnyPlugin = any
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+describe('templates: optional for an adapter with always-empty output (CSR)', () => {
+  let dir: string
+
+  afterEach(async () => {
+    if (dir) await rm(dir, { recursive: true, force: true })
+  })
+
+  test('builds clean with no template files, no manifest.json, and no error — including a component with real ssrDefaults', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'barefoot-plugin-templates-optional-csr-'))
+    await mkdir(join(dir, 'src/components'), { recursive: true })
+    // A signal with a literal initializer produces non-empty `ssrDefaults`
+    // regardless of adapter (that computation reads IR metadata, not
+    // `generate()`'s output) — this is the case that would wrongly trip an
+    // over-broad guard checking ANY adapter output, not just the template.
+    await writeFile(
+      join(dir, 'src/components/Counter.tsx'),
+      '\'use client\'\nimport { createSignal } from \'@barefootjs/client\'\nexport function Counter() {\n  const [count, setCount] = createSignal(0)\n  return <button onClick={() => setCount(count() + 1)}>{count()}</button>\n}\n',
+    )
+
+    const plugin: AnyPlugin = barefoot({
+      adapter: new CSRAdapter(),
+      components: ['src/components'],
+    })
+    await plugin.config({ root: dir }, { command: 'build', mode: 'production' })
+    plugin.configResolved({ root: dir, base: '/', build: { outDir: 'dist', manifest: true } })
+    await mkdir(join(dir, 'dist/.vite'), { recursive: true })
+    await writeFile(
+      join(dir, 'dist/.vite/manifest.json'),
+      JSON.stringify({ 'src/components/Counter.tsx': { file: 'assets/Counter-abc123.js', isEntry: true } }),
+    )
+
+    await expect(plugin.writeBundle()).resolves.toBeUndefined()
+
+    // No `templates` option was given, so there is no directory this
+    // plugin could have written a template/manifest into in the first
+    // place — the absence of a stray output directory anywhere under the
+    // project root is the observable half of "no template files".
+    expect(await pathExists(join(dir, 'manifest.json'))).toBe(false)
+  })
+
+  test('dev pass also builds clean with `templates` omitted', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'barefoot-plugin-templates-optional-csr-dev-'))
+    await mkdir(join(dir, 'src/components'), { recursive: true })
+    await writeFile(join(dir, 'src/components/Greeting.tsx'), 'export function Greeting() { return <p>Hi</p> }')
+
+    const plugin: AnyPlugin = barefoot({
+      adapter: new CSRAdapter(),
+      components: ['src/components'],
+    })
+    await plugin.config({ root: dir }, { command: 'serve', mode: 'development' })
+    plugin.configResolved({ root: dir, base: '/', build: { outDir: 'dist', manifest: true } })
+
+    // Drive `configureServer`'s middleware-mode path (no `httpServer`)
+    // directly, matching how `e2e-vite-dev.test.ts` exercises this without
+    // a real listening server.
+    const watchedDirs: string[] = []
+    const listeners: Record<string, (arg: string) => void> = {}
+    plugin.configureServer({
+      httpServer: null,
+      config: { logger: { error: () => {} } },
+      watcher: {
+        add: (d: string) => watchedDirs.push(d),
+        on: (event: string, cb: (arg: string) => void) => { listeners[event] = cb },
+      },
+      ws: { send: () => {} },
+    })
+
+    // The initial pass runs asynchronously (middleware-mode branch) —
+    // give it a tick to complete and surface any thrown error.
+    await new Promise(r => setTimeout(r, 50))
+    expect(watchedDirs).toContain(join(dir, 'src/components'))
+  })
+})
+
+describe('templates: refuses loudly when omitted but the adapter produces a real template', () => {
+  let dir: string
+
+  afterEach(async () => {
+    if (dir) await rm(dir, { recursive: true, force: true })
+  })
+
+  test('writeBundle throws a clear error naming the offending file', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'barefoot-plugin-templates-optional-refuse-'))
+    await mkdir(join(dir, 'src/components'), { recursive: true })
+    // `testAdapter` (unlike CSRAdapter) emits a REAL, non-empty template —
+    // exactly the output that would be silently dropped without this guard.
+    await writeFile(join(dir, 'src/components/Greeting.tsx'), 'export function Greeting() { return <p>Hi</p> }')
+
+    const plugin: AnyPlugin = barefoot({
+      adapter: testAdapter,
+      components: ['src/components'],
+    })
+    await plugin.config({ root: dir }, { command: 'build', mode: 'production' })
+    plugin.configResolved({ root: dir, base: '/', build: { outDir: 'dist', manifest: true } })
+    await mkdir(join(dir, 'dist/.vite'), { recursive: true })
+    await writeFile(join(dir, 'dist/.vite/manifest.json'), '{}')
+
+    await expect(plugin.writeBundle()).rejects.toThrow(/templates/)
+    await expect(plugin.writeBundle()).rejects.toThrow(/Greeting\.tsx/)
+  })
+})

package/src/child-marker.ts

@@ -0,0 +1,67 @@
+/**
+ * `@bf-child:<Name>` marker resolution.
+ *
+ * The compiler emits `import '/* @bf-child:ChildName *\/'` inside a
+ * component's client JS for every OTHER component it references (loop-body
+ * children, `initChild`-driven nested components, etc.) — see
+ * `packages/jsx/src/ir-to-client-js/child-components.ts`. That specifier
+ * is not a real module: it's a marker this plugin must resolve at build
+ * time, one way or another, for every reference it stands for.
+ *
+ * Simply DROPPING the marker (resolving it to an empty no-op module) is
+ * not a safe choice for every child reference the marker stands for, only
+ * for SOME of them. The distinction (found empirically against gin's real
+ * TodoApp/TodoItem — no PR01-03 fixture exercised this shape):
+ *
+ * - A child rendered via `initChild()` (an SSR-hydrated child, or one
+ *   whose scope a cross-template Go/ERB/… render already put on the
+ *   page) is genuinely safe to drop: `@barefootjs/client`'s registry
+ *   (`packages/client/src/runtime/registry.ts`) queues an `initChild`
+ *   call for a not-yet-registered name (`pendingChildInits`) and drains
+ *   it the moment the child's OWN script loads and calls
+ *   `registerComponent` — however that script physically reached the
+ *   page. As long as the child's own template renders somewhere (which
+ *   is what registers its script — see `plugin.ts`'s docstring), this
+ *   is load-order-tolerant by design.
+ * - A child created via `createComponent(name, …)` for a PURELY
+ *   client-rendered loop (no server-side row template at all — e.g.
+ *   TodoApp's `.map()` over `initialTodos`, as opposed to TodoAppSSR's
+ *   server-rendered rows) is NOT tolerant: `materializeComponent`
+ *   (`packages/client/src/runtime/component.ts`) does one synchronous
+ *   `getTemplate(name)` registry lookup with NO queueing — if the
+ *   child's script hasn't run yet, it silently renders a placeholder
+ *   and NEVER retries. If nothing else on the page happens to reference
+ *   the child, ITS SCRIPT NEVER LOADS AT ALL, and the row permanently
+ *   fails to render.
+ *
+ * Resolving every marker to a REAL import of the named child's `.tsx`
+ * source (when discovered) closes this gap the same way Rollup already
+ * handles every other cross-module reference in this design: the
+ * bare `import '/* @bf-child:ChildName *\/'` statement's TEXT doesn't
+ * need to change, only what it resolves to. Once it resolves to
+ * `ChildName.tsx`, Rollup's OWN module graph puts an entry-to-entry
+ * static import in the output (the child is ALSO independently an entry
+ * point — every discovered `'use client'` file is), which is exactly
+ * what makes the browser fetch and execute the child's script as a side
+ * effect of loading the parent's — no registry timing dependent on
+ * anything server-side at all. A name that can't be resolved (unknown,
+ * or a multi-component-per-file export the simple name→file map below
+ * doesn't cover) falls back to the empty no-op module rather than
+ * failing the build outright — the SAME degraded-but-shippable behavior
+ * as before this fix for whatever slice of cases it doesn't cover,
+ * rather than a regression for OTHER apps that build cleanly today.
+ */
+
+const BF_CHILD_MARKER_RE = /^\/\* @bf-child:(\w+) \*\/$/
+
+/** The single virtual module id an UNRESOLVED `@bf-child:` marker falls
+ * back to — one shared id (not one per child name) because the module's
+ * content is always the same (empty) and Rollup dedupes same-id imports
+ * for free. */
+export const BF_CHILD_NOOP_ID = '\0barefoot-bf-child-noop'
+
+/** The child component name embedded in a `@bf-child:` marker, or `null`
+ * if `source` doesn't look like a compiler-emitted one. */
+export function bfChildMarkerName(source: string): string | null {
+  return source.match(BF_CHILD_MARKER_RE)?.[1] ?? null
+}

package/src/compile-cache.ts

@@ -0,0 +1,63 @@
+/**
+ * Content-hash keyed cache of full `CompileResult` objects.
+ *
+ * Both the graph pass (`transform`, driven by Rollup visiting `.tsx`
+ * modules) and the eager pass (`writeBundle`, driven by a directory walk
+ * that isn't gated on the module graph at all — see the design's rationale
+ * for why server-only components need it) call `compileFile()` for the
+ * same source files. Keying by content hash rather than just by file path
+ * means a file edited between the two passes (or across a `--watch`
+ * rebuild) always recompiles, while an unchanged file is compiled exactly
+ * once no matter which pass reaches it first.
+ */
+import { createHash } from 'node:crypto'
+import type { CompileResult } from '@barefootjs/jsx'
+
+function hashContent(content: string): string {
+  return createHash('sha256').update(content).digest('hex')
+}
+
+interface CacheRow {
+  hash: string
+  result: CompileResult
+}
+
+export class CompileCache {
+  private rows = new Map<string, CacheRow>()
+
+  /**
+   * Return the cached `CompileResult` for `absPath` if its content hash
+   * matches what's cached; otherwise call `compile()`, cache the result,
+   * and return it. `compile()` runs at most once per distinct
+   * `(absPath, content)` pair.
+   */
+  getOrCompile(
+    absPath: string,
+    content: string,
+    compile: () => CompileResult,
+  ): CompileResult {
+    const hash = hashContent(content)
+    const cached = this.rows.get(absPath)
+    if (cached && cached.hash === hash) return cached.result
+
+    const result = compile()
+    this.rows.set(absPath, { hash, result })
+    return result
+  }
+
+  /** Look up a previously cached result without recompiling. */
+  peek(absPath: string): CompileResult | undefined {
+    return this.rows.get(absPath)?.result
+  }
+
+  /** Drop a single file's cached entry — used when a file is deleted
+   * (dev watcher `'unlink'`) so a later file recreated at the same path
+   * never reuses a stale result keyed only by path, not content. */
+  delete(absPath: string): void {
+    this.rows.delete(absPath)
+  }
+
+  clear(): void {
+    this.rows.clear()
+  }
+}

package/src/component-manifest.ts

@@ -0,0 +1,139 @@
+/**
+ * Reassembles ONE source file's row for the combined `manifest.json` this
+ * plugin writes to `templatesDir` alongside the per-component
+ * `<Name>.ssr-defaults.json` files `emit.ts`'s `planEmits` already produces.
+ *
+ * WHY THIS EXISTS (not just the per-component files): every PHP/Python/Ruby
+ * backend driving a `templatesPerComponent` adapter (Blade/Jinja2/ERB) reads
+ * `ssrDefaults` — an optional-prop-derived signal's SSR seed value — from
+ * disk at REQUEST time (there is no compile step to bake it into source the
+ * way Go's generated `NewXxxProps` constructor or Hono's self-contained
+ * `.tsx` file can). Combining every source file's row into one manifest
+ * means each backend reads a single file instead of glob-and-reassembling
+ * the identical `{ [component]: { ssrDefaults } }` shape itself — avoiding
+ * seven copies of the same reconstruction logic across three languages,
+ * each of which could drift or break independently. One place in core
+ * beats three `/vite` packages reimplementing it, and
+ * `@barefootjs/go-template/vite` / `@barefootjs/hono/vite` get the same
+ * manifest for free even though neither adapter's own backend currently
+ * reads it (Go bakes `ssrDefaults` into generated source; Hono's `.tsx`
+ * inlines them as JS defaults) — see this module's own callers for the
+ * confirmation that neither reads a manifest today.
+ *
+ * Implemented standalone rather than by importing from `@barefootjs/cli`,
+ * for the same reason as `paths.ts`'s header comment: that package's only
+ * published entry point is the full `bf` binary.
+ *
+ * Two fields are deliberately NOT part of `ManifestEntry`:
+ *
+ * - `stubDeps` is not emitted: Rollup's own module graph resolution
+ *   handles dependency wiring, so there is no separate stub-dependency
+ *   bookkeeping to produce, and no consumer reads such a field.
+ * - `clientJs` is not emitted: there is no single static path to put
+ *   there. The real client JS URL is content-hashed and mode-dependent
+ *   (dev-origin vs. build-manifest-resolved) — exactly what
+ *   `scriptAssets` already resolves and bakes directly into the compiled
+ *   template's own script-registration call. No adapter backend or native
+ *   runtime reads `manifest[name].clientJs`; however, `@barefootjs/hono`'s
+ *   `BfPreload` component can read `clientJs` from a caller-supplied
+ *   manifest object (legacy site builds emit one). Plugin-manifest
+ *   consumers wanting preloads use the `preloadAssets` path instead
+ *   (`registerComponentPreloads` → `<link rel="modulepreload">`).
+ */
+import type { CompileResult, TemplateAdapter } from '@barefootjs/jsx'
+import { perComponentRelPath, relativeUnderComponentDir, withExtension } from './paths.ts'
+
+/** One exported component's row inside a multi-export source file's
+ * `components` map (`templatesPerComponent` adapters only). */
+export interface ManifestComponentEntry {
+  markedTemplate: string
+  ssrDefaults?: Record<string, unknown>
+}
+
+/** One SOURCE FILE's row in the combined manifest (see this module's
+ * header for the fields intentionally not included). */
+export interface ManifestEntry {
+  markedTemplate: string
+  ssrDefaults?: Record<string, unknown>
+  /** Per-exported-component rows for `templatesPerComponent` adapters
+   * (piconic-ai/barefootjs#2132) — present even for a single-component
+   * file. */
+  components?: Record<string, ManifestComponentEntry>
+}
+
+/**
+ * Builds one source file's `{ manifestKey, entry }` pair from its
+ * already-compiled `CompileResult`. Returns `null` when the compile
+ * produced no `markedTemplate` at all (nothing to register).
+ */
+export function buildManifestEntry(
+  result: CompileResult,
+  absPath: string,
+  componentDirs: readonly string[],
+  adapter: TemplateAdapter,
+): { manifestKey: string; entry: ManifestEntry } | null {
+  const markedTemplates = result.files.filter(f => f.type === 'markedTemplate')
+  if (markedTemplates.length === 0) return null
+
+  const relUnderComponentDir = relativeUnderComponentDir(absPath, componentDirs)
+  // Source file's path relative to its `components` dir, extension
+  // stripped (e.g. `Counter`, or `ui/toast/index` for a multi-export
+  // file). `relativeUnderComponentDir` gives the position under whichever
+  // configured `componentDirs` entry contains it, still WITH the
+  // extension; `withExtension(..., '')` strips it.
+  const manifestKey = withExtension(relUnderComponentDir, '')
+
+  const ssrDefaultsByComponent = new Map<string, Record<string, unknown>>()
+  for (const f of result.files) {
+    if (f.type !== 'ssrDefaults' || !f.componentName) continue
+    try {
+      ssrDefaultsByComponent.set(f.componentName, JSON.parse(f.content) as Record<string, unknown>)
+    } catch {
+      // Malformed ssrDefaults content is dropped silently rather than
+      // failing the build.
+    }
+  }
+
+  // Every `markedTemplate`/`ssrDefaults` FileOutput is unconditionally
+  // stamped with `componentName` (see `packages/jsx/src/compiler.ts`,
+  // both the single- and multi-component-per-file code paths) — pairing on
+  // it directly is exact and adapter-agnostic, with no filename-based
+  // heuristic needed.
+  const relPathFor = (componentName: string | undefined): string =>
+    adapter.templatesPerComponent && componentName
+      ? perComponentRelPath(relUnderComponentDir, componentName, adapter.extension)
+      : withExtension(relUnderComponentDir, adapter.extension)
+
+  let componentsMap: Record<string, ManifestComponentEntry> | undefined
+  if (adapter.templatesPerComponent) {
+    componentsMap = {}
+    for (const tpl of markedTemplates) {
+      if (!tpl.componentName) continue
+      const ssrDefaults = ssrDefaultsByComponent.get(tpl.componentName)
+      componentsMap[tpl.componentName] = {
+        markedTemplate: relPathFor(tpl.componentName),
+        ...(ssrDefaults ? { ssrDefaults } : {}),
+      }
+    }
+    if (Object.keys(componentsMap).length === 0) componentsMap = undefined
+  }
+
+  // Primary (top-level) template is `markedTemplates[0]`. For a
+  // `templatesPerComponent` adapter this is the sole/first component —
+  // the source file's own basename in every real component in this repo
+  // (`Counter.tsx` exports `Counter`), or, for a multi-export file where
+  // no per-component name equals the file's own basename (e.g.
+  // `ui/toast/index.tsx`), simply the first exported component. For a
+  // combined-file adapter there is only ever one entry, so the same
+  // index works unconditionally.
+  const primary = markedTemplates[0]!
+  const primarySsrDefaults = primary.componentName ? ssrDefaultsByComponent.get(primary.componentName) : undefined
+
+  const entry: ManifestEntry = {
+    markedTemplate: relPathFor(primary.componentName),
+    ...(primarySsrDefaults ? { ssrDefaults: primarySsrDefaults } : {}),
+    ...(componentsMap ? { components: componentsMap } : {}),
+  }
+
+  return { manifestKey, entry }
+}

package/src/corpus-program.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared `ts.Program` management for the plugin's compile passes.
+ *
+ * Type-based reactivity detection (Reactive<T> brand classification, the
+ * BF023/BF024 nullable-loop-key check) needs a `ts.TypeChecker`. Without a
+ * caller-supplied Program, `compileJSX` falls back to building one Program
+ * PER FILE — and `ts.createProgram`'s dominant cost is constructing the
+ * lib.d.ts/node_modules type graph, not parsing the one source file
+ * (~500-600 ms per call regardless of file size; ~44-109 s measured across
+ * site/ui's 71 type-needing files). Worse than slow: for a file importing
+ * a Reactive<T>-branded package (`@barefootjs/form`) the analyzer emits
+ * BF050 at severity `error` when no shared Program was supplied, and the
+ * plugin throws on error diagnostics — so without this manager such a file
+ * cannot build through the plugin at all. See #2537.
+ *
+ * This manager keeps ONE Program whose roots are every discovered file
+ * that `needsTypeBasedDetection` says needs a checker (a cheap content
+ * test — the majority of components don't and never pay anything). The
+ * type graph is built once per build (~hundreds of ms, amortized), and
+ * watch-mode rebuilds go through `ts.createProgram`'s `oldProgram`
+ * incremental path: unchanged files reuse their parsed SourceFiles, so a
+ * single-file edit re-parses only that file (tens of ms).
+ *
+ * Contract with the analyzer: `compileJSX` only uses a supplied Program if
+ * `program.getSourceFile(filePath).text` EXACTLY matches the source being
+ * compiled (a mismatched Program is silently discarded, which would
+ * re-open the per-file fallback and, for brand importers, BF050). Both
+ * entry points verify that text match and rebuild — or fall back to a
+ * virtual single-file Program for in-memory content that diverges from
+ * disk — rather than ever handing back a Program the analyzer would
+ * reject.
+ */
+import path from 'node:path'
+import type ts from 'typescript'
+import {
+  createProgramForCorpus,
+  createProgramForFile,
+  needsTypeBasedDetection,
+} from '@barefootjs/jsx'
+
+export class CorpusProgramManager {
+  private program: ts.Program | undefined
+  private roots = new Set<string>()
+
+  /**
+   * (Re)build the corpus Program from a full discovery pass's snapshot.
+   * Filters `files` down to the ones needing type-based detection; no-ops
+   * entirely (keeping the existing Program) when the root set and every
+   * root's on-Program text are unchanged — the common case for the dev
+   * watcher's full re-runs, where `CompileCache` already makes unchanged
+   * files free and this keeps the Program free too.
+   *
+   * Callers pass the content DISCOVERY read, and `createProgramForCorpus`'s
+   * host re-reads from disk — the two can only diverge if the file changed
+   * in the microseconds between, and `programFor`'s per-file text check
+   * catches exactly that before any compile trusts the Program.
+   */
+  seed(files: readonly { absPath: string; content: string }[]): void {
+    const needing = files
+      .filter(f => needsTypeBasedDetection(f.content))
+      .map(f => ({ abs: path.resolve(f.absPath), content: f.content }))
+
+    if (needing.length === 0) {
+      this.program = undefined
+      this.roots.clear()
+      return
+    }
+
+    const sameRoots =
+      needing.length === this.roots.size && needing.every(f => this.roots.has(f.abs))
+    const sameText =
+      sameRoots &&
+      this.program !== undefined &&
+      needing.every(f => this.program!.getSourceFile(f.abs)?.text === f.content)
+    if (sameText) return
+
+    this.roots = new Set(needing.map(f => f.abs))
+    this.rebuild()
+  }
+
+  /**
+   * The Program to pass as `CompileOptions.program` when compiling
+   * `absPath` with `content` — or `undefined` when the file doesn't need
+   * type-based detection at all (the analyzer then never builds a checker,
+   * and passing nothing costs nothing).
+   *
+   * Handles the two ways the seeded Program can be behind reality:
+   * - `absPath` isn't a root yet (a needing file created after the last
+   *   seed, reached by the graph pass before the next eager pass) or its
+   *   disk content changed: add the root and rebuild incrementally.
+   * - `content` diverges from what's on disk even after a rebuild (an
+   *   in-flight edit): fall back to a virtual single-file Program built
+   *   from `content` itself — the pre-manager per-file behavior, correct
+   *   and BF050-suppressing, just slow, and only for that one file until
+   *   disk catches up.
+   */
+  programFor(absPath: string, content: string): ts.Program | undefined {
+    if (!needsTypeBasedDetection(content)) return undefined
+    const abs = path.resolve(absPath)
+
+    const cached = this.program?.getSourceFile(abs)
+    if (cached && cached.text === content) return this.program
+
+    this.roots.add(abs)
+    this.rebuild()
+
+    const rebuilt = this.program?.getSourceFile(abs)
+    if (rebuilt && rebuilt.text === content) return this.program
+
+    return createProgramForFile(content, abs)?.program
+  }
+
+  private rebuild(): void {
+    try {
+      this.program = createProgramForCorpus([...this.roots], {
+        oldProgram: this.program,
+      })
+    } catch {
+      // A failed corpus build degrades to `programFor`'s virtual
+      // single-file fallback per needing file — slow but correct, and the
+      // same failure would almost certainly hit the per-file path too.
+      this.program = undefined
+    }
+  }
+}