@cfbender/cesium 0.4.0 → 0.5.1

package/src/render/blocks/highlight.ts

@@ -0,0 +1,188 @@
+// 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/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";

package/src/render/blocks/markdown.ts

@@ -0,0 +1,217 @@
+// Owned markdown subset — no external dependencies.
+// src/render/blocks/markdown.ts
+//
+// Block-level: paragraph, bullet list (- ), ordered list (1. ),
+//   blockquote (> ), horizontal rule (---), hard break (two-space EOL).
+// Inline: **bold**, *italic*, `code`, [text](href) — external hrefs → plain text.
+// HTML safelist: <kbd>, <span class="pill">, <span class="tag">.
+//   Everything else is HTML-escaped.
+
+import { escapeHtml, escapeAttr } from "./escape.ts";
+
+// ─── Safelist placeholder pass ───────────────────────────────────────────────
+
+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>();
+  let counter = 0;
+  const text = input.replace(SAFELIST_RE, (...args: unknown[]) => {
+    // args: [fullMatch, kbdTag, kbdContent, spanClass, spanContent, offset, string]
+    const full = args[0] as string;
+    const kbdTag = args[1] as string | undefined;
+    const kbdContent = args[2] as string | undefined;
+    const spanClass = args[3] as string | undefined;
+    const spanContent = args[4] as string | undefined;
+
+    let html: string;
+    if (kbdTag !== undefined && kbdContent !== undefined) {
+      html = `<kbd>${escapeHtml(kbdContent)}</kbd>`;
+    } else if (spanClass !== undefined && spanContent !== undefined) {
+      html = `<span class="${escapeAttr(spanClass)}">${escapeHtml(spanContent)}</span>`;
+    } else {
+      // Shouldn't happen, but fall back to escaping the whole match
+      html = escapeHtml(full);
+    }
+
+    const id = `\x00SAFE${counter++}\x00`;
+    map.set(id, html);
+    return id;
+  });
+  return { text, map };
+}
+
+function restoreSafelist(html: string, map: Map<string, string>): string {
+  let result = html;
+  for (const [id, replacement] of map) {
+    result = result.split(id).join(replacement);
+  }
+  return result;
+}
+
+// ─── Inline rendering ────────────────────────────────────────────────────────
+
+const RELATIVE_HREF_RE = /^([/#]|[^:/?#]*[/?#]|[^:/?#]+$)/;
+
+function renderInline(text: string): string {
+  // Step 1: extract inline code spans before any escaping
+  const codeMap = new Map<string, string>();
+  let codeCounter = 0;
+  let working = text.replace(/`([^`]+)`/g, (_m, inner: string) => {
+    const id = `\x00CODE${codeCounter++}\x00`;
+    codeMap.set(id, `<code>${escapeHtml(inner)}</code>`);
+    return id;
+  });
+
+  // Step 2: escape remaining HTML
+  working = working.replace(/&/g, "&amp;");
+  working = working.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+  // Step 3: process other inline patterns
+  // **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>`);
+  // [text](href) — only relative/anchor hrefs; external → plain text
+  working = working.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, linkText: string, href: string) => {
+    if (RELATIVE_HREF_RE.test(href)) {
+      return `<a href="${escapeAttr(href)}">${linkText}</a>`;
+    }
+    return linkText;
+  });
+
+  // Step 4: restore code spans and hard break placeholders
+  for (const [id, html] of codeMap) {
+    working = working.split(id).join(html);
+  }
+  working = working.split(HARD_BREAK_PLACEHOLDER).join("<br>");
+
+  return working;
+}
+
+// ─── Block-level rendering ───────────────────────────────────────────────────
+
+type Line = string;
+
+function isHr(line: Line): boolean {
+  return /^-{3,}\s*$/.test(line) || /^\*{3,}\s*$/.test(line) || /^_{3,}\s*$/.test(line);
+}
+
+function isBullet(line: Line): boolean {
+  return /^[ \t]*[-*+]\s+/.test(line);
+}
+
+function isOrdered(line: Line): boolean {
+  return /^[ \t]*\d+\.\s+/.test(line);
+}
+
+function isBlockquote(line: Line): boolean {
+  return /^[ \t]*>\s?/.test(line);
+}
+
+function isBlank(line: Line): boolean {
+  return line.trim() === "";
+}
+
+function getBulletContent(line: Line): string {
+  return line.replace(/^[ \t]*[-*+]\s+/, "");
+}
+
+function getOrderedContent(line: Line): string {
+  return line.replace(/^[ \t]*\d+\.\s+/, "");
+}
+
+function getBlockquoteContent(line: Line): string {
+  return line.replace(/^[ \t]*>\s?/, "");
+}
+
+/** Applies hard-break rule: line ending with two spaces → placeholder, restored after escaping */
+const HARD_BREAK_PLACEHOLDER = "\x00BR\x00";
+
+function applyHardBreak(line: string): string {
+  if (line.endsWith("  ")) {
+    return line.slice(0, -2) + HARD_BREAK_PLACEHOLDER;
+  }
+  return line;
+}
+
+export function renderMarkdown(md: string): string {
+  const { text: safeText, map: safeMap } = extractSafelist(md);
+  const lines = safeText.split("\n");
+  const parts: string[] = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+
+    if (isBlank(line)) {
+      i++;
+      continue;
+    }
+
+    if (isHr(line)) {
+      parts.push("<hr>");
+      i++;
+      continue;
+    }
+
+    // Bullet list
+    if (isBullet(line)) {
+      const items: string[] = [];
+      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))));
+        }
+        i++;
+      }
+      parts.push(`<ul>\n${items.map((it) => `  <li>${it}</li>`).join("\n")}\n</ul>`);
+      continue;
+    }
+
+    // Ordered list
+    if (isOrdered(line)) {
+      const items: string[] = [];
+      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))));
+        }
+        i++;
+      }
+      parts.push(`<ol>\n${items.map((it) => `  <li>${it}</li>`).join("\n")}\n</ol>`);
+      continue;
+    }
+
+    // Blockquote
+    if (isBlockquote(line)) {
+      const bqLines: string[] = [];
+      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))));
+        } else {
+          bqLines.push(renderInline(applyHardBreak(cur)));
+        }
+        i++;
+      }
+      parts.push(`<blockquote>${bqLines.join("<br>")}</blockquote>`);
+      continue;
+    }
+
+    // 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] ?? "")) {
+      paraLines.push(applyHardBreak(lines[i] ?? ""));
+      i++;
+    }
+    if (paraLines.length > 0) {
+      const inner = paraLines.map((l) => renderInline(l)).join("\n");
+      parts.push(`<p>${inner}</p>`);
+    }
+  }
+
+  const result = parts.join("\n");
+  return restoreSafelist(result, safeMap);
+}

package/src/render/blocks/render.ts

@@ -0,0 +1,104 @@
+// Block tree walker and dispatcher.
+// 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";
+import { renderProse } from "./renderers/prose.ts";
+import { renderList } from "./renderers/list.ts";
+import { renderCallout } from "./renderers/callout.ts";
+import { renderCode } from "./renderers/code.ts";
+import { renderTimeline } from "./renderers/timeline.ts";
+import { renderCompareTable } from "./renderers/compare-table.ts";
+import { renderRiskTable } from "./renderers/risk-table.ts";
+import { renderKv } from "./renderers/kv.ts";
+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";
+
+/** Shared mutable counter — all section renderers increment this via the ctx ref. */
+export interface SectionCounter {
+  value: number;
+}
+
+/** Shared render context threaded through the tree walk. */
+export interface RenderCtx {
+  /** Shared auto-incrementing section counter (1-based). Mutable ref. */
+  sectionCounter: SectionCounter;
+  /** Current nesting depth (root = 0, inside section = 1, etc.). */
+  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(highlightTheme: HighlightTheme = "claret-dark"): RenderCtx {
+  return {
+    sectionCounter: { value: 1 },
+    depth: 0,
+    path: "blocks",
+    highlightTheme,
+  };
+}
+
+/** Dispatch a single block to its renderer. */
+export async function renderBlock(block: Block, ctx: RenderCtx): Promise<string> {
+  switch (block.type) {
+    case "hero":
+      return renderHero(block, ctx);
+    case "tldr":
+      return renderTldr(block, ctx);
+    case "section":
+      return renderSection(block, ctx);
+    case "prose":
+      return renderProse(block, ctx);
+    case "list":
+      return renderList(block, ctx);
+    case "callout":
+      return renderCallout(block, ctx);
+    case "code":
+      return renderCode(block, ctx);
+    case "timeline":
+      return renderTimeline(block, ctx);
+    case "compare_table":
+      return renderCompareTable(block, ctx);
+    case "risk_table":
+      return renderRiskTable(block, ctx);
+    case "kv":
+      return renderKv(block, ctx);
+    case "pill_row":
+      return renderPillRow(block, ctx);
+    case "divider":
+      return renderDivider(block, ctx);
+    case "diagram":
+      return renderDiagram(block, ctx);
+    case "raw_html":
+      return renderRawHtml(block, ctx);
+  }
+}
+
+/** Render an array of blocks, returning the concatenated HTML body string. */
+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];
+    if (block === undefined) continue;
+    const blockCtx: RenderCtx = {
+      ...ctx,
+      path: `blocks[${i}]`,
+    };
+    // 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;
+  return parts.join("\n");
+}

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

@@ -0,0 +1,38 @@
+// Callout block renderer.
+// src/render/blocks/renderers/callout.ts
+
+import type { CalloutBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { escapeHtml } from "../escape.ts";
+import { renderMarkdown } from "../markdown.ts";
+
+export function renderCallout(block: CalloutBlock, _ctx: RenderCtx): string {
+  const titleHtml =
+    block.title !== undefined && block.title !== ""
+      ? `<strong>${escapeHtml(block.title)}</strong> `
+      : "";
+  const contentHtml = renderMarkdown(block.markdown);
+  return `<aside class="callout ${block.variant}">\n${titleHtml}${contentHtml}\n</aside>`;
+}
+
+export const meta: BlockMeta = {
+  type: "callout",
+  description: "Highlighted aside with variant styling. Variants: note, warn, risk.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "callout" },
+      variant: { type: "string", enum: ["note", "warn", "risk"] },
+      title: { type: "string" },
+      markdown: { type: "string" },
+    },
+    required: ["type", "variant", "markdown"],
+  },
+  example: {
+    type: "callout",
+    variant: "warn",
+    title: "Breaking Change",
+    markdown: "This change removes the `html` fallback path. Migrate to `blocks` before upgrading.",
+  },
+};

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

@@ -0,0 +1,46 @@
+// 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 async function renderCode(block: CodeBlock, ctx: RenderCtx): Promise<string> {
+  const parts: string[] = [];
+
+  const captionText = block.filename ?? block.caption;
+  if (captionText !== undefined && captionText !== "") {
+    parts.push(`  <figcaption>${escapeHtml(captionText)}</figcaption>`);
+  }
+
+  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>`;
+}
+
+export const meta: BlockMeta = {
+  type: "code",
+  description: "Code block with syntax language label and optional filename/caption.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "code" },
+      lang: { type: "string" },
+      code: { type: "string" },
+      filename: { type: "string" },
+      caption: { type: "string" },
+    },
+    required: ["type", "lang", "code"],
+  },
+  example: {
+    type: "code",
+    lang: "typescript",
+    filename: "src/index.ts",
+    code: 'import { createPublishTool } from "./tools/publish.ts";\nexport { createPublishTool };',
+  },
+};

package/src/render/blocks/renderers/compare-table.ts

@@ -0,0 +1,56 @@
+// CompareTable block renderer.
+// src/render/blocks/renderers/compare-table.ts
+
+import type { CompareTableBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+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 bodyRows = block.rows
+    .map((row) => {
+      const cells = row
+        .map((cell) => {
+          const content = renderMarkdown(cell).replace(/^<p>|<\/p>$/g, "");
+          return `      <td>${content}</td>`;
+        })
+        .join("\n");
+      return `    <tr>\n${cells}\n    </tr>`;
+    })
+    .join("\n");
+
+  return (
+    `<table class="compare-table">\n` +
+    `  <thead>\n    <tr>\n${headerCells}\n    </tr>\n  </thead>\n` +
+    `  <tbody>\n${bodyRows}\n  </tbody>\n` +
+    `</table>`
+  );
+}
+
+export const meta: BlockMeta = {
+  type: "compare_table",
+  description: "Bordered comparison grid. Headers define columns; rows must have matching cell count.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "compare_table" },
+      headers: { type: "array", items: { type: "string" } },
+      rows: { type: "array", items: { type: "array", items: { type: "string" } } },
+    },
+    required: ["type", "headers", "rows"],
+  },
+  example: {
+    type: "compare_table",
+    headers: ["Feature", "html mode", "blocks mode"],
+    rows: [
+      ["Token cost", "High", "**~2× lower**"],
+      ["Type safety", "None", "Full"],
+      ["Escape hatch", "`raw_html`", "`raw_html`"],
+    ],
+  },
+};