@cfbender/cesium 0.3.6 → 0.5.0

package/src/storage/assets.ts

@@ -0,0 +1,66 @@
+// Materializes /theme.css in the state directory, atomically and idempotently.
+
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import {
+  frameworkRulesCss,
+  themeTokensCss,
+  defaultTheme,
+  type ThemeTokens,
+} from "../render/theme.ts";
+import { atomicWrite } from "./write.ts";
+import { readFile } from "node:fs/promises";
+
+/** Per-theme CSS cache: built CSS string keyed by theme content hash. */
+const cssCache = new Map<string, string>();
+
+/** Returns a stable cache key for a theme (hash of its JSON representation). */
+function themeKey(theme: ThemeTokens): string {
+  return createHash("sha256").update(JSON.stringify(theme)).digest("hex");
+}
+
+/** Build the full theme.css string for a given theme (tokens + framework rules). */
+function buildCss(theme: ThemeTokens): string {
+  const key = themeKey(theme);
+  const cached = cssCache.get(key);
+  if (cached !== undefined) return cached;
+  const css = themeTokensCss(theme) + "\n" + frameworkRulesCss();
+  cssCache.set(key, css);
+  return css;
+}
+
+/** Returns the absolute path to theme.css in stateDir. */
+export function themeCssAssetPath(stateDir: string): string {
+  return join(stateDir, "theme.css");
+}
+
+/**
+ * Writes <stateDir>/theme.css with the full framework CSS (tokens + rules)
+ * for the given theme, iff the on-disk file is missing or its content hash
+ * differs from the expected content.  Idempotent and self-healing on plugin
+ * upgrade or theme change.
+ *
+ * When called without a theme argument, falls back to defaultTheme() so
+ * existing call sites remain valid.
+ */
+export async function ensureThemeCss(
+  stateDir: string,
+  theme: ThemeTokens = defaultTheme(),
+): Promise<void> {
+  const dest = themeCssAssetPath(stateDir);
+  const bundledCss = buildCss(theme);
+  const bundledHash = createHash("sha256").update(bundledCss).digest("hex");
+
+  // Fast path: compare hash of existing file to expected hash.
+  try {
+    const existing = await readFile(dest, "utf8");
+    const existingHash = createHash("sha256").update(existing).digest("hex");
+    if (existingHash === bundledHash) {
+      return; // already up-to-date
+    }
+  } catch {
+    // ENOENT or unreadable — fall through to write
+  }
+
+  await atomicWrite(dest, bundledCss);
+}

package/src/storage/index-cache.ts

@@ -19,6 +19,7 @@ export interface IndexEntry {
   projectSlug: string;
   projectName: string;
   bodyText: string;
+  inputMode?: "html" | "blocks";
 }
 
 export async function loadIndex(jsonPath: string): Promise<IndexEntry[]> {

package/src/storage/index-gen.ts

@@ -2,8 +2,8 @@
 
 import type { IndexEntry } from "./index-cache.ts";
 import type { ThemeTokens } from "../render/theme.ts";
-import { frameworkRulesCss, themeTokensCss } from "../render/theme.ts";
 import { faviconLinkTag, faviconEmblemSvg } from "../render/favicon.ts";
+import { fallbackCss } from "../render/fallback.ts";
 
 export interface RenderProjectIndexArgs {
   projectSlug: string;
@@ -236,6 +236,9 @@ function indexJs(): string {
 function renderEntryCard(entry: IndexEntry): string {
   const isSuperseded = entry.supersededBy !== null ? "1" : "0";
   const kindPill = `<span class="pill">${esc(entry.kind)}</span>`;
+  const inputModeBadge = entry.inputMode !== undefined
+    ? ` <span class="tag">${esc(entry.inputMode)}</span>`
+    : "";
   const dateStr = `<span class="card-date">${esc(formatDate(entry.createdAt))}</span>`;
   const supersededBadge =
     entry.supersedes !== null
@@ -255,7 +258,7 @@ function renderEntryCard(entry: IndexEntry): string {
       : "";
 
   return `<div class="entry-card" data-card data-kind="${esc(entry.kind)}" data-title-lower="${esc(entry.title.toLowerCase())}" data-body-text="${esc(entry.bodyText.toLowerCase())}" data-superseded="${isSuperseded}">
-  <div class="card-top">${kindPill}${supersededBadge}${supersededByBadge}${dateStr}</div>
+  <div class="card-top">${kindPill}${inputModeBadge}${supersededBadge}${supersededByBadge}${dateStr}</div>
   <div class="card-title"><a href="artifacts/${esc(entry.filename)}">${esc(entry.title)}</a></div>
   ${summaryHtml}${tagsHtml}
   <div class="card-footer"><a class="open-link" href="artifacts/${esc(entry.filename)}">Open →</a></div>
@@ -265,7 +268,7 @@ function renderEntryCard(entry: IndexEntry): string {
 // ─── renderProjectIndex ──────────────────────────────────────────────────────
 
 export function renderProjectIndex(args: RenderProjectIndexArgs): string {
-  const { projectSlug, projectName, entries, theme } = args;
+  const { projectSlug, projectName, entries } = args;
   const href =
     args.themeCssHref === undefined
       ? "../../theme.css"
@@ -274,8 +277,7 @@ export function renderProjectIndex(args: RenderProjectIndexArgs): string {
         : args.themeCssHref;
   const suppressLink = args.themeCssHref === null;
 
-  const rules = frameworkRulesCss();
-  const tokens = themeTokensCss(theme);
+  const fallback = fallbackCss();
   const iCss = indexCss();
   const iJs = indexJs();
 
@@ -358,9 +360,8 @@ ${cardsHtml}
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${esc(projectName)} · cesium</title>
-  <style>${rules}
-/* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}${iCss}</style>${linkTag}${faviconTag}
+  <style>/* fallback — standalone-readable; full styles served from /theme.css */
+${fallback}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">
@@ -381,7 +382,7 @@ ${tokens}${iCss}</style>${linkTag}${faviconTag}
 // ─── renderGlobalIndex ───────────────────────────────────────────────────────
 
 export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
-  const { projects, theme } = args;
+  const { projects } = args;
   const href =
     args.themeCssHref === undefined
       ? "theme.css"
@@ -390,8 +391,7 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
         : args.themeCssHref;
   const suppressLink = args.themeCssHref === null;
 
-  const rules = frameworkRulesCss();
-  const tokens = themeTokensCss(theme);
+  const fallback = fallbackCss();
   const iCss = indexCss();
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
@@ -448,9 +448,8 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>All projects · cesium</title>
-  <style>${rules}
-/* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}${iCss}</style>${linkTag}${faviconTag}
+  <style>/* fallback — standalone-readable; full styles served from /theme.css */
+${fallback}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">

package/src/tools/ask.ts

@@ -13,7 +13,7 @@ import { wrapDocument, type ArtifactMeta } from "../render/wrap.ts";
 import type { InteractiveData } from "../render/validate.ts";
 import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
 import { atomicWrite } from "../storage/write.ts";
-import { writeThemeCss } from "../storage/theme-write.ts";
+import { ensureThemeCss } from "../storage/assets.ts";
 import { writeFaviconSvg } from "../storage/favicon-write.ts";
 import { loadIndex, writeIndex, appendEntry, type IndexEntry } from "../storage/index-cache.ts";
 import { withLock } from "../storage/lock.ts";
@@ -204,6 +204,7 @@ export function createAskTool(
         supersedes: null,
         supersededBy: null,
         contentSha256,
+        inputMode: "html",
       };
 
       // 12. Build interactive data
@@ -228,8 +229,8 @@ export function createAskTool(
       // 14. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
 
-      // 14a. Write theme.css + favicon.svg (idempotent, outside index lock — separate files)
-      await writeThemeCss(config.stateDir, theme);
+      // 14a. Ensure theme.css + favicon.svg (idempotent, outside index lock — separate files)
+      await ensureThemeCss(config.stateDir, theme);
       await writeFaviconSvg(config.stateDir);
 
       const fullHtml = wrapDocument({
@@ -309,6 +310,7 @@ export function createAskTool(
           portMax: config.portMax,
           idleTimeoutMs: config.idleTimeoutMs,
           hostname: config.hostname,
+          theme,
         });
         if (maybeInfo !== null) {
           serverInfo = maybeInfo;

package/src/tools/critique.ts

@@ -1,8 +1,15 @@
-// Tool handler for cesium_critique — runs the body analyzer and returns a human-readable report.
+// Tool handler for cesium_critique — mode-aware body analyzer.
+// Accepts either { html: string } (html mode) or { blocks: Block[] } (blocks mode). Exactly one required.
 
 import { tool } from "@opencode-ai/plugin";
 import type { PluginInput } from "@opencode-ai/plugin";
-import { critique, type CritiqueResult, type CritiqueSeverity } from "../render/critique.ts";
+import {
+  critiqueHtml,
+  critiqueBlocks,
+  type CritiqueResult,
+  type CritiqueSeverity,
+} from "../render/critique.ts";
+import type { Block } from "../render/blocks/types.ts";
 
 const TOOL_DESCRIPTION = `Analyze a draft HTML body for adherence to the cesium design
 system before publishing. Returns a 0-100 score and findings (warn/suggest/info).
@@ -18,6 +25,7 @@ HTML only, no <!doctype>/<html>/<head>/<body> wrappers.`;
  * Format a CritiqueResult into a concise human-readable string the agent can parse.
  * Format:
  *   score: 87/100
+ *   mode: html
  *
  *   warn:
  *   - [external-resource] External resource will be stripped...
@@ -29,7 +37,7 @@ HTML only, no <!doctype>/<html>/<head>/<body> wrappers.`;
  *   - [code-without-highlights] Code blocks render without...
  */
 export function formatCritiqueForAgent(result: CritiqueResult): string {
-  const lines: string[] = [`score: ${result.score}/100`];
+  const lines: string[] = [`score: ${result.score}/100`, `mode: ${result.mode}`];
 
   const bySeverity: Record<CritiqueSeverity, typeof result.findings> = {
     warn: [],
@@ -47,7 +55,8 @@ export function formatCritiqueForAgent(result: CritiqueResult): string {
     lines.push("");
     lines.push(`${sev}:`);
     for (const f of group) {
-      lines.push(`- [${f.code}] ${f.message}`);
+      const pathSuffix = f.path !== undefined ? ` (${f.path})` : "";
+      lines.push(`- [${f.code}] ${f.message}${pathSuffix}`);
     }
   }
 
@@ -57,9 +66,35 @@ export function formatCritiqueForAgent(result: CritiqueResult): string {
 export function createCritiqueTool(_ctx: PluginInput): ReturnType<typeof tool> {
   return tool({
     description: TOOL_DESCRIPTION,
-    args: { html: tool.schema.string() },
+    args: {
+      html: tool.schema.string().optional(),
+      blocks: tool.schema.any().optional(),
+    },
     async execute(args) {
-      const result = critique(args.html);
+      const hasHtml = args.html !== undefined && args.html !== null;
+      const hasBlocks = args.blocks !== undefined && args.blocks !== null;
+
+      if (hasHtml && hasBlocks) {
+        return "error: provide exactly one of html or blocks, not both";
+      }
+      if (!hasHtml && !hasBlocks) {
+        return "error: provide exactly one of html or blocks";
+      }
+
+      let result: CritiqueResult;
+
+      if (hasHtml) {
+        if (typeof args.html !== "string") {
+          return "error: html must be a string";
+        }
+        result = critiqueHtml(args.html);
+      } else {
+        if (!Array.isArray(args.blocks)) {
+          return "error: blocks must be an array";
+        }
+        result = critiqueBlocks(args.blocks as Block[]);
+      }
+
       return formatCritiqueForAgent(result);
     },
   });

package/src/tools/publish.ts

@@ -10,10 +10,11 @@ import { scrub } from "../render/scrub.ts";
 import { extractTextContent } from "../render/extract.ts";
 import { themeFromPreset, mergeTheme } from "../render/theme.ts";
 import { validatePublishInput, htmlBodyWarnings, PUBLISH_KINDS } from "../render/validate.ts";
+import { renderBlocks } from "../render/blocks/render.ts";
 import { wrapDocument, type ArtifactMeta } from "../render/wrap.ts";
 import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
 import { atomicWrite, patchEmbeddedMetadata } from "../storage/write.ts";
-import { writeThemeCss } from "../storage/theme-write.ts";
+import { ensureThemeCss } from "../storage/assets.ts";
 import { writeFaviconSvg } from "../storage/favicon-write.ts";
 import {
   loadIndex,
@@ -112,7 +113,18 @@ export function createPublishTool(
     args: {
       title: tool.schema.string(),
       kind: tool.schema.enum([...PUBLISH_KINDS] as [string, ...string[]]),
-      html: tool.schema.string(),
+      html: tool.schema
+        .string()
+        .optional()
+        .describe(
+          "Body HTML — escape valve / legacy mode. Provide exactly one of html or blocks.",
+        ),
+      blocks: tool.schema
+        .array(tool.schema.any())
+        .optional()
+        .describe(
+          "Structured block array — preferred for token efficiency. Provide exactly one of html or blocks.",
+        ),
       summary: tool.schema.string().optional(),
       tags: tool.schema.array(tool.schema.string()).optional(),
       supersedes: tool.schema.string().optional(),
@@ -174,11 +186,23 @@ export function createPublishTool(
       // 6. Timestamps
       const createdAt = now();
 
-      // 7. Scrub
-      const scrubbed = scrub(input.html);
+      // 7. Render body (blocks path or html path)
+      let bodyHtml: string;
+      let scrubRemovedCount = 0;
+      const inputMode: "html" | "blocks" = input.blocks !== undefined ? "blocks" : "html";
+
+      if (input.blocks !== undefined) {
+        // Blocks path: render structured blocks → trusted HTML
+        bodyHtml = renderBlocks(input.blocks);
+      } else {
+        // HTML path: scrub agent-supplied HTML
+        const scrubbed = scrub(input.html);
+        bodyHtml = scrubbed.html;
+        scrubRemovedCount = scrubbed.removed.length;
+      }
 
       // 7a. Extract body text for full-text search
-      const bodyText = extractTextContent(scrubbed.html);
+      const bodyText = extractTextContent(bodyHtml);
 
       // 8. Compute filename + paths
       const filename = artifactFilename({ title: input.title, id, createdAt });
@@ -189,7 +213,7 @@ export function createPublishTool(
       });
 
       // 9. Content SHA-256
-      const contentSha256 = createHash("sha256").update(scrubbed.html).digest("hex");
+      const contentSha256 = createHash("sha256").update(bodyHtml).digest("hex");
 
       // 10. Build ArtifactMeta
       const meta: ArtifactMeta = {
@@ -210,14 +234,15 @@ export function createPublishTool(
         supersedes: input.supersedes ?? null,
         supersededBy: null,
         contentSha256,
+        inputMode,
       };
 
       // 11. Build warnings
       const warnings: string[] = [];
-      if (scrubbed.removed.length > 0) {
-        warnings.push(`Removed ${scrubbed.removed.length} external resource(s) during scrub.`);
+      if (scrubRemovedCount > 0) {
+        warnings.push(`Removed ${scrubRemovedCount} external resource(s) during scrub.`);
       }
-      const bodyWarnings = htmlBodyWarnings(scrubbed.html);
+      const bodyWarnings = input.html !== undefined ? htmlBodyWarnings(bodyHtml) : [];
       for (const w of bodyWarnings) {
         warnings.push(w);
       }
@@ -225,12 +250,12 @@ export function createPublishTool(
       // 12. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
 
-      // 12a. Write theme.css + favicon.svg (idempotent, outside index lock — separate files)
-      await writeThemeCss(config.stateDir, theme);
+      // 12a. Ensure theme.css + favicon.svg (idempotent, outside index lock — separate files)
+      await ensureThemeCss(config.stateDir, theme);
       await writeFaviconSvg(config.stateDir);
 
       const fullHtml = wrapDocument({
-        body: scrubbed.html,
+        body: bodyHtml,
         meta,
         theme,
         warnings,
@@ -257,6 +282,7 @@ export function createPublishTool(
         projectSlug: identity.slug,
         projectName: identity.name,
         bodyText,
+        inputMode,
       };
 
       const lockPath = join(config.stateDir, ".index.lock");
@@ -336,6 +362,7 @@ export function createPublishTool(
           portMax: config.portMax,
           idleTimeoutMs: config.idleTimeoutMs,
           hostname: config.hostname,
+          theme,
         });
         if (maybeInfo !== null) {
           serverInfo = maybeInfo;

package/src/tools/styleguide.ts

@@ -1,15 +1,115 @@
-// Tool handler for cesium_styleguide — returns the full CSS reference page as a string.
+// Tool handler for cesium_styleguide — returns a markdown reference generated from the block catalog.
 
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { tool } from "@opencode-ai/plugin";
 import type { PluginInput } from "@opencode-ai/plugin";
+import { blockCatalog, blockTypes } from "../render/blocks/catalog.ts";
+import { renderBlock } from "../render/blocks/render.ts";
+import type { RenderCtx, SectionCounter } from "../render/blocks/render.ts";
 
-const STYLEGUIDE_PATH = join(
-  dirname(fileURLToPath(import.meta.url)),
-  "../../assets/styleguide.html",
-);
+function makeCtx(): RenderCtx {
+  const counter: SectionCounter = { value: 1 };
+  return { sectionCounter: counter, depth: 0, path: "blocks[0]" };
+}
+
+/** Escape a string for safe insertion inside a markdown fenced code block. */
+function escapeForCodeFence(s: string): string {
+  // Prevent accidental fence closing — replace ``` with ` `` ` (rare in practice)
+  return s.replace(/```/g, "` `` `");
+}
+
+/** Generate the full markdown reference from the catalog. Deterministic — same catalog → same output. */
+export function generateStyleguideMarkdown(): string {
+  const lines: string[] = [];
+
+  lines.push("# Cesium publishing reference");
+  lines.push("");
+  lines.push("## Two input modes");
+  lines.push("");
+  lines.push(
+    "`cesium_publish` accepts either `blocks: Block[]` (preferred) or `html: string`" +
+      " (escape valve). Provide exactly one.",
+  );
+  lines.push("");
+  lines.push(
+    "Prefer `blocks` for plans, reviews, reports, explainers, comparisons, audits, design docs." +
+      " Use `html` only for whole-document bespoke layouts (custom hero, non-standard grid," +
+      " experimental visual essay). For isolated bespoke regions, stay in `blocks` and use" +
+      " `raw_html` or `diagram`.",
+  );
+  lines.push("");
+  lines.push("## Block reference");
+  lines.push("");
+
+  for (const blockType of blockTypes) {
+    const entry = blockCatalog[blockType];
+
+    lines.push(`### \`${entry.type}\``);
+    lines.push("");
+    lines.push(entry.description);
+    lines.push("");
+
+    // Schema as JSON
+    lines.push("```json");
+    lines.push(escapeForCodeFence(JSON.stringify(entry.schema, null, 2)));
+    lines.push("```");
+    lines.push("");
+
+    // Canonical example
+    lines.push("Example:");
+    lines.push("");
+    lines.push("```json");
+    lines.push(escapeForCodeFence(JSON.stringify(entry.example, null, 2)));
+    lines.push("```");
+    lines.push("");
+
+    // Rendered HTML
+    const rendered = entry.renderedExample ?? (() => {
+      try {
+        return renderBlock(entry.example, makeCtx());
+      } catch {
+        return "";
+      }
+    })();
+
+    if (rendered !== "") {
+      lines.push("Renders to:");
+      lines.push("");
+      lines.push("```html");
+      lines.push(escapeForCodeFence(rendered));
+      lines.push("```");
+      lines.push("");
+    }
+  }
+
+  lines.push(
+    "## Markdown subset (inside `prose`, `tldr`, `callout.markdown`, list items, table cells)",
+  );
+  lines.push("");
+  lines.push(
+    "- Block: paragraph, `-` lists, `1.` lists, `>` blockquote, `---` rule, hard break (two-space EOL).",
+  );
+  lines.push(
+    "- Inline: `**bold**`, `*italic*`, `` `code` ``, `[text](href)` (relative or anchor only).",
+  );
+  lines.push(
+    "- HTML safelist: `<kbd>`, `<span class=\"pill\">`, `<span class=\"tag\">`. Anything else is escaped.",
+  );
+  lines.push("");
+  lines.push("## When to reach for raw_html / diagram");
+  lines.push("");
+  lines.push(
+    "- `diagram` — inline SVG visualizations or bespoke composed HTML diagrams.",
+  );
+  lines.push(
+    "- `raw_html` — anything genuinely creative that doesn't fit a known block type." +
+      " Include a `purpose` string describing what you're building.",
+  );
+  lines.push(
+    "- Critique flags raw_html overuse (>2 blocks or >30% of body characters).",
+  );
+
+  return lines.join("\n");
+}
 
 export function createStyleguideTool(_ctx: PluginInput): ReturnType<typeof tool> {
   return tool({
@@ -17,7 +117,7 @@ export function createStyleguideTool(_ctx: PluginInput): ReturnType<typeof tool>
       "Returns the cesium HTML design system reference page (CSS classes with example usage). Call this once at the start of writing a complex artifact to internalize the available components.",
     args: {},
     async execute(_args, _context) {
-      return await readFile(STYLEGUIDE_PATH, "utf8");
+      return generateStyleguideMarkdown();
     },
   });
 }