@marshalliqiu/loupe 0.1.0 → 0.2.0

package/README.md

@@ -75,6 +75,18 @@ loupe spec spec/guest-checkout.html  # on Execute: write the companion spec (gue
 
 > Use `npx @marshalliqiu/loupe new <file>` to map out what we discussed before building it.
 
+**Skill (slash command).** Install the Loupe skill in the [Agent Skills](https://github.com/anthropics/skills) format with `npx skills` — it teaches your agent the full grill → lock → before/after workflow and, in Claude Code, exposes it as `/loupe`:
+
+```sh
+npx skills add jerry5789k1/loupe --skill loupe
+```
+
+The skill runs the CLI on demand via `npx -y @marshalliqiu/loupe`, so nothing else needs to be installed. Then:
+
+```
+/loupe let's inspect the guest-checkout change before building it
+```
+
 **Session hook.** Want Loupe's ambient context — including your live open sessions — fed into every agent session instead of loading on demand? Install globally and opt into the hook:
 
 ```sh

package/dist/cli.mjs

@@ -801,6 +801,7 @@ function defaultPort() {
 
 // src/scaffold.js
 var MERMAID_CDN = "https://cdn.jsdelivr.net/npm/mermaid@11.15.0/dist/mermaid.esm.min.mjs";
+var SVG_PAN_ZOOM_CDN = "https://esm.sh/svg-pan-zoom@3.6.2";
 function escapeHtml(value) {
   return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 }
@@ -1201,8 +1202,18 @@ ${decisionSection()}`;
 
   .loupe-card { background: var(--surface); border: 1px solid var(--hair); border-radius: var(--radius); padding: 22px; }
 
-  .loupe-diagram { display: flex; justify-content: center; min-width: 0; overflow-x: auto; }
-  .loupe-diagram .mermaid { min-width: 0; }
+  /* A pannable/zoomable viewport: the diagram renders at full size inside a fixed
+     frame so it never shrinks to fit the card. Drag to pan, \u2318/Ctrl+wheel to zoom. */
+  .loupe-diagram { position: relative; height: clamp(320px, 52vh, 580px); min-width: 0; overflow: hidden; border: 1px solid var(--hair); border-radius: var(--radius); background: var(--surface); cursor: grab; user-select: none; }
+  .loupe-diagram:active { cursor: grabbing; }
+  /* gesture hint \u2014 purely informational, never intercepts clicks */
+  .loupe-diagram-hint { position: absolute; top: 8px; right: 10px; z-index: 2; pointer-events: none; font-size: 11px; color: var(--ink-3); background: rgba(255,255,255,0.82); border: 1px solid var(--hair); border-radius: 999px; padding: 2px 9px; }
+  /* margin:0 \u2014 <pre>'s default 1em top/bottom margin (~26px) otherwise overflows the
+     fixed-height frame and trips the layout audit's clipped-text check. */
+  .loupe-diagram .mermaid { width: 100%; height: 100%; min-width: 0; margin: 0; padding: 0; }
+  /* display:block removes the inline-element baseline descender gap (~6px) that
+     otherwise overflows the frame and re-trips the layout audit. */
+  .loupe-diagram svg { display: block; width: 100% !important; height: 100% !important; max-width: none !important; }
   .loupe-legend { display: flex; flex-wrap: wrap; gap: 16px; margin-top: 14px; font-size: 13px; color: var(--ink-2); }
   .loupe-legend span { display: inline-flex; align-items: center; gap: 7px; }
   .loupe-sw { width: 13px; height: 13px; border-radius: 4px; display: inline-block; }
@@ -1277,12 +1288,67 @@ ${lenses}
 
 <script type="module">
   import mermaid from "${MERMAID_CDN}";
+  // useMaxWidth:true makes mermaid emit a viewBox, so each SVG scales to fit its frame
+  // immediately (no transient natural-size overflow before svg-pan-zoom's async CDN
+  // import resolves \u2014 that overflow tripped the layout audit). The tall .loupe-diagram
+  // frame + svg-pan-zoom fit then enlarge the diagram to fill the frame, so it stays big.
   mermaid.initialize({ startOnLoad: false, theme: "base", securityLevel: "loose", flowchart: { useMaxWidth: true } });
   try {
     await mermaid.run();
   } catch (e) {
     console.error("Loupe: mermaid render failed", e);
   }
+  // Make every rendered diagram pannable/zoomable. Loaded after mermaid so the SVGs
+  // exist; isolated in its own try so a CDN/offline failure leaves diagrams static but intact.
+  try {
+    const svgPanZoom = (await import("${SVG_PAN_ZOOM_CDN}")).default;
+    for (const svg of document.querySelectorAll(".loupe-diagram .mermaid svg")) {
+      svg.style.maxWidth = "none";
+      svg.style.width = "100%";
+      svg.style.height = "100%";
+      const pz = svgPanZoom(svg, {
+        zoomEnabled: true,
+        controlIconsEnabled: true, // discoverable + / \u2212 / reset(fit) buttons
+        fit: true,
+        center: true,
+        minZoom: 0.2,
+        maxZoom: 12,
+        dblClickZoomEnabled: false, // leave double-click free; pan is drag, annotate is click
+        // A plain wheel must scroll the PAGE, not zoom the diagram \u2014 otherwise the page
+        // scroll gets hijacked whenever the cursor is over a diagram (the reported bug).
+        mouseWheelZoomEnabled: false,
+        // Do NOT preventDefault on mouse events: Loupe's annotation picker listens for
+        // click (capture phase); the default true swallows that click. false keeps
+        // drag-to-pan AND click-to-annotate working.
+        preventMouseEventsDefault: false,
+      });
+      const frame = svg.closest(".loupe-diagram");
+      // Zoom is intentional only: \u2318/Ctrl + wheel zooms at the cursor; a plain wheel is
+      // ignored here so the page scrolls normally. (The +/\u2212/reset buttons also zoom.)
+      frame.addEventListener(
+        "wheel",
+        (e) => {
+          if (!(e.ctrlKey || e.metaKey)) return; // plain scroll \u2192 let the page handle it
+          e.preventDefault();
+          const rect = svg.getBoundingClientRect();
+          // gentle step per wheel tick \u2014 wheels/trackpads fire many events, so a small
+          // factor keeps zoom controllable instead of jumping.
+          const step = 1.06;
+          pz.zoomAtPointBy(e.deltaY < 0 ? step : 1 / step, { x: e.clientX - rect.left, y: e.clientY - rect.top });
+        },
+        { passive: false },
+      );
+      // discoverability hint, pointer-events:none so it never blocks a click
+      if (!frame.querySelector(".loupe-diagram-hint")) {
+        const hint = document.createElement("div");
+        hint.className = "loupe-diagram-hint";
+        hint.textContent = "drag to pan \xB7 \u2318/Ctrl + scroll to zoom";
+        frame.appendChild(hint);
+      }
+    }
+  } catch (e) {
+    console.error("Loupe: pan/zoom init failed (diagrams stay static)", e);
+  }
 </script>
 
 <script>
@@ -1782,6 +1848,7 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
       if (!(el instanceof Element) || isLavishUi(el)) return;
       if (isIntentionalHorizontalScroller(el)) return;
       elements.push(el);
+      if (el.tagName && el.tagName.toLowerCase() === "svg") return;
       for (const child of el.children) walk(child);
     }
     if (document.body) walk(document.body);
@@ -1981,13 +2048,13 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     document.documentElement.appendChild(host);
     shadow = host.attachShadow({ mode: "open" });
     const style = document.createElement("style");
-    style.textContent = `:host{all:initial;position:fixed;z-index:2147483647;left:0;top:0;color-scheme:dark;--ink-900:#0f1115;--ink-800:#11141a;--ink-700:#171a21;--ink-600:#1c212b;--steel-700:#2a2f3a;--steel-600:#303745;--steel-500:#3c4557;--steel-400:#8c96aa;--steel-300:#aeb6c6;--steel-200:#b9c0cf;--steel-100:#d8deea;--cream-50:#fffbf3;--cream-100:#f7f3ea;--cream-200:#e8e1cf;--brass-500:#f4c95d;--brass-400:#ffd877;--brass-ink:#17130a;--bg:var(--ink-900);--bg-panel:var(--ink-800);--bg-elevated:var(--ink-600);--fg:var(--cream-100);--fg-faint:var(--steel-300);--border:var(--steel-600);--accent:#f4c95d;--accent-hover:#ffd877;--font-sans:Geist,ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;--font-mono:"Geist Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;--radius-md:10px;--radius-xl:14px;--shadow-floating:0 20px 70px rgba(0,0,0,.35);font-family:var(--font-sans)}*{box-sizing:border-box}:focus-visible{outline:2px solid var(--accent);outline-offset:2px}.lavish-text-highlight{position:fixed;pointer-events:none;background:rgba(244,201,93,.28);border-radius:2px;box-shadow:0 0 0 1px rgba(244,201,93,.45)}.lavish-annotation-card{position:fixed;width:min(320px,calc(100vw - 24px));padding:12px;border-radius:var(--radius-xl);background:var(--bg-panel);color:var(--fg);border:1px solid var(--accent);box-shadow:var(--shadow-floating);font:14px/1.4 var(--font-sans)}.lavish-heading{font-weight:700;margin-bottom:6px}.lavish-annotation-card textarea{width:100%;min-height:86px;resize:vertical;border-radius:var(--radius-md);border:1px solid var(--border);background:var(--bg);color:var(--fg);padding:9px;font:inherit;font-family:var(--font-sans)}.lavish-annotation-card textarea::placeholder{color:var(--fg-faint)}.lavish-annotation-card .lavish-hint{margin-top:6px;font-size:11px;color:var(--fg-faint)}.lavish-annotation-card .lavish-row{display:flex;gap:8px;justify-content:flex-end;margin-top:8px}.lavish-annotation-card button{border:0;border-radius:var(--radius-md);padding:8px 10px;font-family:var(--font-sans);font-size:13px;font-weight:700;cursor:pointer}.lavish-annotation-card button:active{opacity:.85}.lavish-annotation-card .lavish-send{background:var(--accent);color:var(--brass-ink)}.lavish-annotation-card .lavish-send:hover{background:var(--accent-hover)}.lavish-annotation-card .lavish-cancel{background:var(--steel-700);color:var(--fg)}`;
+    style.textContent = `:host{all:initial;position:fixed;z-index:2147483647;left:0;top:0;color-scheme:dark;--ink-900:#0f1115;--ink-800:#11141a;--ink-700:#171a21;--ink-600:#1c212b;--steel-700:#2a2f3a;--steel-600:#303745;--steel-500:#3c4557;--steel-400:#8c96aa;--steel-300:#aeb6c6;--steel-200:#b9c0cf;--steel-100:#d8deea;--cream-50:#fffbf3;--cream-100:#f7f3ea;--cream-200:#e8e1cf;--brass-500:#f4c95d;--brass-400:#ffd877;--brass-ink:#17130a;--bg:var(--ink-900);--bg-panel:var(--ink-800);--bg-elevated:var(--ink-600);--fg:var(--cream-100);--fg-faint:var(--steel-300);--border:var(--steel-600);--accent:#f4c95d;--accent-hover:#ffd877;--font-sans:Geist,ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;--font-mono:"Geist Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;--radius-md:10px;--radius-xl:14px;--shadow-floating:0 20px 70px rgba(0,0,0,.35);font-family:var(--font-sans)}*{box-sizing:border-box}:focus-visible{outline:2px solid var(--accent);outline-offset:2px}.lavish-text-highlight{position:fixed;pointer-events:none;background:rgba(244,201,93,.28);border-radius:2px;box-shadow:0 0 0 1px rgba(244,201,93,.45)}.lavish-annotation-card{position:fixed;width:min(320px,calc(100vw - 24px));padding:12px;border-radius:var(--radius-xl);background:var(--bg-panel);color:var(--fg);border:1px solid var(--accent);box-shadow:var(--shadow-floating);font:14px/1.4 var(--font-sans)}.lavish-heading{font-weight:700;margin-bottom:6px}.lavish-annotation-card textarea{width:100%;min-height:86px;resize:vertical;border-radius:var(--radius-md);border:1px solid var(--border);background:var(--bg);color:var(--fg);padding:9px;font:inherit;font-family:var(--font-sans)}.lavish-annotation-card textarea::placeholder{color:var(--fg-faint)}.lavish-annotation-card .lavish-hint{margin-top:6px;font-size:11px;color:var(--fg-faint)}.lavish-annotation-card .lavish-row{display:flex;gap:8px;justify-content:flex-end;margin-top:8px}.lavish-annotation-card button{border:0;border-radius:var(--radius-md);padding:8px 10px;font-family:var(--font-sans);font-size:13px;font-weight:700;cursor:pointer}.lavish-annotation-card button:active{opacity:.85}.lavish-annotation-card .lavish-send{background:var(--accent);color:var(--brass-ink)}.lavish-annotation-card .lavish-send:hover{background:var(--accent-hover)}.lavish-annotation-card .lavish-cancel{background:var(--steel-700);color:var(--fg)}.lavish-select-pill{position:fixed;display:flex;align-items:center;gap:10px;max-width:min(340px,calc(100vw - 24px));padding:5px 6px 5px 12px;border-radius:999px;background:var(--bg-panel);color:var(--fg);border:1px solid var(--accent);box-shadow:var(--shadow-floating);font:13px/1.3 var(--font-sans)}.lavish-select-pill .lavish-pill-label{display:flex;align-items:center;gap:7px;min-width:0;overflow:hidden;white-space:nowrap;text-overflow:ellipsis}.lavish-select-pill .lavish-pill-tag{flex:none;font-family:var(--font-mono);font-size:11px;color:var(--accent)}.lavish-select-pill .lavish-pill-text{overflow:hidden;text-overflow:ellipsis;color:var(--fg);font-weight:700}.lavish-select-pill .lavish-pill-add{flex:none;border:0;border-radius:999px;padding:6px 12px;background:var(--accent);color:var(--brass-ink);font:inherit;font-weight:700;cursor:pointer}.lavish-select-pill .lavish-pill-add:hover{background:var(--accent-hover)}`;
     shadow.appendChild(style);
     return shadow;
   }
   function closeCard() {
     if (shadow) {
-      for (const el of [...shadow.querySelectorAll(".lavish-annotation-card")]) el.remove();
+      for (const el of [...shadow.querySelectorAll(".lavish-annotation-card,.lavish-select-pill")]) el.remove();
     }
     clearHighlight(hovered);
     clearHighlight(selected);
@@ -1995,6 +2062,49 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     clearTextHighlight();
     selected = null;
   }
+  function describeTarget(el) {
+    const c = context(el);
+    let label = c.text;
+    if (!label && el && el.closest) {
+      const group = el.closest("g");
+      if (group) label = (group.textContent || "").trim().replace(/\s+/g, " ");
+    }
+    return { tag: c.tag, label: (label || "").slice(0, 60) };
+  }
+  function positionFloating(el, rect) {
+    const pad = 8;
+    const w = el.offsetWidth;
+    const h = el.offsetHeight;
+    const left = Math.min(Math.max(12, rect.left), window.innerWidth - w - 12);
+    let top = rect.top - h - pad;
+    if (top < 12) top = Math.min(rect.bottom + pad, window.innerHeight - h - 12);
+    el.style.left = left + "px";
+    el.style.top = top + "px";
+  }
+  function selectElement(target) {
+    const root = ensureShadow();
+    closeCard();
+    selected = target;
+    highlightElement(selected);
+    const d = describeTarget(target);
+    const pill = document.createElement("div");
+    pill.className = "lavish-select-pill";
+    pill.innerHTML = '<span class="lavish-pill-label"><span class="lavish-pill-tag"></span><span class="lavish-pill-text"></span></span><button class="lavish-pill-add" type="button">\u270E Add note</button>';
+    const tagEl = pill.querySelector(".lavish-pill-tag");
+    if (tagEl) tagEl.textContent = "<" + d.tag + ">";
+    const textEl = pill.querySelector(".lavish-pill-text");
+    if (textEl) {
+      if (d.label) textEl.textContent = '"' + d.label + '"';
+      else textEl.remove();
+    }
+    root.appendChild(pill);
+    positionFloating(pill, target.getBoundingClientRect());
+    const addButton = (
+      /** @type {HTMLButtonElement | null} */
+      pill.querySelector(".lavish-pill-add")
+    );
+    if (addButton) addButton.onclick = () => showAnnotationCard(selected);
+  }
   function showAnnotationCard(target, options = {}) {
     const root = ensureShadow();
     closeCard();
@@ -2008,10 +2118,13 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     const rect = options.range ? options.range.getBoundingClientRect() : target.getBoundingClientRect();
     const card = document.createElement("div");
     card.className = "lavish-annotation-card";
-    const heading = c.tag === "text" ? "Annotate text" : "Annotate &lt;" + c.tag + "&gt;";
+    const label = c.tag === "text" ? "" : describeTarget(target).label;
+    const headingText = c.tag === "text" ? "Annotate text" : "Annotate <" + c.tag + ">" + (label ? ' \xB7 "' + label + '"' : "");
     const placeholder = c.tag === "text" ? "Tell the agent what to change about this text..." : "Tell the agent what to change about this element...";
-    card.innerHTML = '<div class="lavish-heading">' + heading + '</div><textarea placeholder="' + placeholder + '"></textarea><div class="lavish-hint">Enter to queue &middot; ' + (/Mac|iP(hone|ad|od)/.test(navigator.platform) ? "\u2318" : "Ctrl") + '+Enter to send now</div><div class="lavish-row"><button class="lavish-cancel" type="button">Cancel</button><button class="lavish-send" type="button">Queue</button></div>';
+    card.innerHTML = '<div class="lavish-heading"></div><textarea placeholder="' + placeholder + '"></textarea><div class="lavish-hint">Enter to queue &middot; ' + (/Mac|iP(hone|ad|od)/.test(navigator.platform) ? "\u2318" : "Ctrl") + '+Enter to send now</div><div class="lavish-row"><button class="lavish-cancel" type="button">Cancel</button><button class="lavish-send" type="button">Queue</button></div>';
     root.appendChild(card);
+    const headingEl = card.querySelector(".lavish-heading");
+    if (headingEl) headingEl.textContent = headingText;
     const left = Math.min(Math.max(12, rect.left), window.innerWidth - card.offsetWidth - 12);
     const top = Math.min(Math.max(12, rect.bottom + 8), window.innerHeight - card.offsetHeight - 12);
     card.style.left = left + "px";
@@ -2120,7 +2233,27 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
         ignoreNextClick = false;
         return;
       }
-      showAnnotationCard(event.target);
+      const t = event.target;
+      if (t === document.body || t === document.documentElement) {
+        closeCard();
+        return;
+      }
+      selectElement(t);
+    },
+    true
+  );
+  document.addEventListener(
+    "keydown",
+    (event) => {
+      if (!annotationMode || !shadow) return;
+      if (event.key === "Escape") {
+        if (shadow.querySelector(".lavish-select-pill,.lavish-annotation-card")) closeCard();
+        return;
+      }
+      if (event.key === "Enter" && !event.isComposing && selected && shadow.querySelector(".lavish-select-pill")) {
+        event.preventDefault();
+        showAnnotationCard(selected);
+      }
     },
     true
   );
@@ -3001,7 +3134,7 @@ function initDefaultTelemetry(_init) {
 // src/cli.js
 var COMMANDS = /* @__PURE__ */ new Set(["open", "new", "spec", "poll", "end", "stop", "server", "playbook", "design", "setup"]);
 var DESCRIPTION = "Loupe turns a proposed change into a structured visual review surface for the spec phase, so developers grasp a change by looking and clicking instead of reading walls of text. Every Loupe artifact has the same guaranteed shape: \xA7A Current World (a map of the relevant use cases with the blast radius highlighted), \xA7B Grill (interactive cards the developer answers by clicking, each with an open field), and \xA7C Goal Vision (a before -> after of the agreed change). Run `loupe new <html-file>` to scaffold that structure, fill the marked slots, then `loupe <html-file>` to open the review and `loupe poll <html-file>` to receive the developer's grill answers and annotations.";
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 async function run(argv) {
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshalliqiu/loupe",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "packageManager": "pnpm@11.1.1",
   "description": "Inspect a change before you build it: Loupe turns a proposed change into a structured visual spec-review surface. Forked from lavish-axi.",
   "type": "module",

package/skills/loupe/SKILL.md

@@ -14,7 +14,8 @@ metadata:
 Loupe turns a proposed change into a structured visual review surface for the spec phase, so developers grasp a change by looking and clicking instead of reading walls of text. Every Loupe artifact has the same guaranteed shape: §A Current World (a map of the relevant use cases with the blast radius highlighted), §B Grill (interactive cards the developer answers by clicking, each with an open field), and §C Goal Vision (a before -> after of the agreed change). Run `loupe new <html-file>` to scaffold that structure, fill the marked slots, then `loupe <html-file>` to open the review and `loupe poll <html-file>` to receive the developer's grill answers and annotations.
 
 Loupe runs through the `loupe` CLI (a fork of lavish-axi). The commands below assume `loupe`
-is on your PATH; if it is not, run it from the repo as `node bin/lavish-axi.js ...`.
+is on your PATH; if it is not, run it on demand with `npx -y @marshalliqiu/loupe ...` (no install
+needed), or from a source checkout as `node bin/lavish-axi.js ...`.
 
 ## Request