@cfbender/cesium 0.4.0 → 0.5.1

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" },
+    ],
+  },
+};

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

@@ -0,0 +1,51 @@
+// List block renderer.
+// src/render/blocks/renderers/list.ts
+
+import type { ListBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { renderMarkdown } from "../markdown.ts";
+
+export function renderList(block: ListBlock, _ctx: RenderCtx): string {
+  const style = block.style ?? "bullet";
+
+  const items = block.items
+    .map((item) => {
+      const content = renderMarkdown(item).replace(/^<p>|<\/p>$/g, "");
+      return `  <li>${content}</li>`;
+    })
+    .join("\n");
+
+  if (style === "number") {
+    return `<ol>\n${items}\n</ol>`;
+  } else if (style === "check") {
+    const checkItems = block.items
+      .map((item) => {
+        const content = renderMarkdown(item).replace(/^<p>|<\/p>$/g, "");
+        return `  <li class="check">${content}</li>`;
+      })
+      .join("\n");
+    return `<ul class="check-list">\n${checkItems}\n</ul>`;
+  } else {
+    return `<ul>\n${items}\n</ul>`;
+  }
+}
+
+export const meta: BlockMeta = {
+  type: "list",
+  description: "Bullet, numbered, or checklist. Items are markdown strings.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "list" },
+      style: { type: "string", enum: ["bullet", "number", "check"] },
+      items: { type: "array", items: { type: "string" } },
+    },
+    required: ["type", "items"],
+  },
+  example: {
+    type: "list",
+    style: "bullet",
+    items: ["First item with **bold**", "Second item", "Third item"],
+  },
+};

package/src/render/blocks/renderers/pill-row.ts

@@ -0,0 +1,45 @@
+// PillRow block renderer.
+// src/render/blocks/renderers/pill-row.ts
+
+import type { PillRowBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { escapeHtml } from "../escape.ts";
+
+export function renderPillRow(block: PillRowBlock, _ctx: RenderCtx): string {
+  const pills = block.items
+    .map((item) => `  <span class="${item.kind}">${escapeHtml(item.text)}</span>`)
+    .join("\n");
+  return `<div class="pill-row">\n${pills}\n</div>`;
+}
+
+export const meta: BlockMeta = {
+  type: "pill_row",
+  description: "Horizontal row of pill or tag chips. Each item has a kind (pill or tag) and text.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "pill_row" },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            kind: { type: "string", enum: ["pill", "tag"] },
+            text: { type: "string" },
+          },
+          required: ["kind", "text"],
+        },
+      },
+    },
+    required: ["type", "items"],
+  },
+  example: {
+    type: "pill_row",
+    items: [
+      { kind: "pill", text: "TypeScript" },
+      { kind: "pill", text: "Bun" },
+      { kind: "tag", text: "phase-2" },
+    ],
+  },
+};

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

@@ -0,0 +1,29 @@
+// Prose block renderer.
+// src/render/blocks/renderers/prose.ts
+
+import type { ProseBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { renderMarkdown } from "../markdown.ts";
+
+export function renderProse(block: ProseBlock, _ctx: RenderCtx): string {
+  return renderMarkdown(block.markdown);
+}
+
+export const meta: BlockMeta = {
+  type: "prose",
+  description: "Free-form markdown text block. Renders paragraphs, lists, emphasis, links.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "prose" },
+      markdown: { type: "string" },
+    },
+    required: ["type", "markdown"],
+  },
+  example: {
+    type: "prose",
+    markdown:
+      "This is a paragraph with **bold** and *italic* text.\n\n- Item one\n- Item two",
+  },
+};

package/src/render/blocks/renderers/raw-html.ts

@@ -0,0 +1,32 @@
+// RawHtml block renderer — escape-hatch for fully custom HTML payloads.
+// src/render/blocks/renderers/raw-html.ts
+
+import type { RawHtmlBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { scrub } from "../../scrub.ts";
+
+export function renderRawHtml(block: RawHtmlBlock, _ctx: RenderCtx): string {
+  const scrubResult = scrub(block.html);
+  return scrubResult.html;
+}
+
+export const meta: BlockMeta = {
+  type: "raw_html",
+  description:
+    "Fully custom HTML payload. Scrubbed of external resources. Use when no structured block fits. Include a purpose string for audit trail.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "raw_html" },
+      html: { type: "string" },
+      purpose: { type: "string" },
+    },
+    required: ["type", "html"],
+  },
+  example: {
+    type: "raw_html",
+    html: '<div class="card" style="display:grid;grid-template-columns:1fr 1fr;gap:16px;"><div><h3>Option A</h3><p>Fast but brittle.</p></div><div><h3>Option B</h3><p>Slower but robust.</p></div></div>',
+    purpose: "Two-column card layout not expressible as compare_table",
+  },
+};

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

@@ -0,0 +1,76 @@
+// RiskTable block renderer.
+// src/render/blocks/renderers/risk-table.ts
+
+import type { RiskTableBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { escapeHtml } from "../escape.ts";
+
+export function renderRiskTable(block: RiskTableBlock, _ctx: RenderCtx): string {
+  const headerRow =
+    "  <thead>\n    <tr>\n" +
+    "      <th>Risk</th>\n      <th>Likelihood</th>\n      <th>Impact</th>\n      <th>Mitigation</th>\n" +
+    "    </tr>\n  </thead>";
+
+  const bodyRows = block.rows
+    .map((row) => {
+      return (
+        `    <tr>\n` +
+        `      <td>${escapeHtml(row.risk)}</td>\n` +
+        `      <td class="risk-${escapeHtml(row.likelihood)}">${escapeHtml(row.likelihood)}</td>\n` +
+        `      <td class="risk-${escapeHtml(row.impact)}">${escapeHtml(row.impact)}</td>\n` +
+        `      <td>${escapeHtml(row.mitigation)}</td>\n` +
+        `    </tr>`
+      );
+    })
+    .join("\n");
+
+  return (
+    `<table class="risk-table">\n` +
+    `${headerRow}\n` +
+    `  <tbody>\n${bodyRows}\n  </tbody>\n` +
+    `</table>`
+  );
+}
+
+export const meta: BlockMeta = {
+  type: "risk_table",
+  description: "Risk register grid with likelihood/impact/mitigation columns.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "risk_table" },
+      rows: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            risk: { type: "string" },
+            likelihood: { type: "string", enum: ["low", "medium", "high"] },
+            impact: { type: "string", enum: ["low", "medium", "high"] },
+            mitigation: { type: "string" },
+          },
+          required: ["risk", "likelihood", "impact", "mitigation"],
+        },
+      },
+    },
+    required: ["type", "rows"],
+  },
+  example: {
+    type: "risk_table",
+    rows: [
+      {
+        risk: "Agent ignores blocks mode",
+        likelihood: "high",
+        impact: "high",
+        mitigation: "Prompt steering + critique bonus + styleguide.",
+      },
+      {
+        risk: "Markdown subset too narrow",
+        likelihood: "low",
+        impact: "medium",
+        mitigation: "Audit first 50 artifacts; expand if needed.",
+      },
+    ],
+  },
+};

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

@@ -0,0 +1,97 @@
+// Section block renderer.
+// src/render/blocks/renderers/section.ts
+
+import type { SectionBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { renderBlock } from "../render.ts";
+import { escapeHtml } from "../escape.ts";
+
+export async function renderSection(block: SectionBlock, ctx: RenderCtx): Promise<string> {
+  // Determine section number: explicit or auto-increment
+  let num: string;
+  if (block.num !== undefined && block.num !== "") {
+    num = block.num;
+  } else {
+    num = String(ctx.sectionCounter.value).padStart(2, "0");
+    ctx.sectionCounter.value += 1;
+  }
+
+  const parts: string[] = [];
+
+  if (block.eyebrow !== undefined && block.eyebrow !== "") {
+    parts.push(`  <div class="eyebrow">${escapeHtml(block.eyebrow)}</div>`);
+  }
+
+  parts.push(
+    `  <h2 class="h-section"><span class="section-num">${escapeHtml(num)}</span> ${escapeHtml(block.title)}</h2>`,
+  );
+
+  // Render children with incremented depth.
+  // Non-section children are grouped into <div class="card"> wrappers for visual polish.
+  // Nested section children are emitted at top level (they carry their own card structure).
+  const childCtx: RenderCtx = {
+    sectionCounter: ctx.sectionCounter,
+    depth: ctx.depth + 1,
+    path: `${ctx.path}.children`,
+    highlightTheme: ctx.highlightTheme,
+  };
+
+  let buffer: string[] = [];
+
+  for (let i = 0; i < block.children.length; i++) {
+    const child = block.children[i];
+    if (child === undefined) continue;
+    const childBlockCtx: RenderCtx = {
+      ...childCtx,
+      path: `${ctx.path}.children[${i}]`,
+    };
+    // eslint-disable-next-line no-await-in-loop -- sequential render required; card buffer tracks contiguous non-section children
+    const rendered = await renderBlock(child, childBlockCtx);
+    if (child.type === "section") {
+      // Flush buffered non-section children into a card first
+      if (buffer.length > 0) {
+        parts.push(`  <div class="card">\n${buffer.join("\n")}\n  </div>`);
+        buffer = [];
+      }
+      parts.push(`  ${rendered}`);
+    } else {
+      buffer.push(`  ${rendered}`);
+    }
+  }
+
+  // Flush any remaining non-section children
+  if (buffer.length > 0) {
+    parts.push(`  <div class="card">\n${buffer.join("\n")}\n  </div>`);
+  }
+
+  return `<section>\n${parts.join("\n")}\n</section>`;
+}
+
+export const meta: BlockMeta = {
+  type: "section",
+  description:
+    "Numbered section with title and child blocks. Only block type with children. Nesting depth ≤ 3.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "section" },
+      title: { type: "string" },
+      num: { type: "string" },
+      eyebrow: { type: "string" },
+      children: { type: "array", items: { type: "object" } },
+    },
+    required: ["type", "title", "children"],
+  },
+  example: {
+    type: "section",
+    title: "Goals",
+    eyebrow: "Why we're here",
+    children: [
+      {
+        type: "prose",
+        markdown: "Reduce output tokens by moving structural HTML into the server.",
+      },
+    ],
+  },
+};

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

@@ -0,0 +1,58 @@
+// Timeline block renderer.
+// src/render/blocks/renderers/timeline.ts
+
+import type { TimelineBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { escapeHtml } from "../escape.ts";
+
+export function renderTimeline(block: TimelineBlock, _ctx: RenderCtx): string {
+  const items = block.items
+    .map((item) => {
+      const dateHtml =
+        item.date !== undefined && item.date !== ""
+          ? ` <span class="timeline-date">${escapeHtml(item.date)}</span>`
+          : "";
+      return (
+        `  <li class="timeline-item">\n` +
+        `    <span class="timeline-label">${escapeHtml(item.label)}${dateHtml}</span>\n` +
+        `    <span class="timeline-text">${escapeHtml(item.text)}</span>\n` +
+        `  </li>`
+      );
+    })
+    .join("\n");
+
+  return `<ul class="timeline">\n${items}\n</ul>`;
+}
+
+export const meta: BlockMeta = {
+  type: "timeline",
+  description: "Milestone list with dot connectors. Each item has a label, text, and optional date.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "timeline" },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            label: { type: "string" },
+            text: { type: "string" },
+            date: { type: "string" },
+          },
+          required: ["label", "text"],
+        },
+      },
+    },
+    required: ["type", "items"],
+  },
+  example: {
+    type: "timeline",
+    items: [
+      { label: "Phase 1", text: "CSS extraction and theme serving", date: "2026-05-10" },
+      { label: "Phase 2", text: "Block plumbing and renderers", date: "2026-05-12" },
+      { label: "Phase 3", text: "Tooling flip — prompt and styleguide update" },
+    ],
+  },
+};

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

@@ -0,0 +1,30 @@
+// Tldr block renderer.
+// src/render/blocks/renderers/tldr.ts
+
+import type { TldrBlock } from "../types.ts";
+import type { BlockMeta } from "../types.ts";
+import type { RenderCtx } from "../render.ts";
+import { renderMarkdown } from "../markdown.ts";
+
+export function renderTldr(block: TldrBlock, _ctx: RenderCtx): string {
+  return `<aside class="tldr">\n${renderMarkdown(block.markdown)}\n</aside>`;
+}
+
+export const meta: BlockMeta = {
+  type: "tldr",
+  description:
+    "Clay-bordered summary box. Use at most one per document, near the top. Content is markdown.",
+  schema: {
+    type: "object",
+    properties: {
+      type: { const: "tldr" },
+      markdown: { type: "string" },
+    },
+    required: ["type", "markdown"],
+  },
+  example: {
+    type: "tldr",
+    markdown:
+      "**Summary:** This document covers the block-mode refactor for `cesium_publish`. Three phases: plumbing, tooling flip, and cleanup.",
+  },
+};