@cfbender/cesium 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## v0.5.0 — 2026-05-12
+
+Block-mode refactor — `cesium_publish` now accepts a structured `blocks` array
+alongside the legacy `html` field. The server templates 15 block types from
+JSON; raw HTML stays available as a per-block escape hatch (`raw_html`,
+`diagram`). Framework CSS moves out of every artifact and into a single served
+`/theme.css`. Styleguide is generated from a catalog at request time.
+Critique is mode-aware. Expected savings on a balanced doc: roughly 2× output
+tokens, more on heavily structured artifacts.
+
+- **feat:** `cesium_publish({ blocks: Block[] })` — closed discriminated union
+  of 15 block types: `hero`, `tldr`, `section`, `prose`, `list`, `callout`,
+  `code`, `timeline`, `compare_table`, `risk_table`, `kv`, `pill_row`,
+  `divider`, `diagram`, `raw_html`. Mutually exclusive with `html`.
+- **feat:** Owned markdown subset (~80 lines, no dependency) for `prose`,
+  `tldr`, `callout`, list items, and table cells. Supports paragraphs, lists,
+  blockquotes, hr, hard breaks, `**bold**`, `*italic*`, `` `code` ``, local
+  links, and the safelisted inline tags `<kbd>`, `<span class="pill">`,
+  `<span class="tag">`.
+- **feat:** Sections recurse to depth 3; non-section children get auto-wrapped
+  in `<div class="card">` for visual consistency.
+- **feat:** `theme.css` served from `<state-dir>/theme.css` with a small
+  inline fallback (~8 lines) so standalone-opened `.html` files remain
+  readable. Existing artifacts (with full CSS inlined) are never rewritten and
+  stay self-contained.
+- **feat:** `cesium_styleguide` returns a markdown reference generated from
+  the block catalog at request time — schema, examples, and renderer can no
+  longer drift.
+- **feat:** `cesium_critique` is mode-aware. `html` mode adds a soft
+  `prefer-blocks` nag; `blocks` mode focuses on quality (raw-html overuse,
+  prose walls, missing tldr on long docs, table-shape, redundant raw_html,
+  nesting depth). Findings carry path tags like `blocks[2].children[1]`.
+- **feat:** Deep block validation walks the catalog schema per type. Returns
+  path-tagged errors with "did you mean" suggestions for common drift
+  (`label`→`k`, `value`→`v`, `description`→`text`, `med`→`medium`, etc.).
+- **feat:** System prompt fragment generated from the block catalog at plugin
+  load time — drift between schema and prompt is now physically impossible.
+- **feat:** `inputMode: "html" | "blocks"` recorded in artifact metadata and
+  surfaced as a small badge on index cards.
+- **feat:** Framework CSS extended with rules for every block-renderer
+  pattern: `dl.kv` (2-column grid), `.pill-row`, `.check-list`, `<hr
+  data-label>`, `figure.code`, timeline-item internals, `.lede`, plus
+  `.diagram svg text { fill: currentColor }` so SVGs inherit theme color.
+- **feat:** `escapeHtml` and `escapeAttr` throw a clear error on non-string
+  input instead of crashing inside `.replace()`.
+- **fix:** `ensureThemeCss` respects the configured `themePreset` (regression
+  introduced when the framework CSS was first extracted to a served file).
+- **fix:** `wait` test fixtures use relative timestamps so they don't go
+  stale.
+- **docs:** `AGENTS.md` updated with the new project layout, two-input-modes
+  architecture, catalog-as-source-of-truth, and softened CSS portability
+  invariant ("no external network resources; local `/theme.css` is allowed").
+
 ## v0.3.6 — 2026-05-11
 
 Adds a periodic-table-themed favicon for the cesium HTTP server.

package/README.md

@@ -9,10 +9,7 @@ on disk, instead of dumping markdown into the terminal. The browser becomes the
 reading surface; the terminal stays the control surface. Each artifact is a single
 `.html` file: portable, archivable, viewable offline, shareable as a URL over SSH.
 
-<video src="assets/cesium.mp4" autoplay loop muted playsinline width="720">
-  Demo video — see <a href="assets/cesium.mp4">assets/cesium.mp4</a> if it
-  doesn't play inline (some markdown viewers strip <code>&lt;video&gt;</code>).
-</video>
+https://github.com/user-attachments/assets/03fdf32a-c4d5-4819-84eb-d272178d35cb
 
 ## Examples
 
@@ -488,7 +485,7 @@ Cesium took inspiration from:
 - [@trq212's tweet](https://x.com/trq212/status/2052809885763747935) on
   letting agents respond with HTML instead of dumping markdown into the
   terminal — the seed idea for the whole project.
-- **Octto** — for the model of an agent that publishes a live, browser-served
+- [Octto](https://github.com/vtemian/octto) — for the model of an agent that publishes a live, browser-served
   surface alongside the terminal, rather than replacing it.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "license": "MIT",
   "author": "Cody Bender",

package/src/cli/commands/serve.ts

@@ -4,6 +4,7 @@ import { parseArgs } from "node:util";
 import { loadConfig, type CesiumConfig } from "../../config.ts";
 import { ensureRunning, stopRunning } from "../../server/lifecycle.ts";
 import { resolveDisplayHost } from "../../tools/publish.ts";
+import { themeFromPreset, mergeTheme } from "../../render/theme.ts";
 
 export interface ServeContext {
   stdout: { write: (s: string) => void };
@@ -160,12 +161,14 @@ 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({
       stateDir: effectiveCfg.stateDir,
       port: effectiveCfg.port,
       portMax: effectiveCfg.portMax,
       idleTimeoutMs: effectiveCfg.idleTimeoutMs,
       hostname: effectiveCfg.hostname,
+      theme,
     });
   } catch (err) {
     const e = err as Error;

package/src/index.ts

@@ -10,12 +10,15 @@ import { createWaitTool } from "./tools/wait.ts";
 import { createStyleguideTool } from "./tools/styleguide.ts";
 import { createCritiqueTool } from "./tools/critique.ts";
 import { createStopTool } from "./tools/stop.ts";
+import { generateBlockFieldReference } from "./prompt/field-reference.ts";
 
-const PROMPT_FRAGMENT = await readFile(
+const rawFragment = await readFile(
   join(dirname(fileURLToPath(import.meta.url)), "prompt/system-fragment.md"),
   "utf8",
 );
 
+const PROMPT_FRAGMENT = rawFragment.replace("{{BLOCK_FIELD_REFERENCE}}", generateBlockFieldReference());
+
 export const CesiumPlugin: Plugin = async (ctx): Promise<Hooks> => {
   return {
     tool: {

package/src/prompt/field-reference.ts

@@ -0,0 +1,94 @@
+// Generates a compact block field reference from the catalog.
+// Injected into the system-fragment at plugin load time via placeholder replacement.
+// src/prompt/field-reference.ts
+
+import { blockCatalog } from "../render/blocks/catalog.ts";
+import type { Block } from "../render/blocks/types.ts";
+
+// ─── Schema → compact field description ──────────────────────────────────────
+
+type SchemaNode = Record<string, unknown>;
+
+function formatFieldType(node: SchemaNode): string {
+  if ("const" in node) return `"${String(node["const"])}"`;
+  const type = node["type"] as string | undefined;
+  if (type === undefined) return "unknown";
+  if (type === "string") {
+    const enumVals = node["enum"] as string[] | undefined;
+    if (enumVals !== undefined) return enumVals.map((e) => `"${e}"`).join(" | ");
+    return "string";
+  }
+  if (type === "number") return "number";
+  if (type === "boolean") return "boolean";
+  if (type === "array") {
+    const items = node["items"] as SchemaNode | undefined;
+    if (items !== undefined) {
+      const innerType = items["type"] as string | undefined;
+      if (innerType === "object") {
+        const props = items["properties"] as Record<string, SchemaNode> | undefined;
+        const req = items["required"] as string[] | undefined;
+        if (props !== undefined) {
+          const fields = Object.entries(props)
+            .filter(([k]) => k !== "type")
+            .map(([k, v]) => {
+              const isRequired = req !== undefined && req.includes(k);
+              return `${k}${isRequired ? "" : "?"}: ${formatFieldType(v)}`;
+            })
+            .join(", ");
+          return `[{ ${fields} }]`;
+        }
+        return "object[]";
+      }
+      if (innerType === "string") return "string[]";
+      return `${innerType ?? "unknown"}[]`;
+    }
+    return "array";
+  }
+  if (type === "object") return "object";
+  return type;
+}
+
+function formatBlockLine(type: Block["type"]): string {
+  const entry = blockCatalog[type];
+  const schema = entry.schema as SchemaNode;
+  const props = schema["properties"] as Record<string, SchemaNode> | undefined;
+  const required = schema["required"] as string[] | undefined;
+
+  if (props === undefined) return `- \`${type}\``;
+
+  const fields = Object.entries(props)
+    .filter(([k]) => k !== "type")
+    .map(([k, v]) => {
+      const isRequired = required !== undefined && required.includes(k);
+      return `${k}${isRequired ? "" : "?"}: ${formatFieldType(v)}`;
+    })
+    .join(", ");
+
+  return `- \`${type}\` — ${fields}`;
+}
+
+/**
+ * Generates a compact markdown block field reference from the catalog.
+ * This is injected into system-fragment.md at the {{BLOCK_FIELD_REFERENCE}} placeholder.
+ */
+export function generateBlockFieldReference(): string {
+  const lines = [
+    "## Block field reference",
+    "",
+    "For full schemas with rendered examples, call `cesium_styleguide`. Exact field names:",
+    "",
+  ];
+
+  for (const type of Object.keys(blockCatalog) as Block["type"][]) {
+    lines.push(formatBlockLine(type));
+  }
+
+  lines.push("");
+  lines.push(
+    "All `markdown` fields support `**bold**`, `*italic*`, `` `code` ``, lists, blockquotes, " +
+    "and the safelisted inline tags `<kbd>`, `<span class=\"pill\">`, `<span class=\"tag\">`. " +
+    "External URLs in links render as plain text.",
+  );
+
+  return lines.join("\n");
+}

package/src/prompt/system-fragment.md

@@ -1,97 +1,88 @@
 # Cesium — beautiful HTML artifacts
 
+Cesium publishes beautiful self-contained artifacts to a local server you can open in a browser.
+
 You have access to six tools:
 
 - `cesium_publish` — write a substantive response as a self-contained HTML document
 - `cesium_ask` — publish an interactive Q&A artifact; returns `{ id, httpUrl, ... }`
 - `cesium_wait` — block until the user completes a `cesium_ask` artifact (polls disk)
-- `cesium_styleguide` — fetch the full HTML design system reference (call this before writing anything complex)
-- `cesium_critique` — analyze a draft body for design-system adherence; returns a 0-100 score and findings
+- `cesium_styleguide` — fetch the full block reference (call before writing anything complex)
+- `cesium_critique` — analyze a draft artifact; returns a 0-100 score and findings
 - `cesium_stop` — stop the running cesium HTTP server
 
-## When to publish (vs. reply in terminal)
-
-Publish when:
-
-- Your response would be ≥ 400 words
-- It contains a comparison, decision matrix, or multi-section plan/PRD/RFC
-- It is a code review with more than 3 findings
-- It is a design proposal, audit, post-mortem, or explainer
-- The user is likely to re-read, share, or come back to it
-
-Stay in terminal for:
-
-- Short factual answers
-- Status updates ("done", "running tests", "fixed")
-- Mid-tool-call chatter
-- Single-paragraph replies
-- Acknowledgements
-
-User overrides:
+## Two input modes
+
+`cesium_publish` accepts either `blocks: Block[]` (preferred) or `html: string` (escape valve). Provide exactly one.
+
+**Prefer `blocks`** for plans, reviews, reports, explainers, comparisons, audits, design docs. Blocks are token-efficient (no structural boilerplate), server-templated, and machine-checkable. Use `html` only when the whole document needs bespoke art-direction. For isolated bespoke regions, use `raw_html` or `diagram` blocks.
+
+### Example
+
+```json
+{ "title": "Migration Guide", "kind": "plan", "blocks": [
+  { "type": "hero", "eyebrow": "v2", "title": "Migration Guide",
+    "meta": [{ "k": "Status", "v": "Draft" }, { "k": "Owner", "v": "platform" }] },
+  { "type": "tldr", "markdown": "**Summary:** Update one import path and bump the SDK." },
+  { "type": "section", "title": "What Changed", "children": [
+    { "type": "prose", "markdown": "The `auth` module is now a standalone package." },
+    { "type": "callout", "variant": "warn", "markdown": "Change `sdk/auth` imports before upgrading." }
+  ]},
+  { "type": "risk_table", "rows": [
+    { "risk": "Missed imports", "likelihood": "medium", "impact": "high", "mitigation": "Run codemods." }
+  ]},
+  { "type": "timeline", "items": [
+    { "label": "Phase 1", "text": "Audit existing imports", "date": "2026-06-01" },
+    { "label": "Phase 2", "text": "Run migration script" }
+  ]}
+]}
+```
 
-- "/cesium", "publish this", "make me an HTML report" → publish
-- "in terminal", "just tell me", "don't make a doc" → don't publish
+## Quick block reference
 
-When uncertain: publish AND emit a 2-3 line terminal summary pointing at the doc. Cheap to over-publish, expensive to under-publish.
+Call `cesium_styleguide` for full schemas and rendered examples.
 
-## How to write the body
+- `hero` — page-title header (eyebrow, subtitle, meta pairs)
+- `tldr` — summary box; at most one per document
+- `section` — numbered section with child blocks (depth ≤ 3)
+- `prose` — free-form markdown; `list` — bullet/numbered/checklist
+- `callout` — aside with variant: note/warn/risk; `divider` — rule
+- `code` — fenced code with lang; `timeline` — milestone list
+- `compare_table` — comparison grid; `risk_table` — risk grid
+- `kv` — key-value pairs; `pill_row` — pill/tag chips
+- `diagram` — SVG/HTML visual (scrubbed)
+- `raw_html` — custom HTML escape hatch (scrubbed; add `purpose`)
 
-The `html` argument is body-only (no `<!doctype>`, `<html>`, `<head>`, `<body>` wrappers — the plugin adds them).
+{{BLOCK_FIELD_REFERENCE}}
 
-Use these classes (full reference via `cesium_styleguide`):
+## When to use raw_html / diagram
 
-- `.eyebrow` `.h-display` `.h-section` `.section-num`
-- `.card` `.tldr` `.callout` (`.note`/`.warn`/`.risk`)
-- `.code` (with `.kw` `.str` `.cm` `.fn` highlights)
-- `.timeline` `.diagram` `.compare-table` `.risk-table`
-- `.kbd` `.pill` `.tag`
+- `diagram` — SVG visualizations, bespoke layouts.
+- `raw_html` — anything no typed block covers. Critique flags overuse (>2 blocks or >30% of body characters).
 
-Inline `style="..."` and inline `<svg>` are encouraged for bespoke diagrams. NEVER reference external resources (no `<script src>`, no remote fonts, no CDN images).
+## When to publish (vs. reply in terminal)
 
-## Tone
+Publish when: ≥ 400 words; comparison/matrix/plan/PRD/RFC; code review with >3 findings; design proposal/audit/explainer; or the user will re-read or share it. Stay in terminal for short answers and status updates.
 
-Warm, considered, not flashy. Match the aesthetic of a thoughtful design document, not marketing material.
+User overrides: "/cesium" or "publish this" → publish; "in terminal" → don't.
 
 ## Self-check before publishing
 
-For substantial artifacts (plans, reviews, comparisons, explainers > 500 words),
-call `cesium_critique` with your draft body BEFORE calling `cesium_publish`. Act
-on warn-level findings; consider suggest-level. info-level is FYI.
-
-If critique reports score < 70, revise the body before publishing.
+Call `cesium_critique` before `cesium_publish` on substantive artifacts. Mode is auto-detected (pass `html` or `blocks`). Act on warn-level findings; consider suggest-level. If score < 70, revise.
 
 ## After publishing
 
-The tool returns URLs (file://, http://). Print a short 2-line terminal summary like:
-
-```
-Cesium · <Title> (<kind>)
-  http://localhost:3030/projects/.../...
-  file:///.../...html
-```
-
-Do not paste the full document content into the terminal after publishing.
-
-## Stopping the server
-
-If the user asks to stop, restart, or recycle the cesium server (e.g. after a
-config change), call `cesium_stop`. The next `cesium_publish` will lazy-start
-a fresh server with the latest config.
+Print a 2-line terminal summary: `Cesium · <Title> (<kind>)` + the HTTP URL. Do not paste the full document content into the terminal.
 
 ## Interactive Q&A: cesium_ask + cesium_wait
 
-When you need structured user input before producing a final artifact (design tradeoffs,
-plan branches, confirmation gates), publish an interactive artifact:
-
 1. `cesium_ask({ title, body, questions: [...] })` → returns `{ id, httpUrl, ... }`
 2. Print the terminalSummary so the user knows where to click.
 3. `cesium_wait({ id })` → blocks until user finishes (or 10-min timeout).
-4. Decide next step from `result.answers` — typically `cesium_publish` with the chosen path.
+4. Decide next step from `result.answers`.
 
-Question types: pick_one, pick_many, confirm, ask_text, slider, react. The artifact
-is a permanent record of the conversation; once answered, controls freeze into a static
-markup that captures the user's decisions. Set `optional: true` on an `ask_text` question
-to add a Skip button (useful for "anything else?"-type follow-ups).
+Question types: pick_one, pick_many, confirm, ask_text, slider, react. Set `optional: true` on an `ask_text` question to add a Skip button. Don't use cesium_ask for trivial yes/no questions — use it when the question deserves to live on disk as a decision record.
+
+## Stopping the server
 
-Don't use cesium_ask for trivial yes/no questions you can ask in the terminal. Use it
-when the question deserves to live on disk as a decision record.
+Call `cesium_stop` to stop or restart. The next `cesium_publish` will lazy-start a fresh server.

package/src/render/blocks/catalog.ts

@@ -0,0 +1,39 @@
+// Catalog — source of truth: aggregates meta from every renderer module.
+// src/render/blocks/catalog.ts
+
+import type { Block, BlockMeta } from "./types.ts";
+import { meta as heroMeta } from "./renderers/hero.ts";
+import { meta as tldrMeta } from "./renderers/tldr.ts";
+import { meta as sectionMeta } from "./renderers/section.ts";
+import { meta as proseMeta } from "./renderers/prose.ts";
+import { meta as listMeta } from "./renderers/list.ts";
+import { meta as calloutMeta } from "./renderers/callout.ts";
+import { meta as codeMeta } from "./renderers/code.ts";
+import { meta as timelineMeta } from "./renderers/timeline.ts";
+import { meta as compareTableMeta } from "./renderers/compare-table.ts";
+import { meta as riskTableMeta } from "./renderers/risk-table.ts";
+import { meta as kvMeta } from "./renderers/kv.ts";
+import { meta as pillRowMeta } from "./renderers/pill-row.ts";
+import { meta as dividerMeta } from "./renderers/divider.ts";
+import { meta as diagramMeta } from "./renderers/diagram.ts";
+import { meta as rawHtmlMeta } from "./renderers/raw-html.ts";
+
+export const blockCatalog: Record<Block["type"], BlockMeta> = {
+  hero: heroMeta,
+  tldr: tldrMeta,
+  section: sectionMeta,
+  prose: proseMeta,
+  list: listMeta,
+  callout: calloutMeta,
+  code: codeMeta,
+  timeline: timelineMeta,
+  compare_table: compareTableMeta,
+  risk_table: riskTableMeta,
+  kv: kvMeta,
+  pill_row: pillRowMeta,
+  divider: dividerMeta,
+  diagram: diagramMeta,
+  raw_html: rawHtmlMeta,
+};
+
+export const blockTypes = Object.keys(blockCatalog) as Array<Block["type"]>;

package/src/render/blocks/escape.ts

@@ -0,0 +1,27 @@
+// Pure HTML escape helpers — no dependencies.
+// src/render/blocks/escape.ts
+
+/** Escapes a string for safe insertion as HTML text content. */
+export function escapeHtml(s: string): string {
+  if (typeof s !== "string") {
+    throw new Error(`escapeHtml expected string, got ${typeof s}: ${String(s)}`);
+  }
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/** Escapes a string for safe insertion as an HTML attribute value (double-quoted). */
+export function escapeAttr(s: string): string {
+  if (typeof s !== "string") {
+    throw new Error(`escapeAttr expected string, got ${typeof s}: ${String(s)}`);
+  }
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/src/render/blocks/index.ts

@@ -0,0 +1,6 @@
+// Barrel — re-exports for the blocks module.
+// src/render/blocks/index.ts
+
+export type { Block, BlockMeta } from "./types.ts";
+export { renderBlocks } from "./render.ts";
+export { blockCatalog, blockTypes } from "./catalog.ts";