@barefootjs/rust 0.30.6 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/rust",
-  "version": "0.30.6",
+  "version": "0.31.1",
   "description": "minijinja (Rust) adapter for BarefootJS — compiles IR to .j2 templates and ships a Rust rendering runtime (packages/adapter-rust/runtime/); runs under any Rust web framework (axum, etc.)",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,9 +17,9 @@
     "./test-render": {
       "bun": "./src/test-render.ts"
     },
-    "./build": {
-      "types": "./dist/build.d.ts",
-      "import": "./dist/build.js"
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
     }
   },
   "files": [
@@ -30,7 +30,7 @@
   ],
   "scripts": {
     "build": "bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/adapter/index.ts ./src/build.ts --root ./src --outdir ./dist --format esm --external @barefootjs/jsx --external @barefootjs/shared",
+    "build:js": "bun build ./src/index.ts ./src/adapter/index.ts --root ./src --outdir ./dist --format esm --external @barefootjs/jsx --external @barefootjs/shared --external @barefootjs/vite --external vite && bun build ./src/vite.ts --outfile ./dist/vite.js --format esm --target node --external @barefootjs/vite --external vite --external typescript",
     "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
     "test": "bun test",
     "clean": "rm -rf dist",
@@ -54,14 +54,27 @@
     "directory": "packages/adapter-rust"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.30.6"
+    "@barefootjs/shared": "0.31.1"
   },
   "peerDependencies": {
-    "@barefootjs/jsx": ">=0.2.0"
+    "@barefootjs/jsx": ">=0.2.0",
+    "@barefootjs/vite": ">=0.2.0",
+    "vite": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@barefootjs/vite": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.30.6",
-    "typescript": "^5.0.0"
+    "@barefootjs/jsx": "0.31.1",
+    "@barefootjs/vite": "0.31.1",
+    "@barefootjs/client": "0.31.1",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0"
   }
 }

package/runtime/src/runtime.rs

@@ -811,6 +811,14 @@ pub struct ChildRendererSpec {
 pub struct RenderSession {
     pub scripts: Mutex<Vec<String>>,
     pub script_seen: Mutex<HashSet<String>>,
+    /// `<link rel="modulepreload">` hints, kept as their own list/dedup-set
+    /// pair mirroring `scripts`/`script_seen` exactly -- see
+    /// `register_preload`'s docstring. A preload URL and a script URL are
+    /// never the same concern (preloads are the entry's TRANSITIVE deps,
+    /// never the entry itself), so there is no cross-dedup between the two
+    /// sets.
+    pub preloads: Mutex<Vec<String>>,
+    pub preload_seen: Mutex<HashSet<String>>,
     pub child_renderers: Mutex<HashMap<String, ChildRendererSpec>>,
     pub context_stacks: Mutex<HashMap<String, Vec<JsValue>>>,
     rng_counter: Mutex<u64>,
@@ -821,6 +829,8 @@ impl RenderSession {
         Arc::new(RenderSession {
             scripts: Mutex::new(Vec::new()),
             script_seen: Mutex::new(HashSet::new()),
+            preloads: Mutex::new(Vec::new()),
+            preload_seen: Mutex::new(HashSet::new()),
             child_renderers: Mutex::new(HashMap::new()),
             context_stacks: Mutex::new(HashMap::new()),
             rng_counter: Mutex::new(0),
@@ -976,20 +986,54 @@ impl BfInstance {
         self.session.scripts.lock().unwrap().push(path.to_string());
     }
 
+    /// Register a `<link rel="modulepreload">` hint (a component's resolved
+    /// TRANSITIVE-chunk preload URL, per `AdapterGenerateOptions.
+    /// preloadAssets`) into the SAME session every `BfInstance` clone in
+    /// this render tree shares (`Arc<RenderSession>` -- see the struct
+    /// docstring), exactly mirroring `register_script` above. Because every
+    /// clone (root, and every child minted by `render_child`) holds the
+    /// SAME `Arc`, a preload registered three levels deep is visible to the
+    /// root's `scripts()` call with no separate propagation step needed --
+    /// unlike the PHP/Python ports, which mutate per-instance state and
+    /// must explicitly re-seed each child's collector from the parent's.
+    fn register_preload(&self, path: &str) {
+        let mut seen = self.session.preload_seen.lock().unwrap();
+        if seen.contains(path) {
+            return;
+        }
+        seen.insert(path.to_string());
+        self.session.preloads.lock().unwrap().push(path.to_string());
+    }
+
     /// `pub` (beyond the `"scripts"` `call_method` dispatch below) so a
-    /// production host can read back the accumulated `<script>` tags AFTER
-    /// rendering, to splice into its own page layout (mirrors Python
-    /// integrations' `bf.scripts()` call in their layout helper, e.g.
+    /// production host can read back the accumulated `<link>`/`<script>`
+    /// tags AFTER rendering, to splice into its own page layout (mirrors
+    /// Python integrations' `bf.scripts()` call in their layout helper, e.g.
     /// `integrations/flask/app.py`'s `layout(..., scripts=bf.scripts())`).
+    ///
+    /// Preload hints are emitted FIRST, ahead of every `<script
+    /// type="module">` tag -- a hint that arrives after the script it
+    /// describes is useless. Preloads carry no execution-order constraint
+    /// the way scripts do (they are just hints, not code that runs), so
+    /// registration order is emitted as-is.
     pub fn scripts(&self) -> String {
-        self.session
+        let preload_tags = self
+            .session
+            .preloads
+            .lock()
+            .unwrap()
+            .iter()
+            .map(|p| format!("<link rel=\"modulepreload\" crossorigin href=\"{p}\">"))
+            .collect::<Vec<_>>();
+        let script_tags = self
+            .session
             .scripts
             .lock()
             .unwrap()
             .iter()
             .map(|p| format!("<script type=\"module\" src=\"{p}\"></script>"))
-            .collect::<Vec<_>>()
-            .join("\n")
+            .collect::<Vec<_>>();
+        preload_tags.into_iter().chain(script_tags).collect::<Vec<_>>().join("\n")
     }
 
     /// Renderer contract (#1897): invoked from a template as
@@ -1305,6 +1349,10 @@ impl Object for BfInstance {
                 self.register_script(a(0).as_str().unwrap_or(""));
                 Ok(MjValue::from(()))
             }
+            "register_preload" => {
+                self.register_preload(a(0).as_str().unwrap_or(""));
+                Ok(MjValue::from(()))
+            }
             "scripts" => Ok(safe(self.scripts())),
 
             // -- Streaming SSR ----------------------------------------------

package/src/__tests__/minijinja-adapter-unit.test.ts

@@ -555,3 +555,149 @@ export function Wrapper({ children }: { children?: any }) {
     )
   })
 })
+
+describe('MinijinjaAdapter - scriptAssets (Vite late-binding, PR1)', () => {
+  const CLIENT_COMPONENT = `
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+  return <button onClick={() => setCount(count() + 1)}>{count()}</button>
+}
+`
+
+  test('emits one register_script per URL, in order, when scriptAssets is set', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js', '/assets/counter-def456.js'],
+    })
+    const runtimeIdx = template.indexOf("bf.register_script('/assets/runtime-abc123.js')")
+    const compIdx = template.indexOf("bf.register_script('/assets/counter-def456.js')")
+    expect(runtimeIdx).toBeGreaterThanOrEqual(0)
+    expect(compIdx).toBeGreaterThanOrEqual(0)
+    expect(runtimeIdx).toBeLessThan(compIdx)
+    expect(template).toContain('_bf_reg0')
+    expect(template).toContain('_bf_reg1')
+    expect(template).not.toContain('/static/components/barefoot.js')
+    expect(template).not.toContain('Counter.client.js')
+  })
+
+  test('emits a single registration for a single-element scriptAssets array', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      scriptAssets: ['/assets/only-one.js'],
+    })
+    expect(template).toContain("bf.register_script('/assets/only-one.js')")
+    expect(template.match(/register_script/g)?.length).toBe(1)
+  })
+
+  test('an empty scriptAssets array emits no script registrations', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, { scriptAssets: [] })
+    expect(template).not.toContain('register_script')
+  })
+
+  test('skipScriptRegistration still wins when scriptAssets is also set', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      skipScriptRegistration: true,
+      scriptAssets: ['/assets/should-not-appear.js'],
+    })
+    expect(template).not.toContain('register_script')
+  })
+
+  test('absent scriptAssets falls back to adapter-computed script paths', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const computed = new MinijinjaAdapter().generate(ir).template
+    const explicitUndefined = new MinijinjaAdapter().generate(ir, { scriptAssets: undefined }).template
+    expect(computed).toContain("bf.register_script('/static/components/barefoot.js')")
+    expect(computed).toContain("bf.register_script('/static/components/Counter.client.js')")
+    expect(explicitUndefined).toBe(computed)
+  })
+})
+
+describe('MinijinjaAdapter - preloadAssets', () => {
+  const CLIENT_COMPONENT = `
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+  return <button onClick={() => setCount(count() + 1)}>{count()}</button>
+}
+`
+
+  test('non-empty preloadAssets + non-empty scriptAssets: preload registrations emitted, in order, before script registrations', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js', '/assets/counter-def456.js'],
+      preloadAssets: ['/assets/index-pre1.js', '/assets/shared-pre2.js'],
+    })
+    const pre1Idx = template.indexOf("{% set _bf_pre0 = bf.register_preload('/assets/index-pre1.js') %}")
+    const pre2Idx = template.indexOf("{% set _bf_pre1 = bf.register_preload('/assets/shared-pre2.js') %}")
+    const script1Idx = template.indexOf("{% set _bf_reg0 = bf.register_script('/assets/runtime-abc123.js') %}")
+    const script2Idx = template.indexOf("{% set _bf_reg1 = bf.register_script('/assets/counter-def456.js') %}")
+    expect(pre1Idx).toBeGreaterThanOrEqual(0)
+    expect(pre2Idx).toBeGreaterThan(pre1Idx)
+    expect(script1Idx).toBeGreaterThan(pre2Idx)
+    expect(script2Idx).toBeGreaterThan(script1Idx)
+  })
+
+  test('preloadAssets: [] emits no preload registration', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: [],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).toContain("bf.register_script('/assets/runtime-abc123.js')")
+  })
+
+  test('preloadAssets: undefined emits no preload registration', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: undefined,
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).toContain("bf.register_script('/assets/runtime-abc123.js')")
+  })
+
+  test('preloadAssets non-empty but scriptAssets: [] emits no preload registration (preloads are only meaningful alongside a real script)', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      scriptAssets: [],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).not.toContain('register_script')
+  })
+
+  test('skipScriptRegistration: true suppresses both preloads and scripts', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      skipScriptRegistration: true,
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).not.toContain('register_script')
+  })
+
+  // Regression guard: a previous attempt emitted a literal
+  // `<link rel="modulepreload">` tag directly into the component template,
+  // which injected a rendered DOM node before the component's root and
+  // broke hydration across all eight integrations (blade, erb,
+  // go-template, jinja, mojolicious, rust, twig, xslate). Preload hints
+  // must ONLY ever be emitted as no-output register statements (here,
+  // `{% set _bf_preN = bf.register_preload(...) %}`) that the adapter's
+  // runtime later renders itself — never as literal markup baked into the
+  // template.
+  test('never emits a literal <link tag into the template', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new MinijinjaAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('<link')
+  })
+})

package/src/__tests__/vite.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Coverage of `@barefootjs/rust/vite`'s `barefoot()`:
+ *
+ * - one real `vite build()` end to end (mirrors `@barefootjs/go-template/
+ *   vite`, `@barefootjs/hono/vite`, `@barefootjs/blade/vite`'s,
+ *   `@barefootjs/jinja/vite`'s, and `@barefootjs/erb/vite`'s own
+ *   `vite.test.ts` rigor — a plugin that only passes mocked unit tests
+ *   hasn't been shown to work) against a checked-in fixture (not a system
+ *   tmpdir) so `@barefootjs/client` resolves through the monorepo's real
+ *   node_modules symlinks;
+ * - the `assets` → generated `bf-assets.json` behavior, exercised the same
+ *   way (a real build, since it needs the real manifest Vite writes).
+ *
+ * Unlike Go, there is no `afterEmit`-driven type-combination step to test
+ * here (see `vite.ts`'s module docstring) — `MinijinjaAdapter.generate()`
+ * never produces a `types` section at all, so `barefoot()` always returns a
+ * single-element array unless `assets` is set.
+ */
+import { describe, test, expect } 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 { barefoot, barefoot as defaultBarefoot } from '../vite.ts'
+
+const FIXTURE_ROOT = resolve(import.meta.dirname, '../../e2e-fixture')
+
+describe('@barefootjs/rust/vite: real vite build', () => {
+  test('exports the same function as both named `barefoot` and default', () => {
+    expect(defaultBarefoot).toBe(barefoot)
+  })
+
+  test('returns a single-element plugin array when `assets` is omitted', () => {
+    const plugins = barefoot({ components: ['src/components'], templates: 'views' })
+    expect(plugins).toHaveLength(1)
+  })
+
+  test('writes a self-contained .j2 template with scriptAssets baked in, same as core alone would do', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-rust-vite-dist-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-rust-vite-views-'))
+
+    try {
+      await build({
+        configFile: false,
+        root: FIXTURE_ROOT,
+        base: '/static/build/',
+        logLevel: 'warn',
+        build: { outDir, emptyOutDir: true },
+        plugins: barefoot({
+          components: ['src/components'],
+          templates: templatesDir,
+        }),
+      })
+
+      const template = await readFile(join(templatesDir, 'Counter.j2'), 'utf8')
+      expect(template).toContain("bf.register_script(")
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+    }
+  }, 60_000)
+
+  test('`assets` resolves a non-component entry\'s manifest-hashed URL into a generated JSON asset map', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-rust-vite-dist-assets-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-rust-vite-views-assets-'))
+    const assetsPath = join(FIXTURE_ROOT, 'dist/bf-assets.json')
+
+    try {
+      await build({
+        configFile: false,
+        root: FIXTURE_ROOT,
+        base: '/static/build/',
+        logLevel: 'warn',
+        build: {
+          outDir,
+          emptyOutDir: true,
+          // Registering the non-component entry is the CALLER's job (stock
+          // Vite config) — `assets` below only resolves the URL Vite
+          // already bundled it to, it doesn't request the bundling.
+          rollupOptions: { input: { bootstrap: resolve(FIXTURE_ROOT, 'client/bootstrap.ts') } },
+        },
+        plugins: barefoot({
+          components: ['src/components'],
+          templates: templatesDir,
+          assets: { Bootstrap: 'client/bootstrap.ts' },
+        }),
+      })
+
+      const manifest = JSON.parse(await readFile(join(outDir, '.vite/manifest.json'), 'utf8'))
+      const expectedUrl = `/static/build/${manifest['client/bootstrap.ts'].file}`
+
+      const content = JSON.parse(await readFile(assetsPath, 'utf8'))
+      expect(content).toEqual({ Bootstrap: expectedUrl })
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+      await rm(join(FIXTURE_ROOT, 'dist'), { recursive: true, force: true })
+    }
+  }, 60_000)
+
+  test('`assets` throws an actionable error when the entry was never registered as a Rollup input', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-rust-vite-dist-assets-missing-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-rust-vite-views-assets-missing-'))
+
+    try {
+      await expect(
+        build({
+          configFile: false,
+          root: FIXTURE_ROOT,
+          base: '/static/build/',
+          logLevel: 'silent',
+          build: { outDir, emptyOutDir: true },
+          plugins: barefoot({
+            components: ['src/components'],
+            templates: templatesDir,
+            assets: { Bootstrap: 'client/bootstrap.ts' },
+          }),
+        }),
+      ).rejects.toThrow(/was not found in the build manifest/)
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+      await rm(join(FIXTURE_ROOT, 'dist'), { recursive: true, force: true })
+    }
+  }, 60_000)
+})

package/src/adapter/expr/emitters.ts

@@ -117,15 +117,33 @@ export function truthyTest(node: ParsedExpr, rendered: string): string {
  * callback's receiver.
  */
 export class JinjaFilterEmitter implements ParsedExprEmitter {
+  // Plain field declarations + assignment, NOT TS constructor-parameter-
+  // property shorthand: Vite's `bundleConfigFile` externalizes any bare
+  // (non-relative) import when loading `vite.config.ts` (see
+  // `@barefootjs/rust/vite`'s docstring), so this file can be loaded
+  // directly by Node's OWN native TypeScript type-stripping (enabled by
+  // default since Node 22.18/23.6) rather than esbuild — and Node's
+  // strip-only mode does not support parameter properties (`SyntaxError
+  // [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]`), only plain type annotations.
+  private readonly param: string
+  private readonly localVarMap: Map<string, string>
+  private readonly isStringName: (n: string) => boolean
+  // Records a BF101 for predicate shapes this emitter can only degrade
+  // (#2038). Optional so emitter construction stays possible without an
+  // adapter; a missing hook keeps the old silent-degrade emit.
+  private readonly onUnsupported?: (message: string, reason?: string) => void
+
   constructor(
-    private readonly param: string,
-    private readonly localVarMap: Map<string, string>,
-    private readonly isStringName: (n: string) => boolean = () => false,
-    // Records a BF101 for predicate shapes this emitter can only degrade
-    // (#2038). Optional so emitter construction stays possible without an
-    // adapter; a missing hook keeps the old silent-degrade emit.
-    private readonly onUnsupported?: (message: string, reason?: string) => void,
-  ) {}
+    param: string,
+    localVarMap: Map<string, string>,
+    isStringName: (n: string) => boolean = () => false,
+    onUnsupported?: (message: string, reason?: string) => void,
+  ) {
+    this.param = param
+    this.localVarMap = localVarMap
+    this.isStringName = isStringName
+    this.onUnsupported = onUnsupported
+  }
 
   identifier(name: string): string {
     if (name === this.param) return minijinjaIdent(this.param)
@@ -288,7 +306,13 @@ export class JinjaFilterEmitter implements ParsedExprEmitter {
  *   - no lambda fallback exists (see the file header, divergence 2).
  */
 export class JinjaTopLevelEmitter implements ParsedExprEmitter {
-  constructor(private readonly ctx: JinjaEmitContext) {}
+  // Plain field + assignment, not a parameter property — see
+  // `JinjaFilterEmitter`'s constructor comment above for why.
+  private readonly ctx: JinjaEmitContext
+
+  constructor(ctx: JinjaEmitContext) {
+    this.ctx = ctx
+  }
 
   identifier(name: string): string {
     // `undefined` / `null` nested inside a larger expression tree — Jinja

package/src/adapter/minijinja-adapter.ts

@@ -241,9 +241,6 @@ export class MinijinjaAdapter extends BaseAdapter implements IRNodeEmitter<Jinja
   name = 'minijinja'
   extension = '.j2'
   templatesPerComponent = true
-  // Template-string target with no component layer: `bf build` emits a static
-  // import-map HTML snippet to include into the page <head>.
-  importMapInjection = 'html-snippet' as const
 
   /**
    * Identifier-path callees the Jinja runtime can render in template scope.
@@ -408,7 +405,7 @@ export class MinijinjaAdapter extends BaseAdapter implements IRNodeEmitter<Jinja
     // Generate script registration
     const scriptReg = options?.skipScriptRegistration
       ? ''
-      : this.generateScriptRegistrations(ir, options?.scriptBaseName)
+      : this.generateScriptRegistrations(ir, options?.scriptBaseName, options?.scriptAssets, options?.preloadAssets)
 
     // SSR context consumers (`const x = useContext(Ctx)`): seed each local
     // from the active provider value (or the `createContext` default). The
@@ -450,7 +447,35 @@ export class MinijinjaAdapter extends BaseAdapter implements IRNodeEmitter<Jinja
   // Script Registration
   // ===========================================================================
 
-  private generateScriptRegistrations(ir: ComponentIR, scriptBaseName?: string): string {
+  private generateScriptRegistrations(ir: ComponentIR, scriptBaseName?: string, scriptAssets?: string[], preloadAssets?: string[]): string {
+    // `scriptAssets`, when present (including `[]`), fully supersedes the
+    // adapter-computed `barefootJsPath` / `clientJsBasePath` pair — see
+    // `AdapterGenerateOptions.scriptAssets`. The caller (e.g. the Vite
+    // plugin) has already decided the exact ordered URL list, including
+    // whether any script is needed at all.
+    if (scriptAssets) {
+      if (scriptAssets.length === 0) return ''
+      const lines: string[] = []
+      // `preloadAssets` is only meaningful alongside a non-empty
+      // `scriptAssets` (see `AdapterGenerateOptions.preloadAssets`) — this
+      // branch is only reached when that already holds. Emitted BEFORE the
+      // script registrations: every preload hint must precede the script
+      // tags it describes, or the hint is useless (see `register_preload`'s
+      // docstring in the Rust runtime — `bf.register_preload`/`bf.scripts()`
+      // preserve that ordering downstream, so codegen order is what fixes
+      // it here).
+      if (preloadAssets && preloadAssets.length > 0) {
+        preloadAssets.forEach((url, i) => {
+          lines.push(`{% set _bf_pre${i} = bf.register_preload('${url}') %}`)
+        })
+      }
+      scriptAssets.forEach((url, i) => {
+        lines.push(`{% set _bf_reg${i} = bf.register_script('${url}') %}`)
+      })
+      lines.push('')
+      return lines.join('\n')
+    }
+
     const hasInteractivity = hasClientInteractivity(ir)
     if (!hasInteractivity) return ''