@cfbender/cesium 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## v0.5.1 — 2026-05-12
+
+Server-side syntax highlighting for `code` blocks via shiki, custom claret
+themes derived from the canonical `claret.nvim` sources, and a critical fix
+to the lazy-start lifecycle so `cesium stop` (or test friendly-fire) can no
+longer kill the plugin host process.
+
+- **fix (critical):** Lazy-started cesium server now runs as a detached
+  subprocess. Previously `ensureRunning` (called from publish/ask plugin
+  paths) ran `Bun.serve()` in-process and wrote `pid: process.pid` to the PID
+  file — meaning that PID was the *plugin host* (e.g. opencode). Any
+  invocation of `cesium stop` (CLI, tool, or test) would signal the host
+  process and kill it. Now lazy-start spawns `bun run cli serve` as a
+  detached child; the PID file points at that child. Foreground `cesium
+  serve` still runs in-process (correct for its semantics).
+- **api:** Split `ensureRunning` into `runServerForeground` (in-process, for
+  the foreground CLI) and `ensureServerRunning` (detached subprocess, for
+  plugins). `ensureRunning` is kept as a backward-compat alias for
+  `runServerForeground`.
+- **fix:** `test/cli-entry.test.ts` now sets `CESIUM_STATE_DIR` to a temp
+  dir per spawned subprocess, so the `cesium stop` test no longer reads the
+  user's real PID file.
+- **feat:** Server-side syntax highlighting via shiki. `code` blocks are
+  tokenized at publish time and emit styled token spans. Async cascade
+  through `renderBlock`/`renderBlocks`/`renderSection`/`renderCode`.
+- **feat:** Custom `claret-dark` shiki theme — converted directly from
+  `claret.nvim`'s `ports/bat/ClaretDark.tmTheme` so colors are faithful to
+  the canonical claret palette (keywords claret rose, strings olive,
+  comments muted italic, functions gold, etc.).
+- **feat:** Custom `claret-light` shiki theme — derived from claret.nvim's
+  light palette using the same scope grammar as the dark theme.
+- **feat:** `resolveHighlightTheme(cesiumThemeName)` — maps cesium presets
+  to the right shiki theme. `claret`/`claret-dark` → claret-dark,
+  `claret-light` → claret-light, all others → `vitesse-dark`.
+- **feat:** `RenderCtx.highlightTheme` threaded from publish through the
+  render context. Default is `claret-dark` (matches the framework default).
+- **feat:** `cesium serve` gains a `--state-dir` flag and respects
+  `CESIUM_STATE_DIR` / `CESIUM_PORT` env vars (used by the detached spawn).
+- **dep:** Added `shiki@^4.0.0` as a runtime dependency (~3.8MB on disk;
+  languages loaded lazily).
+
 ## v0.5.0 — 2026-05-12
 
 Block-mode refactor — `cesium_publish` now accepts a structured `blocks` array

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "license": "MIT",
   "author": "Cody Bender",
@@ -50,7 +50,8 @@
   "dependencies": {
     "@opencode-ai/plugin": "latest",
     "nanoid": "^5.0.0",
-    "parse5": "^7.1.0"
+    "parse5": "^7.1.0",
+    "shiki": "^4.0.2"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/cli/commands/serve.ts

@@ -2,7 +2,7 @@
 
 import { parseArgs } from "node:util";
 import { loadConfig, type CesiumConfig } from "../../config.ts";
-import { ensureRunning, stopRunning } from "../../server/lifecycle.ts";
+import { runServerForeground, stopRunning } from "../../server/lifecycle.ts";
 import { resolveDisplayHost } from "../../tools/publish.ts";
 import { themeFromPreset, mergeTheme } from "../../render/theme.ts";
 
@@ -22,6 +22,7 @@ function defaultCtx(): ServeContext {
 export interface ServeOptions {
   port?: number;
   hostname?: string;
+  stateDir?: string;
   /**
    * Idle timeout in milliseconds. 0 (the default for `cesium serve`) means the
    * server runs forever until SIGINT/SIGTERM. Override with --idle-timeout to
@@ -54,6 +55,7 @@ export function parseServeArgs(
     port: string | undefined;
     hostname: string | undefined;
     "idle-timeout": string | undefined;
+    "state-dir": string | undefined;
     help: boolean;
   };
 
@@ -64,6 +66,7 @@ export function parseServeArgs(
         port: { type: "string", short: "p" },
         hostname: { type: "string", short: "H" },
         "idle-timeout": { type: "string" },
+        "state-dir": { type: "string" },
         help: { type: "boolean", short: "h", default: false },
       },
       allowPositionals: false,
@@ -85,6 +88,7 @@ export function parseServeArgs(
         "Options:",
         "  --port, -p N        Override configured port (default: 3030)",
         "  --hostname, -H H    Override configured bind address (default: 127.0.0.1)",
+        "  --state-dir DIR     Override the cesium state directory",
         "  --idle-timeout DUR  Auto-shutdown after DUR of inactivity. Accepts plain",
         "                      milliseconds or a suffixed value (90s, 30m, 2h).",
         "                      Use 0 / never / off to disable. Default: 0 (never).",
@@ -121,6 +125,14 @@ export function parseServeArgs(
     opts.hostname = values.hostname;
   }
 
+  if (values["state-dir"] !== undefined) {
+    if (values["state-dir"].length === 0) {
+      ctx.stderr.write(`cesium serve: --state-dir must not be empty\n`);
+      return null;
+    }
+    opts.stateDir = values["state-dir"];
+  }
+
   if (values["idle-timeout"] !== undefined) {
     const ms = parseDuration(values["idle-timeout"]);
     if (ms === null) {
@@ -154,6 +166,7 @@ export async function serveCommand(argv: string[], ctx?: Partial<ServeContext>):
   // Apply overrides from CLI flags
   const effectiveCfg = {
     ...cfg,
+    ...(opts.stateDir !== undefined ? { stateDir: opts.stateDir } : {}),
     ...(opts.port !== undefined ? { port: opts.port, portMax: opts.port } : {}),
     ...(opts.hostname !== undefined ? { hostname: opts.hostname } : {}),
     idleTimeoutMs: effectiveIdleTimeoutMs,
@@ -162,7 +175,7 @@ export async function serveCommand(argv: string[], ctx?: Partial<ServeContext>):
   let serverInfo: { port: number; url: string };
   try {
     const theme = mergeTheme(themeFromPreset(effectiveCfg.themePreset), effectiveCfg.theme);
-    serverInfo = await ensureRunning({
+    serverInfo = await runServerForeground({
       stateDir: effectiveCfg.stateDir,
       port: effectiveCfg.port,
       portMax: effectiveCfg.portMax,

package/src/render/blocks/highlight.ts

@@ -0,0 +1,188 @@
+// Server-side syntax highlighting via shiki.
+// src/render/blocks/highlight.ts
+//
+// Lazy-initializes a shared highlighter on first call.
+// Returns styled <span> tokens only — no <pre> wrapper.
+// The caller (code renderer) is responsible for the <pre><code> panel chrome.
+
+import type { ThemedToken, BundledLanguage } from "shiki";
+import { escapeHtml } from "./escape.ts";
+import { claretDark } from "./themes/claret-dark.ts";
+import { claretLight } from "./themes/claret-light.ts";
+import { THEME_PRESETS, isThemePresetName } from "../../render/theme.ts";
+
+// ─── Highlight theme type ─────────────────────────────────────────────────────
+
+export type HighlightTheme =
+  | "claret-dark"
+  | "claret-light"
+  | "vitesse-dark"
+  | "vitesse-light";
+
+// ─── Supported languages ─────────────────────────────────────────────────────
+
+/**
+ * The curated language list loaded into the highlighter.
+ * ~25 languages covering 95 %+ of real use.
+ */
+export const SUPPORTED_LANGUAGES: readonly string[] = [
+  "typescript",
+  "ts",
+  "tsx",
+  "javascript",
+  "js",
+  "jsx",
+  "json",
+  "html",
+  "css",
+  "markdown",
+  "md",
+  "shellscript",
+  "sh",
+  "bash",
+  "shell",
+  "python",
+  "py",
+  "rust",
+  "go",
+  "ruby",
+  "rb",
+  "yaml",
+  "yml",
+  "sql",
+  "toml",
+  "dockerfile",
+  "diff",
+];
+
+// ─── Theme resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Map a cesium theme preset name to the appropriate shiki highlight theme.
+ *
+ * - "claret" / "claret-dark" → "claret-dark" (custom)
+ * - "claret-light"           → "claret-light" (custom)
+ * - other named preset       → vitesse-dark if codeBg is dark, else vitesse-light
+ * - unknown / undefined      → "claret-dark" (matches framework default in themeFromPreset)
+ */
+export function resolveHighlightTheme(cesiumThemeName: string | undefined): HighlightTheme {
+  if (cesiumThemeName === "claret" || cesiumThemeName === "claret-dark") {
+    return "claret-dark";
+  }
+  if (cesiumThemeName === "claret-light") {
+    return "claret-light";
+  }
+  if (cesiumThemeName !== undefined && isThemePresetName(cesiumThemeName)) {
+    const palette = THEME_PRESETS[cesiumThemeName];
+    // Use the code panel background color to choose the shiki theme.
+    // All current non-claret presets have a dark codeBg, but check anyway.
+    return isHexDark(palette.codeBg) ? "vitesse-dark" : "vitesse-light";
+  }
+  // undefined / unknown — match the framework theme default (claret-dark).
+  return "claret-dark";
+}
+
+/**
+ * Returns true if the hex color's perceived luminance is dark (< 0.5).
+ * Accepts 3- or 6-digit hex with or without leading '#'.
+ */
+function isHexDark(hex: string): boolean {
+  const clean = hex.replace("#", "");
+  const full = clean.length === 3
+    ? clean
+        .split("")
+        .map((c) => c + c)
+        .join("")
+    : clean;
+  const r = parseInt(full.slice(0, 2), 16);
+  const g = parseInt(full.slice(2, 4), 16);
+  const b = parseInt(full.slice(4, 6), 16);
+  // Simple average luminance threshold
+  const avg = (r + g + b) / 3;
+  return avg < 128;
+}
+
+// ─── Highlighter singleton ────────────────────────────────────────────────────
+
+/** Promise cache — concurrent first-calls share one init. */
+let highlighterPromise: Promise<import("shiki").Highlighter> | null = null;
+
+async function getHighlighter(): Promise<import("shiki").Highlighter> {
+  if (highlighterPromise === null) {
+    const { createHighlighter } = await import("shiki");
+    highlighterPromise = createHighlighter({
+      themes: [
+        // Custom claret themes passed as ThemeRegistration objects
+        claretDark,
+        claretLight,
+        // Vitesse themes loaded by name from the bundled set
+        "vitesse-dark",
+        "vitesse-light",
+      ],
+      langs: SUPPORTED_LANGUAGES as string[],
+    });
+  }
+  return highlighterPromise;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Highlight `code` in language `lang` with the given `theme`.
+ * Returns the inner HTML for a `<code>` element: one `<span class="line">` per
+ * source line, each containing `<span style="color:...">` token spans.
+ *
+ * If `lang` is not in SUPPORTED_LANGUAGES, falls back to plain-escaped output
+ * wrapped the same way (one `<span class="line">` per line, no color spans).
+ *
+ * shiki internally escapes `<`, `>`, `&` in token content, so XSS is covered.
+ * The plain-text fallback goes through `escapeHtml` for the same guarantee.
+ */
+export async function highlightCode(
+  code: string,
+  lang: string,
+  theme: HighlightTheme = "claret-dark",
+): Promise<string> {
+  const supported = SUPPORTED_LANGUAGES.includes(lang);
+
+  if (!supported) {
+    return plainFallback(code);
+  }
+
+  const hi = await getHighlighter();
+  const result = hi.codeToTokens(code, { theme, lang: lang as BundledLanguage });
+
+  return tokensToHtml(result.tokens);
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Render shiki token lines into `<span class="line">` HTML.
+ * Token `content` is already HTML-escaped by shiki.
+ */
+function tokensToHtml(lines: ThemedToken[][]): string {
+  return lines
+    .map((line) => {
+      const inner = line
+        .map((token) => {
+          if (token.color !== undefined && token.color !== "") {
+            return `<span style="color:${token.color}">${token.content}</span>`;
+          }
+          // No color info — emit bare content (shiki has already escaped it)
+          return token.content;
+        })
+        .join("");
+      return `<span class="line">${inner}</span>`;
+    })
+    .join("\n");
+}
+
+/**
+ * Plain-text fallback: escape HTML and wrap each line in a `<span class="line">`.
+ * Used when the requested language is not in the supported set.
+ */
+function plainFallback(code: string): string {
+  const lines = code.split("\n");
+  return lines.map((line) => `<span class="line">${escapeHtml(line)}</span>`).join("\n");
+}

package/src/render/blocks/render.ts

@@ -2,6 +2,7 @@
 // src/render/blocks/render.ts
 
 import type { Block } from "./types.ts";
+import type { HighlightTheme } from "./highlight.ts";
 import { renderHero } from "./renderers/hero.ts";
 import { renderTldr } from "./renderers/tldr.ts";
 import { renderSection } from "./renderers/section.ts";
@@ -31,18 +32,21 @@ export interface RenderCtx {
   depth: number;
   /** Path string for error messages (e.g. "blocks[2].children[1]"). */
   path: string;
+  /** Shiki highlight theme derived from the active cesium theme preset. */
+  highlightTheme: HighlightTheme;
 }
 
-function makeRootCtx(): RenderCtx {
+function makeRootCtx(highlightTheme: HighlightTheme = "claret-dark"): RenderCtx {
   return {
     sectionCounter: { value: 1 },
     depth: 0,
     path: "blocks",
+    highlightTheme,
   };
 }
 
 /** Dispatch a single block to its renderer. */
-export function renderBlock(block: Block, ctx: RenderCtx): string {
+export async function renderBlock(block: Block, ctx: RenderCtx): Promise<string> {
   switch (block.type) {
     case "hero":
       return renderHero(block, ctx);
@@ -78,8 +82,11 @@ export function renderBlock(block: Block, ctx: RenderCtx): string {
 }
 
 /** Render an array of blocks, returning the concatenated HTML body string. */
-export function renderBlocks(blocks: Block[], opts?: { title?: string }): string {
-  const ctx = makeRootCtx();
+export async function renderBlocks(
+  blocks: Block[],
+  opts?: { title?: string; highlightTheme?: HighlightTheme },
+): Promise<string> {
+  const ctx = makeRootCtx(opts?.highlightTheme);
   const parts: string[] = [];
   for (let i = 0; i < blocks.length; i++) {
     const block = blocks[i];
@@ -88,7 +95,8 @@ export function renderBlocks(blocks: Block[], opts?: { title?: string }): string
       ...ctx,
       path: `blocks[${i}]`,
     };
-    parts.push(renderBlock(block, blockCtx));
+    // eslint-disable-next-line no-await-in-loop -- sequential render required; section counter is a shared mutable ref
+    parts.push(await renderBlock(block, blockCtx));
   }
   // Unused opts.title kept for API compatibility; wrapDocument handles the title
   void opts;

package/src/render/blocks/renderers/code.ts

@@ -1,12 +1,13 @@
-// Code block renderer.
+// Code block renderer — server-side syntax highlighting via shiki.
 // src/render/blocks/renderers/code.ts
 
 import type { CodeBlock } from "../types.ts";
 import type { BlockMeta } from "../types.ts";
 import type { RenderCtx } from "../render.ts";
 import { escapeHtml, escapeAttr } from "../escape.ts";
+import { highlightCode } from "../highlight.ts";
 
-export function renderCode(block: CodeBlock, _ctx: RenderCtx): string {
+export async function renderCode(block: CodeBlock, ctx: RenderCtx): Promise<string> {
   const parts: string[] = [];
 
   const captionText = block.filename ?? block.caption;
@@ -14,8 +15,9 @@ export function renderCode(block: CodeBlock, _ctx: RenderCtx): string {
     parts.push(`  <figcaption>${escapeHtml(captionText)}</figcaption>`);
   }
 
+  const highlighted = await highlightCode(block.code, block.lang, ctx.highlightTheme);
   parts.push(
-    `  <pre><code class="lang-${escapeAttr(block.lang)}">${escapeHtml(block.code)}</code></pre>`,
+    `  <pre><code class="lang-${escapeAttr(block.lang)}">${highlighted}</code></pre>`,
   );
 
   return `<figure class="code">\n${parts.join("\n")}\n</figure>`;

package/src/render/blocks/renderers/section.ts

@@ -7,7 +7,7 @@ import type { RenderCtx } from "../render.ts";
 import { renderBlock } from "../render.ts";
 import { escapeHtml } from "../escape.ts";
 
-export function renderSection(block: SectionBlock, ctx: RenderCtx): string {
+export async function renderSection(block: SectionBlock, ctx: RenderCtx): Promise<string> {
   // Determine section number: explicit or auto-increment
   let num: string;
   if (block.num !== undefined && block.num !== "") {
@@ -34,6 +34,7 @@ export function renderSection(block: SectionBlock, ctx: RenderCtx): string {
     sectionCounter: ctx.sectionCounter,
     depth: ctx.depth + 1,
     path: `${ctx.path}.children`,
+    highlightTheme: ctx.highlightTheme,
   };
 
   let buffer: string[] = [];
@@ -45,7 +46,8 @@ export function renderSection(block: SectionBlock, ctx: RenderCtx): string {
       ...childCtx,
       path: `${ctx.path}.children[${i}]`,
     };
-    const rendered = renderBlock(child, childBlockCtx);
+    // eslint-disable-next-line no-await-in-loop -- sequential render required; card buffer tracks contiguous non-section children
+    const rendered = await renderBlock(child, childBlockCtx);
     if (child.type === "section") {
       // Flush buffered non-section children into a card first
       if (buffer.length > 0) {

package/src/render/blocks/themes/claret-dark.ts

@@ -0,0 +1,206 @@
+// Claret-dark shiki theme — converted from ports/bat/ClaretDark.tmTheme.
+// src/render/blocks/themes/claret-dark.ts
+//
+// Source of truth: /claret.nvim/ports/bat/ClaretDark.tmTheme
+// Every scope rule in the tmTheme is preserved verbatim; comma-separated
+// scope strings are split into the string[] form shiki prefers.
+//
+// Global tokens (from tmTheme global settings):
+//   bg         #180810  — editor background
+//   fg         #DDD3C7  — default foreground
+//   selection  #2B1F22
+//   gutter fg  #71685E
+//
+// Derived palette reference (claret.nvim/lua/claret/palette.lua — dark):
+//   rose_1    #C75B7A   keyword / statement / accent
+//   rose_2    #B04A68   property / data keys
+//   gold_1    #D4A76A   function / number / constant / decorator
+//   sage_1    #8FA86E   string
+//   slate_1   #8995A8   type / class / tag / escape / link
+//   slate_2   #6E7A90   tag attribute
+//   text      #DDD3C7   variable / default fg
+//   text_2    #BDB3A7   operator (syntax.lua maps Operator → text_2; tmTheme uses #9E9288)
+//             NOTE: the tmTheme uses #9E9288 (text_3) for operator/punctuation — preserved.
+//   text_4    #71685E   comment (fg)
+//   terra_1   #C44536   invalid / diff deleted
+
+import type { ThemeRegistration } from "shiki";
+
+export const claretDark: ThemeRegistration = {
+  name: "claret-dark",
+  type: "dark",
+  fg: "#DDD3C7",
+  bg: "#180810",
+  colors: {
+    "editor.foreground": "#DDD3C7",
+    "editor.background": "#180810",
+    "editor.selectionBackground": "#2B1F22",
+    "editor.lineHighlightBackground": "#2B1F22",
+    "editorLineNumber.foreground": "#71685E",
+  },
+  tokenColors: [
+    // Comment — #71685E italic
+    {
+      name: "Comment",
+      scope: ["comment", "punctuation.definition.comment"],
+      settings: { foreground: "#71685E", fontStyle: "italic" },
+    },
+    // Keyword — #C75B7A
+    {
+      name: "Keyword",
+      scope: ["keyword", "storage.type", "storage.modifier"],
+      settings: { foreground: "#C75B7A" },
+    },
+    // Function — #D4A76A
+    {
+      name: "Function",
+      scope: ["entity.name.function", "support.function"],
+      settings: { foreground: "#D4A76A" },
+    },
+    // String — #8FA86E
+    {
+      name: "String",
+      scope: ["string", "punctuation.definition.string"],
+      settings: { foreground: "#8FA86E" },
+    },
+    // Number — #D4A76A
+    {
+      name: "Number",
+      scope: ["constant.numeric"],
+      settings: { foreground: "#D4A76A" },
+    },
+    // Constant — #D4A76A
+    {
+      name: "Constant",
+      scope: ["constant", "constant.language", "variable.language"],
+      settings: { foreground: "#D4A76A" },
+    },
+    // Type — #8995A8
+    {
+      name: "Type",
+      scope: [
+        "entity.name.type",
+        "entity.name.class",
+        "support.type",
+        "support.class",
+      ],
+      settings: { foreground: "#8995A8" },
+    },
+    // Variable — #DDD3C7
+    {
+      name: "Variable",
+      scope: ["variable", "variable.parameter"],
+      settings: { foreground: "#DDD3C7" },
+    },
+    // Parameter — #DDD3C7 italic (overrides Variable for parameters)
+    {
+      name: "Parameter",
+      scope: ["variable.parameter"],
+      settings: { foreground: "#DDD3C7", fontStyle: "italic" },
+    },
+    // Property — #B04A68
+    {
+      name: "Property",
+      scope: ["variable.other.property", "variable.other.member"],
+      settings: { foreground: "#B04A68" },
+    },
+    // JSON/YAML/TOML Keys — #B04A68
+    {
+      name: "JSON/YAML/TOML Keys",
+      scope: [
+        "meta.mapping.key string",
+        "support.type.property-name.json",
+        "punctuation.support.type.property-name.json",
+        "support.type.property-name.toml",
+        "punctuation.support.type.property-name.toml",
+        "entity.name.tag.yaml",
+        "support.type.property-name.yaml",
+      ],
+      settings: { foreground: "#B04A68" },
+    },
+    // Operator — #9E9288
+    {
+      name: "Operator",
+      scope: ["keyword.operator"],
+      settings: { foreground: "#9E9288" },
+    },
+    // Punctuation — #9E9288
+    {
+      name: "Punctuation",
+      scope: ["punctuation"],
+      settings: { foreground: "#9E9288" },
+    },
+    // Decorator — #D4A76A italic
+    {
+      name: "Decorator",
+      scope: ["meta.decorator", "punctuation.decorator"],
+      settings: { foreground: "#D4A76A", fontStyle: "italic" },
+    },
+    // Tag — #8995A8
+    {
+      name: "Tag",
+      scope: ["entity.name.tag"],
+      settings: { foreground: "#8995A8" },
+    },
+    // Tag Attribute — #6E7A90
+    {
+      name: "Tag Attribute",
+      scope: ["entity.other.attribute-name"],
+      settings: { foreground: "#6E7A90" },
+    },
+    // Invalid — #C44536
+    {
+      name: "Invalid",
+      scope: ["invalid", "invalid.illegal"],
+      settings: { foreground: "#C44536" },
+    },
+    // Escape — #8995A8
+    {
+      name: "Escape",
+      scope: ["constant.character.escape"],
+      settings: { foreground: "#8995A8" },
+    },
+    // Markup Heading — #C75B7A bold
+    {
+      name: "Markup Heading",
+      scope: ["markup.heading"],
+      settings: { foreground: "#C75B7A", fontStyle: "bold" },
+    },
+    // Markup Bold — bold (no color override)
+    {
+      name: "Markup Bold",
+      scope: ["markup.bold"],
+      settings: { fontStyle: "bold" },
+    },
+    // Markup Italic — italic (no color override)
+    {
+      name: "Markup Italic",
+      scope: ["markup.italic"],
+      settings: { fontStyle: "italic" },
+    },
+    // Markup Link — #8995A8
+    {
+      name: "Markup Link",
+      scope: ["markup.underline.link", "string.other.link"],
+      settings: { foreground: "#8995A8" },
+    },
+    // Diff Added — #8FA86E
+    {
+      name: "Diff Added",
+      scope: ["markup.inserted"],
+      settings: { foreground: "#8FA86E" },
+    },
+    // Diff Deleted — #C44536
+    {
+      name: "Diff Deleted",
+      scope: ["markup.deleted"],
+      settings: { foreground: "#C44536" },
+    },
+    // Diff Changed — #D4A76A
+    {
+      name: "Diff Changed",
+      scope: ["markup.changed"],
+      settings: { foreground: "#D4A76A" },
+    },
+  ],
+};

package/src/render/blocks/themes/claret-light.ts

@@ -0,0 +1,227 @@
+// Claret-light shiki theme — derived from claret.nvim light palette.
+// src/render/blocks/themes/claret-light.ts
+//
+// Source of truth: /claret.nvim/lua/claret/palette.lua (light section)
+// Scope-to-role mapping mirrors ClaretDark.tmTheme exactly; colors
+// are substituted from the light palette using the same semantic roles.
+//
+// Light palette (palette.lua):
+//   bg         #F5E6E2   editor background
+//   bg_mute    #DDD0CC   selection / line highlight
+//   text       #2A1F1A   default fg
+//   text_4     #928578   comment / gutter fg
+//   rose_1     #B80842   keyword / heading / statement
+//   rose_2     #920820   property / data keys
+//   gold_1     #946000   function / number / constant / decorator
+//   sage_1     #1B5500   string
+//   slate_1    #0E3088   type / class / tag / escape / link
+//   slate_2    #0A2575   tag attribute
+//   terra_1    #D42010   invalid / diff deleted
+//
+// Role mapping (matching dark tmTheme):
+//   Comment       → text_4   #928578   italic
+//   Keyword       → rose_1   #B80842
+//   Function      → gold_1   #946000
+//   String        → sage_1   #1B5500
+//   Number        → gold_1   #946000
+//   Constant      → gold_1   #946000
+//   Type          → slate_1  #0E3088
+//   Variable      → text     #2A1F1A
+//   Parameter     → text     #2A1F1A   italic
+//   Property      → rose_2   #920820
+//   Keys          → rose_2   #920820
+//   Operator      → text_4   #928578   (text_3 equivalent; nearest warm muted in light palette)
+//   Punctuation   → text_4   #928578
+//   Decorator     → gold_1   #946000   italic
+//   Tag           → slate_1  #0E3088
+//   Tag Attribute → slate_2  #0A2575
+//   Invalid       → terra_1  #D42010
+//   Escape        → slate_1  #0E3088
+//   Markup Heading→ rose_1   #B80842   bold
+//   Markup Bold   → (no fg)            bold
+//   Markup Italic → (no fg)            italic
+//   Markup Link   → slate_1  #0E3088
+//   Diff Added    → sage_1   #1B5500
+//   Diff Deleted  → terra_1  #D42010
+//   Diff Changed  → gold_1   #946000
+
+import type { ThemeRegistration } from "shiki";
+
+export const claretLight: ThemeRegistration = {
+  name: "claret-light",
+  type: "light",
+  fg: "#2A1F1A",
+  bg: "#F5E6E2",
+  colors: {
+    "editor.foreground": "#2A1F1A",
+    "editor.background": "#F5E6E2",
+    "editor.selectionBackground": "#DDD0CC",
+    "editor.lineHighlightBackground": "#DDD0CC",
+    "editorLineNumber.foreground": "#928578",
+  },
+  tokenColors: [
+    // Comment — #928578 italic
+    {
+      name: "Comment",
+      scope: ["comment", "punctuation.definition.comment"],
+      settings: { foreground: "#928578", fontStyle: "italic" },
+    },
+    // Keyword — #B80842
+    {
+      name: "Keyword",
+      scope: ["keyword", "storage.type", "storage.modifier"],
+      settings: { foreground: "#B80842" },
+    },
+    // Function — #946000
+    {
+      name: "Function",
+      scope: ["entity.name.function", "support.function"],
+      settings: { foreground: "#946000" },
+    },
+    // String — #1B5500
+    {
+      name: "String",
+      scope: ["string", "punctuation.definition.string"],
+      settings: { foreground: "#1B5500" },
+    },
+    // Number — #946000
+    {
+      name: "Number",
+      scope: ["constant.numeric"],
+      settings: { foreground: "#946000" },
+    },
+    // Constant — #946000
+    {
+      name: "Constant",
+      scope: ["constant", "constant.language", "variable.language"],
+      settings: { foreground: "#946000" },
+    },
+    // Type — #0E3088
+    {
+      name: "Type",
+      scope: [
+        "entity.name.type",
+        "entity.name.class",
+        "support.type",
+        "support.class",
+      ],
+      settings: { foreground: "#0E3088" },
+    },
+    // Variable — #2A1F1A
+    {
+      name: "Variable",
+      scope: ["variable", "variable.parameter"],
+      settings: { foreground: "#2A1F1A" },
+    },
+    // Parameter — #2A1F1A italic (overrides Variable for parameters)
+    {
+      name: "Parameter",
+      scope: ["variable.parameter"],
+      settings: { foreground: "#2A1F1A", fontStyle: "italic" },
+    },
+    // Property — #920820
+    {
+      name: "Property",
+      scope: ["variable.other.property", "variable.other.member"],
+      settings: { foreground: "#920820" },
+    },
+    // JSON/YAML/TOML Keys — #920820
+    {
+      name: "JSON/YAML/TOML Keys",
+      scope: [
+        "meta.mapping.key string",
+        "support.type.property-name.json",
+        "punctuation.support.type.property-name.json",
+        "support.type.property-name.toml",
+        "punctuation.support.type.property-name.toml",
+        "entity.name.tag.yaml",
+        "support.type.property-name.yaml",
+      ],
+      settings: { foreground: "#920820" },
+    },
+    // Operator — #928578
+    {
+      name: "Operator",
+      scope: ["keyword.operator"],
+      settings: { foreground: "#928578" },
+    },
+    // Punctuation — #928578
+    {
+      name: "Punctuation",
+      scope: ["punctuation"],
+      settings: { foreground: "#928578" },
+    },
+    // Decorator — #946000 italic
+    {
+      name: "Decorator",
+      scope: ["meta.decorator", "punctuation.decorator"],
+      settings: { foreground: "#946000", fontStyle: "italic" },
+    },
+    // Tag — #0E3088
+    {
+      name: "Tag",
+      scope: ["entity.name.tag"],
+      settings: { foreground: "#0E3088" },
+    },
+    // Tag Attribute — #0A2575
+    {
+      name: "Tag Attribute",
+      scope: ["entity.other.attribute-name"],
+      settings: { foreground: "#0A2575" },
+    },
+    // Invalid — #D42010
+    {
+      name: "Invalid",
+      scope: ["invalid", "invalid.illegal"],
+      settings: { foreground: "#D42010" },
+    },
+    // Escape — #0E3088
+    {
+      name: "Escape",
+      scope: ["constant.character.escape"],
+      settings: { foreground: "#0E3088" },
+    },
+    // Markup Heading — #B80842 bold
+    {
+      name: "Markup Heading",
+      scope: ["markup.heading"],
+      settings: { foreground: "#B80842", fontStyle: "bold" },
+    },
+    // Markup Bold — bold (no color override)
+    {
+      name: "Markup Bold",
+      scope: ["markup.bold"],
+      settings: { fontStyle: "bold" },
+    },
+    // Markup Italic — italic (no color override)
+    {
+      name: "Markup Italic",
+      scope: ["markup.italic"],
+      settings: { fontStyle: "italic" },
+    },
+    // Markup Link — #0E3088
+    {
+      name: "Markup Link",
+      scope: ["markup.underline.link", "string.other.link"],
+      settings: { foreground: "#0E3088" },
+    },
+    // Diff Added — #1B5500
+    {
+      name: "Diff Added",
+      scope: ["markup.inserted"],
+      settings: { foreground: "#1B5500" },
+    },
+    // Diff Deleted — #D42010
+    {
+      name: "Diff Deleted",
+      scope: ["markup.deleted"],
+      settings: { foreground: "#D42010" },
+    },
+    // Diff Changed — #946000
+    {
+      name: "Diff Changed",
+      scope: ["markup.changed"],
+      settings: { foreground: "#946000" },
+    },
+  ],
+};

package/src/server/lifecycle.ts

@@ -2,7 +2,10 @@
 
 import { join } from "node:path";
 import { readFileSync, unlinkSync } from "node:fs";
-import { unlink, writeFile } from "node:fs/promises";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
 import { startServer, type ServerHandle } from "./http.ts";
 import { acquireLock } from "../storage/lock.ts";
 import { createApiHandler } from "./api.ts";
@@ -202,8 +205,19 @@ export async function stopRunning(stateDir: string): Promise<void> {
   }
 }
 
-export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo> {
-  const { stateDir, port, portMax, idleTimeoutMs, hostname = "127.0.0.1", theme = defaultTheme() } = cfg;
+// ─── In-process (foreground) server start ────────────────────────────────────
+// Used by `cesium serve` CLI. Runs Bun.serve() in-process; killing the process
+// IS stopping the server, which is the user's intent for a foreground invocation.
+
+export async function runServerForeground(cfg: LifecycleConfig): Promise<RunningInfo> {
+  const {
+    stateDir,
+    port,
+    portMax,
+    idleTimeoutMs,
+    hostname = "127.0.0.1",
+    theme = defaultTheme(),
+  } = cfg;
   const pidFilePath = join(stateDir, ".server.pid");
   const lockPath = join(stateDir, ".server-start.lock");
 
@@ -310,6 +324,173 @@ export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo>
   }
 }
 
+// ─── Detached (lazy) server start ────────────────────────────────────────────
+// Used by plugin callers (publish, ask). Spawns `cesium serve` as a detached
+// subprocess so the subprocess PID is what ends up in the PID file. Sending a
+// signal to that PID kills only the server child, never the plugin host.
+
+// Locate CLI entry relative to this file: src/server/lifecycle.ts → src/cli/index.ts
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI_ENTRY = join(HERE, "..", "cli", "index.ts");
+
+// Readiness poll backoff schedule (ms between attempts)
+const POLL_SCHEDULE = [50, 100, 200, 500, 1000, 1000, 1000, 1000, 1000, 1000];
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function httpProbe(url: string): Promise<boolean> {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(1000) });
+    // Any HTTP response (even 404) means the server is up
+    return res.status < 600;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureServerRunning(cfg: LifecycleConfig): Promise<RunningInfo> {
+  const { stateDir, port, idleTimeoutMs } = cfg;
+  const pidFilePath = join(stateDir, ".server.pid");
+  // Use a separate lock from runServerForeground's ".server-start.lock" to avoid
+  // deadlock: the child process runs runServerForeground which acquires that lock,
+  // so the parent must not hold it while waiting for the child.
+  const spawnLockPath = join(stateDir, ".server-spawn.lock");
+
+  // Fast path: read existing PID file and probe liveness
+  const existing = readPidFile(pidFilePath);
+  if (existing !== null && isAlive(existing.pid)) {
+    const probeUrl = `http://${existing.hostname}:${existing.port}/`;
+    const alive = await httpProbe(probeUrl);
+    if (alive) {
+      return {
+        port: existing.port,
+        url: `http://${existing.hostname}:${existing.port}`,
+        pid: existing.pid,
+        startedAt: existing.startedAt,
+      };
+    }
+    // Process alive but not responding — fall through to spawn fresh
+  }
+
+  // Ensure state dir exists before trying to acquire lock or write files
+  await mkdir(stateDir, { recursive: true });
+
+  // Use a spawn-only lock to prevent concurrent spawns. Release it immediately
+  // after spawning so the child can acquire its own (.server-start.lock) lock.
+  const spawnLock = await acquireLock({ lockPath: spawnLockPath, timeoutMs: 15_000, staleMs: 30_000 });
+  try {
+    // Re-check after acquiring lock
+    const existingAfterLock = readPidFile(pidFilePath);
+    if (existingAfterLock !== null && isAlive(existingAfterLock.pid)) {
+      const probeUrl = `http://${existingAfterLock.hostname}:${existingAfterLock.port}/`;
+      const alive = await httpProbe(probeUrl);
+      if (alive) {
+        return {
+          port: existingAfterLock.port,
+          url: `http://${existingAfterLock.hostname}:${existingAfterLock.port}`,
+          pid: existingAfterLock.pid,
+          startedAt: existingAfterLock.startedAt,
+        };
+      }
+    }
+
+    // Clean up stale PID file if present
+    try {
+      await unlink(pidFilePath);
+    } catch {
+      // ENOENT is fine
+    }
+
+    // Build spawn args — rely on env vars for config; CLI flags as defense in depth.
+    // portMax is not a serve flag; the child will scan ports starting from `port`.
+    // Port 0 means "auto-assign" — the CLI flag rejects 0, so rely on CESIUM_PORT=0 env var.
+    const spawnArgs: string[] = ["run", CLI_ENTRY, "serve", "--state-dir", stateDir];
+    if (port > 0) {
+      spawnArgs.push("--port", String(port));
+    }
+    // Pass idle timeout so the detached child self-terminates on inactivity.
+    // Serve command defaults to 0 (never) for foreground use; we override for daemon mode.
+    if (idleTimeoutMs > 0) {
+      spawnArgs.push("--idle-timeout", String(idleTimeoutMs));
+    }
+
+    const child = spawn("bun", spawnArgs, {
+      detached: true,
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        CESIUM_STATE_DIR: stateDir,
+        CESIUM_PORT: String(port),
+      },
+    });
+
+    // Unref so the parent can exit without waiting for the child
+    child.unref();
+
+    if (child.pid === undefined) {
+      throw new Error("cesium: failed to spawn server subprocess (no PID assigned)");
+    }
+  } finally {
+    // Release spawn lock immediately — the child needs to acquire its own lock
+    // (.server-start.lock via runServerForeground). Holding the spawn lock any
+    // longer would deadlock the child.
+    await spawnLock.release();
+  }
+
+  // Wait for the child to write its PID file and respond to HTTP.
+  // This polling happens OUTSIDE the spawn lock so the child can run freely.
+  const deadline = Date.now() + 10_000;
+  let lastError = "timeout";
+  let scheduleIdx = 0;
+
+  while (Date.now() < deadline) {
+    const waitMs = POLL_SCHEDULE[scheduleIdx] ?? 1000;
+    scheduleIdx = Math.min(scheduleIdx + 1, POLL_SCHEDULE.length - 1);
+    await sleep(waitMs);
+
+    const pidContent = readPidFile(pidFilePath);
+    if (pidContent !== null && isAlive(pidContent.pid)) {
+      const probeUrl = `http://${pidContent.hostname}:${pidContent.port}/`;
+      const alive = await httpProbe(probeUrl);
+      if (alive) {
+        return {
+          port: pidContent.port,
+          url: `http://${pidContent.hostname}:${pidContent.port}`,
+          pid: pidContent.pid,
+          startedAt: pidContent.startedAt,
+        };
+      }
+      lastError = `pid ${pidContent.pid} alive but not yet responding on port ${pidContent.port}`;
+    } else if (pidContent !== null) {
+      lastError = `pid ${pidContent.pid} in PID file is not alive`;
+    } else {
+      lastError = "PID file not yet written";
+    }
+  }
+
+  // Timeout — try to clean up the spawned process
+  const staleContent = readPidFile(pidFilePath);
+  if (staleContent !== null && isAlive(staleContent.pid)) {
+    try {
+      process.kill(staleContent.pid, "SIGTERM");
+    } catch {
+      // best-effort
+    }
+  }
+
+  throw new Error(
+    `cesium: timed out waiting for server to start in ${stateDir} (last: ${lastError})`,
+  );
+}
+
+// ─── Backward-compat alias ────────────────────────────────────────────────────
+// Internal callers have been updated to use runServerForeground or ensureServerRunning.
+// Keep ensureRunning exported for any external consumers that haven't migrated.
+
+export { runServerForeground as ensureRunning };
+
 // ─── Test reset hook ──────────────────────────────────────────────────────────
 // This function is intended for test use only. It clears module-level singleton
 // state, stops any running server, and removes signal/exit listeners.

package/src/tools/ask.ts

@@ -20,7 +20,7 @@ import { withLock } from "../storage/lock.ts";
 import { renderProjectIndex, renderGlobalIndex } from "../storage/index-gen.ts";
 import { buildProjectSummaries } from "../storage/project-summaries.ts";
 import {
-  ensureRunning as defaultEnsureRunning,
+  ensureServerRunning as defaultEnsureServerRunning,
   type RunningInfo,
   type LifecycleConfig,
 } from "../server/lifecycle.ts";
@@ -58,7 +58,7 @@ export function createAskTool(
   const resolveConfig = overrides?.loadConfig ?? loadConfig;
   const now = overrides?.now ?? (() => new Date());
   const genId = overrides?.nanoid ?? defaultNanoid;
-  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureRunning;
+  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureServerRunning;
 
   return tool({
     description: TOOL_DESCRIPTION,

package/src/tools/publish.ts

@@ -11,6 +11,7 @@ import { extractTextContent } from "../render/extract.ts";
 import { themeFromPreset, mergeTheme } from "../render/theme.ts";
 import { validatePublishInput, htmlBodyWarnings, PUBLISH_KINDS } from "../render/validate.ts";
 import { renderBlocks } from "../render/blocks/render.ts";
+import { resolveHighlightTheme } from "../render/blocks/highlight.ts";
 import { wrapDocument, type ArtifactMeta } from "../render/wrap.ts";
 import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
 import { atomicWrite, patchEmbeddedMetadata } from "../storage/write.ts";
@@ -27,7 +28,7 @@ import { withLock } from "../storage/lock.ts";
 import { renderProjectIndex, renderGlobalIndex } from "../storage/index-gen.ts";
 import { buildProjectSummaries } from "../storage/project-summaries.ts";
 import {
-  ensureRunning as defaultEnsureRunning,
+  ensureServerRunning as defaultEnsureServerRunning,
   type RunningInfo,
   type LifecycleConfig,
 } from "../server/lifecycle.ts";
@@ -106,7 +107,7 @@ export function createPublishTool(
   const resolveConfig = overrides?.loadConfig ?? loadConfig;
   const now = overrides?.now ?? (() => new Date());
   const genId = overrides?.nanoid ?? defaultNanoid;
-  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureRunning;
+  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureServerRunning;
 
   return tool({
     description: TOOL_DESCRIPTION,
@@ -193,7 +194,8 @@ export function createPublishTool(
 
       if (input.blocks !== undefined) {
         // Blocks path: render structured blocks → trusted HTML
-        bodyHtml = renderBlocks(input.blocks);
+        const highlightTheme = resolveHighlightTheme(config.themePreset);
+        bodyHtml = await renderBlocks(input.blocks, { highlightTheme });
       } else {
         // HTML path: scrub agent-supplied HTML
         const scrubbed = scrub(input.html);

package/src/tools/styleguide.ts

@@ -8,7 +8,7 @@ import type { RenderCtx, SectionCounter } from "../render/blocks/render.ts";
 
 function makeCtx(): RenderCtx {
   const counter: SectionCounter = { value: 1 };
-  return { sectionCounter: counter, depth: 0, path: "blocks[0]" };
+  return { sectionCounter: counter, depth: 0, path: "blocks[0]", highlightTheme: "claret-dark" };
 }
 
 /** Escape a string for safe insertion inside a markdown fenced code block. */
@@ -18,7 +18,7 @@ function escapeForCodeFence(s: string): string {
 }
 
 /** Generate the full markdown reference from the catalog. Deterministic — same catalog → same output. */
-export function generateStyleguideMarkdown(): string {
+export async function generateStyleguideMarkdown(): Promise<string> {
   const lines: string[] = [];
 
   lines.push("# Cesium publishing reference");
@@ -40,8 +40,26 @@ export function generateStyleguideMarkdown(): string {
   lines.push("## Block reference");
   lines.push("");
 
-  for (const blockType of blockTypes) {
+  // Pre-render all examples in parallel (order preserved via index)
+  const renderedExamples = await Promise.all(
+    blockTypes.map(async (blockType) => {
+      const entry = blockCatalog[blockType];
+      if (entry.renderedExample !== undefined) {
+        return entry.renderedExample;
+      }
+      try {
+        return await renderBlock(entry.example, makeCtx());
+      } catch {
+        return "";
+      }
+    }),
+  );
+
+  for (let i = 0; i < blockTypes.length; i++) {
+    const blockType = blockTypes[i];
+    if (blockType === undefined) continue;
     const entry = blockCatalog[blockType];
+    const rendered = renderedExamples[i] ?? "";
 
     lines.push(`### \`${entry.type}\``);
     lines.push("");
@@ -62,15 +80,6 @@ export function generateStyleguideMarkdown(): string {
     lines.push("```");
     lines.push("");
 
-    // Rendered HTML
-    const rendered = entry.renderedExample ?? (() => {
-      try {
-        return renderBlock(entry.example, makeCtx());
-      } catch {
-        return "";
-      }
-    })();
-
     if (rendered !== "") {
       lines.push("Renders to:");
       lines.push("");
@@ -117,7 +126,7 @@ export function createStyleguideTool(_ctx: PluginInput): ReturnType<typeof tool>
       "Returns the cesium HTML design system reference page (CSS classes with example usage). Call this once at the start of writing a complex artifact to internalize the available components.",
     args: {},
     async execute(_args, _context) {
-      return generateStyleguideMarkdown();
+      return await generateStyleguideMarkdown();
     },
   });
 }