@barefootjs/jinja 0.30.6 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/jinja",
-  "version": "0.30.6",
+  "version": "0.31.0",
   "description": "Jinja2 adapter for BarefootJS — compiles IR to .jinja templates and ships the Python BarefootJS rendering runtime; runs under any Python web framework (Flask, 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",
@@ -53,14 +53,27 @@
     "directory": "packages/adapter-jinja"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.30.6"
+    "@barefootjs/shared": "0.31.0"
   },
   "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.0",
+    "@barefootjs/vite": "0.31.0",
+    "@barefootjs/client": "0.31.0",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0"
   }
 }

package/python/barefootjs/runtime.py

@@ -531,6 +531,8 @@ class BarefootJS:
 
     _scripts = _dual_accessor("_scripts", lambda self: [])
     _script_seen = _dual_accessor("_script_seen", lambda self: {})
+    _preloads = _dual_accessor("_preloads", lambda self: [])
+    _preload_seen = _dual_accessor("_preload_seen", lambda self: {})
     _child_renderers = _dual_accessor("_child_renderers", lambda self: {})
     _is_child = _dual_accessor("_is_child", False)
     _scope_id = _dual_accessor("_scope_id")
@@ -675,6 +677,24 @@ class BarefootJS:
         seen[path] = True
         self._scripts().append(path)
 
+    def register_preload(self, path: str) -> None:
+        """Register a `<link rel="modulepreload">` hint (a component's
+        resolved TRANSITIVE-chunk preload URL, per
+        `AdapterGenerateOptions.preloadAssets`) -- mirrors `register_script`
+        above exactly. Kept as a SEPARATE `_preloads`/`_preload_seen` pair
+        -- a preload URL and a script URL are never the same concern, so
+        there is no cross-dedup to do between the two. Python lists/dicts
+        are mutable REFERENCE types (unlike PHP arrays), so
+        `child_bf._preloads(parent._preloads())` shares the SAME underlying
+        list -- no `ArrayObject`-style wrapper is needed for cross-instance
+        propagation the way the PHP port requires (see that port's
+        `register_preload` docblock)."""
+        seen = self._preload_seen()
+        if seen.get(path):
+            return
+        seen[path] = True
+        self._preloads().append(path)
+
     # -----------------------------------------------------------------
     # Child Component Rendering
     # -----------------------------------------------------------------
@@ -721,8 +741,9 @@ class BarefootJS:
     def register_components_from_manifest(
         self, manifest: dict, signal_init: Optional[dict] = None
     ) -> None:
-        """`bf build` emits a manifest describing every component the page
-        might invoke. This walks that manifest and registers one child
+        """`vite build` (via `@barefootjs/jinja/vite`'s `barefoot()` plugin)
+        emits a manifest describing every component the page might invoke.
+        This walks that manifest and registers one child
         renderer per UI registry entry -- the path shape `ui/<name>/index`
         maps to the `<name>` slot key the generated template invokes via
         `bf.render_child('<name>', ...)`.
@@ -787,6 +808,8 @@ class BarefootJS:
                     child_bf._child_renderers(parent._child_renderers())
                     child_bf._scripts(parent._scripts())
                     child_bf._script_seen(parent._script_seen())
+                    child_bf._preloads(parent._preloads())
+                    child_bf._preload_seen(parent._preload_seen())
 
                     extra: dict = {}
                     if signal_init_fn:
@@ -810,7 +833,14 @@ class BarefootJS:
     # -----------------------------------------------------------------
 
     def scripts(self) -> str:
-        tags = [f'<script type="module" src="{path}"></script>' for path in self._scripts()]
+        """Renders every collected `<link rel="modulepreload">` hint, THEN
+        every collected `<script type="module">` tag -- preloads always
+        precede the scripts they describe, or the hint 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."""
+        tags = [f'<link rel="modulepreload" crossorigin href="{path}">' for path in self._preloads()]
+        tags += [f'<script type="module" src="{path}"></script>' for path in self._scripts()]
         return "\n".join(tags)
 
     # -----------------------------------------------------------------

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

@@ -567,3 +567,149 @@ export function Child() {
     expect(template).not.toContain('scope_comment')
   })
 })
+
+describe('JinjaAdapter - 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 JinjaAdapter().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 JinjaAdapter().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 JinjaAdapter().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 JinjaAdapter().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 JinjaAdapter().generate(ir).template
+    const explicitUndefined = new JinjaAdapter().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('JinjaAdapter - 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 JinjaAdapter().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 JinjaAdapter().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 JinjaAdapter().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 JinjaAdapter().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 JinjaAdapter().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 JinjaAdapter().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,125 @@
+/**
+ * Coverage of `@barefootjs/jinja/vite`'s `barefoot()`:
+ *
+ * - one real `vite build()` end to end (mirrors `@barefootjs/go-template/
+ *   vite`, `@barefootjs/hono/vite`, and `@barefootjs/blade/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) — `JinjaAdapter.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/jinja/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 .jinja template with scriptAssets baked in, same as core alone would do', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-jinja-vite-dist-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-jinja-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.jinja'), '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-jinja-vite-dist-assets-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-jinja-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-jinja-vite-dist-assets-missing-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-jinja-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/jinja/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 jinjaIdent(this.param)
@@ -296,7 +314,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/jinja-adapter.ts

@@ -193,9 +193,6 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
   name = 'jinja'
   extension = '.jinja'
   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.
@@ -360,7 +357,7 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
     // 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
@@ -402,7 +399,32 @@ export class JinjaAdapter extends BaseAdapter implements IRNodeEmitter<JinjaRend
   // 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.
+      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 ''