@cfbender/cesium 0.4.0 → 0.5.1

package/src/server/lifecycle.ts

@@ -2,11 +2,16 @@
 
 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";
 import { createFaviconHandler } from "./favicon.ts";
+import { ensureThemeCss } from "../storage/assets.ts";
+import { defaultTheme, type ThemeTokens } from "../render/theme.ts";
 
 export interface LifecycleConfig {
   stateDir: string;
@@ -14,6 +19,7 @@ export interface LifecycleConfig {
   portMax: number; // upper bound (inclusive)
   idleTimeoutMs: number;
   hostname?: string; // default "127.0.0.1"
+  theme?: ThemeTokens; // default: defaultTheme()
 }
 
 export interface RunningInfo {
@@ -199,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" } = 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");
 
@@ -259,6 +276,9 @@ export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo>
     const handle = await tryBindPort(port);
     const boundPort = handle.port;
 
+    // Materialize theme.css before serving — self-heals on plugin upgrade
+    await ensureThemeCss(stateDir, theme);
+
     // Wire API handler before static file fallback
     handle.addHandler(createApiHandler({ stateDir }));
     // /favicon.ico shim — browsers auto-request this even when the page
@@ -304,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/storage/assets.ts

@@ -0,0 +1,66 @@
+// Materializes /theme.css in the state directory, atomically and idempotently.
+
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import {
+  frameworkRulesCss,
+  themeTokensCss,
+  defaultTheme,
+  type ThemeTokens,
+} from "../render/theme.ts";
+import { atomicWrite } from "./write.ts";
+import { readFile } from "node:fs/promises";
+
+/** Per-theme CSS cache: built CSS string keyed by theme content hash. */
+const cssCache = new Map<string, string>();
+
+/** Returns a stable cache key for a theme (hash of its JSON representation). */
+function themeKey(theme: ThemeTokens): string {
+  return createHash("sha256").update(JSON.stringify(theme)).digest("hex");
+}
+
+/** Build the full theme.css string for a given theme (tokens + framework rules). */
+function buildCss(theme: ThemeTokens): string {
+  const key = themeKey(theme);
+  const cached = cssCache.get(key);
+  if (cached !== undefined) return cached;
+  const css = themeTokensCss(theme) + "\n" + frameworkRulesCss();
+  cssCache.set(key, css);
+  return css;
+}
+
+/** Returns the absolute path to theme.css in stateDir. */
+export function themeCssAssetPath(stateDir: string): string {
+  return join(stateDir, "theme.css");
+}
+
+/**
+ * Writes <stateDir>/theme.css with the full framework CSS (tokens + rules)
+ * for the given theme, iff the on-disk file is missing or its content hash
+ * differs from the expected content.  Idempotent and self-healing on plugin
+ * upgrade or theme change.
+ *
+ * When called without a theme argument, falls back to defaultTheme() so
+ * existing call sites remain valid.
+ */
+export async function ensureThemeCss(
+  stateDir: string,
+  theme: ThemeTokens = defaultTheme(),
+): Promise<void> {
+  const dest = themeCssAssetPath(stateDir);
+  const bundledCss = buildCss(theme);
+  const bundledHash = createHash("sha256").update(bundledCss).digest("hex");
+
+  // Fast path: compare hash of existing file to expected hash.
+  try {
+    const existing = await readFile(dest, "utf8");
+    const existingHash = createHash("sha256").update(existing).digest("hex");
+    if (existingHash === bundledHash) {
+      return; // already up-to-date
+    }
+  } catch {
+    // ENOENT or unreadable — fall through to write
+  }
+
+  await atomicWrite(dest, bundledCss);
+}

package/src/storage/index-cache.ts

@@ -19,6 +19,7 @@ export interface IndexEntry {
   projectSlug: string;
   projectName: string;
   bodyText: string;
+  inputMode?: "html" | "blocks";
 }
 
 export async function loadIndex(jsonPath: string): Promise<IndexEntry[]> {

package/src/storage/index-gen.ts

@@ -2,8 +2,8 @@
 
 import type { IndexEntry } from "./index-cache.ts";
 import type { ThemeTokens } from "../render/theme.ts";
-import { frameworkRulesCss, themeTokensCss } from "../render/theme.ts";
 import { faviconLinkTag, faviconEmblemSvg } from "../render/favicon.ts";
+import { fallbackCss } from "../render/fallback.ts";
 
 export interface RenderProjectIndexArgs {
   projectSlug: string;
@@ -236,6 +236,9 @@ function indexJs(): string {
 function renderEntryCard(entry: IndexEntry): string {
   const isSuperseded = entry.supersededBy !== null ? "1" : "0";
   const kindPill = `<span class="pill">${esc(entry.kind)}</span>`;
+  const inputModeBadge = entry.inputMode !== undefined
+    ? ` <span class="tag">${esc(entry.inputMode)}</span>`
+    : "";
   const dateStr = `<span class="card-date">${esc(formatDate(entry.createdAt))}</span>`;
   const supersededBadge =
     entry.supersedes !== null
@@ -255,7 +258,7 @@ function renderEntryCard(entry: IndexEntry): string {
       : "";
 
   return `<div class="entry-card" data-card data-kind="${esc(entry.kind)}" data-title-lower="${esc(entry.title.toLowerCase())}" data-body-text="${esc(entry.bodyText.toLowerCase())}" data-superseded="${isSuperseded}">
-  <div class="card-top">${kindPill}${supersededBadge}${supersededByBadge}${dateStr}</div>
+  <div class="card-top">${kindPill}${inputModeBadge}${supersededBadge}${supersededByBadge}${dateStr}</div>
   <div class="card-title"><a href="artifacts/${esc(entry.filename)}">${esc(entry.title)}</a></div>
   ${summaryHtml}${tagsHtml}
   <div class="card-footer"><a class="open-link" href="artifacts/${esc(entry.filename)}">Open →</a></div>
@@ -265,7 +268,7 @@ function renderEntryCard(entry: IndexEntry): string {
 // ─── renderProjectIndex ──────────────────────────────────────────────────────
 
 export function renderProjectIndex(args: RenderProjectIndexArgs): string {
-  const { projectSlug, projectName, entries, theme } = args;
+  const { projectSlug, projectName, entries } = args;
   const href =
     args.themeCssHref === undefined
       ? "../../theme.css"
@@ -274,8 +277,7 @@ export function renderProjectIndex(args: RenderProjectIndexArgs): string {
         : args.themeCssHref;
   const suppressLink = args.themeCssHref === null;
 
-  const rules = frameworkRulesCss();
-  const tokens = themeTokensCss(theme);
+  const fallback = fallbackCss();
   const iCss = indexCss();
   const iJs = indexJs();
 
@@ -358,9 +360,8 @@ ${cardsHtml}
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${esc(projectName)} · cesium</title>
-  <style>${rules}
-/* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}${iCss}</style>${linkTag}${faviconTag}
+  <style>/* fallback — standalone-readable; full styles served from /theme.css */
+${fallback}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">
@@ -381,7 +382,7 @@ ${tokens}${iCss}</style>${linkTag}${faviconTag}
 // ─── renderGlobalIndex ───────────────────────────────────────────────────────
 
 export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
-  const { projects, theme } = args;
+  const { projects } = args;
   const href =
     args.themeCssHref === undefined
       ? "theme.css"
@@ -390,8 +391,7 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
         : args.themeCssHref;
   const suppressLink = args.themeCssHref === null;
 
-  const rules = frameworkRulesCss();
-  const tokens = themeTokensCss(theme);
+  const fallback = fallbackCss();
   const iCss = indexCss();
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
@@ -448,9 +448,8 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>All projects · cesium</title>
-  <style>${rules}
-/* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}${iCss}</style>${linkTag}${faviconTag}
+  <style>/* fallback — standalone-readable; full styles served from /theme.css */
+${fallback}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">

package/src/tools/ask.ts

@@ -13,14 +13,14 @@ import { wrapDocument, type ArtifactMeta } from "../render/wrap.ts";
 import type { InteractiveData } from "../render/validate.ts";
 import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
 import { atomicWrite } from "../storage/write.ts";
-import { writeThemeCss } from "../storage/theme-write.ts";
+import { ensureThemeCss } from "../storage/assets.ts";
 import { writeFaviconSvg } from "../storage/favicon-write.ts";
 import { loadIndex, writeIndex, appendEntry, type IndexEntry } from "../storage/index-cache.ts";
 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,
@@ -204,6 +204,7 @@ export function createAskTool(
         supersedes: null,
         supersededBy: null,
         contentSha256,
+        inputMode: "html",
       };
 
       // 12. Build interactive data
@@ -228,8 +229,8 @@ export function createAskTool(
       // 14. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
 
-      // 14a. Write theme.css + favicon.svg (idempotent, outside index lock — separate files)
-      await writeThemeCss(config.stateDir, theme);
+      // 14a. Ensure theme.css + favicon.svg (idempotent, outside index lock — separate files)
+      await ensureThemeCss(config.stateDir, theme);
       await writeFaviconSvg(config.stateDir);
 
       const fullHtml = wrapDocument({
@@ -309,6 +310,7 @@ export function createAskTool(
           portMax: config.portMax,
           idleTimeoutMs: config.idleTimeoutMs,
           hostname: config.hostname,
+          theme,
         });
         if (maybeInfo !== null) {
           serverInfo = maybeInfo;

package/src/tools/critique.ts

@@ -1,8 +1,15 @@
-// Tool handler for cesium_critique — runs the body analyzer and returns a human-readable report.
+// Tool handler for cesium_critique — mode-aware body analyzer.
+// Accepts either { html: string } (html mode) or { blocks: Block[] } (blocks mode). Exactly one required.
 
 import { tool } from "@opencode-ai/plugin";
 import type { PluginInput } from "@opencode-ai/plugin";
-import { critique, type CritiqueResult, type CritiqueSeverity } from "../render/critique.ts";
+import {
+  critiqueHtml,
+  critiqueBlocks,
+  type CritiqueResult,
+  type CritiqueSeverity,
+} from "../render/critique.ts";
+import type { Block } from "../render/blocks/types.ts";
 
 const TOOL_DESCRIPTION = `Analyze a draft HTML body for adherence to the cesium design
 system before publishing. Returns a 0-100 score and findings (warn/suggest/info).
@@ -18,6 +25,7 @@ HTML only, no <!doctype>/<html>/<head>/<body> wrappers.`;
  * Format a CritiqueResult into a concise human-readable string the agent can parse.
  * Format:
  *   score: 87/100
+ *   mode: html
  *
  *   warn:
  *   - [external-resource] External resource will be stripped...
@@ -29,7 +37,7 @@ HTML only, no <!doctype>/<html>/<head>/<body> wrappers.`;
  *   - [code-without-highlights] Code blocks render without...
  */
 export function formatCritiqueForAgent(result: CritiqueResult): string {
-  const lines: string[] = [`score: ${result.score}/100`];
+  const lines: string[] = [`score: ${result.score}/100`, `mode: ${result.mode}`];
 
   const bySeverity: Record<CritiqueSeverity, typeof result.findings> = {
     warn: [],
@@ -47,7 +55,8 @@ export function formatCritiqueForAgent(result: CritiqueResult): string {
     lines.push("");
     lines.push(`${sev}:`);
     for (const f of group) {
-      lines.push(`- [${f.code}] ${f.message}`);
+      const pathSuffix = f.path !== undefined ? ` (${f.path})` : "";
+      lines.push(`- [${f.code}] ${f.message}${pathSuffix}`);
     }
   }
 
@@ -57,9 +66,35 @@ export function formatCritiqueForAgent(result: CritiqueResult): string {
 export function createCritiqueTool(_ctx: PluginInput): ReturnType<typeof tool> {
   return tool({
     description: TOOL_DESCRIPTION,
-    args: { html: tool.schema.string() },
+    args: {
+      html: tool.schema.string().optional(),
+      blocks: tool.schema.any().optional(),
+    },
     async execute(args) {
-      const result = critique(args.html);
+      const hasHtml = args.html !== undefined && args.html !== null;
+      const hasBlocks = args.blocks !== undefined && args.blocks !== null;
+
+      if (hasHtml && hasBlocks) {
+        return "error: provide exactly one of html or blocks, not both";
+      }
+      if (!hasHtml && !hasBlocks) {
+        return "error: provide exactly one of html or blocks";
+      }
+
+      let result: CritiqueResult;
+
+      if (hasHtml) {
+        if (typeof args.html !== "string") {
+          return "error: html must be a string";
+        }
+        result = critiqueHtml(args.html);
+      } else {
+        if (!Array.isArray(args.blocks)) {
+          return "error: blocks must be an array";
+        }
+        result = critiqueBlocks(args.blocks as Block[]);
+      }
+
       return formatCritiqueForAgent(result);
     },
   });

package/src/tools/publish.ts

@@ -10,10 +10,12 @@ import { scrub } from "../render/scrub.ts";
 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";
-import { writeThemeCss } from "../storage/theme-write.ts";
+import { ensureThemeCss } from "../storage/assets.ts";
 import { writeFaviconSvg } from "../storage/favicon-write.ts";
 import {
   loadIndex,
@@ -26,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";
@@ -105,14 +107,25 @@ 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,
     args: {
       title: tool.schema.string(),
       kind: tool.schema.enum([...PUBLISH_KINDS] as [string, ...string[]]),
-      html: tool.schema.string(),
+      html: tool.schema
+        .string()
+        .optional()
+        .describe(
+          "Body HTML — escape valve / legacy mode. Provide exactly one of html or blocks.",
+        ),
+      blocks: tool.schema
+        .array(tool.schema.any())
+        .optional()
+        .describe(
+          "Structured block array — preferred for token efficiency. Provide exactly one of html or blocks.",
+        ),
       summary: tool.schema.string().optional(),
       tags: tool.schema.array(tool.schema.string()).optional(),
       supersedes: tool.schema.string().optional(),
@@ -174,11 +187,24 @@ export function createPublishTool(
       // 6. Timestamps
       const createdAt = now();
 
-      // 7. Scrub
-      const scrubbed = scrub(input.html);
+      // 7. Render body (blocks path or html path)
+      let bodyHtml: string;
+      let scrubRemovedCount = 0;
+      const inputMode: "html" | "blocks" = input.blocks !== undefined ? "blocks" : "html";
+
+      if (input.blocks !== undefined) {
+        // Blocks path: render structured blocks → trusted HTML
+        const highlightTheme = resolveHighlightTheme(config.themePreset);
+        bodyHtml = await renderBlocks(input.blocks, { highlightTheme });
+      } else {
+        // HTML path: scrub agent-supplied HTML
+        const scrubbed = scrub(input.html);
+        bodyHtml = scrubbed.html;
+        scrubRemovedCount = scrubbed.removed.length;
+      }
 
       // 7a. Extract body text for full-text search
-      const bodyText = extractTextContent(scrubbed.html);
+      const bodyText = extractTextContent(bodyHtml);
 
       // 8. Compute filename + paths
       const filename = artifactFilename({ title: input.title, id, createdAt });
@@ -189,7 +215,7 @@ export function createPublishTool(
       });
 
       // 9. Content SHA-256
-      const contentSha256 = createHash("sha256").update(scrubbed.html).digest("hex");
+      const contentSha256 = createHash("sha256").update(bodyHtml).digest("hex");
 
       // 10. Build ArtifactMeta
       const meta: ArtifactMeta = {
@@ -210,14 +236,15 @@ export function createPublishTool(
         supersedes: input.supersedes ?? null,
         supersededBy: null,
         contentSha256,
+        inputMode,
       };
 
       // 11. Build warnings
       const warnings: string[] = [];
-      if (scrubbed.removed.length > 0) {
-        warnings.push(`Removed ${scrubbed.removed.length} external resource(s) during scrub.`);
+      if (scrubRemovedCount > 0) {
+        warnings.push(`Removed ${scrubRemovedCount} external resource(s) during scrub.`);
       }
-      const bodyWarnings = htmlBodyWarnings(scrubbed.html);
+      const bodyWarnings = input.html !== undefined ? htmlBodyWarnings(bodyHtml) : [];
       for (const w of bodyWarnings) {
         warnings.push(w);
       }
@@ -225,12 +252,12 @@ export function createPublishTool(
       // 12. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
 
-      // 12a. Write theme.css + favicon.svg (idempotent, outside index lock — separate files)
-      await writeThemeCss(config.stateDir, theme);
+      // 12a. Ensure theme.css + favicon.svg (idempotent, outside index lock — separate files)
+      await ensureThemeCss(config.stateDir, theme);
       await writeFaviconSvg(config.stateDir);
 
       const fullHtml = wrapDocument({
-        body: scrubbed.html,
+        body: bodyHtml,
         meta,
         theme,
         warnings,
@@ -257,6 +284,7 @@ export function createPublishTool(
         projectSlug: identity.slug,
         projectName: identity.name,
         bodyText,
+        inputMode,
       };
 
       const lockPath = join(config.stateDir, ".index.lock");
@@ -336,6 +364,7 @@ export function createPublishTool(
           portMax: config.portMax,
           idleTimeoutMs: config.idleTimeoutMs,
           hostname: config.hostname,
+          theme,
         });
         if (maybeInfo !== null) {
           serverInfo = maybeInfo;