@ammduncan/easel 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 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
+- **App-fidelity (`kind:"mockup"`/`"app"`) text painted with `light-dark()` now tracks the easel light/dark toggle instead of the OS color scheme.** Authors paint mockup ink with `color: light-dark(#dark-ink, #light-ink)`, which resolves off the document's *computed* `color-scheme` — not the `data-theme` attribute. The normal wrapper binds `color-scheme` to `data-theme` via `PRESET_TOKENS_CSS`, so `light-dark()` follows the toggle there. But the app-fidelity branch deliberately omits the preset tokens (the agent owns every pixel) and nothing else bound `color-scheme`, so it stayed at the author's `color-scheme: light dark` and `light-dark()` followed the **OS** preference. The symptom was intermittent and maddening: text was perfectly readable when the viewer's theme happened to match the OS, then washed out (white ink on a light card, or dark ink on a dark card) the moment they disagreed. Added a `:root[data-theme]{color-scheme}` binding to the shared `STRUCTURAL_PRIMITIVES_CSS` so `light-dark()` tracks the easel toggle in *every* wrapper branch. A new visual-regression fixture (`mockup-lightdark-ink`) audited across the theme × OS-scheme matrix reproduces the washout with the binding removed (contrast 1.0) and passes with it in place.
+- **Session-id resolution no longer drifts for non-Claude-Code MCP clients (opencode, Cursor, Windsurf, …).** The resolver's tier-4 fallback scanned `~/.claude/projects/<cwd>/` for the most-recently-modified transcript. That's a Claude-Code-specific signal, but it fired for *any* client — so a non-CC client running in a cwd that also holds Claude Code transcripts latched onto whichever transcript was touched last, and the resolved session id changed on every tool call (observed in opencode: `open()`, `push()`, and `label()` each landing on a different session). The scan is now gated behind a positive Claude Code signal (`CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`); other clients fall straight through to the stable per-process synthetic id (tier 5), so `open`/`push`/`label` all resolve to one session for the life of the chat. Covered by a new unit suite (`tests/unit/session-id.test.mjs`, run via `npm test`).
+
+### Docs
+- **`push` tool description and the using-easel skill now lead with a fidelity bar: ship high-fidelity, production-grade output by default.** Aimed at getting quality output from non-Claude models that don't infer it — every push should read like a screenshot of shipped software (real content, complete regions, exact values when recreating UI, real iconography, deliberate hierarchy), not a wireframe or grey-box. Low-fidelity is opt-in: only when the user explicitly says rough/wireframe/sketch is fine.
+
 ## 0.3.1 — 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");
@@ -120,6 +141,15 @@
      block, so stripping these in fidelity mode left the skill's own guidance
      ("wrap a mockup in .window") producing unstyled output. */
   const STRUCTURAL_PRIMITIVES_CSS = `
+/* Bind the CSS color-scheme to the host theme so any author CSS that uses
+   light-dark() (text ink, surfaces, borders) tracks the easel light/dark
+   TOGGLE rather than the OS preference. The default wrapper already gets this
+   via PRESET_TOKENS_CSS, but app-fidelity (kind:"mockup") pushes omit the
+   preset tokens — without this rule their light-dark() ink follows the OS
+   scheme and washes out whenever the OS disagrees with the easel toggle. */
+:root[data-theme="light"] { color-scheme: light; }
+:root[data-theme="dark"]  { color-scheme: dark; }
+
 /* Skeuomorphic macOS-style window chrome for UI mockups. Usage:
      <div class="window" data-title="App name"> …mockup content… </div>
    Draws a 40px title bar with the three traffic-light dots (red/yellow/green)
@@ -267,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")
@@ -645,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
@@ -667,6 +699,7 @@
             "*",
           );
       } catch (err) {
+        clearExportWatchdog(push.id);
         delete exportBtn.dataset.loading;
         console.error("[easel] export failed", err);
       }
@@ -760,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,
@@ -995,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>`;
@@ -1057,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/mcp.js

@@ -102,6 +102,15 @@ export async function main() {
             {
                 name: TOOL_PUSH,
                 description: "Push an HTML card to this session's live browser tab. Renders in a sandboxed iframe over a host-controlled canvas that can be LIGHT or DARK depending on the user's OS theme. Treat each card as a presentation slide — generous whitespace, presentation-scale type, tangible visuals. Your HTML MUST adapt to both light and dark modes.\n\n" +
+                    "═══ FIDELITY BAR — SHIP HIGH-FIDELITY BY DEFAULT ═══\n" +
+                    "Default to polished, production-grade output that looks like a real screenshot of shipped software or a finished design — NOT a rough sketch, wireframe, or grey-box placeholder. This is the default for EVERY push; you do not need to be asked for quality. Only drop to low-fidelity (wireframe, ASCII-ish boxes, lorem-ipsum, unstyled) when the user EXPLICITLY says rough/lo-fi/wireframe/sketch/quick-and-dirty is fine, or asks for a thumbnail/napkin idea. When in doubt, go high-fidelity.\n" +
+                    "What high-fidelity means concretely:\n" +
+                    "• REAL content, not placeholders. Plausible names, realistic numbers/dates/currency, actual copy — never 'Lorem ipsum', 'Label', 'Item 1 / Item 2', 'Title goes here', or '...'.\n" +
+                    "• COMPLETE, not stubbed. Fill every region you draw — no empty cells, half-built tables, or 'etc.' rows. If a screen has 8 nav items, draw 8.\n" +
+                    "• EXACT values when recreating real UI — pull true colors, spacing, radii, type, and layout from the component/theme/Figma/DevTools (see the recreation rules below). A close-but-wrong mock misleads more than none.\n" +
+                    "• Visual craft: deliberate hierarchy, aligned grids, consistent spacing scale, real iconography (inline SVG, not emoji-as-icon), proper empty/hover/active states where they matter. Avoid the generic-AI look (one purple gradient, evenly-sized boxes, centered everything).\n" +
+                    "• Tangible over abstract (see VISUALS): a mock should read as the actual thing, not labeled rectangles.\n" +
+                    "If you genuinely can't reach the bar (missing real values, ambiguous source), say so in ONE line in chat and push your best honest attempt — don't pass a rough draft off as final, and don't silently ship a grey-box.\n\n" +
                     "═══ ADAPTIVE COLOR (gets wrong most often) ═══\n" +
                     "• Do NOT set `background` on `body` or your root wrapper. The host paints the canvas — setting bg fights it and creates a wrong-shade block in the opposite mode.\n" +
                     "• Use `light-dark()` for ALL text colors, card backgrounds, borders, and decorative shades. Add `:root { color-scheme: light dark; }` so the function resolves. Hardcoded `color: #475569` goes invisible in dark mode; hardcoded `border: 1px solid #e5e5e5` becomes a hard white line.\n" +

package/dist/session-id.js

@@ -10,7 +10,11 @@ import { HOOK_DIR } from "./paths.js";
  *   3. Hook file at ~/.easel/hook/cc-session-<ppid>.txt (Claude Code's
  *      SessionStart hook writes this; pitstop-style PPID bridging)
  *   4. Most-recently-modified transcript under ~/.claude/projects/<cwd>/
- *      (Claude Code transcript scan)
+ *      (Claude Code transcript scan) — ONLY when a positive Claude Code env
+ *      signal is present. Other MCP clients (opencode, Cursor, Windsurf, …)
+ *      can share a cwd that already holds CC transcripts; without this guard
+ *      they'd latch onto whichever unrelated transcript was touched last and
+ *      the resolved session would drift on every tool call.
  *   5. Synthetic id derived from this MCP child's PPID — gives every other
  *      MCP client (Cursor, Windsurf, Claude Desktop, etc.) a stable session
  *      per chat without requiring any hook. The MCP child IS the session.
@@ -38,25 +42,33 @@ export function resolveClaudeSessionId(opts = {}) {
     catch {
         /* fall through */
     }
-    try {
-        const encoded = cwd.replace(/\//g, "-");
-        const dir = join(home, ".claude", "projects", encoded);
-        let bestId;
-        let bestMtime = 0;
-        for (const f of readdirSync(dir)) {
-            if (!f.endsWith(".jsonl"))
-                continue;
-            const m = statSync(join(dir, f)).mtimeMs;
-            if (m > bestMtime) {
-                bestMtime = m;
-                bestId = f.slice(0, -".jsonl".length);
+    // Tier 4 (transcript scan) is Claude-Code-specific: only trust it when we
+    // have positive evidence we're actually running inside Claude Code. For any
+    // other MCP client the scan would pick an unrelated, actively-changing CC
+    // transcript in the same cwd and the session id would drift per call — so
+    // skip straight to the stable per-process synthetic id (tier 5).
+    const isClaudeCode = Boolean(env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT);
+    if (isClaudeCode) {
+        try {
+            const encoded = cwd.replace(/\//g, "-");
+            const dir = join(home, ".claude", "projects", encoded);
+            let bestId;
+            let bestMtime = 0;
+            for (const f of readdirSync(dir)) {
+                if (!f.endsWith(".jsonl"))
+                    continue;
+                const m = statSync(join(dir, f)).mtimeMs;
+                if (m > bestMtime) {
+                    bestMtime = m;
+                    bestId = f.slice(0, -".jsonl".length);
+                }
             }
+            if (bestId)
+                return bestId;
+        }
+        catch {
+            /* fall through */
         }
-        if (bestId)
-            return bestId;
-    }
-    catch {
-        /* fall through */
     }
     return syntheticSessionIdFromPpid(ppid);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",
@@ -43,6 +43,7 @@
     "build": "tsc && node scripts/copy-client.mjs",
     "start": "node dist/cli.js",
     "dev": "tsc --watch",
+    "test": "npm run build && node --test tests/unit/*.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "publishConfig": {

package/skills/using-easel/SKILL.md

@@ -49,6 +49,20 @@ Don't poll. Just react to the hint when it appears.
 
 Pushed cards are **presentations**, not UI dashboards. Read each rule and apply it; the wrapper gives you good defaults but they only carry so far.
 
+### 0. Fidelity bar — ship high-fidelity by default
+
+Every push should look like a **screenshot of shipped software or a finished design** — polished and production-grade — not a rough sketch, wireframe, or grey-box placeholder. Quality is the default; you don't need to be asked for it. Only drop to low-fidelity when the user **explicitly** says rough / lo-fi / wireframe / sketch / quick-and-dirty is fine, or asks for a napkin-level thumbnail. When unsure, go high-fidelity.
+
+Concretely, high-fidelity means:
+
+- **Real content, never placeholders.** Plausible names, realistic numbers/dates/currency, actual copy — no "Lorem ipsum", "Label", "Item 1 / Item 2", "Title goes here", or "…".
+- **Complete, not stubbed.** Fill every region you draw — no empty cells, half-built tables, or "etc." rows. A nav with 8 items shows 8.
+- **Exact values when recreating real UI.** Pull true colors, spacing, radii, type, and layout from the component / theme / Figma / DevTools (see [Use the actual values](#use-the-actual-values-not-approximations)). A close-but-wrong mock misleads more than none.
+- **Visual craft.** Deliberate hierarchy, aligned grids, a consistent spacing scale, real iconography (inline SVG — not emoji standing in for icons), and the states that matter (empty / hover / active). Avoid the generic-AI look: one purple gradient, evenly-sized boxes, everything centered.
+- **Tangible over abstract** (see [Visualizations](#5-visualizations--tangible-over-abstract)) — the mock should read as the actual thing, not labeled rectangles.
+
+If you genuinely can't clear the bar (missing real values, ambiguous source), say so in one line in chat and push your best honest attempt — don't pass a rough draft off as final, and don't silently ship a grey-box.
+
 ### 1. Typography
 
 - **Page lede**: 40–52 px, weight 500, letter-spacing ≈ -0.025em