@comty.io/core 0.1.7 → 0.1.9

package/README.md

@@ -10,17 +10,19 @@ Comments use the pathname and hash routes starting with `#/` or `#!/`. Plain fra
 
 Target matching combines content, attributes and surrounding structure. Small changes inside a container can preserve its comments; ambiguous matches do not place a pin. The sidebar shows **Target missing** when no target is found and **Target uncertain** when placement cannot be determined reliably. Both still open the full thread. Closed or unmounted known overlays do not count as deleted elements, and their comments never attach to matching content outside that overlay.
 
+New anchors exclude editable content from inputs, textareas, selects and rich-text editors, including when comparing their surrounding containers. Repeated fields use their attributes and question context to distinguish them. React-generated IDs are not treated as permanent identities. Existing comments are resolved again on reload without rewriting their stored anchors.
+
 Run `npm run test:anchors` for route, reload, ambiguity and overlay regressions.
 
 ## Comment screenshots
 
-Posting immediately displays a pending comment and sends the JSON request. After the API confirms the save, the SDK captures and uploads the viewport separately. Screenshot failures do not roll back comments; save failures restore the draft for retry. Screenshot annotations reuse the real Comty pin and hover card (avatar, author, date and content). They are measured in an invisible, inert host, then cloned with their computed styles and embedded resources into the screenshot. The temporary host is removed after cloning and never appears on screen.
+Posting immediately displays a pending comment, captures the viewport, then sends the comment and screenshot in one multipart request. The API stores the screenshot before creating the comment. Capture or save failures restore the draft for retry instead of silently creating a comment without an image. Screenshot annotations reuse the real Comty pin and hover card (avatar, author, date and content). They are measured in an invisible, inert host, then cloned with their computed styles and embedded resources into the screenshot. The temporary host is removed after cloning and never appears on screen.
 
 The bundled capture engine is based on `html-to-image` 1.11.13 (MIT), not SnapDOM. It embeds web fonts, responsive images, CSS backgrounds and pseudo-elements, preserves scroll offsets, and yields during DOM traversal. Each font face keeps its source when selecting WOFF2, including consecutive subset and weight rules. Transparent page backgrounds are composited over the browser's light or dark canvas so the image viewer cannot tint the screenshot. Offscreen leaf boxes keep their layout dimensions without their rendering cost. PNG is preferred for text; large images fall back to JPEG. Captures are capped at 2× resolution / 2560 pixels per side and have a 15-second processing deadline.
 
 Resources are fetched directly first. Public cross-origin assets blocked by CORS can use `/api/sdk/capture-resource`, authenticated with the SDK token and restricted to the project's allowed domain. The API validates and pins public DNS addresses on every redirect, limits bytes/concurrency/time, and never forwards credentials to resource hosts. Deploy the API alongside the SDK to enable this fallback.
 
-The capture never locks or restyles the live page. If the URL, viewport or page scroll changes before cloning finishes, it skips that screenshot rather than attaching a mismatched image. Browser restrictions still apply to private resources, closed shadow roots and embedded frames; inaccessible frames retain an empty layout box. The final SVG serialization/rasterization still uses browser APIs on the main thread, so zero processing cost on every possible site cannot be guaranteed.
+The capture never locks or restyles the live page. If the URL, viewport or page scroll changes before cloning finishes, posting fails and restores the draft for retry rather than attaching a mismatched image. Browser restrictions still apply to private resources, closed shadow roots and embedded frames; inaccessible frames retain an empty layout box. The final SVG serialization/rasterization still uses browser APIs on the main thread, so zero processing cost on every possible site cannot be guaranteed.
 
 `npm run build` reproducibly bundles the pinned library with small checked hooks for cooperative scheduling, resource fetching, cloning and exact font sizes; its MIT notice is included. No runtime package install is needed by SDK consumers. `npm run test:capture` runs Chrome/Chromium visual and posting tests; install Chromium with `npx playwright install chromium` on machines without Chrome. Comparison PNGs are written to `test-results/`.
 
@@ -37,12 +39,15 @@ import { initComty } from '@comty.io/core';
 
 await initComty({
   projectKey: 'YOUR_PROJECT_KEY',
-  apiUrl: 'https://YOUR_COMTY_API',
 });
 ```
 
 Call once from your application entry. Server rendering is safe: it does nothing until called in a browser. Repeated calls with the same options reuse the document's instance. Reload the page to change its project or API URL. Register the site's domain in Comty to use shared comments.
 
+The project key is the only required option for hosted Comty. The SDK connects to `https://api.comty.io` by default, including when your application runs on localhost. You do not need an API URL environment variable or your own Comty server. Set `apiUrl` only when using a different Comty API, such as `http://localhost:4000` for developing Comty itself or the URL of a self-hosted installation.
+
+The browser entry also works in production. If Comty should only appear in development or preview, conditionally call `initComty` in your application. To include production, do not guard initialization with a development-only flag. The Vite companion below is a separate development-only integration.
+
 ## Color tokens
 
 Element inspection shows a copyable CSS custom-property name above foreground/background colors when the winning declaration can be identified. It handles ordinary selectors, `:where()`, inline styles, inheritance, `!important`, active media/supports rules and named top-level cascade layers. Semantic aliases retain their declared name. No extra line is rendered for literal colors or uncertain provenance (including inaccessible stylesheets, shadow/scoped or nested cascades, and unsupported functional selectors).
@@ -81,7 +86,7 @@ export default defineConfig({
 });
 ```
 
-Keep your existing plugins. Run your normal dev command and open `http://localhost:<vite-port>`. The plugin injects the SDK and starts the companion automatically. It is disabled for production builds. Choose the installed coding agent with `agent: 'codex' | 'claude' | 'cursor' | 'gemini' | 'grok'`. The optional `model` setting accepts a model ID from the selected agent; omit it to use that agent's default. A project key is optional in local Agent mode; set `projectKey` and `apiUrl` in the plugin options if you also want shared Comty comments.
+Keep your existing plugins. Run your normal dev command and open `http://localhost:<vite-port>`. The plugin injects the SDK and starts the companion automatically. It is disabled for production builds. Choose the installed coding agent with `agent: 'codex' | 'claude' | 'cursor' | 'gemini' | 'grok'`. The optional `model` setting accepts a model ID from the selected agent; omit it to use that agent's default. A project key is optional in local Agent mode; set `projectKey` in the plugin options if you also want shared Comty comments. Set `apiUrl` only for a local or self-hosted Comty API.
 
 ## Other development servers
 

package/comty-sdk.js

@@ -1629,6 +1629,11 @@ function createAnchorMatcher({
   getPresentationLayer,
   isComtyNode,
 }) {
+    function getStableAnchorId(id) {
+      // React useId values change with mount order, including Base UI and Radix IDs.
+      return /^(?:(?:radix|base-ui)-)?(?:_r_[\w-]+_|:r[\w-]+:)$/i.test(id || "") ? "" : (id || "");
+    }
+
     function includesText(haystack, needle) {
       if (!haystack || !needle) return false;
       return haystack.toLowerCase().includes(needle.toLowerCase());
@@ -1652,12 +1657,13 @@ function createAnchorMatcher({
       }
 
       let score = 0;
-      const text = getElementTextSignature(el);
-      const ownText = getElementOwnTextSignature(el);
+      const text = getElementTextSignature(el, fingerprint.textMode === "static");
+      const ownText = getElementOwnTextSignature(el, fingerprint.textMode === "static");
 
       score += 20;
-      if (fingerprint.id) {
-        score += el.id.slice(0, 160) === fingerprint.id ? 70 : -30;
+      const stableId = getStableAnchorId(fingerprint.id);
+      if (stableId) {
+        score += el.id.slice(0, 160) === stableId ? 70 : -30;
       }
       const exactAttributes = [
         ["role", "role", 24],
@@ -1752,7 +1758,7 @@ function createAnchorMatcher({
 
     function scoreSibling(el, fingerprint) {
       if (!fingerprint) return 0;
-      const sibling = getSiblingFingerprint(el);
+      const sibling = getSiblingFingerprint(el, fingerprint.textMode === "static");
       if (!sibling || sibling.tag !== fingerprint.tag) return -4;
       let score = 4;
       if (fingerprint.ariaLabel && sibling.ariaLabel === fingerprint.ariaLabel) {
@@ -1791,7 +1797,7 @@ function createAnchorMatcher({
           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;
+        if (ancestors[index].text && getElementTextSignature(parent, ancestors[index].textMode === "static") === ancestors[index].text) score += 18;
         parent = parent.parentElement;
       }
 
@@ -1812,14 +1818,17 @@ function createAnchorMatcher({
       for (const [key, attribute] of Object.entries(attributes)) {
         if (fingerprint[key] && getAttributeSignature(el, attribute) !== fingerprint[key]) return false;
       }
-      if (fingerprint.id && el.id !== fingerprint.id) return false;
+      const stableId = getStableAnchorId(fingerprint.id);
+      if (stableId && el.id !== stableId) 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) ||
+      const stableIdentity = (stableId && el.id === stableId) ||
         (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;
+      const staticText = fingerprint.textMode === "static";
+      const text = getElementTextSignature(el, staticText);
+      if (fingerprint.ownText && getElementOwnTextSignature(el, staticText) !== fingerprint.ownText && !(allowTextChanges && stableIdentity)) return false;
       // Container text is useful for matching remounted drawers and dialogs.
-      if (!ignoreDescendantText && !fingerprint.ownText && fingerprint.text && getElementTextSignature(el) !== fingerprint.text && !(allowTextChanges && stableIdentity)) {
-        if (!allowTextChanges || !el.children.length || !similarText(getElementTextSignature(el), fingerprint.text)) return false;
+      if (!ignoreDescendantText && !fingerprint.ownText && fingerprint.text && text !== fingerprint.text && !(allowTextChanges && stableIdentity)) {
+        if (!allowTextChanges || !el.children.length || !similarText(text, fingerprint.text)) return false;
       }
       return true;
     }
@@ -1852,10 +1861,11 @@ function createAnchorMatcher({
         .map(el => ({ el, score: scoreAnchorCandidate(el, context) + (context.version === 1 && el === exact ? 16 : 0) }))
         .sort((a, b) => b.score - a.score);
       if (context.candidateCount > 1) {
+        // Creation counts full context matches, not every element with the same text.
         const peers = candidates.filter(el => matchesAnchorIdentity(el, context.target));
-        if (peers.length !== context.candidateCount) {
+        if (matches.length !== context.candidateCount && 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);
+          const distinctive = matches[0] && (getStableAnchorId(context.target.id) || context.target.testId);
           if (!distinctive) return { element: null, status: "uncertain" };
         }
       }
@@ -1868,8 +1878,8 @@ function createAnchorMatcher({
         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))));
+        (getStableAnchorId(context.target.id) && el.id === context.target.id) ||
+        (context.target.text && (getElementTextSignature(el, context.target.textMode === "static") === context.target.text || similarText(getElementTextSignature(el, context.target.textMode === "static"), context.target.text))));
       return { element: null, status: plausible ? "uncertain" : "missing" };
     }
 
@@ -2046,7 +2056,7 @@ function createAnchorMatcher({
       return { clientX, clientY };
     }
 
-    return { matchesAnchorContext, resolveAnchor, resolveByAnchorContext, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint };
+    return { getStableAnchorId, matchesAnchorContext, resolveAnchor, resolveByAnchorContext, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint };
 }
 
 const captureEngine = (() => { // Generated from html-to-image 1.11.13 by scripts/capture-engine.mjs.
@@ -3585,7 +3595,7 @@ function initComty(options = {}) {
     } catch { return Promise.reject(new TypeError("Comty: companion must share the page origin")); }
   }
   const projectKey = options.projectKey || (agent ? "local" : undefined);
-  const apiUrl = options.apiUrl || "http://localhost:4000";
+  const apiUrl = options.apiUrl || "https://api.comty.io";
   if (typeof projectKey !== "string" || !projectKey.trim()) {
     return Promise.reject(new TypeError("Comty: projectKey is required"));
   }
@@ -3675,7 +3685,7 @@ function initComty(options = {}) {
     const commentTargets = new Map();
 
     const {
-      matchesAnchorContext,
+      getStableAnchorId, matchesAnchorContext,
       resolveAnchor, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint,
     } = createAnchorMatcher({
       getElementTextSignature,
@@ -5168,8 +5178,11 @@ function initComty(options = {}) {
             }));
           } catch { /* Resume in comment mode if browser storage is unavailable. */ }
           const destination = new URL("/api/auth/sign-in/google", apiUrl);
-          destination.searchParams.set("callbackURL", loginUrl);
-          setTimeout(() => window.location.assign(guestAllowed ? destination.toString() : loginUrl), 50);
+          const authorizeUrl = new URL(loginUrl);
+          // Bootstrap may predate navigation within a single-page application.
+          authorizeUrl.searchParams.set("returnTo", window.location.href);
+          destination.searchParams.set("callbackURL", authorizeUrl.toString());
+          setTimeout(() => window.location.assign(destination.toString()), 50);
         };
       }
       const guestForm = backdrop.querySelector(".comty-guest-form");
@@ -5777,9 +5790,10 @@ function initComty(options = {}) {
       ) {
         let selector = currentEl.nodeName.toLowerCase();
 
-        if (currentEl.id && currentEl.id.length <= 160) {
+        const stableId = getStableAnchorId(currentEl.id);
+        if (stableId && stableId.length <= 160) {
           try {
-            selector += `#${CSS.escape(currentEl.id)}`;
+            selector += `#${CSS.escape(stableId)}`;
           } catch {
             // fallback
           }
@@ -5787,7 +5801,7 @@ function initComty(options = {}) {
 
         const stableAttributeSelector = getStableAttributeSelector(currentEl);
         if (
-          (!currentEl.id || currentEl.id.length > 160) &&
+          (!stableId || stableId.length > 160) &&
           stableAttributeSelector
         ) {
           selector += stableAttributeSelector;
@@ -5884,12 +5898,16 @@ function initComty(options = {}) {
       return el;
     }
 
-    function getElementTextSignature(el) {
+    function isEditableContent(el) {
+      return Boolean(el?.closest('input, textarea, select, [contenteditable]:not([contenteditable="false"])'));
+    }
+
+    function getElementTextSignature(el, staticText = false) {
       if (!el) return "";
       const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
       let text = "", node;
       while ((node = walker.nextNode()) && text.length < 480) {
-        if (!isComtyNode(node.parentElement)) text += ` ${node.textContent || ""}`;
+        if (!isComtyNode(node.parentElement) && !(staticText && isEditableContent(node.parentElement))) text += ` ${node.textContent || ""}`;
       }
       return text.replace(/\s+/g, " ").trim().slice(0, 240);
     }
@@ -5907,8 +5925,8 @@ function initComty(options = {}) {
         .slice(0, 8);
     }
 
-    function getElementOwnTextSignature(el) {
-      if (!el) return "";
+    function getElementOwnTextSignature(el, staticText = false) {
+      if (!el || (staticText && isEditableContent(el))) return "";
       return [...el.childNodes]
         .filter((node) => node.nodeType === Node.TEXT_NODE)
         .map((node) => node.textContent || "")
@@ -5922,11 +5940,12 @@ function initComty(options = {}) {
       return (el.getAttribute(attribute) || "").trim().slice(0, 240);
     }
 
-    function getSiblingFingerprint(el) {
+    function getSiblingFingerprint(el, staticText = false) {
       if (!(el instanceof Element)) return null;
       return {
         tag: el.tagName.toLowerCase(),
-        text: getElementOwnTextSignature(el) || getElementTextSignature(el),
+        ...(staticText ? { textMode: "static" } : {}),
+        text: getElementOwnTextSignature(el, staticText) || getElementTextSignature(el, staticText),
         ariaLabel: getAttributeSignature(el, "aria-label"),
         role: getAttributeSignature(el, "role"),
       };
@@ -5941,10 +5960,12 @@ function initComty(options = {}) {
 
       const fingerprint = {
         tag: el.tagName.toLowerCase(),
-        id: (el.id || "").slice(0, 160),
+        id: getStableAnchorId(el.id).slice(0, 160),
         classes: getElementClassList(el),
-        text: getElementTextSignature(el),
-        ownText: getElementOwnTextSignature(el),
+        // Keep editable values out of the field and every ancestor's identity.
+        textMode: "static",
+        text: getElementTextSignature(el, true),
+        ownText: getElementOwnTextSignature(el, true),
         role: getAttributeSignature(el, "role"),
         ariaLabel: getAttributeSignature(el, "aria-label"),
         name: getAttributeSignature(el, "name"),
@@ -5967,8 +5988,9 @@ function initComty(options = {}) {
       if (includeSiblings) {
         fingerprint.previousSibling = getSiblingFingerprint(
           el.previousElementSibling,
+          true,
         );
-        fingerprint.nextSibling = getSiblingFingerprint(el.nextElementSibling);
+        fingerprint.nextSibling = getSiblingFingerprint(el.nextElementSibling, true);
       }
 
       return fingerprint;
@@ -6187,33 +6209,6 @@ function initComty(options = {}) {
 
     const { captureViewportScreenshot } = createScreenshotCapture({ apiUrl, projectKey, getHeaders: getSdkHeaders });
 
-    async function uploadCommentScreenshot(comment, context, point) {
-      try {
-        const screenshot = await captureViewportScreenshot({ context, annotation: () => mountCaptureAnnotation(comment, point) });
-        if (!screenshot) return;
-        const formData = new FormData();
-        formData.append("projectKey", projectKey);
-        formData.append("screenshot", screenshot.blob, screenshot.blob.type === "image/jpeg" ? "comment.jpg" : "comment.png");
-        formData.append("screenshotWidth", String(screenshot.width));
-        formData.append("screenshotHeight", String(screenshot.height));
-        const response = await fetch(
-          `${apiUrl}/api/comments/${encodeURIComponent(comment.id)}/screenshot`,
-          { method: "POST", headers: getSdkHeaders(), body: formData },
-        );
-        if (!response.ok) throw new Error(`Screenshot upload failed (${response.status})`);
-        // Updating metadata must not redraw the page or interrupt a new draft.
-        const { screenshotUrl } = await response.json();
-        const cached = cachedComments.find(item => String(item.id) === String(comment.id));
-        if (cached) Object.assign(cached, {
-          screenshot_url: screenshotUrl,
-          screenshot_width: screenshot.width,
-          screenshot_height: screenshot.height,
-        });
-      } catch (error) {
-        console.warn("Comty: comment saved, screenshot unavailable", error);
-      }
-    }
-
     function addLocalComment(commentId, payload) {
       const comment = {
         id: commentId,
@@ -6681,13 +6676,26 @@ function initComty(options = {}) {
         if (draftAnchor === editorDraft) draftAnchor = null;
         syncPlacementCursor();
         hideInspector();
-        if (!isAgentTask) addLocalComment(pendingId, payload);
+        const pendingComment = isAgentTask ? null : addLocalComment(pendingId, payload);
         let post;
         try {
+          let body = JSON.stringify({ ...payload, projectKey });
+          let screenshot;
+          if (!isAgentTask) {
+            screenshot = await captureViewportScreenshot({ context, annotation: () => mountCaptureAnnotation(pendingComment, point) });
+            if (!screenshot) throw new Error("Screenshot unavailable. Keep this page visible and retry.");
+            body = new FormData();
+            for (const [key, value] of Object.entries(payload)) {
+              if (value != null) body.append(key, String(value));
+            }
+            body.append("screenshot", screenshot.blob, screenshot.blob.type === "image/jpeg" ? "comment.jpg" : "comment.png");
+            body.append("screenshotWidth", String(screenshot.width));
+            body.append("screenshotHeight", String(screenshot.height));
+          }
           post = await fetch(payload.kind === "agent" ? `${agentBridgeUrl}/tasks` : `${apiUrl}/api/comments`, {
             method: "POST",
-            headers: payload.kind === "agent" ? agentHeaders() : getSdkHeaders({ "Content-Type": "application/json" }),
-            body: JSON.stringify(payload.kind === "agent" ? { ...payload, projectKey } : payload),
+            headers: isAgentTask ? agentHeaders() : getSdkHeaders(),
+            body,
           });
           if (!post.ok) throw new Error(`Save failed (${post.status})`);
           const data = await post.json();
@@ -6700,7 +6708,7 @@ function initComty(options = {}) {
             cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
             if (context.url === location.href) {
               const comment = addLocalComment(String(id), payload);
-              void uploadCommentScreenshot(comment, context, point);
+              Object.assign(comment, { screenshot_url: data.screenshotUrl, screenshot_width: screenshot.width, screenshot_height: screenshot.height });
             } else void loadComments({ force: true });
           }
         } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comty.io/core",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Comty visual comments, inspector and local agent tools",
   "type": "module",
   "license": "UNLICENSED",
@@ -37,6 +37,7 @@
     "test:inspector": "node --test tests/inspector.browser.test.mjs tests/inspect-markup.browser.test.mjs tests/idle-network.browser.test.mjs",
     "test:placement": "node --test tests/placement.browser.test.mjs",
     "test:anchors": "node --test tests/anchors.test.mjs tests/anchor-reload.browser.test.mjs",
+    "test:auth": "node --test tests/auth-return.browser.test.mjs",
     "test:vite": "node --test tests/vite.test.mjs",
     "prepack": "npm run build"
   },

package/src/anchors.js

@@ -6,6 +6,11 @@ export function createAnchorMatcher({
   getPresentationLayer,
   isComtyNode,
 }) {
+    function getStableAnchorId(id) {
+      // React useId values change with mount order, including Base UI and Radix IDs.
+      return /^(?:(?:radix|base-ui)-)?(?:_r_[\w-]+_|:r[\w-]+:)$/i.test(id || "") ? "" : (id || "");
+    }
+
     function includesText(haystack, needle) {
       if (!haystack || !needle) return false;
       return haystack.toLowerCase().includes(needle.toLowerCase());
@@ -29,12 +34,13 @@ export function createAnchorMatcher({
       }
 
       let score = 0;
-      const text = getElementTextSignature(el);
-      const ownText = getElementOwnTextSignature(el);
+      const text = getElementTextSignature(el, fingerprint.textMode === "static");
+      const ownText = getElementOwnTextSignature(el, fingerprint.textMode === "static");
 
       score += 20;
-      if (fingerprint.id) {
-        score += el.id.slice(0, 160) === fingerprint.id ? 70 : -30;
+      const stableId = getStableAnchorId(fingerprint.id);
+      if (stableId) {
+        score += el.id.slice(0, 160) === stableId ? 70 : -30;
       }
       const exactAttributes = [
         ["role", "role", 24],
@@ -129,7 +135,7 @@ export function createAnchorMatcher({
 
     function scoreSibling(el, fingerprint) {
       if (!fingerprint) return 0;
-      const sibling = getSiblingFingerprint(el);
+      const sibling = getSiblingFingerprint(el, fingerprint.textMode === "static");
       if (!sibling || sibling.tag !== fingerprint.tag) return -4;
       let score = 4;
       if (fingerprint.ariaLabel && sibling.ariaLabel === fingerprint.ariaLabel) {
@@ -168,7 +174,7 @@ export function createAnchorMatcher({
           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;
+        if (ancestors[index].text && getElementTextSignature(parent, ancestors[index].textMode === "static") === ancestors[index].text) score += 18;
         parent = parent.parentElement;
       }
 
@@ -189,14 +195,17 @@ export function createAnchorMatcher({
       for (const [key, attribute] of Object.entries(attributes)) {
         if (fingerprint[key] && getAttributeSignature(el, attribute) !== fingerprint[key]) return false;
       }
-      if (fingerprint.id && el.id !== fingerprint.id) return false;
+      const stableId = getStableAnchorId(fingerprint.id);
+      if (stableId && el.id !== stableId) 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) ||
+      const stableIdentity = (stableId && el.id === stableId) ||
         (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;
+      const staticText = fingerprint.textMode === "static";
+      const text = getElementTextSignature(el, staticText);
+      if (fingerprint.ownText && getElementOwnTextSignature(el, staticText) !== fingerprint.ownText && !(allowTextChanges && stableIdentity)) return false;
       // Container text is useful for matching remounted drawers and dialogs.
-      if (!ignoreDescendantText && !fingerprint.ownText && fingerprint.text && getElementTextSignature(el) !== fingerprint.text && !(allowTextChanges && stableIdentity)) {
-        if (!allowTextChanges || !el.children.length || !similarText(getElementTextSignature(el), fingerprint.text)) return false;
+      if (!ignoreDescendantText && !fingerprint.ownText && fingerprint.text && text !== fingerprint.text && !(allowTextChanges && stableIdentity)) {
+        if (!allowTextChanges || !el.children.length || !similarText(text, fingerprint.text)) return false;
       }
       return true;
     }
@@ -229,10 +238,11 @@ export function createAnchorMatcher({
         .map(el => ({ el, score: scoreAnchorCandidate(el, context) + (context.version === 1 && el === exact ? 16 : 0) }))
         .sort((a, b) => b.score - a.score);
       if (context.candidateCount > 1) {
+        // Creation counts full context matches, not every element with the same text.
         const peers = candidates.filter(el => matchesAnchorIdentity(el, context.target));
-        if (peers.length !== context.candidateCount) {
+        if (matches.length !== context.candidateCount && 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);
+          const distinctive = matches[0] && (getStableAnchorId(context.target.id) || context.target.testId);
           if (!distinctive) return { element: null, status: "uncertain" };
         }
       }
@@ -245,8 +255,8 @@ export function createAnchorMatcher({
         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))));
+        (getStableAnchorId(context.target.id) && el.id === context.target.id) ||
+        (context.target.text && (getElementTextSignature(el, context.target.textMode === "static") === context.target.text || similarText(getElementTextSignature(el, context.target.textMode === "static"), context.target.text))));
       return { element: null, status: plausible ? "uncertain" : "missing" };
     }
 
@@ -423,5 +433,5 @@ export function createAnchorMatcher({
       return { clientX, clientY };
     }
 
-    return { matchesAnchorContext, resolveAnchor, resolveByAnchorContext, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint };
+    return { getStableAnchorId, matchesAnchorContext, resolveAnchor, resolveByAnchorContext, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint };
 }

package/src/browser.d.ts

@@ -1,7 +1,7 @@
 export interface ComtyOptions {
   /** Project key from your Comty dashboard. */
   projectKey?: string;
-  /** Absolute URL of your Comty API. Defaults to http://localhost:4000. */
+  /** Defaults to https://api.comty.io. Override for a local or self-hosted Comty API. */
   apiUrl?: string;
   /** Set automatically by comty dev; not needed in application code. */
   agent?: { url: string; token: string };

package/src/browser.js

@@ -21,7 +21,7 @@ export function initComty(options = {}) {
     } catch { return Promise.reject(new TypeError("Comty: companion must share the page origin")); }
   }
   const projectKey = options.projectKey || (agent ? "local" : undefined);
-  const apiUrl = options.apiUrl || "http://localhost:4000";
+  const apiUrl = options.apiUrl || "https://api.comty.io";
   if (typeof projectKey !== "string" || !projectKey.trim()) {
     return Promise.reject(new TypeError("Comty: projectKey is required"));
   }
@@ -111,7 +111,7 @@ export function initComty(options = {}) {
     const commentTargets = new Map();
 
     const {
-      matchesAnchorContext,
+      getStableAnchorId, matchesAnchorContext,
       resolveAnchor, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint,
     } = createAnchorMatcher({
       getElementTextSignature,
@@ -1604,8 +1604,11 @@ export function initComty(options = {}) {
             }));
           } catch { /* Resume in comment mode if browser storage is unavailable. */ }
           const destination = new URL("/api/auth/sign-in/google", apiUrl);
-          destination.searchParams.set("callbackURL", loginUrl);
-          setTimeout(() => window.location.assign(guestAllowed ? destination.toString() : loginUrl), 50);
+          const authorizeUrl = new URL(loginUrl);
+          // Bootstrap may predate navigation within a single-page application.
+          authorizeUrl.searchParams.set("returnTo", window.location.href);
+          destination.searchParams.set("callbackURL", authorizeUrl.toString());
+          setTimeout(() => window.location.assign(destination.toString()), 50);
         };
       }
       const guestForm = backdrop.querySelector(".comty-guest-form");
@@ -2213,9 +2216,10 @@ export function initComty(options = {}) {
       ) {
         let selector = currentEl.nodeName.toLowerCase();
 
-        if (currentEl.id && currentEl.id.length <= 160) {
+        const stableId = getStableAnchorId(currentEl.id);
+        if (stableId && stableId.length <= 160) {
           try {
-            selector += `#${CSS.escape(currentEl.id)}`;
+            selector += `#${CSS.escape(stableId)}`;
           } catch {
             // fallback
           }
@@ -2223,7 +2227,7 @@ export function initComty(options = {}) {
 
         const stableAttributeSelector = getStableAttributeSelector(currentEl);
         if (
-          (!currentEl.id || currentEl.id.length > 160) &&
+          (!stableId || stableId.length > 160) &&
           stableAttributeSelector
         ) {
           selector += stableAttributeSelector;
@@ -2320,12 +2324,16 @@ export function initComty(options = {}) {
       return el;
     }
 
-    function getElementTextSignature(el) {
+    function isEditableContent(el) {
+      return Boolean(el?.closest('input, textarea, select, [contenteditable]:not([contenteditable="false"])'));
+    }
+
+    function getElementTextSignature(el, staticText = false) {
       if (!el) return "";
       const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
       let text = "", node;
       while ((node = walker.nextNode()) && text.length < 480) {
-        if (!isComtyNode(node.parentElement)) text += ` ${node.textContent || ""}`;
+        if (!isComtyNode(node.parentElement) && !(staticText && isEditableContent(node.parentElement))) text += ` ${node.textContent || ""}`;
       }
       return text.replace(/\s+/g, " ").trim().slice(0, 240);
     }
@@ -2343,8 +2351,8 @@ export function initComty(options = {}) {
         .slice(0, 8);
     }
 
-    function getElementOwnTextSignature(el) {
-      if (!el) return "";
+    function getElementOwnTextSignature(el, staticText = false) {
+      if (!el || (staticText && isEditableContent(el))) return "";
       return [...el.childNodes]
         .filter((node) => node.nodeType === Node.TEXT_NODE)
         .map((node) => node.textContent || "")
@@ -2358,11 +2366,12 @@ export function initComty(options = {}) {
       return (el.getAttribute(attribute) || "").trim().slice(0, 240);
     }
 
-    function getSiblingFingerprint(el) {
+    function getSiblingFingerprint(el, staticText = false) {
       if (!(el instanceof Element)) return null;
       return {
         tag: el.tagName.toLowerCase(),
-        text: getElementOwnTextSignature(el) || getElementTextSignature(el),
+        ...(staticText ? { textMode: "static" } : {}),
+        text: getElementOwnTextSignature(el, staticText) || getElementTextSignature(el, staticText),
         ariaLabel: getAttributeSignature(el, "aria-label"),
         role: getAttributeSignature(el, "role"),
       };
@@ -2377,10 +2386,12 @@ export function initComty(options = {}) {
 
       const fingerprint = {
         tag: el.tagName.toLowerCase(),
-        id: (el.id || "").slice(0, 160),
+        id: getStableAnchorId(el.id).slice(0, 160),
         classes: getElementClassList(el),
-        text: getElementTextSignature(el),
-        ownText: getElementOwnTextSignature(el),
+        // Keep editable values out of the field and every ancestor's identity.
+        textMode: "static",
+        text: getElementTextSignature(el, true),
+        ownText: getElementOwnTextSignature(el, true),
         role: getAttributeSignature(el, "role"),
         ariaLabel: getAttributeSignature(el, "aria-label"),
         name: getAttributeSignature(el, "name"),
@@ -2403,8 +2414,9 @@ export function initComty(options = {}) {
       if (includeSiblings) {
         fingerprint.previousSibling = getSiblingFingerprint(
           el.previousElementSibling,
+          true,
         );
-        fingerprint.nextSibling = getSiblingFingerprint(el.nextElementSibling);
+        fingerprint.nextSibling = getSiblingFingerprint(el.nextElementSibling, true);
       }
 
       return fingerprint;
@@ -2623,33 +2635,6 @@ export function initComty(options = {}) {
 
     const { captureViewportScreenshot } = createScreenshotCapture({ apiUrl, projectKey, getHeaders: getSdkHeaders });
 
-    async function uploadCommentScreenshot(comment, context, point) {
-      try {
-        const screenshot = await captureViewportScreenshot({ context, annotation: () => mountCaptureAnnotation(comment, point) });
-        if (!screenshot) return;
-        const formData = new FormData();
-        formData.append("projectKey", projectKey);
-        formData.append("screenshot", screenshot.blob, screenshot.blob.type === "image/jpeg" ? "comment.jpg" : "comment.png");
-        formData.append("screenshotWidth", String(screenshot.width));
-        formData.append("screenshotHeight", String(screenshot.height));
-        const response = await fetch(
-          `${apiUrl}/api/comments/${encodeURIComponent(comment.id)}/screenshot`,
-          { method: "POST", headers: getSdkHeaders(), body: formData },
-        );
-        if (!response.ok) throw new Error(`Screenshot upload failed (${response.status})`);
-        // Updating metadata must not redraw the page or interrupt a new draft.
-        const { screenshotUrl } = await response.json();
-        const cached = cachedComments.find(item => String(item.id) === String(comment.id));
-        if (cached) Object.assign(cached, {
-          screenshot_url: screenshotUrl,
-          screenshot_width: screenshot.width,
-          screenshot_height: screenshot.height,
-        });
-      } catch (error) {
-        console.warn("Comty: comment saved, screenshot unavailable", error);
-      }
-    }
-
     function addLocalComment(commentId, payload) {
       const comment = {
         id: commentId,
@@ -3117,13 +3102,26 @@ export function initComty(options = {}) {
         if (draftAnchor === editorDraft) draftAnchor = null;
         syncPlacementCursor();
         hideInspector();
-        if (!isAgentTask) addLocalComment(pendingId, payload);
+        const pendingComment = isAgentTask ? null : addLocalComment(pendingId, payload);
         let post;
         try {
+          let body = JSON.stringify({ ...payload, projectKey });
+          let screenshot;
+          if (!isAgentTask) {
+            screenshot = await captureViewportScreenshot({ context, annotation: () => mountCaptureAnnotation(pendingComment, point) });
+            if (!screenshot) throw new Error("Screenshot unavailable. Keep this page visible and retry.");
+            body = new FormData();
+            for (const [key, value] of Object.entries(payload)) {
+              if (value != null) body.append(key, String(value));
+            }
+            body.append("screenshot", screenshot.blob, screenshot.blob.type === "image/jpeg" ? "comment.jpg" : "comment.png");
+            body.append("screenshotWidth", String(screenshot.width));
+            body.append("screenshotHeight", String(screenshot.height));
+          }
           post = await fetch(payload.kind === "agent" ? `${agentBridgeUrl}/tasks` : `${apiUrl}/api/comments`, {
             method: "POST",
-            headers: payload.kind === "agent" ? agentHeaders() : getSdkHeaders({ "Content-Type": "application/json" }),
-            body: JSON.stringify(payload.kind === "agent" ? { ...payload, projectKey } : payload),
+            headers: isAgentTask ? agentHeaders() : getSdkHeaders(),
+            body,
           });
           if (!post.ok) throw new Error(`Save failed (${post.status})`);
           const data = await post.json();
@@ -3136,7 +3134,7 @@ export function initComty(options = {}) {
             cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
             if (context.url === location.href) {
               const comment = addLocalComment(String(id), payload);
-              void uploadCommentScreenshot(comment, context, point);
+              Object.assign(comment, { screenshot_url: data.screenshotUrl, screenshot_width: screenshot.width, screenshot_height: screenshot.height });
             } else void loadComments({ force: true });
           }
         } catch (error) {