@cfbender/cesium 0.4.0 → 0.5.0

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,96 @@
+// Block tree walker and dispatcher.
+// src/render/blocks/render.ts
+
+import type { Block } from "./types.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;
+}
+
+function makeRootCtx(): RenderCtx {
+  return {
+    sectionCounter: { value: 1 },
+    depth: 0,
+    path: "blocks",
+  };
+}
+
+/** Dispatch a single block to its renderer. */
+export function renderBlock(block: Block, ctx: RenderCtx): 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 function renderBlocks(blocks: Block[], opts?: { title?: string }): string {
+  const ctx = makeRootCtx();
+  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}]`,
+    };
+    parts.push(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,44 @@
+// Code block renderer.
+// 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";
+
+export function renderCode(block: CodeBlock, _ctx: RenderCtx): string {
+  const parts: string[] = [];
+
+  const captionText = block.filename ?? block.caption;
+  if (captionText !== undefined && captionText !== "") {
+    parts.push(`  <figcaption>${escapeHtml(captionText)}</figcaption>`);
+  }
+
+  parts.push(
+    `  <pre><code class="lang-${escapeAttr(block.lang)}">${escapeHtml(block.code)}</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`"],
+    ],
+  },
+};

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

@@ -0,0 +1,48 @@
+// Diagram block renderer — escape-hatch for inline SVG or HTML diagrams.
+// src/render/blocks/renderers/diagram.ts
+
+import type { DiagramBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { escapeHtml } from "../escape.ts";
+import { scrub } from "../../scrub.ts";
+
+export function renderDiagram(block: DiagramBlock, _ctx: RenderCtx): string {
+  const payload = block.svg ?? block.html ?? "";
+  const scrubResult = scrub(payload);
+  const scrubbed = scrubResult.html;
+
+  const parts: string[] = [];
+  parts.push(scrubbed);
+
+  if (block.caption !== undefined && block.caption !== "") {
+    parts.push(`<figcaption>${escapeHtml(block.caption)}</figcaption>`);
+  }
+
+  return `<figure class="diagram">\n${parts.join("\n")}\n</figure>`;
+}
+
+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).",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "diagram" },
+      caption: { type: "string" },
+      svg: { type: "string" },
+      html: { type: "string" },
+    },
+    required: ["type"],
+    oneOf: [
+      { required: ["svg"] },
+      { required: ["html"] },
+    ],
+  },
+  example: {
+    type: "diagram",
+    caption: "System architecture overview",
+    svg: '<svg viewBox="0 0 100 50" xmlns="http://www.w3.org/2000/svg"><rect x="10" y="10" width="80" height="30" rx="4" fill="none" stroke="#888"/><text x="50" y="30" text-anchor="middle" font-size="12">cesium</text></svg>',
+  },
+};

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

@@ -0,0 +1,31 @@
+// Divider block renderer.
+// src/render/blocks/renderers/divider.ts
+
+import type { DividerBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { escapeAttr } from "../escape.ts";
+
+export function renderDivider(block: DividerBlock, _ctx: RenderCtx): string {
+  if (block.label !== undefined && block.label !== "") {
+    return `<hr data-label="${escapeAttr(block.label)}">`;
+  }
+  return `<hr>`;
+}
+
+export const meta: BlockMeta = {
+  type: "divider",
+  description: "Horizontal rule separator, with an optional text label.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "divider" },
+      label: { type: "string" },
+    },
+    required: ["type"],
+  },
+  example: {
+    type: "divider",
+    label: "End of Phase 1",
+  },
+};

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

@@ -0,0 +1,66 @@
+// Hero block renderer.
+// src/render/blocks/renderers/hero.ts
+
+import type { HeroBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { escapeHtml } from "../escape.ts";
+
+export function renderHero(block: HeroBlock, _ctx: RenderCtx): string {
+  const parts: string[] = [];
+
+  if (block.eyebrow !== undefined && block.eyebrow !== "") {
+    parts.push(`  <div class="eyebrow">${escapeHtml(block.eyebrow)}</div>`);
+  }
+
+  parts.push(`  <h1 class="h-display">${escapeHtml(block.title)}</h1>`);
+
+  if (block.subtitle !== undefined && block.subtitle !== "") {
+    parts.push(`  <p class="lede">${escapeHtml(block.subtitle)}</p>`);
+  }
+
+  if (block.meta !== undefined && block.meta.length > 0) {
+    const rows = block.meta
+      .map((row) => `    <dt>${escapeHtml(row.k)}</dt><dd>${escapeHtml(row.v)}</dd>`)
+      .join("\n");
+    parts.push(`  <dl class="kv">\n${rows}\n  </dl>`);
+  }
+
+  return `<header>\n${parts.join("\n")}\n</header>`;
+}
+
+export const meta: BlockMeta = {
+  type: "hero",
+  description: "Page title header with optional eyebrow, subtitle, and key-value metadata pairs.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "hero" },
+      eyebrow: { type: "string" },
+      title: { type: "string" },
+      subtitle: { type: "string" },
+      meta: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            k: { type: "string" },
+            v: { type: "string" },
+          },
+          required: ["k", "v"],
+        },
+      },
+    },
+    required: ["type", "title"],
+  },
+  example: {
+    type: "hero",
+    eyebrow: "Phase 2",
+    title: "Block Mode Design",
+    subtitle: "Structured input for cesium_publish",
+    meta: [
+      { k: "Status", v: "Draft" },
+      { k: "Author", v: "AI" },
+    ],
+  },
+};

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

@@ -0,0 +1,45 @@
+// KV block renderer.
+// src/render/blocks/renderers/kv.ts
+
+import type { KvBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { escapeHtml } from "../escape.ts";
+
+export function renderKv(block: KvBlock, _ctx: RenderCtx): string {
+  const rows = block.rows
+    .map((row) => `  <dt>${escapeHtml(row.k)}</dt><dd>${escapeHtml(row.v)}</dd>`)
+    .join("\n");
+  return `<dl class="kv">\n${rows}\n</dl>`;
+}
+
+export const meta: BlockMeta = {
+  type: "kv",
+  description: "Key-value metadata list. Renders as a definition list.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "kv" },
+      rows: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            k: { type: "string" },
+            v: { type: "string" },
+          },
+          required: ["k", "v"],
+        },
+      },
+    },
+    required: ["type", "rows"],
+  },
+  example: {
+    type: "kv",
+    rows: [
+      { k: "Author", v: "AI Agent" },
+      { k: "Status", v: "Draft" },
+      { k: "Version", v: "2.0.0" },
+    ],
+  },
+};