@comty.io/core 0.1.4 → 0.1.6

package/comty-sdk.js

@@ -3,7 +3,7 @@
 function getComtyStyle() {
     const toolbarSurface = "#2b2d2f";
     const toolbarMuted = "#b8babb";
-    const commentCursor = `<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><path d="M20 2C30 2 38 10 38 20S30 38 20 38H3V28C2 25 2 23 2 20 2 10 10 2 20 2Z" fill="white" stroke="#d6dbe2"/><circle cx="20" cy="20" r="14" fill="#e6e6e6"/><path d="M20 14v12m-6-6h12" fill="none" stroke="#404040" stroke-width="2.5" stroke-linecap="round"/></svg>`;
+    const commentCursor = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 40 40"><path d="M20 2C30 2 38 10 38 20S30 38 20 38H3V28C2 25 2 23 2 20 2 10 10 2 20 2Z" fill="white" stroke="#d6dbe2"/><circle cx="20" cy="20" r="14" fill="#e6e6e6"/><path d="M20 14v12m-6-6h12" fill="none" stroke="#404040" stroke-width="2.5" stroke-linecap="round"/></svg>`;
     const typographyCursor = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32"><rect x="8" y="8" width="23" height="23" rx="7" fill="${toolbarSurface}" stroke="${toolbarMuted}" stroke-width=".75"/><path d="m14 25 5.5-12L25 25m-8.5-4h6M13 25h4m5 0h4" fill="none" stroke="${toolbarMuted}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/><path d="m2 2 2 15 4-5 6-3Z" fill="${toolbarSurface}" stroke="${toolbarMuted}" stroke-width="1.5" stroke-linejoin="round"/></svg>`;
     return `
       #comty-root {
@@ -13,7 +13,7 @@ function getComtyStyle() {
         --comty-muted: var(--comty-toolbar-muted);
         --comty-accent: #55aaf5;
         --comty-error: #ef7676;
-        --comty-outline: var(--comty-toolbar-muted);
+        --comty-outline: var(--comty-accent);
         --comty-comment-focus: var(--comty-toolbar-muted);
         --comty-paper: #fff;
         --comty-ink: #171717;
@@ -60,6 +60,8 @@ function getComtyStyle() {
         --comty-dialog-width: 32rem;
         --comty-dialog-shadow: 0 1.5rem 4rem rgb(0 0 0 / .16);
         --comty-motion-duration: 220ms;
+        --comty-working-dot-size: .25em;
+        --comty-working-dot-gap: .125em;
         --comty-ease-out: cubic-bezier(0.23, 1, 0.32, 1);
         --comty-ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
         position: fixed;
@@ -71,13 +73,73 @@ function getComtyStyle() {
         font-family: var(--comty-font);
         color-scheme: dark;
       }
-
+      #comty-root :is(button, .comty-comment-avatar) { user-select: none; -webkit-user-select: none; }
+      #comty-root .comty-comment-avatar img { -webkit-user-drag: none; }
+      #comty-root .comty-pin .comty-comment-avatar { pointer-events: none; }
+      #comty-root > .comty-agent-panel { position: fixed; right: 1rem; bottom: 5rem; z-index: 2147483647; width: min(22rem, calc(100vw - 2rem)); max-height: min(32rem, calc(100vh - 6rem)); box-sizing: border-box; display: flex; flex-direction: column; overflow: hidden; pointer-events: auto; border: .0625rem solid var(--comty-border); border-radius: 1rem; 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; transform: translateY(0); opacity: 1; transition: transform var(--comty-motion-duration) var(--comty-ease-out), opacity var(--comty-motion-duration) ease; color-scheme: dark; }
+      #comty-root > .comty-agent-panel[data-side="left"] { left: 1rem; right: auto; }
+      #comty-root > .comty-agent-panel[data-closed] { transform: translateY(.5rem); opacity: 0; pointer-events: none; }
+      #comty-root > .comty-agent-panel[hidden] { display: none; }
+      .comty-agent-panel *, .comty-agent-panel *::before { box-sizing: border-box; }
+      .comty-agent-panel-header { display: flex; flex: 0 0 auto; align-items: center; gap: .75rem; padding: .5rem .75rem; border-bottom: .0625rem solid var(--comty-hover-surface); }
+      .comty-agent-brand { display: grid; place-items: center; width: 2.375rem; height: 2.375rem; flex-shrink: 0; border-radius: .6875rem; color: var(--comty-accent); background: var(--comty-hover-surface); }
+      .comty-agent-brand.comty-agent-avatar { width: 2.375rem; height: 2.375rem; border-radius: 0; background: transparent; }
+      .comty-agent-panel svg { display: block; width: 1rem; height: 1rem; flex-shrink: 0; }
+      .comty-agent-brand svg { width: 1.25rem; height: 1.25rem; }
+      .comty-agent-brand.comty-agent-avatar svg { width: 100%; height: 100%; }
+      .comty-agent-answer { display: flex; align-items: flex-start; gap: .5rem; padding: .375rem .5rem .875rem; }
+      .comty-agent-answer .comty-agent-brand { width: 1.5rem; height: 1.5rem; }
+      .comty-agent-answer p { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; color: var(--comty-foreground); }
+      .comty-agent-heading { flex: 1; min-width: 0; }
+      .comty-agent-heading strong { display: block; font-weight: 600; font-size: .875rem; }
+      .comty-agent-panel-content { flex: 1; min-height: 0; overflow-y: auto; overscroll-behavior: contain; scrollbar-width: thin; scrollbar-color: var(--comty-hover-surface) transparent; padding: .375rem .5rem 2rem; }
+      .comty-agent-item { padding: .375rem .25rem; overflow-wrap: anywhere; }
+      .comty-agent-item + .comty-agent-item { border-top: .0625rem solid var(--comty-hover-surface); }
+      .comty-agent-item h3 { margin: 0 0 .25rem; color: var(--comty-foreground); font: 500 .875rem/1.4 ui-sans-serif, system-ui, sans-serif; }
+      .comty-agent-list { display: grid; gap: .125rem; }
+      .comty-agent-row { position: relative; display: flex; align-items: center; gap: .625rem; min-height: 2rem; padding: .25rem .5rem; border-radius: .5rem; color: var(--comty-foreground); }
+      .comty-agent-row:hover { background: var(--comty-hover-surface); }
+      .comty-agent-dot { width: .4375rem; height: .4375rem; flex: 0 0 auto; border-radius: 50%; background: var(--comty-muted); }
+      .comty-working-indicator { display: inline-grid; grid-template-columns: repeat(3, var(--comty-working-dot-size)); gap: var(--comty-working-dot-gap); flex: 0 0 auto; color: var(--comty-foreground); }
+      .comty-working-indicator > i { display: block; width: var(--comty-working-dot-size); height: var(--comty-working-dot-size); border-radius: 50%; background: currentColor; opacity: .25; transition: opacity 150ms linear; }
+      .comty-working-indicator > i[data-active] { opacity: 1; }
+      .comty-agent-dot[data-status="success"] { background: var(--comty-agent-success); }
+      .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-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-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-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; }
+      .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; }
+      .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; }
+      .comty-agent-working { position: fixed; z-index: 1; box-sizing: border-box; border: 2px solid var(--comty-accent); border-radius: 0; pointer-events: none; }
+      .comty-agent-working-badge { position: absolute; left: -.125rem; bottom: 100%; display: inline-flex; align-items: center; gap: .4rem; padding: .25rem .5rem; border-radius: .375rem .375rem 0 0; background: var(--comty-surface); color: var(--comty-foreground); font: 600 .6875rem/1.4 ui-sans-serif, system-ui, sans-serif; white-space: nowrap; }
+      .comty-agent-working[data-badge-below] .comty-agent-working-badge { bottom: auto; top: 100%; border-radius: 0 0 .375rem .375rem; }
       #comty-root { cursor: default; }
       #comty-root::backdrop { background: transparent; pointer-events: none; }
       html.comty-comment-placement,
       html.comty-comment-placement body,
       html.comty-comment-placement body *:not(#comty-root):not(#comty-root *) {
-        cursor: url("data:image/svg+xml,${encodeURIComponent(commentCursor)}") 20 20, crosshair !important;
+        cursor: url("data:image/svg+xml,${encodeURIComponent(commentCursor)}") 16 16, crosshair !important;
       }
       #comty-root > .comty-sidepanel-open, #comty-root > .comty-pin, #comty-root > .comty-bubble, #comty-root > .comty-create-bubble, #comty-root > .comty-popover, #comty-root > .comty-auth-backdrop, #comty-root > .comty-auth-toast { pointer-events: auto; }
       .comty-toolbar {
@@ -144,7 +206,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 { 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 { transition: none !important; animation: none !important; }
       }
 
       .comty-sidepanel {
@@ -326,6 +388,16 @@ function getComtyStyle() {
         white-space: nowrap;
       }
 
+      .comty-anchor-badge {
+        display: inline-block;
+        margin-top: .375rem;
+        padding: .125rem .375rem;
+        border: 1px solid var(--comty-border);
+        border-radius: 999rem;
+        color: var(--comty-muted);
+        font: .6875rem/1.4 sans-serif;
+      }
+
       .comty-pin {
         position: fixed;
         z-index: 2147483645;
@@ -607,6 +679,8 @@ function getComtyStyle() {
         height: 100%;
         object-fit: cover;
       }
+      .comty-comment-avatar.comty-agent-avatar { overflow: visible; border-radius: 0; background: transparent; color: var(--comty-paper); }
+      .comty-comment-avatar.comty-agent-avatar svg { display: block; width: 100%; height: 100%; }
 
       .comty-pin-avatar {
         width: 24px;
@@ -721,12 +795,12 @@ function getComtyStyle() {
       }
 
       .comty-popover-item.comty-popover-item-destructive {
-        color: var(--comty-error);
+        color: var(--comty-agent-error);
       }
 
       .comty-popover-item.comty-popover-item-destructive:hover,
       .comty-popover-item.comty-popover-item-destructive:focus-visible {
-        background: color-mix(in srgb, var(--comty-error) 12%, var(--comty-surface));
+        background: color-mix(in srgb, var(--comty-agent-error) 12%, var(--comty-surface));
         outline: none;
       }
 
@@ -1097,15 +1171,15 @@ function getComtyStyle() {
         margin: 4px 0;
       }
 
-      html.comty-comments-active .comty-pin {
+      html:is(.comty-comments-active, .comty-inspect-annotations) .comty-pin {
         display: grid;
       }
 
-      html.comty-comments-active .comty-pin.comty-filtered-out {
+      html:is(.comty-comments-active, .comty-inspect-annotations) .comty-pin.comty-filtered-out {
         display: none;
       }
 
-      html.comty-comments-active .comty-bubble {
+      html:is(.comty-comments-active, .comty-inspect-annotations) .comty-bubble {
         display: block;
       }
 
@@ -1215,10 +1289,10 @@ function getComtyStyle() {
         position: fixed;
         box-sizing: border-box;
         border: .0625rem solid var(--comty-outline);
-        background: color-mix(in oklch, var(--comty-outline) 8%, transparent);
+        background: transparent;
+        border-radius: 0;
         pointer-events: none;
       }
-      .comty-inspection-box[data-selected] { background: color-mix(in oklch, var(--comty-outline) 5%, transparent); }
       .comty-inspect-spacing { position: fixed; pointer-events: none; background: var(--comty-spacing-color); }
       .comty-inspect-margin { --comty-spacing-color: var(--comty-margin-fill); }
       .comty-inspect-padding { --comty-spacing-color: var(--comty-padding-fill); }
@@ -1272,6 +1346,15 @@ function getComtyStyle() {
         height: 5.75rem;
         border-radius: .75rem;
       }
+      .comty-agent-scope { display: inline-flex; align-items: center; gap: .375rem; color: var(--comty-muted); font: .6875rem/1.25 var(--comty-font); white-space: nowrap; cursor: pointer; pointer-events: auto; opacity: 0; visibility: hidden; }
+      .comty-create-expanded .comty-agent-scope { opacity: 1; visibility: visible; }
+      .comty-agent-scope input { position: absolute; width: 1px; height: 1px; margin: 0; opacity: 0; }
+      .comty-agent-scope-track { position: relative; width: 1.5rem; height: .875rem; flex: 0 0 auto; border-radius: 999rem; background: var(--comty-border); transition: background-color 160ms ease; }
+      .comty-agent-scope-track::after { content: ""; position: absolute; top: .125rem; left: .125rem; width: .625rem; height: .625rem; border-radius: 50%; background: var(--comty-paper); transition: transform 160ms ease; }
+      .comty-agent-scope input:checked + .comty-agent-scope-track { background: var(--comty-accent); }
+      .comty-agent-scope input:checked + .comty-agent-scope-track::after { transform: translateX(.625rem); }
+      .comty-agent-scope input:focus-visible + .comty-agent-scope-track { outline: .125rem solid var(--comty-comment-focus); outline-offset: .125rem; }
+      .comty-agent-thread-error { grid-column: 2; margin: .25rem 0 0; color: var(--comty-agent-error); font: .6875rem/1.3 var(--comty-font); }
 
       .comty-create-bubble.comty-create-has-attachment { height: 7.5rem; }
       .comty-create-bubble.comty-bubble-left { transform-origin: top right; }
@@ -1502,6 +1585,14 @@ function createAnchorMatcher({
       return haystack.toLowerCase().includes(needle.toLowerCase());
     }
 
+    function similarText(a, b) {
+      if (!a || !b) return false;
+      const words = value => new Set(value.toLowerCase().split(/\s+/).filter(Boolean));
+      const left = words(a), right = words(b);
+      const common = [...left].filter(word => right.has(word)).length;
+      return common >= 2 && common / Math.max(left.size, right.size) >= 0.7;
+    }
+
     function scoreFingerprint(el, fingerprint) {
       if (!el || !fingerprint) return 0;
       if (
@@ -1571,6 +1662,8 @@ function createAnchorMatcher({
         score += 15;
       }
 
+      if (text !== fingerprint.text && similarText(text, fingerprint.text)) score += 24;
+
       if (typeof fingerprint.siblingIndex === "number" && el.parentElement) {
         const siblings = [...el.parentElement.children].filter(
           (child) => child.tagName === el.tagName,
@@ -1648,6 +1741,8 @@ function createAnchorMatcher({
         if (ancestorScore > 0) {
           score += Math.min(ancestorScore, 40) * (index === 0 ? 0.5 : 0.2);
         }
+        // Distinguish repeated cards by their section, even when dimensions match.
+        if (index < 3 && ancestors[index].text && getElementTextSignature(parent) === ancestors[index].text) score += 18;
         parent = parent.parentElement;
       }
 
@@ -1662,46 +1757,75 @@ function createAnchorMatcher({
       return score;
     }
 
-    function matchesAnchorIdentity(el, fingerprint) {
+    function matchesAnchorIdentity(el, fingerprint, ignoreDescendantText = false, allowTextChanges = true) {
       if (!el || !fingerprint || el.tagName.toLowerCase() !== fingerprint.tag) return false;
       const attributes = { ariaLabel: "aria-label", name: "name", href: "href", src: "src", alt: "alt", title: "title", role: "role" };
       for (const [key, attribute] of Object.entries(attributes)) {
         if (fingerprint[key] && getAttributeSignature(el, attribute) !== fingerprint[key]) return false;
       }
-      if (fingerprint.ownText && getElementOwnTextSignature(el) !== fingerprint.ownText) return false;
+      if (fingerprint.id && el.id !== fingerprint.id) return false;
+      if (fingerprint.testId && !["data-testid", "data-test", "data-cy"].some(name => getAttributeSignature(el, name) === fingerprint.testId)) return false;
+      const stableIdentity = (fingerprint.id && el.id === fingerprint.id) ||
+        (fingerprint.testId && ["data-testid", "data-test", "data-cy"].some(name => getAttributeSignature(el, name) === fingerprint.testId));
+      if (fingerprint.ownText && getElementOwnTextSignature(el) !== fingerprint.ownText && !(allowTextChanges && stableIdentity)) return false;
       // Container text is useful for matching remounted drawers and dialogs.
-      if (!fingerprint.ownText && fingerprint.text && getElementTextSignature(el) !== fingerprint.text) return false;
+      if (!ignoreDescendantText && !fingerprint.ownText && fingerprint.text && getElementTextSignature(el) !== fingerprint.text && !(allowTextChanges && stableIdentity)) {
+        if (!allowTextChanges || !el.children.length || !similarText(getElementTextSignature(el), fingerprint.text)) return false;
+      }
       return true;
     }
 
     function matchesAnchorContext(el, context) {
       if (!context) return true;
-      if (!matchesAnchorIdentity(el, context.target)) return false;
+      // A unique page landmark keeps its identity when a child is edited.
+      const pageContainer = !context.layer && (context.target?.tag === "main" || context.target?.role === "main") &&
+        [...document.querySelectorAll('main, [role="main"]')].filter(node => !isComtyNode(node)).length === 1;
+      if (!matchesAnchorIdentity(el, context.target, pageContainer)) return false;
       const parentFingerprint = context.ancestors?.[0];
       if (parentFingerprint?.text && parentFingerprint.text !== context.target.text &&
-          !matchesAnchorIdentity(el.parentElement, parentFingerprint)) return false;
+          !matchesAnchorIdentity(el.parentElement, parentFingerprint, pageContainer)) return false;
       const layer = getPresentationLayer(el);
-      if (context.layer && (!layer || !matchesAnchorIdentity(layer, context.layer))) return false;
+      if (context.layer && (!layer || !matchesAnchorIdentity(layer, context.layer, false, false))) return false;
       if (context.version >= 2 && !context.layer && layer) return false;
       return scoreAnchorCandidate(el, context) >= 50;
     }
 
-    function resolveByAnchorContext(context) {
-      if (!context?.target) return null;
+    function resolveAnchor(context, exact = null) {
+      if (!context?.target) return { element: exact, status: exact ? "matched" : "missing" };
       let candidates;
       try {
-        candidates = [...document.body.querySelectorAll(context.target.tag || "*")];
+        candidates = [...document.body.querySelectorAll(context.target.tag || "*")].filter(el => !isComtyNode(el));
       } catch {
-        return null;
+        return { element: null, status: "missing" };
       }
       const matches = candidates
-        .filter(el => !isComtyNode(el) && matchesAnchorContext(el, context))
-        .map(el => ({ el, score: scoreAnchorCandidate(el, context) }))
+        .filter(el => matchesAnchorContext(el, context))
+        .map(el => ({ el, score: scoreAnchorCandidate(el, context) + (context.version === 1 && el === exact ? 16 : 0) }))
         .sort((a, b) => b.score - a.score);
-      if (!matches.length || matches[0].score < 58) return null;
-      // ponytail: ambiguous remounts stay hidden; explicit reattachment can handle identical twins later.
-      if (matches[1] && matches[0].score - matches[1].score < 12) return null;
-      return matches[0].el;
+      if (context.candidateCount > 1) {
+        const peers = candidates.filter(el => matchesAnchorIdentity(el, context.target));
+        if (peers.length !== context.candidateCount) {
+          // A removed identical sibling must not move its comment to the survivor.
+          const distinctive = matches[0] && (context.target.id || context.target.testId);
+          if (!distinctive) return { element: null, status: "uncertain" };
+        }
+      }
+      if (matches[0]?.score >= 58 && (!matches[1] || matches[0].score - matches[1].score >= 12)) {
+        return { element: matches[0].el, status: "matched" };
+      }
+      // A closed/unmounted overlay is not evidence that its contents were deleted.
+      if (context.layer && !candidates.some(el => {
+        const layer = getPresentationLayer(el);
+        return layer && matchesAnchorIdentity(layer, context.layer, false, false);
+      })) return { element: null, status: "hidden" };
+      const plausible = matches.length || candidates.some(el =>
+        (context.target.id && el.id === context.target.id) ||
+        (context.target.text && (getElementTextSignature(el) === context.target.text || similarText(getElementTextSignature(el), context.target.text))));
+      return { element: null, status: plausible ? "uncertain" : "missing" };
+    }
+
+    function resolveByAnchorContext(context) {
+      return resolveAnchor(context).element;
     }
 
     function getViewportBounds() {
@@ -1873,7 +1997,7 @@ function createAnchorMatcher({
       return { clientX, clientY };
     }
 
-    return { matchesAnchorContext, resolveByAnchorContext, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint };
+    return { matchesAnchorContext, resolveAnchor, resolveByAnchorContext, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint };
 }
 
 const captureEngine = (() => { // Generated from html-to-image 1.11.13 by scripts/capture-engine.mjs.
@@ -1901,7 +2025,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 */
-function S(t,e){if(t.match(/^[a-z]+:\/\//i))return t;if(t.match(/^\/\//))return window.location.protocol+t;if(t.match(/^[a-z]+:/i))return t;let r=document.implementation.createHTMLDocument(),n=r.createElement("base"),i=r.createElement("a");return r.head.appendChild(n),r.body.appendChild(i),e&&(n.href=e),i.href=t,i.href}var P=(()=>{let t=0,e=()=>`0000${(Math.random()*36**4<<0).toString(36)}`.slice(-4);return()=>(t+=1,`u${e()}${t}`)})();function u(t){let e=[];for(let r=0,n=t.length;r<n;r++)e.push(t[r]);return e}var f=null;function y(t={}){return f||(t.includeStyleProperties?(f=t.includeStyleProperties,f):(f=u(window.getComputedStyle(document.documentElement)),f))}function w(t){return new Promise((e,r)=>{let n=new Image;n.onload=()=>{n.decode().then(()=>{requestAnimationFrame(()=>e(n))})},n.onerror=r,n.crossOrigin="anonymous",n.decoding="async",n.src=t})}async function D(t){return Promise.resolve().then(()=>new XMLSerializer().serializeToString(t)).then(encodeURIComponent).then(e=>`data:image/svg+xml;charset=utf-8,${e}`)}async function I(t,e,r){let n="http://www.w3.org/2000/svg",i=document.createElementNS(n,"svg"),o=document.createElementNS(n,"foreignObject");return i.setAttribute("width",`${e}`),i.setAttribute("height",`${r}`),i.setAttribute("viewBox",`0 0 ${e} ${r}`),o.setAttribute("width","100%"),o.setAttribute("height","100%"),o.setAttribute("x","0"),o.setAttribute("y","0"),o.setAttribute("externalResourcesRequired","true"),i.appendChild(o),o.appendChild(t),D(i)}var l=(t,e)=>{if(t instanceof e)return!0;let r=Object.getPrototypeOf(t);return r===null?!1:r.constructor.name===e.name||l(r,e)};function U(t){let e=t.getPropertyValue("content");return`${t.cssText} content: '${e.replace(/'|"/g,"")}';`}function V(t,e){return y(e).map(r=>{let n=t.getPropertyValue(r),i=t.getPropertyPriority(r);return`${r}: ${n}${i?" !important":""};`}).join(" ")}function M(t,e,r,n){let i=`.${t}:${e}`,o=r.cssText?U(r):V(r,n);return document.createTextNode(`${i}{${o}}`)}function R(t,e,r,n){let i=window.getComputedStyle(t,r),o=i.getPropertyValue("content");if(o===""||o==="none")return;let a=P();try{e.className=`${e.className} ${a}`}catch{return}let c=document.createElement("style");c.appendChild(M(a,r,i,n)),e.appendChild(c)}function C(t,e,r){R(t,e,":before",r),R(t,e,":after",r)}var T="application/font-woff",$="image/jpeg",F={woff:T,woff2:T,ttf:"application/font-truetype",eot:"application/vnd.ms-fontobject",png:"image/png",jpg:$,jpeg:$,gif:"image/gif",tiff:"image/tiff",svg:"image/svg+xml",webp:"image/webp"};function H(t){let e=/\.([^./]*?)$/g.exec(t);return e?e[1]:""}function m(t){let e=H(t).toLowerCase();return F[e]||""}function O(t){return t.split(/,/)[1]}function p(t){return t.search(/^(data:)/)!==-1}function x(t,e){return`data:${e};base64,${t}`}async function k(t,e,r){let n=await(e?.captureFetch||fetch)(t,e);if(!n.ok)throw new Error(`Resource "${n.url}" not found`);let i=await n.blob();return new Promise((o,a)=>{let c=new FileReader;c.onerror=a,c.onloadend=()=>{try{o(r({res:n,result:c.result}))}catch(s){a(s)}},c.readAsDataURL(i)})}async function h(t,e,r){let n=r.resourceCache||{},i=t;if(n[i]!=null)return n[i];r.cacheBust&&(t+=(/\?/.test(t)?"&":"?")+new Date().getTime());let o;try{let a=await k(t,r.fetchRequestInit,({res:c,result:s})=>(e||(e=c.headers.get("Content-Type")||""),O(s)));o=x(a,e)}catch(a){o=r.imagePlaceholder||"";let c=`Failed to fetch resource: ${t}`;a&&(c=typeof a=="string"?a:a.message),c&&console.warn(c)}return n[i]=o,o}async function q(t){let e=t.toDataURL();return e==="data:,"?t.cloneNode(!1):w(e)}async function _(t,e){if(t.currentSrc){let o=document.createElement("canvas"),a=o.getContext("2d");o.width=t.clientWidth,o.height=t.clientHeight,a?.drawImage(t,0,0,o.width,o.height);let c=o.toDataURL();return w(c)}let r=t.poster,n=m(r),i=await h(r,n,e);return w(i)}async function v(t,e){var r;try{if(!((r=t?.contentDocument)===null||r===void 0)&&r.body)return await b(t.contentDocument.body,e,!0)}catch{}return t.cloneNode(!1)}async function B(t,e){return l(t,HTMLCanvasElement)?q(t).catch(()=>t.cloneNode(!1)):l(t,HTMLVideoElement)?_(t,e).catch(()=>document.createElement("div")):l(t,HTMLIFrameElement)?v(t,e):t.cloneNode(!1)}var G=t=>t.tagName!=null&&t.tagName.toUpperCase()==="SLOT";async function j(t,e,r){var n,i;let o=[];return G(t)&&t.assignedNodes?o=u(t.assignedNodes()):l(t,HTMLIFrameElement)&&(!((n=t.contentDocument)===null||n===void 0)&&n.body)?o=u(t.contentDocument.body.childNodes):o=u(((i=t.shadowRoot)!==null&&i!==void 0?i:t).childNodes),o.length===0||l(t,HTMLVideoElement)||await o.reduce((a,c)=>a.then(()=>b(c,r)).then(s=>{s&&e.appendChild(s)}),Promise.resolve()),e}function z(t,e,r){let n=e.style;if(!n)return;let i=window.getComputedStyle(t);i.cssText?(n.cssText=i.cssText,n.transformOrigin=i.transformOrigin):y(r).forEach(o=>{let a=i.getPropertyValue(o);o==="font-size"&&a.endsWith("px")&&(a=`${parseFloat(a.substring(0,a.length-2))}px`),l(t,HTMLIFrameElement)&&o==="display"&&a==="inline"&&(a="block"),o==="d"&&e.getAttribute("d")&&(a=`path(${e.getAttribute("d")})`),n.setProperty(o,a,i.getPropertyPriority(o))})}function W(t,e){l(t,HTMLTextAreaElement)&&(e.textContent=t.value),l(t,HTMLInputElement)&&e.setAttribute("value",t.value)}function X(t,e){if(l(t,HTMLSelectElement)){let n=Array.from(e.children).find(i=>t.value===i.getAttribute("value"));n&&n.setAttribute("selected","")}}function K(t,e,r){return l(e,Element)&&(z(t,e,r),C(t,e,r),W(t,e),X(t,e)),e}async function J(t,e){let r=t.querySelectorAll?t.querySelectorAll("use"):[];if(r.length===0)return t;let n={};for(let o=0;o<r.length;o++){let a=r[o],c=a.getAttribute("href")||a.getAttribute("xlink:href");if(c){let s=t.querySelector(c),d=document.querySelector(c);!s&&d&&!n[c]&&(n[c]=await b(d,e,!0))}}let i=Object.values(n);if(i.length){let o="http://www.w3.org/1999/xhtml",a=document.createElementNS(o,"svg");a.setAttribute("xmlns",o),a.style.position="absolute",a.style.width="0",a.style.height="0",a.style.overflow="hidden",a.style.display="none";let c=document.createElementNS(o,"defs");a.appendChild(c);for(let s=0;s<i.length;s++)c.appendChild(i[s]);t.appendChild(a)}return t}async function b(t,e,r){if(await e.beforeClone?.(t),!r&&e.filter&&!e.filter(t))return null;let n=e.placeholder?.(t);return n||Promise.resolve(t).then(i=>B(i,e)).then(i=>j(t,i,e)).then(async i=>(await e.beforeClone?.(t),K(t,i,e))).then(i=>e.afterClone?.(t,i)??i).then(i=>J(i,e))}var L=/url\((['"]?)([^'"]+?)\1\)/g,Q=/url\([^)]+\)\s*format\((["']?)([^"']+)\1\)/g,Y=/src:\s*(?:url\([^)]+\)\s*format\([^)]+\)[,;]\s*)+/g;function Z(t){let e=t.replace(/([.*+?^${}()|\[\]\/\\])/g,"\\$1");return new RegExp(`(url\\(['"]?)(${e})(['"]?\\))`,"g")}function N(t){let e=[];return t.replace(L,(r,n,i)=>(e.push(i),r)),e.filter(r=>!p(r)&&!r.startsWith("#"))}async function tt(t,e,r,n,i){try{let o=r?S(e,r):e,a=m(e),c;if(i){let s=await i(o);c=x(s,a)}else c=await h(o,a,n);return t.replace(Z(e),`$1${c}$3`)}catch{}return t}function et(t,{preferredFontFormat:e}){return e?t.replace(Y,r=>{for(;;){let[n,,i]=Q.exec(r)||[];if(!i)return"";if(i===e)return`src: ${n};`}}):t}function rt(t){return t.search(L)!==-1}async function E(t,e,r){if(!rt(t))return t;let n=et(t,r);return N(n).reduce((o,a)=>o.then(c=>tt(c,a,e,r)),Promise.resolve(n))}async function g(t,e,r){var n;let i=(n=e.style)===null||n===void 0?void 0:n.getPropertyValue(t);if(i){let o=await E(i,null,r);return e.style.setProperty(t,o,e.style.getPropertyPriority(t)),!0}return!1}async function nt(t,e){await g("background",t,e)||await g("background-image",t,e),await g("mask",t,e)||await g("-webkit-mask",t,e)||await g("mask-image",t,e)||await g("-webkit-mask-image",t,e)}async function it(t,e){let r=l(t,HTMLImageElement);if(!(r&&!p(t.src))&&!(l(t,SVGImageElement)&&!p(t.href.baseVal)))return;let n=r?t.src:t.href.baseVal,i=await h(n,m(n),e);await new Promise((o,a)=>{t.onload=o,t.onerror=e.onImageErrorHandler?(...s)=>{try{o(e.onImageErrorHandler(...s))}catch(d){a(d)}}:a;let c=t;c.decode&&(c.decode=o),c.loading==="lazy"&&(c.loading="eager"),r?(t.srcset="",t.src=i):t.href.baseVal=i})}async function ot(t,e){let n=u(t.childNodes).map(i=>A(i,e));await Promise.all(n).then(()=>t)}async function A(t,e){await e.beforeClone?.(t),l(t,Element)&&(await nt(t,e),await it(t,e),await ot(t,e))} return {cloneNode:b,embedImages:A,embedResources:E,nodeToDataURL:I}; })();
+function S(t,e){if(t.match(/^[a-z]+:\/\//i))return t;if(t.match(/^\/\//))return window.location.protocol+t;if(t.match(/^[a-z]+:/i))return t;let r=document.implementation.createHTMLDocument(),n=r.createElement("base"),i=r.createElement("a");return r.head.appendChild(n),r.body.appendChild(i),e&&(n.href=e),i.href=t,i.href}var P=(()=>{let t=0,e=()=>`0000${(Math.random()*36**4<<0).toString(36)}`.slice(-4);return()=>(t+=1,`u${e()}${t}`)})();function u(t){let e=[];for(let r=0,n=t.length;r<n;r++)e.push(t[r]);return e}var f=null;function y(t={}){return f||(t.includeStyleProperties?(f=t.includeStyleProperties,f):(f=u(window.getComputedStyle(document.documentElement)),f))}function w(t){return new Promise((e,r)=>{let n=new Image;n.onload=()=>{n.decode().then(()=>{requestAnimationFrame(()=>e(n))})},n.onerror=r,n.crossOrigin="anonymous",n.decoding="async",n.src=t})}async function I(t){return Promise.resolve().then(()=>new XMLSerializer().serializeToString(t)).then(encodeURIComponent).then(e=>`data:image/svg+xml;charset=utf-8,${e}`)}async function U(t,e,r){let n="http://www.w3.org/2000/svg",i=document.createElementNS(n,"svg"),o=document.createElementNS(n,"foreignObject");return i.setAttribute("width",`${e}`),i.setAttribute("height",`${r}`),i.setAttribute("viewBox",`0 0 ${e} ${r}`),o.setAttribute("width","100%"),o.setAttribute("height","100%"),o.setAttribute("x","0"),o.setAttribute("y","0"),o.setAttribute("externalResourcesRequired","true"),i.appendChild(o),o.appendChild(t),I(i)}var l=(t,e)=>{if(t instanceof e)return!0;let r=Object.getPrototypeOf(t);return r===null?!1:r.constructor.name===e.name||l(r,e)};function V(t){let e=t.getPropertyValue("content");return`${t.cssText} content: '${e.replace(/'|"/g,"")}';`}function M(t,e){return y(e).map(r=>{let n=t.getPropertyValue(r),i=t.getPropertyPriority(r);return`${r}: ${n}${i?" !important":""};`}).join(" ")}function F(t,e,r,n){let i=`.${t}:${e}`,o=r.cssText?V(r):M(r,n);return document.createTextNode(`${i}{${o}}`)}function R(t,e,r,n){let i=window.getComputedStyle(t,r),o=i.getPropertyValue("content");if(o===""||o==="none")return;let a=P();try{e.className=`${e.className} ${a}`}catch{return}let c=document.createElement("style");c.appendChild(F(a,r,i,n)),e.appendChild(c)}function C(t,e,r){R(t,e,":before",r),R(t,e,":after",r)}var T="application/font-woff",$="image/jpeg",H={woff:T,woff2:T,ttf:"application/font-truetype",eot:"application/vnd.ms-fontobject",png:"image/png",jpg:$,jpeg:$,gif:"image/gif",tiff:"image/tiff",svg:"image/svg+xml",webp:"image/webp"};function O(t){let e=/\.([^./]*?)$/g.exec(t);return e?e[1]:""}function m(t){let e=O(t).toLowerCase();return H[e]||""}function k(t){return t.split(/,/)[1]}function p(t){return t.search(/^(data:)/)!==-1}function x(t,e){return`data:${e};base64,${t}`}async function q(t,e,r){let n=await(e?.captureFetch||fetch)(t,e);if(!n.ok)throw new Error(`Resource "${n.url}" not found`);let i=await n.blob();return new Promise((o,a)=>{let c=new FileReader;c.onerror=a,c.onloadend=()=>{try{o(r({res:n,result:c.result}))}catch(s){a(s)}},c.readAsDataURL(i)})}async function h(t,e,r){let n=r.resourceCache||{},i=t;if(n[i]!=null)return n[i];r.cacheBust&&(t+=(/\?/.test(t)?"&":"?")+new Date().getTime());let o;try{let a=await q(t,r.fetchRequestInit,({res:c,result:s})=>(e||(e=c.headers.get("Content-Type")||""),k(s)));o=x(a,e)}catch(a){o=r.imagePlaceholder||"";let c=`Failed to fetch resource: ${t}`;a&&(c=typeof a=="string"?a:a.message),c&&console.warn(c)}return n[i]=o,o}async function _(t){let e=t.toDataURL();return e==="data:,"?t.cloneNode(!1):w(e)}async function v(t,e){if(t.currentSrc){let o=document.createElement("canvas"),a=o.getContext("2d");o.width=t.clientWidth,o.height=t.clientHeight,a?.drawImage(t,0,0,o.width,o.height);let c=o.toDataURL();return w(c)}let r=t.poster,n=m(r),i=await h(r,n,e);return w(i)}async function B(t,e){var r;try{if(!((r=t?.contentDocument)===null||r===void 0)&&r.body)return await b(t.contentDocument.body,e,!0)}catch{}return t.cloneNode(!1)}async function G(t,e){return l(t,HTMLCanvasElement)?_(t).catch(()=>t.cloneNode(!1)):l(t,HTMLVideoElement)?v(t,e).catch(()=>document.createElement("div")):l(t,HTMLIFrameElement)?B(t,e):t.cloneNode(!1)}var j=t=>t.tagName!=null&&t.tagName.toUpperCase()==="SLOT";async function z(t,e,r){var n,i;let o=[];return j(t)&&t.assignedNodes?o=u(t.assignedNodes()):l(t,HTMLIFrameElement)&&(!((n=t.contentDocument)===null||n===void 0)&&n.body)?o=u(t.contentDocument.body.childNodes):o=u(((i=t.shadowRoot)!==null&&i!==void 0?i:t).childNodes),o.length===0||l(t,HTMLVideoElement)||await o.reduce((a,c)=>a.then(()=>b(c,r)).then(s=>{s&&e.appendChild(s)}),Promise.resolve()),e}function W(t,e,r){let n=e.style;if(!n)return;let i=window.getComputedStyle(t);i.cssText?(n.cssText=i.cssText,n.transformOrigin=i.transformOrigin):y(r).forEach(o=>{let a=i.getPropertyValue(o);o==="font-size"&&a.endsWith("px")&&(a=`${parseFloat(a.substring(0,a.length-2))}px`),l(t,HTMLIFrameElement)&&o==="display"&&a==="inline"&&(a="block"),o==="d"&&e.getAttribute("d")&&(a=`path(${e.getAttribute("d")})`),n.setProperty(o,a,i.getPropertyPriority(o))})}function X(t,e){l(t,HTMLTextAreaElement)&&(e.textContent=t.value),l(t,HTMLInputElement)&&e.setAttribute("value",t.value)}function K(t,e){if(l(t,HTMLSelectElement)){let n=Array.from(e.children).find(i=>t.value===i.getAttribute("value"));n&&n.setAttribute("selected","")}}function J(t,e,r){return l(e,Element)&&(W(t,e,r),C(t,e,r),X(t,e),K(t,e)),e}async function Q(t,e){let r=t.querySelectorAll?t.querySelectorAll("use"):[];if(r.length===0)return t;let n={};for(let o=0;o<r.length;o++){let a=r[o],c=a.getAttribute("href")||a.getAttribute("xlink:href");if(c){let s=t.querySelector(c),d=document.querySelector(c);!s&&d&&!n[c]&&(n[c]=await b(d,e,!0))}}let i=Object.values(n);if(i.length){let o="http://www.w3.org/1999/xhtml",a=document.createElementNS(o,"svg");a.setAttribute("xmlns",o),a.style.position="absolute",a.style.width="0",a.style.height="0",a.style.overflow="hidden",a.style.display="none";let c=document.createElementNS(o,"defs");a.appendChild(c);for(let s=0;s<i.length;s++)c.appendChild(i[s]);t.appendChild(a)}return t}async function b(t,e,r){if(await e.beforeClone?.(t),!r&&e.filter&&!e.filter(t))return null;let n=e.placeholder?.(t);return n||Promise.resolve(t).then(i=>G(i,e)).then(i=>z(t,i,e)).then(async i=>(await e.beforeClone?.(t),J(t,i,e))).then(i=>e.afterClone?.(t,i)??i).then(i=>Q(i,e))}var A=/url\((['"]?)([^'"]+?)\1\)/g,L=/url\([^)]+\)\s*format\((["']?)([^"']+)\1\)/g,Y=/src:\s*(?:url\([^)]+\)\s*format\([^)]+\)[,;]\s*)+/g;function Z(t){let e=t.replace(/([.*+?^${}()|\[\]\/\\])/g,"\\$1");return new RegExp(`(url\\(['"]?)(${e})(['"]?\\))`,"g")}function N(t){let e=[];return t.replace(A,(r,n,i)=>(e.push(i),r)),e.filter(r=>!p(r)&&!r.startsWith("#"))}async function tt(t,e,r,n,i){try{let o=r?S(e,r):e,a=m(e),c;if(i){let s=await i(o);c=x(s,a)}else c=await h(o,a,n);return t.replace(Z(e),`$1${c}$3`)}catch{}return t}function et(t,{preferredFontFormat:e}){return e?t.replace(Y,r=>{for(L.lastIndex=0;;){let[n,,i]=L.exec(r)||[];if(!i)return"";if(i===e)return`src: ${n};`}}):t}function rt(t){return t.search(A)!==-1}async function E(t,e,r){if(!rt(t))return t;let n=et(t,r);return N(n).reduce((o,a)=>o.then(c=>tt(c,a,e,r)),Promise.resolve(n))}async function g(t,e,r){var n;let i=(n=e.style)===null||n===void 0?void 0:n.getPropertyValue(t);if(i){let o=await E(i,null,r);return e.style.setProperty(t,o,e.style.getPropertyPriority(t)),!0}return!1}async function nt(t,e){await g("background",t,e)||await g("background-image",t,e),await g("mask",t,e)||await g("-webkit-mask",t,e)||await g("mask-image",t,e)||await g("-webkit-mask-image",t,e)}async function it(t,e){let r=l(t,HTMLImageElement);if(!(r&&!p(t.src))&&!(l(t,SVGImageElement)&&!p(t.href.baseVal)))return;let n=r?t.src:t.href.baseVal,i=await h(n,m(n),e);await new Promise((o,a)=>{t.onload=o,t.onerror=e.onImageErrorHandler?(...s)=>{try{o(e.onImageErrorHandler(...s))}catch(d){a(d)}}:a;let c=t;c.decode&&(c.decode=o),c.loading==="lazy"&&(c.loading="eager"),r?(t.srcset="",t.src=i):t.href.baseVal=i})}async function ot(t,e){let n=u(t.childNodes).map(i=>D(i,e));await Promise.all(n).then(()=>t)}async function D(t,e){await e.beforeClone?.(t),l(t,Element)&&(await nt(t,e),await it(t,e),await ot(t,e))} return {cloneNode:b,embedImages:D,embedResources:E,nodeToDataURL:U}; })();
 // Fetches belong to one capture. Never forward SDK credentials to a resource host.
 function createCaptureResources({ apiUrl, projectKey, getHeaders, signal }) {
   const cache = new Map();
@@ -2221,7 +2345,12 @@ function createScreenshotCapture({ apiUrl, projectKey, getHeaders = () => ({}) }
       await untilAborted(captureEngine.embedImages(stage, options));
       checkContext();
       await yieldCapture();
-      const svg = await captureEngine.nodeToDataURL(stage, context.width, context.height);
+      // Transparent page backgrounds reveal the browser canvas, not the image viewer.
+      const viewport = document.createElement("div");
+      viewport.style.backgroundColor = "Canvas";
+      viewport.style.colorScheme = rootStyle.colorScheme;
+      viewport.append(stage);
+      const svg = await captureEngine.nodeToDataURL(viewport, context.width, context.height);
       const image = new Image();
       image.src = svg;
       await untilAborted(image.decode());
@@ -2236,9 +2365,6 @@ function createScreenshotCapture({ apiUrl, projectKey, getHeaders = () => ({}) }
       let blob = await untilAborted(new Promise(resolve => canvas.toBlob(resolve, "image/png")));
       if (!blob) throw new Error("Screenshot encoding failed");
       if (blob.size > 2800000) {
-        ctx.globalCompositeOperation = "destination-over";
-        ctx.fillStyle = getComputedStyle(document.documentElement).getPropertyValue("background-color");
-        ctx.fillRect(0, 0, context.width, context.height);
         blob = await untilAborted(new Promise(resolve => canvas.toBlob(resolve, "image/jpeg", 0.9)));
         if (!blob) throw new Error("Screenshot encoding failed");
       }
@@ -2369,7 +2495,7 @@ function createCommentThread(context) {
     renderSidepanelComments, applyStatusFilters, createThreadItem, renderCommentContent,
     isOwnCommentEntry, updateCommentContent, deleteSdkComment, getCommentId,
     updateReplyContent, deleteSdkReply, createCommentAvatar, getSdkHeaders,
-    showAuthPrompt,
+    showAuthPrompt, startThreadAgent,
   } = context;
 
   return function openCommentThread(
@@ -2432,16 +2558,16 @@ function createCommentThread(context) {
       };
 
       const saveStatus = async (nextStatus, control) => {
-        if (!context.canManage) return false;
+        if (!context.canManage || comment.local_agent) return false;
         control.disabled = true;
         const savedStatus = await updateCommentStatus(comment, nextStatus);
         control.disabled = false;
         if (!savedStatus) return false;
 
         const savedStatusOption = getCommentStatus(savedStatus);
-        pin.dataset.status = savedStatusOption.value;
-        applyStatusDot(pinStatusDot, savedStatus);
-        pin.setAttribute(
+        if (pin) pin.dataset.status = savedStatusOption.value;
+        if (pinStatusDot) applyStatusDot(pinStatusDot, savedStatus);
+        pin?.setAttribute(
           "aria-label",
           `Afficher le commentaire, statut ${savedStatusOption.label}`,
         );
@@ -2457,7 +2583,7 @@ function createCommentThread(context) {
         return true;
       };
 
-      statusMenuButton.disabled = !context.canManage;
+      statusMenuButton.disabled = comment.local_agent || !context.canManage;
       statusMenuButton.onclick = (event) => {
         event.stopPropagation();
         const existingPopover = document.querySelector(
@@ -2606,7 +2732,7 @@ function createCommentThread(context) {
         );
       };
 
-      const mainItem = createThreadItem(comment, { showMore: isOwnCommentEntry(comment) });
+      const mainItem = createThreadItem(comment, { showMore: !comment.local_agent && isOwnCommentEntry(comment) });
 
       const startEditingEntry = (entry, item, persist) => {
         if (!isOwnCommentEntry(entry)) return;
@@ -2702,7 +2828,7 @@ function createCommentThread(context) {
                   getCommentId(cachedComment) !== getCommentId(comment),
               );
               placedPins.delete(getCommentId(comment));
-              pin.remove();
+              pin?.remove();
               closeBubbles();
               renderSidepanelComments();
               applyStatusFilters();
@@ -2749,11 +2875,19 @@ function createCommentThread(context) {
       };
       replies.forEach(appendReply);
       thread.appendChild(threadList);
+      bubble.addEventListener('comty-agent-reply', (event) => {
+        const reply = event.detail;
+        if (!reply || replies.some(item => item.id === reply.id)) return;
+        replies.push(reply);
+        comment.replies = replies;
+        appendReply(reply);
+        threadList.scrollTop = threadList.scrollHeight;
+      });
 
       const replyForm = document.createElement("div");
       replyForm.className = "comty-reply-form";
 
-      if (context.canWrite) {
+      if (context.canWrite && !comment.local_agent) {
         replyForm.appendChild(createCommentAvatar(context.currentUser || { name: "You" }));
         const replyField = document.createElement("div");
         replyField.className = "comty-reply-field";
@@ -2796,6 +2930,18 @@ function createCommentThread(context) {
               appendReply(data.reply);
               replyInput.value = "";
               syncReplySize();
+              if (/(^|\s)@agent\b/i.test(content)) {
+                try {
+                  await startThreadAgent(comment, replies, content);
+                } catch (error) {
+                  const notice = document.createElement('p');
+                  notice.className = 'comty-agent-thread-error';
+                  notice.setAttribute('role', 'alert');
+                  notice.textContent = `Agent could not start: ${error.message}`;
+                  replyForm.querySelector('.comty-agent-thread-error')?.remove();
+                  replyForm.appendChild(notice);
+                }
+              }
               requestAnimationFrame(() => {
                 threadList.scrollTop = threadList.scrollHeight;
               });
@@ -2843,7 +2989,7 @@ function createCommentThread(context) {
         replyField.appendChild(replyInput);
         replyField.appendChild(replyButton);
         replyForm.appendChild(replyField);
-      } else {
+      } else if (!comment.local_agent) {
         replyForm.classList.add("comty-reply-form-guest");
         const signInButton = document.createElement("button");
         signInButton.className = "comty-sign-in-reply";
@@ -2856,7 +3002,7 @@ function createCommentThread(context) {
         replyForm.appendChild(signInButton);
       }
 
-      thread.appendChild(replyForm);
+      if (!comment.local_agent) thread.appendChild(replyForm);
       bubble.appendChild(thread);
       root.appendChild(bubble);
 
@@ -3093,7 +3239,17 @@ const instanceKey = Symbol.for("comty.sdk.instance");
 /** Initialize once per document; safe to import and call during server rendering. */
 function initComty(options = {}) {
   if (typeof window === "undefined" || typeof document === "undefined") return Promise.resolve();
-  const projectKey = options.projectKey;
+  const isLocalSite = ["localhost", "127.0.0.1", "[::1]"].includes(window.location.hostname);
+  const agent = options.agent;
+  if (agent && (!isLocalSite || typeof agent.token !== "string" || !/^[a-f0-9]{64}$/.test(agent.token))) {
+    return Promise.reject(new TypeError("Comty: invalid local companion configuration"));
+  }
+  if (agent) {
+    try {
+      if (new URL(agent.url).origin !== window.location.origin) throw new Error();
+    } 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";
   if (typeof projectKey !== "string" || !projectKey.trim()) {
     return Promise.reject(new TypeError("Comty: projectKey is required"));
@@ -3105,12 +3261,14 @@ function initComty(options = {}) {
   if (!["http:", "https:"].includes(parsedApi.protocol)) {
     return Promise.reject(new TypeError("Comty: apiUrl must be an absolute HTTP(S) URL"));
   }
-  const configuration = JSON.stringify([projectKey, apiUrl]);
+  const configuration = JSON.stringify([projectKey, apiUrl, agent || null]);
   const existing = window[instanceKey];
   if (existing) {
     return existing.configuration === configuration ? existing.ready
       : Promise.reject(new Error("Comty: already initialized with different options"));
   }
+  const agentBridgeUrl = agent?.url;
+  const localOnly = Boolean(agent && !options.projectKey);
   const ready = new Promise((resolve, reject) => {
     const mount = () => {
       try { resolve(mountComty()); } catch (error) { reject(error); }
@@ -3124,10 +3282,22 @@ function initComty(options = {}) {
 
   function mountComty() {
     let projectId = null;
+    let localTasks = [];
+    const deliveringAgentReplies = new Set();
+    let localApprovals = [];
+    const seenAgentApprovals = new Set();
+    const seenFailedAgentTasks = new Set();
+    let agentPanelOpen = false;
+    let agentPanelSignature = "";
+    let agentPanelTransition = 0;
+    let agentConnectionError = "";
+    let agentActionError = "";
+    const agentPendingActions = new Set();
     const session = {
       mode: "off",
-      get comments() { return this.mode === "browse" || this.mode === "edit"; },
-      get edit() { return this.mode === "edit"; },
+      get comments() { return this.mode === "browse" || this.mode === "edit" || this.mode === "agent"; },
+      get edit() { return this.mode === "edit" || this.mode === "agent"; },
+      get agent() { return this.mode === "agent"; },
       get inspect() { return this.mode === "inspect"; },
     };
     const selectedStatusFilters = new Set();
@@ -3151,9 +3321,10 @@ function initComty(options = {}) {
     const authReturnStorageKey = `comty:${projectKey}:auth-return`;
     let sdkToken = "";
     const activeHoverCommentIds = new Set();
-    /** @type {null | 'edit' | 'browse'} */
+    /** @type {null | 'edit' | 'browse' | 'agent'} */
     let sessionEntry = null;
     const placedPins = new Map();
+    const workingOutlines = new Map();
     const placementDiagnostics = new Map();
     let inspectedElement = null;
     let selectedElement = null;
@@ -3167,8 +3338,8 @@ function initComty(options = {}) {
     const commentTargets = new Map();
 
     const {
-      matchesAnchorContext, resolveByAnchorContext,
-      isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint,
+      matchesAnchorContext,
+      resolveAnchor, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint,
     } = createAnchorMatcher({
       getElementTextSignature,
       getElementOwnTextSignature,
@@ -3246,10 +3417,20 @@ function initComty(options = {}) {
     const inspectorBtn = toolButton("Inspect · Shift I", '<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"/><path d="m9 9 8 4-4 1-1 4Z"/>', () => setSession("inspect"));
     const btn = toolButton("Comment · Shift C", '<path d="M21 11.5a8.4 8.4 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.4 8.4 0 0 1-3.8-.9L3 21l1.9-5.7a8.4 8.4 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6A8.4 8.4 0 0 1 12.5 3h.5a8.5 8.5 0 0 1 8 8v.5Z"/>', () => {
       if (!canWrite) showAuthPrompt();
-      else if (session.inspect || !isSessionActive()) startEditSession();
+      else if (session.agent || session.inspect || !isSessionActive()) startEditSession();
       else if (!session.edit) setSession("edit", { entry: sessionEntry });
     });
     btn.id = "comty-toggle";
+    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) {
+            if (localTasks.some(task => task.status === 'in_review' || (!task.thread_comment_id && task.status === 'done')) || localApprovals.length) {
+              agentPanelOpen = true;
+              renderAgentPanel();
+            }
+          } else startAgentSession();
+        })
+      : null;
     const divider = document.createElement("span");
     divider.className = "comty-tool-divider";
     toolbar.appendChild(divider);
@@ -3259,7 +3440,7 @@ function initComty(options = {}) {
     const primaryTools = document.createElement("div");
     primaryTools.className = "comty-tool-primary";
     toolbar.insertBefore(primaryTools, browseBtn);
-    for (const button of [browseBtn, inspectorBtn, btn]) primaryTools.appendChild(button);
+    for (const button of [browseBtn, inspectorBtn, btn, agentBtn].filter(Boolean)) primaryTools.appendChild(button);
     const inspectorTools = document.createElement("div");
     inspectorTools.className = "comty-tool-context";
     inspectorTools.hidden = true;
@@ -4112,6 +4293,50 @@ function initComty(options = {}) {
     let toolbarMotionFrame = 0;
     let toolbarAnimations = [];
     const reducedMotion = matchMedia("(prefers-reduced-motion: reduce)");
+    let workingIndicatorTimer = 0;
+    function scheduleWorkingIndicators() {
+      if (workingIndicatorTimer || reducedMotion.matches || document.hidden) return;
+      workingIndicatorTimer = setTimeout(() => {
+        workingIndicatorTimer = 0;
+        if (!root.isConnected) return;
+        const indicators = root.querySelectorAll('.comty-working-indicator');
+        if (!indicators.length) return;
+        for (const indicator of indicators) {
+          const previous = Number(indicator.dataset.activeDots.split(',')[0]);
+          const first = (previous + 1 + Math.floor(Math.random() * 8)) % 9;
+          const second = (first + 1 + Math.floor(Math.random() * 8)) % 9;
+          indicator.dataset.activeDots = `${first},${second}`;
+          [...indicator.children].forEach((dot, index) => dot.toggleAttribute('data-active', index === first || index === second));
+        }
+        scheduleWorkingIndicators();
+      }, 600);
+    }
+    function createWorkingIndicator() {
+      const indicator = document.createElement('span');
+      indicator.className = 'comty-working-indicator';
+      indicator.setAttribute('aria-hidden', 'true');
+      indicator.dataset.activeDots = '3,5';
+      for (let index = 0; index < 9; index++) {
+        const dot = document.createElement('i');
+        dot.toggleAttribute('data-active', index === 3 || index === 5);
+        indicator.appendChild(dot);
+      }
+      scheduleWorkingIndicators();
+      return indicator;
+    }
+    function resetWorkingIndicators() {
+      clearTimeout(workingIndicatorTimer);
+      workingIndicatorTimer = 0;
+      if (reducedMotion.matches) {
+        for (const indicator of root.querySelectorAll('.comty-working-indicator')) {
+          indicator.dataset.activeDots = '3,5';
+          [...indicator.children].forEach((dot, index) => dot.toggleAttribute('data-active', index === 3 || index === 5));
+        }
+      }
+      if (root.querySelector('.comty-working-indicator')) scheduleWorkingIndicators();
+    }
+    reducedMotion.addEventListener('change', resetWorkingIndicators);
+    document.addEventListener('visibilitychange', resetWorkingIndicators);
     const clampToolbar = (value, size, viewport) => Math.max(8, Math.min(value, viewport - size - 8));
     function rememberToolbarPosition(left, top) {
       const width = toolbar.offsetWidth, height = toolbar.offsetHeight;
@@ -4224,7 +4449,7 @@ function initComty(options = {}) {
 
     function prepareToolbarMotion() {
       if (toolbarMotionFrame) return;
-      const nodes = [toolbarSurface, dragHandle, primaryTools, commentTools, inspectorTools].filter(Boolean);
+      const nodes = [toolbarSurface, dragHandle, primaryTools, commentTools, inspectorTools];
       // Move each group's background with its icons, including when interrupted.
       const before = new Map(nodes.filter(node => !node.hidden).map(node => [node, {
         rect: node.getBoundingClientRect(), opacity: getComputedStyle(node).opacity,
@@ -4448,7 +4673,8 @@ function initComty(options = {}) {
         selectedElement = null;
         sessionEntry = null;
         session.mode = "off";
-        document.documentElement.classList.remove("comty-comments-active", "comty-comment-placement");
+        syncPlacementCursor();
+        document.documentElement.classList.remove("comty-comments-active", "comty-inspect-annotations");
         hideInspector();
         setSidepanelOpen(false);
         closeBubbles();
@@ -4462,25 +4688,29 @@ function initComty(options = {}) {
       if (mode === "off") return;
       if (mode === "inspect") {
         session.mode = "inspect";
+        document.documentElement.classList.add("comty-inspect-annotations");
         syncToolbar();
+        renderCachedComments();
         ensureLiveTracking();
         return;
       }
 
-      if (session.edit && mode === "browse") {
+      if ((session.edit && mode === "browse") || (session.agent && mode === "edit")) {
         closeBubbles();
       }
       const hadComments = session.comments;
       session.mode = mode;
       sessionEntry = entry;
+      document.documentElement.classList.remove("comty-inspect-annotations");
       document.documentElement.classList.toggle("comty-comments-active", session.comments);
-      document.documentElement.classList.toggle("comty-comment-placement", session.edit);
+      syncPlacementCursor();
       if (session.edit) {
         setMotionEnabled(false);
         selectedElement = null;
       } else {
         hideInspector();
       }
+      if (session.agent && sidepanelOpen) setSidepanelOpen(false);
       syncToolbar();
       ensureLiveTracking();
       if (renderComments || !hadComments) renderCachedComments();
@@ -4493,6 +4723,10 @@ 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.");
+        return;
+      }
       const guestAllowed = allowGuestComments;
       document.querySelector(".comty-auth-backdrop")?.remove();
       const opener = document.activeElement;
@@ -4614,14 +4848,16 @@ function initComty(options = {}) {
     }
 
     function syncToolbar() {
-      if (commentTools.hidden !== session.inspect || inspectorTools.hidden !== !session.inspect) prepareToolbarMotion();
+      if (commentTools.hidden !== (session.inspect || session.agent) || inspectorTools.hidden !== !session.inspect) prepareToolbarMotion();
       root.classList.toggle("comty-active", session.comments || session.edit || sidepanelOpen || session.inspect);
       browseBtn.setAttribute("aria-pressed", String(!session.edit && !session.inspect));
       inspectorBtn.setAttribute("aria-pressed", String(session.inspect));
-      btn.setAttribute("aria-pressed", String(session.edit));
-      commentTools.hidden = session.inspect;
+      btn.setAttribute("aria-pressed", String(session.edit && !session.agent));
+      agentBtn?.setAttribute("aria-pressed", String(session.edit && session.agent));
+      commentTools.hidden = session.inspect || session.agent;
       inspectorTools.hidden = !session.inspect;
       syncInspectorTools();
+      renderAgentPanel();
     }
 
     const inspectionLayer = document.createElement("div");
@@ -5084,6 +5320,13 @@ function initComty(options = {}) {
       setSession("edit", { renderComments: true });
     }
 
+    function startAgentSession() {
+      if (!isLocalSite) return;
+      if (session.agent) return;
+      closeBubbles();
+      setSession("agent", { renderComments: true });
+    }
+
     function toggleSidepanel() {
       if (sidepanelOpen) {
         setSidepanelOpen(false);
@@ -5107,7 +5350,7 @@ function initComty(options = {}) {
         showAuthPrompt();
         return;
       }
-      if (session.inspect || !isSessionActive()) {
+      if (session.agent || session.inspect || !isSessionActive()) {
         startEditSession();
         return;
       }
@@ -5395,6 +5638,24 @@ function initComty(options = {}) {
         ancestors,
         layer: layer ? getElementFingerprint(layer) : null,
       };
+      // React exposes this in development builds. Keep it as a hint: the coding
+      // agent must confirm the component and variant in source before editing.
+      const fiberKey = Object.keys(el).find(key => key.startsWith('__reactFiber$'));
+      let fiber = fiberKey ? el[fiberKey] : null;
+      const components = [];
+      while (fiber && components.length < 8) {
+        const component = fiber.type;
+        const name = component?.displayName || component?.name;
+        if (name && typeof name === 'string') {
+          const props = fiber.memoizedProps || {};
+          const variants = Object.fromEntries(['variant', 'size', 'tone', 'appearance'].filter(key =>
+            ['string', 'number', 'boolean'].includes(typeof props[key])).map(key => [key, props[key]]));
+          const source = fiber._debugSource;
+          components.push({ name, variants, ...(source?.fileName ? { file: source.fileName, line: source.lineNumber } : {}) });
+        }
+        fiber = fiber.return;
+      }
+      if (components.length) context.components = components;
       context.candidateCount = [...document.querySelectorAll(context.target.tag)]
         .filter(candidate => !isComtyNode(candidate) && matchesAnchorContext(candidate, context)).length;
       return context;
@@ -5423,6 +5684,11 @@ function initComty(options = {}) {
       };
     }
 
+    function getPagePath() {
+      const { pathname, hash } = window.location;
+      return pathname + (hash.startsWith("#/") || hash.startsWith("#!/") ? hash : "");
+    }
+
     function resolveBySelector(selector) {
       if (!selector) return null;
       try {
@@ -5444,17 +5710,9 @@ function initComty(options = {}) {
       }
       const context = parseAnchorContext(comment);
       const exact = resolveBySelector(comment.selector || "body");
-      if (context?.candidateCount > 1) {
-        const count = [...document.querySelectorAll("*")].filter(candidate => candidate.tagName.toLowerCase() === context.target.tag)
-          .filter(candidate => !isComtyNode(candidate) && matchesAnchorContext(candidate, context)).length;
-        if (count !== context.candidateCount) {
-          commentTargets.set(key, { element: null, signature, revision: anchorRevision });
-          return null;
-        }
-      }
-      let element = exact && matchesAnchorContext(exact, context) ? getAnchorElement(exact) : null;
-      if (!element) element = resolveByAnchorContext(context);
-      commentTargets.set(key, { element, signature, revision: anchorRevision });
+      const resolution = resolveAnchor(context, exact);
+      const element = resolution.element ? getAnchorElement(resolution.element) : null;
+      commentTargets.set(key, { ...resolution, element, signature, revision: anchorRevision });
       return element;
     }
 
@@ -5525,9 +5783,14 @@ function initComty(options = {}) {
       return { deviceType: "desktop", deviceLabel: "Desktop" };
     }
 
+    function syncPlacementCursor() {
+      document.documentElement.classList.toggle("comty-comment-placement", session.edit && !draftAnchor);
+    }
+
     function closeBubbles() {
       const hadDraft = Boolean(draftAnchor);
       draftAnchor = null;
+      syncPlacementCursor();
       activeHoverCommentIds.clear();
       if (!session.edit || hadDraft) hideInspector();
       document
@@ -5572,7 +5835,7 @@ function initComty(options = {}) {
         pending: commentId.startsWith("pending-"),
         project_id: projectId,
         domain: payload.host || window.location.host,
-        page_path: payload.pagePath || window.location.pathname,
+        page_path: payload.pagePath || getPagePath(),
         selector: payload.selector || "body",
         rel_x: payload.relX,
         rel_y: payload.relY,
@@ -5597,7 +5860,7 @@ function initComty(options = {}) {
         replies: [],
       };
 
-      cachedPagePath = window.location.pathname;
+      cachedPagePath = getPagePath();
       cachedComments = [
         ...cachedComments.filter(
           (cached) => getCommentId(cached) !== commentId,
@@ -5610,6 +5873,7 @@ function initComty(options = {}) {
     }
 
     function getCommentAuthorName(comment) {
+      if (comment?.author_kind === 'agent') return 'Agent';
       return comment?.author_name || comment?.name || "Anonymous";
     }
 
@@ -5631,6 +5895,12 @@ function initComty(options = {}) {
     function createCommentAvatar(comment, extraClass = "") {
       const avatar = document.createElement("span");
       avatar.className = `comty-comment-avatar${extraClass ? ` ${extraClass}` : ""}`;
+      if (comment?.author_kind === 'agent') {
+        avatar.classList.add('comty-agent-avatar');
+        avatar.setAttribute('aria-label', 'Agent');
+        avatar.innerHTML = '<svg viewBox="0 0 48 48" aria-hidden="true"><path d="M24 2C26.62 2 28.47 5.29 31.27 6.45C34.07 7.61 37.71 6.59 39.56 8.44C41.41 10.29 40.39 13.93 41.55 16.73C42.71 19.53 46 21.38 46 24C46 26.62 42.71 28.47 41.55 31.27C40.39 34.07 41.41 37.71 39.56 39.56C37.71 41.41 34.07 40.39 31.27 41.55C28.47 42.71 26.62 46 24 46C21.38 46 19.53 42.71 16.73 41.55C13.93 40.39 10.29 41.41 8.44 39.56C6.59 37.71 7.61 34.07 6.45 31.27C5.29 28.47 2 26.62 2 24C2 21.38 5.29 19.53 6.45 16.73C7.61 13.93 6.59 10.29 8.44 8.44C10.29 6.59 13.93 7.61 16.73 6.45C19.53 5.29 21.38 2 24 2Z" fill="currentColor"/><path fill="var(--comty-surface)" fill-rule="evenodd" d="M16 33 22.3 15h3.4L32 33h-3.3l-1.3-4h-6.8l-1.3 4H16Zm5.5-6.8h5L24 18.4l-2.5 7.8Z"/></svg>';
+        return avatar;
+      }
       const authorName = getCommentAuthorName(comment);
       const avatarUrl = getCommentAuthorAvatarUrl(comment);
 
@@ -5638,6 +5908,7 @@ function initComty(options = {}) {
         const image = document.createElement("img");
         image.src = avatarUrl;
         image.alt = "";
+        image.draggable = false;
         image.onerror = () => {
           image.remove();
           avatar.innerText = authorName.charAt(0).toUpperCase();
@@ -5862,6 +6133,7 @@ function initComty(options = {}) {
         payload,
         preview: { rect: target.getBoundingClientRect(), rows: getInspectRows(target), selector: getSelector(target), spacing: getSpacingPreview(target) },
       };
+      syncPlacementCursor();
       ensureLiveTracking();
 
       const pin = document.createElement("div");
@@ -5879,10 +6151,21 @@ function initComty(options = {}) {
 
       const textarea = document.createElement("textarea");
       textarea.className = "comty-create-textarea";
-      textarea.placeholder = "Add a comment";
+      textarea.placeholder = payload.kind === "agent" ? "Ask a question or describe a change" : "Add a comment";
       textarea.setAttribute("aria-label", textarea.placeholder);
       textarea.rows = 1;
 
+      const scopePicker = document.createElement('label');
+      scopePicker.className = 'comty-agent-scope';
+      if (payload.kind === 'agent') {
+        const input = document.createElement('input');
+        input.type = 'checkbox';
+        input.setAttribute('aria-label', 'Apply to all instances of this variant');
+        const track = document.createElement('span'); track.className = 'comty-agent-scope-track'; track.setAttribute('aria-hidden', 'true');
+        scopePicker.title = 'Apply to all instances of this variant';
+        scopePicker.append(input, track, document.createTextNode('Apply globally'));
+      }
+
       const actions = document.createElement("div");
       actions.className = "comty-create-actions";
 
@@ -5936,7 +6219,7 @@ function initComty(options = {}) {
       const submitBtn = document.createElement("button");
       submitBtn.type = "button";
       submitBtn.className = "comty-btn-submit";
-      submitBtn.setAttribute("aria-label", "Post comment");
+      submitBtn.setAttribute("aria-label", payload.kind === "agent" ? "Send agent task" : "Post comment");
       submitBtn.disabled = true;
       submitBtn.innerHTML = `
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -5953,49 +6236,62 @@ function initComty(options = {}) {
         textarea.disabled = true;
         linkBtn.disabled = true;
 
+        if (payload.kind === "agent" && !agent) {
+          showAgentBridgeError(); submitBtn.disabled = false; textarea.disabled = false; return;
+        }
         payload.content = content;
+        if (payload.kind === 'agent') payload.scope = scopePicker.querySelector('input').checked ? 'variant' : 'element';
         payload.linkUrl = attachedLink || null;
         textarea.textContent = content;
 
-        const context = captureContext();
-        const point = getPinPoint(pin);
-        const pendingId = `pending-${crypto.randomUUID()}`;
-        // Paint the comment immediately. The network save never waits for capture work.
+        const isAgentTask = payload.kind === "agent";
+        const context = isAgentTask ? null : captureContext();
+        const point = isAgentTask ? null : getPinPoint(pin);
+        const pendingId = isAgentTask ? null : `pending-${crypto.randomUUID()}`;
         bubble.remove();
         pin.remove();
         if (draftAnchor === editorDraft) draftAnchor = null;
+        syncPlacementCursor();
         hideInspector();
-        addLocalComment(pendingId, payload);
+        if (!isAgentTask) addLocalComment(pendingId, payload);
         let post;
         try {
-          post = await fetch(`${apiUrl}/api/comments`, {
+          post = await fetch(payload.kind === "agent" ? `${agentBridgeUrl}/tasks` : `${apiUrl}/api/comments`, {
             method: "POST",
-            headers: getSdkHeaders({ "Content-Type": "application/json" }),
-            body: JSON.stringify(payload),
+            headers: payload.kind === "agent" ? agentHeaders() : getSdkHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify(payload.kind === "agent" ? { ...payload, projectKey } : payload),
           });
-          if (!post.ok) throw new Error(`Comment save failed (${post.status})`);
+          if (!post.ok) throw new Error(`Save failed (${post.status})`);
           const data = await post.json();
-          if (!data?.id) throw new Error("Comment save returned no ID");
-          cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
-          if (context.url === location.href) {
-            const comment = addLocalComment(String(data.id), payload);
-            // Start only after the save and immediate UI update; the capture yields to input.
-            void uploadCommentScreenshot(comment, context, point);
-          } else void loadComments({ force: true });
+          const id = isAgentTask ? data?.task?.id : data?.id;
+          if (!id) throw new Error("Save returned no ID");
+          if (isAgentTask) {
+            void loadComments({ force: true });
+          } else {
+            cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
+            if (context.url === location.href) {
+              const comment = addLocalComment(String(id), payload);
+              void uploadCommentScreenshot(comment, context, point);
+            } else void loadComments({ force: true });
+          }
         } catch (error) {
           console.error("Comty: save failed", error);
-          cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
-          renderSidepanelComments();
-          void renderComments(cachedComments, { retry: false });
+          if (isAgentTask) showAgentBridgeError(error.message);
+          else {
+            cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
+            renderSidepanelComments();
+            void renderComments(cachedComments, { retry: false });
+          }
           // Keep the original editor and its text available for retry, including attachments.
           if (!draftAnchor) draftAnchor = editorDraft;
+          syncPlacementCursor();
           root.append(pin, bubble);
           submitBtn.disabled = false;
           textarea.disabled = false;
           linkBtn.disabled = false;
           const errorMessage = document.createElement("p");
           errorMessage.setAttribute("role", "alert");
-          errorMessage.textContent = "Comment not saved. Your draft is ready to retry.";
+          errorMessage.textContent = `${isAgentTask ? "Task" : "Comment"} not saved. Your draft is ready to retry.`;
           bubble.querySelector('[role="alert"]')?.remove();
           bubble.append(errorMessage);
           if (bubble.isConnected) textarea.focus();
@@ -6084,7 +6380,8 @@ function initComty(options = {}) {
         renderInspector();
       };
 
-      actions.append(linkBtn, submitBtn, linkEditor);
+      if (payload.kind === 'agent') actions.append(scopePicker, submitBtn);
+      else actions.append(linkBtn, submitBtn, linkEditor);
 
       bubble.appendChild(textarea);
       bubble.appendChild(attachment);
@@ -6097,6 +6394,219 @@ function initComty(options = {}) {
       setTimeout(() => textarea.focus(), 10);
     }
 
+    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 toast = document.createElement("div");
+      toast.className = "comty-auth-toast comty-agent-task-toast";
+      toast.setAttribute("role", "alert");
+      const issue = describeAgentError(message);
+      toast.textContent = issue.title + ". " + issue.description;
+      root.appendChild(toast);
+      setTimeout(() => toast.remove(), 5000);
+    }
+
+    function describeAgentError(error) {
+      const raw = typeof error === 'string' ? error : JSON.stringify(error, null, 2) || 'Unknown error';
+      let value = error;
+      for (let depth = 0; depth < 8; depth++) {
+        if (typeof value === 'string') {
+          try { value = JSON.parse(value); continue; } catch {}
+          const start = value.indexOf('{'), end = value.lastIndexOf('}');
+          if (start >= 0 && end > start) { try { value = JSON.parse(value.slice(start, end + 1)); continue; } catch {} }
+          break;
+        }
+        if (!value || typeof value !== 'object') break;
+        value = value.error || value.message || value.cause || value.stderr || value;
+      }
+      const message = typeof value === 'string' ? value : '';
+      const source = raw + ' ' + message;
+      const agentName = /codex/i.test(source) ? 'Codex' : /claude/i.test(source) ? 'Claude Code' : /cursor/i.test(source) ? 'Cursor' : 'your coding agent';
+      let title, description;
+      if (/requires a newer version|upgrade.*latest|outdated|unsupported.*version/i.test(source)) {
+        title = 'Agent update required'; description = `Update ${agentName}, restart your local development session, then retry this task.`;
+      } else if (/insufficient_quota|quota exceeded|credit balance|billing|usage limit/i.test(source)) {
+        title = 'Usage limit reached'; description = 'Check your agent account’s usage allowance or billing, then retry when capacity is available.';
+      } else if (/rate.?limit|too many requests|\b429\b/i.test(source)) {
+        title = 'Too many requests'; description = 'The agent is temporarily rate limited. Wait a moment before retrying.';
+      } 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.';
+      } 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)) {
+        title = 'Task timed out'; description = 'Review any changes already made, then retry with a smaller, more specific request.';
+      } else if (/permission|denied|forbidden|\b403\b/i.test(source)) {
+        title = 'Permission needed'; description = 'Check the agent’s access to this project and any pending approval before retrying.';
+      } else if (/ENOENT|command not found|not installed|executable.*not found/i.test(source)) {
+        title = 'Agent not found'; description = `Install or configure ${agentName} in your local development environment, then restart and retry.`;
+      } else if (/completion was not verified/i.test(source)) {
+        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.';
+      }
+      return { title, description, raw, message };
+    }
+
+    function renderAgentPanel() {
+      if (!agent) return;
+      const visibleTasks = [];
+      const latestResult = [...localTasks].reverse().find(task => ['done', 'in_review'].includes(task.status) && (!task.thread_comment_id || task.status === 'in_review'));
+      if (latestResult) visibleTasks.push(latestResult);
+      if (!visibleTasks.length && !localApprovals.length && !agentActionError) agentPanelOpen = false;
+      let panel = root.querySelector(".comty-agent-panel");
+      if (!panel && !agentPanelOpen) return;
+      if (!panel) {
+        panel = document.createElement("section");
+        panel.className = "comty-agent-panel";
+        panel.setAttribute("aria-label", "Local agent tasks");
+        panel.hidden = true;
+        // Keep the task card above inspection overlays and below the toolbar.
+        root.insertBefore(panel, toolbar);
+      }
+      const open = Boolean(agent) && agentPanelOpen;
+      if (open) {
+        if (panel.hidden) {
+          const rect = toolbar.getBoundingClientRect();
+          panel.dataset.side = rect.left + rect.width / 2 < innerWidth / 2 ? "left" : "right";
+          panel.dataset.closed = "";
+          panel.hidden = false;
+          panel.getBoundingClientRect();
+        }
+        if (panel.hasAttribute("data-closed")) { agentPanelTransition++; delete panel.dataset.closed; }
+      } else if (!panel.hidden && !panel.hasAttribute("data-closed")) {
+        const transition = ++agentPanelTransition;
+        panel.dataset.closed = "";
+        const finish = () => { if (transition === agentPanelTransition && panel.hasAttribute("data-closed")) panel.hidden = true; };
+        if (reducedMotion.matches) finish();
+        else setTimeout(finish, parseFloat(getComputedStyle(root).getPropertyValue("--comty-motion-duration")));
+      }
+      panel.inert = !open;
+      panel.setAttribute("aria-hidden", String(!open));
+      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;
+      const node = (tag, className, text) => {
+        const element = document.createElement(tag);
+        if (className) element.className = className;
+        if (text != null) element.textContent = text;
+        return element;
+      };
+      const brand = () => createCommentAvatar({ author_kind: 'agent' }, 'comty-agent-brand');
+      panel.replaceChildren();
+      const header = node('header', 'comty-agent-panel-header');
+      const heading = node('div', 'comty-agent-heading');
+      heading.append(node('strong', '', 'Agent'));
+      const toggle = node('button', 'comty-agent-action comty-agent-close'); toggle.type = 'button';
+      toggle.innerHTML = icon('<path d="m6 6 12 12M6 18 18 6"/>');
+      toggle.setAttribute('aria-label', 'Close Agent task'); toggle.title = 'Close'; toggle.dataset.focusKey = 'close';
+      toggle.onclick = () => { agentPanelOpen = false; renderAgentPanel(); agentBtn?.focus({ preventScroll: true }); };
+      header.append(heading, toggle); panel.appendChild(header);
+      const content = node('div', 'comty-agent-panel-content'); panel.appendChild(content);
+      const technicalDetails = (parent, raw, key) => {
+        const details = node('details', 'comty-agent-details'); details.dataset.detailKey = key; details.open = expanded.has(key);
+        const summary = node('summary', '', 'Technical details'); summary.dataset.focusKey = 'details-' + key;
+        details.append(summary, node('pre', '', raw)); parent.appendChild(details);
+      };
+      const errorMessage = (parent, error, key) => {
+        const issue = describeAgentError(error);
+        const message = node('div', 'comty-agent-error');
+        message.append(node('strong', '', issue.title), node('p', '', issue.description));
+        parent.appendChild(message); technicalDetails(parent, issue.raw, key);
+      };
+      if (agentConnectionError || agentActionError) {
+        const banner = node('div', 'comty-agent-item comty-agent-banner'); banner.setAttribute('role', 'alert');
+        errorMessage(banner, agentConnectionError || agentActionError, 'connection'); content.appendChild(banner);
+      }
+      const action = (parent, label, path, input = {}, primary = false) => {
+        const button = node('button', 'comty-agent-action', label); button.type = 'button';
+        const key = path + JSON.stringify(input); button.dataset.focusKey = key;
+        button.disabled = agentPendingActions.has(key);
+        if (primary) button.dataset.primary = '';
+        button.onclick = async () => {
+          if (agentPendingActions.has(key)) return;
+          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 });
+          } catch (error) { agentActionError = error.message; }
+          finally { agentPendingActions.delete(key); agentPanelSignature = ''; renderAgentPanel(); }
+        };
+        parent.appendChild(button);
+      };
+      for (const approval of localApprovals) {
+        const section = node('div', 'comty-agent-item');
+        section.append(node('h3', '', 'Approval required'));
+        const task = localTasks.find(task => task.id === approval.taskId);
+        if (task) section.appendChild(node('p', '', task.content));
+        section.appendChild(node('p', '', 'Review this operation before allowing the agent to continue.'));
+        const operation = approval.details?.command || approval.details?.file_path || approval.details?.path;
+        if (typeof operation === 'string' || Array.isArray(operation)) section.appendChild(node('pre', '', Array.isArray(operation) ? operation.join(' ') : operation));
+        technicalDetails(section, JSON.stringify(approval.details ?? {}, null, 2), 'approval-' + approval.id);
+        const actions = node('div', 'comty-agent-actions');
+        action(actions, 'Allow once', `approvals/${approval.id}`, { allow: true }, true);
+        action(actions, 'Deny', `approvals/${approval.id}`, { allow: false });
+        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()) {
+        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;
+        const dot = state === 'working' ? createWorkingIndicator() : node('span', 'comty-agent-dot');
+        dot.dataset.status = state; dot.setAttribute('aria-hidden', 'true');
+        const name = node('span', 'comty-agent-row-name', task.thread_comment_id ? `@Agent · ${task.content}` : task.content);
+        row.append(dot, name);
+        if (state === 'working') row.appendChild(node('span', 'comty-agent-row-state', task.status === 'todo' ? 'Starting' : 'Working'));
+        const actions = node('div', 'comty-agent-row-actions');
+        if (['in_review', 'cancel'].includes(task.status)) action(actions, 'Retry', `tasks/${task.id}/retry`);
+        if (['todo', 'in_progress'].includes(task.status)) action(actions, 'Cancel', `tasks/${task.id}/cancel`);
+        if (task.status === 'done') action(actions, 'Dismiss', `tasks/${task.id}/dismiss`);
+        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.result?.summary) {
+          const answer = node('div', 'comty-agent-answer');
+          answer.append(brand(), node('p', '', task.result.summary));
+          list.appendChild(answer);
+        }
+      }
+      content.scrollTop = scrollTop;
+      if (focusKey && open) [...panel.querySelectorAll('[data-focus-key]')].find(element => element.dataset.focusKey === focusKey)?.focus({ preventScroll: true });
+    }
+
     function setSidepanelOpen(open) {
       sidepanelOpen = open;
       sidepanel.classList.toggle("comty-sidepanel-open", sidepanelOpen);
@@ -6132,12 +6642,52 @@ function initComty(options = {}) {
 
     function openCommentFromPanel(comment) {
       const target = resolveCommentElement(comment);
-      if (!target || isElementTreeHidden(target)) return;
+      if (!target || isElementTreeHidden(target)) {
+        openDetachedThread(comment);
+        return;
+      }
       setSession(session.comments ? session.mode : "browse", { entry: sessionEntry, renderComments: true });
       target.scrollIntoView({ block: "center", inline: "nearest", behavior: "instant" });
+      const rect = target.getBoundingClientRect();
+      const relX = Number(comment.rel_x ?? comment.relX);
+      const relY = Number(comment.rel_y ?? comment.relY);
+      // Large page containers must reveal the annotation point, not their center.
+      window.scrollBy({
+        left: rect.width > innerWidth && Number.isFinite(relX) ? rect.left + Math.max(0, Math.min(1, relX)) * rect.width - innerWidth / 2 : 0,
+        top: rect.height > innerHeight && Number.isFinite(relY) ? rect.top + Math.max(0, Math.min(1, relY)) * rect.height - innerHeight / 2 : 0,
+        behavior: "instant",
+      });
       syncCommentAnchors();
       const pin = findPlacedPin(comment);
       if (pin && !pin.hasAttribute("data-comty-anchor-hidden")) pin.click();
+      else openDetachedThread(comment);
+    }
+
+    function openDetachedThread(comment) {
+      openCommentThread(comment, null, null, innerWidth / 2, innerHeight / 3, () => {});
+      const bubble = [...root.querySelectorAll(".comty-bubble")].find(node => node.dataset.commentId === String(comment.id));
+      if (bubble) {
+        bubble.dataset.detached = "";
+        positionCommentBubble(bubble, innerWidth / 2, innerHeight / 3);
+      }
+    }
+
+    function updateAnchorBadge(item, comment) {
+      resolveCommentElement(comment);
+      const result = commentTargets.get(String(comment.id));
+      const legacy = getPagePath() !== window.location.pathname && comment.page_path === window.location.pathname;
+      const status = legacy && !result?.element ? "uncertain" : result?.status;
+      const label = status === "missing" ? "Target missing" : status === "uncertain" ? "Target uncertain" : "";
+      let badge = item.querySelector(".comty-anchor-badge");
+      if (!label) { badge?.remove(); return; }
+      if (!badge) {
+        badge = document.createElement("span");
+        badge.className = "comty-anchor-badge";
+        item.querySelector(".comty-sidepanel-item-body").appendChild(badge);
+      }
+      if (badge.textContent !== label) badge.textContent = label;
+      badge.title = legacy ? "This older comment has no saved hash route. Its target may be on another page." :
+        status === "missing" ? "The target is not present on this page. The comment is still available." : "The target cannot be identified reliably. No pin is placed.";
     }
 
     let sidepanelFilters = { status: "", device: "", dateSort: "desc" };
@@ -6150,6 +6700,7 @@ function initComty(options = {}) {
           ? sidepanelSearch.value.trim().toLowerCase()
           : "";
       let list = cachedComments.filter((comment) => {
+        if (comment.local_agent || comment.kind === "agent") return false;
         if (
           search &&
           !`${comment.content ?? ""} ${getCommentLabel(comment)}`
@@ -6196,6 +6747,7 @@ function initComty(options = {}) {
         const item = document.createElement("button");
         item.type = "button";
         item.className = "comty-sidepanel-item";
+        item.dataset.commentId = String(comment.id);
         item.disabled = Boolean(comment.pending);
         item.innerHTML = `
         <span class="comty-sidepanel-item-status" aria-hidden="true"></span>
@@ -6219,8 +6771,13 @@ function initComty(options = {}) {
         if (metaEl instanceof HTMLElement) {
           metaEl.innerText = `${comment.author_name || "Anonymous"} · ${comment.pending ? "Sending…" : getCommentLabel(comment)}`;
           metaEl.title = getCommentLabel(comment);
+          if (getPagePath() !== window.location.pathname && comment.page_path === window.location.pathname && !resolveCommentElement(comment)) {
+            metaEl.innerText += " · Original page unknown";
+          }
         }
 
+        updateAnchorBadge(item, comment);
+
         item.onclick = (event) => {
           event.stopPropagation();
           openCommentFromPanel(comment);
@@ -6336,14 +6893,15 @@ function initComty(options = {}) {
     createStatusFilters();
 
     async function updateCommentStatus(comment, status) {
-      if (!projectId || !comment?.id) return false;
+      if (comment?.local_agent || !projectId || !comment?.id) return false;
 
       let res;
       try {
-        res = await fetch(`${apiUrl}/api/comments/${comment.id}/status`, {
+        const local = comment.local_agent === true;
+        res = await fetch(local ? `${agentBridgeUrl}/tasks/${encodeURIComponent(comment.id)}/status` : `${apiUrl}/api/comments/${comment.id}/status`, {
           method: "POST",
-          headers: getSdkHeaders({ "Content-Type": "application/json" }),
-          body: JSON.stringify({
+          headers: local ? { "Content-Type": "application/json" } : getSdkHeaders({ "Content-Type": "application/json" }),
+          body: JSON.stringify(local ? { status } : {
             projectKey,
             host: window.location.host,
             status,
@@ -6360,7 +6918,7 @@ function initComty(options = {}) {
       }
 
       const data = await res.json();
-      comment.status = getCommentStatus(data.status).value;
+      comment.status = getCommentStatus(data.task?.status ?? data.status).value;
       return comment.status;
     }
 
@@ -6552,6 +7110,23 @@ function initComty(options = {}) {
       isOwnCommentEntry, updateCommentContent, deleteSdkComment, getCommentId,
       updateReplyContent, deleteSdkReply, createCommentAvatar, getSdkHeaders,
       showAuthPrompt,
+      startThreadAgent: async (comment, replies, content) => {
+        if (!agent) throw new Error('Start the local agent to reply with @Agent');
+        if (!canManage) throw new Error('Sign in as a project editor to use @Agent');
+        const transcript = [
+          `${getCommentAuthorName(comment)}: ${comment.content}`,
+          ...replies.map(reply => `${getCommentAuthorName(reply)}: ${reply.content}`),
+        ].join('\n').slice(-24000);
+        const response = await fetch(`${agentBridgeUrl}/tasks`, {
+          method: 'POST', headers: agentHeaders(),
+          body: JSON.stringify({ content, pagePath: comment.page_path || getPagePath(),
+            selector: comment.selector || 'body', relX: comment.rel_x ?? 0.5, relY: comment.rel_y ?? 0.5,
+            domElement: comment.dom_element || '', viewport: comment.viewport || '',
+            anchorContext: comment.anchor_context || '', scope: 'element',
+            thread: { commentId: String(comment.id), transcript } }),
+        });
+        if (!response.ok) throw new Error((await response.json().catch(() => null))?.error || 'Could not start Agent');
+      },
       get canWrite() { return canWrite; },
       get canManage() { return canManage; },
       get allowGuestComments() { return allowGuestComments; },
@@ -6752,42 +7327,112 @@ function initComty(options = {}) {
     function reconcileComments(comments) {
       const previous = new Map(cachedComments.map(comment => [String(comment.id), comment]));
       cachedComments = comments
-        .filter(comment => comment.kind !== "agent" && !comment.local_agent)
+        .filter(comment => comment.kind !== "agent" || comment.status !== "done")
         .map(comment => Object.assign(previous.get(String(comment.id)) || {}, comment));
       for (const comment of previous.values()) {
         if (comment.pending && !cachedComments.some(item => item.id === comment.id)) cachedComments.push(comment);
       }
     }
 
+    async function deliverThreadReply(task) {
+      if (deliveringAgentReplies.has(task.id)) return;
+      deliveringAgentReplies.add(task.id);
+      try {
+        const response = await fetch(`${apiUrl}/api/comments/${encodeURIComponent(task.thread_comment_id)}/replies`, {
+          method: 'POST', headers: getSdkHeaders({ 'Content-Type': 'application/json' }),
+          body: JSON.stringify({ projectKey, content: task.result.summary, agentTaskId: task.id }),
+        });
+        if (!response.ok) throw new Error(`Could not save Agent reply (${response.status})`);
+        const { reply } = await response.json();
+        const local = cachedComments.find(comment => String(comment.id) === task.thread_comment_id);
+        if (local && !local.replies?.some(item => item.id === reply.id)) {
+          local.replies ||= [];
+          local.replies.push(reply);
+        }
+        for (const bubble of root.querySelectorAll('.comty-bubble')) {
+          if (bubble.dataset.commentId === task.thread_comment_id) bubble.dispatchEvent(new CustomEvent('comty-agent-reply', { detail: reply }));
+        }
+        const ack = await fetch(`${agentBridgeUrl}/tasks/${task.id}/dismiss`, { method: 'POST', headers: agentHeaders(), body: '{}' });
+        if (!ack.ok) throw new Error('Agent reply saved, but local acknowledgement failed');
+        localTasks = localTasks.filter(item => item.id !== task.id);
+      } catch (error) {
+        agentActionError = error.message;
+        console.error('Comty: Agent reply delivery failed', error);
+      } finally {
+        deliveringAgentReplies.delete(task.id);
+        agentPanelSignature = '';
+        renderAgentPanel();
+      }
+    }
+
     async function loadComments({ force = false } = {}) {
-      if (!projectId) return;
-      const pagePath = window.location.pathname;
+      if (!projectId && !agent) return;
+      const pagePath = getPagePath();
       if (!force && cachedPagePath === pagePath) { await renderComments(cachedComments); return; }
       if (pendingCommentsLoad) {
         await pendingCommentsLoad;
-        if (!force) return;
+        if (!force && cachedPagePath === pagePath) return;
       }
       pendingCommentsLoad = (async () => {
-        let comments = cachedPagePath === pagePath ? cachedComments : [];
+        let comments = cachedPagePath === pagePath ? cachedComments.filter(comment => !comment.local_agent) : [];
         if (projectId) {
           try {
-            const url = new URL(`${apiUrl}/api/comments`);
-            url.search = new URLSearchParams({ projectKey, host: window.location.host, pagePath, ...(force ? { _t: String(Date.now()) } : {}) });
-            const res = await fetch(url);
-            if (!res.ok) throw new Error(await res.text());
-            const data = await res.json();
-            if (Array.isArray(data.comments)) comments = data.comments;
+            const paths = [...new Set([pagePath, window.location.pathname])];
+            const batches = await Promise.all(paths.map(async path => {
+              const url = new URL(`${apiUrl}/api/comments`);
+              url.search = new URLSearchParams({ projectKey, host: window.location.host, pagePath: path, ...(force ? { _t: String(Date.now()) } : {}) });
+              const res = await fetch(url);
+              if (!res.ok) throw new Error(await res.text());
+              const data = await res.json();
+              return Array.isArray(data.comments) ? data.comments : [];
+            }));
+            comments = [...new Map(batches.flat().map(comment => [String(comment.id), comment])).values()];
           } catch (error) { console.error("Comty: list comments failed", error); }
         }
+        if (agent) {
+          try {
+            const res = await fetch(`${agentBridgeUrl}/tasks`, { headers: agentHeaders(), cache: "no-store" });
+            if (!res.ok) throw new Error("Local companion unavailable");
+            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);
+            if (Array.isArray(data.approvals)) {
+              localApprovals = data.approvals;
+              if (localApprovals.some(approval => !seenAgentApprovals.has(approval.id))) agentPanelOpen = true;
+              seenAgentApprovals.clear();
+              for (const approval of localApprovals) seenAgentApprovals.add(approval.id);
+            }
+            agentConnectionError = "";
+          } catch (error) {
+            agentConnectionError = "Local agent disconnected. Check the development server, then reload this page.";
+            console.error("Comty: local tasks failed", error);
+          }
+          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)));
+          renderAgentPanel();
+        }
+        if (pagePath !== getPagePath()) return;
         reconcileComments(comments);
         cachedPagePath = pagePath;
         renderSidepanelComments();
         await renderComments(cachedComments);
+        syncAgentWorkingOutlines();
         ensureLiveTracking();
       })();
       try { await pendingCommentsLoad; } finally { pendingCommentsLoad = null; }
     }
 
+    if (agent) {
+      setInterval(() => {
+        if (!pendingCommentsLoad && document.visibilityState === "visible") void loadComments({ force: true });
+      }, 2000);
+    }
+
     function getPinPoint(pin) {
       return { x: parseFloat(pin.style.left), y: parseFloat(pin.style.top) };
     }
@@ -6815,7 +7460,7 @@ function initComty(options = {}) {
     }
 
     function syncCommentAnchors() {
-      if (!session.comments) return;
+      if (!session.comments && !session.inspect) return;
       const modal = getTopActiveModal();
       for (const comment of cachedComments) {
         const id = String(comment.id);
@@ -6826,7 +7471,7 @@ function initComty(options = {}) {
           placePin(comment, modal);
           pin = placedPins.get(id);
         }
-        const bubbles = [...root.querySelectorAll(".comty-bubble")].filter(bubble => bubble.dataset.commentId === id || bubble.dataset.hoverId === id);
+        const bubbles = [...root.querySelectorAll(".comty-bubble")].filter(bubble => (bubble.dataset.commentId === id || bubble.dataset.hoverId === id) && !bubble.hasAttribute("data-detached"));
         // A pin can remove its target's :hover style as the pointer enters it.
         if (!point && pin && target?.isConnected && !target.hasAttribute("hidden") && !isElementTreeHidden(target.parentElement) &&
           (activeHoverCommentIds.has(id) || bubbles.some(bubble => bubble.dataset.commentId === id))) continue;
@@ -6841,6 +7486,10 @@ function initComty(options = {}) {
         if (pin.style.top !== y) pin.style.top = y;
         for (const bubble of bubbles) positionCommentBubble(bubble, point.clientX, point.clientY);
       }
+      if (sidepanelOpen) for (const item of sidepanelList.querySelectorAll(".comty-sidepanel-item")) {
+        const comment = cachedComments.find(comment => String(comment.id) === item.dataset.commentId);
+        if (comment) updateAnchorBadge(item, comment);
+      }
       if (draftAnchor) {
         if (!draftAnchor.target?.isConnected) draftAnchor.target = resolveCommentElement(draftAnchor.payload);
         const point = getVisibleAnchorPoint(draftAnchor.target, draftAnchor.payload.relX, draftAnchor.payload.relY, modal);
@@ -6854,16 +7503,50 @@ function initComty(options = {}) {
       }
     }
 
+    function syncAgentWorkingOutlines() {
+      const working = localTasks.filter(task => task.status === "in_progress" && task.page_path === getPagePath());
+      const ids = new Set(working.map(task => String(task.id)));
+      for (const [id, outline] of workingOutlines) {
+        if (ids.has(id)) continue;
+        outline.remove(); workingOutlines.delete(id);
+      }
+      const modal = getTopActiveModal();
+      for (const task of working) {
+        const id = String(task.id);
+        let outline = workingOutlines.get(id);
+        if (!outline) {
+          outline = document.createElement("div");
+          outline.className = "comty-agent-working";
+          outline.setAttribute("aria-label", "Agent working on this element");
+          const badge = document.createElement("span");
+          badge.className = "comty-agent-working-badge";
+          badge.append(createWorkingIndicator(), "Working");
+          outline.appendChild(badge); root.appendChild(outline);
+          workingOutlines.set(id, outline);
+        }
+        const target = resolveCommentElement(task);
+        const point = target && getVisibleAnchorPoint(target, Number(task.rel_x), Number(task.rel_y), modal);
+        outline.hidden = !point;
+        if (!point) continue;
+        const rect = target.getBoundingClientRect();
+        setMeasuredRect(outline, rect);
+        outline.toggleAttribute("data-badge-below", rect.top < 32);
+      }
+    }
+
     function onFrame() {
       if (motion.enabled) updateMotion();
-      if (session.comments) syncCommentAnchors();
+      if (session.comments || session.inspect) syncCommentAnchors();
+      if (session.agent || workingOutlines.size || localTasks.some(task => task.status === "in_progress" && task.page_path === getPagePath())) {
+        syncAgentWorkingOutlines();
+      }
       if (session.inspect || session.edit || inspectionLayer.childNodes.length) renderInspector();
       if (session.inspect && rulersEnabled) renderRulers();
       if (session.inspect && rulersEnabled) measurements.render();
     }
 
     function ensureLiveTracking() {
-      const active = motion.enabled || session.inspect || session.edit || (session.comments && cachedComments.length > 0);
+      const active = motion.enabled || session.inspect || session.edit || (session.comments && cachedComments.length > 0) || workingOutlines.size > 0;
       if (!active || document.hidden) {
         if (liveFrame) cancelAnimationFrame(liveFrame);
         liveFrame = null;
@@ -6883,13 +7566,14 @@ function initComty(options = {}) {
     syncOverlayHost();
 
     function renderCachedComments() {
-      if (!session.comments && !session.inspect && !session.edit) return;
+      if (!session.comments && !session.inspect && !session.edit && !workingOutlines.size) return;
       if (resizeRenderFrame) {
         window.cancelAnimationFrame(resizeRenderFrame);
       }
       resizeRenderFrame = window.requestAnimationFrame(() => {
         resizeRenderFrame = null;
         syncCommentAnchors();
+        syncAgentWorkingOutlines();
         renderInspector();
         ensureLiveTracking();
       });
@@ -6931,6 +7615,29 @@ function initComty(options = {}) {
       characterData: true,
     });
 
+    let activePagePath = getPagePath();
+    function handleRouteChange() {
+      const next = getPagePath();
+      if (next === activePagePath) return;
+      activePagePath = next;
+      closeBubbles();
+      commentTargets.clear();
+      reconcileComments([]);
+      void renderComments([], { retry: false });
+      renderSidepanelComments();
+      void loadComments({ force: true });
+    }
+    window.addEventListener("hashchange", handleRouteChange);
+    window.addEventListener("popstate", handleRouteChange);
+    for (const method of ["pushState", "replaceState"]) {
+      const original = history[method];
+      history[method] = function (...args) {
+        const result = original.apply(this, args);
+        handleRouteChange();
+        return result;
+      };
+    }
+
     document.addEventListener("scroll", handleHostLayoutEvent, {
       capture: true,
       passive: true,
@@ -7068,13 +7775,14 @@ function initComty(options = {}) {
         const y = e.clientY;
 
         const anchorContext = getAnchorContext(el);
+        if (session.agent && anchorContext) anchorContext.inspectedStyles = getInspectRows(el);
 
         const payload = {
           ...getDeviceContext(),
           projectId,
-          kind: "comment",
+          kind: session.agent ? "agent" : "comment",
           host: window.location.host,
-          pagePath: window.location.pathname,
+          pagePath: getPagePath(),
           selector: getSelector(el),
           relX,
           relY,
@@ -7172,6 +7880,7 @@ function initComty(options = {}) {
     window.addEventListener("blur", () => { measureAlt = false; renderInspector(); });
 
     async function boot() {
+      if (localOnly) { await loadComments(); return; }
       const res = await fetch(`${apiUrl}/api/sdk/bootstrap`, {
         method: "POST",
         headers: getSdkHeaders({ "Content-Type": "application/json" }),
@@ -7184,6 +7893,7 @@ function initComty(options = {}) {
 
       if (!res.ok) {
         console.error("Comty: bootstrap failed", await res.text());
+        if (agent) await loadComments();
         return;
       }
 
@@ -7228,16 +7938,30 @@ function initComty(options = {}) {
 
     if (typeof options.onTestReady === "function") {
       options.onTestReady({
-        getSelector, getAnchorContext, resolveCommentElement, getVisibleAnchorPoint,
+        getPagePath, getSelector, getAnchorContext, resolveCommentElement, getVisibleAnchorPoint,
         getDistanceSegments, getInspectRows, syncCommentAnchors,
         setInspectorMode(enabled) { setSession(enabled ? "inspect" : "off"); },
         startEditSession, startBrowseSession, endSession, showInspector,
-        motion, setMotionEnabled, updateMotion,
+        motion, setMotionEnabled, updateMotion, describeAgentError,
+        previewAgent(tasks, approvals = [], error = "") {
+          localTasks = tasks;
+          localApprovals = approvals;
+          agentConnectionError = error;
+          startAgentSession();
+          agentPanelOpen = true;
+          agentPanelSignature = "";
+          renderAgentPanel();
+        },
         seed(comments) {
           reconcileComments(comments);
           setSession(session.comments ? session.mode : "browse", { entry: sessionEntry, renderComments: true });
           return renderComments(cachedComments, { retry: false });
         },
+        seedAgentTasks(tasks) {
+          localTasks = tasks;
+          syncAgentWorkingOutlines();
+          ensureLiveTracking();
+        },
         setCanWrite(value) { canWrite = value; canManage = value; },
         invalidate() { anchorRevision += 1; },
       });
@@ -7245,6 +7969,7 @@ function initComty(options = {}) {
 
     return boot().catch(error => {
       console.error("Comty: bootstrap failed", error);
+      if (agent) return loadComments();
     });
   }
 }