@barefootjs/vite 0.30.0

package/src/debounced-serial-runner.ts

@@ -0,0 +1,67 @@
+/**
+ * Debounce + serialize an async task behind a single `trigger()` entry
+ * point. Built for `configureServer`'s watcher handlers: a burst of
+ * `'change'`/`'add'`/`'unlink'` events (save-twice-quickly, a multi-file
+ * save, a `git checkout` touching many files) must not start several
+ * overlapping eager passes writing the same template files.
+ *
+ * Two, deliberately separate, guarantees:
+ *  - **debounce**: `trigger()` calls within `debounceMs` of each other
+ *    collapse into a single scheduled run.
+ *  - **serialize + coalesce**: if `task()` is still running when the
+ *    debounce timer fires, this does NOT start a second, overlapping
+ *    call — it marks exactly one follow-up run, which starts the instant
+ *    the in-flight one finishes. A change arriving mid-pass is delayed,
+ *    never dropped, and at most one run is ever in flight.
+ *
+ * Deliberately minimal: no queue of distinct payloads, no rehashing —
+ * `task()` itself (the caller's full eager pass) is the unit of work, and
+ * it re-discovers everything from disk on every call, so "run it again"
+ * is always correct regardless of how many trigger()s piled up.
+ */
+export interface DebouncedSerialRunner {
+  /** Schedule a run, debounced. Safe to call from multiple event sources. */
+  trigger(): void
+}
+
+export function createDebouncedSerialRunner(
+  task: () => Promise<void>,
+  debounceMs: number,
+  onError: (err: unknown) => void,
+): DebouncedSerialRunner {
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  let running: Promise<void> | null = null
+  let rerunQueued = false
+
+  function runOnce(): void {
+    if (running) {
+      // A task is already in flight — don't start a second one racing it
+      // to write the same files. Queue exactly one follow-up instead;
+      // repeated triggers while running collapse into that same single
+      // follow-up (the `do`/`while` below re-checks the flag, not a count).
+      rerunQueued = true
+      return
+    }
+
+    running = (async () => {
+      do {
+        rerunQueued = false
+        await task()
+      } while (rerunQueued)
+    })()
+      .catch(onError)
+      .finally(() => {
+        running = null
+      })
+  }
+
+  return {
+    trigger() {
+      if (debounceTimer) clearTimeout(debounceTimer)
+      debounceTimer = setTimeout(() => {
+        debounceTimer = null
+        runOnce()
+      }, debounceMs)
+    },
+  }
+}

package/src/dev-server.ts

@@ -0,0 +1,184 @@
+/**
+ * Dev-server-only helpers for the `configureServer` hook: computing the
+ * dev origin, building the two-URL `scriptAssets` list a `'use client'`
+ * component needs in dev (the `@vite/client` HMR/full-reload socket plus
+ * the component's own `.tsx` module), the localhost-only CORS default,
+ * the on-disk marker that flags a `templates` directory as holding dev
+ * artifacts (localhost URLs baked in) rather than production output, and
+ * the cross-language dev-reload sentinel path (see `devSentinelPath`'s
+ * docstring).
+ *
+ * The pure, easily-unit-tested pieces live here; the orchestration
+ * (compiling, writing files, wiring the watcher) stays in `plugin.ts`
+ * where the shared `CompileCache` / `componentDirs` / `templatesDir`
+ * closures already live.
+ */
+import { resolve, sep } from 'node:path'
+import type { ResolvedConfig, ViteDevServer } from 'vite'
+import { joinBaseAndFile } from './manifest.ts'
+
+/**
+ * Vite's absolute-path passthrough prefix (`/@fs/…`, `FS_PREFIX` in Vite's
+ * own source) for serving files outside the project root. Needed because
+ * `components` dirs are commonly siblings of the Vite project root in this
+ * monorepo's real layouts — an app's `vite.config.ts` root is the backend
+ * app directory, while shared components live in a sibling `ui/`-style
+ * directory Vite's default dev serving otherwise refuses (only `root` and
+ * its subdirectories are served as plain paths).
+ */
+const FS_SERVE_PREFIX = '@fs'
+
+/**
+ * Localhost-only CORS default this plugin fills in — ONLY when the user
+ * hasn't configured `server.cors` themselves (see the `config` hook in
+ * `plugin.ts`). Vite 6+ defaults `cors` to same-origin-only, which breaks
+ * the cross-origin split this plugin sets up (the page is rendered by the
+ * backend on its own origin; modules are served by Vite on another)
+ * unless something opts localhost origins in. Deliberately not a wildcard
+ * `true` — see the PR brief for the reasoning.
+ */
+export const DEFAULT_DEV_CORS_ORIGIN = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/
+
+/**
+ * Debounce window (ms) for the dev watcher's `'change'` / `'add'` /
+ * `'unlink'` handlers — long enough to coalesce a save-twice-quickly or a
+ * multi-file save/`git checkout` into a single eager pass, short enough
+ * that a reload still feels instant.
+ */
+export const DEV_WATCH_DEBOUNCE_MS = 100
+
+/** Posix-normalize an absolute filesystem path (Windows uses `sep`; POSIX
+ * paths already use `/`). */
+function toPosixAbsolute(absPath: string): string {
+  return absPath.split(sep).join('/')
+}
+
+/**
+ * The request path (relative to `config.base`, no leading slash) a browser
+ * must use to reach `absPath` through Vite's dev server: a root-relative
+ * path when `absPath` is under `config.root`, or Vite's `/@fs/`
+ * absolute-path passthrough when it isn't.
+ */
+export function devRequestPath(config: Pick<ResolvedConfig, 'root'>, absPath: string): string {
+  const posixAbs = toPosixAbsolute(absPath)
+  const posixRoot = toPosixAbsolute(config.root)
+  if (posixAbs === posixRoot) return ''
+  if (posixAbs.startsWith(`${posixRoot}/`)) return posixAbs.slice(posixRoot.length + 1)
+  return `${FS_SERVE_PREFIX}${posixAbs}`
+}
+
+/** Full absolute URL (origin + `base` + request path) for `absPath` under
+ * the dev server. */
+export function devModuleUrl(
+  config: Pick<ResolvedConfig, 'root' | 'base'>,
+  origin: string,
+  absPath: string,
+): string {
+  return `${origin}${joinBaseAndFile(config.base, devRequestPath(config, absPath))}`
+}
+
+/**
+ * The ordered `scriptAssets` a `'use client'` component needs in dev: the
+ * `@vite/client` HMR/full-reload socket first (so the page always gets a
+ * live-reload connection), then the component's own module — Vite serves
+ * it plain-JS via this plugin's `transform` hook exactly like it would any
+ * other dev module, no different from a production entry. Per the design,
+ * server-only components (no `'use client'`) get `[]` — computed by the
+ * caller without consulting this function at all, see `plugin.ts`.
+ */
+export function devScriptAssets(
+  config: Pick<ResolvedConfig, 'root' | 'base'>,
+  origin: string,
+  absPath: string,
+): string[] {
+  return [
+    `${origin}${joinBaseAndFile(config.base, '@vite/client')}`,
+    devModuleUrl(config, origin, absPath),
+  ]
+}
+
+/**
+ * The dev origin to bake into `scriptAssets`: the user's own
+ * `server.origin` if they set one, otherwise `http://localhost:<port>`
+ * using the port Vite actually bound — NOT the configured port, which can
+ * be wrong (Vite auto-increments past an in-use port unless `strictPort`
+ * is set). Also writes the computed default back onto
+ * `server.config.server.origin` so Vite's OWN asset-URL rewriting
+ * (`import.meta.url`, CSS `url()`, etc.) agrees with the URLs this plugin
+ * bakes into templates — both need to match for the cross-origin split
+ * (page from the backend, assets from Vite) to work end to end.
+ *
+ * Call only after the server is actually listening (`httpServer`'s
+ * `'listening'` event) — the resolved port isn't known before then.
+ */
+export function resolveDevOrigin(server: ViteDevServer): string {
+  const configured = server.config.server.origin
+  if (configured) return configured
+
+  const address = server.httpServer?.address()
+  const port = address && typeof address === 'object' ? address.port : (server.config.server.port ?? 5173)
+  const origin = `http://localhost:${port}`
+  server.config.server.origin = origin
+  return origin
+}
+
+/**
+ * Filename of the marker BarefootJS writes at the root of `templates`
+ * while the dev server is running, so a stray `git add` or a production
+ * deploy of dev-only output (localhost URLs baked into every template) is
+ * obvious before it ships. `writeBundle` (the `vite build` path) removes
+ * it — see `plugin.ts`.
+ *
+ * A per-template, per-adapter comment (Go `{{/* … *\/}}`, ERB `<%# … %>`,
+ * etc.) would pinpoint the problem more precisely, but needs new surface
+ * on every `TemplateAdapter` implementation across 9+ adapter packages —
+ * out of scope for a dev-server PR that touches none of them. The brief
+ * explicitly allows this single-file fallback in that case.
+ */
+export const DEV_ARTIFACT_MARKER_FILENAME = '.barefootjs-dev-build'
+
+export const DEV_ARTIFACT_MARKER_CONTENT = `This directory currently holds DEV BUILD OUTPUT from @barefootjs/vite's
+dev server, not a production build.
+
+Every template in this directory has dev-only URLs baked into it
+(http://localhost:<port>/...) pointing at the Vite dev server. They will
+break if committed, deployed, or served without that dev server running.
+
+Run \`vite build\` to regenerate this directory with real, hashed,
+production asset URLs — the build overwrites every template here and
+removes this file.
+`
+
+/**
+ * Cross-language dev-reload sentinel: `<outDir>/.dev/build-id`, ONE
+ * DIRECTORY ABOVE `templates`. The path is fixed, not derived from
+ * `templatesDir`, because several server runtimes below poll this exact
+ * location.
+ *
+ * Several adapter runtimes poll this exact path for a value change and
+ * push an SSE `event: reload` on it — a mechanism that does NOT require
+ * the polling process to restart, only the file's mtime/content to
+ * change: `bfdev.NewReloadHandler` (Go — echo/gin/chi/nethttp),
+ * `Mojolicious::Plugin::BarefootJS::DevReload` /
+ * `BarefootJS::DevReload` (Perl — mojolicious/xslate), and
+ * `barefoot_js/dev_reload.rb` (Ruby — sinatra/rails, ERB). `vite dev` is
+ * the only piece of the dev loop those adapters' apps run alongside — if
+ * this plugin didn't write the sentinel, nothing would, and their reload
+ * handlers would never fire.
+ *
+ * Hono's dev-reload story does not consume this at all: both its
+ * Cloudflare Workers target (`dev-worker.ts`'s boot id) and its Node
+ * target (`barefootDevReload`'s SSE endpoint, wired up in the scaffold's
+ * `factory.ts`) detect a restart directly over their own SSE connection,
+ * no file involved. Writing this sentinel unconditionally whenever
+ * `templates` is configured is harmless there — nothing reads it — which
+ * is what keeps this a zero-config, adapter-agnostic signal rather than a
+ * 4th plugin option naming which adapters want it.
+ */
+export const DEV_SENTINEL_SUBDIR = '.dev'
+export const DEV_SENTINEL_FILENAME = 'build-id'
+
+/** Absolute path of the dev-reload sentinel for a given `templates` dir. */
+export function devSentinelPath(templatesDir: string): string {
+  return resolve(templatesDir, '..', DEV_SENTINEL_SUBDIR, DEV_SENTINEL_FILENAME)
+}

package/src/discover.ts

@@ -0,0 +1,230 @@
+/**
+ * Component discovery: which `.tsx` files live under the configured
+ * `components` dirs, and which of those carry a `'use client'` directive.
+ *
+ * `hasUseClientDirective` and `discoverComponentFiles` are implemented
+ * standalone rather than imported from `@barefootjs/cli` — that package's
+ * `exports` map only publishes the `bf` binary entry point, not an
+ * internal module path, and pulling in the CLI's whole dependency graph
+ * for two small pure functions would be the wrong shape for a Vite
+ * plugin. See CLAUDE.md: "reuse or port it, don't reinvent."
+ */
+import { readdir } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+import { listExportedComponents } from '@barefootjs/jsx'
+
+/** Does `content` start with a `'use client'` / `"use client"` directive
+ * (after skipping leading block/line comments)? */
+export function hasUseClientDirective(content: string): boolean {
+  let trimmed = content.trimStart()
+  // Skip block comments
+  while (trimmed.startsWith('/*')) {
+    const endIndex = trimmed.indexOf('*/')
+    if (endIndex === -1) break
+    trimmed = trimmed.slice(endIndex + 2).trimStart()
+  }
+  // Skip line comments
+  while (trimmed.startsWith('//')) {
+    const endIndex = trimmed.indexOf('\n')
+    if (endIndex === -1) break
+    trimmed = trimmed.slice(endIndex + 1).trimStart()
+  }
+  return trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'")
+}
+
+/**
+ * Is `name` (a bare filename, not a path) a component source file this
+ * plugin should discover/compile? `.tsx`, excluding `.test.tsx`,
+ * `.spec.tsx`, and `.preview.tsx`. Exported separately from
+ * `discoverComponentFiles` so the dev-server file watcher (`plugin.ts`'s
+ * `configureServer`) can apply the exact same filter to a single changed
+ * path without re-walking a directory.
+ */
+export function isComponentSourceFile(name: string): boolean {
+  return (
+    name.endsWith('.tsx') &&
+    !name.endsWith('.test.tsx') &&
+    !name.endsWith('.spec.tsx') &&
+    !name.endsWith('.preview.tsx')
+  )
+}
+
+/**
+ * Recursively discover `.tsx` component files in a directory.
+ * Skips `.test.tsx`, `.spec.tsx`, and `.preview.tsx` files.
+ */
+export async function discoverComponentFiles(
+  dir: string,
+  options?: { skipDirs?: string[] }
+): Promise<string[]> {
+  const results: string[] = []
+  const skipDirs = options?.skipDirs ? new Set(options.skipDirs) : null
+
+  let entries: { name: string; isDirectory(): boolean }[]
+  try {
+    entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) =>
+      String(a.name).localeCompare(String(b.name))
+    )
+  } catch {
+    return results
+  }
+
+  for (const entry of entries) {
+    const fullPath = resolve(dir, String(entry.name))
+    if (entry.isDirectory()) {
+      if (skipDirs?.has(String(entry.name))) continue
+      results.push(...await discoverComponentFiles(fullPath, options))
+    } else if (isComponentSourceFile(String(entry.name))) {
+      results.push(fullPath)
+    }
+  }
+
+  return results
+}
+
+export interface DiscoveredComponent {
+  /** Absolute path to the `.tsx` source file. */
+  absPath: string
+  /**
+   * The file's full source text, as read by the discovery pass. Retained
+   * (discovery had to read it anyway for the directive/exports checks) so
+   * downstream consumers — the corpus-program seeding and the eager pass's
+   * compile loop — work from the SAME snapshot discovery classified,
+   * instead of re-reading and racing an edit that landed in between.
+   */
+  content: string
+  /** Whether the file's content starts with a `'use client'` directive. */
+  isClient: 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`.
+   */
+  exportedComponents: string[]
+  /**
+   * `CompileOptions.cssLayerPrefix` this file should compile with, carried
+   * over unchanged from whichever `components` entry's `dir` this file was
+   * discovered under (see `ResolvedComponentDirEntry.cssLayerPrefix`).
+   * `undefined` when that entry set none (or was a plain string entry).
+   */
+  cssLayerPrefix?: string
+}
+
+/**
+ * A `components` directory to scan, already resolved to an absolute `dir`,
+ * plus the per-directory compile behavior `barefoot()`'s `ComponentDirEntry`
+ * (`types.ts`) carries. `discoverComponents` also accepts a plain absolute
+ * path string as shorthand for `{ dir: string }` — the same "string is
+ * exactly equivalent to `{ dir }`" equivalence `ComponentDirEntry` itself
+ * documents — so existing callers that only ever had bare directories
+ * (`integrations/h3`/`elysia`'s `vite.config.ts`, reusing this exported
+ * function to resolve every discovered client component's URL) keep
+ * compiling and behaving unchanged.
+ */
+export interface ResolvedComponentDirEntry {
+  /** Absolute path to the source directory to scan. */
+  dir: string
+  /** Stamped onto every `DiscoveredComponent` found under `dir` — see
+   * `DiscoveredComponent.cssLayerPrefix`. */
+  cssLayerPrefix?: string
+  /** Directory NAMES to skip anywhere under `dir` — passed straight
+   * through to `discoverComponentFiles`. */
+  skipDirs?: string[]
+}
+
+/**
+ * Scan every configured `components` directory for `.tsx` files and
+ * classify each as client (`'use client'`) or server-only. Each entry may
+ * be a plain absolute path (shorthand for `{ dir }`, no `cssLayerPrefix`/
+ * `skipDirs`) or a `ResolvedComponentDirEntry`.
+ *
+ * A file reachable under more than one entry is discovered once, stamped
+ * with the FIRST matching entry's `cssLayerPrefix` — entries are walked in
+ * array order and `seen` short-circuits every later match, the same
+ * first-writer-wins precedence `buildChildNameIndex` already documents for
+ * `@bf-child:` name collisions.
+ */
+export async function discoverComponents(
+  entries: readonly (string | ResolvedComponentDirEntry)[],
+  readFile: (absPath: string) => Promise<string>,
+): Promise<DiscoveredComponent[]> {
+  const seen = new Set<string>()
+  const out: DiscoveredComponent[] = []
+  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 })) {
+      if (seen.has(absPath)) continue
+      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.
+      out.push({
+        absPath,
+        content,
+        isClient,
+        exportedComponents: isClient ? listExportedComponents(content, absPath) : [],
+        cssLayerPrefix: entry.cssLayerPrefix,
+      })
+    }
+  }
+  return out
+}
+
+/**
+ * Component-name → absolute-path index used to resolve `@bf-child:<Name>`
+ * markers (see `child-marker.ts`) to a real file: a bare-marker child
+ * reference embeds only the referenced component's NAME (the compiler has
+ * no filesystem access at that phase — see `child-components.ts`), so
+ * `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.
+ *
+ * This used to key on the file's basename, which worked only because the
+ * one-component-per-file convention makes the two coincide
+ * (`TodoItem.tsx` exports `TodoItem`). A file exporting several
+ * components broke it silently: `icon/index.tsx` was keyed `index`, so
+ * `@bf-child:CopyIcon` found nothing and fell through to the no-op module
+ * (`plugin.ts`'s `resolveId`) — a child that never hydrates, with no
+ * diagnostic.
+ *
+ * The blast radius was wider than multi-export files. Because the key was
+ * the bare basename, EVERY colocated `index.tsx` collided on the single
+ * key `"index"` — including single-export ones like `ui/button/index.tsx`
+ * exporting `Button`. No colocated component was reachable as a
+ * `@bf-child:` target at all, whatever its export count. Measured with
+ * `listExportedComponents` over `ui/components` + `site/ui/components`:
+ * 112 files export more than one component, 105 of them `'use client'`.
+ *
+ * First writer wins on a duplicate name, and discovery order is the
+ * `components` option's order — so an earlier directory shadows a later
+ * one, the same precedence the option list already implies.
+ */
+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'>[],
+): 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
+}

package/src/emit.ts

@@ -0,0 +1,66 @@
+/**
+ * Turn a `CompileResult` into on-disk files under the configured
+ * `templates` dir, mirroring the component's position under its
+ * `components` source dir.
+ *
+ * Adapter-generated `types` output (e.g. Go's per-component Props struct +
+ * `NewXxxProps` constructor) is written RAW, one file per source, rather
+ * than combined into a single backend-native file (Go's `components.go`).
+ * Combining is a real per-language operation — for Go specifically it
+ * means stripping each fragment's `package`/import header and injecting a
+ * single shared `randomID` helper the individual fragments assume exists
+ * (see `@barefootjs/go-template/go-types.ts`'s `combineGoTypes`) — and it
+ * lives entirely OUTSIDE this core plugin, in each adapter's own `/vite`
+ * composition wrapper, driven by core's `afterEmit` escape hatch (see
+ * `AfterEmitContext`). Each `.types` fragment is written next to its
+ * template so it's visible on disk, but treat it as source material, not a
+ * ready-to-compile file.
+ */
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import type { CompileResult, TemplateAdapter } from '@barefootjs/jsx'
+import { perComponentRelPath, relativeUnderComponentDir, withExtension } from './paths.ts'
+
+export interface EmitTarget {
+  /** POSIX path, relative to the `templates` dir. */
+  relPath: string
+  content: string
+}
+
+export function planEmits(
+  result: CompileResult,
+  absPath: string,
+  componentDirs: readonly string[],
+  adapter: TemplateAdapter,
+): EmitTarget[] {
+  const relUnderComponentDir = relativeUnderComponentDir(absPath, componentDirs)
+  const targets: EmitTarget[] = []
+
+  for (const tpl of result.files.filter(f => f.type === 'markedTemplate')) {
+    const relPath = adapter.templatesPerComponent && tpl.componentName
+      ? perComponentRelPath(relUnderComponentDir, tpl.componentName, adapter.extension)
+      : withExtension(relUnderComponentDir, adapter.extension)
+    targets.push({ relPath, content: tpl.content })
+  }
+
+  for (const ssr of result.files.filter(f => f.type === 'ssrDefaults')) {
+    const relPath = adapter.templatesPerComponent && ssr.componentName
+      ? perComponentRelPath(relUnderComponentDir, ssr.componentName, '.ssr-defaults.json')
+      : withExtension(relUnderComponentDir, '.ssr-defaults.json')
+    targets.push({ relPath, content: ssr.content })
+  }
+
+  for (const types of result.files.filter(f => f.type === 'types')) {
+    targets.push({ relPath: withExtension(relUnderComponentDir, '.types'), content: types.content })
+  }
+
+  return targets
+}
+
+export async function writeEmits(templatesDir: string, targets: EmitTarget[]): Promise<void> {
+  for (const target of targets) {
+    const outPath = resolve(templatesDir, target.relPath)
+    await mkdir(dirname(outPath), { recursive: true })
+    await writeFile(outPath, target.content)
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { barefoot, PLUGIN_NAME } from './plugin.ts'
+export { barefoot as default } from './plugin.ts'
+export type { AfterEmitContext, BarefootPluginApi, BarefootViteOptions, ComponentDirEntry } from './types.ts'
+
+// Re-exported so an adapter's own `/vite` subpath (e.g.
+// `@barefootjs/go-template/vite`) can resolve script/asset URLs the SAME
+// way this plugin's own `writeBundle`/`configureServer` do, for entries
+// this plugin's own component discovery never sees (e.g. a hand-written
+// client bootstrap script) — reused, not re-derived, per CLAUDE.md.
+export { loadManifest, resolveScriptAssets, joinBaseAndFile } from './manifest.ts'
+export { devModuleUrl, devRequestPath, resolveDevOrigin } from './dev-server.ts'
+export { toPosixRelative } from './paths.ts'
+
+// Re-exported for the same reason: a host framework with no per-request
+// script collector (h3, Elysia — see `@barefootjs/hono/vite`'s docstring)
+// has to build its OWN full component-name -> URL map (there is no
+// per-request SSR collector to derive it from at request time), via the
+// SAME `assets` mechanism `@barefootjs/go-template/vite`/`@barefootjs/hono/
+// vite` already expose for a single hand-written entry — just populated
+// from every discovered `'use client'` file instead of one path. Reusing
+// this plugin's own discovery (rather than re-walking `components` dirs
+// with ad hoc, possibly-diverging logic) is exactly the CLAUDE.md
+// "reuse or port it, don't reinvent" rule this module's own docstring
+// already invokes.
+export { discoverComponents, type DiscoveredComponent, type ResolvedComponentDirEntry } from './discover.ts'

package/src/manifest.ts

@@ -0,0 +1,89 @@
+/**
+ * `scriptAssets` resolution from Vite's build manifest (`build.manifest =
+ * true`, forced on by this plugin's `config` hook). By `writeBundle` time
+ * the manifest is final — every entry's hashed output filename is known —
+ * which is exactly why template emission happens there and not in
+ * `transform` (see the design's "script URL late-binding" section).
+ */
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import type { Manifest } from 'vite'
+
+/** Read and parse the manifest Vite just wrote to `outDir`. `manifestOption`
+ * mirrors `build.manifest`: `true` → the default `.vite/manifest.json`
+ * path; a string → that custom path, relative to `outDir`. */
+export async function loadManifest(outDir: string, manifestOption: boolean | string): Promise<Manifest> {
+  const relPath = typeof manifestOption === 'string' ? manifestOption : '.vite/manifest.json'
+  const content = await readFile(resolve(outDir, relPath), 'utf8')
+  return JSON.parse(content) as Manifest
+}
+
+/** Join a Vite `base` (may or may not have a trailing slash; may be a full
+ * URL, an absolute path, or `'./'`) with a manifest-relative file path
+ * (never starts with `/`) into the URL an adapter should register. */
+export function joinBaseAndFile(base: string, file: string): string {
+  if (base === '' || base === './') return file
+  return base.endsWith('/') ? `${base}${file}` : `${base}/${file}`
+}
+
+/**
+ * The ordered `scriptAssets` list for one component's entry, per the
+ * design: just the entry's own hashed file — shared chunks (including the
+ * `@barefootjs/client` runtime) arrive as ESM imports the browser follows
+ * on its own, so they need no separate registration. `[]` when the entry
+ * isn't in the manifest (e.g. a `'use client'` file whose compile produced
+ * no client JS at all, or a stale discovery/build mismatch).
+ */
+export function resolveScriptAssets(
+  manifest: Manifest,
+  manifestKey: string,
+  base: string,
+): string[] {
+  const entry = manifest[manifestKey]
+  if (!entry) return []
+  return [joinBaseAndFile(base, entry.file)]
+}
+
+/**
+ * The ordered `preloadAssets` list for one component's entry: every chunk
+ * the entry pulls in **transitively** via static `imports`, excluding the
+ * entry's own file (that one is already covered by `resolveScriptAssets`).
+ *
+ * Walked **breadth-first** from the entry so the chunks most likely to be
+ * shared across components (the runtime chunk, common child islands) sort
+ * first, and deduped by manifest key — both needed to keep the returned
+ * order deterministic across builds; a rebuild that reshuffles this list
+ * for no reason would show up as a spurious template diff. A `seen` set
+ * keyed by manifest key also guards against import cycles.
+ *
+ * Deliberately does NOT follow `dynamicImports`: a dynamic import is by
+ * definition not needed for first paint — the app chose to defer it — and
+ * preloading it would pull that deferred work forward, defeating the
+ * point of having split it out.
+ *
+ * `[]` when the entry isn't in the manifest, same as `resolveScriptAssets`.
+ */
+export function resolvePreloadAssets(
+  manifest: Manifest,
+  manifestKey: string,
+  base: string,
+): string[] {
+  const entry = manifest[manifestKey]
+  if (!entry) return []
+
+  const seen = new Set<string>([manifestKey])
+  const queue = [...(entry.imports ?? [])]
+  const result: string[] = []
+
+  while (queue.length > 0) {
+    const key = queue.shift() as string
+    if (seen.has(key)) continue
+    seen.add(key)
+    const row = manifest[key]
+    if (!row) continue
+    result.push(joinBaseAndFile(base, row.file))
+    queue.push(...(row.imports ?? []))
+  }
+
+  return result
+}