livemark 0.24.1 → 0.26.0

package/source/actions/target/build.ts

@@ -1,86 +1,66 @@
-import { createHash } from "node:crypto"
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs"
-import { dirname, join } from "node:path"
+import { cpSync, existsSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from "node:fs"
+import { basename, dirname, join, relative, resolve } from "node:path"
+import { resolveDependencyDir } from "../../helpers/dependency-dir.ts"
 import { ESCAPABLE_FILES, ESCAPABLE_FOLDERS } from "../../settings.ts"
 
-// This file ships at <livemark-pkg>/source/actions/target/build.ts AND
-// gets copied into <livemark-pkg>/targets/<hash>/actions/target/build.ts
-// as part of every per-consumer mount. content-collections loads the
-// COPIED version, so `import.meta.dirname` can land inside `targets/`.
-// Walk up to the first directory holding livemark's `package.json` so
-// SOURCE_DIR / TARGETS_ROOT always anchor at the package, never at a
-// per-consumer dir.
-const LIVEMARK_PKG = findLivemarkPkg(import.meta.dirname)
-const SOURCE_DIR = join(LIVEMARK_PKG, "source")
-const TARGETS_ROOT = join(LIVEMARK_PKG, "targets")
-
-function findLivemarkPkg(start: string) {
-  let cur = start
-  while (cur !== dirname(cur)) {
-    if (existsSync(join(cur, "package.json"))) return cur
-    cur = dirname(cur)
-  }
-  throw new Error(`Could not locate livemark package root from ${start}`)
-}
-
 /**
- * Synthesize a fully self-contained per-consumer Vite mount at
- * `<livemark-pkg>/targets/<hash>/`.
- *
- * The mount is built by copying livemark's `source/` wholesale, then
- * overlaying any matching files from the consumer's `.livemark/`. Every
- * file lives at its target path as a real file — no symlinks — so
- * Vite's relative-import and bare-specifier resolution all anchor
- * inside the target dir, where node_modules walks reach livemark's pnpm
- * subtree natively.
- *
- * Behavior:
- * - First run (target dir missing): full source copy + overlay.
- * - Subsequent runs: skip the source copy. Source is immutable in
- *   installed mode; in livemark's own dev the watcher keeps the target
- *   in sync. Only the `.livemark/` overlay is re-applied each time —
- *   cheap, and may have changed between runs.
- * - With `--clear` in argv: wipe the entire target dir (including
- *   downstream caches like `.vite/`, `.content-collections/`,
- *   `cache/`, `routeTree.gen.ts`) and rebuild from scratch. Use this
- *   to recover from a stale or corrupted cache.
- *
- * Returns the absolute path to the target dir.
+ * Synthesize the project's Vite mount at `.livemark/.target/`: livemark's `source/` with
+ * the project's `.livemark/` escapes copied over it, plus a `node_modules` link to
+ * livemark's dependencies. Escapable folders are rebuilt on every run, so a removed escape
+ * never keeps rendering. Returns the target dir.
  */
-export function buildTarget(configPath: string) {
-  const targetDir = targetDirFor(configPath)
-  const overridesRoot = join(dirname(configPath), ".livemark")
-  const clear = process.argv.includes("--clear")
-
-  if (clear) rmSync(targetDir, { recursive: true, force: true })
-
-  if (!existsSync(targetDir)) {
-    mkdirSync(targetDir, { recursive: true })
-    cpSync(SOURCE_DIR, targetDir, { recursive: true })
-  }
+export function buildTarget(props: { configPath: string; sourceDir: string }) {
+  const targetDir = targetDirFor(props.configPath)
+  const overridesRoot = dirname(targetDir)
+  mkdirSync(targetDir, { recursive: true })
 
+  cpSync(props.sourceDir, targetDir, {
+    recursive: true,
+    filter: src => isPackageFile(src) && !isEscapableFolder(src, props.sourceDir),
+  })
   for (const folder of ESCAPABLE_FOLDERS) {
-    const overlay = join(overridesRoot, folder)
-    if (!existsSync(overlay)) continue
     const dest = join(targetDir, folder)
-    if (!existsSync(dest)) mkdirSync(dest, { recursive: true })
-    for (const f of readdirSync(overlay)) {
-      cpSync(join(overlay, f), join(dest, f), { recursive: true, force: true })
-    }
+    rmSync(dest, { recursive: true, force: true })
+    const source = join(props.sourceDir, folder)
+    if (existsSync(source))
+      cpSync(source, dest, { recursive: true, filter: isPackageFile })
+    const overlay = join(overridesRoot, folder)
+    if (existsSync(overlay)) cpSync(overlay, dest, { recursive: true })
   }
   for (const file of ESCAPABLE_FILES) {
     const overlay = join(overridesRoot, file)
-    if (!existsSync(overlay)) continue
-    cpSync(overlay, join(targetDir, file), { force: true })
+    if (existsSync(overlay)) cpSync(overlay, join(targetDir, file))
   }
 
+  linkDependencies(targetDir, resolveDependencyDir(props.sourceDir))
   return targetDir
 }
 
-/** Compute the target dir for a given consumer config path without
- *  rebuilding it. Used by code that needs to write into the target
- *  (e.g. cache writers) outside of `buildTarget`'s setup phase. */
+/** Locate the project's target dir without building it. */
 export function targetDirFor(configPath: string) {
-  const hash = createHash("sha256").update(configPath).digest("hex").slice(0, 16)
-  return join(TARGETS_ROOT, hash)
+  return join(dirname(configPath), ".livemark", ".target")
+}
+
+function isPackageFile(src: string) {
+  return !/\.unit\.tsx?$/.test(src) && basename(src) !== "fixtures"
+}
+
+function isEscapableFolder(src: string, sourceDir: string) {
+  return ESCAPABLE_FOLDERS.includes(relative(sourceDir, src))
+}
+
+function linkDependencies(targetDir: string, dependencyDir: string) {
+  const link = join(targetDir, "node_modules")
+  if (readLink(link) === resolve(dependencyDir)) return
+  // Not recursive: a stale link must go without touching the store it points into.
+  rmSync(link, { force: true })
+  symlinkSync(dependencyDir, link, "junction")
+}
+
+function readLink(path: string) {
+  try {
+    return resolve(dirname(path), readlinkSync(path))
+  } catch {
+    return undefined
+  }
 }

package/source/actions/target/build.unit.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs"
+import { mkdir, rm, symlink, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { temporaryDirectoryTask } from "tempy"
+import { describe, expect, it } from "vite-plus/test"
+import { buildTarget, targetDirFor } from "./build.ts"
+
+describe("buildTarget", () => {
+  it("copies the source, overlays escapes and skips unit tests", () =>
+    temporaryDirectoryTask(async root => {
+      const { configPath, sourceDir } = await createFixture(root)
+      await put(join(root, "project/.livemark/components/Footer.tsx"), "escaped")
+      await put(join(root, "project/.livemark/head.ts"), "escaped head")
+
+      const targetDir = buildTarget({ configPath, sourceDir })
+
+      expect(targetDir).toBe(join(root, "project/.livemark/.target"))
+      expect(read(targetDir, "components/Footer.tsx")).toBe("escaped")
+      expect(read(targetDir, "components/Header.tsx")).toBe("default")
+      expect(read(targetDir, "head.ts")).toBe("escaped head")
+      expect(read(targetDir, "helpers/util.ts")).toBe("util")
+      expect(existsSync(join(targetDir, "helpers/util.unit.ts"))).toBe(false)
+    }))
+
+  it("drops escapes removed since the last run", () =>
+    temporaryDirectoryTask(async root => {
+      const { configPath, sourceDir } = await createFixture(root)
+      const overrides = join(root, "project/.livemark")
+      await put(join(overrides, "components/Footer.tsx"), "escaped")
+      await put(join(overrides, "routes/about.tsx"), "about")
+      await put(join(overrides, "head.ts"), "escaped head")
+      buildTarget({ configPath, sourceDir })
+
+      await rm(join(overrides, "components"), { recursive: true })
+      await rm(join(overrides, "routes"), { recursive: true })
+      await rm(join(overrides, "head.ts"))
+      const targetDir = buildTarget({ configPath, sourceDir })
+
+      expect(read(targetDir, "components/Footer.tsx")).toBe("default")
+      expect(existsSync(join(targetDir, "routes/about.tsx"))).toBe(false)
+      expect(read(targetDir, "head.ts")).toBe("head")
+    }))
+
+  it("keeps generated entries between runs", () =>
+    temporaryDirectoryTask(async root => {
+      const { configPath, sourceDir } = await createFixture(root)
+      const targetDir = buildTarget({ configPath, sourceDir })
+      await put(join(targetDir, "cache/changelog/entry.md"), "cached")
+
+      buildTarget({ configPath, sourceDir })
+
+      expect(read(targetDir, "cache/changelog/entry.md")).toBe("cached")
+    }))
+
+  it("links node_modules to livemark's dependencies and repairs a stale link", () =>
+    temporaryDirectoryTask(async root => {
+      const { configPath, sourceDir } = await createFixture(root)
+      const link = join(targetDirFor(configPath), "node_modules")
+      const dependencyDir = realpathSync(join(root, "livemark/node_modules"))
+
+      buildTarget({ configPath, sourceDir })
+      expect(readlinkSync(link)).toBe(dependencyDir)
+
+      await rm(link)
+      await mkdir(join(root, "elsewhere"))
+      await symlink(join(root, "elsewhere"), link, "junction")
+      buildTarget({ configPath, sourceDir })
+
+      expect(readlinkSync(link)).toBe(dependencyDir)
+      expect(existsSync(join(root, "elsewhere"))).toBe(true)
+    }))
+})
+
+async function createFixture(root: string) {
+  const sourceDir = join(root, "livemark/source")
+  await put(join(sourceDir, "components/Footer.tsx"), "default")
+  await put(join(sourceDir, "components/Header.tsx"), "default")
+  await put(join(sourceDir, "routes/index.tsx"), "index")
+  await put(join(sourceDir, "helpers/util.ts"), "util")
+  await put(join(sourceDir, "helpers/util.unit.ts"), "test")
+  await put(join(sourceDir, "head.ts"), "head")
+  await mkdir(join(root, "livemark/node_modules"))
+  const configPath = join(root, "project/livemark.config.ts")
+  await put(configPath, "export default {}")
+  return { configPath, sourceDir }
+}
+
+async function put(path: string, content: string) {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, content)
+}
+
+function read(dir: string, path: string) {
+  return readFileSync(join(dir, path), "utf-8")
+}

package/source/actions/target/clear.ts

@@ -0,0 +1,14 @@
+import { rmSync } from "node:fs"
+import { join } from "node:path"
+import { targetDirFor } from "./build.ts"
+
+/**
+ * Wipe the project's target dir so the next run rebuilds it from scratch.
+ */
+export function clearTarget(configPath: string) {
+  const targetDir = targetDirFor(configPath)
+  // Unlink the dependency link first so the recursive remove cannot reach the store.
+  rmSync(join(targetDir, "node_modules"), { force: true })
+  rmSync(targetDir, { recursive: true, force: true })
+  return targetDir
+}

package/source/actions/target/clear.unit.ts

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs"
+import { mkdir, symlink, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import { temporaryDirectoryTask } from "tempy"
+import { describe, expect, it } from "vite-plus/test"
+import { targetDirFor } from "./build.ts"
+import { clearTarget } from "./clear.ts"
+
+describe("clearTarget", () => {
+  it("removes the target dir without following its dependency link", () =>
+    temporaryDirectoryTask(async root => {
+      const configPath = join(root, "livemark.config.ts")
+      const targetDir = targetDirFor(configPath)
+      await mkdir(join(targetDir, "cache"), { recursive: true })
+      await writeFile(join(targetDir, "cache", "entry.md"), "cached")
+      await mkdir(join(root, "deps"))
+      await writeFile(join(root, "deps", "kept.js"), "")
+      await symlink(join(root, "deps"), join(targetDir, "node_modules"), "junction")
+
+      expect(clearTarget(configPath)).toBe(targetDir)
+      expect(existsSync(targetDir)).toBe(false)
+      expect(existsSync(join(root, "deps", "kept.js"))).toBe(true)
+      expect(() => clearTarget(configPath)).not.toThrow()
+    }))
+})

package/source/commands/build.ts

@@ -9,7 +9,6 @@ const configFile = join(import.meta.dirname, "..", "..", "source", "vite.config.
  */
 export const build = new Command("build")
   .description("Build the site for production")
-  .option("--clear", "Wipe and fully rebuild the runtime target dir")
   .action(async () => {
     const builder = await createBuilder({ configFile })
     await builder.buildApp()

package/source/commands/clear.ts

@@ -0,0 +1,15 @@
+import { Command } from "commander"
+import pc from "picocolors"
+import { loadConfig } from "../actions/config/load.ts"
+import { clearTarget } from "../actions/target/clear.ts"
+
+/**
+ * Wipe the generated `.livemark/.target/` mount.
+ */
+export const clear = new Command("clear")
+  .description("Wipe the generated .livemark/.target/ mount")
+  .action(async () => {
+    const config = await loadConfig()
+    const targetDir = clearTarget(config.configPath)
+    console.log(`Cleared ${pc.dim(targetDir)}`)
+  })

package/source/commands/escape.ts

@@ -1,79 +1,62 @@
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-  writeFileSync,
-} from "node:fs"
-import { dirname, join } from "node:path"
+import { join } from "node:path"
+import { autocompleteMultiselect, cancel, isCancel } from "@clack/prompts"
 import { Command } from "commander"
 import pc from "picocolors"
-import { ESCAPABLE_FILES, ESCAPABLE_FOLDERS } from "../settings.ts"
+import { copyEscape } from "../actions/escape/copy.ts"
+import { listEscapes } from "../actions/escape/list.ts"
 
-const defaultsRoot = join(import.meta.dirname, "..", "..", "source")
+const sourceRoot = join(import.meta.dirname, "..", "..", "source")
 
 /**
- * List or copy escapable livemark files into `.livemark/`.
+ * Pick, list or copy escapable livemark files into `.livemark/`.
  *
- * Without an argument, prints every file you can shadow. With a path, copies
- * the default from the livemark package into `.livemark/<path>`; fails if the
+ * Without an argument, opens a searchable picker in a terminal and prints every
+ * file you can shadow otherwise (or with `--list`). With paths, copies each
+ * default from the livemark package into `.livemark/<path>`; fails if a
  * destination already exists.
  */
 export const escape = new Command("escape")
-  .description("List or copy escapable livemark files into .livemark/")
+  .description("Pick, list or copy escapable livemark files into .livemark/")
   .argument(
-    "[path]",
-    "path relative to .livemark/ (e.g. components/Footer.tsx, client.tsx)",
+    "[paths...]",
+    "paths relative to .livemark/ (e.g. components/Footer.tsx, client.tsx)",
   )
-  .action((relPath?: string) => {
-    if (!relPath) {
-      for (const file of listEscapable()) console.log(file)
+  .option("-l, --list", "print every escapable file instead of opening the picker")
+  .action(async (paths: string[], options: { list?: boolean }) => {
+    const root = process.cwd()
+    if (paths.length) return copyPaths(root, paths)
+
+    const escapes = listEscapes({ root, sourceRoot })
+    if (options.list || !process.stdin.isTTY || !process.stdout.isTTY) {
+      for (const escape of escapes) console.log(escape.path)
       console.log(pc.dim("\nRun 'livemark escape <path>' to copy a file into .livemark/"))
       return
     }
 
-    const isTopLevelFile = !relPath.includes("/") && ESCAPABLE_FILES.includes(relPath)
-    const [first] = relPath.split("/")
-    const isFolderPath =
-      !!first && ESCAPABLE_FOLDERS.includes(first) && !relPath.includes("..")
-    if (!isTopLevelFile && !isFolderPath) {
-      console.error(
-        pc.red(
-          `Error: '${relPath}' is not escapable (folders: ${ESCAPABLE_FOLDERS.join(", ")}; files: ${ESCAPABLE_FILES.join(", ")})`,
-        ),
-      )
-      process.exit(1)
-    }
-
-    const src = join(defaultsRoot, relPath)
-    if (!existsSync(src) || !statSync(src).isFile()) {
-      console.error(pc.red(`Error: '${relPath}' is not a livemark file`))
-      process.exit(1)
-    }
-
-    const dest = join(process.cwd(), ".livemark", relPath)
-    if (existsSync(dest)) {
-      console.error(pc.red(`Error: .livemark/${relPath} already exists`))
-      process.exit(1)
-    }
-
-    mkdirSync(dirname(dest), { recursive: true })
-    writeFileSync(dest, readFileSync(src))
-    console.log(`Copied ${pc.dim(relPath)} → ${pc.green(`.livemark/${relPath}`)}`)
+    const selected = await autocompleteMultiselect({
+      message: "Select files to escape into .livemark/",
+      placeholder: "Type to search...",
+      options: escapes.map(escape => ({
+        value: escape.path,
+        label: escape.path,
+        hint: escape.escaped ? "already escaped" : undefined,
+        disabled: escape.escaped,
+      })),
+      required: false,
+    })
+    if (isCancel(selected)) return cancel("Nothing copied")
+    copyPaths(root, selected)
   })
 
-function listEscapable() {
-  const files: string[] = []
-  for (const folder of ESCAPABLE_FOLDERS) {
-    const dir = join(defaultsRoot, folder)
-    if (!existsSync(dir)) continue
-    for (const entry of readdirSync(dir)) {
-      if (statSync(join(dir, entry)).isFile()) files.push(`${folder}/${entry}`)
+function copyPaths(root: string, paths: string[]) {
+  for (const path of paths) {
+    try {
+      copyEscape({ root, sourceRoot, path })
+      console.log(`Copied ${pc.dim(path)} → ${pc.green(`.livemark/${path}`)}`)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.error(pc.red(`Error: ${message}`))
+      process.exitCode = 1
     }
   }
-  for (const file of ESCAPABLE_FILES) {
-    if (existsSync(join(defaultsRoot, file))) files.push(file)
-  }
-  return files.sort()
 }

package/source/commands/preview.ts

@@ -9,7 +9,6 @@ const configFile = join(import.meta.dirname, "..", "..", "source", "vite.config.
  */
 export const preview = new Command("preview")
   .description("Preview the production build locally")
-  .option("--clear", "Wipe and fully rebuild the runtime target dir")
   .action(async () => {
     const server = await vitePreview({
       configFile,

package/source/commands/start.ts

@@ -9,7 +9,6 @@ const configFile = join(import.meta.dirname, "..", "..", "source", "vite.config.
  */
 export const start = new Command("start")
   .description("Start a live server")
-  .option("--clear", "Wipe and fully rebuild the runtime target dir")
   .action(async () => {
     const server = await createServer({
       configFile,

package/source/components/AnsiCode.tsx

@@ -1,7 +1,7 @@
 /** Renders pre-formatted HTML produced from ANSI escape sequences */
 export function AnsiCode(props: { html: string }) {
   return (
-    <figure className="shiki not-prose my-4 relative rounded-xl border shadow-sm overflow-hidden text-sm bg-sidebar dark:bg-sidebar">
+    <figure className="shiki not-prose my-4 relative rounded-card border shadow-sm overflow-hidden text-sm bg-sidebar dark:bg-sidebar">
       <div className="text-[0.8125rem] py-3.5 overflow-auto">
         <pre className="min-w-full w-max">
           <code

package/source/components/Article.tsx

@@ -1,6 +1,8 @@
+import { useRef } from "react"
 import { MDXContent } from "@content-collections/mdx/react"
 import { Calendar, History, User } from "lucide-react"
 import type { ArticleView } from "../models/article.ts"
+import { useSearchHighlight } from "../helpers/search-highlight.ts"
 import { TocContext } from "../helpers/toc-context.ts"
 import { Abbr } from "./Abbr.tsx"
 import { AnsiCode } from "./AnsiCode.tsx"
@@ -42,8 +44,10 @@ import { ZoomImage } from "./ZoomImage.tsx"
 import { Separator } from "../elements/separator.tsx"
 
 /** Full-page article layout: MDX content, table of contents, toolbar, prev/next, footer */
-export function Article(props: { article: ArticleView }) {
+export function Article(props: { article: ArticleView; highlight?: string }) {
   const { article } = props
+  const prose = useRef<HTMLDivElement>(null)
+  useSearchHighlight(prose, article.path, props.highlight)
   const lastUpdated = formatDate(article.lastUpdated)
   const publishedDate = formatDate(article.date)
   const authors = article.author
@@ -56,7 +60,7 @@ export function Article(props: { article: ArticleView }) {
   return (
     <TocContext.Provider value={article.tocItems}>
       {article.toc !== false && (
-        <MobileToc items={article.tocItems}>
+        <MobileToc items={article.tocItems} title={article.title}>
           <PageToolbar
             file={article.file}
             sourceUrl={article.sourceUrl}
@@ -67,7 +71,7 @@ export function Article(props: { article: ArticleView }) {
       )}
       <div className="flex flex-1 gap-10 p-4 pt-8 md:p-10">
         <div className="flex-1 min-w-0 mx-auto max-w-3xl">
-          <div className="prose dark:prose-invert max-w-none">
+          <div ref={prose} className="prose dark:prose-invert max-w-none">
             <h1 id="top">
               <a href="#top">{article.title}</a>
             </h1>
@@ -97,7 +101,7 @@ export function Article(props: { article: ArticleView }) {
               <img
                 src={article.image}
                 alt=""
-                className="!mt-0 !mb-6 w-full rounded-xl border shadow-sm"
+                className="!mt-0 !mb-6 w-full rounded-card border shadow-sm"
               />
             )}
             <MDXContent

package/source/components/Banner.tsx

@@ -1,4 +1,14 @@
-/** Optional header banner. Empty by default; shadow via `.livemark/components/Banner.tsx` to render content. */
+import { bannerHtml } from "livemark:virtual"
+
+/** Announcement strip above the header, rendered from the `banner` config option. */
 export function Banner() {
-  return null
+  if (!bannerHtml) return null
+  return (
+    <div className="bg-banner text-banner-foreground">
+      <div
+        className="min-w-0 px-4 py-2 text-center font-mono text-xs tracking-wide text-balance sm:px-6 [&_a]:underline [&_a]:underline-offset-4 [&_a:hover]:no-underline [&_code]:font-semibold"
+        dangerouslySetInnerHTML={{ __html: bannerHtml }}
+      />
+    </div>
+  )
 }

package/source/components/BlogIndex.tsx

@@ -40,7 +40,7 @@ export function BlogIndex(props: { sectionPrefix: string }) {
 
   return (
     <TocContext.Provider value={tocItems}>
-      <MobileToc items={tocItems}>
+      <MobileToc items={tocItems} title={section?.title ?? "Blog"}>
         <PageToolbar content={content} />
       </MobileToc>
       <div className="flex flex-1 gap-10 p-4 pt-8 md:p-10">

package/source/components/Callout.tsx

@@ -25,20 +25,18 @@ const configs: Record<CalloutType, CalloutConfig> = {
   tip: {
     icon: Lightbulb,
     label: "Tip",
-    classes:
-      "border-green-500/30 bg-green-50/50 text-green-900 dark:bg-green-950/30 dark:text-green-200",
+    classes: "border-positive/30 bg-positive-tint/50 text-positive-tint-foreground",
   },
   warning: {
     icon: AlertTriangle,
     label: "Warning",
-    classes:
-      "border-yellow-500/30 bg-yellow-50/50 text-yellow-900 dark:bg-yellow-950/30 dark:text-yellow-200",
+    classes: "border-warning/30 bg-warning-tint/50 text-warning-tint-foreground",
   },
   danger: {
     icon: Flame,
     label: "Danger",
     classes:
-      "border-red-500/30 bg-red-50/50 text-red-900 dark:bg-red-950/30 dark:text-red-200",
+      "border-destructive/30 bg-destructive-tint/50 text-destructive-tint-foreground",
   },
 }
 
@@ -54,7 +52,7 @@ export function Callout(props: {
   const title = props.title ?? config.label
 
   return (
-    <aside className={cn("not-prose my-4 rounded-xl border px-4 py-3", config.classes)}>
+    <aside className={cn("not-prose my-4 rounded-card border px-4 py-3", config.classes)}>
       <div className="flex items-center gap-2 font-semibold text-sm mb-2">
         <Icon className="size-4 shrink-0" />
         <span>{title}</span>

package/source/components/ChangelogIndex.tsx

@@ -37,7 +37,7 @@ export function ChangelogIndex(props: { sectionPrefix: string }) {
 
   return (
     <TocContext.Provider value={tocItems}>
-      <MobileToc items={tocItems}>
+      <MobileToc items={tocItems} title={section?.title ?? "Changelog"}>
         <PageToolbar content={content} />
       </MobileToc>
       <div className="flex flex-1 gap-10 p-4 pt-8 md:p-10">

package/source/components/ChoiceList.tsx

@@ -0,0 +1,69 @@
+import { CheckIcon } from "lucide-react"
+import type { MouseEvent, ReactNode } from "react"
+import { cn } from "cn"
+
+export type Choice = {
+  id: string
+  label: ReactNode
+  icon?: ReactNode
+  href?: string
+  /** Indent level below the top one, for a nested choice like a sub-heading. */
+  depth?: number
+}
+
+/** The rows of a sheet that picks one of a list, the selected one tinted and ticked. */
+export function ChoiceList(props: {
+  choices: Choice[]
+  selectedId?: string
+  onSelect?: (choice: Choice, event: MouseEvent<HTMLElement>) => void
+}) {
+  return (
+    <ul className="-mx-2 flex flex-col gap-0.5">
+      {props.choices.map(choice => {
+        const selected = choice.id === props.selectedId
+        const className = cn(
+          "hover:bg-muted active:bg-muted flex h-10 w-full items-center gap-2.5 rounded-control px-2 text-left text-base outline-hidden focus-visible:ring-2 focus-visible:ring-ring [&_svg]:size-[18px] [&_svg]:shrink-0",
+          selected && "bg-sidebar-accent text-sidebar-accent-foreground font-medium",
+        )
+        const content = (
+          <>
+            {choice.icon}
+            <span
+              className={cn(
+                "flex-1 truncate",
+                choice.depth === 1 && "ps-4",
+                (choice.depth ?? 0) >= 2 && "ps-8",
+              )}
+            >
+              {choice.label}
+            </span>
+            {selected && <CheckIcon className="text-primary" />}
+          </>
+        )
+        return (
+          <li key={choice.id}>
+            {choice.href ? (
+              <a
+                href={choice.href}
+                aria-current={selected || undefined}
+                className={className}
+                onClick={event => props.onSelect?.(choice, event)}
+              >
+                {content}
+              </a>
+            ) : (
+              <button
+                type="button"
+                aria-pressed={selected}
+                className={className}
+                onClick={event => props.onSelect?.(choice, event)}
+              >
+                {content}
+              </button>
+            )}
+          </li>
+        )
+      })}
+    </ul>
+  )
+}