@cfbender/cesium 0.5.0 → 0.5.2

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

@@ -0,0 +1,185 @@
+// 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/markdown.ts

@@ -11,8 +11,7 @@ import { escapeHtml, escapeAttr } from "./escape.ts";
 
 // ─── Safelist placeholder pass ───────────────────────────────────────────────
 
-const SAFELIST_RE =
-  /<(kbd)>(.*?)<\/kbd>|<span\s+class="(pill|tag)">(.*?)<\/span>/gi;
+const SAFELIST_RE = /<(kbd)>(.*?)<\/kbd>|<span\s+class="(pill|tag)">(.*?)<\/span>/gi;
 
 function extractSafelist(input: string): { text: string; map: Map<string, string> } {
   const map = new Map<string, string>();
@@ -72,7 +71,10 @@ function renderInline(text: string): string {
   // **bold**
   working = working.replace(/\*\*(.+?)\*\*/g, (_m, inner: string) => `<strong>${inner}</strong>`);
   // *italic* (not preceded by another *)
-  working = working.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, (_m, inner: string) => `<em>${inner}</em>`);
+  working = working.replace(
+    /(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g,
+    (_m, inner: string) => `<em>${inner}</em>`,
+  );
   // [text](href) — only relative/anchor hrefs; external → plain text
   working = working.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, linkText: string, href: string) => {
     if (RELATIVE_HREF_RE.test(href)) {
@@ -159,7 +161,11 @@ export function renderMarkdown(md: string): string {
     // Bullet list
     if (isBullet(line)) {
       const items: string[] = [];
-      while (i < lines.length && (isBullet(lines[i] ?? "") || (!isBlank(lines[i] ?? "") && /^[ \t]{2,}/.test(lines[i] ?? "")))) {
+      while (
+        i < lines.length &&
+        (isBullet(lines[i] ?? "") ||
+          (!isBlank(lines[i] ?? "") && /^[ \t]{2,}/.test(lines[i] ?? "")))
+      ) {
         const cur = lines[i] ?? "";
         if (isBullet(cur)) {
           items.push(renderInline(applyHardBreak(getBulletContent(cur))));
@@ -173,7 +179,11 @@ export function renderMarkdown(md: string): string {
     // Ordered list
     if (isOrdered(line)) {
       const items: string[] = [];
-      while (i < lines.length && (isOrdered(lines[i] ?? "") || (!isBlank(lines[i] ?? "") && /^[ \t]{2,}/.test(lines[i] ?? "")))) {
+      while (
+        i < lines.length &&
+        (isOrdered(lines[i] ?? "") ||
+          (!isBlank(lines[i] ?? "") && /^[ \t]{2,}/.test(lines[i] ?? "")))
+      ) {
         const cur = lines[i] ?? "";
         if (isOrdered(cur)) {
           items.push(renderInline(applyHardBreak(getOrderedContent(cur))));
@@ -187,7 +197,11 @@ export function renderMarkdown(md: string): string {
     // Blockquote
     if (isBlockquote(line)) {
       const bqLines: string[] = [];
-      while (i < lines.length && (isBlockquote(lines[i] ?? "") || (!isBlank(lines[i] ?? "") && !/^[-*]/.test(lines[i] ?? "")))) {
+      while (
+        i < lines.length &&
+        (isBlockquote(lines[i] ?? "") ||
+          (!isBlank(lines[i] ?? "") && !/^[-*]/.test(lines[i] ?? "")))
+      ) {
         const cur = lines[i] ?? "";
         if (isBlockquote(cur)) {
           bqLines.push(renderInline(applyHardBreak(getBlockquoteContent(cur))));
@@ -202,7 +216,14 @@ export function renderMarkdown(md: string): string {
 
     // Paragraph — collect until blank or block-level
     const paraLines: string[] = [];
-    while (i < lines.length && !isBlank(lines[i] ?? "") && !isHr(lines[i] ?? "") && !isBullet(lines[i] ?? "") && !isOrdered(lines[i] ?? "") && !isBlockquote(lines[i] ?? "")) {
+    while (
+      i < lines.length &&
+      !isBlank(lines[i] ?? "") &&
+      !isHr(lines[i] ?? "") &&
+      !isBullet(lines[i] ?? "") &&
+      !isOrdered(lines[i] ?? "") &&
+      !isBlockquote(lines[i] ?? "")
+    ) {
       paraLines.push(applyHardBreak(lines[i] ?? ""));
       i++;
     }

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";
@@ -17,6 +18,7 @@ import { renderPillRow } from "./renderers/pill-row.ts";
 import { renderDivider } from "./renderers/divider.ts";
 import { renderDiagram } from "./renderers/diagram.ts";
 import { renderRawHtml } from "./renderers/raw-html.ts";
+import { renderDiff } from "./renderers/diff.ts";
 
 /** Shared mutable counter — all section renderers increment this via the ctx ref. */
 export interface SectionCounter {
@@ -31,18 +33,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);
@@ -74,12 +79,17 @@ export function renderBlock(block: Block, ctx: RenderCtx): string {
       return renderDiagram(block, ctx);
     case "raw_html":
       return renderRawHtml(block, ctx);
+    case "diff":
+      return renderDiff(block, ctx);
   }
 }
 
 /** 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 +98,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,9 +15,8 @@ export function renderCode(block: CodeBlock, _ctx: RenderCtx): string {
     parts.push(`  <figcaption>${escapeHtml(captionText)}</figcaption>`);
   }
 
-  parts.push(
-    `  <pre><code class="lang-${escapeAttr(block.lang)}">${escapeHtml(block.code)}</code></pre>`,
-  );
+  const highlighted = await highlightCode(block.code, block.lang, ctx.highlightTheme);
+  parts.push(`  <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/compare-table.ts

@@ -8,9 +8,7 @@ import { escapeHtml } from "../escape.ts";
 import { renderMarkdown } from "../markdown.ts";
 
 export function renderCompareTable(block: CompareTableBlock, _ctx: RenderCtx): string {
-  const headerCells = block.headers
-    .map((h) => `      <th>${escapeHtml(h)}</th>`)
-    .join("\n");
+  const headerCells = block.headers.map((h) => `      <th>${escapeHtml(h)}</th>`).join("\n");
 
   const bodyRows = block.rows
     .map((row) => {
@@ -34,7 +32,8 @@ export function renderCompareTable(block: CompareTableBlock, _ctx: RenderCtx): s
 
 export const meta: BlockMeta = {
   type: "compare_table",
-  description: "Bordered comparison grid. Headers define columns; rows must have matching cell count.",
+  description:
+    "Bordered comparison grid. Headers define columns; rows must have matching cell count.",
   schema: {
     type: "object",
     properties: {

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

@@ -25,7 +25,7 @@ export function renderDiagram(block: DiagramBlock, _ctx: RenderCtx): string {
 export const meta: BlockMeta = {
   type: "diagram",
   description:
-    "Escape-hatch for inline SVG or bespoke HTML diagrams. Exactly one of svg or html required. Payload is scrubbed. For SVG, prefer fill=\"currentColor\" and stroke=\"currentColor\" so the diagram inherits the theme's text color. Use explicit colors only for emphasis (accents, warnings).",
+    'Escape-hatch for inline SVG or bespoke HTML diagrams. Exactly one of svg or html required. Payload is scrubbed. For SVG, prefer fill="currentColor" and stroke="currentColor" so the diagram inherits the theme\'s text color. Use explicit colors only for emphasis (accents, warnings).',
   schema: {
     type: "object",
     properties: {
@@ -35,10 +35,7 @@ export const meta: BlockMeta = {
       html: { type: "string" },
     },
     required: ["type"],
-    oneOf: [
-      { required: ["svg"] },
-      { required: ["html"] },
-    ],
+    oneOf: [{ required: ["svg"] }, { required: ["html"] }],
   },
   example: {
     type: "diagram",