@cfbender/cesium 0.5.0 → 0.5.2

package/src/render/blocks/themes/claret-light.ts

@@ -0,0 +1,222 @@
+// Claret-light shiki theme — derived from claret.nvim light palette.
+// src/render/blocks/themes/claret-light.ts
+//
+// Source of truth: /claret.nvim/lua/claret/palette.lua (light section)
+// Scope-to-role mapping mirrors ClaretDark.tmTheme exactly; colors
+// are substituted from the light palette using the same semantic roles.
+//
+// Light palette (palette.lua):
+//   bg         #F5E6E2   editor background
+//   bg_mute    #DDD0CC   selection / line highlight
+//   text       #2A1F1A   default fg
+//   text_4     #928578   comment / gutter fg
+//   rose_1     #B80842   keyword / heading / statement
+//   rose_2     #920820   property / data keys
+//   gold_1     #946000   function / number / constant / decorator
+//   sage_1     #1B5500   string
+//   slate_1    #0E3088   type / class / tag / escape / link
+//   slate_2    #0A2575   tag attribute
+//   terra_1    #D42010   invalid / diff deleted
+//
+// Role mapping (matching dark tmTheme):
+//   Comment       → text_4   #928578   italic
+//   Keyword       → rose_1   #B80842
+//   Function      → gold_1   #946000
+//   String        → sage_1   #1B5500
+//   Number        → gold_1   #946000
+//   Constant      → gold_1   #946000
+//   Type          → slate_1  #0E3088
+//   Variable      → text     #2A1F1A
+//   Parameter     → text     #2A1F1A   italic
+//   Property      → rose_2   #920820
+//   Keys          → rose_2   #920820
+//   Operator      → text_4   #928578   (text_3 equivalent; nearest warm muted in light palette)
+//   Punctuation   → text_4   #928578
+//   Decorator     → gold_1   #946000   italic
+//   Tag           → slate_1  #0E3088
+//   Tag Attribute → slate_2  #0A2575
+//   Invalid       → terra_1  #D42010
+//   Escape        → slate_1  #0E3088
+//   Markup Heading→ rose_1   #B80842   bold
+//   Markup Bold   → (no fg)            bold
+//   Markup Italic → (no fg)            italic
+//   Markup Link   → slate_1  #0E3088
+//   Diff Added    → sage_1   #1B5500
+//   Diff Deleted  → terra_1  #D42010
+//   Diff Changed  → gold_1   #946000
+
+import type { ThemeRegistration } from "shiki";
+
+export const claretLight: ThemeRegistration = {
+  name: "claret-light",
+  type: "light",
+  fg: "#2A1F1A",
+  bg: "#F5E6E2",
+  colors: {
+    "editor.foreground": "#2A1F1A",
+    "editor.background": "#F5E6E2",
+    "editor.selectionBackground": "#DDD0CC",
+    "editor.lineHighlightBackground": "#DDD0CC",
+    "editorLineNumber.foreground": "#928578",
+  },
+  tokenColors: [
+    // Comment — #928578 italic
+    {
+      name: "Comment",
+      scope: ["comment", "punctuation.definition.comment"],
+      settings: { foreground: "#928578", fontStyle: "italic" },
+    },
+    // Keyword — #B80842
+    {
+      name: "Keyword",
+      scope: ["keyword", "storage.type", "storage.modifier"],
+      settings: { foreground: "#B80842" },
+    },
+    // Function — #946000
+    {
+      name: "Function",
+      scope: ["entity.name.function", "support.function"],
+      settings: { foreground: "#946000" },
+    },
+    // String — #1B5500
+    {
+      name: "String",
+      scope: ["string", "punctuation.definition.string"],
+      settings: { foreground: "#1B5500" },
+    },
+    // Number — #946000
+    {
+      name: "Number",
+      scope: ["constant.numeric"],
+      settings: { foreground: "#946000" },
+    },
+    // Constant — #946000
+    {
+      name: "Constant",
+      scope: ["constant", "constant.language", "variable.language"],
+      settings: { foreground: "#946000" },
+    },
+    // Type — #0E3088
+    {
+      name: "Type",
+      scope: ["entity.name.type", "entity.name.class", "support.type", "support.class"],
+      settings: { foreground: "#0E3088" },
+    },
+    // Variable — #2A1F1A
+    {
+      name: "Variable",
+      scope: ["variable", "variable.parameter"],
+      settings: { foreground: "#2A1F1A" },
+    },
+    // Parameter — #2A1F1A italic (overrides Variable for parameters)
+    {
+      name: "Parameter",
+      scope: ["variable.parameter"],
+      settings: { foreground: "#2A1F1A", fontStyle: "italic" },
+    },
+    // Property — #920820
+    {
+      name: "Property",
+      scope: ["variable.other.property", "variable.other.member"],
+      settings: { foreground: "#920820" },
+    },
+    // JSON/YAML/TOML Keys — #920820
+    {
+      name: "JSON/YAML/TOML Keys",
+      scope: [
+        "meta.mapping.key string",
+        "support.type.property-name.json",
+        "punctuation.support.type.property-name.json",
+        "support.type.property-name.toml",
+        "punctuation.support.type.property-name.toml",
+        "entity.name.tag.yaml",
+        "support.type.property-name.yaml",
+      ],
+      settings: { foreground: "#920820" },
+    },
+    // Operator — #928578
+    {
+      name: "Operator",
+      scope: ["keyword.operator"],
+      settings: { foreground: "#928578" },
+    },
+    // Punctuation — #928578
+    {
+      name: "Punctuation",
+      scope: ["punctuation"],
+      settings: { foreground: "#928578" },
+    },
+    // Decorator — #946000 italic
+    {
+      name: "Decorator",
+      scope: ["meta.decorator", "punctuation.decorator"],
+      settings: { foreground: "#946000", fontStyle: "italic" },
+    },
+    // Tag — #0E3088
+    {
+      name: "Tag",
+      scope: ["entity.name.tag"],
+      settings: { foreground: "#0E3088" },
+    },
+    // Tag Attribute — #0A2575
+    {
+      name: "Tag Attribute",
+      scope: ["entity.other.attribute-name"],
+      settings: { foreground: "#0A2575" },
+    },
+    // Invalid — #D42010
+    {
+      name: "Invalid",
+      scope: ["invalid", "invalid.illegal"],
+      settings: { foreground: "#D42010" },
+    },
+    // Escape — #0E3088
+    {
+      name: "Escape",
+      scope: ["constant.character.escape"],
+      settings: { foreground: "#0E3088" },
+    },
+    // Markup Heading — #B80842 bold
+    {
+      name: "Markup Heading",
+      scope: ["markup.heading"],
+      settings: { foreground: "#B80842", fontStyle: "bold" },
+    },
+    // Markup Bold — bold (no color override)
+    {
+      name: "Markup Bold",
+      scope: ["markup.bold"],
+      settings: { fontStyle: "bold" },
+    },
+    // Markup Italic — italic (no color override)
+    {
+      name: "Markup Italic",
+      scope: ["markup.italic"],
+      settings: { fontStyle: "italic" },
+    },
+    // Markup Link — #0E3088
+    {
+      name: "Markup Link",
+      scope: ["markup.underline.link", "string.other.link"],
+      settings: { foreground: "#0E3088" },
+    },
+    // Diff Added — #1B5500
+    {
+      name: "Diff Added",
+      scope: ["markup.inserted"],
+      settings: { foreground: "#1B5500" },
+    },
+    // Diff Deleted — #D42010
+    {
+      name: "Diff Deleted",
+      scope: ["markup.deleted"],
+      settings: { foreground: "#D42010" },
+    },
+    // Diff Changed — #946000
+    {
+      name: "Diff Changed",
+      scope: ["markup.changed"],
+      settings: { foreground: "#946000" },
+    },
+  ],
+};

package/src/render/blocks/types.ts

@@ -16,7 +16,8 @@ export type Block =
   | PillRowBlock
   | DividerBlock
   | DiagramBlock
-  | RawHtmlBlock;
+  | RawHtmlBlock
+  | DiffBlock;
 
 export type HeroBlock = {
   type: "hero";
@@ -116,6 +117,17 @@ export type RawHtmlBlock = {
   purpose?: string; // brief reason; surfaced in critique findings
 };
 
+export type DiffBlock = {
+  type: "diff";
+  // Provide exactly one of these arms:
+  patch?: string; // unified diff format
+  before?: string; // OR
+  after?: string; //   (paired with before)
+  lang?: string; // for per-line shiki highlight; default "text"
+  filename?: string; // optional, shown in header strip
+  caption?: string; // optional, shown below the diff
+};
+
 // ─── BlockMeta ───────────────────────────────────────────────────────────────
 
 export type BlockMeta = {

package/src/render/blocks/validate-block.ts

@@ -23,11 +23,7 @@ function levenshtein(a: string, b: string): number {
     curr[0] = i;
     for (let j = 1; j <= bLen; j++) {
       const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(
-        (prev[j] ?? 0) + 1,
-        (curr[j - 1] ?? 0) + 1,
-        (prev[j - 1] ?? 0) + cost,
-      );
+      curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
     }
     [prev, curr] = [curr, prev];
   }
@@ -91,11 +87,19 @@ function isSchemaNode(v: unknown): v is SchemaNode {
  * Validate a single value against a JSON Schema fragment node.
  * Appends any findings to `errors`. `path` is the dotted path for error messages.
  */
-function validateNode(value: unknown, schema: SchemaNode, path: string, errors: BlockFieldError[]): void {
+function validateNode(
+  value: unknown,
+  schema: SchemaNode,
+  path: string,
+  errors: BlockFieldError[],
+): void {
   // const node
   if ("const" in schema) {
     if (value !== schema.const) {
-      errors.push({ path, message: `expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}` });
+      errors.push({
+        path,
+        message: `expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`,
+      });
     }
     return;
   }
@@ -143,7 +147,10 @@ function validateNode(value: unknown, schema: SchemaNode, path: string, errors:
     }
     case "object": {
       if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        errors.push({ path, message: `expected object, got ${Array.isArray(value) ? "array" : typeof value}` });
+        errors.push({
+          path,
+          message: `expected object, got ${Array.isArray(value) ? "array" : typeof value}`,
+        });
         return;
       }
       const obj = value as Record<string, unknown>;
@@ -171,7 +178,10 @@ function validateNode(value: unknown, schema: SchemaNode, path: string, errors:
             // Unknown field — suggest closest known
             const suggestion = didYouMean(key, knownKeys);
             const suggestionMsg = suggestion !== null ? `; did you mean "${suggestion}"?` : "";
-            errors.push({ path: `${path}.${key}`, message: `unknown field "${key}"${suggestionMsg}` });
+            errors.push({
+              path: `${path}.${key}`,
+              message: `unknown field "${key}"${suggestionMsg}`,
+            });
           } else if (isSchemaNode(propSchema)) {
             validateNode(val, propSchema, `${path}.${key}`, errors);
           }

package/src/render/theme.ts

@@ -13,6 +13,9 @@ export interface ThemePalette {
   olive: string;
   codeBg: string;
   codeFg: string;
+  diffAdd: string; // line-tint and connector color for additions
+  diffRemove: string; // line-tint and connector color for deletions
+  diffChange: string; // connector color for replacements
 }
 
 export interface ThemeFonts {
@@ -56,6 +59,9 @@ export const THEME_PRESETS: Readonly<Record<ThemePresetName, ThemePalette>> = {
     olive: "#8FA86E",
     codeBg: "#2B1F22",
     codeFg: "#DDD3C7",
+    diffAdd: "#6D9E60",
+    diffRemove: "#C75B5B",
+    diffChange: "#D4A85A",
   },
   // claret-light: deep-rose-on-warm-cream — derived from claret.nvim light palette.
   // (this is the old "claret" palette, now renamed)
@@ -72,6 +78,9 @@ export const THEME_PRESETS: Readonly<Record<ThemePresetName, ThemePalette>> = {
     olive: "#5A6B40",
     codeBg: "#180810",
     codeFg: "#DDD3C7",
+    diffAdd: "#5A6B40",
+    diffRemove: "#9E3838",
+    diffChange: "#B07A2A",
   },
   // claret: alias for claret-dark (backward compat)
   claret: {
@@ -87,6 +96,9 @@ export const THEME_PRESETS: Readonly<Record<ThemePresetName, ThemePalette>> = {
     olive: "#8FA86E",
     codeBg: "#2B1F22",
     codeFg: "#DDD3C7",
+    diffAdd: "#6D9E60",
+    diffRemove: "#C75B5B",
+    diffChange: "#D4A85A",
   },
   // Warm: ivory/clay/oat — the html-effectiveness reference palette.
   warm: {
@@ -102,6 +114,9 @@ export const THEME_PRESETS: Readonly<Record<ThemePresetName, ThemePalette>> = {
     olive: "#788C5D",
     codeBg: "#141413",
     codeFg: "#E8E6DE",
+    diffAdd: "#788C5D",
+    diffRemove: "#C0392B",
+    diffChange: "#D97757",
   },
   // Cool: desaturated blue-grey — technical, trustworthy.
   cool: {
@@ -117,6 +132,9 @@ export const THEME_PRESETS: Readonly<Record<ThemePresetName, ThemePalette>> = {
     olive: "#4E8A6A",
     codeBg: "#1B2333",
     codeFg: "#D8E0ED",
+    diffAdd: "#4E8A6A",
+    diffRemove: "#B6443A",
+    diffChange: "#3A7BB8",
   },
   // Mono: black/white/grey — editorial, high-contrast.
   mono: {
@@ -132,6 +150,9 @@ export const THEME_PRESETS: Readonly<Record<ThemePresetName, ThemePalette>> = {
     olive: "#5A7A5A",
     codeBg: "#111111",
     codeFg: "#EBEBEB",
+    diffAdd: "#5A7A5A",
+    diffRemove: "#A03A2B",
+    diffChange: "#666666",
   },
   // Paper: sepia/cream — soft, book-like, warm and aged.
   paper: {
@@ -147,6 +168,9 @@ export const THEME_PRESETS: Readonly<Record<ThemePresetName, ThemePalette>> = {
     olive: "#607848",
     codeBg: "#2A2218",
     codeFg: "#E8DEC8",
+    diffAdd: "#607848",
+    diffRemove: "#A0392B",
+    diffChange: "#B05A2A",
   },
 };
 
@@ -198,6 +222,9 @@ export function themeToCssVars(theme: ThemeTokens): string {
   --olive: ${colors.olive};
   --code-bg: ${colors.codeBg};
   --code-fg: ${colors.codeFg};
+  --diff-add: ${colors.diffAdd};
+  --diff-remove: ${colors.diffRemove};
+  --diff-change: ${colors.diffChange};
   --serif: ${fonts.serif};
   --sans: ${fonts.sans};
   --mono: ${fonts.mono};
@@ -936,6 +963,110 @@ textarea.cs-text { font-family: var(--mono); }
   font-weight: 600;
   z-index: 10;
 }
+
+/* diff block */
+.diff-block {
+  margin: var(--space-6, 1.5rem) 0;
+  border: 1.5px solid var(--rule);
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--code-bg);
+  font-family: var(--mono);
+  font-size: 13px;
+  color: var(--code-fg);
+}
+.diff-block.fallback pre {
+  margin: 0;
+  padding: 12px 14px;
+  white-space: pre;
+  overflow-x: auto;
+}
+.diff-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 14px;
+  border-bottom: 1px solid color-mix(in oklab, var(--rule), transparent 40%);
+  background: color-mix(in oklab, var(--code-bg), var(--code-fg) 5%);
+  font-size: 12px;
+  color: color-mix(in oklab, var(--code-fg), transparent 30%);
+}
+.diff-filename { font-weight: 500; }
+.diff-stat { font-variant-numeric: tabular-nums; display: inline-flex; gap: 8px; }
+.diff-stat .add { color: var(--diff-add); }
+.diff-stat .rem { color: var(--diff-remove); }
+
+.diff-grid {
+  display: grid;
+  grid-template-columns: 1fr 60px 1fr;
+  align-items: start;
+}
+.diff-side {
+  list-style: none;
+  margin: 0;
+  padding: 8px 0;
+  overflow-x: auto;
+  min-width: 0;
+}
+.diff-line {
+  display: grid;
+  grid-template-columns: 3.25em 1fr;
+  gap: 0;
+  height: 22px;
+  line-height: 22px;
+  white-space: pre;
+}
+.diff-line .num {
+  text-align: right;
+  padding-right: 12px;
+  color: color-mix(in oklab, var(--code-fg), transparent 60%);
+  user-select: none;
+  font-variant-numeric: tabular-nums;
+}
+.diff-line .content {
+  padding-right: 14px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.diff-line.add  { background: color-mix(in oklab, transparent, var(--diff-add) 14%); }
+.diff-line.remove { background: color-mix(in oklab, transparent, var(--diff-remove) 14%); }
+.diff-line.hunk-sep {
+  background: color-mix(in oklab, var(--code-bg), var(--code-fg) 8%);
+  color: color-mix(in oklab, var(--code-fg), transparent 50%);
+  font-style: italic;
+  font-size: 11px;
+}
+
+.diff-connector {
+  position: relative;
+  align-self: stretch;
+  padding: 8px 0;
+  background: color-mix(in oklab, var(--code-bg), var(--code-fg) 2%);
+  border-left: 1px solid color-mix(in oklab, var(--rule), transparent 60%);
+  border-right: 1px solid color-mix(in oklab, var(--rule), transparent 60%);
+}
+.diff-connector svg {
+  display: block;
+  width: 100%;
+}
+.diff-conn { stroke-width: 1; }
+.diff-conn.add    { fill: var(--diff-add);    stroke: var(--diff-add);    fill-opacity: 0.22; }
+.diff-conn.remove { fill: var(--diff-remove); stroke: var(--diff-remove); fill-opacity: 0.22; }
+.diff-conn.change { fill: var(--diff-change); stroke: var(--diff-change); fill-opacity: 0.18; }
+
+.diff-block figcaption {
+  padding: 8px 14px;
+  border-top: 1px solid color-mix(in oklab, var(--rule), transparent 40%);
+  font-size: 12px;
+  font-family: var(--sans);
+  color: color-mix(in oklab, var(--code-fg), transparent 30%);
+}
+
+@media (max-width: 720px) {
+  .diff-grid { grid-template-columns: 1fr; }
+  .diff-connector { display: none; }
+  .diff-side.before { border-bottom: 1px solid color-mix(in oklab, var(--rule), transparent 60%); }
+}
 `;
 }
 

package/src/render/validate.ts

@@ -439,7 +439,9 @@ function isPublishKind(val: unknown): val is PublishKind {
 // ─── Block validation ─────────────────────────────────────────────────────────
 
 type BlockValidationError = { path: string; message: string };
-type BlockValidationResult = { ok: true; blocks: Block[] } | { ok: false; errors: BlockValidationError[] };
+type BlockValidationResult =
+  | { ok: true; blocks: Block[] }
+  | { ok: false; errors: BlockValidationError[] };
 
 function validateBlock(raw: unknown, path: string, depth: number): BlockValidationError[] {
   const errors: BlockValidationError[] = [];
@@ -484,7 +486,10 @@ function validateBlock(raw: unknown, path: string, depth: number): BlockValidati
         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})` });
+          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++) {
@@ -518,7 +523,10 @@ function validateBlock(raw: unknown, path: string, depth: number): BlockValidati
     }
     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)' });
+        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" });
@@ -580,7 +588,10 @@ function validateBlock(raw: unknown, path: string, depth: number): BlockValidati
       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" });
+        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" });
       }
@@ -592,6 +603,35 @@ function validateBlock(raw: unknown, path: string, depth: number): BlockValidati
       }
       break;
     }
+    case "diff": {
+      const hasPatch = "patch" in b && b["patch"] !== undefined;
+      const hasBefore = "before" in b && b["before"] !== undefined;
+      const hasAfter = "after" in b && b["after"] !== undefined;
+
+      if (hasPatch && (hasBefore || hasAfter)) {
+        errors.push({
+          path,
+          message: "provide exactly one of patch or before/after, not both",
+        });
+      } else if (!hasPatch && !hasBefore && !hasAfter) {
+        errors.push({
+          path,
+          message: "diff block requires either patch or before+after",
+        });
+      } else if (hasPatch) {
+        if (typeof b["patch"] !== "string" || (b["patch"] as string).trim() === "") {
+          errors.push({ path, message: "diff block patch must be a non-empty string" });
+        }
+      } else {
+        // before/after arm
+        if (hasBefore && !hasAfter) {
+          errors.push({ path, message: "diff block before/after arm requires both fields" });
+        } else if (!hasBefore && hasAfter) {
+          errors.push({ path, message: "diff block before/after arm requires both fields" });
+        }
+      }
+      break;
+    }
   }
 
   // Deep field validation against catalog schema — catches unknown fields (with "did you mean"
@@ -611,7 +651,10 @@ function validateBlocksArray(raw: unknown): BlockValidationResult {
   }
 
   if (raw.length > 1000) {
-    return { ok: false, errors: [{ path: "blocks", message: "blocks array exceeds maximum of 1000 blocks" }] };
+    return {
+      ok: false,
+      errors: [{ path: "blocks", message: "blocks array exceeds maximum of 1000 blocks" }],
+    };
   }
 
   const allErrors: BlockValidationError[] = [];
@@ -627,7 +670,10 @@ function validateBlocksArray(raw: unknown): BlockValidationResult {
     if (blockType === "hero") {
       heroCount++;
       if (i !== 0) {
-        allErrors.push({ path: `blocks[${i}]`, message: "hero block must be the first block if present" });
+        allErrors.push({
+          path: `blocks[${i}]`,
+          message: "hero block must be the first block if present",
+        });
       }
     }
     if (blockType === "tldr") {
@@ -740,9 +786,7 @@ export function validatePublishInput(input: unknown): ValidationResult<PublishIn
     // blocks branch
     const blocksResult = validateBlocksArray(raw["blocks"]);
     if (!blocksResult.ok) {
-      const errorMessages = blocksResult.errors
-        .map((e) => `${e.path}: ${e.message}`)
-        .join("; ");
+      const errorMessages = blocksResult.errors.map((e) => `${e.path}: ${e.message}`).join("; ");
       return { ok: false, error: `blocks validation failed — ${errorMessages}` };
     }
     return {