@barefootjs/vite 0.33.2 → 0.33.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/vite",
-  "version": "0.33.2",
+  "version": "0.33.3",
   "description": "Vite plugin for BarefootJS: Vite/Rollup owns bundling, hashing, chunking, tree-shaking and minification of client assets, BarefootJS keeps only the JSX to (template, client JS) compile",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,17 +38,17 @@
     "directory": "packages/vite"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.33.2"
+    "@barefootjs/shared": "0.33.3"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0",
     "vite": "^6.0.0"
   },
   "devDependencies": {
-    "@barefootjs/client": "0.33.2",
-    "@barefootjs/go-template": "0.33.2",
-    "@barefootjs/hono": "0.33.2",
-    "@barefootjs/jsx": "0.33.2",
+    "@barefootjs/client": "0.33.3",
+    "@barefootjs/go-template": "0.33.3",
+    "@barefootjs/hono": "0.33.3",
+    "@barefootjs/jsx": "0.33.3",
     "typescript": "^5.0.0",
     "vite": "^6.0.0"
   }

package/src/__tests__/discover.test.ts

@@ -2,7 +2,13 @@ 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 { buildChildNameIndex, hasUseClientDirective, discoverComponentFiles, discoverComponents } from '../discover.ts'
+import {
+  buildChildNameIndex,
+  computeClientEntryPaths,
+  hasUseClientDirective,
+  discoverComponentFiles,
+  discoverComponents,
+} from '../discover.ts'
 
 describe('hasUseClientDirective', () => {
   test('detects a leading double-quoted directive', () => {
@@ -75,13 +81,124 @@ describe('discoverComponents', () => {
     expect(byName['Client.tsx']).toBe(true)
     expect(byName['Server.tsx']).toBe(false)
   })
+
+  // #2767: a plain server file that renders a 'use client' descendant needs
+  // its OWN client bundle too — it's the file whose compiled init actually
+  // owns the `initChild(...)` call reaching that descendant. Exercises the
+  // analyzer scan (`scanComponentFile`) + `computeClientEntryPaths` closure
+  // end to end, on real files, not fabricated rows.
+  test('a server parent that renders a client child needs its own client entry', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'barefoot-discover-entry-'))
+    await writeFile(join(dir, 'Child.tsx'), '\'use client\'\nexport function Child() { return <span/> }')
+    await writeFile(
+      join(dir, 'Parent.tsx'),
+      "import { Child } from './Child'\nexport function Parent() { return <div><Child/></div> }",
+    )
+    await writeFile(join(dir, 'Leaf.tsx'), 'export function Leaf() { return <span/> }')
+
+    const found = await discoverComponents([dir], p => Bun.file(p).text())
+    const byName = Object.fromEntries(found.map(f => [f.absPath.slice(dir.length + 1), f.needsClientEntry]))
+    expect(byName['Child.tsx']).toBe(true)
+    expect(byName['Parent.tsx']).toBe(true)
+    expect(byName['Leaf.tsx']).toBe(false)
+  })
+})
+
+describe('computeClientEntryPaths', () => {
+  test('a server parent that directly references a client child needs its own entry', () => {
+    const rows = [
+      { absPath: '/proj/Parent.tsx', isClient: false, exportedComponents: ['Parent'], referencedComponents: ['Child'] },
+      { absPath: '/proj/Child.tsx', isClient: true, exportedComponents: ['Child'], referencedComponents: [] },
+    ]
+    const entries = computeClientEntryPaths(rows)
+    expect(entries.has('/proj/Parent.tsx')).toBe(true)
+    expect(entries.has('/proj/Child.tsx')).toBe(true)
+  })
+
+  // A parent-of-client-only fix would miss this: every server file on the
+  // path from the SSR root down to the client descendant must ship its own
+  // bundle, since each one owns the `initChild` call reaching the next.
+  test('walks the transitive chain all the way up from a deeply nested client component', () => {
+    const rows = [
+      { absPath: '/proj/GreatGrand.tsx', isClient: false, exportedComponents: ['GreatGrand'], referencedComponents: ['Grandparent'] },
+      { absPath: '/proj/Grandparent.tsx', isClient: false, exportedComponents: ['Grandparent'], referencedComponents: ['Parent'] },
+      { absPath: '/proj/Parent.tsx', isClient: false, exportedComponents: ['Parent'], referencedComponents: ['Child'] },
+      { absPath: '/proj/Child.tsx', isClient: true, exportedComponents: ['Child'], referencedComponents: [] },
+    ]
+    const entries = computeClientEntryPaths(rows)
+    expect(entries.has('/proj/GreatGrand.tsx')).toBe(true)
+    expect(entries.has('/proj/Grandparent.tsx')).toBe(true)
+    expect(entries.has('/proj/Parent.tsx')).toBe(true)
+    expect(entries.has('/proj/Child.tsx')).toBe(true)
+  })
+
+  // The anti-regression: an all-server tree with zero client descendants
+  // anywhere must produce ZERO entries. A `analyzeClientNeeds(ir).needsInit`
+  // predicate would get this wrong (it's true for StaticParent purely
+  // because it references ServerChild at all) — this is exactly why the
+  // closure is seeded from `isClient`, not from the compiler's per-file
+  // "needs init" signal.
+  test('an all-server tree with no client descendants produces no entries at all', () => {
+    const rows = [
+      { absPath: '/proj/StaticParent.tsx', isClient: false, exportedComponents: ['StaticParent'], referencedComponents: ['ServerChild'] },
+      { absPath: '/proj/ServerChild.tsx', isClient: false, exportedComponents: ['ServerChild'], referencedComponents: [] },
+    ]
+    const entries = computeClientEntryPaths(rows)
+    expect(entries.size).toBe(0)
+  })
+
+  test('a server leaf with no component references is never an entry', () => {
+    const rows = [
+      { absPath: '/proj/Leaf.tsx', isClient: false, exportedComponents: ['Leaf'], referencedComponents: [] },
+    ]
+    expect(computeClientEntryPaths(rows).size).toBe(0)
+  })
+
+  // Cycle-safety: a mutual server↔server reference must terminate and stay
+  // empty; adding a client component into the cycle must pull in every
+  // member reachable from it, not just the one that references it directly.
+  test('is cycle-safe and still finds every member of a cycle once one member is a client entry', () => {
+    const allServer = [
+      { absPath: '/proj/A.tsx', isClient: false, exportedComponents: ['A'], referencedComponents: ['B'] },
+      { absPath: '/proj/B.tsx', isClient: false, exportedComponents: ['B'], referencedComponents: ['A'] },
+    ]
+    expect(computeClientEntryPaths(allServer).size).toBe(0)
+
+    const withClientMember = [
+      { absPath: '/proj/A.tsx', isClient: false, exportedComponents: ['A'], referencedComponents: ['B', 'C'] },
+      { absPath: '/proj/B.tsx', isClient: false, exportedComponents: ['B'], referencedComponents: ['A'] },
+      { absPath: '/proj/C.tsx', isClient: true, exportedComponents: ['C'], referencedComponents: [] },
+    ]
+    const entries = computeClientEntryPaths(withClientMember)
+    expect(entries.has('/proj/A.tsx')).toBe(true)
+    expect(entries.has('/proj/B.tsx')).toBe(true)
+    expect(entries.has('/proj/C.tsx')).toBe(true)
+  })
+
+  test('resolves a reference through a multi-export file, same as buildChildNameIndex', () => {
+    const rows = [
+      { absPath: '/proj/Parent.tsx', isClient: false, exportedComponents: ['Parent'], referencedComponents: ['CopyIcon'] },
+      { absPath: '/proj/icon/index.tsx', isClient: true, exportedComponents: ['CopyIcon', 'CheckIcon'], referencedComponents: [] },
+    ]
+    const entries = computeClientEntryPaths(rows)
+    expect(entries.has('/proj/Parent.tsx')).toBe(true)
+    expect(entries.has('/proj/icon/index.tsx')).toBe(true)
+  })
+
+  test('an unresolved tag name (e.g. a third-party import) is ignored, not a crash', () => {
+    const rows = [
+      { absPath: '/proj/Parent.tsx', isClient: false, exportedComponents: ['Parent'], referencedComponents: ['SomeExternalLib'] },
+    ]
+    expect(() => computeClientEntryPaths(rows)).not.toThrow()
+    expect(computeClientEntryPaths(rows).size).toBe(0)
+  })
 })
 
 describe('buildChildNameIndex', () => {
   test('keys \'use client\' files by their exported component names', () => {
     const index = buildChildNameIndex([
-      { absPath: '/proj/components/TodoItem.tsx', isClient: true, exportedComponents: ['TodoItem'] },
-      { absPath: '/proj/blog/LikeButton.tsx', isClient: true, exportedComponents: ['LikeButton'] },
+      { absPath: '/proj/components/TodoItem.tsx', needsClientEntry: true, exportedComponents: ['TodoItem'] },
+      { absPath: '/proj/blog/LikeButton.tsx', needsClientEntry: true, exportedComponents: ['LikeButton'] },
     ])
     expect(index.get('TodoItem')).toBe('/proj/components/TodoItem.tsx')
     expect(index.get('LikeButton')).toBe('/proj/blog/LikeButton.tsx')
@@ -95,7 +212,7 @@ describe('buildChildNameIndex', () => {
     const index = buildChildNameIndex([
       {
         absPath: '/proj/components/icon/index.tsx',
-        isClient: true,
+        needsClientEntry: true,
         exportedComponents: ['CopyIcon', 'CheckIcon'],
       },
     ])
@@ -109,8 +226,8 @@ describe('buildChildNameIndex', () => {
   // single-export `ui/button/index.tsx` was unreachable as a marker target.
   test('single-export colocated index.tsx files resolve by name, and never collide on "index"', () => {
     const index = buildChildNameIndex([
-      { absPath: '/proj/ui/button/index.tsx', isClient: true, exportedComponents: ['Button'] },
-      { absPath: '/proj/ui/toggle/index.tsx', isClient: true, exportedComponents: ['Toggle'] },
+      { absPath: '/proj/ui/button/index.tsx', needsClientEntry: true, exportedComponents: ['Button'] },
+      { absPath: '/proj/ui/toggle/index.tsx', needsClientEntry: true, exportedComponents: ['Toggle'] },
     ])
     expect(index.get('Button')).toBe('/proj/ui/button/index.tsx')
     expect(index.get('Toggle')).toBe('/proj/ui/toggle/index.tsx')
@@ -119,29 +236,40 @@ describe('buildChildNameIndex', () => {
 
   test('first writer wins on a duplicate name, so an earlier components dir shadows a later one', () => {
     const index = buildChildNameIndex([
-      { absPath: '/proj/a/Button.tsx', isClient: true, exportedComponents: ['Button'] },
-      { absPath: '/proj/b/Button.tsx', isClient: true, exportedComponents: ['Button'] },
+      { absPath: '/proj/a/Button.tsx', needsClientEntry: true, exportedComponents: ['Button'] },
+      { absPath: '/proj/b/Button.tsx', needsClientEntry: true, exportedComponents: ['Button'] },
     ])
     expect(index.get('Button')).toBe('/proj/a/Button.tsx')
   })
 
   test('falls back to the basename when no exports were parsed, keeping the old convention working', () => {
     const index = buildChildNameIndex([
-      { absPath: '/proj/components/Widget.tsx', isClient: true, exportedComponents: [] },
+      { absPath: '/proj/components/Widget.tsx', needsClientEntry: true, exportedComponents: [] },
     ])
     expect(index.get('Widget')).toBe('/proj/components/Widget.tsx')
   })
 
-  test('excludes server-only files — a @bf-child marker only ever names an interactive component', () => {
+  test('excludes files that need no client entry — a @bf-child marker only ever names a component whose bundle ships', () => {
     const index = buildChildNameIndex([
-      { absPath: '/proj/components/ServerOnly.tsx', isClient: false, exportedComponents: [] },
+      { absPath: '/proj/components/ServerOnly.tsx', needsClientEntry: false, exportedComponents: [] },
     ])
     expect(index.has('ServerOnly')).toBe(false)
   })
 
+  // #2767: `needsClientEntry`, not `isClient`, decides indexability — a
+  // plain server file that owns a 'use client' descendant is a legitimate
+  // `@bf-child:` marker target too, because IT is the file whose compiled
+  // init contains the `initChild(...)` call reaching that descendant.
+  test('indexes a server-only file whose subtree owns a client descendant (needsClientEntry: true)', () => {
+    const index = buildChildNameIndex([
+      { absPath: '/proj/components/ServerParent.tsx', needsClientEntry: true, exportedComponents: ['ServerParent'] },
+    ])
+    expect(index.get('ServerParent')).toBe('/proj/components/ServerParent.tsx')
+  })
+
   test('accepts a .ts extension too', () => {
     const index = buildChildNameIndex([
-      { absPath: '/proj/components/Widget.ts', isClient: true, exportedComponents: ['Widget'] },
+      { absPath: '/proj/components/Widget.ts', needsClientEntry: true, exportedComponents: ['Widget'] },
     ])
     expect(index.get('Widget')).toBe('/proj/components/Widget.ts')
   })

package/src/__tests__/e2e-vite-build.test.ts

@@ -65,10 +65,34 @@ describe('e2e: vite build', () => {
     expect(keys.some(k => k.endsWith('Counter.tsx'))).toBe(true)
     expect(keys.some(k => k.endsWith('SharedCounter.tsx'))).toBe(true)
     expect(keys.some(k => k.endsWith('counterState.tsx'))).toBe(true)
-    // Greeting.tsx has no 'use client' directive — never an entry.
+    // Greeting.tsx has no 'use client' directive AND no client descendant
+    // anywhere — the anti-regression guard: an all-server file must never
+    // become a spurious Rollup entry. See the `needsClientEntry` false case.
     expect(keys.some(k => k.endsWith('Greeting.tsx'))).toBe(false)
   })
 
+  // #2767: ServerParent/ServerGrandparent carry NO 'use client' directive at
+  // all — they're plain server components whose only reason to become
+  // entries is that they transitively render `Counter`. See
+  // `e2e-fixture/src/components/ServerParent.tsx` and
+  // `ServerGrandparent.tsx`.
+  test('a server component that renders a client descendant also becomes a Rollup entry, transitively', async () => {
+    const manifest = JSON.parse(await readFile(resolve(outDir, '.vite/manifest.json'), 'utf8'))
+    const keys = Object.keys(manifest)
+    const serverParentKey = keys.find(k => k.endsWith('ServerParent.tsx'))
+    const serverGrandparentKey = keys.find(k => k.endsWith('ServerGrandparent.tsx'))
+    expect(serverParentKey).toBeDefined()
+    expect(serverGrandparentKey).toBeDefined()
+
+    const counterKey = keys.find(k => k.endsWith('Counter.tsx') && !k.includes('Shared'))!
+
+    // Proof `@bf-child:` resolved through the fixed `buildChildNameIndex`
+    // to the REAL entry-to-entry import, not the no-op module — mirrors the
+    // LoopParent→LoopChild assertion below, one level deeper.
+    expect(manifest[serverParentKey!].imports).toContain(counterKey)
+    expect(manifest[serverGrandparentKey!].imports).toContain(serverParentKey)
+  })
+
   test('the runtime collapses into one shared chunk imported by every client entry', async () => {
     const manifest = JSON.parse(await readFile(resolve(outDir, '.vite/manifest.json'), 'utf8'))
     const counterKey = Object.keys(manifest).find(k => k.endsWith('Counter.tsx') && !k.includes('Shared'))!
@@ -147,6 +171,26 @@ describe('e2e: vite build', () => {
     expect(parentContent).not.toContain('bf-child')
   })
 
+  // #2767: each server component on the path to Counter owns the
+  // `initChild(...)` call reaching the NEXT link in the chain, so each one
+  // needs its OWN `Scripts.Register` — not just Counter's.
+  test('server components that transitively render a client descendant get their own script registration', async () => {
+    const manifest = JSON.parse(await readFile(resolve(outDir, '.vite/manifest.json'), 'utf8'))
+    const serverParentKey = Object.keys(manifest).find(k => k.endsWith('ServerParent.tsx'))!
+    const serverGrandparentKey = Object.keys(manifest).find(k => k.endsWith('ServerGrandparent.tsx'))!
+
+    const serverParentTemplate = await readFile(resolve(templatesDir, 'ServerParent.tmpl'), 'utf8')
+    const serverGrandparentTemplate = await readFile(resolve(templatesDir, 'ServerGrandparent.tmpl'), 'utf8')
+
+    expect(serverParentTemplate).toContain(`{{.Scripts.Register "/static/build/${manifest[serverParentKey].file}"}}`)
+    expect(serverGrandparentTemplate).toContain(
+      `{{.Scripts.Register "/static/build/${manifest[serverGrandparentKey].file}"}}`,
+    )
+  })
+
+  // Anti-regression guard, unchanged by #2767: a component with genuinely
+  // no client descendant anywhere must stay OUT of the Rollup graph and
+  // carry no script registration at all.
   test('emits a template for the server-only component (never in the Rollup graph) with NO script registration', async () => {
     const manifest = JSON.parse(await readFile(resolve(outDir, '.vite/manifest.json'), 'utf8'))
     expect(Object.keys(manifest).some(k => k.endsWith('Greeting.tsx'))).toBe(false)

package/src/__tests__/e2e-vite-dev.test.ts

@@ -135,6 +135,7 @@ describe('e2e: vite dev server', () => {
     // for its output to actually land on disk before asserting on it.
     await waitFor(async () => (await readIfExists(join(templatesDir, 'Counter.tmpl'))) !== null)
     await waitFor(async () => (await readIfExists(join(templatesDir, 'Greeting.tmpl'))) !== null)
+    await waitFor(async () => (await readIfExists(join(templatesDir, 'ServerParent.tmpl'))) !== null)
   }, 30_000)
 
   afterAll(async () => {
@@ -176,6 +177,25 @@ describe('e2e: vite dev server', () => {
     expect(template).toContain('Hello')
   })
 
+  // #2767: ServerParent has no 'use client' directive but renders Counter —
+  // it must get its OWN dev-origin script registration (the `@vite/client`
+  // entry plus its own `/@fs/…` module URL), mirroring the client-component
+  // assertion above, and that module URL must actually serve compiled JS
+  // whose init calls `initChild('Counter', ...)`.
+  test('a server component that renders a client descendant also gets dev-origin script registration', async () => {
+    const serverParentPath = join(COMPONENTS_DIR, 'ServerParent.tsx')
+    const requestPath = devRequestPath({ root: APP_ROOT }, serverParentPath)
+    const template = await readFile(join(templatesDir, 'ServerParent.tmpl'), 'utf8')
+
+    expect(template).toContain(`{{.Scripts.Register "${baseUrl}/@vite/client"}}`)
+    expect(template).toContain(`{{.Scripts.Register "${baseUrl}/${requestPath}"}}`)
+
+    const res = await fetch(`${baseUrl}/${requestPath}`)
+    expect(res.status).toBe(200)
+    const body = await res.text()
+    expect(body).toContain('initChild("Counter"')
+  })
+
   test('the templates dir carries the dev-artifact marker while the dev server is running', async () => {
     const marker = await readIfExists(join(templatesDir, '.barefootjs-dev-build'))
     expect(marker).not.toBeNull()

package/src/__tests__/plugin.test.ts

@@ -64,10 +64,20 @@ describe('config hook', () => {
     if (dir) await rm(dir, { recursive: true, force: true })
   })
 
-  test('sets appType custom, forces build.manifest, and keys rollupOptions.input by ONLY "use client" files', async () => {
+  test('sets appType custom, forces build.manifest, and keys rollupOptions.input by "use client" files AND the server components that own them (#2767)', async () => {
     dir = await mkdtemp(join(tmpdir(), 'barefoot-plugin-config-'))
     await mkdir(join(dir, 'src/components'), { recursive: true })
     await writeFile(join(dir, 'src/components/Counter.tsx'), '\'use client\'\nexport function Counter() { return <div/> }')
+    // Server component (no 'use client') that renders the client Counter —
+    // it must ALSO become an entry, since its own compiled init is the only
+    // place the `initChild('Counter', ...)` call reaching Counter lives.
+    await writeFile(
+      join(dir, 'src/components/Parent.tsx'),
+      "import { Counter } from './Counter'\nexport function Parent() { return <div><Counter/></div> }",
+    )
+    // Plain server leaf with no client descendant anywhere — must stay OUT
+    // of the entry list. This is the anti-regression: an all-server tree
+    // must not start shipping spurious empty bundles.
     await writeFile(join(dir, 'src/components/Greeting.tsx'), 'export function Greeting() { return <div/> }')
 
     const plugin = makePlugin('src/components', 'internal/views')
@@ -76,7 +86,10 @@ describe('config hook', () => {
     expect(result.appType).toBe('custom')
     expect(result.build.manifest).toBe(true)
     const inputPaths = Object.values(result.build.rollupOptions.input) as string[]
-    expect(inputPaths).toEqual([resolve(dir, 'src/components/Counter.tsx')])
+    expect(inputPaths.sort()).toEqual(
+      [resolve(dir, 'src/components/Counter.tsx'), resolve(dir, 'src/components/Parent.tsx')].sort(),
+    )
+    expect(inputPaths).not.toContain(resolve(dir, 'src/components/Greeting.tsx'))
   })
 
   test('produces no entries when nothing under components has "use client"', async () => {
@@ -258,6 +271,13 @@ describe('writeBundle: manifest → scriptAssets resolution', () => {
       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',
     )
+    // #2767: a plain server component that merely RENDERS Counter must get
+    // its own script registration too — it owns the `initChild('Counter', ...)`
+    // call, not Counter itself.
+    await writeFile(
+      join(dir, 'src/components/Parent.tsx'),
+      "import { Counter } from './Counter'\nexport function Parent() { return <div><Counter/></div> }",
+    )
     await writeFile(
       join(dir, 'src/components/Greeting.tsx'),
       'export function Greeting() { return <p>Hi</p> }',
@@ -288,17 +308,22 @@ describe('writeBundle: manifest → scriptAssets resolution', () => {
       join(dir, 'dist/.vite/manifest.json'),
       JSON.stringify({
         'src/components/Counter.tsx': { file: 'assets/Counter-abc123.js', isEntry: true },
+        'src/components/Parent.tsx': { file: 'assets/Parent-def456.js', isEntry: true },
       }),
     )
 
     await plugin.writeBundle()
 
     const counterTpl = await readFile(join(templatesDir, `Counter${adapter.extension}`), 'utf8')
+    const parentTpl = await readFile(join(templatesDir, `Parent${adapter.extension}`), 'utf8')
     const greetingTpl = await readFile(join(templatesDir, `Greeting${adapter.extension}`), 'utf8')
 
     expect(counterTpl).toContain('{{.Scripts.Register "/static/build/assets/Counter-abc123.js"}}')
-    // Server-only: never in the manifest → scriptAssets resolves to [] →
-    // no script registration text at all.
+    // The server parent needed a bundle too (#2767) and gets its own
+    // registration, from its OWN manifest entry — not Counter's.
+    expect(parentTpl).toContain('{{.Scripts.Register "/static/build/assets/Parent-def456.js"}}')
+    // Genuinely server-only, no client descendant: never in the manifest →
+    // scriptAssets resolves to [] → no script registration text at all.
     expect(greetingTpl).not.toContain('Scripts.Register')
     expect(greetingTpl).toContain('Hi')
   })

package/src/discover.ts

@@ -11,7 +11,7 @@
  */
 import { readdir } from 'node:fs/promises'
 import { basename, resolve } from 'node:path'
-import { listExportedComponents } from '@barefootjs/jsx'
+import { scanComponentFile } from '@barefootjs/jsx'
 
 /** Does `content` start with a `'use client'` / `"use client"` directive
  * (after skipping leading block/line comments)? */
@@ -95,14 +95,40 @@ export interface DiscoveredComponent {
   content: string
   /** Whether the file's content starts with a `'use client'` directive. */
   isClient: boolean
+  /**
+   * `isClient`, OR this file transitively instantiates a component that
+   * needs one — the property `computeClientEntryPaths` computes over the
+   * whole discovered corpus. This, not `isClient`, is the signal for
+   * "does this file need its own client bundle and a `<script>` on the
+   * page": a plain server component that merely renders a `'use client'`
+   * descendant still needs an `initChild(...)` call to run in the
+   * browser, and that call lives in ITS OWN compiled init, not the
+   * child's (issue #2767 — `hydrateElementScope` in
+   * `@barefootjs/client`'s `runtime/hydrate.ts` explicitly skips any
+   * element carrying the child marker, deferring to the parent's
+   * `initChild`; if the parent's own bundle never ships, that call never
+   * happens and the child never hydrates, silently).
+   */
+  needsClientEntry: boolean
   /**
    * Every component this file exports, from `@barefootjs/jsx`'s TS-AST
    * walk (`listExportedComponents`) — never a regex, and never the
    * basename standing in for the name. A file exporting more than one
    * component (`icon/index.tsx` → `CopyIcon` + `CheckIcon`) is why this
-   * exists; see `buildChildNameIndex`.
+   * exists; see `buildChildNameIndex`. Populated for EVERY file, not just
+   * client ones — `computeClientEntryPaths` resolves JSX tag references
+   * by name across the whole corpus, so a server file must be indexable
+   * too (it may itself be someone else's `referencedComponents` target).
    */
   exportedComponents: string[]
+  /**
+   * PascalCase JSX tag identifiers this file's JSX instantiates (its
+   * component-instantiation out-edges), from `@barefootjs/jsx`'s
+   * `scanComponentFile`. Feeds `computeClientEntryPaths` — never used for
+   * anything import-resolution-shaped, so an unresolved or aliased tag
+   * name is simply not an edge (see that function's docstring).
+   */
+  referencedComponents: string[]
   /**
    * `CompileOptions.cssLayerPrefix` this file should compile with, carried
    * over unchanged from whichever `components` entry's `dir` this file was
@@ -151,7 +177,7 @@ export async function discoverComponents(
   readFile: (absPath: string) => Promise<string>,
 ): Promise<DiscoveredComponent[]> {
   const seen = new Set<string>()
-  const out: DiscoveredComponent[] = []
+  const out: Omit<DiscoveredComponent, 'needsClientEntry'>[] = []
   for (const raw of entries) {
     const entry: ResolvedComponentDirEntry = typeof raw === 'string' ? { dir: raw } : raw
     for (const absPath of await discoverComponentFiles(entry.dir, { skipDirs: entry.skipDirs })) {
@@ -159,19 +185,132 @@ export async function discoverComponents(
       seen.add(absPath)
       const content = await readFile(absPath)
       const isClient = hasUseClientDirective(content)
-      // Only client files can be `@bf-child:` targets, so only they need
-      // their export list parsed — this is a `ts.createSourceFile` per
-      // file and server-only components are the majority in most trees.
+      // One parse gets both the export list AND the JSX tags this file
+      // references — every file needs both now, not just client ones:
+      // `computeClientEntryPaths` walks the instantiation graph across
+      // the whole corpus, so a server file must carry its out-edges (and
+      // be indexable by name) too.
+      const scan = scanComponentFile(content, absPath)
       out.push({
         absPath,
         content,
         isClient,
-        exportedComponents: isClient ? listExportedComponents(content, absPath) : [],
+        exportedComponents: scan.exports,
+        referencedComponents: scan.referencedComponents,
         cssLayerPrefix: entry.cssLayerPrefix,
       })
     }
   }
-  return out
+  const clientEntryPaths = computeClientEntryPaths(out)
+  return out.map(row => ({ ...row, needsClientEntry: clientEntryPaths.has(row.absPath) }))
+}
+
+/**
+ * The component-name → absolute-path index shared by `computeClientEntryPaths`
+ * (resolving JSX-tag out-edges to the file that exports them) and
+ * `buildChildNameIndex` (resolving `@bf-child:<Name>` markers) — both need
+ * the identical "exported names, falling back to the basename when the AST
+ * walk found none; first writer wins on a duplicate name" rule, so it lives
+ * in exactly one place. `include` lets each caller restrict which rows are
+ * indexable: `computeClientEntryPaths` indexes every row (a server file can
+ * be another file's out-edge target), `buildChildNameIndex` only rows that
+ * ended up needing a client entry (a marker can only ever resolve to a file
+ * that actually ships a bundle).
+ */
+function nameIndexOver<T extends Pick<DiscoveredComponent, 'absPath' | 'exportedComponents'>>(
+  rows: readonly T[],
+  include: (row: T) => boolean,
+): Map<string, string> {
+  const index = new Map<string, string>()
+  for (const c of rows) {
+    if (!include(c)) continue
+    const names = c.exportedComponents.length > 0
+      ? c.exportedComponents
+      : [basename(c.absPath).replace(/\.tsx?$/, '')]
+    for (const name of names) {
+      if (!index.has(name)) index.set(name, c.absPath)
+    }
+  }
+  return index
+}
+
+/**
+ * Which discovered files need their OWN client bundle and `<script>` tag on
+ * the page: every `'use client'` file (the seed set), plus every file that
+ * transitively instantiates one — a plain server component nested between
+ * the SSR root and a `'use client'` descendant still needs its own compiled
+ * `init` to run in the browser, because that's the ONLY place the
+ * `initChild(...)` call reaching the client descendant is emitted (issue
+ * #2767; see `DiscoveredComponent.needsClientEntry`'s docstring). A nested
+ * component can't self-hydrate to make up for a missing parent bundle: its
+ * SSR root carries the child marker (`bf-h`), which `hydrateElementScope`
+ * (`@barefootjs/client`'s `runtime/hydrate.ts`) unconditionally skips,
+ * deferring to a parent's `initChild` call that only exists if the parent's
+ * own bundle shipped.
+ *
+ * Deliberately NOT `analyzeClientNeeds(ir).needsInit` (the compiler's
+ * per-file "does this file's compiled init do anything nontrivial" signal)
+ * — that's true for almost any server component with dynamic content at
+ * all (a prop interpolation, a conditional, a `.map()`, a plain
+ * `onClick`...), not just ones that own a client descendant. Gating Vite
+ * entries on it would bundle huge swaths of purely-server trees that have
+ * nothing to hydrate. The property this function computes — "is there a
+ * `'use client'` file reachable via component-instantiation edges" — is
+ * inherently cross-file, so it can only be answered here, with the whole
+ * discovered corpus in hand, not by any single-file compiler analysis.
+ *
+ * Pure structural closure over JSX tag references — no compile. Resolves
+ * each file's `referencedComponents` (JSX tag names) to the file that
+ * exports that name via the shared `nameIndexOver` index, then walks the
+ * REVERSE edges breadth-first from the `isClient` seed set. Cycle-safe (a
+ * visited-set) and runs in O(files + edges); on this repo's real
+ * `ui`/`site` component corpus (~260 files) the whole discovery pass
+ * (parse + this closure) costs low-single-digit milliseconds.
+ *
+ * The closure only ever needs to walk upward from a `'use client'` seed:
+ * a client file cannot legally import a server component in the first
+ * place (`analyzer.ts`'s `validateClientImports` raises BF003, a hard
+ * compile error), so there is no "server child of a client parent needing
+ * its own entry" shape to account for.
+ */
+export function computeClientEntryPaths(
+  rows: readonly Pick<DiscoveredComponent, 'absPath' | 'isClient' | 'exportedComponents' | 'referencedComponents'>[],
+): Set<string> {
+  const nameToPath = nameIndexOver(rows, () => true)
+
+  // Reverse edges: referencers.get(g) = every file that references a name
+  // resolving to g.
+  const referencers = new Map<string, Set<string>>()
+  for (const row of rows) {
+    for (const name of row.referencedComponents) {
+      const target = nameToPath.get(name)
+      if (!target || target === row.absPath) continue
+      let set = referencers.get(target)
+      if (!set) {
+        set = new Set()
+        referencers.set(target, set)
+      }
+      set.add(row.absPath)
+    }
+  }
+
+  const visited = new Set<string>()
+  const queue: string[] = []
+  for (const row of rows) {
+    if (row.isClient && !visited.has(row.absPath)) {
+      visited.add(row.absPath)
+      queue.push(row.absPath)
+    }
+  }
+  while (queue.length > 0) {
+    const current = queue.shift() as string
+    for (const referencer of referencers.get(current) ?? []) {
+      if (visited.has(referencer)) continue
+      visited.add(referencer)
+      queue.push(referencer)
+    }
+  }
+  return visited
 }
 
 /**
@@ -182,10 +321,16 @@ export async function discoverComponents(
  * `resolveId` needs a name→file lookup built from a full discovery pass.
  *
  * Keyed by each exported component NAME, which is what the marker
- * carries. Server-only files are excluded: a `@bf-child:` marker only
- * ever names another component this one instantiates at runtime
- * (`initChild`/`createComponent`), which requires an `init` function only
- * a `'use client'` file has.
+ * carries. Files that don't need their own client entry are excluded: a
+ * `@bf-child:` marker only ever names another component this one
+ * instantiates at runtime (`initChild`/`createComponent`), which requires
+ * a REAL `init` — and a file with `needsClientEntry: false` compiles to a
+ * no-op template-only mount (`generateTemplateOnlyMount` in
+ * `@barefootjs/jsx`'s `ir-to-client-js`), nothing to jump to. This is
+ * `needsClientEntry`, not `isClient` — a plain server file that owns a
+ * `'use client'` descendant is a legitimate marker target too (issue
+ * #2767: it's the file whose compiled init actually contains the
+ * `initChild(...)` call reaching that descendant).
  *
  * This used to key on the file's basename, which worked only because the
  * one-component-per-file convention makes the two coincide
@@ -211,20 +356,7 @@ export function buildChildNameIndex(
   // Only the fields the index actually reads — callers with a full
   // `DiscoveredComponent[]` pass it as-is, and tests can construct rows
   // without dragging in `content`.
-  discovered: readonly Pick<DiscoveredComponent, 'absPath' | 'isClient' | 'exportedComponents'>[],
+  discovered: readonly Pick<DiscoveredComponent, 'absPath' | 'needsClientEntry' | 'exportedComponents'>[],
 ): Map<string, string> {
-  const index = new Map<string, string>()
-  for (const c of discovered) {
-    if (!c.isClient) continue
-    // Fall back to the basename when the AST walk found no exports: a
-    // file can still be a marker target through the old convention, and
-    // losing that would be a regression rather than a fix.
-    const names = c.exportedComponents.length > 0
-      ? c.exportedComponents
-      : [basename(c.absPath).replace(/\.tsx?$/, '')]
-    for (const name of names) {
-      if (!index.has(name)) index.set(name, c.absPath)
-    }
-  }
-  return index
+  return nameIndexOver(discovered, c => c.needsClientEntry)
 }