@barefootjs/hono 0.30.5 → 0.31.0

package/src/adapter/hono-adapter.ts

@@ -69,11 +69,10 @@ export interface HonoAdapterOptions {
   clientJsFilename?: string
 
   /**
-   * Display name surfaced through `JsxAdapter.name` — read by `bf build`
-   * for its `Adapter: …` banner. Defaults to `'hono'`. CSR-mode callers
-   * (`@barefootjs/client/build`) pass `'csr'` so the banner reflects the
-   * mode the user picked at scaffold time instead of leaking the
-   * fact that CSR currently reuses HonoAdapter under the hood.
+   * Display name surfaced through `JsxAdapter.name`. Defaults to `'hono'`.
+   * (CSR mode no longer reuses `HonoAdapter` under the hood — see
+   * `@barefootjs/client/csr-adapter`'s own in-package `CSRAdapter` — so
+   * this option has no CSR-specific caller today.)
    */
   name?: string
 }
@@ -125,9 +124,6 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
   name = 'hono'
   extension = '.tsx'
   clientShimSource = '@barefootjs/hono/client-shim'
-  // Importmap is injected at render time by the `BfImportMap` component
-  // (reads `barefoot-externals.json`), so `bf build` emits no static snippet.
-  importMapInjection = 'component' as const
 
   // The Hono SSR runtime is JavaScript (Node / Bun / CF Workers), so any
   // synchronous JS call the user writes can be rendered as-is at template
@@ -165,6 +161,28 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
   private rewriteRelativeImport?: (importPath: string) => string
   /** Stack of loop keys for generating data-key / data-key-1 attributes on loop items */
   private loopKeyStack: Array<{ key: string | null; param: string }> = []
+  /**
+   * Per-call `AdapterGenerateOptions.scriptAssets`, stashed for the
+   * duration of one `generate()` call (same lifecycle as
+   * `rewriteRelativeImport`) so `generateImports`/`generateComponent`/
+   * `renderIfStatement` can all see it without threading it through every
+   * method signature. `undefined` means "the caller didn't resolve
+   * scriptAssets", so no script-registration codegen is emitted; `[]`
+   * means "resolved, and empty" (a server-only file, or a client file
+   * whose bundle isn't in the manifest yet); a non-empty array means
+   * "bake exactly these URLs in". See `AdapterGenerateOptions.
+   * scriptAssets`'s docstring for the full precedence contract this
+   * mirrors from `GoTemplateAdapter`.
+   */
+  private scriptAssets?: string[]
+  /**
+   * Per-call `AdapterGenerateOptions.preloadAssets`, same stash-for-the-
+   * duration-of-one-`generate()`-call lifecycle as `scriptAssets`. Only
+   * consulted when `hasScriptAssets()` is also true — see
+   * `AdapterGenerateOptions.preloadAssets`'s docstring: preloads are only
+   * meaningful alongside a non-empty `scriptAssets`.
+   */
+  private preloadAssets?: string[]
 
   constructor(options: HonoAdapterOptions = {}) {
     super()
@@ -180,6 +198,19 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
     this.componentName = ir.metadata.componentName
     this.isClientComponent = ir.metadata.isClientComponent
     this.rewriteRelativeImport = options?.rewriteRelativeImport
+    // `skipScriptRegistration` wins over `scriptAssets`/`preloadAssets`
+    // unconditionally — see both fields' docstrings on
+    // `AdapterGenerateOptions`. Stashing `undefined` for both here (rather
+    // than gating each call site individually) makes every downstream
+    // `hasScriptAssets()`/`hasPreloadAssets()` check "just work" without
+    // its own skip check.
+    if (options?.skipScriptRegistration) {
+      this.scriptAssets = undefined
+      this.preloadAssets = undefined
+    } else {
+      this.scriptAssets = options?.scriptAssets
+      this.preloadAssets = options?.preloadAssets
+    }
 
     // Generate component body FIRST so we can scan it for used imports
     const component = this.generateComponent(ir)
@@ -216,9 +247,34 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
       extension: this.extension,
     }
     this.rewriteRelativeImport = undefined
+    this.scriptAssets = undefined
+    this.preloadAssets = undefined
     return result
   }
 
+  /**
+   * True when `options.scriptAssets` was resolved AND non-empty for this
+   * `generate()` call — the single guard `generateImports`/
+   * `generateComponent`/`renderIfStatement` all consult before emitting
+   * script-registration codegen. See `scriptAssets`'s field docstring for
+   * why `undefined` and `[]` are both "no" here.
+   */
+  private hasScriptAssets(): boolean {
+    return !!this.scriptAssets && this.scriptAssets.length > 0
+  }
+
+  /**
+   * True when `options.preloadAssets` was resolved AND non-empty for this
+   * `generate()` call, AND `hasScriptAssets()` also holds — see
+   * `AdapterGenerateOptions.preloadAssets`'s docstring: preloads are only
+   * meaningful alongside a non-empty `scriptAssets`. Consulted by
+   * `generateImports`/`generateComponent`/`renderIfStatement` alongside
+   * `hasScriptAssets()` before emitting preload-registration codegen.
+   */
+  private hasPreloadAssets(): boolean {
+    return this.hasScriptAssets() && !!this.preloadAssets && this.preloadAssets.length > 0
+  }
+
   private generateModuleLevelContextBindings(ir: ComponentIR): string {
     const lines: string[] = []
     for (const c of ir.metadata.localConstants) {
@@ -251,6 +307,18 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
       lines.push(`import { ${utilImports.join(', ')} } from '@barefootjs/hono/utils'`)
     }
 
+    // Only imported when this call's `scriptAssets` (see the field
+    // docstring, and `generateComponent`) actually resolved to a non-empty
+    // URL list, so a server-only file emits no dead import.
+    // `registerComponentPreloads` is imported alongside them only when
+    // `preloadAssets` also resolved non-empty (`hasPreloadAssets()`).
+    if (this.hasScriptAssets()) {
+      const names = this.hasPreloadAssets()
+        ? ['registerComponentScripts', 'registerComponentPreloads', 'wrapWithInlineScripts']
+        : ['registerComponentScripts', 'wrapWithInlineScripts']
+      lines.push(`import { ${names.join(', ')} } from '@barefootjs/hono/scripts'`)
+    }
+
     // Import Suspense / ErrorBoundary when async boundaries are used. Both
     // are imported under `__Bf`-prefixed aliases (and emitted as such by
     // `renderAsync`) so the generated tags can never collide with a user
@@ -580,6 +648,25 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
     const exportPrefix = ir.metadata.isExported === false ? '' : 'export '
     lines.push(`${exportPrefix}function ${name}(${fullPropsDestructure}${typeAnnotation}${noArgDefault}) {`)
 
+    // Vite-pipeline script registration (see `scriptAssets`'s field
+    // docstring): register this call's resolved URLs against the request
+    // context right away, independent of props — `__bfInlineScripts` is
+    // then threaded through every `return (...)` this function can reach
+    // (the plain tail return below, and both branches of an if-statement
+    // root via `renderIfStatement`) so a component rendered after
+    // `<BfScripts />` (e.g. inside Suspense) ships its scripts inline
+    // instead of silently dropping them from the already-flushed collector.
+    // `__bfInlinePreloads` (registered FIRST, so preloads flush ahead of
+    // scripts wherever `<BfScripts />` renders them) follows the exact
+    // same pattern for `preloadAssets` — see `AdapterGenerateOptions.
+    // preloadAssets` and `hasPreloadAssets()`.
+    if (this.hasPreloadAssets()) {
+      lines.push(`  const __bfInlinePreloads = registerComponentPreloads(${JSON.stringify(this.preloadAssets)})`)
+    }
+    if (this.hasScriptAssets()) {
+      lines.push(`  const __bfInlineScripts = registerComponentScripts(${JSON.stringify(this.scriptAssets)})`)
+    }
+
     // Add props extraction for SolidJS-style pattern
     if (propsExtraction) {
       lines.push(propsExtraction)
@@ -627,9 +714,19 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
       return lines.join('\n')
     }
 
-    lines.push(`  return (`)
-    lines.push(`    ${jsxBody}`)
-    lines.push(`  )`)
+    if (this.hasScriptAssets()) {
+      lines.push(`  return wrapWithInlineScripts((`)
+      lines.push(`    ${jsxBody}`)
+      lines.push(
+        this.hasPreloadAssets()
+          ? `  ), __bfInlineScripts, __bfInlinePreloads)`
+          : `  ), __bfInlineScripts)`,
+      )
+    } else {
+      lines.push(`  return (`)
+      lines.push(`    ${jsxBody}`)
+      lines.push(`  )`)
+    }
     lines.push(`}`)
 
     return lines.join('\n')
@@ -1032,11 +1129,27 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
     // Render the consequent (then branch) JSX
     const consequent = this.renderNode(ifStmt.consequent, ctx)
 
+    // Every early-return branch below wraps with `wrapWithInlineScripts`
+    // when this call's `scriptAssets` resolved non-empty — same
+    // `__bfInlineScripts` binding `generateComponent` declares at the top
+    // of the function, reused across every branch this if-chain can take.
+    // `__bfInlinePreloads` (same declare-once-reuse-every-branch pattern)
+    // is threaded in as a third argument when `preloadAssets` also
+    // resolved non-empty.
+    const wrap = this.hasScriptAssets()
+    const wrapPreload = this.hasPreloadAssets()
+    const openReturn = wrap ? '    return wrapWithInlineScripts((' : '    return ('
+    const closeReturn = wrap
+      ? wrapPreload
+        ? '    ), __bfInlineScripts, __bfInlinePreloads)'
+        : '    ), __bfInlineScripts)'
+      : '    )'
+
     // Build the if statement
     lines.unshift(`  if (${ifStmt.condition}) {`)
-    lines.push(`    return (`)
+    lines.push(openReturn)
     lines.push(`      ${consequent}`)
-    lines.push(`    )`)
+    lines.push(closeReturn)
     lines.push(`  }`)
 
     // Handle the alternate (else branch)
@@ -1049,9 +1162,15 @@ export class HonoAdapter extends JsxAdapter implements IRNodeEmitter<HonoRenderC
       } else {
         // Final else branch with regular JSX
         const alternate = this.renderNode(ifStmt.alternate, ctx)
-        lines.push(`  return (`)
+        lines.push(wrap ? '  return wrapWithInlineScripts((' : '  return (')
         lines.push(`    ${alternate}`)
-        lines.push(`  )`)
+        lines.push(
+          wrap
+            ? wrapPreload
+              ? '  ), __bfInlineScripts, __bfInlinePreloads)'
+              : '  ), __bfInlineScripts)'
+            : '  )',
+        )
       }
     } else {
       // No alternate - return null

package/src/app.ts

@@ -9,10 +9,9 @@
  *
  * Two pieces:
  *
- *   - **JSX components** (`<BfImportMap />`, `<BfScripts />`,
- *     `<BfDevReload />`) — return raw HTML the caller composes inside
- *     the Layout passed to Hono's `jsxRenderer`. All URL/data inputs
- *     are required props.
+ *   - **JSX components** (`<BfScripts />`, `<BfDevReload />`) — return
+ *     raw HTML the caller composes inside the Layout passed to Hono's
+ *     `jsxRenderer`. All URL/data inputs are required props.
  *
  *   - **Middleware** (`barefootDevReload`) — registers the SSE endpoint
  *     paired with `<BfDevReload />`. Both `endpoint` and `enabled` are
@@ -30,9 +29,6 @@ import type { MiddlewareHandler } from 'hono'
 import { html, raw } from 'hono/html'
 import type { HtmlEscapedString } from 'hono/utils/html'
 import { useRequestContext } from 'hono/jsx-renderer'
-// Zero-dependency subpath — keeps the compiler (and its `typescript` dep) out
-// of this runtime/Workers-bundled module while sharing one importmap renderer.
-import { renderImportMapHtml, type ImportMapManifest } from '@barefootjs/jsx/import-map'
 import { createDevReloader } from './dev-worker.ts'
 // Side-effect import: auto-wires request-scoped `searchParams()` for SSR so any
 // Hono app rendering the BarefootJS scripts gets it without an opt-in step.
@@ -43,10 +39,10 @@ const DEV_RELOAD_ENDPOINT_KEY = 'bfDevReloadEndpoint'
 // ── helpers ────────────────────────────────────────────────────────────────
 
 /**
- * Build manifest shape produced by `bf build`. Each compiled
- * component is keyed by its manifest name; `__barefoot__` is the
- * runtime entry. `clientJs` is a path under `dist/`, e.g.
- * `"components/Counter.client.js"`.
+ * Build manifest shape read by `manifestToScriptUrls` (and `BfScripts`
+ * below) to emit per-component `<script>` tags. Each compiled component
+ * is keyed by its manifest name; `__barefoot__` is the runtime entry.
+ * `clientJs` is a path under `dist/`, e.g. `"components/Counter.client.js"`.
  *
  * `stubDeps` lists the manifest keys of every `'use client'` sibling
  * this bundle reaches via a stub rewrite (i.e. via an imperative
@@ -59,8 +55,7 @@ const DEV_RELOAD_ENDPOINT_KEY = 'bfDevReloadEndpoint'
  * `ui/button/index.tsx`), not the runtime registry name passed to
  * `createComponent(...)` (e.g. `"Button"`). For top-level
  * single-component files the two coincide; for nested layouts they
- * differ. `build.ts` does the path → manifest-key conversion before
- * writing this field.
+ * differ.
  */
 export interface BarefootBuildManifest {
   __barefoot__?: { clientJs?: string }
@@ -94,62 +89,6 @@ export function relPathFromComponentsBase(p: string): string {
 
 // ── JSX components ─────────────────────────────────────────────────────────
 
-export interface BfImportMapProps {
-  /** Base URL where the runtime + component bundles are served. */
-  base: string
-  /**
-   * Contents of `barefoot-externals.json` (import it and pass it
-   * through). Its `importmap.imports` are merged on top of the
-   * built-in `@barefootjs/client*` mappings so islands importing
-   * configured externals (e.g. `zod`, `@barefootjs/form`) resolve in
-   * the browser. When omitted, only the `@barefootjs/client*`
-   * mappings are emitted — the pre-#1639 behavior.
-   *
-   * Typed with the shared {@link ImportMapManifest} from `@barefootjs/jsx`,
-   * so the component and the `bf build` snippet path describe the manifest
-   * with one type.
-   */
-  externals?: ImportMapManifest
-  /**
-   * Whether to also emit `<link rel="modulepreload">` for the
-   * manifest's `preloads`. Defaults to `true`; set `false` to emit
-   * the importmap only.
-   */
-  preload?: boolean
-}
-
-/**
- * Emits the `<script type="importmap">` that maps the bare
- * `@barefootjs/client` / `@barefootjs/client/runtime` specifiers to
- * the runtime bundle, plus any externals from `barefoot-externals.json`
- * passed via the `externals` prop. Also emits `<link rel="modulepreload">`
- * for the manifest's `preloads` unless `preload` is `false`. Place in
- * `<head>`.
- *
- * The merge of the `@barefootjs/client*` defaults (synthesized from `base`
- * for prop-less / hand-written manifests) is Hono-specific; the actual HTML
- * rendering — importmap JSON escaping, `<link rel="modulepreload">`
- * emission with `crossorigin` (#1648) — is delegated to the shared
- * `renderImportMapHtml` so this path can never drift from the static
- * `barefoot-importmap.html` snippet `bf build` emits for template-string
- * adapters (#1644). Imported from the `@barefootjs/jsx/import-map` subpath,
- * a zero-dependency module, to keep this runtime file free of the compiler.
- */
-export function BfImportMap(props: BfImportMapProps): HtmlEscapedString | Promise<HtmlEscapedString> {
-  const base = props.base.replace(/\/$/, '')
-  // Built-in defaults first, then manifest imports so a configured
-  // `@barefootjs/client` mapping (emitted by `bf build` against the
-  // build's `externalsBasePath`) wins over the prop-derived one.
-  const imports: Record<string, string> = {
-    '@barefootjs/client': `${base}/barefoot.js`,
-    '@barefootjs/client/runtime': `${base}/barefoot.js`,
-    ...(props.externals?.importmap?.imports ?? {}),
-  }
-  const preloads = props.preload === false ? [] : props.externals?.preloads ?? []
-
-  return html`${raw(renderImportMapHtml({ importmap: { imports }, preloads }))}`
-}
-
 export interface BfScriptsProps {
   /** Base URL where the runtime + component bundles are served. */
   base: string
@@ -168,9 +107,9 @@ let __bfEmptyManifestWarned = false
  * manifest, runtime first. Place at the end of `<body>`.
  *
  * Logs a one-time warning when the manifest is empty — a strong
- * signal the user is running the server before `bf build` has
- * produced anything, which would otherwise present as a silent
- * "page renders but nothing is interactive."
+ * signal the user is running the server before a build has produced
+ * anything, which would otherwise present as a silent "page renders
+ * but nothing is interactive."
  */
 export function BfScripts(props: BfScriptsProps): HtmlEscapedString | Promise<HtmlEscapedString> {
   const urls = manifestToScriptUrls(props.manifest, props.base)
@@ -178,7 +117,7 @@ export function BfScripts(props: BfScriptsProps): HtmlEscapedString | Promise<Ht
     __bfEmptyManifestWarned = true
     console.warn(
       '[barefootjs] BfScripts: manifest is empty — no <script> tags emitted. ' +
-        'Run `bf build` to compile components and rebuild the manifest.',
+        'Run `vite build` to compile components and rebuild the manifest.',
     )
   }
   const tags = urls

package/src/index.ts

@@ -11,7 +11,7 @@ export { conformancePins } from './conformance-pins.ts'
 
 // BfScripts is exported from a separate entry point to avoid JSX runtime issues in tests
 // Usage: import { BfScripts } from '@barefootjs/hono/scripts'
-export type { CollectedScript } from './scripts.tsx'
+export type { CollectedScript, CollectedPreload } from './scripts.tsx'
 
 // Portal components for SSR
 // Usage: import { BfPortals, Portal } from '@barefootjs/hono/portals'

package/src/preload.tsx

@@ -40,6 +40,12 @@ export interface ManifestEntry {
   markedTemplate: string
   clientJs?: string
   props?: Array<{ name: string; type: string; optional: boolean }>
+  /**
+   * Dependency component names for recursive preloading.
+   * Note: no current producer (neither legacy site build nor @barefootjs/vite)
+   * emits this field, so dependency recursion only activates for
+   * hand-authored manifests. Kept for API compatibility.
+   */
   dependencies?: string[]
 }
 
@@ -84,7 +90,11 @@ export interface BfPreloadProps {
  * Resolves the full dependency chain for given components.
  * Uses a visited set to prevent infinite loops from circular dependencies.
  *
- * @param components - Component names to resolve
+ * Manifest keys are whatever the manifest producer used — the legacy site
+ * build uses path-qualified keys like `ui/button`, so component name entries
+ * must match those exactly. A key mismatch is silently skipped (no error).
+ *
+ * @param components - Component names/keys to resolve (must match manifest keys exactly)
  * @param manifest - Component manifest with dependency information
  * @param visited - Set of already visited component names (for cycle detection)
  * @returns Array of clientJs paths for all dependencies
@@ -126,7 +136,10 @@ function resolveDependencyChain(
  * by all BarefootJS components.
  *
  * When manifest and components props are provided, automatically
- * preloads the full dependency chain for those components.
+ * preloads the full dependency chain for those components. The `components`
+ * array entries must match manifest keys exactly — for the legacy site
+ * build, use path-qualified keys like `ui/button`, not component names.
+ * A mismatched key is silently skipped.
  */
 export function BfPreload({
   staticPath = '/static',

package/src/render.ts

@@ -15,7 +15,7 @@
  *                        `<Suspense>` boundaries flush out-of-order.
  *
  * Both accept a `hono/jsx` node (typically a full page including the
- * layout shell, `<BfImportMap>`, and `<BfScripts>`).
+ * layout shell and `<BfScripts>`).
  */
 
 import { renderToReadableStream } from 'hono/jsx/streaming'

package/src/scripts.tsx

@@ -46,6 +46,10 @@ export type CollectedScript = {
   src: string
 }
 
+export type CollectedPreload = {
+  href: string
+}
+
 export interface BfScriptsProps {
   /**
    * Build manifest from `dist/components/manifest.json`. When supplied
@@ -103,6 +107,7 @@ export function BfScripts(props: BfScriptsProps = {}) {
     c.set('bfScriptsRendered', true)
 
     const scripts: CollectedScript[] = c.get('bfCollectedScripts') || []
+    const preloads: CollectedPreload[] = c.get('bfCollectedPreloads') || []
     const outputSet: Set<string> = c.get('bfOutputScripts') || new Set()
     const { manifest, base, entryRoots } = props
     // `entryRoots` extends both the walk-root set AND the `excluded` set.
@@ -146,8 +151,16 @@ export function BfScripts(props: BfScriptsProps = {}) {
       ...componentScripts.reverse(),
     ]
 
+    // Preloads carry no execution-order constraint the way scripts do (they
+    // are just hints, not code that runs) — insertion order is emitted as-
+    // is, ahead of every `<script type="module">` tag, so the browser sees
+    // the hint before it would otherwise discover the same chunk as an
+    // import of one of those scripts.
     return (
       <Fragment>
+        {preloads.map(({ href }) => (
+          <link rel="modulepreload" crossorigin="" href={href} />
+        ))}
         {finalScripts.map(({ src }) => (
           <script type="module" src={src} />
         ))}
@@ -159,6 +172,129 @@ export function BfScripts(props: BfScriptsProps = {}) {
   }
 }
 
+/**
+ * Register `urls` (a component's resolved script URLs for THIS render) into
+ * the same request-context collector `BfScripts` reads, and return the
+ * subset that must be rendered INLINE right here instead — see
+ * `BfScripts`'s docstring on `bfScriptsRendered` (a component rendering
+ * after `<BfScripts />` has already run, e.g. inside a Suspense boundary,
+ * can't rely on the end-of-body collector; its scripts have to ship inline
+ * at the point of render for streaming to deliver them at all).
+ *
+ * `HonoAdapter.generate()` calls this directly from CODEGEN — one call per
+ * rendered component, with `urls` baked in as
+ * `AdapterGenerateOptions.scriptAssets` (the Vite plugin's already-resolved,
+ * manifest-hashed or dev-origin URL list). Two properties follow from that:
+ *
+ * - No separate `barefoot.js` runtime registration: `scriptAssets` under
+ *   Vite is just the component's own bundled entry (see
+ *   `@barefootjs/vite`'s `resolveScriptAssets` docstring) — the
+ *   `@barefootjs/client` runtime arrives as a shared ESM chunk that entry
+ *   imports, which the browser follows on its own with no extra
+ *   `<script src>` needed. Go's `.Scripts.Register` calls (generated by
+ *   `GoTemplateAdapter`) make exactly the same simplification for the same
+ *   reason.
+ * - Dedup keys on the URL itself (there is no separate `componentId` to key
+ *   by): rendering the SAME component N times (e.g. inside a `.map()`) or
+ *   two different components that happen to share a chunk both correctly
+ *   collapse to one `<script>` tag.
+ *
+ * Swallows a missing request context (no `jsxRenderer` in the render path),
+ * returning `[]` — SSR still renders, just without hydration scripts.
+ */
+export function registerComponentScripts(urls: string[]): string[] {
+  try {
+    const c = useRequestContext()
+    const scripts: CollectedScript[] = c.get('bfCollectedScripts') || []
+    const outputScripts: Set<string> = c.get('bfOutputScripts') || new Set()
+    const rendered = c.get('bfScriptsRendered')
+    const inline: string[] = []
+    for (const src of urls) {
+      if (outputScripts.has(src)) continue
+      outputScripts.add(src)
+      if (rendered) inline.push(src)
+      else scripts.push({ src })
+    }
+    c.set('bfCollectedScripts', scripts)
+    c.set('bfOutputScripts', outputScripts)
+    return inline
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Register `urls` (a component's resolved TRANSITIVE-chunk preload URLs for
+ * THIS render, per `AdapterGenerateOptions.preloadAssets`) into the same
+ * request-context collector `BfScripts` reads, and return the subset that
+ * must be rendered INLINE right here instead — same
+ * already-rendered-`<BfScripts />` escape hatch as `registerComponentScripts`
+ * (see that function's docstring), and the same reasons apply: a component
+ * whose SSR happens inside a Suspense boundary that renders after
+ * `<BfScripts />` has already flushed can't rely on the end-of-body
+ * collector.
+ *
+ * Kept as a SEPARATE collector (`bfCollectedPreloads` / `bfOutputPreloads`)
+ * from `registerComponentScripts`'s `bfCollectedScripts` /
+ * `bfOutputScripts` — a preload URL and a script URL are never the same
+ * concern (preloads are the entry's TRANSITIVE deps, never the entry
+ * itself — see `AdapterGenerateOptions.preloadAssets`), so there is no
+ * cross-dedup to do between the two sets; keeping them separate avoids
+ * conflating "this was preloaded" with "this was registered as a script".
+ *
+ * Dedup keys on the URL itself, same as `registerComponentScripts`:
+ * rendering the SAME component N times (e.g. inside a `.map()`), or two
+ * different components that happen to share a transitive chunk, both
+ * correctly collapse to one `<link rel="modulepreload">` tag.
+ *
+ * Swallows a missing request context, returning `[]` — SSR still renders,
+ * just without preload hints.
+ */
+export function registerComponentPreloads(urls: string[]): string[] {
+  try {
+    const c = useRequestContext()
+    const preloads: CollectedPreload[] = c.get('bfCollectedPreloads') || []
+    const outputPreloads: Set<string> = c.get('bfOutputPreloads') || new Set()
+    const rendered = c.get('bfScriptsRendered')
+    const inline: string[] = []
+    for (const href of urls) {
+      if (outputPreloads.has(href)) continue
+      outputPreloads.add(href)
+      if (rendered) inline.push(href)
+      else preloads.push({ href })
+    }
+    c.set('bfCollectedPreloads', preloads)
+    c.set('bfOutputPreloads', outputPreloads)
+    return inline
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Wrap `jsx` with a leading `<link rel="modulepreload">` per entry in
+ * `inlinePreloads` and a trailing `<script type="module">` per entry in
+ * `inlineScripts` (the return values of `registerComponentPreloads` and
+ * `registerComponentScripts` respectively) — a single shared function
+ * every generated component imports, rather than per-file duplicated
+ * inline-asset logic. Returns `jsx` unchanged when both are empty (the
+ * common case: collected, not inline).
+ *
+ * `inlinePreloads` defaults to `[]` so existing generated call sites that
+ * only ever pass `inlineScripts` (a component with `scriptAssets` but no
+ * `preloadAssets`) keep compiling and behaving exactly as before.
+ */
+export function wrapWithInlineScripts(jsx: unknown, inlineScripts: string[], inlinePreloads: string[] = []) {
+  if (inlineScripts.length === 0 && inlinePreloads.length === 0) return jsx
+  return (
+    <Fragment>
+      {inlinePreloads.map(href => <link rel="modulepreload" crossorigin="" href={href} />)}
+      {jsx as never}
+      {inlineScripts.map(src => <script type="module" src={src} />)}
+    </Fragment>
+  )
+}
+
 /**
  * Walk stub-rewrite edges from each manifest entry in `roots`,
  * returning the script URLs for every transitively reachable