@khanglvm/relay 0.16.0 → 0.16.1

package/README.md

@@ -78,7 +78,7 @@ unchanged; pick whichever surface fits.
 | "Here's the diff — paste it in your editor" | Side-by-side **diff** blocks, syntax-highlighted **code**, **video** walkthroughs, and **file paths you click to open** in the default app |
 | "Which commits should I pick? Resolve this conflict manually." | `rly git pick` / `rly git cherry-pick` boards and color-coded `git-conflict` resolvers with ours/theirs/custom hunk choices |
 | "Type *done* when finished reviewing" | A Submit button; answers, notes, and inline comments returned as JSON |
-| Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence; hold+drag an image area to attach a local crop — the agent replies and the thread grows on the board |
+| Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence; drag an image region to attach a local crop — the agent replies and the thread grows on the board |
 
 Everything autosaves in real time, detached board links keep serving after
 agent timeouts, multiple boards run at once, and the package has **zero npm
@@ -111,6 +111,15 @@ npm test     # smoke tests with no external services (spawns real servers, fake-
 
 ## Changelog
 
+### 0.16.1 — reliable area-comment zones
+
+- Primary drag now draws a comment area directly on image and comparison views;
+  **Area** remains as a visible one-shot lock. Image pan uses Space-drag or the
+  middle button, while the comparison divider moves only from its handle.
+- The selected rectangle remains visible while its comment is composed. Saved
+  zones carry a comment icon plus count, reopen for add/edit/delete, and disappear
+  automatically when their final comment is removed.
+
 ### 0.16.0 — native viewer chrome, area comments, and durable agent waits
 
 - Viewer toolbars now use browser-native sticky positioning instead of a

package/docs/AGENT.md

@@ -536,7 +536,7 @@ the question-types section above.
 | `diff` | proposed code changes / before-after — a unified diff rendered as a colored git-style comparison (no git needed) |
 | `video` | demos, screen recordings, walkthroughs — YouTube/Vimeo embeds, a media URL, or a local video file (streamed) |
 | `pdf` | quotes, reports, exports, forms — local `.pdf` files or PDF URLs rendered inline; local files stream from the board server |
-| `image` | screenshots, mockup exports, photos — local files embed and work offline; hold then drag to comment on an exact area |
+| `image` | screenshots, mockup exports, photos — local files embed and work offline; drag to comment on exact pixels |
 | `palette` | color palettes / themes — swatch cards with hover-hex + click-to-copy; pair with a `color` question to let the user pick |
 | `kpi` | big-number metric cards (`items:[{label,value,delta?,dir?,sub?}]`) with up/down/flat-tinted deltas — at-a-glance numbers without a chart |
 | `typography` | type specimens (`specimens:[{label?,size?,weight?,font?,text?}]`) — react to type choices like a palette |
@@ -550,12 +550,18 @@ click-to-drop coordinate pin-comments. `table` blocks take `"rowsFile"` (load
 rows from .csv/.tsv/.json), `"filterable"`, and `"exportable"` (CSV download).
 
 Every interactive `image` and `compare` block also supports area feedback:
-hold briefly, then drag a rectangle. Relay saves a pixel crop beside the board
-record and returns its local path with the annotation, so the agent can open the
-exact pixels instead of inferring from a whole-image comment. In a comparison,
-the side visible where the hold began is recorded as `before` or `after` and the
-crop comes from that source image. Remote images that prevent browser canvas
-access still return coordinates and a `cropUnavailable` marker.
+primary drag draws a rectangle directly; the viewer's **Area** control remains a
+discoverable one-shot lock for the same gesture. On images, Space-drag or the
+middle mouse button pans. In comparisons, only dragging the divider handle moves
+the split. The provisional rectangle remains visible while the comment is
+composed; a saved zone shows a comment icon plus count and reopens for
+add/edit/delete. Removing its final comment removes the zone. Relay saves a pixel
+crop beside the board record and returns its local path with the annotation, so
+the agent can open the exact pixels instead of inferring from a whole-image
+comment. In a comparison, the visible side where drawing began is recorded as
+`before` or `after` and the crop comes from that source image. Remote images that
+prevent browser canvas access still return coordinates and a `cropUnavailable`
+marker.
 
 ### Height rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",

package/skills/relay/SKILL.md

@@ -85,7 +85,7 @@ priority call in a `rank` question — not in paragraphs. Unsure which exists? R
 | `code` | source / config / command output — highlighted, line numbers, hover-a-line to comment |
 | `diff` | code changes — colored unified/split, multi-file (`rly diff` builds the whole board) |
 | `git-conflict` | conflict-marker files — side-by-side ours/theirs/base with hunk choices; returns resolved content in `result.blockEdits[blockId]` |
-| `image` | screenshots / mockups / renders — zoom+pan; hold+drag → area crop comment; `pins:true` → point comments |
+| `image` | screenshots / mockups / renders — drag → area crop; Space-drag/middle-button → pan; `pins:true` → point comments |
 | `compare` | a before/after pair — draggable divider; area comments retain the selected side |
 | `video` | a demo / screen recording / walkthrough |
 | `pdf` | a quote / report / exported document that should render inline |
@@ -441,12 +441,16 @@ drop a comment anchored to that exact spot (Figma-style), returned as an
 
 ### Comment on an exact image area (local crop)
 
-Every interactive `image` and `compare` block supports hold-then-drag area
-feedback without another spec flag. Relay returns an `image-region` target with
-normalized `x`, `y`, `w`, and `h`; browser boards also save the selected pixels
-beside the board and return `target.crop.path`, which the agent should open with
-its image viewer. Comparison targets include `side:"before"|"after"`, and the
-crop comes from that source image rather than the composited slider view.
+Every interactive `image` and `compare` block accepts direct primary drag for the
+desired rectangle; **Area** remains as a discoverable one-shot lock. Image pan is
+Space-drag or middle-button drag, and a comparison divider moves only from its
+handle. The provisional zone remains while the user writes, and a saved zone
+exposes a comment icon/count plus add/edit/delete threads; deleting its last
+comment removes the zone. Relay returns an `image-region` target with normalized
+`x`, `y`, `w`, and `h`; browser boards also save the selected pixels beside the
+board and return `target.crop.path`, which the agent should open with its image
+viewer. Comparison targets include `side:"before"|"after"`, and the crop comes
+from that source image rather than the composited slider view.
 
 ### Show a git diff in one step — `rly diff`
 

package/src/cli.js

@@ -1125,7 +1125,7 @@ the user should view — put it in relay instead of printing it.**
 - **There's a purpose-built component for most content — use the MOST SPECIFIC one,
   never plain prose when a block fits.** Blocks: \`table\` (sortable/filterable/CSV,
   load from .csv/.json), \`chart\`, \`kpi\` (stat cards), \`mermaid\`/\`graphviz\`/\`plantuml\`,
-  \`code\`, \`diff\`, \`git-conflict\`, \`image\` (hold+drag area crops; +\`pins\` for points), \`compare\` (before/after with side-aware area crops), \`video\`, \`pdf\`, \`palette\`,
+  \`code\`, \`diff\`, \`git-conflict\`, \`image\` (drag for crop comments; Space-drag/middle-button to pan; +\`pins\` for points), \`compare\` (before/after with side-aware area crops; divider-handle drag), \`video\`, \`pdf\`, \`palette\`,
   \`typography\`, \`html\`. Question types: \`single\`/\`multi\`/\`yesno\`/\`scale\`/\`color\`/
   \`text\`/\`textarea\` plus \`rank\` (prioritize), \`allocate\` (split a budget), \`checklist\`
   (per-item sign-off). For a business user, reach for \`kpi\`+\`chart\`+\`table\` and

package/src/ui/annotate.js

@@ -115,6 +115,7 @@
   let pinEntry = null;
   let popOpen = false;
   let popSave = null;
+  let popCloseHook = null;
   let popAnchorEl = null;
   let popPositionFrame = 0;
   const commentDrafts = new Map();
@@ -523,15 +524,20 @@
     popPositionFrame = requestAnimationFrame(positionPopover);
   }
 
-  function closePopover() {
+  function closePopover(reason = 'dismissed') {
     if (!popOpen) return;
+    const closeHook = popCloseHook;
     popOpen = false;
     popSave = null;
+    popCloseHook = null;
     popAnchorEl = null;
     if (popPositionFrame) cancelAnimationFrame(popPositionFrame);
     popPositionFrame = 0;
     dom.pop.style.display = 'none';
     dom.pop.replaceChildren();
+    if (closeHook) {
+      try { closeHook(reason); } catch (_) { /* lifecycle hooks are best-effort */ }
+    }
   }
 
   // ---------- delete a comment (with confirm) ----------
@@ -589,11 +595,12 @@
     // add-comment dialog.
     if (!permissions.add && !hasExisting) return;
     closePopover();
+    popCloseHook = typeof info.onClose === 'function' ? info.onClose : null;
     hidePin();
     const pop = dom.pop;
     // Header: target label + an explicit CLOSE button, so × always means "close".
     const popClose = el('button', { class: 'ann-pop-close', type: 'button', title: 'Close', 'aria-label': 'Close' }, '×');
-    popClose.addEventListener('click', closePopover);
+    popClose.addEventListener('click', () => closePopover('dismissed'));
     pop.replaceChildren(el('div', { class: 'ann-pop-head' }, el('div', { class: 'ann-pop-label' }, humanize(info.target)), popClose));
 
     // Existing comments on this exact target, rendered as threads: author
@@ -679,12 +686,13 @@
       const text = ta.value.trim();
       if (text) addAnnotation(info, text);
       commentDrafts.delete(draftKey);
-      closePopover();
+      if (text) closePopover('saved');
+      else closePopover('empty');
     };
     save.addEventListener('click', () => popSave && popSave());
     cancel.addEventListener('click', () => {
       commentDrafts.delete(draftKey);
-      closePopover();
+      closePopover('cancelled');
     });
     if (permissions.add) pop.append(ta, el('div', { class: 'ann-pop-actions' }, save, cancel));
 

package/src/ui/blocks.css

@@ -651,6 +651,8 @@
   width: 100%;
   max-width: none;
   height: auto;
+  -webkit-user-drag: none;
+  user-select: none;
   border-radius: 6px;
   object-fit: contain;
   object-position: left top;
@@ -757,6 +759,9 @@ body.blk-full-open { overflow: hidden; }
    dragging. During an active drag the inner svg/img/canvas ignore the pointer
    so hover pins/cursors don't flicker and the whole surface shows "grabbing". */
 .blk-pannable { cursor: grab; }
+.blk-has-regions.blk-pannable { cursor: crosshair; }
+body.blk-space-pan .blk-has-regions.blk-pannable,
+body.blk-space-pan .blk-has-regions.blk-pannable * { cursor: grab !important; }
 .blk-panning { cursor: grabbing; user-select: none; }
 .blk-panning svg,
 .blk-panning img,
@@ -789,6 +794,19 @@ body.blk-full-open { overflow: hidden; }
   background: var(--accent); border-color: var(--accent); color: var(--accent-fg);
 }
 .blk-tools .tool-comment.has-comment:hover { background: var(--accent-hover); border-color: var(--accent-hover); color: var(--accent-fg); }
+.blk-tools .tool-region {
+  display: inline-flex; align-items: center; gap: 5px;
+}
+.blk-tools .tool-region svg { display: block; }
+.blk-tools .tool-region.is-active {
+  background: var(--accent); border-color: var(--accent); color: var(--accent-fg);
+}
+.blk-tools .tool-region.is-active:hover {
+  background: var(--accent-hover); border-color: var(--accent-hover); color: var(--accent-fg);
+}
+@media (max-width: 520px) {
+  .blk-tools .tool-region-label { display: none; }
+}
 
 /* code blocks reuse the viewer toolbar (comment + full-screen); the pre keeps
    its own card, the wrapper only hosts the toolbar strip */
@@ -847,7 +865,7 @@ body.blk-full-open { overflow: hidden; }
 .cmp-frame {
   position: relative; overflow: hidden; user-select: none; touch-action: none;
   border: 1px solid var(--border); border-radius: 12px; line-height: 0;
-  cursor: ew-resize;
+  cursor: crosshair;
 }
 .cmp-img { display: block; width: 100%; height: auto; }
 .cmp-before { position: absolute; inset: 0; width: 50%; overflow: hidden; }
@@ -855,6 +873,7 @@ body.blk-full-open { overflow: hidden; }
 .cmp-handle {
   position: absolute; top: 0; bottom: 0; left: 50%; width: 2px;
   background: #fff; box-shadow: 0 0 0 1px rgba(0,0,0,0.25); transform: translateX(-1px);
+  cursor: ew-resize;
 }
 .cmp-handle-grip {
   position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);
@@ -941,17 +960,29 @@ body.blk-full-open { overflow: hidden; }
   padding: 0;
   min-width: 10px;
   min-height: 10px;
+  appearance: none;
 }
-.blk-imgregion::after {
-  content: attr(data-count);
+.blk-imgregion-badge {
   position: absolute; top: -11px; right: -11px;
-  min-width: 20px; height: 20px; padding: 0 5px;
-  display: grid; place-items: center;
+  min-width: 24px; height: 22px; padding: 0 6px;
+  display: inline-flex; align-items: center; justify-content: center; gap: 3px;
   border: 2px solid #fff; border-radius: 999px;
   background: var(--accent); color: #fff;
   font: 600 0.68rem/1 var(--sans);
   box-shadow: 0 1px 4px rgba(0,0,0,0.3);
+  pointer-events: none;
 }
+.blk-imgregion-badge svg { width: 10px; height: 10px; }
+.blk-imgregion-count { min-width: 0.7em; text-align: center; }
+.blk-imgregion-provisional {
+  z-index: 8;
+  border-style: dashed;
+  background: color-mix(in srgb, var(--card) 34%, var(--accent) 20%);
+}
+.blk-imgregion-provisional .blk-imgregion-badge { opacity: 0.9; }
+.blk-region-mode,
+.blk-region-mode * { cursor: crosshair !important; }
+.blk-region-mode { touch-action: none; }
 .blk-region-arming { cursor: crosshair !important; }
 .blk-region-selecting { cursor: crosshair !important; touch-action: none; }
 .blk-region-status {

package/src/ui/blocks.js

@@ -1888,6 +1888,24 @@
   }
 
   // ---------- image ----------
+  let activeRegionMode = null;
+  let viewerSpacePan = false;
+  const setViewerSpacePan = (enabled) => {
+    viewerSpacePan = Boolean(enabled);
+    document.body.classList.toggle('blk-space-pan', viewerSpacePan);
+  };
+  document.addEventListener('keydown', (e) => {
+    const tag = e.target && e.target.tagName ? e.target.tagName.toLowerCase() : '';
+    if (e.code === 'Space' && !e.repeat && !['input', 'textarea', 'select'].includes(tag)) {
+      setViewerSpacePan(true);
+      e.preventDefault();
+    }
+  });
+  document.addEventListener('keyup', (e) => {
+    if (e.code === 'Space') setViewerSpacePan(false);
+  });
+  window.addEventListener('blur', () => setViewerSpacePan(false));
+
   // src is a remote URL, or absent for embedded local files (served by the
   // board server at /img/b/<id>). Same sizing rule as diagrams: never upscale
   // past natural width; zoom/full-screen viewer attached once loaded.
@@ -1901,8 +1919,10 @@
       src,
       alt: block.alt || 'image',
       loading: 'lazy',
-      title: ctx.canComment === false ? '' : 'Hold briefly, then drag to comment on an area',
+      draggable: 'false',
+      title: ctx.canComment === false ? '' : 'Drag to draw a comment area · Space-drag to pan',
     });
+    img.addEventListener('dragstart', (e) => e.preventDefault());
     const stage = el('div', { class: 'blk-imgstage' }, img);
     // Inline default: the image fills its full width (container width, never
     // upscaled past natural) so it's readable without manual zoom; the CONTAINER
@@ -1914,27 +1934,28 @@
       container.replaceChildren(el('div', { class: 'blk-error' }, 'Image failed to load'));
     });
     container.append(stage);
+    const region = ctx.annotate && ctx.canComment !== false
+      ? enableImageRegions({
+          host: stage,
+          surface: img,
+          panHost: container,
+          sourceForSide: () => img,
+          sideAtPoint: () => null,
+          ctx,
+          blockId,
+          label: block.alt || 'Image',
+        })
+      : null;
     const attachImgViewer = () =>
       attachViewer(container, {
         zoomEl: stage,
         natural: () => (img.naturalWidth > 0 ? { w: img.naturalWidth, h: img.naturalHeight } : null),
         label: 'image',
         comment: wholeBlockComment(ctx, blockId, 'image'),
+        region,
       });
     if (img.complete && img.naturalWidth > 0) attachImgViewer();
     else img.addEventListener('load', attachImgViewer, { once: true });
-    if (ctx.annotate && ctx.canComment !== false) {
-      enableImageRegions({
-        host: stage,
-        surface: img,
-        panHost: container,
-        sourceForSide: () => img,
-        sideAtPoint: () => null,
-        ctx,
-        blockId,
-        label: block.alt || 'Image',
-      });
-    }
     if (ctx.annotate && block.pins === true) {
       enableImagePins(stage, img, ctx, blockId, block.alt || 'Image');
     } else if (ctx.annotate) {
@@ -2009,11 +2030,14 @@
     const selection = el('div', { class: 'blk-region-selection' });
     layer.append(selection);
     host.append(layer);
+    panHost._rlyHasRegions = true;
+    panHost.classList.add('blk-has-regions');
     let pending = null;
     let active = false;
-    let holdTimer = 0;
     let status = null;
-    const HOLD_MS = 280;
+    let modeActive = false;
+    const modeHooks = new Set();
+    let controller = null;
     const MIN_REGION = 0.012;
 
     const localPoint = (e) => {
@@ -2030,8 +2054,6 @@
       host.append(status);
     };
     const reset = () => {
-      clearTimeout(holdTimer);
-      holdTimer = 0;
       active = false;
       pending = null;
       panHost._rlyRegionSelecting = false;
@@ -2039,6 +2061,30 @@
       selection.style.display = 'none';
       clearStatus();
     };
+    const setModeActive = (next) => {
+      const enabled = Boolean(next);
+      if (enabled && activeRegionMode && activeRegionMode !== controller) {
+        activeRegionMode.setModeActive(false);
+      }
+      if (!enabled && pending) reset();
+      if (modeActive === enabled) return;
+      modeActive = enabled;
+      panHost._rlyRegionMode = enabled;
+      host.classList.toggle('blk-region-mode', enabled);
+      activeRegionMode = enabled ? controller : (activeRegionMode === controller ? null : activeRegionMode);
+      for (const fn of modeHooks) { try { fn(enabled); } catch (_) {} }
+    };
+    controller = {
+      setModeActive,
+      isModeActive: () => modeActive,
+      onModeChange: (fn) => {
+        if (typeof fn === 'function') modeHooks.add(fn);
+        return () => modeHooks.delete(fn);
+      },
+    };
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape' && modeActive) setModeActive(false);
+    });
     const draw = (a, b) => {
       const x = Math.min(a.x, b.x), y = Math.min(a.y, b.y);
       const w = Math.abs(a.x - b.x), h = Math.abs(a.y - b.y);
@@ -2048,6 +2094,34 @@
       selection.style.height = (h * 100) + '%';
       return { x, y, w, h };
     };
+    const createRegionZone = (target, count, provisional = false) => {
+      const badge = el('span', { class: 'blk-imgregion-badge', 'aria-hidden': 'true' });
+      badge.innerHTML = ICON_COMMENT;
+      badge.append(el('span', { class: 'blk-imgregion-count' }, String(count)));
+      const sideLabel = target.side ? target.side + ' ' : '';
+      const region = el('button', {
+        class: 'blk-imgregion' + (provisional ? ' blk-imgregion-provisional' : ''),
+        type: 'button',
+        title: provisional
+          ? `Add a comment to this ${sideLabel}area`
+          : `${target.side ? target.side + ' · ' : ''}${count} ${count === 1 ? 'comment' : 'comments'}`,
+        'aria-label': provisional
+          ? `New ${sideLabel}image area comment`
+          : `${sideLabel}image area with ${count} ${count === 1 ? 'comment' : 'comments'}`,
+      }, badge);
+      region.style.left = (target.x * 100) + '%';
+      region.style.top = (target.y * 100) + '%';
+      region.style.width = (target.w * 100) + '%';
+      region.style.height = (target.h * 100) + '%';
+      region.addEventListener('pointerdown', (e) => e.stopPropagation());
+      if (!provisional) {
+        region.addEventListener('click', (e) => {
+          e.stopPropagation();
+          ctx.annotate.openExternal({ blockId, questionId: ctx.questionId, target }, region);
+        });
+      }
+      return region;
+    };
     const beginSelection = (pointerId) => {
       if (!pending || active) return;
       active = true;
@@ -2091,6 +2165,8 @@
         side: side || undefined,
         label,
       };
+      const provisional = createRegionZone(target, 0, true);
+      layer.append(provisional);
       showStatus('Saving selected area…');
       try {
         target.crop = await cropRegion(sourceForSide(side), region);
@@ -2098,12 +2174,21 @@
         target.cropUnavailable = true;
       }
       clearStatus();
-      ctx.annotate.openExternal({ blockId, questionId: ctx.questionId, target }, host);
+      ctx.annotate.openExternal({
+        blockId,
+        questionId: ctx.questionId,
+        target,
+        onClose: () => provisional.remove(),
+      }, provisional);
     };
 
     surface.addEventListener('pointerdown', (e) => {
-      if (e.button !== 0 || ctx.canComment === false) return;
+      if (e.button !== 0 || viewerSpacePan || ctx.canComment === false) return;
       if (e.target.closest && e.target.closest('.cmp-handle, .blk-imgregion, .blk-tools')) return;
+      if (modeActive) {
+        e.preventDefault();
+        e.stopPropagation();
+      }
       const p = localPoint(e);
       pending = {
         start: p,
@@ -2111,38 +2196,41 @@
         clientX: e.clientX,
         clientY: e.clientY,
         pointerId: e.pointerId,
-        startedAt: performance.now(),
+        explicitMode: modeActive,
         side: sideAtPoint(p.x),
       };
       host.classList.add('blk-region-arming');
-      holdTimer = setTimeout(() => beginSelection(e.pointerId), HOLD_MS);
+      if (modeActive) beginSelection(e.pointerId);
     });
     surface.addEventListener('pointermove', (e) => {
       if (!pending) return;
       const moved = Math.hypot(e.clientX - pending.clientX, e.clientY - pending.clientY);
-      // Timers can be throttled while an automation host or background tab owns
-      // the event loop. The first post-hold move is also authoritative, so a
-      // genuine hold still enters area mode even if setTimeout fired late.
-      if (!active && performance.now() - pending.startedAt >= HOLD_MS) beginSelection(pending.pointerId);
+      if (!active && moved > 5) beginSelection(pending.pointerId);
       if (!active) {
-        if (moved > 5) reset();
         return;
       }
       e.preventDefault();
+      e.stopPropagation();
       pending.last = localPoint(e);
       draw(pending.start, pending.last);
     });
     const end = (e) => {
       if (!pending) return;
-      clearTimeout(holdTimer);
       if (!active) { reset(); return; }
       e.preventDefault();
       const region = draw(pending.start, pending.last || localPoint(e));
       const side = pending.side;
+      const explicitMode = pending.explicitMode;
       surface._rlySuppressPointClick = true;
       reset();
       clearStatus();
-      if (region.w >= MIN_REGION && region.h >= MIN_REGION) finishRegion(region, side);
+      if (region.w >= MIN_REGION && region.h >= MIN_REGION) {
+        if (explicitMode) setModeActive(false);
+        finishRegion(region, side);
+      } else if (explicitMode) {
+        showStatus('Drag a larger area');
+        setTimeout(clearStatus, 1200);
+      }
     };
     surface.addEventListener('pointerup', end);
     // Some Chromium/CDP paths emit pointercancel immediately after granting
@@ -2151,7 +2239,7 @@
     surface.addEventListener('pointercancel', (e) => active ? end(e) : reset());
 
     const syncRegions = () => {
-      for (const node of Array.from(layer.querySelectorAll('.blk-imgregion'))) node.remove();
+      for (const node of Array.from(layer.querySelectorAll('.blk-imgregion:not(.blk-imgregion-provisional)'))) node.remove();
       const groups = new Map();
       for (const a of ctx.annotate.list()) {
         if (a.blockId !== blockId || !a.target || a.target.kind !== 'image-region') continue;
@@ -2162,27 +2250,12 @@
         groups.set(key, group);
       }
       for (const { target, count } of groups.values()) {
-        const region = el('button', {
-          class: 'blk-imgregion',
-          type: 'button',
-          'data-count': String(count),
-          title: `${target.side ? target.side + ' · ' : ''}${count} ${count === 1 ? 'comment' : 'comments'}`,
-          'aria-label': `${target.side ? target.side + ' image area' : 'image area'} with ${count} ${count === 1 ? 'comment' : 'comments'}`,
-        });
-        region.style.left = (target.x * 100) + '%';
-        region.style.top = (target.y * 100) + '%';
-        region.style.width = (target.w * 100) + '%';
-        region.style.height = (target.h * 100) + '%';
-        region.addEventListener('pointerdown', (e) => e.stopPropagation());
-        region.addEventListener('click', (e) => {
-          e.stopPropagation();
-          ctx.annotate.openExternal({ blockId, questionId: ctx.questionId, target }, region);
-        });
-        layer.append(region);
+        layer.append(createRegionZone(target, count));
       }
     };
     if (ctx.annotate.onBadgeRefresh) ctx.annotate.onBadgeRefresh(syncRegions);
     syncRegions();
+    return controller;
   }
 
   // ---------- palette ----------
@@ -2333,19 +2406,20 @@
       if (r.width) { pos = Math.max(0, Math.min(100, ((clientX - r.left) / r.width) * 100)); apply(); }
     };
     frame.addEventListener('pointerdown', (e) => {
-      if (e.target.closest && e.target.closest('.blk-imgregion')) return;
+      const handleTarget = e.target.closest('.cmp-handle');
+      if (!handleTarget || frame._rlyRegionMode) return;
       dragging = true;
       dragMoved = false;
       dragStartX = e.clientX;
       try { frame.setPointerCapture(e.pointerId); } catch (_) {}
     });
     frame.addEventListener('pointermove', (e) => {
-      if (!dragging || frame._rlyRegionSelecting) return;
+      if (!dragging || frame._rlyRegionMode || frame._rlyRegionSelecting) return;
       if (Math.abs(e.clientX - dragStartX) > 3) dragMoved = true;
       if (dragMoved) { setFromX(e.clientX); e.preventDefault(); }
     });
     frame.addEventListener('pointerup', (e) => {
-      if (dragging && !dragMoved && !frame._rlyRegionSelecting) setFromX(e.clientX);
+      if (dragging && !dragMoved && !frame._rlyRegionMode && !frame._rlyRegionSelecting) setFromX(e.clientX);
       dragging = false;
     });
     frame.addEventListener('pointercancel', () => { dragging = false; dragMoved = false; });
@@ -2353,9 +2427,10 @@
       if (e.key === 'ArrowLeft') { pos = Math.max(0, pos - 2); apply(); e.preventDefault(); }
       else if (e.key === 'ArrowRight') { pos = Math.min(100, pos + 2); apply(); e.preventDefault(); }
     });
+    let region = null;
     if (ctx.annotate && ctx.canComment !== false) {
-      frame.title = 'Hold briefly, then drag to comment on the visible Before or After image';
-      enableImageRegions({
+      frame.title = 'Drag to draw a comment area · drag the divider handle to compare';
+      region = enableImageRegions({
         host: frame,
         surface: frame,
         panHost: frame,
@@ -2366,7 +2441,12 @@
         label: 'Comparison',
       });
     }
-    attachViewer(wrap, { zoomEl: null, label: 'comparison', comment: wholeBlockComment(ctx, blockId, 'comparison') });
+    attachViewer(wrap, {
+      zoomEl: null,
+      label: 'comparison',
+      comment: wholeBlockComment(ctx, blockId, 'comparison'),
+      region,
+    });
     return wrap;
   }
 
@@ -2399,6 +2479,10 @@
   const ICON_COMMENT =
     '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
     '<path d="M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8z"/></svg>';
+  const ICON_REGION =
+    '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+    '<rect x="3" y="4" width="14" height="12" rx="2" stroke-dasharray="3 2"/>' +
+    '<path d="M14 14.5h6.5v4H18l-2.5 2v-2H14z" fill="currentColor" stroke="none"/></svg>';
 
   function exitFull() {
     if (!fullOpen) return;
@@ -2520,7 +2604,8 @@
     const refresh = () => scrollEl.classList.toggle('blk-pannable', pannable());
 
     scrollEl.addEventListener('pointerdown', (e) => {
-      if (e.button !== 0 || !pannable()) return;
+      const panGesture = e.button === 1 || (e.button === 0 && (!scrollEl._rlyHasRegions || viewerSpacePan));
+      if (!panGesture || scrollEl._rlyRegionMode || !pannable()) return;
       // leave the toolbar, the diagram editor, and real controls interactive
       if (e.target.closest && e.target.closest('.blk-tools, .blk-editor, button, a, input, textarea, select')) return;
       pending = true; active = false;
@@ -2530,7 +2615,7 @@
     });
     scrollEl.addEventListener('pointermove', (e) => {
       if (!pending) return;
-      if (scrollEl._rlyRegionSelecting) { pending = false; active = false; return; }
+      if (scrollEl._rlyRegionMode || scrollEl._rlyRegionSelecting) { pending = false; active = false; return; }
       const dx = e.clientX - sx, dy = e.clientY - sy;
       if (!active) {
         if (Math.abs(dx) < THRESH && Math.abs(dy) < THRESH) return;
@@ -2581,6 +2666,10 @@
   // comment (optional) = { open(anchor), active(), subscribe(fn) } wiring the
   // "comment on the whole block" button + its already-commented style.
   function attachViewer(container, opts) {
+    if (container._rlyRegionHook) {
+      try { container._rlyRegionHook(); } catch (_) {}
+      container._rlyRegionHook = null;
+    }
     if (container._rlyTools) container._rlyTools.remove();
     container.classList.add('blk-viewer');
     const zoomable = Boolean(opts && opts.zoomEl);
@@ -2695,6 +2784,34 @@
       }
     }
 
+    if (opts && opts.region) {
+      const regionCtl = opts.region;
+      const regionLabel = el('span', { class: 'tool-region-label' }, 'Area');
+      const regionBtn = el('button', {
+        class: 'tool-region',
+        type: 'button',
+        title: 'Draw an area comment',
+        'aria-label': 'Draw an area comment',
+        'aria-pressed': 'false',
+      });
+      regionBtn.innerHTML = ICON_REGION;
+      regionBtn.append(regionLabel);
+      const syncRegionMode = (enabled) => {
+        regionBtn.classList.toggle('is-active', enabled);
+        regionBtn.setAttribute('aria-pressed', enabled ? 'true' : 'false');
+        regionBtn.title = enabled ? 'Cancel area comment' : 'Draw an area comment';
+        regionBtn.setAttribute('aria-label', regionBtn.title);
+        regionLabel.textContent = enabled ? 'Drawing' : 'Area';
+      };
+      regionBtn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        regionCtl.setModeActive(!regionCtl.isModeActive());
+      });
+      container._rlyRegionHook = regionCtl.onModeChange(syncRegionMode);
+      syncRegionMode(regionCtl.isModeActive());
+      tools.append(regionBtn);
+    }
+
     if (zoomable) {
       // cmd/ctrl+wheel zoom, bound ONCE (re-binding per render would stack);
       // delegates to the current controller so it never uses a stale zoomEl