@ammduncan/easel 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.4.0 — 2026-05-26
+
+### Added
+- **Remote images are now inlined server-side at push time, so pushes that embed cross-origin images export correctly.** A push that referenced a remote image (e.g. a mobbin.com screenshot in an `app`/`mockup` recreation) rendered fine on screen but **couldn't be exported to PNG/PDF**: the browser blocks cross-origin images from canvas rasterisation (CORS), and drawing one taints the canvas so `toDataURL` throws — export would stall until the 30s watchdog fired (see 0.3.3). The fix moves the fetch to the server: `POST /api/push` now scans incoming HTML for remote `<img src>` and CSS `url(...)` references, fetches each server-side (no CORS limit), and rewrites them to self-contained `data:` URLs before storing the push. Exports then work, and the push survives the original URL later expiring (mobbin's `…/mcp/short/…` links are ephemeral). Fetches run in parallel, each bounded by an 8s timeout with an 8MB size cap and an image-content-type check; a URL that can't be inlined (timeout, non-image, too large, network error) is left untouched — it still displays, just won't appear in an export — so a dead link degrades gracefully instead of failing the push. Opt out with `EASEL_INLINE_IMAGES=0`. Covered by `tests/unit/inline-images.test.mjs`.
+
+## 0.3.3 — 2026-05-26
+
+### Fixed
+- **PNG and PDF export no longer hang when the easel tab isn't the visible foreground tab.** Export rasterised via `html-to-image`'s `toPng`/`toJpeg`, which resolve through the library's internal `createImage()` — and that waits on `requestAnimationFrame`. Chrome freezes rAF in hidden/background tabs, so the rasterize promise never settled: click export, switch back to your terminal, and the button spinner span forever with no error (the viewer had no timeout to recover). Both formats died here because they share the path. The export now stops at `htmlToImage.toSvg()` (no rAF) and rasterises onto a canvas with a plain `Image`, whose `onload` fires even in hidden tabs. Quality is unchanged — the SVG is vector, drawn onto a DPR-4 canvas, so PNG stays lossless and PDF stays JPEG q1.0. The two render paths (`buildDefaultWrapper` and the full-HTML `injectBridge`, which had drifted to capturing `body` vs `documentElement`) now share one `imageExportScript()`. A missing `html-to-image` now posts an error instead of returning silently, and a 30s parent-side watchdog clears the spinner and surfaces a timeout if the iframe never reports back. Covered by `tests/unit/image-export.test.mjs`.
+
 ## 0.3.2 — 2026-05-26
 
 ### Fixed

package/dist/client/viewer.js

@@ -7,6 +7,27 @@
   const cardsEl = document.getElementById("cards");
   const emptyEl = document.getElementById("empty-state");
   const countEl = document.getElementById("push-count");
+
+  // Per-push export watchdog timers. If the iframe never posts back
+  // image-ready / image-error (e.g. a render stall), the watchdog clears the
+  // button spinner and surfaces an error instead of spinning forever.
+  const EXPORT_TIMEOUT_MS = 30000;
+  const exportWatchdogs = new Map();
+  function clearExportSpinner(pushId) {
+    const iframeEl = cardsEl.querySelector(
+      'iframe[data-push-id="' + cssEscape(pushId) + '"]',
+    );
+    const push = iframeEl && iframeEl.closest(".push");
+    const ex = push && push.querySelector(".push-export");
+    if (ex) delete ex.dataset.loading;
+  }
+  function clearExportWatchdog(pushId) {
+    const t = exportWatchdogs.get(pushId);
+    if (t) {
+      clearTimeout(t);
+      exportWatchdogs.delete(pushId);
+    }
+  }
   const prunedEl = document.getElementById("pruned-marker");
   const liveDotEl = document.getElementById("live-dot");
   const liveLabelEl = document.getElementById("live-label");
@@ -276,27 +297,15 @@
     }
     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;
-      }
+      clearExportWatchdog(data.pushId);
+      clearExportSpinner(data.pushId);
       alert("Export failed (" + (data.format || "?") + "): " + (data.message || "unknown"));
       return;
     }
     if (data.type === "easel:image-ready") {
       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;
-        }
-      };
+      clearExportWatchdog(data.pushId);
+      const clearLoading = () => clearExportSpinner(data.pushId);
 
       if (format === "pdf") {
         downloadAsPdf(data.dataUrl, data.filename || "push.pdf")
@@ -654,6 +663,20 @@
     function requestExport(format) {
       exportBtn.dataset.loading = "true";
 
+      clearExportWatchdog(push.id);
+      exportWatchdogs.set(
+        push.id,
+        setTimeout(() => {
+          exportWatchdogs.delete(push.id);
+          clearExportSpinner(push.id);
+          alert(
+            "Export timed out after " +
+              EXPORT_TIMEOUT_MS / 1000 +
+              "s. Try again with the easel tab in the foreground.",
+          );
+        }, EXPORT_TIMEOUT_MS),
+      );
+
       // Match the export bg to what the user sees inside this card:
       //   carded → card's elevated surface (--ds-bg-elev)
       //   flat   → page canvas (--ds-bg) since the iframe body is transparent
@@ -676,6 +699,7 @@
             "*",
           );
       } catch (err) {
+        clearExportWatchdog(push.id);
         delete exportBtn.dataset.loading;
         console.error("[easel] export failed", err);
       }
@@ -769,6 +793,49 @@
     );
   }
 
+  /**
+   * In-iframe message listener that turns the rendered push into a PNG/JPEG
+   * dataURL on `easel:image` and posts back `easel:image-ready` / `-error`.
+   *
+   * Deliberately stops at htmlToImage.toSvg() and does the canvas rasterisation
+   * by hand. toPng/toJpeg/toCanvas resolve via the library's internal
+   * createImage(), which waits on requestAnimationFrame — and Chrome freezes
+   * rAF in hidden/background tabs, so the export hung forever whenever the
+   * easel tab wasn't the visible one. toSvg has no rAF, and a plain Image's
+   * onload fires even in hidden tabs, so this path works regardless of tab
+   * visibility. Quality is unchanged: the SVG is vector, drawn onto a
+   * PIXEL_RATIO-scaled canvas → still crisp at DPR 4.
+   *
+   * Shared verbatim by buildDefaultWrapper and injectBridge so the two render
+   * paths can't drift.
+   */
+  function imageExportScript() {
+    return (
+      "(function(){var PR=4;" +
+      "function fail(id,fmt,err){console.error('[easel] export failed',err);" +
+      "parent.postMessage({type:'easel:image-error',pushId:id,format:fmt,message:(err&&err.message)?err.message:String(err)},'*')}" +
+      "function rasterize(svgUrl,w,h,bg,fmt){return new Promise(function(resolve,reject){" +
+      "var img=new Image();" +
+      "img.onload=function(){try{var c=document.createElement('canvas');" +
+      "c.width=Math.max(1,Math.round(w*PR));c.height=Math.max(1,Math.round(h*PR));" +
+      "var x=c.getContext('2d');x.fillStyle=bg;x.fillRect(0,0,c.width,c.height);" +
+      "x.drawImage(img,0,0,c.width,c.height);" +
+      "resolve(fmt==='pdf'?c.toDataURL('image/jpeg',1.0):c.toDataURL('image/png'))}catch(e){reject(e)}};" +
+      "img.onerror=function(){reject(new Error('SVG snapshot failed to load'))};img.src=svgUrl})}" +
+      "function run(d){var id=d.pushId;var fn=d.filename||'push.png';var fmt=d.format==='pdf'?'pdf':'png';" +
+      "var bg=d.bgColor||getComputedStyle(document.documentElement).getPropertyValue('--ds-bg-elev').trim()||'#ffffff';" +
+      "function render(){if(!window.htmlToImage){fail(id,fmt,new Error('html-to-image not loaded'));return}" +
+      "var w=document.documentElement.clientWidth;" +
+      "var h=Math.max(document.documentElement.scrollHeight,document.body?document.body.scrollHeight:0);" +
+      "window.htmlToImage.toSvg(document.documentElement,{width:w,height:h,cacheBust:true})" +
+      ".then(function(u){return rasterize(u,w,h,bg,fmt)})" +
+      ".then(function(u){parent.postMessage({type:'easel:image-ready',pushId:id,dataUrl:u,filename:fn,format:fmt},'*')})" +
+      ".catch(function(e){fail(id,fmt,e)})}" +
+      "if(document.fonts&&document.fonts.ready){document.fonts.ready.then(render).catch(render)}else{render()}}" +
+      "window.addEventListener('message',function(e){if(e&&e.data&&e.data.type==='easel:image')run(e.data)})})();"
+    );
+  }
+
   function buildDefaultWrapper(body, theme, preset, pushId, appFidelity) {
     const density = currentDensity();
     // app-fidelity mode: skip presentation defaults (presets, semantic chips,
@@ -1004,58 +1071,10 @@ ${body}
     if (e.data.type === "easel:print") {
       try { window.print(); } catch(_) {}
     }
-    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() ||
-        "#ffffff";
-      function render() {
-        if (!window.htmlToImage) {
-          console.error("[easel] html-to-image not loaded");
-          return;
-        }
-        // Capture the html root at full viewport width so fixed/absolute
-        // positioning resolves the same as on screen. Capturing body alone
-        // honours max-width:auto-margins and breaks fixed elements that
-        // anchor to the viewport (modals at left:50% etc).
-        var width = document.documentElement.clientWidth;
-        var height = Math.max(
-          document.documentElement.scrollHeight,
-          document.body ? document.body.scrollHeight : 0,
-        );
-        // PNG target → lossless PNG @ pixelRatio 4 for crisp standalone files.
-        // PDF target → JPEG @ quality 1.0 + pixelRatio 4. PDFs natively use
-        // DCT compression for embedded JPEGs, so even at max quality the PDF
-        // stays in the ~3-8 MB range for a typical card (vs ~300 MB if we
-        // embedded as PNG — see 0.2.15). 1.0 + DPR 4 keeps text razor-sharp
-        // at any zoom level; tuned down to 0.92 + DPR 2 in 0.2.15 dropped to
-        // ~800 KB but at the cost of visible JPEG artefacts on type.
-        var rasterFn = format === "pdf" ? window.htmlToImage.toJpeg : window.htmlToImage.toPng;
-        var rasterOpts = {
-          backgroundColor: bgColor,
-          pixelRatio: 4,
-          cacheBust: true,
-          width: width,
-          height: height,
-        };
-        if (format === "pdf") rasterOpts.quality = 1.0;
-        rasterFn(document.documentElement, rasterOpts).then(function(dataUrl){
-          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) {
-        document.fonts.ready.then(render).catch(render);
-      } else { render(); }
-    }
   });
 })();
 </script>
+<script>${imageExportScript()}</script>
 <script>${selfMeasureScript(pushId)}</script>
 </body>
 </html>`;
@@ -1066,9 +1085,10 @@ ${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 fmt=e.data.format==='pdf'?'pdf':'png';var bg=e.data.bgColor||'#ffffff';if(!window.htmlToImage)return;var rfn=fmt==='pdf'?window.htmlToImage.toJpeg:window.htmlToImage.toPng;var ropts={backgroundColor:bg,pixelRatio:4,cacheBust:true};if(fmt==='pdf')ropts.quality=1.0;rfn(document.body,ropts).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>";
+      ");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(_){}}})})();</script>";
+    const imageScript = "<script>" + imageExportScript() + "</script>";
     const measureScript = "<script>" + selfMeasureScript(pushId) + "</script>";
-    const combined = configScript + measureScript;
+    const combined = configScript + imageScript + measureScript;
     if (/<\/body>/i.test(html)) return html.replace(/<\/body>/i, combined + "</body>");
     return html + combined;
   }

package/dist/http-server.js

@@ -6,6 +6,7 @@ import { appendPush, deletePush, deleteSession, getSessionView, listSessionSumma
 import { readConfig, writeConfig } from "./config-store.js";
 import { clearLockIfMine, writeLock } from "./server-manager.js";
 import { resolvePort } from "./paths.js";
+import { inlineRemoteImages } from "./inline-images.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLIENT_DIR = resolve(__dirname, "client");
 const clients = new Map();
@@ -157,7 +158,7 @@ export function startHttpServer() {
         const ok = deleteSession(id);
         res.json({ ok });
     });
-    app.post("/api/push", (req, res) => {
+    app.post("/api/push", async (req, res) => {
         const { sessionId, html, title, kind } = req.body ?? {};
         if (typeof sessionId !== "string" || !sessionId.trim()) {
             res.status(400).json({ error: "sessionId required" });
@@ -167,7 +168,24 @@ export function startHttpServer() {
             res.status(400).json({ error: "html required" });
             return;
         }
-        const push = appendPush(sessionId, { html, title, kind });
+        // Inline remote images server-side so the stored push is self-contained
+        // and exportable (cross-origin images are CORS-blocked from client-side
+        // rasterisation). Best-effort: on any failure we store the original html.
+        let storedHtml = html;
+        if (process.env.EASEL_INLINE_IMAGES !== "0") {
+            try {
+                const result = await inlineRemoteImages(html);
+                storedHtml = result.html;
+                if (result.failed.length > 0) {
+                    console.warn(`[easel] ${result.failed.length} remote image(s) left un-inlined (won't export): ` +
+                        result.failed.map((f) => `${f.url} — ${f.reason}`).join("; "));
+                }
+            }
+            catch (err) {
+                console.warn("[easel] image inlining failed; storing original html:", err);
+            }
+        }
+        const push = appendPush(sessionId, { html: storedHtml, title, kind });
         touchSession(sessionId);
         broadcast(sessionId, "push", push);
         if (Math.random() < 0.05) {

package/dist/inline-images.js

@@ -0,0 +1,91 @@
+/**
+ * Inline remote images into pushed HTML so exports work.
+ *
+ * Cross-origin images (e.g. mobbin screenshots) render on screen but can't be
+ * rasterised client-side: fetching them for inlining is CORS-blocked, and
+ * drawing a cross-origin image taints the canvas so PNG/PDF export throws. We
+ * fetch them server-side (no CORS) at push time and rewrite the references to
+ * self-contained `data:` URLs, so the stored push exports cleanly and survives
+ * the original URL later expiring.
+ *
+ * A remote URL that can't be inlined (timeout, non-image, too large, network
+ * error) is left untouched — it still displays cross-origin, it just won't
+ * appear in an export — so a dead link degrades gracefully instead of failing
+ * the push. Only `http(s)` URLs are touched; `data:`, `blob:`, and relative
+ * references are left alone.
+ */
+const PER_IMAGE_TIMEOUT_MS = 8000;
+const MAX_IMAGE_BYTES = 8_000_000;
+// `src="https://…"` (img/source/…) and CSS `url(https://…)` with optional quotes.
+// Capture group 2 is the URL in both.
+const URL_PATTERNS = [
+    /\bsrc\s*=\s*(["'])(https?:\/\/[^"']+?)\1/gi,
+    /url\(\s*(["']?)(https?:\/\/[^)"']+?)\1\s*\)/gi,
+];
+function collectRemoteUrls(html) {
+    const urls = new Set();
+    for (const pattern of URL_PATTERNS) {
+        const re = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = re.exec(html)) !== null) {
+            urls.add(match[2]);
+        }
+    }
+    return [...urls];
+}
+async function fetchAsDataUri(url, fetchImpl) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), PER_IMAGE_TIMEOUT_MS);
+    try {
+        const res = await fetchImpl(url, { signal: ac.signal, redirect: "follow" });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}`);
+        }
+        const type = (res.headers.get("content-type") || "").split(";")[0].trim();
+        if (!type.startsWith("image/")) {
+            throw new Error(`not an image (${type || "unknown content-type"})`);
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.byteLength > MAX_IMAGE_BYTES) {
+            throw new Error(`too large (${buf.byteLength} bytes)`);
+        }
+        return `data:${type};base64,${buf.toString("base64")}`;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch every remote image referenced in `html` and rewrite the references to
+ * `data:` URIs. Fetches run in parallel, each bounded by its own timeout, so
+ * total latency is roughly the slowest single image, not the sum.
+ *
+ * @param fetchImpl - injectable for tests; defaults to global `fetch`.
+ */
+export async function inlineRemoteImages(html, fetchImpl = fetch) {
+    const urls = collectRemoteUrls(html);
+    if (urls.length === 0) {
+        return { html, inlined: 0, failed: [] };
+    }
+    const dataUriByUrl = new Map();
+    const failed = [];
+    await Promise.all(urls.map(async (url) => {
+        try {
+            dataUriByUrl.set(url, await fetchAsDataUri(url, fetchImpl));
+        }
+        catch (err) {
+            failed.push({ url, reason: err instanceof Error ? err.message : String(err) });
+        }
+    }));
+    // Swap each URL inside its matched attribute/url() context only, so a URL
+    // that is a prefix of another can't be corrupted by a blind global replace.
+    let out = html;
+    for (const pattern of URL_PATTERNS) {
+        const re = new RegExp(pattern.source, pattern.flags);
+        out = out.replace(re, (full, _quote, url) => {
+            const dataUri = dataUriByUrl.get(url);
+            return dataUri ? full.replace(url, dataUri) : full;
+        });
+    }
+    return { html: out, inlined: dataUriByUrl.size, failed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "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",