@ammduncan/easel 0.2.8 → 0.2.11

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.11 — 2026-05-22
+
+### Docs
+- **Locked-mode container guidance now covers syntax highlighting explicitly.** The existing rule ("background and text are a pair — commit both, re-scope `color: inherit` to children") only addressed single-color text. Syntax-highlighted code blocks layer multiple token colors on top of that, and the recurring failure was a `property` / `punctuation` / `comment` token colored near-background (e.g. `#2c2c40` on `#0f172a`) silently rendering whole identifiers invisible. New guidance in `skills/using-easel/SKILL.md` and the inline `push` tool description spells out: use a tested theme designed for your bg (Shiki `github-dark` / `vitesse-dark` / `one-dark-pro` for `#0f172a`-ish; `github-light` / `vitesse-light` for `#f5f7fa`-ish) OR pick from a verified 6-color palette for `#0f172a` (keyword `#ff7b72`, string `#a5d6ff`, function `#d2a8ff`, property `#79c0ff`, number `#ffa657`, comment `#8b949e`, default `#e6edf3`). Fallback: drop highlighting, use single-color monospace.
+
+## 0.2.10 — 2026-05-22
+
+### Changed
+- **Auto-open moved from "first tool call" to "first push", and is now aware of which sessions are currently being viewed.** The previous behaviour fired on the very first tool call (often `label` or `config`) and used a binary "have we attempted ever?" guard, which meant agents calling `label` before any push would burn the attempt without opening, and parent orchestrators that never push would still trigger a tab. New decision tree:
+  - `sessionTabs > 0` (this session is being viewed in ≥1 tab) → silent push, no auto-open.
+  - `otherTabs > 0` (easel is being viewed but on a different session) → no auto-open; the push response now hints to the agent to ask the user whether to switch to this session via the topbar `switch ▾` dropdown or call `open` for a new window. Avoids surprising users who deliberately switched their existing easel tab to look at another session.
+  - both `0` and no hook-managed tab → auto-open one tab.
+- Still one-shot per MCP child lifetime — if the user closes the tab after the first auto-open, subsequent pushes don't re-open; the response hints they can call `open` to force one.
+- Explicit `open` calls also mark the attempt as taken, so an `open` followed by a manual close is respected the same way.
+- Server's `/api/push` response now returns `otherTabs` alongside `sessionTabs`.
+
+## 0.2.9 — 2026-05-22
+
+### Added
+- **Per-push download menu with PNG and PDF.** The download icon on each push card now opens a small popover anchored under the icon, offering PNG (existing flow) or PDF. PDF mode reuses the same `html-to-image` rasterise we already run for PNG, then embeds the resulting bitmap into a `jsPDF` document sized to the canvas dimensions — one continuous page, no pagination, regardless of card height. jsPDF loads from the same jsDelivr CDN we already use for `html-to-image`.
+- **Real loading state on the download icon.** Replaces the previous subtle pulse — during render the icon swaps to a spinning ring and the button is click-locked until the export finishes (PNG anchor download or jsPDF save). Errors from the iframe-side rasterise now propagate to the parent via a new `easel:image-error` message and surface as an alert so silent hangs are visible.
+
+### Fixed
+- **Switcher delete button no longer overlaps the push count / timestamp.** The trash icon was absolute-positioned at `right: 36px` and sat on top of `.count` on hover. Moved into the flex flow as a sibling after `.count`, with `visibility: hidden` reserving its 22px slot so the count text stays clear at all times.
+
 ## 0.2.8 — 2026-05-22
 
 ### Docs

package/dist/client/index.css

@@ -76,17 +76,11 @@
   opacity: 1 !important;
 }
 
-.switcher-item {
-  position: relative;
-}
 .switcher-del {
-  position: absolute;
-  top: 50%;
-  right: 36px;
-  transform: translateY(-50%);
   display: inline-flex;
   align-items: center;
   justify-content: center;
+  flex-shrink: 0;
   width: 22px;
   height: 22px;
   background: transparent;
@@ -94,10 +88,14 @@
   border-radius: 6px;
   color: var(--ds-muted);
   cursor: pointer;
+  visibility: hidden;
   opacity: 0;
   transition: opacity 120ms ease, background 120ms ease, color 120ms ease;
 }
-.switcher-item:hover .switcher-del { opacity: 0.65; }
+.switcher-item:hover .switcher-del {
+  visibility: visible;
+  opacity: 0.65;
+}
 .switcher-del:hover {
   background: var(--ds-surface-soft);
   color: var(--ds-danger);

package/dist/client/viewer.css

@@ -588,17 +588,67 @@ body {
 .push-export[data-loading] {
   opacity: 1 !important;
   color: var(--ds-accent);
-  animation: easel-pulse 1.2s ease-in-out infinite;
+  pointer-events: none;
 }
-@keyframes easel-pulse {
-  0%, 100% { opacity: 0.55; }
-  50% { opacity: 1; }
+.push-export .push-export-spinner {
+  display: none;
+}
+.push-export[data-loading] .push-export-icon {
+  display: none;
+}
+.push-export[data-loading] .push-export-spinner {
+  display: block;
+  animation: easel-spin 0.7s linear infinite;
+}
+@keyframes easel-spin {
+  to { transform: rotate(360deg); }
 }
 .push-del svg,
 .push-export svg {
   display: block;
 }
 
+.push-export-wrap {
+  position: relative;
+  display: inline-flex;
+}
+.push-export-menu {
+  position: absolute;
+  top: calc(100% + 4px);
+  right: 0;
+  z-index: 30;
+  display: flex;
+  flex-direction: column;
+  min-width: 96px;
+  padding: 4px;
+  background: var(--ds-bg-elev);
+  border: 1px solid var(--ds-border, rgba(0, 0, 0, 0.12));
+  border-radius: 8px;
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.18);
+}
+.push-export-menu[hidden] {
+  display: none;
+}
+.push-export-menu button {
+  appearance: none;
+  display: block;
+  width: 100%;
+  padding: 6px 10px;
+  background: transparent;
+  border: 0;
+  border-radius: 6px;
+  font: inherit;
+  font-size: 12px;
+  text-align: left;
+  color: var(--ds-ink);
+  cursor: pointer;
+}
+.push-export-menu button:hover,
+.push-export-menu button:focus-visible {
+  background: var(--ds-surface-soft);
+  outline: none;
+}
+
 .push-body {
   background: var(--ds-bg-elev);
   overflow: hidden;

package/dist/client/viewer.html

@@ -8,6 +8,7 @@
 <link rel="stylesheet" href="https://rsms.me/inter/inter.css" />
 <link rel="stylesheet" href="/static/viewer.css" />
 <link rel="stylesheet" href="/static/index.css" />
+<script src="https://cdn.jsdelivr.net/npm/jspdf@2.5.2/dist/jspdf.umd.min.js"></script>
 <script>
   // Bootstrap theme before paint to avoid flash.
   (function () {

package/dist/client/viewer.js

@@ -144,21 +144,48 @@
       }
       return;
     }
+    if (data.type === "easel:image-error") {
+      console.error("[easel] iframe export error", data);
+      const iframeEl = cardsEl.querySelector(
+        'iframe[data-push-id="' + cssEscape(data.pushId) + '"]',
+      );
+      if (iframeEl && iframeEl.closest(".push")) {
+        const ex = iframeEl.closest(".push").querySelector(".push-export");
+        if (ex) delete ex.dataset.loading;
+      }
+      alert("Export failed (" + (data.format || "?") + "): " + (data.message || "unknown"));
+      return;
+    }
     if (data.type === "easel:image-ready") {
-      // Iframe rasterised itself; trigger a download in the parent.
+      const format = data.format === "pdf" ? "pdf" : "png";
+      const clearLoading = () => {
+        const iframeEl = cardsEl.querySelector(
+          'iframe[data-push-id="' + cssEscape(data.pushId) + '"]',
+        );
+        if (iframeEl && iframeEl.closest(".push")) {
+          const ex = iframeEl.closest(".push").querySelector(".push-export");
+          if (ex) delete ex.dataset.loading;
+        }
+      };
+
+      if (format === "pdf") {
+        downloadAsPdf(data.dataUrl, data.filename || "push.pdf")
+          .catch((err) => {
+            console.error("[easel] pdf export failed", err);
+            alert("PDF export failed: " + (err && err.message ? err.message : err));
+          })
+          .finally(clearLoading);
+        return;
+      }
+
+      // PNG — direct anchor download.
       const a = document.createElement("a");
       a.href = data.dataUrl;
       a.download = data.filename || "push.png";
       document.body.appendChild(a);
       a.click();
       a.remove();
-      const btn = cardsEl.querySelector(
-        'iframe[data-push-id="' + cssEscape(data.pushId) + '"]',
-      );
-      if (btn && btn.closest(".push")) {
-        const ex = btn.closest(".push").querySelector(".push-export");
-        if (ex) delete ex.dataset.loading;
-      }
+      clearLoading();
       return;
     }
   });
@@ -168,6 +195,62 @@
     return String(s).replace(/[^a-zA-Z0-9_-]/g, "\\$&");
   }
 
+  /**
+   * Embed a PNG dataURL into a single-page PDF sized to the image's pixel
+   * dimensions, producing a continuous (no page-breaks) document, then save.
+   */
+  function downloadAsPdf(dataUrl, filename) {
+    return new Promise((resolve, reject) => {
+      const jspdfNs = window.jspdf;
+      if (!jspdfNs || !jspdfNs.jsPDF) {
+        reject(new Error("jsPDF not loaded"));
+        return;
+      }
+      const img = new Image();
+      img.onload = () => {
+        try {
+          const w = img.naturalWidth || img.width;
+          const h = img.naturalHeight || img.height;
+          const pdf = new jspdfNs.jsPDF({
+            unit: "px",
+            format: [w, h],
+            orientation: w > h ? "landscape" : "portrait",
+            hotfixes: ["px_scaling"],
+          });
+          pdf.addImage(dataUrl, "PNG", 0, 0, w, h);
+          pdf.save(filename);
+          resolve();
+        } catch (err) {
+          reject(err);
+        }
+      };
+      img.onerror = () => reject(new Error("image decode failed"));
+      img.src = dataUrl;
+    });
+  }
+
+  // Dismiss any open push-export menu on outside click / Escape.
+  document.addEventListener("click", (e) => {
+    if (e.target.closest && e.target.closest(".push-export-wrap")) return;
+    document.querySelectorAll(".push-export-menu").forEach((m) => {
+      if (!m.hidden) {
+        m.hidden = true;
+        const sib = m.previousElementSibling;
+        if (sib) sib.setAttribute("aria-expanded", "false");
+      }
+    });
+  });
+  document.addEventListener("keydown", (e) => {
+    if (e.key !== "Escape") return;
+    document.querySelectorAll(".push-export-menu").forEach((m) => {
+      if (!m.hidden) {
+        m.hidden = true;
+        const sib = m.previousElementSibling;
+        if (sib) sib.setAttribute("aria-expanded", "false");
+      }
+    });
+  });
+
   /* ============================================================
      Theming
      ============================================================ */
@@ -363,21 +446,75 @@
     time.textContent = formatTime(push.createdAt);
     meta.appendChild(time);
 
+    const exportWrap = document.createElement("div");
+    exportWrap.className = "push-export-wrap";
+
     const exportBtn = document.createElement("button");
     exportBtn.className = "push-export";
     exportBtn.type = "button";
-    exportBtn.title = "Save as PNG";
-    exportBtn.setAttribute("aria-label", "Save push as PNG");
+    exportBtn.title = "Download";
+    exportBtn.setAttribute("aria-label", "Download this push");
+    exportBtn.setAttribute("aria-haspopup", "menu");
+    exportBtn.setAttribute("aria-expanded", "false");
     exportBtn.innerHTML =
-      '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" x2="12" y1="15" y2="3"/></svg>';
-    exportBtn.addEventListener("click", (e) => {
-      e.stopPropagation();
-      e.preventDefault();
-      const safeTitle = (push.title || "push-" + push.index)
+      '<svg class="push-export-icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" x2="12" y1="15" y2="3"/></svg>' +
+      '<svg class="push-export-spinner" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><circle cx="12" cy="12" r="9" stroke-opacity="0.25"/><path d="M21 12a9 9 0 0 0-9-9"/></svg>';
+
+    const exportMenu = document.createElement("div");
+    exportMenu.className = "push-export-menu";
+    exportMenu.setAttribute("role", "menu");
+    exportMenu.hidden = true;
+    exportMenu.innerHTML =
+      '<button type="button" role="menuitem" data-format="png">PNG</button>' +
+      '<button type="button" role="menuitem" data-format="pdf">PDF</button>';
+
+    const safeTitle = () =>
+      (push.title || "push-" + push.index)
         .toLowerCase()
         .replace(/[^a-z0-9-]+/g, "-")
         .replace(/^-+|-+$/g, "")
         .slice(0, 60) || "push";
+
+    function closeExportMenu() {
+      if (exportMenu.hidden) return;
+      exportMenu.hidden = true;
+      exportBtn.setAttribute("aria-expanded", "false");
+    }
+
+    function openExportMenu() {
+      // Close any other open export menus first.
+      cardsEl.querySelectorAll(".push-export-menu").forEach((m) => {
+        if (m !== exportMenu) {
+          m.hidden = true;
+          const sib = m.previousElementSibling;
+          if (sib) sib.setAttribute("aria-expanded", "false");
+        }
+      });
+      exportMenu.hidden = false;
+      exportBtn.setAttribute("aria-expanded", "true");
+    }
+
+    exportBtn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      e.preventDefault();
+      if (exportMenu.hidden) {
+        openExportMenu();
+      } else {
+        closeExportMenu();
+      }
+    });
+
+    exportMenu.addEventListener("click", (e) => {
+      const btn = e.target.closest("button[data-format]");
+      if (!btn) return;
+      e.stopPropagation();
+      e.preventDefault();
+      const format = btn.dataset.format === "pdf" ? "pdf" : "png";
+      closeExportMenu();
+      requestExport(format);
+    });
+
+    function requestExport(format) {
       exportBtn.dataset.loading = "true";
 
       // Match the export bg to what the user sees inside this card:
@@ -387,6 +524,7 @@
       const isFlat = currentDensity() === "flat";
       const bgVar = isFlat ? "--ds-bg" : "--ds-bg-elev";
       const bgColor = rootStyle.getPropertyValue(bgVar).trim() || "#ffffff";
+      const filename = safeTitle() + (format === "pdf" ? ".pdf" : ".png");
 
       try {
         iframe.contentWindow &&
@@ -394,7 +532,8 @@
             {
               type: "easel:image",
               pushId: push.id,
-              filename: safeTitle + ".png",
+              filename,
+              format,
               bgColor,
             },
             "*",
@@ -403,8 +542,11 @@
         delete exportBtn.dataset.loading;
         console.error("[easel] export failed", err);
       }
-    });
-    meta.appendChild(exportBtn);
+    }
+
+    exportWrap.appendChild(exportBtn);
+    exportWrap.appendChild(exportMenu);
+    meta.appendChild(exportWrap);
 
     const del = document.createElement("button");
     del.className = "push-del";
@@ -676,6 +818,7 @@ ${body}
     if (e.data.type === "easel:image") {
       var pushId = e.data.pushId;
       var filename = e.data.filename || "push.png";
+      var format = e.data.format === "pdf" ? "pdf" : "png";
       var bgColor =
         e.data.bgColor ||
         getComputedStyle(document.documentElement).getPropertyValue("--ds-bg-elev").trim() ||
@@ -701,9 +844,10 @@ ${body}
           width: width,
           height: height,
         }).then(function(dataUrl){
-          parent.postMessage({ type: "easel:image-ready", pushId: pushId, dataUrl: dataUrl, filename: filename }, "*");
+          parent.postMessage({ type: "easel:image-ready", pushId: pushId, dataUrl: dataUrl, filename: filename, format: format }, "*");
         }).catch(function(err){
           console.error("[easel] export failed", err);
+          parent.postMessage({ type: "easel:image-error", pushId: pushId, format: format, message: (err && err.message) ? err.message : String(err) }, "*");
         });
       }
       if (document.fonts && document.fonts.ready) {
@@ -723,7 +867,7 @@ ${body}
     const configScript =
       "<script src='https://cdn.jsdelivr.net/npm/html-to-image@1.11.13/dist/html-to-image.js'></script><script>(function(){function a(c){if(!c)return;if(c.theme==='light'||c.theme==='dark'){document.documentElement.setAttribute('data-theme',c.theme);window.__claudeDisplayTheme=c.theme}if(c.preset==='paper'||c.preset==='aurora'||c.preset==='slate'){document.documentElement.setAttribute('data-preset',c.preset);window.__claudeDisplayPreset=c.preset}if(c.density==='carded'||c.density==='flat'){document.documentElement.setAttribute('data-density',c.density);window.__claudeDisplayDensity=c.density}}a(" +
       JSON.stringify({ theme, preset, density }) +
-      ");window.addEventListener('message',function(e){if(!e||!e.data)return;if(e.data.type==='easel:config')a(e.data);if(e.data.type==='easel:theme')a({theme:e.data.theme});if(e.data.type==='easel:print'){try{window.print()}catch(_){}}if(e.data.type==='easel:image'){var pid=e.data.pushId;var fn=e.data.filename||'push.png';var bg=e.data.bgColor||'#ffffff';if(!window.htmlToImage)return;window.htmlToImage.toPng(document.body,{backgroundColor:bg,pixelRatio:4,cacheBust:true}).then(function(u){parent.postMessage({type:'easel:image-ready',pushId:pid,dataUrl:u,filename:fn},'*')}).catch(function(err){console.error(err)})}})})();</script>";
+      ");window.addEventListener('message',function(e){if(!e||!e.data)return;if(e.data.type==='easel:config')a(e.data);if(e.data.type==='easel:theme')a({theme:e.data.theme});if(e.data.type==='easel:print'){try{window.print()}catch(_){}}if(e.data.type==='easel:image'){var pid=e.data.pushId;var fn=e.data.filename||'push.png';var fmt=e.data.format==='pdf'?'pdf':'png';var bg=e.data.bgColor||'#ffffff';if(!window.htmlToImage)return;window.htmlToImage.toPng(document.body,{backgroundColor:bg,pixelRatio:4,cacheBust:true}).then(function(u){parent.postMessage({type:'easel:image-ready',pushId:pid,dataUrl:u,filename:fn,format:fmt},'*')}).catch(function(err){console.error(err);parent.postMessage({type:'easel:image-error',pushId:pid,format:fmt,message:(err&&err.message)?err.message:String(err)},'*')})}})})();</script>";
     const measureScript = "<script>" + selfMeasureScript(pushId) + "</script>";
     const combined = configScript + measureScript;
     if (/<\/body>/i.test(html)) return html.replace(/<\/body>/i, combined + "</body>");

package/dist/http-server.js

@@ -164,15 +164,21 @@ export function startHttpServer() {
             sweepIdleSessions();
         }
         let sessionTabs = 0;
+        let otherTabs = 0;
         for (const c of clients.values()) {
-            if (c.sessionId === sessionId)
+            if (c.sessionId === sessionId) {
                 sessionTabs++;
+            }
+            else {
+                otherTabs++;
+            }
         }
         res.json({
             url: `http://localhost:${port}/s/${sessionId}`,
             slide_id: push.id,
             index: push.index,
             sessionTabs,
+            otherTabs,
         });
     });
     const server = app.listen(port, "127.0.0.1", () => {

package/dist/mcp.js

@@ -33,15 +33,41 @@ function hookHasFiredForThisPpid() {
     return existsSync(join(HOOK_DIR, `cc-session-${process.ppid}.txt`));
 }
 // One-shot guard: only auto-open once per MCP-child lifetime. If the user
-// closes the tab afterwards, subsequent pushes won't re-open it.
+// closes the tab afterwards, subsequent pushes won't re-open it — the user
+// closing the tab is treated as an explicit dismissal we should respect.
 let autoOpenAttempted = false;
-function maybeAutoOpenTab(url) {
+/**
+ * Decide whether to auto-open the session URL on first push.
+ *
+ * - `sessionTabs > 0`: a tab is already showing THIS session → no-op.
+ * - `otherTabs > 0`: easel is open, but on a different session. Don't surprise
+ *   the user with another window — return "other-session" so the caller can
+ *   tell the agent to ask whether to use the topbar switcher or open a new tab.
+ * - both 0 + no hook-managed tab: auto-open one tab.
+ *
+ * One-shot per MCP child lifetime. Closing the tab counts as dismissal;
+ * subsequent pushes won't re-open.
+ */
+function autoOpenIfNeeded(url, sessionTabs, otherTabs) {
     if (autoOpenAttempted)
-        return;
+        return { kind: "noop" };
+    if (sessionTabs > 0) {
+        autoOpenAttempted = true;
+        return { kind: "noop" };
+    }
+    if (otherTabs > 0) {
+        // Easel is alive in another session — don't open a new window without asking.
+        autoOpenAttempted = true;
+        return { kind: "other-session" };
+    }
+    if (hookHasFiredForThisPpid()) {
+        // Claude Code's SessionStart hook handled it (or tried to).
+        autoOpenAttempted = true;
+        return { kind: "noop" };
+    }
     autoOpenAttempted = true;
-    if (hookHasFiredForThisPpid())
-        return; // Claude Code already opened it
     openUrlInBrowser(url);
+    return { kind: "opened" };
 }
 const inputSchema = {
     type: "object",
@@ -101,7 +127,8 @@ export async function main() {
                     "  .terminal { background: #0f172a; color: #e6edf3; border-radius: 12px; padding: 20px 24px; font-family: ui-monospace, 'SF Mono', Menlo, monospace; font-size: 13.5px; line-height: 1.7; }\n" +
                     "  .terminal *, .terminal span, .terminal pre { color: inherit; }\n" +
                     "  .terminal .muted { color: #94a3b8; }\n" +
-                    "  .terminal .accent { color: #6ee7b7; }\n\n" +
+                    "  .terminal .accent { color: #6ee7b7; }\n" +
+                    "• Syntax-highlighted code in a locked-bg block: EVERY token color must be verified readable against the bg, not just the body color. Recurring bug: locking to #0f172a then giving 'property' / 'punctuation' / 'comment' tokens something like #2c2c40 because it 'looked subtle' — against #0f172a it's nearly invisible and identifiers disappear. Either use a tested theme designed for your bg (Shiki github-dark / vitesse-dark / one-dark-pro for #0f172a-ish, github-light / vitesse-light for #f5f7fa-ish), or pick from this verified palette for #0f172a: keyword #ff7b72, string #a5d6ff, function #d2a8ff, property #79c0ff, number #ffa657, comment #8b949e, default text #e6edf3. If you can't articulate why each token reads against the bg, drop highlighting and use single-color monospace — that always works.\n\n" +
                     "═══ TYPOGRAPHY (presentation scale, NOT dashboard) ═══\n" +
                     "• Hero title: 44–52px, weight 500, letter-spacing -0.025em\n" +
                     "• Section titles: 28–36px, weight 500\n" +
@@ -191,12 +218,12 @@ export async function main() {
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const sessionId = resolveClaudeSessionId();
         const { port } = await ensureHttpServer();
-        // Non-Claude-Code clients have no SessionStart hook to open the tab —
-        // we do it ourselves on the first tool call instead.
-        maybeAutoOpenTab(`http://localhost:${port}/s/${sessionId}`);
         if (req.params.name === TOOL_OPEN) {
             const url = `http://localhost:${port}/s/${sessionId}`;
             openUrlInBrowser(url);
+            // Explicit open also counts as "we've opened it" — if the user closes
+            // this tab later, a subsequent push shouldn't auto-reopen.
+            autoOpenAttempted = true;
             return {
                 content: [
                     {
@@ -263,9 +290,20 @@ export async function main() {
             kind: args.kind,
             port,
         });
-        const tabHint = result.sessionTabs === 0
-            ? " · NO TAB OPEN for this session — ask the user if you should open one (call `open`)"
-            : "";
+        const url = `http://localhost:${port}/s/${sessionId}`;
+        const openResult = autoOpenIfNeeded(url, result.sessionTabs, result.otherTabs);
+        let tabHint = "";
+        if (openResult.kind === "opened") {
+            tabHint = " · opened a tab for this session";
+        }
+        else if (openResult.kind === "other-session") {
+            tabHint =
+                " · easel is open in another tab on a different session — ASK the user whether to switch via the topbar 'switch ▾' dropdown to this session, or call `open` to launch a new tab/window for it";
+        }
+        else if (result.sessionTabs === 0) {
+            tabHint =
+                " · no tab open for this session — user previously closed it; call `open` to force a new one if needed";
+        }
         return {
             content: [
                 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.8",
+  "version": "0.2.11",
   "description": "A live browser tab for every Claude Code (and MCP) session. The push MCP tool appends HTML cards to a scrolling feed you keep open in split-screen.",
   "type": "module",
   "license": "MIT",

package/skills/using-easel/SKILL.md

@@ -198,6 +198,24 @@ When the mockup references a real thing — a real app, a real component, a real
 
 The rule of thumb: background and text are a pair — commit one, commit the other.
 
+**Syntax highlighting in locked-bg code blocks needs *every token* verified.** "Bg + text are a pair" extends to every token color you use. The recurring failure: lock a code block to `#0f172a`, then layer syntax tokens where one (usually `property`, `punctuation`, or `comment`) is colored `#2c2c40` or `#3b4252` because it "looked subtle" — against `#0f172a` it's nearly invisible and whole identifiers disappear from the block. Two ways out:
+
+1. **Use a tested theme designed for your bg.** Shiki / Prism / Highlight.js themes like `github-dark`, `vitesse-dark`, `one-dark-pro` for `#0f172a`-ish backgrounds; `github-light`, `vitesse-light` for `#f5f7fa`-ish. The theme's author already verified contrast — don't override individual tokens.
+2. **Hand-rolling tokens? Verify each one against the bg, or pick from this verified palette for `#0f172a`:**
+
+```css
+.code            { background: #0f172a; color: #e6edf3; }
+.code .keyword   { color: #ff7b72; }   /* red-pink:   keywords, control flow */
+.code .string    { color: #a5d6ff; }   /* sky:        strings, attribute values */
+.code .function  { color: #d2a8ff; }   /* purple:     function names */
+.code .property  { color: #79c0ff; }   /* blue:       identifiers, properties, members */
+.code .number    { color: #ffa657; }   /* orange:     numbers, constants */
+.code .comment   { color: #8b949e; }   /* muted gray: comments — still readable */
+.code *          { color: inherit; }   /* default everything else to body color */
+```
+
+If you can't articulate why each token color reads against the bg, drop syntax highlighting entirely and use single-color monospace — that always works.
+
 ### 5. Visualizations — tangible over abstract
 
 When something can be represented as a real-world object — browser-chrome tab cards with red/yellow/green dots, proportional horizontal timeline bars with marked phases, device frames, code editor windows, terminal windows, merging-pipe shapes for funnels — **do that**, not abstract labeled rectangles with arrows.