@comty.io/core 0.1.6 → 0.1.8

package/comty-sdk.js

@@ -50,6 +50,10 @@ function getComtyStyle() {
         --comty-toolbar-selected: #505457;
         --comty-toolbar-muted: ${toolbarMuted};
         --comty-measure: #ff3b30;
+        --comty-markup-yellow: #facc15;
+        --comty-markup-green: #22c55e;
+        --comty-color-black: #000;
+        --comty-color-spectrum: linear-gradient(to right, #f00, #ff0, #0f0, #0ff, #00f, #f0f, #f00);
         --comty-font: "Inter", ui-sans-serif, system-ui, sans-serif;
         --comty-dialog-surface: var(--comty-surface);
         --comty-dialog-ink: var(--comty-foreground);
@@ -107,27 +111,34 @@ function getComtyStyle() {
       .comty-agent-dot[data-status="error"] { background: var(--comty-agent-error); }
       .comty-agent-row-name { min-width: 0; flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 500; }
       .comty-agent-row-state { flex: 0 0 auto; color: var(--comty-muted); font-size: .875rem; }
-      .comty-agent-row-actions { position: absolute; top: 50%; right: .25rem; display: flex; gap: .25rem; border-radius: .25rem; background: var(--comty-hover-surface); opacity: 0; pointer-events: none; transform: translateY(-50%); }
-      .comty-agent-row:hover .comty-agent-row-actions, .comty-agent-row-actions:has(.comty-agent-action:focus-visible) { opacity: 1; pointer-events: auto; }
-      @media (hover: none) { .comty-agent-row-actions { position: static; opacity: 1; pointer-events: auto; transform: none; background: transparent; } }
+      .comty-agent-row-actions { display: flex; flex-shrink: 0; gap: .25rem; }
       .comty-agent-panel .comty-agent-row-actions .comty-agent-action { min-height: 1.5rem; padding: .125rem .375rem; border-radius: .25rem; background: transparent; color: var(--comty-muted); font-size: .875rem; }
       .comty-agent-panel .comty-agent-row-actions .comty-agent-action:hover { color: var(--comty-foreground); background: var(--comty-surface); }
-      .comty-agent-error-popover { position: fixed; z-index: 2147483647; width: min(20rem, calc(100vw - 1rem)); max-height: calc(100vh - 1rem); overflow: auto; padding: .75rem .875rem; border: 0; border-radius: .625rem; background: var(--comty-surface); box-shadow: var(--comty-floating-shadow); color: var(--comty-foreground); font: .875rem/1.4 ui-sans-serif, system-ui, sans-serif; pointer-events: none; color-scheme: dark; }
-      .comty-agent-error-popover strong { display: block; font-weight: 600; }
-      .comty-agent-error-popover p { margin: .375rem 0 0; color: var(--comty-muted); white-space: pre-wrap; overflow-wrap: anywhere; }
+      #comty-root > .comty-agent-task-toast { position: fixed; right: 1rem; bottom: 1rem; z-index: 2147483647; width: min(20rem, calc(100vw - 2rem)); box-sizing: border-box; padding: .75rem 2rem .75rem .875rem; border: .0625rem solid var(--comty-border); border-radius: .75rem; background: var(--comty-surface); box-shadow: var(--comty-floating-shadow); color: var(--comty-foreground); font: .75rem/1.5 ui-sans-serif, system-ui, sans-serif; pointer-events: auto; opacity: 1; transform: translateY(0); transition: opacity 200ms ease, transform 200ms var(--comty-ease-out); animation: comty-agent-toast-in 200ms var(--comty-ease-out); color-scheme: dark; }
+      #comty-root > .comty-agent-task-toast[data-toolbar] { right: auto; bottom: auto; }
+      #comty-root > .comty-agent-task-toast[data-leaving] { opacity: 0; transform: translateY(.25rem); pointer-events: none; }
+      .comty-agent-task-toast strong { display: block; font-size: .8125rem; font-weight: 600; }
+      .comty-agent-task-toast p { margin: .25rem 0 0; color: var(--comty-muted); overflow-wrap: anywhere; }
+      .comty-agent-task-toast button { position: absolute; top: .5rem; right: .375rem; display: flex; align-items: center; justify-content: center; width: 1.5rem; height: 1.5rem; padding: 0; border: 0; border-radius: .25rem; background: transparent; color: var(--comty-muted); cursor: pointer; }
+      .comty-agent-task-toast button:hover { background: var(--comty-hover-surface); color: var(--comty-foreground); }
+      .comty-agent-task-toast button:focus-visible { outline: .125rem solid var(--comty-accent); outline-offset: .125rem; }
+      .comty-agent-task-toast svg { width: .875rem; height: .875rem; }
+      @keyframes comty-agent-toast-in { from { opacity: 0; transform: translateY(.25rem); } to { opacity: 1; transform: translateY(0); } }
       .comty-agent-panel p { margin: .5rem 0 0; font: inherit; color: var(--comty-muted); }
       .comty-agent-error { margin-top: .75rem; }
       .comty-agent-error strong { display: block; font-weight: 500; color: var(--comty-foreground); }
       .comty-agent-error p { margin-top: .25rem; }
       .comty-agent-banner { margin-bottom: 1rem; }
       .comty-agent-banner .comty-agent-error { margin-top: 0; }
+      .comty-agent-task-actions { display: flex; justify-content: flex-end; gap: .375rem; padding: .375rem .625rem; border-top: .0625rem solid var(--comty-border); }
       .comty-agent-actions { display: flex; flex-wrap: wrap; gap: .5rem; margin-top: .875rem; }
-      .comty-agent-panel .comty-agent-action { display: inline-flex; align-items: center; justify-content: center; gap: .375rem; min-height: 2rem; margin: 0; padding: .375rem .625rem; border: 0; border-radius: .5rem; font: 500 .875rem/1.4 ui-sans-serif, system-ui, sans-serif; cursor: pointer; color: var(--comty-foreground); background: var(--comty-hover-surface); transition: background-color 150ms ease; }
-      .comty-agent-panel .comty-agent-action:hover { background: color-mix(in srgb, var(--comty-foreground) 12%, var(--comty-hover-surface)); }
-      .comty-agent-panel .comty-agent-action[data-primary] { color: var(--comty-paper); background: var(--comty-accent); }
-      .comty-agent-panel .comty-agent-action:disabled { opacity: .5; cursor: wait; }
+      :is(.comty-agent-panel, .comty-agent-task-thread) .comty-agent-action { display: inline-flex; align-items: center; justify-content: center; gap: .375rem; min-height: 2rem; margin: 0; padding: .375rem .625rem; border: 0; border-radius: .5rem; font: 500 .875rem/1.4 ui-sans-serif, system-ui, sans-serif; cursor: pointer; color: var(--comty-foreground); background: var(--comty-hover-surface); transition: background-color 150ms ease; }
+      .comty-agent-task-thread .comty-agent-action { min-height: 1.5rem; padding: .125rem .5rem; border-radius: .375rem; font-size: .75rem; }
+      :is(.comty-agent-panel, .comty-agent-task-thread) .comty-agent-action:hover { background: color-mix(in srgb, var(--comty-foreground) 12%, var(--comty-hover-surface)); }
+      :is(.comty-agent-panel, .comty-agent-task-thread) .comty-agent-action[data-primary] { color: var(--comty-paper); background: var(--comty-accent); }
+      :is(.comty-agent-panel, .comty-agent-task-thread) .comty-agent-action:disabled { opacity: .5; cursor: wait; }
       .comty-agent-panel .comty-agent-close { width: 1.5rem; min-height: 1.5rem; padding: 0; background: transparent; color: var(--comty-muted); }
-      .comty-agent-panel :is(button, summary):focus-visible { outline: .125rem solid var(--comty-accent); outline-offset: .1875rem; }
+      :is(.comty-agent-panel, .comty-agent-task-thread) :is(button, summary):focus-visible { outline: .125rem solid var(--comty-accent); outline-offset: .1875rem; }
       .comty-agent-details { margin-top: .625rem; }
       .comty-agent-panel summary { cursor: pointer; color: var(--comty-muted); font-size: .875rem; }
       .comty-agent-panel pre { margin: .5rem 0 0; padding: .625rem; white-space: pre-wrap; overflow-wrap: anywhere; max-height: 10rem; overflow: auto; border-radius: .5rem; background: var(--comty-surface); color: var(--comty-muted); font: .875rem/1.4 ui-monospace, monospace; }
@@ -206,7 +217,7 @@ function getComtyStyle() {
       #comty-root [hidden] { display: none !important; }
       [data-comty-anchor-hidden] { visibility: hidden !important; pointer-events: none !important; }
       @media (prefers-reduced-motion: reduce) {
-        .comty-toolbar, .comty-control-button, .comty-sidepanel, .comty-pin, .comty-bubble, .comty-agent-panel, .comty-agent-action, .comty-agent-dot, .comty-working-indicator > i { transition: none !important; animation: none !important; }
+        .comty-toolbar, .comty-control-button, .comty-sidepanel, .comty-pin, .comty-bubble, .comty-agent-panel, .comty-agent-action, .comty-agent-dot, .comty-working-indicator > i, #comty-root > .comty-agent-task-toast { transition: none !important; animation: none !important; }
       }
 
       .comty-sidepanel {
@@ -929,6 +940,8 @@ function getComtyStyle() {
       }
 
       .comty-hover-bubble .comty-thread {
+        display: grid;
+        gap: 1rem;
         padding: 12px;
       }
 
@@ -1184,6 +1197,10 @@ function getComtyStyle() {
       }
 
       .comty-inspection-layer { position: relative; z-index: 2147483647; pointer-events: none; }
+      .comty-markup-layer, .comty-markup-surface { position: fixed; inset: 0; width: 100%; height: 100%; z-index: 2; pointer-events: none; }
+      .comty-markup-surface { pointer-events: auto; cursor: crosshair; touch-action: none; user-select: none; }
+      .comty-markup-surface[aria-busy="true"] { cursor: progress; }
+      .comty-capture-selection { position: absolute; box-sizing: border-box; border: .0625rem solid var(--comty-accent); box-shadow: 0 0 0 100vmax var(--comty-dialog-backdrop); color: var(--comty-paper); text-shadow: 0 .0625rem .125rem var(--comty-ink); font: .6875rem/1.5 var(--comty-font); padding: .25rem; white-space: nowrap; }
       .comty-overlay-tools, .comty-layout-guides, .comty-layout-guide { position: fixed; inset: 0; pointer-events: none; }
       .comty-overlay-tools { overflow: hidden; }
       .comty-layout-guide { display: grid; box-sizing: border-box; }
@@ -1209,6 +1226,38 @@ function getComtyStyle() {
       .comty-guide-fields label { display: flex; align-items: center; justify-content: space-between; gap: .5rem; }
       .comty-tool-panel input, .comty-tool-panel select { min-width: 0; width: 6rem; box-sizing: border-box; border: 0; border-radius: .25rem; padding: .25rem; background: var(--comty-surface); color: var(--comty-foreground); font: inherit; }
       .comty-tool-panel input[type="color"] { height: 1.75rem; padding: .125rem; }
+      .comty-tool-panel.comty-markup-panel { width: max-content; padding: .375rem; border-radius: .875rem; background: var(--comty-toolbar-group); }
+      .comty-markup-controls, .comty-markup-options, .comty-markup-strokes, .comty-markup-colors { display: flex; align-items: center; gap: .125rem; }
+      .comty-markup-controls { justify-content: space-between; }
+      .comty-markup-options { margin-top: .375rem; padding-top: .375rem; border-top: .0625rem solid var(--comty-border); }
+      .comty-markup-divider { flex: 0 0 .0625rem; height: 1rem; margin-inline: .25rem; background: var(--comty-border); }
+      .comty-markup-panel button { flex: 0 0 auto; width: 2rem; height: 2rem; padding: 0; color: var(--comty-toolbar-muted); border-radius: .5rem; }
+      .comty-markup-panel button svg { display: block; flex: 0 0 auto; width: 1rem; height: 1rem; }
+      .comty-markup-panel button[aria-pressed="false"] { opacity: 1; }
+      .comty-markup-panel button[aria-pressed="true"] { color: var(--comty-foreground); background: var(--comty-hover-surface); }
+      .comty-markup-panel button:disabled { opacity: .35; cursor: default; }
+      .comty-markup-panel button:disabled:hover { background: transparent; }
+      .comty-markup-panel button:not(:disabled):active { transform: scale(.97); }
+      .comty-markup-strokes button { width: 1.5rem; height: 1.5rem; }
+      .comty-markup-colors button { width: 1.375rem; height: 1.5rem; background: transparent; }
+      .comty-markup-colors button[aria-pressed="true"] { background: transparent; }
+      .comty-markup-swatch { display: block; width: .875rem; height: .875rem; border-radius: 50%; background: var(--markup-swatch); box-shadow: inset 0 0 0 .0625rem color-mix(in srgb, var(--comty-paper) 15%, transparent); }
+      .comty-markup-colors button[aria-pressed="true"] .comty-markup-swatch { outline: .0625rem solid var(--comty-foreground); outline-offset: .125rem; }
+      .comty-markup-panel button.comty-markup-picker { width: 1rem; padding: 0; position: relative; flex: 0 0 1rem; height: 1rem; margin-inline: .25rem; border-radius: 50%; background: conic-gradient(var(--comty-measure), var(--comty-markup-yellow), var(--comty-markup-green), var(--comty-accent), var(--comty-error), var(--comty-measure)); }
+      .comty-markup-picker[data-selected] { outline: .0625rem solid var(--comty-foreground); outline-offset: .125rem; }
+      .comty-markup-picker:focus-visible { outline: .125rem solid var(--comty-accent); outline-offset: .125rem; }
+      .comty-markup-color { display: grid; gap: .625rem; margin-top: .375rem; padding: .625rem .25rem .25rem; border-top: .0625rem solid var(--comty-border); }
+      .comty-markup-color-field { position: relative; height: 8rem; border-radius: .5rem; background: linear-gradient(to top, var(--comty-color-black), transparent), linear-gradient(to right, var(--comty-paper), transparent), var(--markup-hue); touch-action: none; cursor: crosshair; }
+      .comty-markup-color-field:focus-visible { outline: .125rem solid var(--comty-accent); outline-offset: .125rem; }
+      .comty-markup-color-field > span { position: absolute; width: .625rem; height: .625rem; box-sizing: border-box; border: .125rem solid var(--comty-paper); border-radius: 50%; background: var(--markup-color); box-shadow: 0 0 0 .0625rem var(--comty-ink); transform: translate(-50%, -50%); pointer-events: none; }
+      .comty-markup-color input.comty-markup-hue { appearance: none; -webkit-appearance: none; display: block; width: 100%; height: 1rem; margin: 0; padding: 0; border-radius: 1rem; background: var(--comty-color-spectrum); cursor: pointer; }
+      .comty-markup-hue::-webkit-slider-thumb { appearance: none; -webkit-appearance: none; width: .875rem; height: .875rem; box-sizing: border-box; border: .125rem solid var(--comty-paper); border-radius: 50%; background: var(--markup-hue); box-shadow: 0 0 0 .0625rem var(--comty-ink); }
+      .comty-markup-hue::-moz-range-thumb { width: .875rem; height: .875rem; box-sizing: border-box; border: .125rem solid var(--comty-paper); border-radius: 50%; background: var(--markup-hue); box-shadow: 0 0 0 .0625rem var(--comty-ink); }
+      .comty-markup-hex { display: flex; align-items: center; gap: .5rem; padding: .25rem .5rem; border-radius: .5rem; background: var(--comty-surface); color: var(--comty-muted); font: .6875rem/1.5 var(--comty-font); }
+      .comty-markup-color-preview { flex: 0 0 1rem; height: 1rem; border-radius: .25rem; background: var(--markup-color); box-shadow: inset 0 0 0 .0625rem var(--comty-border); }
+      .comty-markup-hex input { flex: 1; width: 0; text-align: right; font-family: ui-monospace, monospace; }
+      .comty-markup-hex input[aria-invalid="true"] { outline: .0625rem solid var(--comty-error); }
+
       .comty-ruler { position: fixed; background: var(--comty-surface); pointer-events: auto; touch-action: none; }
       .comty-ruler-horizontal { left: 0; top: 0; width: 100vw; height: 1.125rem; border-bottom: .0625rem solid var(--comty-border); cursor: ns-resize; }
       .comty-ruler-vertical { left: 0; top: 0; height: 100vh; width: 1.125rem; border-right: .0625rem solid var(--comty-border); cursor: ew-resize; }
@@ -1283,7 +1332,7 @@ function getComtyStyle() {
       .comty-motion-panel button[aria-pressed="true"] { opacity: 1; color: var(--comty-paper); background: var(--comty-hover-surface); }
       .comty-motion-panel button[aria-pressed="false"] { opacity: 1; }
       .comty-motion-panel [data-motion-status] { margin: .5rem; font-size: .75rem; color: var(--comty-muted); }
-      @media (max-width: 25rem) { #comty-root { --comty-tool-size: 2rem; --comty-toolbar-padding: .25rem; } .comty-toolbar { right: .5rem; bottom: .5rem; max-width: calc(100vw - 1rem); flex-wrap: wrap; justify-content: center; row-gap: .25rem; } .comty-tool-divider { display: none; } }
+      @media (max-width: 38rem) { #comty-root { --comty-tool-size: 2rem; --comty-toolbar-padding: .25rem; } .comty-toolbar { right: .5rem; bottom: .5rem; max-width: calc(100vw - 1rem); flex-wrap: wrap; justify-content: center; row-gap: .25rem; } .comty-tool-divider { display: none; } }
 
       .comty-inspection-box {
         position: fixed;
@@ -2141,8 +2190,10 @@ 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;
@@ -2156,7 +2207,7 @@ 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");
       }
     };
@@ -2355,21 +2406,21 @@ 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();
@@ -3023,6 +3074,290 @@ function createCommentThread(context) {
     }
 }
 
+// Page-coordinate drawings stay attached to the document when the viewport scrolls.
+function createInspectMarkup({ root, icon, onChange, capture, onError }) {
+  const ns = 'http://www.w3.org/2000/svg';
+  const layer = document.createElementNS(ns, 'svg');
+  layer.classList.add('comty-markup-layer');
+  layer.setAttribute('aria-hidden', 'true');
+  const drawings = document.createElementNS(ns, 'g');
+  layer.append(drawings);
+  root.append(layer);
+  const surface = document.createElement('div');
+  surface.className = 'comty-markup-surface';
+  surface.hidden = true;
+  const selection = document.createElement('div');
+  selection.className = 'comty-capture-selection';
+  selection.hidden = true;
+  surface.append(selection);
+  root.append(surface);
+  const panel = document.createElement('section');
+  panel.className = 'comty-tool-panel comty-markup-panel';
+  panel.id = 'comty-markup-panel';
+  panel.setAttribute('aria-label', 'Annotations and screenshot');
+  panel.hidden = true;
+  root.append(panel);
+  const shapes = {
+    pencil: ['Pencil', '<path d="m16 3 5 5L8 21H3v-5ZM14 5l5 5"/>'],
+    rectangle: ['Rectangle', '<rect x="4" y="5" width="16" height="14" rx="1"/>'],
+    ellipse: ['Ellipse', '<ellipse cx="12" cy="12" rx="9" ry="7"/>'],
+    arrow: ['Arrow', '<path d="M4 20 20 4M8 4h12v12"/>'],
+  };
+  const palette = [
+    ['Red', '--comty-measure'], ['Yellow', '--comty-markup-yellow'],
+    ['Green', '--comty-markup-green'], ['Blue', '--comty-accent'],
+    ['Black', '--comty-ink'], ['White', '--comty-paper'],
+  ];
+  const tokenColor = token => {
+    const value = getComputedStyle(root).getPropertyValue(token).trim();
+    return /^#[\da-f]{3}$/i.test(value) ? '#' + [...value.slice(1)].map(char => char + char).join('') : value;
+  };
+  panel.setAttribute('aria-label', 'Annotation tools');
+  panel.innerHTML = [
+    '<div class="comty-markup-controls" role="group" aria-label="Drawing tools">',
+    ...Object.entries(shapes).map(([key, [label, paths]]) => `<button type="button" data-shape="${key}" aria-label="${label}" title="${label}" aria-pressed="false">${icon(paths)}</button>`),
+    '<span class="comty-markup-divider" aria-hidden="true"></span>',
+    `<button type="button" data-undo aria-label="Undo annotation" title="Undo · ⌘/Ctrl Z">${icon('<path d="m9 4-5 5 5 5M4 9h10a6 6 0 0 1 0 12"/>')}</button>`,
+    `<button type="button" data-clear aria-label="Clear annotations" title="Clear annotations">${icon('<path d="M3 6h18M9 6V3h6v3M5 6l1 15h12l1-15M10 10v7m4-7v7"/>')}</button></div>`,
+    '<div class="comty-markup-options"><div class="comty-markup-strokes" role="group" aria-label="Stroke width">',
+    ...[[2, 'Thin'], [3, 'Medium'], [5, 'Thick']].map(([width, label]) => `<button type="button" data-stroke="${width}" aria-label="${label} stroke" title="${label}" aria-pressed="false"><svg viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="m7 7 10 10" stroke="currentColor" stroke-width="${width}" stroke-linecap="round"/></svg></button>`),
+    '</div><span class="comty-markup-divider" aria-hidden="true"></span><div class="comty-markup-colors" role="group" aria-label="Annotation colors">',
+    ...palette.map(([name, token]) => `<button type="button" data-color="${token}" aria-label="${name} ink" title="${name}" aria-pressed="false"><span class="comty-markup-swatch" aria-hidden="true"></span></button>`),
+    '<button type="button" class="comty-markup-picker" title="Custom color" aria-label="Custom annotation color" aria-expanded="false" aria-controls="comty-markup-color"></button>',
+    '</div></div>',
+    '<div class="comty-markup-color" id="comty-markup-color" role="group" aria-label="Custom color picker" hidden>',
+    '<div class="comty-markup-color-field" tabindex="0" role="group" aria-label="Saturation and brightness" aria-description="Left and right arrows adjust saturation. Up and down arrows adjust brightness."><span aria-hidden="true"></span></div>',
+    '<input class="comty-markup-hue" type="range" min="0" max="360" step="1" aria-label="Hue">',
+    '<label class="comty-markup-hex"><span class="comty-markup-color-preview" aria-hidden="true"></span><span>HEX</span><input type="text" aria-label="Hex color" maxlength="7" spellcheck="false" autocomplete="off" autocapitalize="off"></label>',
+    '</div>',
+  ].join('');
+  const picker = panel.querySelector('.comty-markup-picker');
+  const colorPanel = panel.querySelector('.comty-markup-color');
+  const colorField = panel.querySelector('.comty-markup-color-field');
+  const hueInput = panel.querySelector('.comty-markup-hue');
+  const hexInput = panel.querySelector('[aria-label="Hex color"]');
+  let pickerOpen = false, colorPointer = null;
+  let hue = 0, saturation = 1, brightness = 1;
+  let mode = null, shape = 'pencil', drag = null, visible = false, busy = false;
+  let stroke = 3, color = tokenColor('--comty-measure');
+  readColor(color);
+  for (const button of panel.querySelectorAll('[data-color]')) button.style.setProperty('--markup-swatch', tokenColor(button.dataset.color));
+  let revision = 0;
+  const history = [];
+  const clamp = (v, max) => Math.max(0, Math.min(max, v));
+  function point(event) { return { x: clamp(event.clientX, innerWidth), y: clamp(event.clientY, innerHeight) }; }
+  function sync() {
+    layer.style.display = visible ? '' : 'none';
+    surface.hidden = !visible || !mode;
+    panel.hidden = !visible || mode !== 'annotate';
+    for (const button of panel.querySelectorAll('[data-stroke]')) button.setAttribute('aria-pressed', String(Number(button.dataset.stroke) === stroke));
+    for (const button of panel.querySelectorAll('[data-color]')) button.setAttribute('aria-pressed', String(tokenColor(button.dataset.color) === color));
+    picker.toggleAttribute('data-selected', !palette.some(([, token]) => tokenColor(token) === color));
+    syncPicker();
+    for (const button of panel.querySelectorAll('[data-shape]')) button.setAttribute('aria-pressed', String(button.dataset.shape === shape));
+    panel.querySelector('[data-undo]').disabled = !history.length;
+    panel.querySelector('[data-clear]').disabled = !history.length;
+    render();
+    onChange();
+  }
+  function cancelDrag() {
+    if (!drag) return;
+    drag.node?.remove();
+    const id = drag.id;
+    drag = null;
+    if (surface.hasPointerCapture(id)) surface.releasePointerCapture(id);
+    selection.hidden = true;
+  }
+  function setMode(next) {
+    if (busy && next) return;
+    cancelDrag();
+    if (!next) revision++;
+    mode = next;
+    if (next !== 'annotate') { pickerOpen = false; finishColorDrag(); }
+    sync();
+  }
+  function undo() { history.pop()?.remove(); sync(); }
+  function clear() { cancelDrag(); history.length = 0; drawings.replaceChildren(); sync(); }
+  panel.querySelector('[data-undo]').onclick = undo;
+  panel.querySelector('[data-clear]').onclick = clear;
+  for (const button of panel.querySelectorAll('[data-shape]')) button.onclick = () => { shape = button.dataset.shape; sync(); };
+  for (const button of panel.querySelectorAll('[data-stroke]')) button.onclick = () => { stroke = Number(button.dataset.stroke); sync(); };
+  for (const button of panel.querySelectorAll('[data-color]')) button.onclick = () => {
+    color = tokenColor(button.dataset.color); readColor(color); sync();
+  };
+  function readColor(value) {
+    const [r, g, b] = value.slice(1).match(/../g).map(part => parseInt(part, 16) / 255);
+    const max = Math.max(r, g, b), min = Math.min(r, g, b), delta = max - min;
+    if (delta) hue = ((max === r ? (g - b) / delta : max === g ? (b - r) / delta + 2 : (r - g) / delta + 4) * 60 + 360) % 360;
+    saturation = max ? delta / max : 0;
+    brightness = max;
+  }
+  function writeColor() {
+    const channel = offset => {
+      const k = (offset + hue / 60) % 6;
+      return Math.round(255 * brightness * (1 - saturation * Math.max(0, Math.min(k, 4 - k, 1)))).toString(16).padStart(2, '0');
+    };
+    color = '#' + [5, 3, 1].map(channel).join('');
+    sync();
+  }
+  function syncPicker() {
+    colorPanel.hidden = !pickerOpen;
+    picker.setAttribute('aria-expanded', String(pickerOpen));
+    colorPanel.style.setProperty('--markup-hue', `hsl(${hue} 100% 50%)`);
+    colorPanel.style.setProperty('--markup-color', color);
+    const marker = colorField.firstElementChild;
+    marker.style.left = `${saturation * 100}%`;
+    marker.style.top = `${(1 - brightness) * 100}%`;
+    colorField.setAttribute('aria-description', `Saturation ${Math.round(saturation * 100)}%, brightness ${Math.round(brightness * 100)}%. Left and right arrows adjust saturation. Up and down arrows adjust brightness.`);
+    hueInput.value = String(Math.round(hue));
+    hueInput.setAttribute('aria-valuetext', `${Math.round(hue)} degrees`);
+    if (document.activeElement !== hexInput) { hexInput.value = color.toUpperCase(); hexInput.removeAttribute('aria-invalid'); }
+  }
+  picker.onclick = () => { pickerOpen = !pickerOpen; sync(); };
+  function moveColor(event) {
+    const rect = colorField.getBoundingClientRect();
+    saturation = clamp((event.clientX - rect.left) / rect.width, 1);
+    brightness = 1 - clamp((event.clientY - rect.top) / rect.height, 1);
+    writeColor();
+  }
+  function finishColorDrag() {
+    const id = colorPointer;
+    colorPointer = null;
+    if (id !== null && colorField.hasPointerCapture(id)) colorField.releasePointerCapture(id);
+  }
+  colorField.onpointerdown = event => {
+    if (event.button !== 0 || colorPointer !== null) return;
+    event.preventDefault(); event.stopPropagation();
+    colorField.focus({ preventScroll: true });
+    colorPointer = event.pointerId;
+    colorField.setPointerCapture(event.pointerId);
+    moveColor(event);
+  };
+  colorField.onpointermove = event => { if (colorPointer === event.pointerId) moveColor(event); };
+  colorField.onpointerup = event => { if (colorPointer === event.pointerId) { moveColor(event); finishColorDrag(); } };
+  colorField.onpointercancel = finishColorDrag;
+  colorField.onlostpointercapture = finishColorDrag;
+  window.addEventListener('blur', finishColorDrag);
+  colorField.onkeydown = event => {
+    if (!['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(event.key)) return;
+    event.preventDefault(); event.stopPropagation();
+    const step = event.shiftKey ? .1 : .01;
+    if (event.key === 'ArrowLeft') saturation = clamp(saturation - step, 1);
+    if (event.key === 'ArrowRight') saturation = clamp(saturation + step, 1);
+    if (event.key === 'ArrowUp') brightness = clamp(brightness + step, 1);
+    if (event.key === 'ArrowDown') brightness = clamp(brightness - step, 1);
+    writeColor();
+  };
+  hueInput.oninput = () => { hue = Number(hueInput.value); writeColor(); };
+  function applyHex(commit = false) {
+    const value = hexInput.value.trim().replace(/^#/, '');
+    const valid = /^[\da-f]{6}$/i.test(value) || (commit && /^[\da-f]{3}$/i.test(value));
+    if (valid) {
+      color = '#' + (value.length === 3 ? [...value].map(char => char + char).join('') : value).toLowerCase();
+      readColor(color); hexInput.removeAttribute('aria-invalid'); sync();
+    } else hexInput.setAttribute('aria-invalid', 'true');
+    if (commit) { hexInput.value = color.toUpperCase(); hexInput.removeAttribute('aria-invalid'); }
+  }
+  hexInput.oninput = () => applyHex();
+  hexInput.onblur = () => applyHex(true);
+  hexInput.onkeydown = event => { if (event.key === 'Enter') { event.preventDefault(); applyHex(true); } };
+  function render() { drawings.setAttribute('transform', `translate(${-scrollX} ${-scrollY})`); }
+  function update(event) {
+    const p = point(event), start = drag.start;
+    drag.end = p;
+    if (mode === 'capture') {
+      Object.assign(selection.style, { left: `${Math.min(start.x, p.x)}px`, top: `${Math.min(start.y, p.y)}px`, width: `${Math.abs(p.x - start.x)}px`, height: `${Math.abs(p.y - start.y)}px` });
+      selection.textContent = `${Math.round(Math.abs(p.x - start.x))} × ${Math.round(Math.abs(p.y - start.y))}`;
+      selection.hidden = false;
+      return;
+    }
+    const a = drag.origin, b = { x: p.x + scrollX, y: p.y + scrollY };
+    const left = Math.min(a.x, b.x), top = Math.min(a.y, b.y), w = Math.abs(b.x - a.x), h = Math.abs(b.y - a.y);
+    let d;
+    if (shape === 'pencil') {
+      drag.points.push(b);
+      d = drag.points.map((p, i) => `${i ? 'L' : 'M'}${p.x} ${p.y}`).join(' ');
+    } else if (shape === 'rectangle') d = `M${left} ${top}h${w}v${h}h${-w}Z`;
+    else if (shape === 'ellipse') d = `M${left} ${top + h/2}a${w/2} ${h/2} 0 1 0 ${w} 0a${w/2} ${h/2} 0 1 0 ${-w} 0`;
+    else {
+      const angle = Math.atan2(b.y-a.y, b.x-a.x), size = Math.min(16, Math.hypot(b.x-a.x,b.y-a.y)/3);
+      d = `M${a.x} ${a.y}L${b.x} ${b.y}M${b.x-size*Math.cos(angle-.5)} ${b.y-size*Math.sin(angle-.5)}L${b.x} ${b.y}L${b.x-size*Math.cos(angle+.5)} ${b.y-size*Math.sin(angle+.5)}`;
+    }
+    drag.node.setAttribute('d', d);
+  }
+  surface.addEventListener('pointerdown', event => {
+    if (event.button !== 0 || drag || busy) return;
+    event.preventDefault(); event.stopPropagation();
+    const start = point(event), origin = { x: start.x + scrollX, y: start.y + scrollY };
+    drag = { id: event.pointerId, start, end: start, origin, points: [origin] };
+    if (mode === 'annotate') {
+      drag.node = document.createElementNS(ns, 'path');
+      drag.node.setAttribute('fill', 'none');
+      drag.node.setAttribute('stroke', color);
+      drag.node.setAttribute('stroke-width', String(stroke));
+      drag.node.setAttribute('stroke-linecap', 'round');
+      drag.node.setAttribute('stroke-linejoin', 'round');
+      drawings.append(drag.node);
+    }
+    surface.setPointerCapture(event.pointerId);
+    update(event);
+  });
+  surface.addEventListener('pointermove', event => { if (drag?.id === event.pointerId) { event.preventDefault(); update(event); } });
+  surface.addEventListener('pointerup', async event => {
+    if (drag?.id !== event.pointerId) return;
+    event.preventDefault(); event.stopPropagation();
+    update(event);
+    const finished = drag;
+    drag = null;
+    surface.releasePointerCapture(event.pointerId);
+    selection.hidden = true;
+    if (mode === 'annotate') { history.push(finished.node); sync(); return; }
+    const region = { left: Math.floor(Math.min(finished.start.x, finished.end.x)), top: Math.floor(Math.min(finished.start.y, finished.end.y)), width: Math.round(Math.abs(finished.end.x-finished.start.x)), height: Math.round(Math.abs(finished.end.y-finished.start.y)) };
+    if (region.width < 4 || region.height < 4) return;
+    busy = true;
+    const current = ++revision;
+    surface.setAttribute('aria-busy', 'true');
+    sync();
+    try {
+      const result = await capture(region, layer);
+      if (current !== revision) return;
+      if (!result) throw new Error('Page is not visible');
+      const url = URL.createObjectURL(result.blob);
+      const link = document.createElement('a');
+      link.href = url; link.download = `comty-${new Date().toISOString().replace(/[:.]/g, '-')}.png`;
+      link.click();
+      setTimeout(() => URL.revokeObjectURL(url), 60000);
+    } catch (error) {
+      if (current === revision) onError(`Capture failed. ${error.message}. Try again.`);
+    } finally {
+      busy = false; surface.removeAttribute('aria-busy'); sync();
+    }
+  });
+  surface.addEventListener('pointercancel', cancelDrag);
+  surface.addEventListener('lostpointercapture', cancelDrag);
+  surface.addEventListener('click', event => { event.preventDefault(); event.stopPropagation(); });
+  surface.addEventListener('wheel', event => { if (drag || busy) event.preventDefault(); }, { passive: false });
+  document.addEventListener('scroll', () => { cancelDrag(); render(); }, { passive: true, capture: true });
+  window.addEventListener('resize', cancelDrag);
+  window.addEventListener('blur', cancelDrag);
+  return {
+    panel, setMode, render, clear,
+    get mode() { return mode; },
+    get busy() { return busy; },
+    setVisible(value) { visible = value; if (!value) { revision++; mode = null; pickerOpen = false; finishColorDrag(); cancelDrag(); } sync(); },
+    keydown(event) {
+      if (!mode) return false;
+      if (event.key === 'Escape') {
+        if (pickerOpen) { pickerOpen = false; finishColorDrag(); picker.focus({ preventScroll: true }); sync(); return true; }
+        if (drag) cancelDrag(); else setMode(null);
+        return true;
+      }
+      if (mode === 'annotate' && (event.metaKey || event.ctrlKey) && !event.shiftKey && event.key.toLowerCase() === 'z') { cancelDrag(); undo(); return true; }
+      return false;
+    },
+  };
+}
+
 const edgeAxis = { top: "y", bottom: "y", left: "x", right: "x" };
 const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 
@@ -3055,7 +3390,7 @@ function measurementPoint(anchor, rect, scroll = { x: 0, y: 0 }) {
 }
 
 /** Border measurements live for one activation of the existing ruler tool. */
-function createMeasurements({ root, isComtyElement, isElementTreeHidden, onExit }) {
+function createMeasurements({ root, isComtyElement, isElementTreeHidden, onExit, isInteractionBlocked = () => false }) {
   let enabled = false;
   let hover = null;
   let drag = null;
@@ -3179,7 +3514,7 @@ function createMeasurements({ root, isComtyElement, isElementTreeHidden, onExit
     }
   }
   function isHostEvent(event) {
-    if (!enabled || !(event.target instanceof Element)) return false;
+    if (!enabled || isInteractionBlocked() || !(event.target instanceof Element)) return false;
     if (!isComtyElement(event.target)) return true;
     // The outer ruler strip must still let us anchor to the page's top/left edge.
     return event.target.matches(".comty-ruler") && (event.clientX + scrollX <= 10 || event.clientY + scrollY <= 10);
@@ -3217,7 +3552,7 @@ function createMeasurements({ root, isComtyElement, isElementTreeHidden, onExit
     if (isHostEvent(event)) { event.preventDefault(); event.stopImmediatePropagation(); }
   }, true);
   document.addEventListener("keydown", event => {
-    if (!enabled || event.key !== "Escape" || event.target.closest?.(".comty-auth-dialog, input, textarea, [contenteditable=true]")) return;
+    if (!enabled || isInteractionBlocked() || event.key !== "Escape" || event.target.closest?.(".comty-auth-dialog, input, textarea, [contenteditable=true]")) return;
     event.preventDefault(); event.stopImmediatePropagation();
     if (drag) cancel(); else onExit();
   }, true);
@@ -3250,7 +3585,7 @@ function initComty(options = {}) {
     } catch { return Promise.reject(new TypeError("Comty: companion must share the page origin")); }
   }
   const projectKey = options.projectKey || (agent ? "local" : undefined);
-  const apiUrl = options.apiUrl || "http://localhost:4000";
+  const apiUrl = options.apiUrl || "https://api.comty.io";
   if (typeof projectKey !== "string" || !projectKey.trim()) {
     return Promise.reject(new TypeError("Comty: projectKey is required"));
   }
@@ -3286,12 +3621,14 @@ 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",
@@ -3424,6 +3761,9 @@ 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();
@@ -3431,6 +3771,10 @@ 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);
@@ -3470,6 +3814,7 @@ function initComty(options = {}) {
       root,
       isComtyElement,
       isElementTreeHidden,
+      isInteractionBlocked: () => Boolean(markup.mode),
       onExit() { rulersEnabled = false; syncInspectorTools(); },
     });
     const gridLayer = document.createElement("div");
@@ -3496,6 +3841,7 @@ 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;
@@ -3506,6 +3852,7 @@ 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;
@@ -3523,7 +3870,37 @@ 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');
@@ -3572,6 +3949,7 @@ 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();
@@ -3830,6 +4208,7 @@ 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)));
@@ -4113,6 +4492,7 @@ 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;
@@ -4370,7 +4750,7 @@ 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;
@@ -4387,9 +4767,10 @@ 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 => {
@@ -4724,7 +5105,7 @@ 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;
@@ -4858,6 +5239,7 @@ function initComty(options = {}) {
       inspectorTools.hidden = !session.inspect;
       syncInspectorTools();
       renderAgentPanel();
+      positionNotice();
     }
 
     const inspectionLayer = document.createElement("div");
@@ -5170,7 +5552,7 @@ 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;
       }
@@ -5314,10 +5696,12 @@ 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() {
@@ -5325,6 +5709,7 @@ function initComty(options = {}) {
       if (session.agent) return;
       closeBubbles();
       setSession("agent", { renderComments: true });
+      void loadComments({ force: true });
     }
 
     function toggleSidepanel() {
@@ -6062,6 +6447,7 @@ 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`;
@@ -6079,10 +6465,52 @@ 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 = "";
@@ -6266,6 +6694,7 @@ 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);
@@ -6397,14 +6826,53 @@ 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) {
@@ -6433,7 +6901,7 @@ 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)) {
@@ -6446,11 +6914,21 @@ 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 = [];
@@ -6469,6 +6947,7 @@ 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";
@@ -6489,7 +6968,6 @@ 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;
@@ -6535,12 +7013,7 @@ 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(); }
         };
@@ -6561,9 +7034,7 @@ 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;
@@ -6579,24 +7050,12 @@ 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));
@@ -6847,7 +7306,7 @@ 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);
         });
     }
@@ -7126,6 +7585,10 @@ 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; },
@@ -7241,6 +7704,7 @@ function initComty(options = {}) {
 
       pin.onclick = (event) => {
         event.stopPropagation();
+        if (comment.local_agent) { openAgentTask(comment, getPinPoint(pin).x, getPinPoint(pin).y); return; }
         openCommentThread(
           comment,
           pin,
@@ -7365,7 +7829,7 @@ 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; }
@@ -7375,7 +7839,7 @@ 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 => {
@@ -7396,15 +7860,20 @@ 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.";
@@ -7413,7 +7882,7 @@ 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;
@@ -7429,8 +7898,13 @@ 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) {
@@ -7620,6 +8094,8 @@ function initComty(options = {}) {
       const next = getPagePath();
       if (next === activePagePath) return;
       activePagePath = next;
+      markup.clear();
+      markup.setMode(null);
       closeBubbles();
       commentTargets.clear();
       reconcileComments([]);
@@ -7656,7 +8132,7 @@ 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)) {
@@ -7803,6 +8279,12 @@ 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 });
@@ -7817,7 +8299,7 @@ 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; }
       }
 
@@ -7825,6 +8307,11 @@ 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");