@comty.io/core 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comty.io/core",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Comty visual comments, inspector and local agent tools",
   "type": "module",
   "license": "UNLICENSED",
@@ -34,7 +34,7 @@
     "check:build": "node scripts/build.mjs --check",
     "test": "node --experimental-websocket --test tests/measurements.test.mjs tests/anchors.test.mjs tests/package.test.mjs tests/packed.test.mjs tests/companion.test.mjs tests/codex.test.mjs tests/claude.test.mjs tests/cursor.test.mjs tests/acp.test.mjs",
     "test:capture": "node --test tests/capture.browser.test.mjs",
-    "test:inspector": "node --test tests/inspector.browser.test.mjs",
+    "test:inspector": "node --test tests/inspector.browser.test.mjs tests/inspect-markup.browser.test.mjs tests/idle-network.browser.test.mjs",
     "test:placement": "node --test tests/placement.browser.test.mjs",
     "test:anchors": "node --test tests/anchors.test.mjs tests/anchor-reload.browser.test.mjs",
     "test:vite": "node --test tests/vite.test.mjs",

package/src/browser.js

@@ -1,3 +1,4 @@
+import { createInspectMarkup } from "./inspect-markup.js";
 import { getComtyStyle } from "./style.js";
 import { createAnchorMatcher } from "./anchors.js";
 import { createScreenshotCapture, createColorMagnifier, captureContext } from "./capture.js";
@@ -56,12 +57,14 @@ export function initComty(options = {}) {
     const deliveringAgentReplies = new Set();
     let localApprovals = [];
     const seenAgentApprovals = new Set();
-    const seenFailedAgentTasks = new Set();
+    // Only requests made in this document may interrupt it with agent notifications.
+    const requestedAgentTasks = new Set();
     let agentPanelOpen = false;
     let agentPanelSignature = "";
     let agentPanelTransition = 0;
     let agentConnectionError = "";
     let agentActionError = "";
+    let clearAgentToast = () => {};
     const agentPendingActions = new Set();
     const session = {
       mode: "off",
@@ -194,6 +197,9 @@ export function initComty(options = {}) {
     const agentBtn = isLocalSite
       ? toolButton("Agent task · localhost only", '<path d="M8 7 3 12l5 5m8-10 5 5-5 5M14 4l-4 16"/>', () => {
           if (session.agent) {
+            const failedTask = [...localTasks].reverse().find(task => task.status === 'in_review' && !task.thread_comment_id);
+            const failedPin = failedTask && placedPins.get(String(failedTask.id));
+            if (failedPin && !failedPin.hasAttribute('data-comty-anchor-hidden')) { failedPin.click(); return; }
             if (localTasks.some(task => task.status === 'in_review' || (!task.thread_comment_id && task.status === 'done')) || localApprovals.length) {
               agentPanelOpen = true;
               renderAgentPanel();
@@ -201,6 +207,10 @@ export function initComty(options = {}) {
           } else startAgentSession();
         })
       : null;
+    if (agentBtn) {
+      agentBtn.title = "Agent · Shift A · localhost only";
+      agentBtn.setAttribute("aria-keyshortcuts", "Shift+A");
+    }
     const divider = document.createElement("span");
     divider.className = "comty-tool-divider";
     toolbar.appendChild(divider);
@@ -240,6 +250,7 @@ export function initComty(options = {}) {
       root,
       isComtyElement,
       isElementTreeHidden,
+      isInteractionBlocked: () => Boolean(markup.mode),
       onExit() { rulersEnabled = false; syncInspectorTools(); },
     });
     const gridLayer = document.createElement("div");
@@ -266,6 +277,7 @@ export function initComty(options = {}) {
       syncInspectorTools();
     });
     const rulersBtn = toolButton("Rulers · R", '<path d="M3 3h18v6H9v12H3Z"/><path d="M7 3v3m4-3v3m4-3v3M3 11h3m-3 4h3m-3 4h3"/>', () => {
+      markup.setMode(null);
       closePropertyPanel();
       if (motion.enabled) setMotionEnabled(false);
       rulersEnabled = !rulersEnabled;
@@ -276,6 +288,7 @@ export function initComty(options = {}) {
       syncInspectorTools();
     });
     const gridBtn = toolButton("Layout guides · G", '<rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 10h18M10 3v18"/>', () => {
+      markup.setMode(null);
       closePropertyPanel();
       if (motion.enabled) setMotionEnabled(false);
       gridPanelOpen = !gridPanelOpen;
@@ -293,7 +306,37 @@ export function initComty(options = {}) {
     }
     const motionBtn = toolButton("Motion · M", '<circle cx="12" cy="14" r="8"/><path d="M9 2h6m-3 4V2m6 5 2-2m-8 5v4l3 2"/>', () => setMotionEnabled(!motion.enabled));
     motionBtn.setAttribute("aria-expanded", "false");
-    for (const button of [xrayBtn, rulersBtn, gridBtn, pipetteBtn, typographyBtn, motionBtn]) inspectorTools.appendChild(button);
+    const annotateBtn = toolButton("Annotate · D", '<path d="m16 3 5 5L8 21H3v-5ZM14 5l5 5"/>', () => toggleMarkup("annotate"));
+    const screenshotBtn = toolButton("Capture area · S", '<path d="M8 3H5a2 2 0 0 0-2 2v3m13-5h3a2 2 0 0 1 2 2v3M3 16v3a2 2 0 0 0 2 2h3m13-5v3a2 2 0 0 1-2 2h-3"/><rect x="7" y="8" width="10" height="8" rx="1"/><circle cx="12" cy="12" r="2"/>', () => toggleMarkup("capture"));
+    const markup = createInspectMarkup({
+      root, icon,
+      onError: description => showNotice({ title: "Screenshot unavailable", description }),
+      onChange() {
+        annotateBtn.setAttribute("aria-pressed", String(markup.mode === "annotate"));
+        annotateBtn.setAttribute("aria-expanded", String(markup.mode === "annotate"));
+        screenshotBtn.setAttribute("aria-pressed", String(markup.mode === "capture"));
+        screenshotBtn.setAttribute("aria-busy", String(markup.busy));
+        positionToolbar();
+      },
+      capture: (region, layer) => captureViewportScreenshot({ region, annotation: () => ({
+        elements: [overlayTools, root.querySelector('.comty-distance-layer'), layer].filter(node => node && !node.hidden),
+        dispose() {},
+      }) }),
+    });
+    for (const button of [annotateBtn]) {
+      button.setAttribute("aria-controls", markup.panel.id);
+      button.setAttribute("aria-expanded", "false");
+    }
+    function toggleMarkup(mode) {
+      const next = markup.mode === mode ? null : mode;
+      closePropertyPanel();
+      if (motion.enabled) setMotionEnabled(false);
+      gridPanelOpen = false; toolPanel.hidden = true; gridBtn.setAttribute("aria-expanded", "false");
+      cancelRulerDrag();
+      selectedElement = null; measuredRegion = null; inspectDrag = null; hideInspector();
+      markup.setMode(next);
+    }
+    for (const button of [xrayBtn, rulersBtn, gridBtn, pipetteBtn, typographyBtn, motionBtn, annotateBtn, screenshotBtn]) inspectorTools.appendChild(button);
 
     const motion = { enabled: false, speed: 1, paused: false, managed: new Map(), shadowRoots: [], nextRootScan: 0 };
     const motionPanel = document.createElement('section');
@@ -342,6 +385,7 @@ export function initComty(options = {}) {
       motion.enabled = enabled; motionPanel.hidden = !enabled;
       motionBtn.setAttribute('aria-pressed', String(enabled)); motionBtn.setAttribute('aria-expanded', String(enabled));
       if (enabled) {
+        markup.setMode(null);
         closePropertyPanel();
         rulersEnabled = false;
         syncInspectorTools();
@@ -600,6 +644,7 @@ export function initComty(options = {}) {
       const visible = session.inspect;
       measurements.setEnabled(visible && rulersEnabled && !motion.enabled);
       overlayTools.hidden = !visible;
+      markup.setVisible(visible);
       xrayBtn.setAttribute("aria-pressed", String(visible && xrayEnabled));
       rulersBtn.setAttribute("aria-pressed", String(visible && rulersEnabled));
       gridBtn.setAttribute("aria-pressed", String(visible && layoutGuides.some(guide => guide.visible)));
@@ -883,6 +928,7 @@ export function initComty(options = {}) {
     }
 
     function openPropertyPanel(kind, element, property, opener = null, sampledColor = null) {
+      markup.setMode(null);
       propertyPicking = null;
       colorMagnifier.setEnabled(false);
       delete document.documentElement.dataset.comtyPropertyPicking;
@@ -1140,7 +1186,7 @@ export function initComty(options = {}) {
         });
       }
       const rect = toolbar.getBoundingClientRect();
-      for (const panel of [toolPanel, propertyPanel, sidepanel, motionPanel]) {
+      for (const panel of [toolPanel, propertyPanel, sidepanel, motionPanel, markup.panel]) {
         if (panel.hidden || (panel === sidepanel && !sidepanelOpen)) continue;
         const above = rect.top - 16;
         const below = innerHeight - rect.bottom - 16;
@@ -1157,9 +1203,10 @@ export function initComty(options = {}) {
         panel.style.top = `${useAbove ? rect.top - panel.offsetHeight - 8 : rect.bottom + 8}px`;
         panel.style.bottom = "auto";
       }
+      positionNotice();
     }
     const toolbarResize = new ResizeObserver(positionToolbar);
-    [toolbar, toolPanel, propertyPanel, sidepanel, motionPanel].forEach(node => toolbarResize.observe(node));
+    [toolbar, toolPanel, propertyPanel, sidepanel, motionPanel, markup.panel].forEach(node => toolbarResize.observe(node));
     window.addEventListener("resize", positionToolbar);
 
     toolbar.addEventListener("pointerdown", event => {
@@ -1494,7 +1541,7 @@ export function initComty(options = {}) {
 
     function showAuthPrompt(forbidden = false, onReady = startEditSession) {
       if (localOnly) {
-        showAgentBridgeError("Shared comments need a Comty project key. Use the Agent tool for local tasks without signing in.");
+        showNotice({ title: "Comments are not configured", description: "Connect this site to a Comty project to leave shared comments." });
         return;
       }
       const guestAllowed = allowGuestComments;
@@ -1628,6 +1675,7 @@ export function initComty(options = {}) {
       inspectorTools.hidden = !session.inspect;
       syncInspectorTools();
       renderAgentPanel();
+      positionNotice();
     }
 
     const inspectionLayer = document.createElement("div");
@@ -1940,7 +1988,7 @@ export function initComty(options = {}) {
         });
         return;
       }
-      if (propertyPicking || motion.enabled || (session.inspect && rulersEnabled)) {
+      if (markup.mode || propertyPicking || motion.enabled || (session.inspect && rulersEnabled)) {
         if (inspectionLayer.childNodes.length) hideInspector();
         return;
       }
@@ -2084,10 +2132,12 @@ export function initComty(options = {}) {
 
     function startBrowseSession() {
       setSession("browse", { renderComments: true });
+      void loadComments({ force: true });
     }
 
     function startEditSession() {
       setSession("edit", { renderComments: true });
+      void loadComments({ force: true });
     }
 
     function startAgentSession() {
@@ -2095,6 +2145,7 @@ export function initComty(options = {}) {
       if (session.agent) return;
       closeBubbles();
       setSession("agent", { renderComments: true });
+      void loadComments({ force: true });
     }
 
     function toggleSidepanel() {
@@ -2832,6 +2883,7 @@ export function initComty(options = {}) {
     function createCommentPin(comment, x, y) {
       const pin = document.createElement("button");
       pin.className = "comty-pin";
+      pin.toggleAttribute('data-agent-task', Boolean(comment.local_agent));
       pin.type = "button";
       pin.style.left = `${x}px`;
       pin.style.top = `${y}px`;
@@ -2849,10 +2901,52 @@ export function initComty(options = {}) {
       const thread = document.createElement("div");
       thread.className = "comty-thread";
       thread.appendChild(createThreadItem(comment, { showMore: false, showLink: false }).item);
+      if (comment.local_agent) {
+        thread.appendChild(createThreadItem({ author_kind: 'agent', content: 'Modification failed. Open to retry or dismiss.' }, { showMore: false }).item);
+      }
       bubble.appendChild(thread);
       return bubble;
     }
 
+    function openAgentTask(task, x, y) {
+      closeBubbles();
+      const bubble = document.createElement('div');
+      bubble.className = 'comty-bubble comty-agent-task-thread';
+      bubble.dataset.commentId = task.id;
+      bubble.setAttribute('role', 'dialog');
+      bubble.setAttribute('aria-label', 'Failed modification');
+      const header = document.createElement('div'); header.className = 'comty-bubble-header';
+      const title = document.createElement('strong'); title.textContent = 'Modification failed';
+      const close = document.createElement('button'); close.type = 'button'; close.className = 'comty-icon-button';
+      close.setAttribute('aria-label', 'Close failed modification');
+      close.innerHTML = icon('<path d="m6 6 12 12M6 18 18 6"/>');
+      close.onclick = () => closeBubbles();
+      header.append(title, close);
+      const thread = document.createElement('div'); thread.className = 'comty-thread';
+      const list = document.createElement('div'); list.className = 'comty-thread-list';
+      const issue = task.error ? describeAgentError(task.error) : null;
+      list.append(
+        createThreadItem(task, { showMore: false }).item,
+        createThreadItem({ author_kind: 'agent', content: task.result?.summary || issue?.message || issue?.description || 'The agent could not complete this request.' }, { showMore: false }).item,
+      );
+      thread.appendChild(list);
+      const actions = document.createElement('div'); actions.className = 'comty-agent-task-actions';
+      for (const action of ['retry', 'dismiss']) {
+        const button = document.createElement('button'); button.type = 'button'; button.className = 'comty-agent-action';
+        button.textContent = action === 'retry' ? 'Retry' : 'Dismiss';
+        button.onclick = async () => {
+          for (const control of actions.children) control.disabled = true;
+          try { await runAgentAction(`tasks/${task.id}/${action}`); }
+          catch (error) { showAgentBridgeError(error.message); }
+          finally { for (const control of actions.children) control.disabled = false; }
+        };
+        actions.appendChild(button);
+      }
+      bubble.append(header, thread, actions);
+      root.appendChild(bubble);
+      positionCommentBubble(bubble, x, y);
+    }
+
     function mountCaptureAnnotation(comment, { x, y }) {
       const host = document.createElement("div");
       host.dataset.comtyCaptureExclude = "";
@@ -3036,6 +3130,7 @@ export function initComty(options = {}) {
           const id = isAgentTask ? data?.task?.id : data?.id;
           if (!id) throw new Error("Save returned no ID");
           if (isAgentTask) {
+            requestedAgentTasks.add(id);
             void loadComments({ force: true });
           } else {
             cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
@@ -3167,14 +3262,53 @@ export function initComty(options = {}) {
     function agentHeaders() { return { "Content-Type": "application/json", "X-Comty-Token": agent?.token || "" }; }
 
     function showAgentBridgeError(message = "Start your app with comty dev to use the local agent. Check the terminal if it is already running.") {
-      root.querySelectorAll(".comty-agent-task-toast").forEach((node) => node.remove());
+      const issue = describeAgentError(message);
+      showNotice({ title: 'Modification failed', description: issue.title === 'Task could not finish' ? 'The agent could not complete this request.' : issue.title + '.' });
+    }
+
+    function positionNotice() {
+      const toast = root.querySelector(".comty-agent-task-toast");
+      if (!toast) return;
+      toast.style.removeProperty("left");
+      toast.style.removeProperty("top");
+      toast.toggleAttribute("data-toolbar", isSessionActive());
+      if (!isSessionActive()) return;
+      const rect = toolbar.getBoundingClientRect();
+      const above = rect.top - toast.offsetHeight - 8;
+      toast.style.left = `${Math.max(8, Math.min(rect.right - toast.offsetWidth, innerWidth - toast.offsetWidth - 8))}px`;
+      toast.style.top = `${Math.max(8, Math.min(above >= 8 ? above : rect.bottom + 8, innerHeight - toast.offsetHeight - 8))}px`;
+    }
+
+    function showNotice(issue) {
+      clearAgentToast();
       const toast = document.createElement("div");
-      toast.className = "comty-auth-toast comty-agent-task-toast";
+      toast.className = "comty-agent-task-toast";
       toast.setAttribute("role", "alert");
-      const issue = describeAgentError(message);
-      toast.textContent = issue.title + ". " + issue.description;
+      const title = document.createElement("strong"); title.textContent = issue.title;
+      const description = document.createElement("p"); description.textContent = issue.description;
+      const close = document.createElement("button"); close.type = "button";
+      close.setAttribute("aria-label", "Dismiss notification");
+      close.innerHTML = icon('<path d="m6 6 12 12M6 18 18 6"/>');
+      toast.append(title, description, close);
+      let timer, leaving = false;
+      const dismiss = () => {
+        if (leaving) return;
+        leaving = true;
+        clearTimeout(timer);
+        toast.dataset.leaving = "";
+        timer = setTimeout(() => toast.remove(), reducedMotion.matches ? 0 : 200);
+      };
+      const schedule = () => { if (!leaving) { clearTimeout(timer); timer = setTimeout(dismiss, 6000); } };
+      const pause = () => { if (!leaving) clearTimeout(timer); };
+      clearAgentToast = () => { clearTimeout(timer); toast.remove(); };
+      close.onclick = dismiss;
+      toast.onmouseenter = pause;
+      toast.onmouseleave = schedule;
+      toast.onfocusin = pause;
+      toast.onfocusout = schedule;
       root.appendChild(toast);
-      setTimeout(() => toast.remove(), 5000);
+      positionNotice();
+      schedule();
     }
 
     function describeAgentError(error) {
@@ -3203,7 +3337,7 @@ export function initComty(options = {}) {
       } else if (/unauthorized|unauthenticated|authentication|not logged|sign.?in|log.?in|invalid.api.key|\b401\b/i.test(source)) {
         title = 'Sign in to your agent'; description = `Open ${agentName} and sign in again, then retry this task.`;
       } else if (/model.*(?:not found|does not exist|unavailable|not supported)|unsupported model|model_not_found/i.test(source)) {
-        title = 'Model unavailable'; description = 'Choose a model available to your agent account in the local Comty configuration, then restart and retry.';
+        title = 'Model unavailable'; description = 'The local agent rejected this model. Check its CLI version and signed-in account, then retry.';
       } else if (/disconnected|ECONNREFUSED|ENOTFOUND|network|failed to fetch|development server stopped/i.test(source)) {
         title = 'Connection lost'; description = 'Check that your local development server and coding agent are running, then reload this page.';
       } else if (/timed? ?out|timeout|exceeded.*minutes/i.test(source)) {
@@ -3216,11 +3350,21 @@ export function initComty(options = {}) {
         title = 'Result needs checking'; description = 'The agent could not confirm completion. Review the changes before retrying.';
       } else {
         title = 'Task could not finish';
-        description = message && !/[{}]|\[object Object\]/.test(message) ? message.slice(0, 300) : 'The agent reported an unexpected error. Review the technical details and any changes before retrying.';
+        description = message && !/[{}]|\[object Object\]/.test(message) ? message.slice(0, 160) + (message.length > 160 ? '…' : '') : 'The agent reported an unexpected error. Review the technical details and any changes before retrying.';
       }
       return { title, description, raw, message };
     }
 
+    async function runAgentAction(path, input = {}) {
+      const response = await fetch(`${agentBridgeUrl}/${path}`, { method: 'POST', headers: agentHeaders(), body: JSON.stringify(input) });
+      if (!response.ok) {
+        const body = await response.json().catch(() => null);
+        throw new Error(typeof body?.error === 'string' ? body.error : JSON.stringify(body?.error || { status: response.status, message: 'Request failed' }));
+      }
+      if (path.endsWith('/retry')) requestedAgentTasks.add(path.split('/')[1]);
+      await loadComments({ force: true });
+    }
+
     function renderAgentPanel() {
       if (!agent) return;
       const visibleTasks = [];
@@ -3239,6 +3383,7 @@ export function initComty(options = {}) {
       }
       const open = Boolean(agent) && agentPanelOpen;
       if (open) {
+        clearAgentToast();
         if (panel.hidden) {
           const rect = toolbar.getBoundingClientRect();
           panel.dataset.side = rect.left + rect.width / 2 < innerWidth / 2 ? "left" : "right";
@@ -3259,7 +3404,6 @@ export function initComty(options = {}) {
       const signature = JSON.stringify([visibleTasks, localApprovals, agentConnectionError, agentActionError, agentPanelOpen]);
       if (signature === agentPanelSignature) return;
       agentPanelSignature = signature;
-      root.querySelector('.comty-agent-error-popover')?.remove();
       const expanded = new Set([...panel.querySelectorAll('details[data-detail-key][open]')].map(node => node.dataset.detailKey));
       const focusKey = panel.contains(document.activeElement) ? document.activeElement.dataset.focusKey : null;
       const scrollTop = panel.querySelector('.comty-agent-panel-content')?.scrollTop || 0;
@@ -3305,12 +3449,7 @@ export function initComty(options = {}) {
           agentActionError = '';
           agentPendingActions.add(key); button.disabled = true; button.textContent = 'Please wait…';
           try {
-            const response = await fetch(`${agentBridgeUrl}/${path}`, { method: 'POST', headers: agentHeaders(), body: JSON.stringify(input) });
-            if (!response.ok) {
-              const body = await response.json().catch(() => null);
-              throw new Error(typeof body?.error === 'string' ? body.error : JSON.stringify(body?.error || { status: response.status, message: 'Request failed' }));
-            }
-            await loadComments({ force: true });
+            await runAgentAction(path, input);
           } catch (error) { agentActionError = error.message; }
           finally { agentPendingActions.delete(key); agentPanelSignature = ''; renderAgentPanel(); }
         };
@@ -3331,9 +3470,7 @@ export function initComty(options = {}) {
         section.appendChild(actions); content.appendChild(section);
       }
       const list = node('div', 'comty-agent-list'); content.appendChild(list);
-      const hideErrorPopover = () => root.querySelector('.comty-agent-error-popover')?.remove();
-      content.addEventListener('scroll', hideErrorPopover, { passive: true });
-      for (const [index, task] of visibleTasks.reverse().entries()) {
+      for (const task of visibleTasks.reverse()) {
         const failed = Boolean(task.error) || task.status === 'in_review';
         const state = task.status === 'done' ? 'success' : failed ? 'error' : 'working';
         const row = node('div', 'comty-agent-row'); row.dataset.taskId = task.id;
@@ -3349,24 +3486,12 @@ export function initComty(options = {}) {
         if (task.status === 'in_review') action(actions, 'Dismiss', `tasks/${task.id}/dismiss`);
         if (actions.childElementCount) row.appendChild(actions);
         row.setAttribute('aria-label', `${task.content}, ${state === 'error' ? 'failed' : state === 'success' ? 'completed' : state === 'cancel' ? 'cancelled' : task.status === 'todo' ? 'starting' : 'working'}`);
-        if (failed) {
-          const tooltipId = `comty-agent-error-${index}`;
-          const showErrorPopover = () => {
-            hideErrorPopover();
-            const issue = describeAgentError(task.error || task.result?.summary || task.progress || 'Completion was not verified');
-            const popover = node('div', 'comty-agent-error-popover'); popover.id = tooltipId; popover.setAttribute('role', 'tooltip');
-            popover.append(node('strong', '', task.content), node('p', '', issue.message || issue.description));
-            root.appendChild(popover);
-            const rowRect = row.getBoundingClientRect();
-            const popoverRect = popover.getBoundingClientRect();
-            const left = panel.dataset.side === 'right' ? rowRect.left - popoverRect.width - 8 : rowRect.right + 8;
-            popover.style.left = `${Math.max(8, Math.min(left, innerWidth - popoverRect.width - 8))}px`;
-            popover.style.top = `${Math.max(8, Math.min(rowRect.top - 4, innerHeight - popoverRect.height - 8))}px`;
-          };
-          row.addEventListener('mouseenter', showErrorPopover);
-          row.addEventListener('mouseleave', hideErrorPopover);
-        }
         list.appendChild(row);
+        if (task.error) {
+          const details = node('div', 'comty-agent-item');
+          errorMessage(details, task.error, task.id);
+          list.appendChild(details);
+        }
         if (task.result?.summary) {
           const answer = node('div', 'comty-agent-answer');
           answer.append(brand(), node('p', '', task.result.summary));
@@ -3617,7 +3742,7 @@ export function initComty(options = {}) {
           if (!(pin instanceof HTMLElement)) return;
           const status = pin.dataset.status;
           const shouldShow =
-            !hasFilters || Boolean(status && selectedStatusFilters.has(status));
+            pin.hasAttribute('data-agent-task') || !hasFilters || Boolean(status && selectedStatusFilters.has(status));
           pin.classList.toggle("comty-filtered-out", !shouldShow);
         });
     }
@@ -3896,6 +4021,10 @@ export function initComty(options = {}) {
             thread: { commentId: String(comment.id), transcript } }),
         });
         if (!response.ok) throw new Error((await response.json().catch(() => null))?.error || 'Could not start Agent');
+        const data = await response.json();
+        if (!data.task?.id) throw new Error('Agent returned no task ID');
+        requestedAgentTasks.add(data.task.id);
+        void loadComments({ force: true });
       },
       get canWrite() { return canWrite; },
       get canManage() { return canManage; },
@@ -4011,6 +4140,7 @@ export function initComty(options = {}) {
 
       pin.onclick = (event) => {
         event.stopPropagation();
+        if (comment.local_agent) { openAgentTask(comment, getPinPoint(pin).x, getPinPoint(pin).y); return; }
         openCommentThread(
           comment,
           pin,
@@ -4135,7 +4265,7 @@ export function initComty(options = {}) {
       }
     }
 
-    async function loadComments({ force = false } = {}) {
+    async function loadComments({ force = false, tasksOnly = false } = {}) {
       if (!projectId && !agent) return;
       const pagePath = getPagePath();
       if (!force && cachedPagePath === pagePath) { await renderComments(cachedComments); return; }
@@ -4145,7 +4275,7 @@ export function initComty(options = {}) {
       }
       pendingCommentsLoad = (async () => {
         let comments = cachedPagePath === pagePath ? cachedComments.filter(comment => !comment.local_agent) : [];
-        if (projectId) {
+        if (projectId && !tasksOnly) {
           try {
             const paths = [...new Set([pagePath, window.location.pathname])];
             const batches = await Promise.all(paths.map(async path => {
@@ -4166,15 +4296,20 @@ export function initComty(options = {}) {
             const data = await res.json();
             if (Array.isArray(data.tasks)) localTasks = data.tasks;
             const failedTasks = localTasks.filter(task => task.status === 'in_review');
-            if (failedTasks.some(task => !seenFailedAgentTasks.has(task.id))) agentPanelOpen = true;
-            seenFailedAgentTasks.clear();
-            for (const task of failedTasks) seenFailedAgentTasks.add(task.id);
+            for (const task of failedTasks.filter(task => requestedAgentTasks.has(task.id))) {
+              if (task.error) showAgentBridgeError(task.error);
+              else showNotice({ title: 'Modification failed', description: 'The agent needs clarification.' });
+            }
             if (Array.isArray(data.approvals)) {
               localApprovals = data.approvals;
-              if (localApprovals.some(approval => !seenAgentApprovals.has(approval.id))) agentPanelOpen = true;
+              if (localApprovals.some(approval => requestedAgentTasks.has(approval.taskId) && !seenAgentApprovals.has(approval.id))) agentPanelOpen = true;
               seenAgentApprovals.clear();
               for (const approval of localApprovals) seenAgentApprovals.add(approval.id);
             }
+            for (const id of requestedAgentTasks) {
+              const task = localTasks.find(task => task.id === id);
+              if (!task || ['done', 'cancel', 'in_review'].includes(task.status)) requestedAgentTasks.delete(id);
+            }
             agentConnectionError = "";
           } catch (error) {
             agentConnectionError = "Local agent disconnected. Check the development server, then reload this page.";
@@ -4183,7 +4318,7 @@ export function initComty(options = {}) {
           for (const task of localTasks.filter(task => task.thread_comment_id && task.status === 'done' && task.result?.summary)) {
             void deliverThreadReply(task);
           }
-          comments.push(...localTasks.filter(task => task.page_path === pagePath && !task.thread_comment_id && !["done", "cancel"].includes(task.status)));
+          comments.push(...localTasks.filter(task => task.page_path === pagePath && !task.thread_comment_id && task.status === 'in_review'));
           renderAgentPanel();
         }
         if (pagePath !== getPagePath()) return;
@@ -4199,8 +4334,13 @@ export function initComty(options = {}) {
 
     if (agent) {
       setInterval(() => {
-        if (!pendingCommentsLoad && document.visibilityState === "visible") void loadComments({ force: true });
+        const active = requestedAgentTasks.size || localTasks.some(task =>
+          ['todo', 'in_progress'].includes(task.status) || (task.thread_comment_id && task.status === 'done' && task.result?.summary));
+        if (active && !pendingCommentsLoad && document.visibilityState === "visible") void loadComments({ force: true, tasksOnly: true });
       }, 2000);
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'visible' && !pendingCommentsLoad) void loadComments({ force: true, tasksOnly: true });
+      });
     }
 
     function getPinPoint(pin) {
@@ -4390,6 +4530,8 @@ export function initComty(options = {}) {
       const next = getPagePath();
       if (next === activePagePath) return;
       activePagePath = next;
+      markup.clear();
+      markup.setMode(null);
       closeBubbles();
       commentTargets.clear();
       reconcileComments([]);
@@ -4426,7 +4568,7 @@ export function initComty(options = {}) {
 
     document.addEventListener("pointermove", (event) => {
       if (!session.edit && !session.inspect) return;
-      if (motion.enabled) return;
+      if (motion.enabled || markup.mode) return;
       if (propertyPicking) {
         const target = event.target;
         if (propertyPicking === "font" && target instanceof Element && !isComtyElement(target) && getElementOwnTextSignature(target)) {
@@ -4573,6 +4715,12 @@ export function initComty(options = {}) {
         (target.isContentEditable ||
           ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName));
 
+      const markupMode = markup.mode;
+      if (session.inspect && (e.key === "Escape" || !isEditable) && markup.keydown(e)) {
+        e.preventDefault();
+        if (!markup.mode) (markupMode === "annotate" ? annotateBtn : screenshotBtn).focus({ preventScroll: true });
+        return;
+      }
       if (e.key === "Escape" && motion.enabled) {
         e.preventDefault();
         setMotionEnabled(false); motionBtn.focus({ preventScroll: true });
@@ -4587,7 +4735,7 @@ export function initComty(options = {}) {
         return;
       }
       if (session.inspect && !isEditable && !e.repeat && !e.ctrlKey && !e.metaKey && !e.altKey && !e.shiftKey) {
-        const button = { x: xrayBtn, r: rulersBtn, g: gridBtn, p: pipetteBtn, t: typographyBtn, m: motionBtn }[e.key.toLowerCase()];
+        const button = { x: xrayBtn, r: rulersBtn, g: gridBtn, p: pipetteBtn, t: typographyBtn, m: motionBtn, d: annotateBtn, s: screenshotBtn }[e.key.toLowerCase()];
         if (button) { e.preventDefault(); button.click(); return; }
       }
 
@@ -4595,6 +4743,11 @@ export function initComty(options = {}) {
         measureAlt = true;
         renderInspector();
       }
+      if (isLocalSite && !isEditable && !e.repeat && !e.isComposing && e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey && e.key.toLowerCase() === "a") {
+        e.preventDefault();
+        startAgentSession();
+        return;
+      }
       if (!isEditable && !e.repeat && e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey && e.key.toLowerCase() === "i") {
         e.preventDefault();
         setSession(session.inspect ? "off" : "inspect");

package/src/capture.js

@@ -20,8 +20,10 @@ export function createScreenshotCapture({ apiUrl, projectKey, getHeaders = () =>
     finally { clearTimeout(timer); }
   }
 
-  async function captureViewportScreenshot({ context = captureContext(), annotation } = {}) {
+  async function captureViewportScreenshot({ context = captureContext(), annotation, region } = {}) {
     if (document.visibilityState === "hidden") return null;
+    const area = region || { left: 0, top: 0, width: context.width, height: context.height };
+    if (![area.left, area.top, area.width, area.height].every(Number.isFinite) || area.left < 0 || area.top < 0 || area.width <= 0 || area.height <= 0 || area.left + area.width > context.width || area.top + area.height > context.height) throw new Error("Invalid capture area");
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 15000);
     const { signal } = controller;
@@ -35,7 +37,7 @@ export function createScreenshotCapture({ apiUrl, projectKey, getHeaders = () =>
     let lastYield = performance.now();
     const checkContext = () => {
       signal.throwIfAborted();
-      if (!frozen && (context.url !== location.href || context.width !== innerWidth || context.height !== innerHeight || context.scrollX !== scrollX || context.scrollY !== scrollY)) {
+      if ((!frozen || region) && (context.url !== location.href || context.width !== innerWidth || context.height !== innerHeight || context.scrollX !== scrollX || context.scrollY !== scrollY)) {
         throw new Error("Page moved before its screenshot was ready");
       }
     };
@@ -234,21 +236,21 @@ export function createScreenshotCapture({ apiUrl, projectKey, getHeaders = () =>
       image.src = svg;
       await untilAborted(image.decode());
       checkContext();
-      const scale = Math.min(2, devicePixelRatio || 1, 2560 / context.width, 2560 / context.height);
+      const scale = Math.min(2, devicePixelRatio || 1, 2560 / area.width, 2560 / area.height);
       const canvas = document.createElement("canvas");
-      canvas.width = Math.round(context.width * scale);
-      canvas.height = Math.round(context.height * scale);
+      canvas.width = Math.max(1, Math.round(area.width * scale));
+      canvas.height = Math.max(1, Math.round(area.height * scale));
       const ctx = canvas.getContext("2d");
       ctx.scale(scale, scale);
-      ctx.drawImage(image, 0, 0);
+      ctx.drawImage(image, -area.left, -area.top);
       let blob = await untilAborted(new Promise(resolve => canvas.toBlob(resolve, "image/png")));
       if (!blob) throw new Error("Screenshot encoding failed");
-      if (blob.size > 2800000) {
+      if (!region && blob.size > 2800000) {
         blob = await untilAborted(new Promise(resolve => canvas.toBlob(resolve, "image/jpeg", 0.9)));
         if (!blob) throw new Error("Screenshot encoding failed");
       }
       // CSS dimensions keep the eyedropper's coordinate system independent of DPR.
-      return { blob, width: canvas.width, height: canvas.height, cssWidth: context.width, cssHeight: context.height };
+      return { blob, width: canvas.width, height: canvas.height, cssWidth: area.width, cssHeight: area.height };
     } finally {
       clearTimeout(timeout);
       controller.abort();

package/src/claude.mjs

@@ -1,10 +1,10 @@
 import { spawn } from 'node:child_process';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
-import { existsSync, realpathSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseReceipt, receiptSchema, taskPrompt } from './codex.mjs';
 
@@ -13,7 +13,6 @@ const permissionScript = fileURLToPath(new URL('./claude-permission.mjs', import
 export async function runClaude({ cwd, task, signal, approve, progress, model, executable = 'claude', args = [] }) {
   signal.throwIfAborted();
   cwd = realpathSync(cwd);
-  if (executable === 'claude' && existsSync(resolve(cwd, 'node_modules/.bin/claude'))) executable = resolve(cwd, 'node_modules/.bin/claude');
 
   const token = randomBytes(32).toString('hex');
   const sockets = new Set();