@cfbender/cesium 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v0.3.6 — 2026-05-11
+
+Adds a periodic-table-themed favicon for the cesium HTTP server.
+
+- **feat:** Element-55 ("Cs") periodic-table tile favicon in the claret-dark
+  palette. Source SVG at `assets/favicon.svg`.
+- **feat:** `writeFaviconSvg` drops `<stateDir>/favicon.svg` next to
+  `theme.css` on every publish/ask (and on `cesium theme apply`). The static
+  HTTP server then serves it at `/favicon.svg`.
+- **feat:** `<link rel="icon" type="image/svg+xml">` is now emitted in
+  artifact pages, project index pages, and the global index page (paths
+  derived from the existing theme.css href so suppression behavior matches).
+- **feat:** Inline favicon emblem rendered next to the "cesium" / "cesium ·
+  project" eyebrow on both index pages.
+- **feat:** `/favicon.ico` shim — server pre-handler serves the SVG bytes
+  with `image/svg+xml` content type so browsers that auto-request the legacy
+  `.ico` path don't see a 404.
+
 ## v0.3.5 — 2026-05-11
 
 Fixes the `Publish to npm` GitHub Action.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "license": "MIT",
   "author": "Cody Bender",

package/src/cli/commands/theme.ts

@@ -10,6 +10,7 @@ import {
   type ThemePalette,
 } from "../../render/theme.ts";
 import { writeThemeCss, themeCssPath } from "../../storage/theme-write.ts";
+import { writeFaviconSvg } from "../../storage/favicon-write.ts";
 import { themeTokensCss } from "../../render/theme.ts";
 import { atomicWrite } from "../../storage/write.ts";
 import { readdir } from "node:fs/promises";
@@ -307,6 +308,7 @@ async function themeApplyCommand(argv: string[], ctx: ThemeContext): Promise<num
   const cfg = (ctx.loadConfig ?? loadConfig)();
   const { theme, presetLabel } = resolveTheme(cfg);
   const cssPath = await writeThemeCss(cfg.stateDir, theme);
+  await writeFaviconSvg(cfg.stateDir);
 
   if (values["rewrite-artifacts"]) {
     const { artifacts, indexes } = await retrofitAll(cfg.stateDir, ctx.stdout);

package/src/render/critique.ts

@@ -39,7 +39,7 @@ export interface CritiqueResult {
 const HTTP_RE = /^https?:\/\//i;
 
 /** The only cesium-* class the framework ships with. All others are unknown. */
-const KNOWN_CESIUM_CLASSES = new Set(["cesium-back"]);
+const KNOWN_CESIUM_CLASSES = new Set(["cesium-back", "cesium-eyebrow"]);
 
 /** Callout severity modifiers — a callout needs at least one of these. */
 const CALLOUT_MODIFIERS = new Set(["note", "warn", "risk"]);

package/src/render/favicon.ts

@@ -0,0 +1,56 @@
+// Cesium favicon — periodic-table tile, element 55 ("Cs"), claret-dark palette.
+//
+// The SVG is theme-independent (always claret-dark wine + rose) so it stays
+// recognizable as the cesium emblem regardless of the user's chosen theme.
+//
+// Two consumers:
+//   1. `writeFaviconSvg` writes this string to <stateDir>/favicon.svg, which
+//      is then referenced by <link rel="icon"> in artifact + index pages and
+//      auto-served by the cesium HTTP server.
+//   2. `faviconEmblemSvg` returns inline SVG markup suitable for placing next
+//      to the "cesium" eyebrow on index pages (no <?xml?> declaration, no
+//      role/aria — those are decorative chrome).
+
+/** The full standalone favicon SVG written to <stateDir>/favicon.svg. */
+export const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Cesium — element 55">
+  <!-- Periodic table tile, claret-dark palette -->
+  <rect x="2" y="2" width="60" height="60" rx="10" ry="10" fill="#180810"/>
+  <rect x="2.75" y="2.75" width="58.5" height="58.5" rx="9.25" ry="9.25"
+        fill="none" stroke="#C75B7A" stroke-width="1.5"/>
+
+  <!-- Atomic number, top-left -->
+  <text x="8" y="18" fill="#C75B7A"
+        font-family="ui-monospace, 'SF Mono', Menlo, Monaco, monospace"
+        font-size="13" font-weight="700" letter-spacing="0.5">55</text>
+
+  <!-- Element symbol, centered -->
+  <text x="32" y="48" fill="#DDD3C7" text-anchor="middle"
+        font-family="Georgia, 'Times New Roman', serif"
+        font-size="36" font-weight="700" letter-spacing="-1">Cs</text>
+</svg>
+`;
+
+/** Inline SVG emblem for placing next to the "cesium" eyebrow text.
+ *  Decorative — uses aria-hidden so screen readers skip it (the text label
+ *  next to it already says "cesium").
+ *
+ *  @param size — pixel size for both width and height. Defaults to 18.
+ */
+export function faviconEmblemSvg(size = 18): string {
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="${size}" height="${size}" aria-hidden="true" focusable="false" style="display:inline-block;vertical-align:-3px;flex-shrink:0;">
+  <rect x="2" y="2" width="60" height="60" rx="10" ry="10" fill="#180810"/>
+  <rect x="2.75" y="2.75" width="58.5" height="58.5" rx="9.25" ry="9.25" fill="none" stroke="#C75B7A" stroke-width="1.5"/>
+  <text x="8" y="18" fill="#C75B7A" font-family="ui-monospace, 'SF Mono', Menlo, Monaco, monospace" font-size="13" font-weight="700" letter-spacing="0.5">55</text>
+  <text x="32" y="48" fill="#DDD3C7" text-anchor="middle" font-family="Georgia, 'Times New Roman', serif" font-size="36" font-weight="700" letter-spacing="-1">Cs</text>
+</svg>`;
+}
+
+/** Returns the <link rel="icon"> tag for an HTML head, given a relative href.
+ *
+ *  - Artifact pages (3 levels deep): href = "../../../favicon.svg"
+ *  - Project index (2 levels deep):  href = "../../favicon.svg"
+ *  - Global index (root):            href = "favicon.svg"
+ */
+export function faviconLinkTag(href: string): string {
+  return `<link rel="icon" type="image/svg+xml" href="${href}">`;
+}

package/src/render/wrap.ts

@@ -3,6 +3,7 @@
 import { frameworkRulesCss, themeTokensCss, type ThemeTokens } from "./theme.ts";
 import { renderControl, renderAnswered } from "./controls.ts";
 import { getClientJs } from "./client-js.ts";
+import { faviconLinkTag } from "./favicon.ts";
 import type { InteractiveData, Question } from "./validate.ts";
 
 export interface ArtifactMeta {
@@ -47,6 +48,20 @@ function escapeHtml(str: string): string {
     .replace(/"/g, """);
 }
 
+/** Derives the favicon href from the theme.css href.
+ *
+ *  Both files live in the stateDir root, so the relative depth is identical:
+ *  swap the trailing "theme.css" segment for "favicon.svg". For atypical
+ *  themeCssHref values (absolute URLs, paths without "theme.css" suffix), fall
+ *  back to the artifact-context default.
+ */
+function deriveFaviconHref(themeCssHref: string): string {
+  if (themeCssHref.endsWith("theme.css")) {
+    return themeCssHref.slice(0, -"theme.css".length) + "favicon.svg";
+  }
+  return "../../../favicon.svg";
+}
+
 function safeJsonForScript(obj: unknown): string {
   return JSON.stringify(obj, null, 2).replace(/<\/script>/gi, "<\\/script>");
 }
@@ -145,6 +160,10 @@ export function wrapDocument(opts: WrapOptions): string {
       : "";
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
+  // Favicon path mirrors the theme.css path: artifacts live three levels deep
+  // in <stateDir>/projects/<slug>/artifacts/, so favicon.svg is "../../../".
+  // When suppressed (standalone/test mode), we suppress favicon too.
+  const faviconTag = suppressLink ? "" : `\n  ${faviconLinkTag(deriveFaviconHref(href ?? ""))}`;
 
   return `<!doctype html>
 <html lang="en">
@@ -154,7 +173,7 @@ export function wrapDocument(opts: WrapOptions): string {
   <title>${titleEsc} · cesium</title>
   <style>${rules}
 /* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}</style>${linkTag}
+${tokens}</style>${linkTag}${faviconTag}
   <script type="application/json" id="cesium-meta">${metaJson}</script>
 </head>
 <body>

package/src/server/favicon.ts

@@ -0,0 +1,28 @@
+// Favicon shim handler — serves the cesium favicon at /favicon.ico (the legacy
+// path browsers request automatically) by returning the in-memory SVG bytes
+// with image/svg+xml content type. All evergreen browsers accept SVG favicons
+// regardless of the URL extension.
+//
+// The static server already serves /favicon.svg from <stateDir>/favicon.svg
+// (written by writeFaviconSvg on every publish). This shim covers the .ico
+// fallback so users don't see a 404 in DevTools.
+
+import { FAVICON_SVG } from "../render/favicon.ts";
+
+const SVG_RESPONSE_HEADERS: Record<string, string> = {
+  "Content-Type": "image/svg+xml; charset=utf-8",
+  "Cache-Control": "public, max-age=86400",
+};
+
+export function createFaviconHandler(): (req: Request) => Promise<Response | undefined> {
+  return async (req: Request): Promise<Response | undefined> => {
+    const url = new URL(req.url);
+    if (url.pathname !== "/favicon.ico") {
+      return undefined;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      return undefined;
+    }
+    return new Response(FAVICON_SVG, { status: 200, headers: SVG_RESPONSE_HEADERS });
+  };
+}

package/src/server/lifecycle.ts

@@ -6,6 +6,7 @@ import { unlink, writeFile } from "node:fs/promises";
 import { startServer, type ServerHandle } from "./http.ts";
 import { acquireLock } from "../storage/lock.ts";
 import { createApiHandler } from "./api.ts";
+import { createFaviconHandler } from "./favicon.ts";
 
 export interface LifecycleConfig {
   stateDir: string;
@@ -260,6 +261,9 @@ export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo>
 
     // Wire API handler before static file fallback
     handle.addHandler(createApiHandler({ stateDir }));
+    // /favicon.ico shim — browsers auto-request this even when the page
+    // declares an SVG favicon. Serve the SVG bytes inline so we don't 404.
+    handle.addHandler(createFaviconHandler());
 
     const startedAt = new Date().toISOString();
 

package/src/storage/favicon-write.ts

@@ -0,0 +1,23 @@
+// Writes favicon.svg to the state directory.
+//
+// Mirrors theme-write.ts: produces a single static asset alongside theme.css
+// that artifact pages and index pages reference via relative <link rel="icon">.
+// The cesium HTTP server serves it automatically because the state dir is the
+// server's static root.
+
+import { join } from "node:path";
+import { FAVICON_SVG } from "../render/favicon.ts";
+import { atomicWrite } from "./write.ts";
+
+/** Returns the absolute path to favicon.svg in the given stateDir. */
+export function faviconSvgPath(stateDir: string): string {
+  return join(stateDir, "favicon.svg");
+}
+
+/** Writes <stateDir>/favicon.svg. Atomic. Returns the absolute path.
+ *  Idempotent — content is theme-independent so writing twice is a no-op. */
+export async function writeFaviconSvg(stateDir: string): Promise<string> {
+  const path = faviconSvgPath(stateDir);
+  await atomicWrite(path, FAVICON_SVG);
+  return path;
+}

package/src/storage/index-gen.ts

@@ -3,6 +3,7 @@
 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";
 
 export interface RenderProjectIndexArgs {
   projectSlug: string;
@@ -88,6 +89,11 @@ function formatDate(iso: string): string {
 function indexCss(): string {
   return `
 /* index-page chrome */
+.cesium-eyebrow {
+  display: inline-flex; align-items: center; gap: 8px;
+  /* the eyebrow text is uppercased + tracked; the emblem sits flush left */
+}
+.cesium-eyebrow svg { display: block; }
 .filter-row { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 24px; align-items: center; }
 .filter-chip {
   display: inline-block; font-family: var(--sans); font-size: 0.8em; font-weight: 500;
@@ -274,6 +280,12 @@ export function renderProjectIndex(args: RenderProjectIndexArgs): string {
   const iJs = indexJs();
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
+  // Favicon sits next to theme.css in the stateDir root, so swap the suffix.
+  const faviconHref =
+    href !== null && href.endsWith("theme.css")
+      ? href.slice(0, -"theme.css".length) + "favicon.svg"
+      : "../../favicon.svg";
+  const faviconTag = suppressLink ? "" : `\n  ${faviconLinkTag(faviconHref)}`;
 
   // Sort entries newest-first
   const sorted = [...entries].toSorted(
@@ -348,11 +360,11 @@ ${cardsHtml}
   <title>${esc(projectName)} · cesium</title>
   <style>${rules}
 /* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}${iCss}</style>${linkTag}
+${tokens}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">
-  <p class="eyebrow">cesium · project</p>
+  <p class="eyebrow cesium-eyebrow">${faviconEmblemSvg(18)}<span>cesium · project</span></p>
   <h1 class="h-display">${esc(projectName)}</h1>
   ${subhead}
   ${filterRow}
@@ -383,6 +395,12 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
   const iCss = indexCss();
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
+  // Favicon sits next to theme.css; default href is "theme.css" → "favicon.svg".
+  const faviconHref =
+    href !== null && href.endsWith("theme.css")
+      ? href.slice(0, -"theme.css".length) + "favicon.svg"
+      : "favicon.svg";
+  const faviconTag = suppressLink ? "" : `\n  ${faviconLinkTag(faviconHref)}`;
 
   const sorted = [...projects].toSorted(
     (a, b) => new Date(b.latestCreatedAt).getTime() - new Date(a.latestCreatedAt).getTime(),
@@ -432,11 +450,11 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
   <title>All projects · cesium</title>
   <style>${rules}
 /* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}${iCss}</style>${linkTag}
+${tokens}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">
-  <p class="eyebrow">cesium</p>
+  <p class="eyebrow cesium-eyebrow">${faviconEmblemSvg(18)}<span>cesium</span></p>
   <h1 class="h-display">All projects</h1>
   ${subhead}
   ${bodyContent}

package/src/tools/ask.ts

@@ -14,6 +14,7 @@ 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 { writeFaviconSvg } from "../storage/favicon-write.ts";
 import { loadIndex, writeIndex, appendEntry, type IndexEntry } from "../storage/index-cache.ts";
 import { withLock } from "../storage/lock.ts";
 import { renderProjectIndex, renderGlobalIndex } from "../storage/index-gen.ts";
@@ -227,8 +228,9 @@ export function createAskTool(
       // 14. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
 
-      // 14a. Write theme.css (idempotent, outside index lock — separate file)
+      // 14a. Write theme.css + favicon.svg (idempotent, outside index lock — separate files)
       await writeThemeCss(config.stateDir, theme);
+      await writeFaviconSvg(config.stateDir);
 
       const fullHtml = wrapDocument({
         body: scrubbed.html,

package/src/tools/publish.ts

@@ -14,6 +14,7 @@ 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 { writeFaviconSvg } from "../storage/favicon-write.ts";
 import {
   loadIndex,
   writeIndex,
@@ -224,8 +225,9 @@ export function createPublishTool(
       // 12. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
 
-      // 12a. Write theme.css (idempotent, outside index lock — separate file)
+      // 12a. Write theme.css + favicon.svg (idempotent, outside index lock — separate files)
       await writeThemeCss(config.stateDir, theme);
+      await writeFaviconSvg(config.stateDir);
 
       const fullHtml = wrapDocument({
         body: scrubbed.html,