brustjs 0.1.39-alpha → 0.1.41-alpha

package/README.md

@@ -79,6 +79,7 @@ the empirically-found limits.
 brustjs dev   <entry>             # dev mode: watcher + WS reload + browser auto-reload
 brustjs build <entry> --out-dir D # prebuilt ./dist/ — run from the project (bun run dist/index.js)
                   --target <auto|all|TARGET[,…]> # which native binary to bundle (default: auto = host platform)
+                  --ssg [--ssg-out D]   # prerender static routes (incl. markdown pages) to HTML
 brustjs new   <name>              # scaffold a project (partial — see Status)
 ```
 
@@ -111,6 +112,10 @@ brustjs new   <name>              # scaffold a project (partial — see Status)
   infers the whole API from the server types (no codegen) and returns
   `{ data, error, status, headers }` (never throws). Standard Schema (zod)
   validation, JSON / urlencoded / multipart bodies.
+- **Markdown pages** — `mdRoutes()` compiles a directory of `.md` files
+  (GFM + frontmatter, optional shiki highlighting) into native jinja routes at
+  build time, with React islands and behavior components embeddable straight
+  from markdown.
 - **SSE & WebSockets** as first-class route shapes.
 - Nested routes + dynamic params, per-route typed loaders, request-scoped middleware,
   SPA-style navigation, in-process LRU response cache + island ISR cache, Tailwind v4 + CSS Modules.
@@ -119,6 +124,35 @@ brustjs new   <name>              # scaffold a project (partial — see Status)
   same validation + middleware as an HTTP request, so agents drive the app
   without scraping.
 
+## Markdown pages
+
+Mount a content directory as routes — each `.md` file becomes a `native: true`
+page compiled to a jinja template at build time (no React on the server, no
+markdown parsing at request time):
+
+```tsx
+// routes.tsx
+import { defineRoutes, mdRoutes } from 'brustjs/routes'
+import DocsLayout from './components/DocsLayout' // owns <BrustPage> + <main><Outlet/></main>
+import Counter from './components/Counter'
+
+export const routes = defineRoutes([
+  ...mdRoutes('content/docs', {
+    prefix: '/docs',                  // content/docs/query/where.md → /docs/query/where
+    layout: DocsLayout,               // optional; head comes from frontmatter via `__md`
+    components: { Counter },          // usable as `<Counter start={5} />` in markdown
+  }),
+])
+```
+
+Frontmatter (`title`, `description`, `nav: { group, order }`) drives `<title>`
+and the `mdNav('content/docs')` sidebar tree. Component tags on their own line
+embed islands (`<Counter start={5} />`, `csr` / `hydrate="visible"` supported)
+or native behavior components. Code fences are highlighted server-side when the
+optional `shiki` peer dependency is installed. `brust build` freezes the pages
+into the dist (`md-manifest.json` — the content dir isn't needed at runtime),
+and `brust build --ssg` prerenders them to static HTML.
+
 ## Performance
 
 Two tiers, split by the napi crossing: pure-Rust paths (`/ping`, native jinja

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.39-alpha",
+  "version": "0.1.41-alpha",
   "description": "Bun + Rust SSR framework — React on the server, Rust everywhere else (napi cdylib + per-worker SharedArrayBuffer).",
   "license": "MIT",
   "repository": {
@@ -36,20 +36,27 @@
   "dependencies": {
     "@tailwindcss/node": "^4.3.0",
     "@tailwindcss/oxide": "^4.3.0",
+    "marked": "^18.0.5",
     "smol-toml": "^1.6.1",
     "typescript": "^6.0.3"
   },
   "optionalDependencies": {
-    "brustjs-darwin-x64": "0.1.39-alpha",
-    "brustjs-darwin-arm64": "0.1.39-alpha",
-    "brustjs-linux-x64-gnu": "0.1.39-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.39-alpha",
-    "brustjs-linux-x64-musl": "0.1.39-alpha",
-    "brustjs-linux-arm64-musl": "0.1.39-alpha"
+    "brustjs-darwin-x64": "0.1.41-alpha",
+    "brustjs-darwin-arm64": "0.1.41-alpha",
+    "brustjs-linux-x64-gnu": "0.1.41-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.41-alpha",
+    "brustjs-linux-x64-musl": "0.1.41-alpha",
+    "brustjs-linux-arm64-musl": "0.1.41-alpha"
   },
   "peerDependencies": {
     "react": "^19.2.6",
-    "react-dom": "^19.2.6"
+    "react-dom": "^19.2.6",
+    "shiki": "^4.2.0"
+  },
+  "peerDependenciesMeta": {
+    "shiki": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
@@ -60,6 +67,7 @@
     "lucide-react": "^1.17.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
+    "shiki": "^4.2.0",
     "zod": "^4.4.3"
   },
   "type": "module",
@@ -94,6 +102,8 @@
     "build:debug": "cd runtime && bun run build:debug",
     "test": "bun test tests/integration.test.ts",
     "dev": "bun runtime/cli/index.ts dev example/pokedex/index.ts",
+    "docs:dev": "cd example/docs && bun ../../runtime/cli/index.ts dev index.ts",
+    "docs:build": "cd example/docs && bun ../../runtime/cli/index.ts build index.ts --out-dir dist --ssg",
     "dev:baseline": "bun run bench/apps/bun-serve/index.ts",
     "bench": "bun run scripts/benchmark.ts",
     "format": "biome format --write .",

package/runtime/cli/build.ts

@@ -138,47 +138,60 @@ export function selectNativeBinaries(
   return { selected, errors }
 }
 
-interface ParsedArgs {
+export interface ParsedArgs {
   entry: string // absolute path to the entry file
   outDir: string // absolute path to the output dir
   target: string // --target value (default 'auto')
+  ssg: boolean // --ssg — prerender static routes after the build
+  ssgOut: string | null // --ssg-out value (absolute); null → <outDir>/static computed later
 }
 
-function parseArgs(args: string[]): ParsedArgs {
+/** Parse `brust build` argv. Pure (no fs access, no process.exit) so it's
+ * unit-testable — throws Error on bad input; runBuild owns stderr + exit. */
+export function parseArgs(args: string[]): ParsedArgs {
   let entry: string | undefined
   let outDir: string | undefined
   let target = 'auto'
+  let ssg = false
+  let ssgOut: string | undefined
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '--out-dir') {
       outDir = args[++i]
       if (!outDir) {
-        console.error('brust build: --out-dir requires a value')
-        process.exit(1)
+        throw new Error('brust build: --out-dir requires a value')
       }
     } else if (a.startsWith('--out-dir=')) {
       outDir = a.slice('--out-dir='.length)
     } else if (a === '--target') {
       target = args[++i]
       if (!target) {
-        console.error('brust build: --target requires a value')
-        process.exit(1)
+        throw new Error('brust build: --target requires a value')
       }
     } else if (a.startsWith('--target=')) {
       target = a.slice('--target='.length)
       if (!target) {
-        console.error('brust build: --target= requires a value')
-        process.exit(1)
+        throw new Error('brust build: --target= requires a value')
+      }
+    } else if (a === '--ssg') {
+      ssg = true
+    } else if (a === '--ssg-out') {
+      ssgOut = args[++i]
+      if (!ssgOut) {
+        throw new Error('brust build: --ssg-out requires a value')
+      }
+    } else if (a.startsWith('--ssg-out=')) {
+      ssgOut = a.slice('--ssg-out='.length)
+      if (!ssgOut) {
+        throw new Error('brust build: --ssg-out= requires a value')
       }
     } else if (a.startsWith('-')) {
-      console.error(`brust build: unknown flag "${a}"`)
-      process.exit(1)
+      throw new Error(`brust build: unknown flag "${a}"`)
     } else if (entry === undefined) {
       entry = a
     } else {
-      console.error(`brust build: unexpected positional argument "${a}"`)
-      process.exit(1)
+      throw new Error(`brust build: unexpected positional argument "${a}"`)
     }
   }
 
@@ -189,22 +202,35 @@ function parseArgs(args: string[]): ParsedArgs {
       : resolve(cwd, entry)
     : resolve(cwd, 'index.ts')
 
-  if (!existsSync(entryPath)) {
-    console.error(`brust build: no entry file at ${entryPath}; pass a path or create ./index.ts`)
-    process.exit(1)
-  }
-
   const outPath = outDir
     ? isAbsolute(outDir)
       ? outDir
       : resolve(cwd, outDir)
     : resolve(cwd, 'dist')
 
-  return { entry: entryPath, outDir: outPath, target }
+  if (ssgOut !== undefined && !ssg) {
+    throw new Error('brust build: --ssg-out requires --ssg')
+  }
+  const ssgOutPath = ssgOut ? (isAbsolute(ssgOut) ? ssgOut : resolve(cwd, ssgOut)) : null
+
+  return { entry: entryPath, outDir: outPath, target, ssg, ssgOut: ssgOutPath }
 }
 
 export async function runBuild(args: string[]): Promise<void> {
-  const { entry, outDir, target } = parseArgs(args)
+  let parsed: ParsedArgs
+  try {
+    parsed = parseArgs(args)
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err))
+    process.exit(1)
+  }
+  const { entry, outDir, target } = parsed
+
+  // Entry existence is a runBuild concern (parseArgs stays fs-free/pure).
+  if (!existsSync(entry)) {
+    console.error(`brust build: no entry file at ${entry}; pass a path or create ./index.ts`)
+    process.exit(1)
+  }
   const entryDir = path.dirname(entry)
 
   console.log(`[brust build] entry:  ${entry}`)
@@ -278,10 +304,46 @@ export async function runBuild(args: string[]): Promise<void> {
     }
   }
 
-  // 3. Build islands (if any <Island> usage is found in the routes graph).
+  // 2.8. Routes module — loaded ONCE here, AFTER the css block (the import may
+  // transitively reach `.module.css`, which needs the cssLoaderPlugin already
+  // registered) and BEFORE the island build (the md emit + island scan below
+  // need the flat route table). The MCP and ssg steps reuse it.
+  let loadedRoutes: any[] | undefined
+  if (existsSync(routesFile)) {
+    const { routes } = await import(routesFile)
+    loadedRoutes = routes
+  }
+
+  // 2.9. md routes — emit `Md_*.jinja` into <outDir>/jinja BEFORE the island
+  // build so islands used only from md content join the chunk scan, and write
+  // the frozen `md-manifest.json` next to BOTH jinja dirs (dist root for the
+  // prebuilt boot's loadPrebuiltMdManifest, cwd/.brust for the source runtime —
+  // the same dual-emit the jinja mirror below does). Strict no-op without md
+  // routes: no files, no dirs, byte-identical dist.
+  const jinjaDir = path.join(outDir, 'jinja')
+  let mdIslands = new Map<string, string>()
+  if (existsSync(routesFile) && loadedRoutes !== undefined) {
+    const { emitMdArtifacts } = await import('../md/emit.ts')
+    ;({ mdIslands } = await emitMdArtifacts({
+      entryFile: routesFile,
+      flatRoutes: loadedRoutes,
+      outDir: jinjaDir,
+      withDevClient: false,
+      manifestDirs: [outDir, path.join(process.cwd(), '.brust')],
+      // Build is fatal on a deleted md file — a silent skip would ship a dist
+      // with the route registered but its template missing (dev paths default
+      // to 'skip-warn' so the hot-reload loop survives the same state).
+      onMissing: 'throw',
+    }))
+    const mdCount = loadedRoutes.filter((r: any) => r?.chain?.at(-1)?.__mdSource).length
+    if (mdCount > 0) console.log(`[brust build] md:      ${mdCount} page(s) → ${jinjaDir}`)
+  }
+
+  // 3. Build islands (if any <Island> usage is found in the routes graph,
+  // plus the md-content islands collected above).
   const { scanIslandChunks, buildIslands } = await import('../islands/build.ts')
   const islandMap = existsSync(routesFile)
-    ? scanIslandChunks(routesFile)
+    ? scanIslandChunks(routesFile, mdIslands)
     : new Map<string, string>()
   if (islandMap.size > 0) {
     const islandsOutDir = path.join(outDir, 'islands')
@@ -347,12 +409,11 @@ export async function runBuild(args: string[]): Promise<void> {
     }
   }
 
-  // 4. MCP manifest (if routes.tsx exists).
-  let loadedRoutes: any[] | undefined
+  // 4. MCP manifest (if routes.tsx exists). Reuses the routes module loaded in
+  // section 2.8.
   if (existsSync(routesFile)) {
     const { extractMcpManifest } = await import('../mcp/extractor.ts')
-    const { routes } = await import(routesFile)
-    loadedRoutes = routes
+    const routes = loadedRoutes ?? []
     const actionsFile = path.join(entryDir, 'actions.ts')
     const manifest = await extractMcpManifest({
       actionsFile: existsSync(actionsFile) ? actionsFile : undefined,
@@ -377,7 +438,9 @@ export async function runBuild(args: string[]): Promise<void> {
     // the other pre-built artifacts (islands, css, mcp-manifest), so a dist-only
     // deploy ships the templates. The prebuilt runtime reads them from
     // `<BRUST_DIST_DIR>/jinja` (see index.ts loadJinjaOnce / configureJinjaDir).
-    const jinjaDir = path.join(outDir, 'jinja')
+    // `jinjaDir` is computed in section 2.9, which already emitted the md
+    // templates into it; emitNativeTemplates never clears the dir, and the
+    // `.brust/jinja` mirror below copies the md templates along.
     // Spec S7 Component-source resolution: scan the routes module's source for
     // ImportDeclarations, NOT the app entry's. The app entry only imports the
     // routes module + brust; the page components are imported by routes.tsx.
@@ -507,5 +570,39 @@ export async function runBuild(args: string[]): Promise<void> {
     console.log(`[brust build] native:  ${name}`)
   }
 
+  // 8. SSG export (--ssg): boot the just-built dist once and crawl every
+  // statically-renderable route into <--ssg-out | outDir/static>. Reuses the
+  // routes module ALREADY loaded for the MCP/css steps (loadedRoutes) — no
+  // second import. Without the flag this is a strict no-op.
+  if (parsed.ssg) {
+    const { collectStaticPaths, exportStatic } = await import('./ssg.ts')
+    const decisions = collectStaticPaths(
+      (loadedRoutes ?? []) as Parameters<typeof collectStaticPaths>[0],
+    )
+    const staticOut = parsed.ssgOut ?? path.join(outDir, 'static')
+    try {
+      const { written, skipped } = await exportStatic({
+        distDir: outDir,
+        entryDir,
+        staticOut,
+        routes: decisions,
+      })
+      const counts = new Map<string, number>()
+      for (const s of skipped) {
+        const r = s.reason ?? 'unknown'
+        counts.set(r, (counts.get(r) ?? 0) + 1)
+      }
+      const reasons = [...counts.keys()]
+        .sort()
+        .map((r) => `${r}=${counts.get(r)}`)
+        .join(', ')
+      const skippedDesc = skipped.length > 0 ? ` (skipped ${skipped.length}: ${reasons})` : ''
+      console.log(`[brust build] ssg:     ${written.length} pages → ${staticOut}${skippedDesc}`)
+    } catch (err) {
+      console.error(`[brust build] ssg: ${err instanceof Error ? err.message : String(err)}`)
+      process.exit(1)
+    }
+  }
+
   console.log(`[brust build] done.`)
 }

package/runtime/cli/dev.ts

@@ -89,7 +89,27 @@ export async function runDev(args: string[]): Promise<void> {
     outDir: jinjaDir,
     repoRoot: REPO_ROOT,
   }
+  // md routes piggyback on the same emit sites (task 2.8): templates land in
+  // the SAME jinja dir, the frozen manifest next to it in `.brust/` (the dist
+  // counterpart is written by `brust build`). Dev pages get the WS dev client
+  // baked (md pages render Rust-side — no React-renderer injection point).
+  // Strict no-op when the app has no md routes.
+  const mdEmitOpts = {
+    ...emitOpts,
+    withDevClient: true,
+    manifestDirs: [path.join(process.cwd(), '.brust')],
+  }
+  // Lazy-load the md emit ONLY when md routes exist: md/emit.ts statically
+  // imports the md renderer (marked), and an md-free app must not pay that
+  // dependency at `brust dev` startup (same gating as build.ts / index.ts).
+  const hasMdRoutes = loadedRoutes.some((r) =>
+    (r as { chain?: { __mdSource?: unknown }[] }).chain?.some((n) => n.__mdSource),
+  )
+  const emitMd = hasMdRoutes
+    ? (await import('../md/emit.ts')).emitMdArtifacts
+    : async (_opts: typeof mdEmitOpts) => {}
   await emitNativeTemplates(emitOpts)
+  await emitMd(mdEmitOpts)
 
   // Native-route HMR: on a ts/html/islands hot reload the dev coordinator calls
   // this to recompile the .jinja templates from the (edited) source and reload
@@ -101,6 +121,7 @@ export async function runDev(args: string[]): Promise<void> {
   const { registerJinjaReEmit } = await import('../dev/jinja-reload.ts')
   registerJinjaReEmit(async () => {
     await emitNativeTemplates(emitOpts)
+    await emitMd(mdEmitOpts)
     const native = await import('../index.js')
     ;(native as { napiLoadJinjaTemplates: (dir: string) => unknown }).napiLoadJinjaTemplates(
       jinjaDir,

package/runtime/cli/help.ts

@@ -37,6 +37,8 @@ interface CommandDef {
   summary: string
   usage: string
   flags: { flag: string; desc: string }[]
+  /** Free-form lines rendered after the Options block (one paragraph per entry). */
+  notes?: string[]
 }
 
 export const COMMANDS: CommandDef[] = [
@@ -51,6 +53,19 @@ export const COMMANDS: CommandDef[] = [
         flag: '--target <t>',
         desc: 'Native target(s): auto | all | <platform>-<arch>[-<libc>][,…] (default auto)',
       },
+      {
+        flag: '--ssg',
+        desc: 'Prerender static routes to HTML files after the build',
+      },
+      {
+        flag: '--ssg-out <dir>',
+        desc: 'Output directory for prerendered HTML (default <out-dir>/static)',
+      },
+    ],
+    notes: [
+      'Markdown pages: routes mounted with mdRoutes(<contentDir>) compile to native',
+      'jinja templates at build time and freeze into <out-dir>/md-manifest.json, so',
+      'the dist serves them without the markdown content directory present.',
     ],
   },
   {
@@ -126,5 +141,9 @@ export function renderCommandHelp(name: string): string | null {
   for (const f of c.flags) {
     lines.push(`  ${style.cyan(pad(f.flag, w))}  ${f.desc}`)
   }
+  if (c.notes && c.notes.length > 0) {
+    lines.push('')
+    for (const n of c.notes) lines.push(style.dim(n))
+  }
   return lines.join('\n')
 }

package/runtime/cli/jinja-staleness.ts

@@ -1,5 +1,5 @@
-import { type Dirent, existsSync, readdirSync, statSync } from 'node:fs'
-import { join } from 'node:path'
+import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 
 // Dirs that never hold authored route/component source — skip them so a stray
 // newer .tsx in a build cache or dependency doesn't force a needless recompile.
@@ -8,6 +8,12 @@ const IGNORED_DIRS = new Set(['node_modules', '.brust', 'dist', '.git'])
 /** Walk `dir` recursively, returning the newest mtime (ms) of any `.tsx` file
  * found, or 0 when there are none. Ignored dirs (build caches, deps) are pruned. */
 function newestTsxMtime(dir: string): number {
+  return newestMtimeWithSuffix(dir, '.tsx')
+}
+
+/** Walk `dir` recursively for the newest mtime (ms) of files ending in
+ * `suffix`, or 0 when there are none. Ignored dirs are pruned. */
+function newestMtimeWithSuffix(dir: string, suffix: string): number {
   let newest = 0
   let entries: Dirent[]
   try {
@@ -18,8 +24,8 @@ function newestTsxMtime(dir: string): number {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (IGNORED_DIRS.has(entry.name)) continue
-      newest = Math.max(newest, newestTsxMtime(join(dir, entry.name)))
-    } else if (entry.isFile() && entry.name.endsWith('.tsx')) {
+      newest = Math.max(newest, newestMtimeWithSuffix(join(dir, entry.name), suffix))
+    } else if (entry.isFile() && entry.name.endsWith(suffix)) {
       try {
         newest = Math.max(newest, statSync(join(dir, entry.name)).mtimeMs)
       } catch {
@@ -36,8 +42,14 @@ function newestTsxMtime(dir: string): number {
  * prior `brust build`, and an edited page is picked up without a stale render.
  *
  * Staleness = the build marker (`_manifest.json`, written last by
- * `emitNativeTemplates`) is absent, OR any source `.tsx` is newer than it. */
-export function isJinjaStale(scanRoot: string, jinjaDir: string): boolean {
+ * `emitNativeTemplates`) is absent, OR any source `.tsx` is newer than it.
+ *
+ * `manifestDir` is where `md-manifest.json` lives. It defaults to
+ * `dirname(jinjaDir)` — the layout contract is `jinjaDir == <x>/jinja` with
+ * the md manifest written next to it in `<x>` (both `emitMdArtifacts` callers
+ * pass `manifestDirs: [<x>]`). A caller that already holds the manifest dir
+ * should pass it explicitly instead of relying on that positional contract. */
+export function isJinjaStale(scanRoot: string, jinjaDir: string, manifestDir?: string): boolean {
   const manifestPath = join(jinjaDir, '_manifest.json')
   if (!existsSync(manifestPath)) return true
   let manifestMtime: number
@@ -46,5 +58,41 @@ export function isJinjaStale(scanRoot: string, jinjaDir: string): boolean {
   } catch {
     return true
   }
-  return newestTsxMtime(scanRoot) > manifestMtime
+  if (newestTsxMtime(scanRoot) > manifestMtime) return true
+  return isMdStale(manifestDir ?? dirname(jinjaDir))
+}
+
+// Filename literal kept local (mirrors MD_MANIFEST_FILENAME in md/routes.ts)
+// so this boot-path module never pulls the md module graph into md-free apps.
+const MD_MANIFEST = 'md-manifest.json'
+
+/** Task 2.9: md pages are also "source" for the emitted templates. The frozen
+ * `md-manifest.json` in `manifestDir` (e.g. `.brust/`, next to its jinja dir)
+ * records every content dir (top-level `contentDir` + optional per-entry
+ * override for multi-dir apps); the manifest file itself is the md build
+ * marker — `emitMdArtifacts` writes it together with the md `.jinja`
+ * templates. Missing or unreadable manifest (no md routes / first boot) →
+ * not stale, same behaviour as before. */
+function isMdStale(manifestDir: string): boolean {
+  const mdManifestPath = join(manifestDir, MD_MANIFEST)
+  if (!existsSync(mdManifestPath)) return false
+  let mdManifestMtime: number
+  let manifest: { contentDir?: unknown; entries?: Array<{ contentDir?: unknown }> }
+  try {
+    mdManifestMtime = statSync(mdManifestPath).mtimeMs
+    manifest = JSON.parse(readFileSync(mdManifestPath, 'utf8'))
+  } catch {
+    return false
+  }
+  const contentDirs = new Set<string>()
+  if (typeof manifest?.contentDir === 'string') contentDirs.add(manifest.contentDir)
+  if (Array.isArray(manifest?.entries)) {
+    for (const e of manifest.entries) {
+      if (typeof e?.contentDir === 'string') contentDirs.add(e.contentDir)
+    }
+  }
+  for (const dir of contentDirs) {
+    if (newestMtimeWithSuffix(dir, '.md') > mdManifestMtime) return true
+  }
+  return false
 }

package/runtime/cli/native-routes-emit.ts

@@ -231,8 +231,12 @@ export function countMainTags(template: string): number {
  * Inserted before the first `</head>` when the page has one (a `<BrustPage>`
  * shell); otherwise appended (bare-fragment pages like a plain `<div>`). The
  * browser executes the module script in either position. Gated on `BRUST_DEV`
- * so `brust build` never bakes it into production templates. */
-function injectDevClientIntoTemplate(template: string): string {
+ * so `brust build` never bakes it into production templates.
+ *
+ * Exported for the md emit step (runtime/md/emit.ts), which bakes the same tag
+ * under its `withDevClient` option — md pages render Rust-side too, so without
+ * it they never auto-reload in dev. */
+export function injectDevClientIntoTemplate(template: string): string {
   const tag = buildDevClientTag()
   if (template.includes(tag)) return template // idempotent across re-emits
   const headClose = template.indexOf('</head>')
@@ -276,7 +280,9 @@ export interface NativeRouteEmitOpts {
    * each carrying its `Component`) drives T2 native-chain composition. */
   flatRoutes: {
     nativeTemplate?: string
-    chain?: Array<{ Component?: { name?: string } }>
+    /** Chain nodes parent→leaf. A leaf carrying `__mdSource` is a markdown
+     * page (runtime/md/routes.ts) — emitted by `emitMdTemplates`, NOT here. */
+    chain?: Array<{ Component?: { name?: string }; __mdSource?: unknown }>
   }[]
   /** `.brust/jinja` absolute output dir. Created if missing. */
   outDir: string
@@ -347,8 +353,11 @@ function toRelativeSpecifier(from: string, to: string): string {
  * path: `components.json` stores `sourcePath` relative to the project root
  * (cwd); `.factory.ts` imports relative to its own location (`.brust/jinja/`).
  * `enriched` keeps the ABSOLUTE path internally for the build-time island scan
- * below (`readFileSync`). */
-function emitComponentArtifacts(
+ * below (`readFileSync`).
+ *
+ * Exported for the md emit step (runtime/md/emit.ts), whose chained wrappers
+ * can carry layout SSR components and need the same sidecar emission. */
+export function emitComponentArtifacts(
   jinjaPath: string,
   componentsJsonStr: string,
   pageImports: Map<string, ResolvedImport>,
@@ -471,7 +480,13 @@ function emitComponentArtifacts(
 export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<void> {
   mkdirSync(opts.outDir, { recursive: true })
 
-  const nativeRoutes = opts.flatRoutes.filter((r) => r.nativeTemplate)
+  // md-route exclusion lives HERE (not at the call sites): a chain whose LEAF
+  // carries `__mdSource` is a markdown page emitted by `emitMdTemplates` —
+  // its synthetic template name has no routes-entry import, so letting it
+  // through would log a bogus "no import → skip" warning per md page.
+  const nativeRoutes = opts.flatRoutes.filter(
+    (r) => r.nativeTemplate && !r.chain?.[r.chain.length - 1]?.__mdSource,
+  )
 
   // Compile through the napi addon's `compileJsx` rather than spawning the
   // `jsx-rustc` binary. The binary only exists in the source tree's target/
@@ -881,13 +896,16 @@ export function scanImports(entryFile: string): Map<string, string> {
  *    `.islands.json`.
  * 4. Append `{% raw %}…{% endraw %}`-wrapped bootstrap to the `.jinja`. The raw
  *    block keeps the importmap's literal `}}`/`{{` inert through minijinja's
- *    boot-time compile.
+ *    boot-time compile. The md emit step passes `bakeBootstrap: false` and bakes
+ *    once itself at the END of its pipeline (the append here has no `includes()`
+ *    guard, so a second pass over the same template would double-bake).
  */
 export function reconcileIslandManifest(
   jinjaPath: string,
   islandsJsonPath: string,
   pageImports: Map<string, ResolvedImport>,
   routeName: string,
+  options?: { bakeBootstrap?: boolean },
 ): void {
   if (!existsSync(islandsJsonPath)) return
 
@@ -941,6 +959,10 @@ export function reconcileIslandManifest(
     },
   )
 
+  if (options?.bakeBootstrap === false) {
+    writeFileSync(jinjaPath, jinja)
+    return
+  }
   const baked = `{% raw %}${ISLANDS_IMPORTMAP_AND_BOOTSTRAP}{% endraw %}`
   writeFileSync(jinjaPath, jinja + baked)
 }