brustjs 0.1.38-alpha → 0.1.40-alpha

package/runtime/md/routes.ts

@@ -0,0 +1,347 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import type { ComponentType } from 'react'
+import type { Route } from '../routes.ts'
+import { type MdFile, scanMdDir } from './scan.ts'
+
+/**
+ * Content-addressed jinja template name for an md page:
+ * `Md_<sanitized relPath>_<8hex(sha256 relPath)>`.
+ *
+ * Sanitizes `[^A-Za-z0-9_]` to `_`; the hash (same scheme as
+ * `islandChunkBasename` in runtime/islands/chunk-id.ts) keeps two relPaths
+ * that sanitize identically (e.g. `a-b.md` vs `a_b.md`) from colliding.
+ */
+export function mdTemplateName(relPath: string): string {
+  const sanitized = relPath.replace(/[^A-Za-z0-9_]/g, '_')
+  const hash = createHash('sha256').update(relPath).digest('hex').slice(0, 8)
+  return `Md_${sanitized}_${hash}`
+}
+
+/**
+ * Maps a content-relative md path to its URL under `prefix`.
+ * `index.md` maps to the prefix itself; `guide/index.md` maps to
+ * `<prefix>/guide`; `query/where.md` maps to `<prefix>/query/where`.
+ * Trailing slashes on `prefix` are normalized away (`/docs/` == `/docs`).
+ */
+export function mdUrlPath(relPath: string, prefix: string): string {
+  let base = prefix.replace(/\/+$/, '')
+  if (base !== '' && !base.startsWith('/')) base = `/${base}`
+  let route = relPath.replace(/\.md$/, '')
+  if (route === 'index') route = ''
+  else if (route.endsWith('/index')) route = route.slice(0, -'/index'.length)
+  const url = route === '' ? base : `${base}/${route}`
+  return url === '' ? '/' : url
+}
+
+// ── Task 2.6: mdRoutes / mdNav / frozen manifest ────────────────────────────
+
+/** Build-time source info attached to every md leaf route. Plain field on the
+ * Route node, so it survives `flattenRoutes` into `FlatRoute.chain` (the chain
+ * holds the node objects); the emit step filters chains whose leaf has it. */
+export interface MdRouteSource {
+  absPath: string
+  relPath: string
+  contentDir: string
+  frontmatter: MdFile['frontmatter']
+  components: Record<string, ComponentType<any>>
+  layoutName?: string
+}
+
+/** An md leaf route — an ordinary native Route plus the `__mdSource` marker. */
+export type MdRoute = Route & { __mdSource: MdRouteSource }
+
+export interface MdRoutesOptions {
+  /** URL prefix the pages mount under. Default `'/'`. */
+  prefix?: string
+  /** Optional layout component — when set, mdRoutes returns ONE parent route
+   * `{ path: prefix, Component: layout, children: [...mdLeaves] }`. */
+  layout?: ComponentType<any>
+  /** Component-tag registry for `<Name />` tags inside the md body. */
+  components?: Record<string, ComponentType<any>>
+}
+
+/** One frozen-manifest entry (everything route construction needs per page).
+ * `contentDir` is only present when the entry belongs to a DIFFERENT content
+ * dir than the manifest's top-level `contentDir` (apps mounting two or more
+ * `mdRoutes()` dirs share ONE manifest file per dist) — additive, so version-1
+ * manifests without it stay readable. */
+export interface MdManifestEntry {
+  relPath: string
+  templateName: string
+  urlPath: string
+  frontmatter: MdFile['frontmatter']
+  contentDir?: string
+}
+
+export interface MdManifest {
+  version: 1
+  contentDir: string
+  entries: MdManifestEntry[]
+}
+
+export const MD_MANIFEST_FILENAME = 'md-manifest.json'
+
+/** Write the frozen md manifest as `<dir>/md-manifest.json` (creates `dir`).
+ * Returns the absolute file path written. */
+export function writeMdManifest(
+  dir: string,
+  entries: MdManifestEntry[],
+  contentDir: string,
+): string {
+  mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, MD_MANIFEST_FILENAME)
+  const manifest: MdManifest = { version: 1, contentDir, entries }
+  writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`)
+  return path.resolve(file)
+}
+
+/** Read + schema-check a frozen md manifest. Throws on a missing file, bad
+ * JSON, or an unsupported version (fail loudly — the manifest is build output). */
+export function readMdManifest(file: string): MdManifest {
+  let parsed: Partial<MdManifest>
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8')) as Partial<MdManifest>
+  } catch (err) {
+    throw new Error(`md manifest ${file}: invalid JSON — ${(err as Error).message}`)
+  }
+  if (parsed?.version !== 1) {
+    throw new Error(`md manifest ${file}: unsupported version ${String(parsed?.version)}`)
+  }
+  if (typeof parsed.contentDir !== 'string' || !Array.isArray(parsed.entries)) {
+    throw new Error(`md manifest ${file}: malformed (expected { contentDir, entries })`)
+  }
+  return parsed as MdManifest
+}
+
+/** Prebuilt-dist detection: the SAME signal index.ts uses to resolve jinjaDir
+ * at boot (`BRUST_PREBUILT === '1'` + `BRUST_DIST_DIR`, set by the dist bundle
+ * banner — see runtime/cli/build.ts). In a prebuilt run, md routes come from
+ * the frozen `<distDir>/md-manifest.json` (the content dir may not ship);
+ * everywhere else we fs-scan. A manifest written for a DIFFERENT content dir
+ * is ignored (falls back to scan). */
+function loadPrebuiltMdManifest(contentDir: string): MdManifest | null {
+  // Deliberately prebuilt-ONLY: in source mode the fs scan is the live truth
+  // (the content dir exists by definition) — reading a `.brust/` manifest there
+  // would serve stale routes after md adds/removes. The `.brust/` copy exists
+  // for jinja-staleness checks (it records contentDir), not route resolution.
+  if (process.env.BRUST_PREBUILT !== '1') return null
+  const distDir = process.env.BRUST_DIST_DIR
+  if (!distDir) return null
+  const file = path.join(distDir, MD_MANIFEST_FILENAME)
+  if (!existsSync(file)) return null
+  let manifest: MdManifest
+  try {
+    manifest = readMdManifest(file)
+  } catch (err) {
+    console.warn(
+      `[brust] md manifest unreadable, falling back to fs scan: ${(err as Error).message}`,
+    )
+    return null
+  }
+  // Multi-dir manifests: an entry belongs to `e.contentDir ?? manifest.contentDir`.
+  // Keep only the entries for the REQUESTED dir; if the dir matches nothing at
+  // all, fall back to the fs scan (same semantics as the old whole-manifest
+  // contentDir mismatch).
+  const wanted = path.resolve(contentDir)
+  const baseMatches = path.resolve(manifest.contentDir) === wanted
+  const entries = manifest.entries.filter((e) =>
+    e.contentDir !== undefined ? path.resolve(e.contentDir) === wanted : baseMatches,
+  )
+  if (entries.length === 0 && !baseMatches) return null
+  return { ...manifest, entries }
+}
+
+/** The slice of a FlatRoute the manifest derivation reads (structural — avoids
+ * a circular import with runtime/md/emit.ts's FlatRouteLike). `Component` is
+ * declared (as unknown — never read here) so the all-optional shape shares a
+ * property with Route and FlatRoute[] passes TS weak-type detection. */
+export interface MdManifestFlatRouteLike {
+  fullPath?: string
+  nativeTemplate?: string
+  chain?: Array<{ Component?: unknown; __mdSource?: MdRouteSource }>
+}
+
+/** Derive the frozen md manifest from the FLAT ROUTE TABLE (single source of
+ * truth — never re-scan the fs at manifest-write time). Returns `null` when the
+ * app has no md routes, so callers can skip ALL md output (the `brust build`
+ * byte-identical invariant for md-free apps). With multiple `mdRoutes()` dirs,
+ * the first dir seen is the manifest's top-level `contentDir`; entries from
+ * other dirs carry a per-entry `contentDir`. */
+export function mdManifestFromFlatRoutes(
+  flatRoutes: MdManifestFlatRouteLike[],
+): { contentDir: string; entries: MdManifestEntry[] } | null {
+  let primary: string | undefined
+  const entries: MdManifestEntry[] = []
+  for (const r of flatRoutes) {
+    const src = r.chain?.[r.chain.length - 1]?.__mdSource
+    if (src === undefined || typeof r.nativeTemplate !== 'string') continue
+    if (typeof r.fullPath !== 'string') {
+      throw new Error(
+        `md route "${r.nativeTemplate}" has no fullPath — pass flattened routes (defineRoutes output)`,
+      )
+    }
+    primary ??= src.contentDir
+    const entry: MdManifestEntry = {
+      relPath: src.relPath,
+      templateName: r.nativeTemplate,
+      urlPath: r.fullPath,
+      frontmatter: src.frontmatter,
+    }
+    if (path.resolve(src.contentDir) !== path.resolve(primary)) entry.contentDir = src.contentDir
+    entries.push(entry)
+  }
+  return primary === undefined ? null : { contentDir: primary, entries }
+}
+
+/** mdNav needs the prefix mdRoutes mounted a content dir under; record it at
+ * mdRoutes() time (routes.tsx runs in the same process). Keyed by resolved
+ * content dir. mdNav falls back to '/' when mdRoutes wasn't called. */
+const mdNavPrefixes = new Map<string, string>()
+
+/** Resolve the page list for a content dir: frozen manifest in a prebuilt
+ * run, fs scan otherwise. */
+function resolveMdPages(contentDir: string, prefix: string): MdManifestEntry[] {
+  const manifest = loadPrebuiltMdManifest(contentDir)
+  if (manifest) {
+    // urlPath is recomputed from relPath + the caller's prefix so the routes
+    // stay deterministic even if the manifest was written with another prefix.
+    return manifest.entries.map((e) => ({ ...e, urlPath: mdUrlPath(e.relPath, prefix) }))
+  }
+  return scanMdDir(contentDir).map((f) => ({
+    relPath: f.relPath,
+    templateName: mdTemplateName(f.relPath),
+    urlPath: mdUrlPath(f.relPath, prefix),
+    frontmatter: f.frontmatter,
+  }))
+}
+
+/** Turn a directory of `.md` files into native Route entries. Each file gets a
+ * synthetic named component (name = its jinja template name, satisfying
+ * `validateRoute`'s native checks) and a loader exposing the frontmatter as
+ * `{ __md: { title, description } }`. With `layout`, returns ONE parent route
+ * at `prefix` whose children carry prefix-relative paths; without, the leaves
+ * carry the full prefixed path. */
+export function mdRoutes(contentDir: string, opts: MdRoutesOptions = {}): Route[] {
+  const prefix = opts.prefix ?? '/'
+  const resolvedDir = path.resolve(contentDir)
+  const existingPrefix = mdNavPrefixes.get(resolvedDir)
+  if (existingPrefix !== undefined && existingPrefix !== prefix) {
+    console.warn(
+      `[brust] mdRoutes: content dir "${contentDir}" already mounted under prefix "${existingPrefix}"; mdNav will use "${prefix}"`,
+    )
+  }
+  mdNavPrefixes.set(resolvedDir, prefix)
+  const components = opts.components ?? {}
+  if (opts.layout !== undefined && !opts.layout.name) {
+    throw new Error(
+      'mdRoutes: layout component must be a NAMED component (its name keys the native template)',
+    )
+  }
+  const layoutName = opts.layout?.name
+  // Normalized prefix URL ('/docs' for '/docs/', '/' for '').
+  const basePath = mdUrlPath('index.md', prefix)
+
+  const leaves: MdRoute[] = resolveMdPages(contentDir, prefix).map((page) => {
+    const C = () => null
+    // validateRoute requires a NAMED component for native routes; the name is
+    // also what flattenRoutes captures as `nativeTemplate`, so it must equal
+    // the emitted jinja template name.
+    Object.defineProperty(C, 'name', { value: page.templateName })
+    const title = typeof page.frontmatter.title === 'string' ? page.frontmatter.title : undefined
+    const description =
+      typeof page.frontmatter.description === 'string' ? page.frontmatter.description : undefined
+    return {
+      path: opts.layout ? relativeToBase(page.urlPath, basePath) : page.urlPath,
+      native: true,
+      Component: C,
+      // Uniform loader (chained AND standalone): head metadata only.
+      loader: async () => ({ __md: { title, description } }),
+      __mdSource: {
+        absPath: path.resolve(contentDir, page.relPath),
+        relPath: page.relPath,
+        contentDir,
+        frontmatter: page.frontmatter,
+        components,
+        layoutName,
+      },
+    }
+  })
+
+  if (opts.layout === undefined) return leaves
+  return [{ path: basePath, native: true, Component: opts.layout, children: leaves }]
+}
+
+/** Strip the mount base off a full url path (index page → `''`, which
+ * `joinPath` composes back onto the parent path unchanged). */
+function relativeToBase(urlPath: string, basePath: string): string {
+  if (urlPath === basePath) return ''
+  return basePath === '/' ? urlPath.slice(1) : urlPath.slice(basePath.length + 1)
+}
+
+export interface MdNavItem {
+  title: string
+  path: string
+  order?: number
+}
+
+export interface MdNavGroup {
+  group: string | null
+  items: MdNavItem[]
+}
+
+/** Navigation model for a content dir: items grouped by `frontmatter.nav.group`
+ * (ungrouped pages land in a `group: null` top-level bucket), sorted by
+ * `nav.order` (missing order sorts last) then title. Paths use the prefix the
+ * dir was mounted under by `mdRoutes` (frozen-manifest urlPaths in a prebuilt
+ * run; `'/'` if mdRoutes was never called for the dir). Group order follows
+ * the first appearance of each group in the sorted item sequence. */
+export function mdNav(contentDir: string): MdNavGroup[] {
+  const manifest = loadPrebuiltMdManifest(contentDir)
+  const navPrefix = mdNavPrefixes.get(path.resolve(contentDir)) ?? '/'
+  const pages: MdManifestEntry[] = manifest
+    ? // urlPath recomputed against the LIVE prefix (same rule as mdRoutes) so
+      // nav links can never diverge from the routes when prefixes change
+      // between build and boot.
+      manifest.entries.map((e) => ({ ...e, urlPath: mdUrlPath(e.relPath, navPrefix) }))
+    : scanMdDir(contentDir).map((f) => ({
+        relPath: f.relPath,
+        templateName: mdTemplateName(f.relPath),
+        urlPath: mdUrlPath(f.relPath, mdNavPrefixes.get(path.resolve(contentDir)) ?? '/'),
+        frontmatter: f.frontmatter,
+      }))
+
+  const items = pages.map((p) => {
+    const nav = p.frontmatter.nav
+    return {
+      group: typeof nav?.group === 'string' ? nav.group : null,
+      title:
+        typeof p.frontmatter.title === 'string' ? p.frontmatter.title : defaultTitle(p.relPath),
+      path: p.urlPath,
+      order: typeof nav?.order === 'number' ? nav.order : undefined,
+    }
+  })
+  items.sort(
+    (a, b) =>
+      (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY) ||
+      a.title.localeCompare(b.title),
+  )
+
+  const groups = new Map<string | null, MdNavItem[]>()
+  for (const item of items) {
+    let bucket = groups.get(item.group)
+    if (bucket === undefined) {
+      bucket = []
+      groups.set(item.group, bucket)
+    }
+    bucket.push({ title: item.title, path: item.path, order: item.order })
+  }
+  return [...groups].map(([group, groupItems]) => ({ group, items: groupItems }))
+}
+
+/** Title fallback for pages without a frontmatter title: the file stem. */
+function defaultTitle(relPath: string): string {
+  const stem = relPath.replace(/\.md$/, '')
+  return stem.split('/').pop() ?? stem
+}

package/runtime/md/scan.ts

@@ -0,0 +1,175 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface MdFile {
+  /** Posix-separated path relative to the content dir, e.g. 'query/where.md'. */
+  relPath: string
+  absPath: string
+  frontmatter: {
+    title?: string
+    description?: string
+    nav?: { group?: string; order?: number }
+    [k: string]: unknown
+  }
+  /** Markdown source after the frontmatter block is stripped. */
+  body: string
+}
+
+/**
+ * Recursively scans `contentDir` for `.md` files, sorted by `relPath`.
+ *
+ * Frontmatter is a leading `---` … `---` block parsed as a hand-rolled YAML
+ * subset (NO yaml dependency):
+ * - `key: value` lines; keys match `[A-Za-z0-9_-]+`
+ * - values: double-quoted strings (JSON escapes), single-quoted strings (no
+ *   escapes), bare strings, numbers, booleans
+ * - one-level nested maps via the INLINE-BRACES form only, e.g.
+ *   `nav: { group: "Getting Started", order: 1 }` — indented child keys are
+ *   NOT supported and throw
+ * - blank lines inside the block are ignored
+ *
+ * Files without a frontmatter block get `frontmatter: {}` and the whole file
+ * as `body`. Malformed frontmatter throws with `<absPath>:<line>`. CRLF line
+ * endings are tolerated.
+ */
+export function scanMdDir(contentDir: string): MdFile[] {
+  const relPaths: string[] = []
+  collectMd(contentDir, '', relPaths)
+  relPaths.sort()
+  return relPaths.map((relPath) => {
+    const absPath = join(contentDir, relPath)
+    const source = readFileSync(absPath, 'utf8')
+    const { frontmatter, body } = splitFrontmatter(source, absPath)
+    return { relPath, absPath, frontmatter, body }
+  })
+}
+
+function collectMd(dir: string, relPrefix: string, out: string[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = relPrefix === '' ? entry.name : `${relPrefix}/${entry.name}`
+    if (entry.isDirectory()) collectMd(join(dir, entry.name), rel, out)
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(rel)
+  }
+}
+
+function splitFrontmatter(
+  source: string,
+  absPath: string,
+): { frontmatter: MdFile['frontmatter']; body: string } {
+  // BOM would otherwise make the opening fence read '---' and the whole
+  // block silently fall through as body — common with Windows editors.
+  const lines = source.replace(/^\uFEFF/, '').split('\n')
+  // Fences tolerate trailing whitespace (and CRLF) — `--- ` is still a fence.
+  const isFence = (line: string) => line.trimEnd() === '---'
+  if (!isFence(lines[0] ?? '')) return { frontmatter: {}, body: source }
+
+  let closeIdx = -1
+  for (let i = 1; i < lines.length; i++) {
+    if (isFence(lines[i] ?? '')) {
+      closeIdx = i
+      break
+    }
+  }
+  if (closeIdx === -1) {
+    throw new Error(`${absPath}:1 unterminated frontmatter block (missing closing ---)`)
+  }
+
+  const frontmatter: MdFile['frontmatter'] = {}
+  for (let i = 1; i < closeIdx; i++) {
+    const line = stripCr(lines[i] ?? '')
+    const fileLine = i + 1
+    if (line.trim() === '') continue
+    const m = /^([A-Za-z0-9_-]+):(.*)$/.exec(line)
+    if (m === null) {
+      throw new Error(
+        `${absPath}:${fileLine} malformed frontmatter line (expected 'key: value'): ${line.trim()}`,
+      )
+    }
+    const key = m[1] as string
+    const raw = (m[2] as string).trim()
+    frontmatter[key] = raw.startsWith('{')
+      ? parseInlineMap(raw, absPath, fileLine)
+      : parseScalar(raw, absPath, fileLine)
+  }
+
+  const body = lines.slice(closeIdx + 1).join('\n')
+  return { frontmatter, body }
+}
+
+function stripCr(line: string): string {
+  return line.endsWith('\r') ? line.slice(0, -1) : line
+}
+
+function parseScalar(raw: string, absPath: string, fileLine: number): unknown {
+  if (raw.startsWith('"')) {
+    if (raw.length < 2 || !raw.endsWith('"')) {
+      throw new Error(`${absPath}:${fileLine} unterminated double-quoted string: ${raw}`)
+    }
+    try {
+      return JSON.parse(raw)
+    } catch {
+      throw new Error(`${absPath}:${fileLine} invalid double-quoted string: ${raw}`)
+    }
+  }
+  if (raw.startsWith("'")) {
+    if (raw.length < 2 || !raw.endsWith("'")) {
+      throw new Error(`${absPath}:${fileLine} unterminated single-quoted string: ${raw}`)
+    }
+    return raw.slice(1, -1)
+  }
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw)
+  return raw
+}
+
+/** Parses the inline-braces map form: `{ key: value, key2: value2 }` (one level). */
+function parseInlineMap(raw: string, absPath: string, fileLine: number): Record<string, unknown> {
+  if (!raw.endsWith('}')) {
+    throw new Error(`${absPath}:${fileLine} unterminated inline map (missing closing }): ${raw}`)
+  }
+  const inner = raw.slice(1, -1).trim()
+  const map: Record<string, unknown> = {}
+  if (inner === '') return map
+  for (const entry of splitTopLevel(inner, absPath, fileLine)) {
+    const m = /^\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))\s*:(.*)$/.exec(entry)
+    if (m === null) {
+      throw new Error(
+        `${absPath}:${fileLine} malformed inline map entry (expected 'key: value'): ${entry.trim()}`,
+      )
+    }
+    const key = (m[1] ?? m[2] ?? m[3]) as string
+    const value = (m[4] as string).trim()
+    if (value === '') {
+      throw new Error(`${absPath}:${fileLine} inline map entry "${key}" has no value`)
+    }
+    map[key] = parseScalar(value, absPath, fileLine)
+  }
+  return map
+}
+
+/** Splits map entries on commas that sit outside quoted strings. */
+function splitTopLevel(inner: string, absPath: string, fileLine: number): string[] {
+  const parts: string[] = []
+  let current = ''
+  let quote: '"' | "'" | null = null
+  for (const ch of inner) {
+    if (quote !== null) {
+      current += ch
+      if (ch === quote) quote = null
+    } else if (ch === '"' || ch === "'") {
+      current += ch
+      quote = ch
+    } else if (ch === ',') {
+      parts.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  if (quote !== null) {
+    throw new Error(`${absPath}:${fileLine} unterminated string inside inline map`)
+  }
+  parts.push(current)
+  return parts
+}

package/runtime/native/build.ts

@@ -5,6 +5,14 @@ import { scanImports } from '../cli/native-routes-emit.ts'
 
 const BEHAVIOR_RE = /export\s+const\s+behavior\b/
 
+/** The single island-vs-behavior classifier: a component source is a native
+ * behavior component iff it has `export const behavior`. Shared by
+ * `scanDirectiveComponents` and the md emit step (runtime/md/emit.ts) so the
+ * two paths can never diverge. */
+export function isBehaviorSource(src: string): boolean {
+  return BEHAVIOR_RE.test(src)
+}
+
 /** Deterministic, app-unique directive name = camelCase(basename) + "_" + 8 hex of
  *  sha256(cwd-relative path). The SINGLE name contract: chunk filename, runtime
  *  registry key, and the compiler-emitted `x-data` all derive from this. */
@@ -36,7 +44,7 @@ export function scanDirectiveComponents(routesEntryFile: string): Map<string, st
     for (const dep of scanImports(filePath).values()) {
       if (!visited.has(dep)) queue.push(dep)
     }
-    if (BEHAVIOR_RE.test(src)) {
+    if (isBehaviorSource(src)) {
       const name = directiveName(filePath, process.cwd())
       const existing = found.get(name)
       if (existing && existing !== filePath) {

package/runtime/native/index.ts

@@ -1,3 +1,6 @@
 // brustjs/native — directive runtime registration surface. React-free, dom-only.
-// Authors do NOT import this directly; the build-generated _directives.js entry does.
+// Authors do NOT import the runtime FUNCTIONS directly; the build-generated
+// _directives.js entry does. The TYPES below ARE for authors — annotate a
+// `behavior`'s ctx (e.g. `({ effect }: BehaviorCtx) => …`).
 export { register, start } from './runtime.ts'
+export type { Behavior, BehaviorCtx, Instance } from './runtime.ts'

package/runtime/native/runtime.ts

@@ -4,7 +4,22 @@ import { batch, effect, isComputed, isSignal, signal } from '../store/index.ts'
 import type { Signal } from '../store/index.ts'
 
 export type Instance = Record<string, unknown>
-export type Behavior = (ctx: { el: HTMLElement; props: unknown }) => Instance
+
+/** What a `behavior` receives. Beyond `el`/`props`, two lifecycle helpers whose
+ * teardown auto-joins the component's disposer set (run on unmount / SPA-nav swap):
+ *  - `effect(fn)`  — a reactive effect (React `useEffect` semantics: `fn` may return
+ *                    a cleanup that runs before each re-run and on unmount). Use it
+ *                    for side-effects on signal change (sync localStorage, the DOM
+ *                    outside the component, timers). Returns the disposer too.
+ *  - `onCleanup(fn)` — register a one-shot teardown for unmount (e.g. removeEventListener). */
+export interface BehaviorCtx {
+  el: HTMLElement
+  props: unknown
+  // biome-ignore lint/suspicious/noConfusingVoidType: React useEffect return shape (`void | Destructor`) — see store `effect`.
+  effect: (fn: () => void | (() => void)) => () => void
+  onCleanup: (fn: () => void) => void
+}
+export type Behavior = (ctx: BehaviorCtx) => Instance
 
 interface Mounted {
   disposers: Array<() => void>
@@ -79,9 +94,25 @@ function mountElement(el: HTMLElement): void {
       console.warn(`[brust] x-props on "${name}" is not valid JSON`)
     }
   }
-  const instance = behavior({ el, props })
+  // Build the disposer set and register the element as mounted BEFORE invoking the
+  // behavior, so (a) the ctx `effect`/`onCleanup` helpers can register teardown
+  // (a ctx effect runs immediately during behavior(), pushing its disposer here),
+  // and (b) a behavior that synchronously triggers a re-entrant mount of THIS
+  // element (e.g. a ctx effect whose signal write reaches scanAndMount) hits the
+  // `mounted.has(el)` guard above instead of creating a second, leaked Mounted.
   const m: Mounted = { disposers: [] }
   mounted.set(el, m)
+  // ctxEffect/onCleanup typed via BehaviorCtx so the `void | Destructor` shape is
+  // declared in one place (the interface) — no inline void-union to suppress here.
+  const ctxEffect: BehaviorCtx['effect'] = (fn) => {
+    const dispose = effect(fn)
+    m.disposers.push(dispose)
+    return dispose
+  }
+  const onCleanup: BehaviorCtx['onCleanup'] = (fn) => {
+    m.disposers.push(fn)
+  }
+  const instance = behavior({ el, props, effect: ctxEffect, onCleanup })
   bindTree(el, instance, m.disposers)
   if (typeof instance.init === 'function') {
     try {

package/runtime/routes.ts

@@ -27,6 +27,19 @@ import type { EndpointDef } from './define-actions.ts'
 import { isRespondSentinel, makeRespond } from './define-actions.ts'
 import { validate } from './standard-schema.ts'
 
+// Markdown pages (task 2.11): the md API is part of the `brustjs/routes`
+// surface — apps spread `...mdRoutes('content/docs', …)` into defineRoutes and
+// render sidebars from `mdNav(...)`. Re-exported here so user code never
+// imports runtime-internal paths.
+export { mdNav, mdRoutes } from './md/routes.ts'
+export type {
+  MdNavGroup,
+  MdNavItem,
+  MdRoute,
+  MdRoutesOptions,
+  MdRouteSource,
+} from './md/routes.ts'
+
 // S2 + B3 — unified per-request scope. The request scope (B3 cookies/context) is
 // the OUTERMOST layer, then the request-scoped loader cache/dedupe (S2: one Map
 // per request for `cachedFetch`/`dedupe` across loaders AND render), then the