@cfbender/cesium 0.3.6 → 0.4.0

package/README.md

@@ -1,4 +1,7 @@
-# Cesium
+<h1>
+  <img src="assets/favicon.svg" alt="" width="48" height="48" align="left" style="margin-right: 12px; vertical-align: middle;">
+  Cesium
+</h1>
 
 Cesium publishes substantive opencode agent responses — plans, code reviews,
 comparisons, explainers, audits, RFCs — as self-contained beautiful HTML artifacts
@@ -6,10 +9,6 @@ on disk, instead of dumping markdown into the terminal. The browser becomes the
 reading surface; the terminal stays the control surface. Each artifact is a single
 `.html` file: portable, archivable, viewable offline, shareable as a URL over SSH.
 
-v0.3.0 adds **interactive Q&A artifacts** — the agent can now publish a question
-form, wait for the user to answer in their browser, and receive the structured
-responses before continuing work.
-
 <video src="assets/cesium.mp4" autoplay loop muted playsinline width="720">
   Demo video — see <a href="assets/cesium.mp4">assets/cesium.mp4</a> if it
   doesn't play inline (some markdown viewers strip <code>&lt;video&gt;</code>).
@@ -51,19 +50,37 @@ unreleased changes).
 
 ### CLI
 
+The CLI puts a `cesium` binary on your `PATH` for browsing, opening, and
+managing artifacts (`cesium ls`, `cesium open`, `cesium serve`, `cesium prune`,
+`cesium theme`).
+
+**Recommended: install with [mise](https://mise.jdx.dev/)** so cesium is pinned
+in your config and tracks with the rest of your toolchain. Add to your
+`~/.config/mise/config.toml` (or a project-local `mise.toml`):
+
+```toml
+[tools]
+"npm:@cfbender/cesium" = "latest"
+```
+
+Then run `mise install` (or `mise use -g npm:@cfbender/cesium@latest` for the
+one-liner equivalent). Pin to a specific release with `"0.3.6"` instead of
+`"latest"`. Upgrade with `mise upgrade npm:@cfbender/cesium`.
+
+**Alternative: install with bun directly:**
+
 ```bash
 bun install -g @cfbender/cesium
 ```
 
-This puts a `cesium` binary on your `PATH` (at `~/.bun/bin/cesium`). If
-`which cesium` returns nothing, add `~/.bun/bin` to your shell rc:
+This puts the binary at `~/.bun/bin/cesium`. If `which cesium` returns nothing,
+add `~/.bun/bin` to your shell rc:
 
 ```bash
 export PATH="$HOME/.bun/bin:$PATH"
 ```
 
-Upgrade later with `bun update -g @cfbender/cesium` (or via your version
-manager — e.g. `mise use -g npm:@cfbender/cesium@latest`). To uninstall:
+Upgrade with `bun update -g @cfbender/cesium`. Uninstall with
 `bun remove -g @cfbender/cesium`.
 
 ### Developing on cesium itself

package/assets/styleguide.html

@@ -329,6 +329,89 @@
         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 */
+      .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 {
@@ -845,6 +928,72 @@
         </div>
       </section>
 
+      <!-- ============================================================
+       Section 13 · Ranked list
+       ============================================================ -->
+      <section>
+        <p class="eyebrow">13 · ranked-list</p>
+        <h2 class="h-section"><span class="section-num">13</span>Ranked list</h2>
+        <p>
+          Use <code>.ranked-list</code> + <code>.ranked-item</code> for ordered recommendations,
+          findings, or rankings — anything that would otherwise be a heavy numbered
+          <code>&lt;h3&gt;</code> sequence. Each item gets a soft serif numeral on the left and a
+          calm title + meta + body on the right. Pair <code>.pill.accent</code> +
+          <code>.tag</code> in the meta row for impact and savings; use <code>.rank-aside</code> for
+          a quieter "bonus" addendum.
+        </p>
+
+        <ol class="ranked-list">
+          <li class="ranked-item">
+            <div class="rank-num">01</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Replace the styleguide payload with a compact catalog</h3>
+              <div class="rank-meta">
+                <span class="pill accent">High impact</span>
+                <span class="tag">~6–8k tokens / call</span>
+              </div>
+              <p>
+                Return a structured Markdown reference of <em>class → purpose → minimal example</em>
+                instead of the full HTML framework. Realistic target: 3–5 KB / ~1k tokens, down from
+                ~7–9k.
+              </p>
+              <p class="rank-aside">
+                <span class="rank-aside-label">Bonus</span>
+                Derive the catalog from a single source so it can't drift from the framework.
+              </p>
+            </div>
+          </li>
+          <li class="ranked-item">
+            <div class="rank-num">02</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Trim the system prompt fragment</h3>
+              <div class="rank-meta">
+                <span class="pill">Low impact</span>
+                <span class="tag">~400 tokens / session</span>
+              </div>
+              <p>
+                Remove redundancy with in-tool <code>description</code> strings. Nice but not
+                transformative.
+              </p>
+            </div>
+          </li>
+          <li class="ranked-item">
+            <div class="rank-num">03</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Stop double-emitting CSS in <code>wrapDocument()</code></h3>
+              <div class="rank-meta">
+                <span class="pill">Disk only</span>
+                <span class="tag">~17 KB / artifact</span>
+              </div>
+              <p>
+                Inline the framework only when the linked stylesheet is unavailable; emit tokens
+                inline always.
+              </p>
+            </div>
+          </li>
+        </ol>
+      </section>
+
       <!-- ============================================================
        Footer / byline
        ============================================================ -->

package/package.json

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

package/src/render/theme.ts

@@ -456,6 +456,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 {