@cfbender/cesium 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## v0.5.2 — 2026-05-12
+
+A 16th block type — `diff` — that renders a beautiful side-by-side
+before/after code diff with curved SVG bezier connectors between the two
+columns. JetBrains diff-viewer aesthetic. Plus tooling improvements for
+hot-reload visual iteration during plugin development.
+
+- **feat:** New `diff` block type. Two input arms (XOR):
+  - `patch`: literal unified diff string (e.g. from `git diff` output)
+  - `before`/`after`: paired text strings; server runs Myers O(ND) line
+    diff to compute the change set
+- **feat:** Per-line shiki syntax highlighting is preserved through the
+  diff. The renderer recomposes before-side and after-side text, runs each
+  through `highlightCode`, then zips the styled line spans back into the
+  diff line list — so multi-line constructs (template strings, block
+  comments) tokenize correctly.
+- **feat:** Visual rendering:
+  - Three-column grid (1fr | 60px | 1fr) with line numbers per side
+  - Subtle red/green line-tint backgrounds on remove/add lines
+  - 60px-wide SVG connector column draws semi-transparent cubic-bezier
+    ribbons connecting each remove region on the left to the corresponding
+    add region on the right; pure adds collapse to a teardrop pointing
+    into the left, pure removes mirror
+  - Optional file-header strip with filename + `+N -M` stats
+  - Optional caption strip below
+  - 720px breakpoint collapses to single-column with connector hidden
+- **feat:** Theme tokens `--diff-add`, `--diff-remove`, `--diff-change`
+  added to all seven palette presets so colors fit each preset's character
+  (claret rose, warm clay, cool blue, etc.).
+- **fix:** Diff connector SVG now matches the `padding: 8px 0` of the
+  side columns so the bezier paths line up exactly with their target
+  regions instead of sitting 8px high.
+- **chore:** Project-local opencode config tracked: `.opencode/opencode.json`,
+  `.opencode/plugins/cesium.ts` (dev-loop shim that loads the working
+  tree's source instead of the published npm package), and
+  `.opencode/skills/cesium-preview/SKILL.md` (hot-reload visual iteration
+  workflow that bypasses the stale plugin host by importing render code
+  directly via bun and writing to /tmp).
+- **chore:** `scripts/dogfood-diff.ts` reference preview script for the
+  diff block. Useful template for previewing other block work.
+- **chore:** Apply oxfmt to 30 files that drifted out of format compliance
+  in v0.5.1 (no CI lint gate caught it). Pure cosmetic — line-wrapping,
+  italic style normalization, key ordering. No behavior changes.
+
 ## v0.5.1 — 2026-05-12
 
 Server-side syntax highlighting for `code` blocks via shiki, custom claret
@@ -10,11 +54,11 @@ 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
+  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).
+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
@@ -82,7 +126,7 @@ tokens, more on heavily structured artifacts.
   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
+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()`.

package/README.md

@@ -382,15 +382,15 @@ state directory, hostname, and theme settings flow through.
 
 Optional `~/.config/opencode/cesium.json`:
 
-| Key             | Type   | Default                 | Description                                                                              |
-| --------------- | ------ | ----------------------- | ---------------------------------------------------------------------------------------- |
-| `stateDir`      | string | `~/.local/state/cesium` | Where artifacts and indexes live                                                         |
-| `port`          | number | `3030`                  | First port to try for the local HTTP server                                              |
-| `portMax`       | number | `3050`                  | Upper bound when scanning for free ports                                                 |
-| `hostname`      | string | `127.0.0.1`             | Bind address. Use `0.0.0.0` to expose on the LAN                                         |
+| Key             | Type   | Default                 | Description                                                                                 |
+| --------------- | ------ | ----------------------- | ------------------------------------------------------------------------------------------- |
+| `stateDir`      | string | `~/.local/state/cesium` | Where artifacts and indexes live                                                            |
+| `port`          | number | `3030`                  | First port to try for the local HTTP server                                                 |
+| `portMax`       | number | `3050`                  | Upper bound when scanning for free ports                                                    |
+| `hostname`      | string | `127.0.0.1`             | Bind address. Use `0.0.0.0` to expose on the LAN                                            |
 | `idleTimeoutMs` | number | `1800000`               | Plugin server idle-shutdown threshold (30 min). Does not apply to foreground `cesium serve` |
-| `themePreset`   | string | `"claret-dark"`         | Named color palette (`claret-dark`/`claret-light`/`claret`/`warm`/`cool`/`mono`/`paper`) |
-| `theme`         | object | (claret-dark palette)   | Per-token color overrides (stacked on preset)                                            |
+| `themePreset`   | string | `"claret-dark"`         | Named color palette (`claret-dark`/`claret-light`/`claret`/`warm`/`cool`/`mono`/`paper`)    |
+| `theme`         | object | (claret-dark palette)   | Per-token color overrides (stacked on preset)                                               |
 
 Environment overrides: `CESIUM_PORT`, `CESIUM_STATE_DIR`, `CESIUM_HOSTNAME`, `CESIUM_THEME_PRESET`.
 

package/package.json

@@ -1,29 +1,27 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
-  "license": "MIT",
-  "author": "Cody Bender",
+  "keywords": [
+    "agent",
+    "artifact",
+    "claret",
+    "cli",
+    "html",
+    "opencode",
+    "plugin"
+  ],
   "homepage": "https://github.com/cfbender/cesium#readme",
   "bugs": "https://github.com/cfbender/cesium/issues",
+  "license": "MIT",
+  "author": "Cody Bender",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cfbender/cesium.git"
   },
-  "keywords": [
-    "opencode",
-    "agent",
-    "html",
-    "artifact",
-    "plugin",
-    "cli",
-    "claret"
-  ],
   "bin": {
     "cesium": "./src/cli/index.ts"
   },
-  "type": "module",
-  "main": "src/index.ts",
   "files": [
     "src",
     "assets/styleguide.html",
@@ -31,12 +29,11 @@
     "ARCHITECTURE.md",
     "CHANGELOG.md"
   ],
+  "type": "module",
+  "main": "src/index.ts",
   "publishConfig": {
     "access": "public"
   },
-  "engines": {
-    "bun": ">=1.0.0"
-  },
   "scripts": {
     "test": "bun test",
     "typecheck": "tsc --noEmit",
@@ -58,5 +55,8 @@
     "oxfmt": "^0.48.0",
     "oxlint": "^1.63.0",
     "typescript": "^5.4.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
   }
 }

package/src/cli/commands/serve.ts

@@ -41,8 +41,7 @@ function parseDuration(input: string): number | null {
   const n = parseFloat(match[1] ?? "");
   if (!isFinite(n) || n < 0) return null;
   const unit = match[2] ?? "ms";
-  const mul =
-    unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : /* h */ 3_600_000;
+  const mul = unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : /* h */ 3_600_000;
   return Math.floor(n * mul);
 }
 

package/src/index.ts

@@ -17,7 +17,10 @@ const rawFragment = await readFile(
   "utf8",
 );
 
-const PROMPT_FRAGMENT = rawFragment.replace("{{BLOCK_FIELD_REFERENCE}}", generateBlockFieldReference());
+const PROMPT_FRAGMENT = rawFragment.replace(
+  "{{BLOCK_FIELD_REFERENCE}}",
+  generateBlockFieldReference(),
+);
 
 export const CesiumPlugin: Plugin = async (ctx): Promise<Hooks> => {
   return {

package/src/prompt/field-reference.ts

@@ -86,8 +86,8 @@ export function generateBlockFieldReference(): string {
   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.",
+      '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

@@ -20,22 +20,52 @@ You have access to six tools:
 ### 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" }
-  ]}
-]}
+{
+  "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" }
+      ]
+    }
+  ]
+}
 ```
 
 ## Quick block reference

package/src/render/blocks/catalog.ts

@@ -17,6 +17,7 @@ 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";
+import { meta as diffMeta } from "./renderers/diff.ts";
 
 export const blockCatalog: Record<Block["type"], BlockMeta> = {
   hero: heroMeta,
@@ -34,6 +35,7 @@ export const blockCatalog: Record<Block["type"], BlockMeta> = {
   divider: dividerMeta,
   diagram: diagramMeta,
   raw_html: rawHtmlMeta,
+  diff: diffMeta,
 };
 
 export const blockTypes = Object.keys(blockCatalog) as Array<Block["type"]>;

package/src/render/blocks/diff/myers.ts

@@ -0,0 +1,221 @@
+// Myers O(ND) line-level diff algorithm.
+// src/render/blocks/diff/myers.ts
+//
+// Re-implemented from scratch — no external dependencies.
+// Reference: "An O(ND) Difference Algorithm and Its Variations" — Eugene W. Myers (1986).
+//
+// Implementation follows the standard "trace + backtrack" pattern from:
+// https://blog.jcoglan.com/2017/02/12/the-myers-diff-algorithm-part-1/
+
+import type { DiffLine } from "./parse-unified.ts";
+
+export type { DiffLine };
+
+/**
+ * Split a string into lines, trimming a single trailing empty element when the
+ * input ends with "\n" (so clean files don't produce a phantom blank final line).
+ */
+function splitLines(text: string): string[] {
+  if (text === "") return [];
+  const lines = text.split("\n");
+  // Trim trailing phantom empty line produced by a trailing newline
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines;
+}
+
+// ─── Myers forward pass ───────────────────────────────────────────────────────
+
+/**
+ * Run the Myers forward pass and return the trace (one v[] snapshot per d).
+ * v[k + offset] = furthest row reached on diagonal k at this step.
+ */
+function myersTrace(a: string[], b: string[]): number[][] {
+  const N = a.length;
+  const M = b.length;
+  const MAX = N + M;
+  const offset = MAX;
+
+  const v: number[] = Array.from({ length: 2 * MAX + 2 }, () => 0);
+  v[offset + 1] = 0;
+
+  const trace: number[][] = [];
+
+  for (let d = 0; d <= MAX; d++) {
+    for (let k = -d; k <= d; k += 2) {
+      const ki = k + offset;
+      const vKm1 = v[ki - 1] ?? 0;
+      const vKp1 = v[ki + 1] ?? 0;
+
+      let x: number;
+      if (k === -d || (k !== d && vKm1 < vKp1)) {
+        x = vKp1; // down: insert
+      } else {
+        x = vKm1 + 1; // right: delete
+      }
+
+      let y = x - k;
+
+      // Follow the diagonal (matches)
+      while (x < N && y < M && a[x] === b[y]) {
+        x++;
+        y++;
+      }
+
+      v[ki] = x;
+
+      if (x >= N && y >= M) {
+        trace.push(v.slice());
+        return trace;
+      }
+    }
+
+    trace.push(v.slice());
+  }
+
+  return trace;
+}
+
+// ─── Myers backtrack ──────────────────────────────────────────────────────────
+
+type Edit =
+  | { op: "keep"; aIdx: number; bIdx: number }
+  | { op: "delete"; aIdx: number }
+  | { op: "insert"; bIdx: number };
+
+/**
+ * Backtrack through the trace to produce the edit script.
+ * Reconstructs the path from (N, M) back to (0, 0).
+ */
+function backtrack(a: string[], b: string[], trace: number[][]): Edit[] {
+  const MAX = a.length + b.length;
+  const offset = MAX;
+  const edits: Edit[] = [];
+
+  let x = a.length;
+  let y = b.length;
+
+  // Walk backwards through d steps
+  for (let d = trace.length - 1; d > 0; d--) {
+    const vPrev = trace[d - 1] ?? [];
+    const k = x - y;
+    const ki = k + offset;
+
+    const vPrevKm1 = vPrev[ki - 1] ?? 0;
+    const vPrevKp1 = vPrev[ki + 1] ?? 0;
+
+    // Determine which diagonal we came from
+    let prevK: number;
+    if (k === -d || (k !== d && vPrevKm1 < vPrevKp1)) {
+      prevK = k + 1; // came via down (insert)
+    } else {
+      prevK = k - 1; // came via right (delete)
+    }
+
+    const prevX = vPrev[prevK + offset] ?? 0;
+    const prevY = prevX - prevK;
+
+    // Retrace the snake (diagonal matches) from (prevX, prevY) to (x, y)
+    // but skip the single edit step itself.
+    // After the edit step, we were at:
+    //   insert: (prevX, prevY + 1)
+    //   delete: (prevX + 1, prevY)
+    if (prevK === k + 1) {
+      // insert: moved down, x stays same, y += 1
+      const snakeX = prevX;
+      // snake goes from (snakeX, prevY+1) to (x, y)
+      for (let sx = x - 1; sx >= snakeX; sx--) {
+        const sy = sx - k;
+        edits.push({ op: "keep", aIdx: sx, bIdx: sy });
+      }
+      edits.push({ op: "insert", bIdx: prevY });
+    } else {
+      // delete: moved right, x += 1, y stays same
+      const snakeX = prevX + 1;
+      // snake goes from (snakeX, prevY) to (x, y)
+      for (let sx = x - 1; sx >= snakeX; sx--) {
+        const sy = sx - k;
+        edits.push({ op: "keep", aIdx: sx, bIdx: sy });
+      }
+      edits.push({ op: "delete", aIdx: prevX });
+    }
+
+    x = prevX;
+    y = prevY;
+  }
+
+  // Remaining snake at d=0: (0,0) to (x,y)
+  for (let sx = x - 1; sx >= 0; sx--) {
+    const sy = sx; // k=0 at the start
+    edits.push({ op: "keep", aIdx: sx, bIdx: sy });
+  }
+
+  edits.reverse();
+  return edits;
+}
+
+function myersDiff(a: string[], b: string[]): Edit[] {
+  if (a.length === 0 && b.length === 0) return [];
+  if (a.length === 0) return b.map((_, i) => ({ op: "insert" as const, bIdx: i }));
+  if (b.length === 0) return a.map((_, i) => ({ op: "delete" as const, aIdx: i }));
+
+  const trace = myersTrace(a, b);
+  return backtrack(a, b, trace);
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Compute a line-level diff between two text strings.
+ * Returns a flat DiffLine[] with 1-indexed line numbers per side.
+ * No hunk-sep entries — single contiguous diff.
+ */
+export function diffLines(before: string, after: string): DiffLine[] {
+  const aLines = splitLines(before);
+  const bLines = splitLines(after);
+
+  const edits = myersDiff(aLines, bLines);
+
+  let beforeLine = 1;
+  let afterLine = 1;
+
+  return edits.map((edit): DiffLine => {
+    switch (edit.op) {
+      case "keep": {
+        const text = aLines[edit.aIdx] ?? "";
+        const entry: DiffLine = {
+          kind: "context",
+          text,
+          beforeLineNum: beforeLine,
+          afterLineNum: afterLine,
+        };
+        beforeLine++;
+        afterLine++;
+        return entry;
+      }
+      case "delete": {
+        const text = aLines[edit.aIdx] ?? "";
+        const entry: DiffLine = {
+          kind: "remove",
+          text,
+          beforeLineNum: beforeLine,
+          afterLineNum: null,
+        };
+        beforeLine++;
+        return entry;
+      }
+      case "insert": {
+        const text = bLines[edit.bIdx] ?? "";
+        const entry: DiffLine = {
+          kind: "add",
+          text,
+          beforeLineNum: null,
+          afterLineNum: afterLine,
+        };
+        afterLine++;
+        return entry;
+      }
+    }
+  });
+}

package/src/render/blocks/diff/parse-unified.ts

@@ -0,0 +1,101 @@
+// Unified diff parser — converts a unified patch string to a DiffEntry[].
+// src/render/blocks/diff/parse-unified.ts
+
+export type DiffLine = {
+  kind: "context" | "add" | "remove";
+  text: string; // raw text, no leading +/- prefix
+  beforeLineNum: number | null; // 1-indexed line in "before" file, null for adds
+  afterLineNum: number | null; // 1-indexed line in "after" file, null for removes
+};
+
+export type DiffEntry = DiffLine | { kind: "hunk-sep"; oldStart: number; newStart: number };
+
+// Matches: @@ -<oldStart>[,<oldLines>] +<newStart>[,<newLines>] @@
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+
+/**
+ * Parse a unified diff patch string into a DiffEntry[].
+ * Returns null if no hunk header is found (caller falls back to plaintext).
+ */
+export function parseUnifiedDiff(patch: string): DiffEntry[] | null {
+  const lines = patch.split("\n");
+  const result: DiffEntry[] = [];
+  let foundHunk = false;
+  let firstHunk = true;
+
+  // Counters for current hunk position
+  let beforeLine = 0;
+  let afterLine = 0;
+
+  for (const line of lines) {
+    // Skip file header lines (--- / +++ at the very top)
+    if (line.startsWith("--- ") || line.startsWith("+++ ")) {
+      continue;
+    }
+
+    // Check for hunk header
+    const hunkMatch = HUNK_HEADER.exec(line);
+    if (hunkMatch !== null) {
+      const oldStart = parseInt(hunkMatch[1] ?? "1", 10);
+      const newStart = parseInt(hunkMatch[3] ?? "1", 10);
+
+      if (!firstHunk) {
+        // Emit hunk separator between hunks
+        result.push({ kind: "hunk-sep", oldStart, newStart });
+      }
+      firstHunk = false;
+      foundHunk = true;
+
+      beforeLine = oldStart;
+      afterLine = newStart;
+      continue;
+    }
+
+    if (!foundHunk) {
+      // Haven't seen a hunk header yet — skip pre-header lines
+      continue;
+    }
+
+    // Skip "" markers
+    if (line.startsWith("\\")) {
+      continue;
+    }
+
+    const prefix = line[0];
+    const text = line.slice(1);
+
+    if (prefix === " ") {
+      // Context line — appears on both sides
+      result.push({
+        kind: "context",
+        text,
+        beforeLineNum: beforeLine,
+        afterLineNum: afterLine,
+      });
+      beforeLine++;
+      afterLine++;
+    } else if (prefix === "-") {
+      // Removed line — only in "before"
+      result.push({
+        kind: "remove",
+        text,
+        beforeLineNum: beforeLine,
+        afterLineNum: null,
+      });
+      beforeLine++;
+    } else if (prefix === "+") {
+      // Added line — only in "after"
+      result.push({
+        kind: "add",
+        text,
+        beforeLineNum: null,
+        afterLineNum: afterLine,
+      });
+      afterLine++;
+    }
+    // Any other prefix: skip (e.g. empty lines after hunk body)
+  }
+
+  if (!foundHunk) return null;
+  return result;
+}

package/src/render/blocks/highlight.ts

@@ -13,11 +13,7 @@ import { THEME_PRESETS, isThemePresetName } from "../../render/theme.ts";
 
 // ─── Highlight theme type ─────────────────────────────────────────────────────
 
-export type HighlightTheme =
-  | "claret-dark"
-  | "claret-light"
-  | "vitesse-dark"
-  | "vitesse-light";
+export type HighlightTheme = "claret-dark" | "claret-light" | "vitesse-dark" | "vitesse-light";
 
 // ─── Supported languages ─────────────────────────────────────────────────────
 
@@ -88,12 +84,13 @@ export function resolveHighlightTheme(cesiumThemeName: string | undefined): High
  */
 function isHexDark(hex: string): boolean {
   const clean = hex.replace("#", "");
-  const full = clean.length === 3
-    ? clean
-        .split("")
-        .map((c) => c + c)
-        .join("")
-    : clean;
+  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);