@cfbender/cesium 0.3.6 → 0.5.0

package/src/render/fallback.ts

@@ -0,0 +1,18 @@
+// Minimal inline fallback CSS — ~8 lines, ≤500 bytes minified.
+// Goal: standalone .html files opened via file:// look "plain but readable,"
+// not broken. Full styling comes from the served /theme.css.
+
+/** Returns a compact CSS block covering typography, color tokens, and basic
+ *  component borders. Used as the inline <style> fallback in every artifact.
+ *  Budget: ≤500 bytes minified. */
+export function fallbackCss(): string {
+  return (
+    ":root{font-family:system-ui,sans-serif;line-height:1.6;}" +
+    "body{max-width:900px;margin:0 auto;padding:24px;}" +
+    "@media(prefers-color-scheme:dark){body{background:#180810;color:#ddd;}}" +
+    "pre,code{font-family:ui-monospace,monospace;font-size:.875em;}" +
+    ".card,.tldr{border:1.5px solid #ccc;border-radius:8px;padding:14px 18px;}" +
+    ".callout{border:1.5px solid #ccc;border-radius:6px;padding:12px 16px;}" +
+    "table{border-collapse:collapse;width:100%;}th,td{border:1px solid #ccc;padding:8px;}"
+  );
+}

package/src/render/theme.ts

@@ -336,6 +336,34 @@ h1, h2, h3, h4, h5, h6 {
 .code .cm { color: var(--muted); font-style: italic; }
 .code .fn { color: #d4a85a; }
 
+/* figure.code — block-renderer code blocks (figure > figcaption + pre>code) */
+figure.code {
+  margin: 0 0 1.25em 0;
+}
+figure.code pre {
+  background: var(--code-bg);
+  color: var(--code-fg);
+  font-family: var(--mono);
+  font-size: 0.875rem;
+  line-height: 1.6;
+  border-radius: 8px;
+  padding: 16px 20px;
+  overflow-x: auto;
+  margin: 0;
+  white-space: pre;
+}
+figure.code pre code {
+  font-family: inherit;
+  font-size: inherit;
+  background: none;
+  padding: 0;
+  color: inherit;
+}
+figure.code pre .kw { color: var(--accent); }
+figure.code pre .str { color: var(--olive); }
+figure.code pre .cm { color: var(--muted); font-style: italic; }
+figure.code pre .fn { color: #d4a85a; }
+
 /* timeline */
 .timeline { list-style: none; padding: 0; position: relative; }
 .timeline::before {
@@ -363,6 +391,26 @@ h1, h2, h3, h4, h5, h6 {
   background: var(--oat);
   border: 2px solid var(--accent);
 }
+/* timeline item inner spans */
+.timeline-item { display: flex; flex-direction: column; gap: 0.15em; }
+.timeline-label {
+  font-family: var(--mono);
+  font-size: 0.8rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--accent);
+}
+.timeline-date {
+  font-family: var(--mono);
+  font-size: 0.75rem;
+  color: var(--muted);
+  margin-left: 0.5em;
+  font-weight: 400;
+  letter-spacing: 0;
+  text-transform: none;
+}
+.timeline-text { color: var(--ink-soft); font-size: 0.95rem; }
 
 /* diagram */
 .diagram {
@@ -379,6 +427,112 @@ h1, h2, h3, h4, h5, h6 {
   margin-top: 10px;
   font-family: var(--sans);
 }
+/* svg text/stroke/fill overrides — defense-in-depth for dark themes */
+.diagram svg text,
+figure.diagram svg text { fill: currentColor; }
+.diagram svg [stroke="#888"],
+.diagram svg [stroke="#999"],
+.diagram svg [stroke="#666"] { stroke: currentColor; opacity: 0.55; }
+.diagram svg [fill="#222"],
+.diagram svg [fill="#000"],
+.diagram svg [fill="black"] { fill: currentColor; }
+
+/* kv — key-value definition list (hero meta, standalone kv block) */
+dl.kv {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 0.4rem 1.5rem;
+  margin: 1.25rem 0;
+  align-items: baseline;
+}
+dl.kv dt {
+  font-family: var(--mono);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+dl.kv dd { margin: 0; color: var(--ink-soft); }
+
+/* lede — hero subtitle paragraph */
+.lede {
+  font-size: 1.15rem;
+  color: var(--ink-soft);
+  margin-bottom: 1em;
+  line-height: 1.5;
+}
+
+/* divider — plain hr + labeled variant */
+hr {
+  border: none;
+  border-top: 1.5px solid var(--rule);
+  margin: 2em 0;
+}
+hr[data-label] {
+  display: flex;
+  align-items: center;
+  gap: 0.75em;
+  border: none;
+  margin: 2em 0;
+  color: var(--muted);
+  font-family: var(--mono);
+  font-size: 0.75rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+hr[data-label]::before {
+  content: "";
+  flex: 1;
+  border-top: 1.5px solid var(--rule);
+  display: block;
+}
+hr[data-label]::after {
+  content: attr(data-label);
+  flex-shrink: 0;
+}
+
+/* figure.code — caption above the code block */
+figure.code figcaption {
+  font-family: var(--mono);
+  font-size: 0.75rem;
+  color: var(--muted);
+  margin-bottom: 8px;
+  letter-spacing: 0.04em;
+}
+
+/* pill-row — horizontal chip container */
+.pill-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5em;
+  margin-bottom: 1.25em;
+}
+
+/* check-list — checklist style (ul style="check") */
+.check-list {
+  list-style: none;
+  padding: 0;
+  margin-bottom: 1em;
+}
+.check-list .check {
+  display: flex;
+  align-items: baseline;
+  gap: 0.5em;
+  margin-bottom: 0.4em;
+  padding-left: 0.25em;
+}
+.check-list .check::before {
+  content: "✓";
+  font-family: var(--mono);
+  font-size: 0.8em;
+  font-weight: 700;
+  color: var(--olive);
+  flex-shrink: 0;
+}
+
+/* card stack — sibling cards within a section */
+.card + .card { margin-top: 1em; }
 
 /* compare-table */
 .compare-table {
@@ -456,6 +610,87 @@ h1, h2, h3, h4, h5, h6 {
   color: var(--muted);
   text-transform: lowercase;
 }
+.pill.accent {
+  background: color-mix(in srgb, var(--accent) 18%, var(--surface));
+  color: var(--accent);
+  font-weight: 600;
+}
+
+/* ranked list — numbered cards for ordered recommendations / findings */
+.ranked-list {
+  display: flex;
+  flex-direction: column;
+  gap: 1em;
+  margin: 0 0 1.5em;
+  padding: 0;
+  list-style: none;
+}
+.ranked-item {
+  background: var(--surface);
+  border: 1.5px solid var(--rule);
+  border-radius: 12px;
+  padding: 22px 26px;
+  display: grid;
+  grid-template-columns: 64px 1fr;
+  gap: 6px 24px;
+  align-items: start;
+}
+.ranked-item .rank-num {
+  font-family: var(--serif);
+  font-size: 2.4rem;
+  font-weight: 500;
+  color: var(--oat);
+  line-height: 1;
+  letter-spacing: -0.02em;
+  padding-top: 2px;
+}
+.ranked-item .rank-title {
+  font-family: var(--serif);
+  font-size: 1.2rem;
+  font-weight: 600;
+  color: var(--ink);
+  margin: 0 0 6px;
+  line-height: 1.3;
+}
+.ranked-item .rank-meta {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  margin-bottom: 14px;
+}
+.ranked-item .rank-body > p {
+  color: var(--ink-soft);
+  font-size: 0.95rem;
+  line-height: 1.65;
+  margin: 0 0 0.85em;
+}
+.ranked-item .rank-body > p:last-child { margin-bottom: 0; }
+.ranked-item .rank-body > ul,
+.ranked-item .rank-body > ol {
+  color: var(--ink-soft);
+  font-size: 0.95rem;
+  line-height: 1.65;
+  margin: 0 0 0.85em;
+  padding-left: 1.2em;
+}
+.ranked-item .rank-aside {
+  color: var(--muted);
+  font-size: 0.9rem;
+  line-height: 1.6;
+  padding-left: 14px;
+  border-left: 2px solid var(--rule);
+  margin: 0;
+}
+.ranked-item .rank-aside-label {
+  font-family: var(--mono);
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin-right: 6px;
+}
 
 /* byline */
 .byline {

package/src/render/validate.ts

@@ -2,6 +2,9 @@
 
 import { parseFragment, defaultTreeAdapter as ta } from "parse5";
 import type { DefaultTreeAdapterTypes } from "parse5";
+import type { Block } from "./blocks/types.ts";
+import { blockCatalog } from "./blocks/catalog.ts";
+import { deepValidateBlock } from "./blocks/validate-block.ts";
 
 type ChildNode = DefaultTreeAdapterTypes.ChildNode;
 type Element = DefaultTreeAdapterTypes.Element;
@@ -407,19 +410,251 @@ export function validateAskInput(input: unknown): AskValidationResult {
   return { ok: true, value: result };
 }
 
-export interface PublishInput {
-  title: string;
-  kind: PublishKind;
-  html: string;
-  summary?: string;
-  tags?: string[];
-  supersedes?: string;
-}
+// ─── PublishInput — supports html XOR blocks ──────────────────────────────────
+
+export type PublishInput =
+  | {
+      title: string;
+      kind: PublishKind;
+      html: string;
+      blocks?: never;
+      summary?: string;
+      tags?: string[];
+      supersedes?: string;
+    }
+  | {
+      title: string;
+      kind: PublishKind;
+      blocks: Block[];
+      html?: never;
+      summary?: string;
+      tags?: string[];
+      supersedes?: string;
+    };
 
 function isPublishKind(val: unknown): val is PublishKind {
   return typeof val === "string" && (PUBLISH_KINDS as readonly string[]).includes(val);
 }
 
+// ─── Block validation ─────────────────────────────────────────────────────────
+
+type BlockValidationError = { path: string; message: string };
+type BlockValidationResult = { ok: true; blocks: Block[] } | { ok: false; errors: BlockValidationError[] };
+
+function validateBlock(raw: unknown, path: string, depth: number): BlockValidationError[] {
+  const errors: BlockValidationError[] = [];
+
+  if (raw === null || typeof raw !== "object") {
+    errors.push({ path, message: "block must be an object" });
+    return errors;
+  }
+
+  const b = raw as Record<string, unknown>;
+  const type = b["type"];
+
+  if (typeof type !== "string") {
+    errors.push({ path, message: "block.type must be a string" });
+    return errors;
+  }
+
+  if (!(type in blockCatalog)) {
+    errors.push({ path, message: `unknown block type: "${type}"` });
+    return errors;
+  }
+
+  // Per-type required field checks
+  switch (type) {
+    case "hero": {
+      if (typeof b["title"] !== "string" || (b["title"] as string).trim() === "") {
+        errors.push({ path, message: "hero block requires a non-empty title" });
+      }
+      break;
+    }
+    case "tldr": {
+      if (typeof b["markdown"] !== "string") {
+        errors.push({ path, message: "tldr block requires markdown field" });
+      }
+      break;
+    }
+    case "section": {
+      if (typeof b["title"] !== "string" || (b["title"] as string).trim() === "") {
+        errors.push({ path, message: "section block requires a non-empty title" });
+      }
+      if (!Array.isArray(b["children"])) {
+        errors.push({ path, message: "section block requires children array" });
+      } else {
+        if (depth > 3) {
+          errors.push({ path, message: `section nesting depth exceeds maximum of 3 (current depth: ${depth})` });
+        } else {
+          const children = b["children"] as unknown[];
+          for (let i = 0; i < children.length; i++) {
+            const childErrors = validateBlock(children[i], `${path}.children[${i}]`, depth + 1);
+            for (const e of childErrors) errors.push(e);
+          }
+        }
+      }
+      break;
+    }
+    case "prose": {
+      if (typeof b["markdown"] !== "string") {
+        errors.push({ path, message: "prose block requires markdown field" });
+      }
+      break;
+    }
+    case "list": {
+      if (!Array.isArray(b["items"])) {
+        errors.push({ path, message: "list block requires items array" });
+      }
+      break;
+    }
+    case "callout": {
+      if (b["variant"] !== "note" && b["variant"] !== "warn" && b["variant"] !== "risk") {
+        errors.push({ path, message: 'callout block requires variant: "note", "warn", or "risk"' });
+      }
+      if (typeof b["markdown"] !== "string") {
+        errors.push({ path, message: "callout block requires markdown field" });
+      }
+      break;
+    }
+    case "code": {
+      if (typeof b["lang"] !== "string" || (b["lang"] as string).trim() === "") {
+        errors.push({ path, message: 'code block requires a non-empty lang (use "text" if unknown)' });
+      }
+      if (typeof b["code"] !== "string") {
+        errors.push({ path, message: "code block requires code field" });
+      }
+      break;
+    }
+    case "timeline": {
+      if (!Array.isArray(b["items"])) {
+        errors.push({ path, message: "timeline block requires items array" });
+      }
+      break;
+    }
+    case "compare_table": {
+      if (!Array.isArray(b["headers"]) || (b["headers"] as unknown[]).length === 0) {
+        errors.push({ path, message: "compare_table block requires non-empty headers array" });
+      } else {
+        const headers = b["headers"] as unknown[];
+        const headerCount = headers.length;
+        if (Array.isArray(b["rows"])) {
+          const rows = b["rows"] as unknown[];
+          for (let i = 0; i < rows.length; i++) {
+            const row = rows[i];
+            if (!Array.isArray(row) || (row as unknown[]).length !== headerCount) {
+              errors.push({
+                path: `${path}.rows[${i}]`,
+                message: `compare_table row has ${Array.isArray(row) ? (row as unknown[]).length : "?"} cells but headers has ${headerCount}`,
+              });
+            }
+          }
+        } else {
+          errors.push({ path, message: "compare_table block requires rows array" });
+        }
+      }
+      break;
+    }
+    case "risk_table": {
+      if (!Array.isArray(b["rows"])) {
+        errors.push({ path, message: "risk_table block requires rows array" });
+      }
+      break;
+    }
+    case "kv": {
+      if (!Array.isArray(b["rows"])) {
+        errors.push({ path, message: "kv block requires rows array" });
+      }
+      break;
+    }
+    case "pill_row": {
+      if (!Array.isArray(b["items"])) {
+        errors.push({ path, message: "pill_row block requires items array" });
+      }
+      break;
+    }
+    case "divider": {
+      // No required fields beyond type
+      break;
+    }
+    case "diagram": {
+      const hasSvg = typeof b["svg"] === "string";
+      const hasHtml = typeof b["html"] === "string";
+      if (hasSvg && hasHtml) {
+        errors.push({ path, message: "diagram block must have exactly one of svg or html, not both" });
+      } else if (!hasSvg && !hasHtml) {
+        errors.push({ path, message: "diagram block requires exactly one of svg or html" });
+      }
+      break;
+    }
+    case "raw_html": {
+      if (typeof b["html"] !== "string" || (b["html"] as string).trim() === "") {
+        errors.push({ path, message: "raw_html block requires non-empty html field" });
+      }
+      break;
+    }
+  }
+
+  // Deep field validation against catalog schema — catches unknown fields (with "did you mean"
+  // suggestions) and bad enum values. Only runs when per-type required checks passed to avoid
+  // duplicating error messages.
+  if (errors.length === 0) {
+    const deepErrors = deepValidateBlock(b, path);
+    for (const e of deepErrors) errors.push(e);
+  }
+
+  return errors;
+}
+
+function validateBlocksArray(raw: unknown): BlockValidationResult {
+  if (!Array.isArray(raw)) {
+    return { ok: false, errors: [{ path: "blocks", message: "blocks must be an array" }] };
+  }
+
+  if (raw.length > 1000) {
+    return { ok: false, errors: [{ path: "blocks", message: "blocks array exceeds maximum of 1000 blocks" }] };
+  }
+
+  const allErrors: BlockValidationError[] = [];
+
+  // Structural checks: at most one hero (must be first), at most one tldr
+  let heroCount = 0;
+  let tldrCount = 0;
+
+  for (let i = 0; i < raw.length; i++) {
+    const block = raw[i] as Record<string, unknown> | null | undefined;
+    const blockType = block !== null && typeof block === "object" ? block["type"] : undefined;
+
+    if (blockType === "hero") {
+      heroCount++;
+      if (i !== 0) {
+        allErrors.push({ path: `blocks[${i}]`, message: "hero block must be the first block if present" });
+      }
+    }
+    if (blockType === "tldr") {
+      tldrCount++;
+    }
+  }
+
+  if (heroCount > 1) {
+    allErrors.push({ path: "blocks", message: "at most one hero block is allowed per document" });
+  }
+  if (tldrCount > 1) {
+    allErrors.push({ path: "blocks", message: "at most one tldr block is allowed per document" });
+  }
+
+  // Per-block validation (depth 1 at root)
+  for (let i = 0; i < raw.length; i++) {
+    const blockErrors = validateBlock(raw[i], `blocks[${i}]`, 1);
+    for (const e of blockErrors) allErrors.push(e);
+  }
+
+  if (allErrors.length > 0) {
+    return { ok: false, errors: allErrors };
+  }
+
+  return { ok: true, blocks: raw as Block[] };
+}
+
 export function validatePublishInput(input: unknown): ValidationResult<PublishInput> {
   if (input === null || typeof input !== "object") {
     return { ok: false, error: "input must be an object" };
@@ -444,11 +679,16 @@ export function validatePublishInput(input: unknown): ValidationResult<PublishIn
   }
   const kind = raw["kind"];
 
-  // html
-  if (!("html" in raw) || typeof raw["html"] !== "string" || raw["html"].trim() === "") {
-    return { ok: false, error: "html is required and must be a non-empty string" };
+  // XOR: exactly one of html or blocks
+  const hasHtml = "html" in raw && raw["html"] !== undefined;
+  const hasBlocks = "blocks" in raw && raw["blocks"] !== undefined;
+
+  if (hasHtml && hasBlocks) {
+    return { ok: false, error: "provide exactly one of html or blocks, not both" };
+  }
+  if (!hasHtml && !hasBlocks) {
+    return { ok: false, error: "provide exactly one of html or blocks" };
   }
-  const html = raw["html"];
 
   // summary (optional)
   if ("summary" in raw && raw["summary"] !== undefined) {
@@ -479,12 +719,37 @@ export function validatePublishInput(input: unknown): ValidationResult<PublishIn
     }
   }
 
-  const result: PublishInput = { title, kind, html };
-  if (typeof raw["summary"] === "string") result.summary = raw["summary"];
-  if (Array.isArray(raw["tags"])) result.tags = raw["tags"] as string[];
-  if (typeof raw["supersedes"] === "string") result.supersedes = raw["supersedes"];
+  const commonFields = {
+    title,
+    kind,
+    ...(typeof raw["summary"] === "string" ? { summary: raw["summary"] } : {}),
+    ...(Array.isArray(raw["tags"]) ? { tags: raw["tags"] as string[] } : {}),
+    ...(typeof raw["supersedes"] === "string" ? { supersedes: raw["supersedes"] } : {}),
+  };
 
-  return { ok: true, value: result };
+  if (hasHtml) {
+    // html branch
+    if (typeof raw["html"] !== "string" || raw["html"].trim() === "") {
+      return { ok: false, error: "html is required and must be a non-empty string" };
+    }
+    return {
+      ok: true,
+      value: { ...commonFields, html: raw["html"] },
+    };
+  } else {
+    // blocks branch
+    const blocksResult = validateBlocksArray(raw["blocks"]);
+    if (!blocksResult.ok) {
+      const errorMessages = blocksResult.errors
+        .map((e) => `${e.path}: ${e.message}`)
+        .join("; ");
+      return { ok: false, error: `blocks validation failed — ${errorMessages}` };
+    }
+    return {
+      ok: true,
+      value: { ...commonFields, blocks: blocksResult.blocks },
+    };
+  }
 }
 
 const HEADING_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);

package/src/render/wrap.ts

@@ -1,6 +1,7 @@
 // Assembles the full <!doctype html> document from a body fragment + metadata.
 
-import { frameworkRulesCss, themeTokensCss, type ThemeTokens } from "./theme.ts";
+import { type ThemeTokens } from "./theme.ts";
+import { fallbackCss } from "./fallback.ts";
 import { renderControl, renderAnswered } from "./controls.ts";
 import { getClientJs } from "./client-js.ts";
 import { faviconLinkTag } from "./favicon.ts";
@@ -24,6 +25,7 @@ export interface ArtifactMeta {
   supersedes: string | null;
   supersededBy: string | null;
   contentSha256: string;
+  inputMode: "html" | "blocks";
 }
 
 export interface WrapOptions {
@@ -129,7 +131,7 @@ function renderFooter(meta: ArtifactMeta): string {
 }
 
 export function wrapDocument(opts: WrapOptions): string {
-  const { body, meta, theme, warnings = [], interactive } = opts;
+  const { body, meta, warnings = [], interactive } = opts;
   // Default href: artifact context (three levels deep from stateDir)
   const href =
     opts.themeCssHref === undefined
@@ -140,8 +142,7 @@ export function wrapDocument(opts: WrapOptions): string {
   // Suppress <link> when null is explicitly passed
   const suppressLink = opts.themeCssHref === null;
 
-  const rules = frameworkRulesCss();
-  const tokens = themeTokensCss(theme);
+  const fallback = fallbackCss();
   // Embed interactive into the cesium-meta JSON block when present
   const metaPayload: Record<string, unknown> = { ...meta };
   if (interactive !== undefined) {
@@ -171,9 +172,8 @@ export function wrapDocument(opts: WrapOptions): string {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${titleEsc} · cesium</title>
-  <style>${rules}
-/* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}</style>${linkTag}${faviconTag}
+  <style>/* fallback — standalone-readable; full styles served from /theme.css */
+${fallback}</style>${linkTag}${faviconTag}
   <script type="application/json" id="cesium-meta">${metaJson}</script>
 </head>
 <body>

package/src/server/lifecycle.ts

@@ -7,6 +7,8 @@ import { startServer, type ServerHandle } from "./http.ts";
 import { acquireLock } from "../storage/lock.ts";
 import { createApiHandler } from "./api.ts";
 import { createFaviconHandler } from "./favicon.ts";
+import { ensureThemeCss } from "../storage/assets.ts";
+import { defaultTheme, type ThemeTokens } from "../render/theme.ts";
 
 export interface LifecycleConfig {
   stateDir: string;
@@ -14,6 +16,7 @@ export interface LifecycleConfig {
   portMax: number; // upper bound (inclusive)
   idleTimeoutMs: number;
   hostname?: string; // default "127.0.0.1"
+  theme?: ThemeTokens; // default: defaultTheme()
 }
 
 export interface RunningInfo {
@@ -200,7 +203,7 @@ export async function stopRunning(stateDir: string): Promise<void> {
 }
 
 export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo> {
-  const { stateDir, port, portMax, idleTimeoutMs, hostname = "127.0.0.1" } = cfg;
+  const { stateDir, port, portMax, idleTimeoutMs, hostname = "127.0.0.1", theme = defaultTheme() } = cfg;
   const pidFilePath = join(stateDir, ".server.pid");
   const lockPath = join(stateDir, ".server-start.lock");
 
@@ -259,6 +262,9 @@ export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo>
     const handle = await tryBindPort(port);
     const boundPort = handle.port;
 
+    // Materialize theme.css before serving — self-heals on plugin upgrade
+    await ensureThemeCss(stateDir, theme);
+
     // Wire API handler before static file fallback
     handle.addHandler(createApiHandler({ stateDir }));
     // /favicon.ico shim — browsers auto-request this even when the page