@cfbender/cesium 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## v0.6.2 — 2026-05-13
+
+Prompt fix. The `diff` block was missing from the agent-facing quick reference
+in `system-fragment.md` — only fifteen of the sixteen catalog blocks were
+surfaced — so agents would reach for `code` blocks with hand-rolled `+`/`-`
+lines when asked to walk through a diff or release. The `diff` block is now
+listed alongside `code`/`timeline`, and a short trigger note pairs "release
+walkthrough / version diff / before-after / refactor proposal" with the `diff`
+block explicitly.
+
+- **fix:** Add `diff` to the prompt's quick block reference.
+- **fix:** Add "When showing code changes" trigger paragraph.
+- **chore:** Bump the block-type enumeration tests from 15 → 16 to keep the
+  catalog and the human-curated reference in lockstep.
+
+No runtime or rendering changes; the `diff` block itself was already wired
+end-to-end since v0.4.
+
+## v0.6.1 — 2026-05-13
+
+Fixes a regression introduced by the v0.4 blocks refactor: the README's
+"self-contained HTML file" claim had quietly become false. Block-based
+artifacts (cards, callouts, compare-tables, timelines, code) rendered as
+broken-looking plain HTML when opened via `file://` because the inline
+fallback CSS only covered basic typography — all the block styling lived
+in the server-side `theme.css`. Sharing an artifact required either the
+running cesium server or a recipient who happened to have it.
+
+- **feat:** Artifacts now embed the full `theme.css` (~21KB) in an inline
+  `<style>` block at generation time. Opening any artifact via `file://`
+  or on any other machine now renders correctly with zero external
+  dependencies — typography, blocks, tables, controls, diff renderer, all
+  of it. The `<link rel="stylesheet" href=".../theme.css">` is preserved
+  so served artifacts still pick up live theme changes (the link rules
+  override the earlier inline `<style>` in cascade order).
+- **feat:** New `cesium export <id-prefix>` command emits an artifact's
+  self-contained HTML to stdout, or to `--out file.html`. Resolves the id
+  prefix against the global index the same way `cesium open` does. With
+  the baked-in CSS, export is now a near-trivial file copy — pipe it
+  anywhere, attach it to email, drop it in a chat, commit it to a repo.
+- **refactor:** Removed `src/render/fallback.ts` and the matching test
+  file. The 8-line fallback CSS it produced is no longer needed; the
+  inline `<style>` carries the full framework directly.
+- **chore:** README "Share an artifact" section now leads with
+  `cesium export` and explains the bake-and-override model.
+
+Old artifacts on disk are not retroactively re-baked — they keep their
+generation-time fallback + link, which means they continue to render
+fine when served by cesium but look plain when opened standalone.
+Historical fidelity is preserved. New artifacts written from v0.6.1
+onward are genuinely portable.
+
 ## v0.6.0 — 2026-05-13
 
 Internal cleanup release. Two hand-rolled server and CLI layers swapped

package/README.md

@@ -48,8 +48,8 @@ unreleased changes).
 ### CLI
 
 The CLI puts a `cesium` binary on your `PATH` for browsing, opening, and
-managing artifacts (`cesium ls`, `cesium open`, `cesium serve`, `cesium prune`,
-`cesium theme`).
+managing artifacts (`cesium ls`, `cesium open`, `cesium export`, `cesium serve`,
+`cesium prune`, `cesium theme`).
 
 **Recommended: install with [mise](https://mise.jdx.dev/)** so cesium is pinned
 in your config and tracks with the rest of your toolchain. Add to your
@@ -292,15 +292,24 @@ cesium open a7K9 --print  # just print the URL
 
 ### Share an artifact
 
-Each artifact is a single self-contained `.html` file — no external resources.
-Three ways to share:
+Each artifact is a single self-contained `.html` file — the full theme CSS is
+baked into a `<style>` tag at generation time, so it renders correctly when
+opened anywhere. Four ways to share:
 
+- **Pipe it anywhere** — `cesium export <id-prefix>` dumps the file to stdout;
+  `cesium export <id-prefix> --out plan.html` writes it to disk. The output
+  is a portable HTML file you can attach to email, drop in a chat, or commit
+  to a repo. Opens correctly with no server running.
 - **Same machine** — copy or attach the `file://` path printed in the terminal.
 - **Over SSH** — forward the port with `ssh -L 3030:localhost:3030 your-host`,
   then send the `http://localhost:3030/...` URL.
 - **On a trusted LAN** — set `"hostname": "0.0.0.0"` in `cesium.json` and share
   the LAN URL. Only do this on networks you trust.
 
+When an artifact is served by the cesium HTTP server, a `<link>` to the live
+`theme.css` overrides the baked-in `<style>` so theme changes apply retroactively
+to served pages. Standalone copies keep their generation-time look forever.
+
 ### Clean up old artifacts
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "keywords": [
     "agent",

package/src/cli/commands/export.ts

@@ -0,0 +1,143 @@
+// cesium export — emit an artifact's HTML to stdout (or a file).
+//
+// Because cesium artifacts are written with the full theme CSS baked into a
+// <style> tag at generation time, an artifact file on disk is already a
+// fully self-contained HTML document. Export is therefore a thin wrapper:
+// resolve by id-prefix, read the file, write to stdout or --out.
+//
+// (When served by the cesium HTTP server, the <link rel="stylesheet"
+// href=".../theme.css"> in the same artifact still loads and overrides the
+// baked CSS in cascade order, so live theme changes apply server-side. The
+// baked CSS only acts as the standalone fallback.)
+
+import { defineCommand } from "citty";
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { loadConfig, type CesiumConfig } from "../../config.ts";
+import { loadIndex } from "../../storage/index-cache.ts";
+import { pathsFor } from "../../storage/paths.ts";
+import { atomicWrite } from "../../storage/write.ts";
+
+export interface ExportArgs {
+  idPrefix: string;
+  out: string | null;
+}
+
+export interface ExportContext {
+  stdout: { write: (s: string) => void };
+  stderr: { write: (s: string) => void };
+  loadConfig?: () => CesiumConfig;
+}
+
+function defaultCtx(): ExportContext {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+  };
+}
+
+export async function runExport(
+  args: ExportArgs,
+  ctxOverride?: Partial<ExportContext>,
+): Promise<number> {
+  const ctx: ExportContext = { ...defaultCtx(), ...ctxOverride };
+
+  if (args.idPrefix.length === 0) {
+    ctx.stderr.write(`cesium export: missing required argument <id-prefix>\n`);
+    return 1;
+  }
+
+  const prefixLower = args.idPrefix.toLowerCase();
+  const cfg = (ctx.loadConfig ?? loadConfig)();
+
+  // Resolve artifact via global index (same matching as `open`)
+  const globalJsonPath = join(cfg.stateDir, "index.json");
+  let allEntries;
+  try {
+    allEntries = await loadIndex(globalJsonPath);
+  } catch (err) {
+    const e = err as Error;
+    ctx.stderr.write(`cesium export: failed to read index: ${e.message}\n`);
+    return 1;
+  }
+
+  const matches = allEntries.filter((e) => e.id.toLowerCase().startsWith(prefixLower));
+
+  if (matches.length === 0) {
+    ctx.stderr.write(`cesium export: no artifact found with id prefix "${args.idPrefix}"\n`);
+    return 1;
+  }
+
+  if (matches.length > 1) {
+    ctx.stderr.write(
+      `cesium export: ambiguous prefix "${args.idPrefix}" — ${matches.length} matches:\n`,
+    );
+    for (const m of matches) {
+      ctx.stderr.write(`  ${m.id}  ${m.title}  (${m.kind})\n`);
+    }
+    return 2;
+  }
+
+  const entry = matches[0];
+  if (entry === undefined) {
+    // Unreachable; satisfies type checker
+    ctx.stderr.write(`cesium export: internal error — no match\n`);
+    return 1;
+  }
+
+  const paths = pathsFor({
+    stateDir: cfg.stateDir,
+    projectSlug: entry.projectSlug,
+    filename: entry.filename,
+  });
+
+  let html: string;
+  try {
+    html = await readFile(paths.artifactPath, "utf8");
+  } catch (err) {
+    const e = err as Error;
+    ctx.stderr.write(`cesium export: failed to read artifact: ${e.message}\n`);
+    return 1;
+  }
+
+  if (args.out !== null) {
+    try {
+      await atomicWrite(args.out, html);
+    } catch (err) {
+      const e = err as Error;
+      ctx.stderr.write(`cesium export: failed to write ${args.out}: ${e.message}\n`);
+      return 1;
+    }
+    ctx.stderr.write(`Wrote ${args.out}\n`);
+    return 0;
+  }
+
+  ctx.stdout.write(html);
+  return 0;
+}
+
+export const exportCmd = defineCommand({
+  meta: {
+    name: "export",
+    description: "Emit an artifact's self-contained HTML to stdout (or --out file).",
+  },
+  args: {
+    idPrefix: {
+      type: "positional",
+      description: "Artifact id prefix (any unique substring of the id)",
+      required: true,
+    },
+    out: {
+      type: "string",
+      alias: "o",
+      description: "Write to this file path instead of stdout",
+    },
+  },
+  async run({ args }) {
+    const code = await runExport({
+      idPrefix: args.idPrefix,
+      out: args.out ?? null,
+    });
+    if (code !== 0) process.exit(code);
+  },
+});

package/src/cli/index.ts

@@ -14,6 +14,7 @@ const main = defineCommand({
   subCommands: {
     ls: () => import("./commands/ls.ts").then((m) => m.lsCmd),
     open: () => import("./commands/open.ts").then((m) => m.openCmd),
+    export: () => import("./commands/export.ts").then((m) => m.exportCmd),
     serve: () => import("./commands/serve.ts").then((m) => m.serveCmd),
     stop: () => import("./commands/stop.ts").then((m) => m.stopCmd),
     restart: () => import("./commands/restart.ts").then((m) => m.restartCmd),

package/src/prompt/system-fragment.md

@@ -78,11 +78,16 @@ Call `cesium_styleguide` for full schemas and rendered examples.
 - `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
+- `diff` — side-by-side before/after code with bezier connectors
 - `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`)
 
+## When showing code changes
+
+Showing what changed — release walkthroughs, version diffs, refactor proposals, before/after — use the `diff` block, not a `code` block with hand-rolled `+`/`-` lines. Pass either `patch` (unified diff) or both `before` and `after`. One `diff` block per file or hunk.
+
 {{BLOCK_FIELD_REFERENCE}}
 
 ## When to use raw_html / diagram

package/src/render/wrap.ts

@@ -1,7 +1,7 @@
 // Assembles the full <!doctype html> document from a body fragment + metadata.
 
 import { type ThemeTokens } from "./theme.ts";
-import { fallbackCss } from "./fallback.ts";
+import { buildThemeCss } from "../storage/theme-write.ts";
 import { renderControl, renderAnswered } from "./controls.ts";
 import { getClientJs } from "./client-js.ts";
 import { faviconLinkTag } from "./favicon.ts";
@@ -131,7 +131,7 @@ function renderFooter(meta: ArtifactMeta): string {
 }
 
 export function wrapDocument(opts: WrapOptions): string {
-  const { body, meta, warnings = [], interactive } = opts;
+  const { body, meta, theme, warnings = [], interactive } = opts;
   // Default href: artifact context (three levels deep from stateDir)
   const href =
     opts.themeCssHref === undefined
@@ -142,7 +142,12 @@ export function wrapDocument(opts: WrapOptions): string {
   // Suppress <link> when null is explicitly passed
   const suppressLink = opts.themeCssHref === null;
 
-  const fallback = fallbackCss();
+  // Bake the full theme CSS into every artifact so it's genuinely
+  // self-contained when opened standalone. When served by the cesium HTTP
+  // server, the <link> below still loads and overrides the inline rules in
+  // cascade order — so theme upgrades retroactively apply to served artifacts
+  // while standalone copies retain their generation-time look.
+  const themeCss = buildThemeCss(theme);
   // Embed interactive into the cesium-meta JSON block when present
   const metaPayload: Record<string, unknown> = { ...meta };
   if (interactive !== undefined) {
@@ -172,8 +177,7 @@ export function wrapDocument(opts: WrapOptions): string {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${titleEsc} · cesium</title>
-  <style>/* fallback — standalone-readable; full styles served from /theme.css */
-${fallback}</style>${linkTag}${faviconTag}
+  <style>${themeCss}</style>${linkTag}${faviconTag}
   <script type="application/json" id="cesium-meta">${metaJson}</script>
 </head>
 <body>

package/src/storage/index-gen.ts

@@ -3,7 +3,7 @@
 import type { IndexEntry } from "./index-cache.ts";
 import type { ThemeTokens } from "../render/theme.ts";
 import { faviconLinkTag, faviconEmblemSvg } from "../render/favicon.ts";
-import { fallbackCss } from "../render/fallback.ts";
+import { buildThemeCss } from "./theme-write.ts";
 
 export interface RenderProjectIndexArgs {
   projectSlug: string;
@@ -267,7 +267,7 @@ function renderEntryCard(entry: IndexEntry): string {
 // ─── renderProjectIndex ──────────────────────────────────────────────────────
 
 export function renderProjectIndex(args: RenderProjectIndexArgs): string {
-  const { projectSlug, projectName, entries } = args;
+  const { projectSlug, projectName, entries, theme } = args;
   const href =
     args.themeCssHref === undefined
       ? "../../theme.css"
@@ -276,7 +276,9 @@ export function renderProjectIndex(args: RenderProjectIndexArgs): string {
         : args.themeCssHref;
   const suppressLink = args.themeCssHref === null;
 
-  const fallback = fallbackCss();
+  // Bake the full theme CSS into the index so it's self-contained when opened
+  // standalone; the <link> below still loads and overrides when served.
+  const themeCss = buildThemeCss(theme);
   const iCss = indexCss();
   const iJs = indexJs();
 
@@ -359,8 +361,7 @@ ${cardsHtml}
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${esc(projectName)} · cesium</title>
-  <style>/* fallback — standalone-readable; full styles served from /theme.css */
-${fallback}${iCss}</style>${linkTag}${faviconTag}
+  <style>${themeCss}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">
@@ -381,7 +382,7 @@ ${fallback}${iCss}</style>${linkTag}${faviconTag}
 // ─── renderGlobalIndex ───────────────────────────────────────────────────────
 
 export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
-  const { projects } = args;
+  const { projects, theme } = args;
   const href =
     args.themeCssHref === undefined
       ? "theme.css"
@@ -390,7 +391,9 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
         : args.themeCssHref;
   const suppressLink = args.themeCssHref === null;
 
-  const fallback = fallbackCss();
+  // Bake the full theme CSS into the index so it's self-contained when opened
+  // standalone; the <link> below still loads and overrides when served.
+  const themeCss = buildThemeCss(theme);
   const iCss = indexCss();
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
@@ -447,8 +450,7 @@ 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>/* fallback — standalone-readable; full styles served from /theme.css */
-${fallback}${iCss}</style>${linkTag}${faviconTag}
+  <style>${themeCss}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">

package/src/render/fallback.ts

@@ -1,18 +0,0 @@
-// Minimal inline fallback CSS — ~8 lines, ≤500 bytes minified.
-// Goal: standalone .html files opened via file:// look "plain but readable,"
-// not broken. Full styling comes from the served /theme.css.
-
-/** Returns a compact CSS block covering typography, color tokens, and basic
- *  component borders. Used as the inline <style> fallback in every artifact.
- *  Budget: ≤500 bytes minified. */
-export function fallbackCss(): string {
-  return (
-    ":root{font-family:system-ui,sans-serif;line-height:1.6;}" +
-    "body{max-width:900px;margin:0 auto;padding:24px;}" +
-    "@media(prefers-color-scheme:dark){body{background:#180810;color:#ddd;}}" +
-    "pre,code{font-family:ui-monospace,monospace;font-size:.875em;}" +
-    ".card,.tldr{border:1.5px solid #ccc;border-radius:8px;padding:14px 18px;}" +
-    ".callout{border:1.5px solid #ccc;border-radius:6px;padding:12px 16px;}" +
-    "table{border-collapse:collapse;width:100%;}th,td{border:1px solid #ccc;padding:8px;}"
-  );
-}