npm - brustjs - Versions diffs - 0.1.38-alpha → 0.1.40-alpha - Mend

brustjs 0.1.38-alpha → 0.1.40-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/README.md +34 -0
package/example/pokedex/components/ThemeToggle.tsx +11 -3
package/package.json +16 -8
package/runtime/cli/build.ts +123 -26
package/runtime/cli/dev.ts +21 -0
package/runtime/cli/help.ts +19 -0
package/runtime/cli/jinja-staleness.ts +55 -7
package/runtime/cli/native-routes-emit.ts +29 -7
package/runtime/cli/ssg.ts +257 -0
package/runtime/dev/coordinator.ts +16 -4
package/runtime/dev/watcher.ts +16 -5
package/runtime/index.js +52 -52
package/runtime/index.ts +68 -3
package/runtime/islands/bootstrap.ts +23 -0
package/runtime/islands/build.ts +23 -1
package/runtime/islands/native-render.ts +16 -3
package/runtime/md/emit.ts +544 -0
package/runtime/md/render.ts +469 -0
package/runtime/md/routes.ts +347 -0
package/runtime/md/scan.ts +175 -0
package/runtime/native/build.ts +9 -1
package/runtime/native/index.ts +4 -1
package/runtime/native/runtime.ts +33 -2
package/runtime/routes.ts +13 -0
package/runtime/store/signal.ts +40 -3

package/README.md CHANGED Viewed

@@ -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/example/pokedex/components/ThemeToggle.tsx CHANGED Viewed

@@ -11,6 +11,7 @@
 // /theme action which sets the `mode` cookie — so SSR matches on the next load.
 import { Moon, Sun } from 'lucide-react'
 import { client } from 'brustjs/client'
+import type { BehaviorCtx } from 'brustjs/native'
 import { computed, signal } from 'brustjs/store'
 import type { Actions } from '../actions'
@@ -18,7 +19,7 @@ const api = client<Actions>()
 // behavior → client bundle, registered as "themeToggle". Reads the initial mode
 // straight off <html data-mode> (server already set it from the cookie).
-export const behavior = () => {
+export const behavior = ({ effect }: BehaviorCtx) => {
   const mode = signal(
     typeof document !== 'undefined' ? (document.documentElement.dataset.mode ?? 'dark') : 'dark',
   )
@@ -28,10 +29,17 @@ export const behavior = () => {
   const isDark = computed(() => mode() === 'dark')
   const isLight = computed(() => mode() === 'light')
+  // Reactive sync (dogfooding ctx `effect`): reflect `mode` onto <html data-mode>
+  // whenever it changes — the toggle just flips the signal, the DOM follows. On
+  // mount this runs once and writes the value the server already set (a no-op, so
+  // no flash). Replaces the imperative `dataset.mode = …` that lived in toggle().
+  effect(() => {
+    document.documentElement.dataset.mode = mode()
+  })
   async function toggle() {
     const next = mode() === 'dark' ? 'light' : 'dark'
-    document.documentElement.dataset.mode = next // flip the theme immediately
-    mode.set(next)
+    mode.set(next) // the effect flips <html data-mode> reactively
     await api.theme.post({ mode: next }) // persist via cookie for the next SSR
   }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.38-alpha",
+  "version": "0.1.40-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.38-alpha",
-    "brustjs-darwin-arm64": "0.1.38-alpha",
-    "brustjs-linux-x64-gnu": "0.1.38-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.38-alpha",
-    "brustjs-linux-x64-musl": "0.1.38-alpha",
-    "brustjs-linux-arm64-musl": "0.1.38-alpha"
+    "brustjs-darwin-x64": "0.1.40-alpha",
+    "brustjs-darwin-arm64": "0.1.40-alpha",
+    "brustjs-linux-x64-gnu": "0.1.40-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.40-alpha",
+    "brustjs-linux-x64-musl": "0.1.40-alpha",
+    "brustjs-linux-arm64-musl": "0.1.40-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",

package/runtime/cli/build.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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)
 }