@cfbender/cesium 0.3.6 → 0.5.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,95 @@
+// 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 function renderSection(block: SectionBlock, ctx: RenderCtx): 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`,
+  };
+
+  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}]`,
+    };
+    const rendered = 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.",
+  },
+};

package/src/render/blocks/types.ts

@@ -0,0 +1,127 @@
+// Block discriminated union — the closed type system for cesium_publish structured input.
+// src/render/blocks/types.ts
+
+export type Block =
+  | HeroBlock
+  | TldrBlock
+  | SectionBlock
+  | ProseBlock
+  | ListBlock
+  | CalloutBlock
+  | CodeBlock
+  | TimelineBlock
+  | CompareTableBlock
+  | RiskTableBlock
+  | KvBlock
+  | PillRowBlock
+  | DividerBlock
+  | DiagramBlock
+  | RawHtmlBlock;
+
+export type HeroBlock = {
+  type: "hero";
+  eyebrow?: string;
+  title: string;
+  subtitle?: string;
+  meta?: Array<{ k: string; v: string }>;
+};
+
+export type TldrBlock = {
+  type: "tldr";
+  // markdown subset; at most one tldr per document
+  markdown: string;
+};
+
+export type SectionBlock = {
+  type: "section";
+  title: string;
+  num?: string; // omitted = auto-numbered sequentially
+  eyebrow?: string;
+  children: Block[];
+};
+
+export type ProseBlock = {
+  type: "prose";
+  markdown: string;
+};
+
+export type ListBlock = {
+  type: "list";
+  style?: "bullet" | "number" | "check";
+  items: string[]; // each item is markdown (subset)
+};
+
+export type CalloutBlock = {
+  type: "callout";
+  variant: "note" | "warn" | "risk";
+  title?: string;
+  markdown: string;
+};
+
+export type CodeBlock = {
+  type: "code";
+  lang: string; // required; "text" if unknown
+  code: string;
+  filename?: string;
+  caption?: string;
+};
+
+export type TimelineBlock = {
+  type: "timeline";
+  items: Array<{ label: string; text: string; date?: string }>;
+};
+
+export type CompareTableBlock = {
+  type: "compare_table";
+  headers: string[];
+  rows: string[][]; // cells are markdown (subset)
+};
+
+export type RiskTableBlock = {
+  type: "risk_table";
+  rows: Array<{
+    risk: string;
+    likelihood: "low" | "medium" | "high";
+    impact: "low" | "medium" | "high";
+    mitigation: string;
+  }>;
+};
+
+export type KvBlock = {
+  type: "kv";
+  rows: Array<{ k: string; v: string }>;
+};
+
+export type PillRowBlock = {
+  type: "pill_row";
+  items: Array<{ kind: "pill" | "tag"; text: string }>;
+};
+
+export type DividerBlock = {
+  type: "divider";
+  label?: string;
+};
+
+export type DiagramBlock = {
+  type: "diagram";
+  caption?: string;
+  // exactly one of svg or html
+  svg?: string;
+  html?: string;
+};
+
+export type RawHtmlBlock = {
+  type: "raw_html";
+  html: string;
+  purpose?: string; // brief reason; surfaced in critique findings
+};
+
+// ─── BlockMeta ───────────────────────────────────────────────────────────────
+
+export type BlockMeta = {
+  type: Block["type"];
+  description: string;
+  schema: object; // JSON Schema fragment for the block
+  example: Block; // canonical example matching schema
+  renderedExample?: string; // optional pre-rendered HTML for docs
+};