@ammduncan/easel 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.4.2 — 2026-05-28
+
+### Added
+- **Pushes now self-check for low-contrast text and stamp a warning chip on the card when they find any.** The #1 recurring author bug — flagged prominently in the push tool description and *still* shipped repeatedly — is a hand-rolled dark code container: author sets `background:#0b0f17` on a custom div but leaves base text inheriting the wrapper's `light-dark(#111, …)` ink, which resolves to near-black against the dark panel in light host mode and the code vanishes (only spans with explicit syntax colours survive). A new in-iframe guard now runs after fonts ready, walks text-bearing elements (bounded at 2000 for cheap), computes WCAG contrast ratio between each one's text colour and its effective background (climbing past transparent ancestors), and posts back `easel:contrast-warn` if any ratio is below 3:1 — well below AA's 4.5:1 floor and the point where text becomes genuinely unreadable. The parent stamps an amber `⚠ contrast` chip on the push's meta row with the offender list in the tooltip (tag, class, ratio, fg-on-bg rgb pair), and the iframe also `console.warn`s the full sample so the offenders surface in DevTools. Symmetric: catches both directions of the bug (dark-on-dark *and* light-on-light hand-rolled containers). The guard is injected into all three render paths (`buildDefaultWrapper` app-fidelity branch, `buildDefaultWrapper` presentation branch, `injectBridge`), and a regression test asserts the injection count so no future render branch can silently skip the check. The right fix is still to reach for the locked-mode primitives (`<div class="code">` / `<div class="terminal">`), and the warning text points authors there. Covered by `tests/unit/contrast-guard.test.mjs`.
+
 ## 0.4.1 — 2026-05-26
 
 ### Fixed

package/dist/client/viewer.css

@@ -555,6 +555,26 @@ body {
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
 }
 
+/* Contrast warning chip — stamped on a card by stampContrastWarning() after
+   the iframe reports text failing WCAG 3:1 against its effective background.
+   Amber, not red: this is an author-side smell, not a render error, and the
+   push is still visible. Hover for the offender list. */
+.push-warn {
+  font-size: 11px;
+  padding: 4px 10px;
+  border-radius: 999px;
+  background: rgba(245, 158, 11, 0.14);
+  color: #b45309;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  letter-spacing: 0.02em;
+  cursor: help;
+  white-space: nowrap;
+}
+:root[data-theme="dark"] .push-warn {
+  background: rgba(245, 158, 11, 0.18);
+  color: #fbbf24;
+}
+
 .push-del,
 .push-export {
   display: inline-flex;

package/dist/client/viewer.js

@@ -11,7 +11,8 @@
   // 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;
+  // Generous (2 min) so large/heavy PDF/PNG exports have time to rasterize.
+  const EXPORT_TIMEOUT_MS = 120000;
   const exportWatchdogs = new Map();
   function clearExportSpinner(pushId) {
     const iframeEl = cardsEl.querySelector(
@@ -295,6 +296,10 @@
       }
       return;
     }
+    if (data.type === "easel:contrast-warn") {
+      stampContrastWarning(data.pushId, data.count, data.samples);
+      return;
+    }
     if (data.type === "easel:image-error") {
       console.error("[easel] iframe export error", data);
       clearExportWatchdog(data.pushId);
@@ -776,6 +781,8 @@
     if (cleaned.startsWith("<![CDATA[") && cleaned.endsWith("]]>")) {
       cleaned = cleaned.slice(9, -3).trim();
     }
+    // Make nested iframes capturable on export (no-op when there are none).
+    cleaned = injectNestedCaptureBridge(cleaned);
     const preset = currentPreset();
     const lower = cleaned.toLowerCase();
     if (lower.startsWith("<!doctype") || lower.startsWith("<html")) {
@@ -793,6 +800,79 @@
     );
   }
 
+  /**
+   * Capture bridge injected into every NESTED iframe's srcdoc at wrap time.
+   *
+   * html-to-image clones the DOM into an SVG <foreignObject>; it cannot reach
+   * inside an <iframe> document (and the outer push iframe is opaque-origin, so
+   * it can't read nested contentDocuments either — verified empirically). So a
+   * push built from nested iframes used to export with every panel blank.
+   *
+   * This listener lives INSIDE each nested iframe: on `easel:capture-nested` it
+   * loads html-to-image (if absent), renders its own visible viewport region to
+   * an SVG dataURL, and posts it back tagged with the request token. The outer
+   * export bridge then composites these onto the final canvas. Inert until asked.
+   */
+  function nestedCaptureScript() {
+    return `(function(){
+if(window.__easelNestedCapture)return;
+window.__easelNestedCapture=1;
+function reply(m){try{parent.postMessage(m,'*')}catch(_){}}
+function load(cb){
+if(window.htmlToImage)return cb();
+var s=document.createElement('script');
+s.src='https://cdn.jsdelivr.net/npm/html-to-image@1.11.13/dist/html-to-image.js';
+s.onload=function(){cb()};
+s.onerror=function(){cb()};
+(document.head||document.documentElement).appendChild(s);
+}
+window.addEventListener('message',function(e){
+var d=e&&e.data;
+if(!d||d.type!=='easel:capture-nested')return;
+var tok=d.token;
+load(function(){
+if(!window.htmlToImage){reply({type:'easel:nested-error',token:tok,message:'html-to-image not loaded'});return}
+var de=document.documentElement;
+var w=de.clientWidth||de.scrollWidth;
+var h=de.clientHeight||de.scrollHeight;
+window.htmlToImage.toSvg(de,{width:w,height:h,cacheBust:true})
+.then(function(u){reply({type:'easel:nested-ready',token:tok,dataUrl:u})})
+.catch(function(err){reply({type:'easel:nested-error',token:tok,message:String(err&&err.message||err)})});
+});
+});
+})();`;
+  }
+
+  /**
+   * Append the nested-capture bridge into each `srcdoc="…"` in the pushed HTML
+   * so nested iframes can be composited on export. Encodes only `&` and `"`
+   * (the attribute delimiter) so it survives regardless of how the author
+   * encoded the rest of the srcdoc; the script is appended after the value's
+   * existing markup (a <script> after </html> still runs). No-ops when there
+   * are no nested iframes, and skips any srcdoc already carrying the bridge.
+   */
+  function injectNestedCaptureBridge(html) {
+    if (!/srcdoc=/i.test(html)) return html;
+    // Full entity-encode (matches the common fully-encoded srcdoc style and
+    // decodes correctly under minimal-encoded ones too) and insert BEFORE the
+    // closing body/html so the listener registers during parse — a trailing
+    // <script> after the document end did not reliably execute in sandboxed
+    // srcdoc iframes.
+    const enc = ("<script>" + nestedCaptureScript() + "</scr" + "ipt>")
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#x27;");
+    return html.replace(/srcdoc="([^"]*)"/gi, (m, sd) => {
+      if (sd.indexOf("__easelNestedCapture") !== -1) return m;
+      let at = sd.lastIndexOf("&lt;/body&gt;");
+      if (at === -1) at = sd.lastIndexOf("&lt;/html&gt;");
+      const next = at >= 0 ? sd.slice(0, at) + enc + sd.slice(at) : sd + enc;
+      return 'srcdoc="' + next + '"';
+    });
+  }
+
   /**
    * In-iframe message listener that turns the rendered push into a PNG/JPEG
    * dataURL on `easel:image` and posts back `easel:image-ready` / `-error`.
@@ -811,31 +891,93 @@
    */
   function imageExportScript() {
     return (
-      "(function(){var PR=4;" +
+      "(function(){" +
+      // PIXEL_RATIO 4 for crisp output, but clamp so the biggest canvas side
+      // stays under Chrome's safe ceiling — very tall pushes used to blank/throw.
+      "function ratio(w,h){var MAX=32760;var big=Math.max(w,h);var pr=4;if(big*pr>MAX){pr=Math.max(1,Math.floor(MAX/big*100)/100)}return pr}" +
       "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){" +
+      // Ask each nested iframe to render itself; resolves to [{iframe,dataUrl}]
+      // (dataUrl null on timeout / no bridge, so that panel stays as-is).
+      "function captureNested(frames){return Promise.all(frames.map(function(f,i){return new Promise(function(resolve){" +
+      "var tok='easelN'+i+'_'+(window.performance&&performance.now?Math.round(performance.now()):i);var done=false;" +
+      "function finish(u){if(done)return;done=true;window.removeEventListener('message',onMsg);clearTimeout(t);resolve({iframe:f,dataUrl:u})}" +
+      "function onMsg(e){var d=e&&e.data;if(!d||d.token!==tok)return;if(d.type==='easel:nested-ready'){finish(d.dataUrl)}else if(d.type==='easel:nested-error'){finish(null)}}" +
+      "window.addEventListener('message',onMsg);var t=setTimeout(function(){finish(null)},9000);" +
+      "try{f.contentWindow.postMessage({type:'easel:capture-nested',token:tok},'*')}catch(e){finish(null)}" +
+      "})}))}" +
+      // Base snapshot → fill bg → draw page → overlay each nested capture at its
+      // on-screen rect (SVG stays crisp when scaled into the frame box).
+      "function rasterize(svgUrl,w,h,pr,bg,shots){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));" +
+      "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)}};" +
+      "var pend=shots.filter(function(s){return s.dataUrl});if(!pend.length){return resolve(c)}" +
+      "var left=pend.length;" +
+      "pend.forEach(function(s){var r=s.iframe.getBoundingClientRect();var ni=new Image();" +
+      "ni.onload=function(){try{x.drawImage(ni,(r.left+window.scrollX)*pr,(r.top+window.scrollY)*pr,r.width*pr,r.height*pr)}catch(_){}if(--left===0)resolve(c)};" +
+      "ni.onerror=function(){if(--left===0)resolve(c)};ni.src=s.dataUrl})" +
+      "}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 frames=Array.prototype.slice.call(document.querySelectorAll('iframe'));" +
+      // Force lazy nested iframes to load before capture, else off-screen panels
+      // export blank. Settle briefly so their srcdoc bridge is live, then capture.
+      "frames.forEach(function(f){try{f.loading='eager'}catch(_){}});" +
       "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},'*')})" +
+      "var pr=ratio(w,h);" +
+      "new Promise(function(res){setTimeout(res,frames.length?700:0)}).then(function(){return captureNested(frames)}).then(function(shots){" +
+      "return window.htmlToImage.toSvg(document.documentElement,{width:w,height:h,cacheBust:true})" +
+      ".then(function(u){return rasterize(u,w,h,pr,bg,shots)})})" +
+      ".then(function(c){var u=fmt==='pdf'?c.toDataURL('image/jpeg',1.0):c.toDataURL('image/png');" +
+      "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)})})();"
     );
   }
 
+  /**
+   * In-iframe contrast guard. Scans rendered text-bearing elements and flags
+   * any whose computed text colour fails a WCAG contrast ratio of 3:1 against
+   * its effective background (climbs ancestors past transparent fills).
+   *
+   * Catches BOTH directions of the recurring locked-mode bug from Rule 30:
+   *   - dark text on a hand-rolled dark code container (the #1 case — author
+   *     skipped the .code/.terminal primitive and base text inherits a
+   *     light-mode ink against #0f172a)
+   *   - light text on a hand-rolled bright container
+   *
+   * Runs once after fonts ready + a 400ms settle. Bounded at 2000 text-bearing
+   * elements scanned to stay cheap on large pushes. Posts a single
+   * easel:contrast-warn to the parent with up to 5 offender samples; parent
+   * stamps a chip on the card so the author actually notices.
+   *
+   * Shared verbatim by buildDefaultWrapper (both branches) and injectBridge.
+   */
+  function contrastGuardScript(pushId) {
+    return (
+      "(function(){var ID=" +
+      JSON.stringify(pushId) +
+      ";function parseColor(c){if(!c)return null;var m=c.match(/rgba?\\(([^)]+)\\)/);if(!m)return null;var p=m[1].split(',').map(function(s){return parseFloat(s.trim())});if(p.length<3||p.some(isNaN))return null;return{r:p[0],g:p[1],b:p[2],a:p.length>3?p[3]:1}}" +
+      "function lum(c){function ch(v){v/=255;return v<=0.03928?v/12.92:Math.pow((v+0.055)/1.055,2.4)}return 0.2126*ch(c.r)+0.7152*ch(c.g)+0.0722*ch(c.b)}" +
+      "function contrast(a,b){var la=lum(a),lb=lum(b);var hi=Math.max(la,lb),lo=Math.min(la,lb);return(hi+0.05)/(lo+0.05)}" +
+      "function effBg(el){var n=el;while(n&&n.nodeType===1){var cs=getComputedStyle(n);var bg=parseColor(cs.backgroundColor);if(bg&&bg.a>0.05)return bg;n=n.parentElement}return{r:255,g:255,b:255,a:1}}" +
+      "function hasDirectText(el){for(var i=0;i<el.childNodes.length;i++){var n=el.childNodes[i];if(n.nodeType===3&&n.nodeValue.trim().length>0)return true}return false}" +
+      "function fmt(c){return'rgb('+Math.round(c.r)+','+Math.round(c.g)+','+Math.round(c.b)+')'}" +
+      "function scan(){if(!document.body)return;var offenders=[];var seen=0;var all=document.body.querySelectorAll('*');for(var i=0;i<all.length&&seen<2000;i++){var el=all[i];if(!hasDirectText(el))continue;seen++;var cs=getComputedStyle(el);if(cs.visibility==='hidden'||cs.display==='none')continue;var fg=parseColor(cs.color);if(!fg||fg.a<0.05)continue;var bg=effBg(el);var ratio=contrast(fg,bg);if(ratio<3){offenders.push({tag:el.tagName.toLowerCase(),cls:(el.className&&el.className.toString?el.className.toString():'').slice(0,80),text:(el.textContent||'').trim().slice(0,60),ratio:Math.round(ratio*100)/100,fg:fmt(fg),bg:fmt(bg)})}}" +
+      "if(offenders.length){console.warn('[easel] low-contrast text detected ('+offenders.length+' element(s), threshold 3:1). The #1 cause is a hand-rolled dark code container — use <div class=\"code\"> or <div class=\"terminal\"> instead; they lock background AND ink and re-scope color:inherit to children. Offenders:',offenders.slice(0,10));try{parent.postMessage({type:'easel:contrast-warn',pushId:ID,count:offenders.length,samples:offenders.slice(0,5)},'*')}catch(e){}}}" +
+      "function run(){setTimeout(scan,400)}" +
+      "if(document.fonts&&document.fonts.ready){document.fonts.ready.then(run).catch(run)}else{run()}" +
+      "})();"
+    );
+  }
+
   function buildDefaultWrapper(body, theme, preset, pushId, appFidelity) {
     const density = currentDensity();
     // app-fidelity mode: skip presentation defaults (presets, semantic chips,
@@ -860,6 +1002,7 @@ ${STRUCTURAL_PRIMITIVES_CSS}
 <body>
 ${body}
 <script>${imageExportScript()}</script>
+<script>${contrastGuardScript(pushId)}</script>
 <script>${selfMeasureScript(pushId)}</script>
 </body>
 </html>`;
@@ -1076,6 +1219,7 @@ ${body}
 })();
 </script>
 <script>${imageExportScript()}</script>
+<script>${contrastGuardScript(pushId)}</script>
 <script>${selfMeasureScript(pushId)}</script>
 </body>
 </html>`;
@@ -1088,8 +1232,9 @@ ${body}
       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(_){}}})})();</script>";
     const imageScript = "<script>" + imageExportScript() + "</script>";
+    const guardScript = "<script>" + contrastGuardScript(pushId) + "</script>";
     const measureScript = "<script>" + selfMeasureScript(pushId) + "</script>";
-    const combined = configScript + imageScript + measureScript;
+    const combined = configScript + imageScript + guardScript + measureScript;
     if (/<\/body>/i.test(html)) return html.replace(/<\/body>/i, combined + "</body>");
     return html + combined;
   }
@@ -1108,6 +1253,35 @@ ${body}
     return { wasNearBottom, card };
   }
 
+  /**
+   * Stamp a "contrast" warning chip on a push card's meta row after the
+   * iframe reports low-contrast text. Idempotent: only inserts once per push.
+   * Tooltip lists the first few offenders so the author can locate them
+   * without opening DevTools. The console.warn fires inside the iframe too,
+   * so DevTools still shows the full sample list and computed rgb pairs.
+   */
+  function stampContrastWarning(pushId, count, samples) {
+    if (!pushId) return;
+    const card = document.getElementById("push-" + pushId);
+    if (!card) return;
+    const meta = card.querySelector(".push-meta");
+    if (!meta || meta.querySelector(".push-warn")) return;
+    const chip = document.createElement("span");
+    chip.className = "push-warn";
+    chip.textContent = "⚠ contrast";
+    const head = `${count} low-contrast element(s) detected (WCAG ratio < 3:1).\nMost common cause: a hand-rolled dark code container — use class="code" or class="terminal".\n`;
+    const list = (samples || [])
+      .map((s) => `• <${s.tag}${s.cls ? "." + s.cls.split(/\s+/).join(".") : ""}> "${s.text}" (${s.ratio}:1, ${s.fg} on ${s.bg})`)
+      .join("\n");
+    chip.title = head + list;
+    const time = meta.querySelector(".push-time");
+    if (time) {
+      meta.insertBefore(chip, time);
+    } else {
+      meta.appendChild(chip);
+    }
+  }
+
   function removeCardFromDom(pushId) {
     const card = document.getElementById("push-" + pushId);
     if (card) card.remove();

package/dist/mcp.js

@@ -127,7 +127,8 @@ export async function main() {
                     "It locks BOTH background (#0f172a) and ink (#e6edf3), re-scopes `color:inherit` to every child, and provides verified github-dark syntax token classes you can drop onto spans — NO per-token tuning needed:\n" +
                     "  .kw (keywords #ff7b72) · .string (#a5d6ff) · .fn (function #d2a8ff) · .prop (identifiers #79c0ff) · .num (#ffa657) · .comment (#8b949e) · .muted (#94a3b8) · .accent (#6ee7b7)\n" +
                     "  e.g. <div class=\"code\"><span class=\"kw\">gcloud</span> services enable run.googleapis.com</div>\n" +
-                    "Plain <pre>/<code> are also already safe (bg+ink token pair). Only reach for a fully custom container when .code/.terminal genuinely don't fit — and then obey the locked-mode rule below.\n\n" +
+                    "Plain <pre>/<code> are also already safe (bg+ink token pair). Only reach for a fully custom container when .code/.terminal genuinely don't fit — and then obey the locked-mode rule below.\n" +
+                    "SAFETY NET: every push self-checks for low-contrast text (WCAG <3:1) after render. If your push trips it, the card gets an amber `⚠ contrast` chip on the meta row with the offender list in the tooltip, and the iframe console.warns with sample rgb pairs. Treat the chip as a build-failure-equivalent — the fix is almost always swapping the hand-rolled container for `.code` / `.terminal` (or, for a non-code locked-bg container, applying the locked-mode rule below).\n\n" +
                     "═══ COPY-PASTE STARTER (any OTHER LOCKED-MODE container — brand hero, custom panel) ═══\n" +
                     "If a container has a FIXED background (not `light-dark()`), you MUST set its own text color AND re-scope `color: inherit` to its children. Otherwise the children inherit `light-dark(...)` from `.wrap` and the text flips to the wrong shade in one mode (e.g. dark text on a locked-dark panel in light host mode → invisible).\n" +
                     "  .hero { background: #0f172a; color: #e6edf3; border-radius: 12px; padding: 20px 24px; }\n" +

package/package.json

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