opencode-browser-annotation-plugin 0.4.0 → 0.5.1

package/dist/plugin.js

@@ -54,6 +54,12 @@ function formatElement(el) {
         lines.push(`  src: ${el.src}`);
     if (el.text)
         lines.push(`  text: ${JSON.stringify(truncate(el.text.trim(), 200))}`);
+    if (el.componentPath)
+        lines.push(`  ${el.framework ?? "component"} components: ${el.componentPath}`);
+    if (el.landmark)
+        lines.push(`  nearest region: ${el.landmark}`);
+    if (el.ancestors && el.ancestors.length)
+        lines.push(`  ancestors (nearest first): ${el.ancestors.join(" < ")}`);
     if (el.selector)
         lines.push(`  css path: ${el.selector}`);
     const context = [];
@@ -96,7 +102,8 @@ function buildPrompt(annotations) {
         ...blocks,
         "",
         "Guidance:",
-        "- Locate the code for each element using the most stable identifier available (data-testid, id, name, role, then unique class or text). Treat the CSS path and viewport bounds as weak hints only.",
+        "- Locate the code for each element using the most stable identifier available: framework component path first if given, then data-testid, id, name, role, then the ancestor chain and nearest region to disambiguate, then unique class or text. Treat the CSS path and viewport bounds as weak hints only.",
+        "- Use the ancestors and nearest region to find the right component/file when the element itself is generic (e.g. a bare button that appears many times).",
         "- Confirm the element actually exists in this codebase before editing; if you cannot find it, say so instead of guessing.",
         "- No screenshot is attached; reason from the metadata and the code.",
     ].join("\n");
@@ -143,30 +150,51 @@ export const BrowserAnnotationPlugin = async ({ client, directory }) => {
     const port = envPort();
     let activeSessionID = null;
     let server = null;
+    // Sessions that showed activity in THIS OpenCode run (created, messaged, or
+    // status/idle events). OpenCode has no open/closed flag, so this approximates
+    // "sessions you're currently working in". Deleted sessions are removed.
+    const activeIDs = new Set();
+    const RECENT_FALLBACK_MS = 2 * 60 * 60 * 1000; // 2h
+    const RECENT_FALLBACK_MAX = 8;
     const log = (level, message, extra) => {
         void client.app
             .log({ body: { service: "browser-annotation", level, message, extra } })
             .catch(() => { });
     };
-    /**
-     * All sessions live in this one OpenCode process, so the plugin can address
-     * any of them by id — a single HTTP port/tunnel does not limit targeting.
-     * Returns top-level sessions (no parentID), most-recently-updated first.
-     */
-    async function listSessions() {
+    async function allSessions() {
         try {
             const res = (await client.session.list({ query: { directory } }));
             const rows = Array.isArray(res) ? res : Array.isArray(res?.data) ? res.data : [];
             return rows
                 .filter((s) => s && typeof s.id === "string" && !s.parentID)
-                .map((s) => ({ id: s.id, title: typeof s.title === "string" ? s.title : s.id, updated: s.time?.updated ?? 0 }))
-                .sort((a, b) => b.updated - a.updated);
+                .map((s) => ({ id: s.id, title: typeof s.title === "string" ? s.title : s.id, updated: s.time?.updated ?? 0 }));
         }
         catch (error) {
             log("warn", `session.list failed: ${error instanceof Error ? error.message : "unknown"}`);
             return [];
         }
     }
+    /**
+     * The picker list: sessions active in this run (newest first). If none have
+     * been observed yet (e.g. right after a restart), fall back to the most
+     * recently updated few so the picker is not empty. All live in this one
+     * process, so any can be targeted over the single port.
+     */
+    async function listSessions() {
+        const all = await allSessions();
+        const byRecent = [...all].sort((a, b) => b.updated - a.updated);
+        // Prune ids that no longer exist.
+        const existing = new Set(all.map((s) => s.id));
+        for (const id of activeIDs)
+            if (!existing.has(id))
+                activeIDs.delete(id);
+        if (activeIDs.size > 0) {
+            return byRecent.filter((s) => activeIDs.has(s.id));
+        }
+        const now = Date.now();
+        const recent = byRecent.filter((s) => now - s.updated < RECENT_FALLBACK_MS).slice(0, RECENT_FALLBACK_MAX);
+        return recent.length ? recent : byRecent.slice(0, RECENT_FALLBACK_MAX);
+    }
     async function injectPrompt(sessionID, annotations) {
         try {
             await client.session.promptAsync({
@@ -269,12 +297,36 @@ export const BrowserAnnotationPlugin = async ({ client, directory }) => {
     start();
     return {
         "chat.message": async (input) => {
-            if (input?.sessionID)
+            if (input?.sessionID) {
                 activeSessionID = input.sessionID;
+                activeIDs.add(input.sessionID);
+            }
         },
         event: async ({ event }) => {
-            if (event.type === "session.deleted") {
-                if (event.properties.info.id === activeSessionID)
+            if (event.type === "session.created") {
+                const id = event.properties.info.id;
+                if (id)
+                    activeIDs.add(id);
+            }
+            else if (event.type === "session.updated") {
+                const id = event.properties.info.id;
+                if (id)
+                    activeIDs.add(id);
+            }
+            else if (event.type === "session.status") {
+                const id = event.properties.sessionID;
+                if (id)
+                    activeIDs.add(id);
+            }
+            else if (event.type === "session.idle") {
+                const id = event.properties.sessionID;
+                if (id)
+                    activeIDs.add(id);
+            }
+            else if (event.type === "session.deleted") {
+                const id = event.properties.info.id;
+                activeIDs.delete(id);
+                if (id === activeSessionID)
                     activeSessionID = null;
             }
         },

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "OpenCode Browser Annotation",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Alt+A to annotate an element, Alt+Shift+A for the annotation list. Sends element metadata to your OpenCode agent.",
   "permissions": [
     "activeTab",

package/extension/overlay.js

@@ -139,6 +139,7 @@
   let sessions = []; // [{ id, title, updated }]
   let targetSessionID = null; // user-chosen target; null = auto (last active)
   let autoSessionID = null; // the plugin's last-active session
+  let lastStatusState = null; // "good" | "bad" | "checking" | null; avoids flicker
 
   // A content script keeps running after its extension is reloaded/updated, but
   // its chrome.* calls then throw "Extension context invalidated". Guard every
@@ -203,6 +204,25 @@
     return undefined;
   }
 
+  // Drop build-generated/hashed class names (CSS Modules, styled-components,
+  // Emotion, etc.). They change every build and don't map to source, so they are
+  // noise for locating code. Keep human-authored classes like "heading-element".
+  function isHashedClass(c) {
+    if (!c) return true;
+    if (/module__/i.test(c)) return true; // CSS Modules: Foo-module__Bar__hHXUL
+    if (/__[A-Za-z0-9]{4,}$/.test(c)) return true; // trailing __hash
+    if (/^css-[a-z0-9]{5,}$/i.test(c)) return true; // Emotion: css-1ab2c3
+    if (/^sc-[A-Za-z0-9]{5,}$/.test(c)) return true; // styled-components: sc-bdVaJa
+    if (/^[A-Za-z0-9]{7,}$/.test(c) && /[0-9]/.test(c) && /[A-Z]/.test(c)) return true; // mixed-case+digit opaque hash
+    return false;
+  }
+
+  function cleanClasses(list) {
+    if (!list || !list.length) return undefined;
+    const kept = list.filter((c) => !isHashedClass(c));
+    return kept.length ? kept : undefined;
+  }
+
   function cssPath(el) {
     if (!(el instanceof Element)) return "";
     if (el.id) return `#${CSS.escape(el.id)}`;
@@ -228,9 +248,99 @@
     return parts.join(" > ");
   }
 
+  // A compact one-line signature of an element: tag + the most locating bits.
+  function elemSignature(el) {
+    if (!(el instanceof Element)) return "";
+    let s = el.tagName.toLowerCase();
+    const tid = bestTestId(el);
+    if (tid) s += `[data-testid=${tid}]`;
+    else if (el.id) s += `#${el.id}`;
+    const role = el.getAttribute && el.getAttribute("role");
+    if (role) s += `[role=${role}]`;
+    const cls = cleanClasses(el.classList ? Array.from(el.classList) : []);
+    if (cls) s += "." + cls.slice(0, 3).join(".");
+    return s;
+  }
+
+  // Ancestor chain from the parent up to (but excluding) <body>, piercing shadow
+  // roots. Nearest first. Gives the agent "where in the tree" this element is.
+  function ancestorChain(el, max = 6) {
+    const chain = [];
+    let node = el.parentElement || (el.getRootNode && el.getRootNode().host) || null;
+    while (node && node.nodeType === 1 && chain.length < max) {
+      const tag = node.tagName ? node.tagName.toLowerCase() : "";
+      if (tag === "body" || tag === "html") break;
+      chain.push(elemSignature(node));
+      node = node.parentElement || (node.getRootNode && node.getRootNode() instanceof ShadowRoot ? node.getRootNode().host : null);
+    }
+    return chain;
+  }
+
+  // Nearest semantic landmark/region ancestor (main, nav, header, dialog, form,
+  // or any element with a data-component / data-testid). Tells the agent which
+  // feature/region of the page the element belongs to.
+  function nearestLandmark(el) {
+    const landmarkTags = new Set(["main", "nav", "header", "footer", "aside", "section", "article", "form", "dialog"]);
+    const landmarkRoles = new Set(["main", "navigation", "banner", "contentinfo", "dialog", "form", "search", "region"]);
+    let node = el.parentElement;
+    while (node && node.nodeType === 1) {
+      const tag = node.tagName.toLowerCase();
+      const role = node.getAttribute("role");
+      const comp = node.getAttribute("data-component") || node.getAttribute("data-testid");
+      if (landmarkTags.has(tag) || (role && landmarkRoles.has(role)) || comp) {
+        return elemSignature(node);
+      }
+      if (tag === "body") break;
+      node = node.parentElement;
+    }
+    return undefined;
+  }
+
+  // Best-effort framework component path (React/Preact fiber, or Vue). Returns
+  // e.g. "App > Dashboard > SignupCard". Absent on non-framework pages.
+  function frameworkComponents(el) {
+    try {
+      const keys = Object.keys(el);
+      const fiberKey = keys.find((k) => k.startsWith("__reactFiber$") || k.startsWith("__reactInternalInstance$"));
+      if (fiberKey) {
+        const names = [];
+        let cur = el[fiberKey];
+        let depth = 0;
+        while (cur && depth < 12) {
+          const t = cur.type;
+          let name = null;
+          if (typeof t === "function") name = t.displayName || t.name || null;
+          else if (t && typeof t === "object") name = (t.render && (t.render.displayName || t.render.name)) || (t.type && (t.type.displayName || t.type.name)) || null;
+          if (name && !name.startsWith("_") && name !== "Fragment") names.unshift(name);
+          cur = cur.return;
+          depth++;
+        }
+        if (names.length) return { framework: "react", path: names.slice(-6).join(" > ") };
+      }
+      // Vue 3 exposes __vueParentComponent; Vue 2 exposes __vue__.
+      let vnode = el.__vueParentComponent || (el.__vue__ && el.__vue__.$);
+      if (vnode) {
+        const names = [];
+        let cur = vnode;
+        let depth = 0;
+        while (cur && depth < 12) {
+          const type = cur.type || (cur.$options && cur.$options);
+          const name = (type && (type.name || type.__name)) || (cur.$options && cur.$options.name) || null;
+          if (name) names.unshift(name);
+          cur = cur.parent || (cur.$parent && cur.$parent.$);
+          depth++;
+        }
+        if (names.length) return { framework: "vue", path: names.slice(-6).join(" > ") };
+      }
+    } catch {
+      /* ignore */
+    }
+    return undefined;
+  }
+
   function elementMeta(el, inShadow) {
     const r = el.getBoundingClientRect();
-    const classes = el.classList ? Array.from(el.classList) : [];
+    const fw = frameworkComponents(el);
     const m = {
       selector: cssPath(el),
       tag: el.tagName,
@@ -239,16 +349,21 @@
       testId: bestTestId(el),
       role: el.getAttribute("role") || undefined,
       ariaLabel: el.getAttribute("aria-label") || undefined,
-      classes: classes.length ? classes : undefined,
+      classes: cleanClasses(el.classList ? Array.from(el.classList) : []),
       text: (el.textContent || "").trim().slice(0, 500) || undefined,
       href: el.getAttribute("href") || undefined,
       src: el.getAttribute("src") || undefined,
       bounds: { x: r.left, y: r.top, width: r.width, height: r.height },
       inShadow: Boolean(inShadow),
       inIframe: window.top !== window.self,
+      ancestors: ancestorChain(el),
+      landmark: nearestLandmark(el),
+      componentPath: fw ? fw.path : undefined,
+      framework: fw ? fw.framework : undefined,
       html: (el.outerHTML || "").slice(0, 800),
     };
     for (const k of Object.keys(m)) if (m[k] === undefined) delete m[k];
+    if (Array.isArray(m.ancestors) && m.ancestors.length === 0) delete m.ancestors;
     return m;
   }
 
@@ -276,18 +391,22 @@
             const pad = 6 * dpr;
             let sx = Math.max(0, rect.left * dpr - pad);
             let sy = Math.max(0, rect.top * dpr - pad);
-            let sw = Math.min(img.width - sx, rect.width * dpr + pad * 2);
-            let sh = Math.min(img.height - sy, rect.height * dpr + pad * 2);
+            const sw = Math.min(img.width - sx, rect.width * dpr + pad * 2);
+            const sh = Math.min(img.height - sy, rect.height * dpr + pad * 2);
             if (sw <= 0 || sh <= 0) return resolve(null);
-            // cap output size for a compact list thumbnail
-            const maxW = 300;
+            // Keep the crop at (up to) full captured resolution so it stays sharp
+            // on the sidebar's HiDPI display. Only downscale if it's very large,
+            // to keep the data URL reasonable.
+            const maxW = 900;
             const scale = Math.min(1, maxW / sw);
-            const cw = Math.round(sw * scale);
-            const ch = Math.round(sh * scale);
+            const cw = Math.max(1, Math.round(sw * scale));
+            const ch = Math.max(1, Math.round(sh * scale));
             const c = document.createElement("canvas");
             c.width = cw;
             c.height = ch;
             const ctx = c.getContext("2d");
+            ctx.imageSmoothingEnabled = true;
+            ctx.imageSmoothingQuality = "high";
             ctx.drawImage(img, sx, sy, sw, sh, 0, 0, cw, ch);
             resolve(c.toDataURL("image/png"));
           } catch {
@@ -525,7 +644,7 @@
         </div>`;
       root.appendChild(sb);
       sb.querySelector("#oc-close").addEventListener("click", closeSidebar);
-      sb.querySelector("#oc-pick").addEventListener("click", () => startPicking());
+      sb.querySelector("#oc-pick").addEventListener("click", () => (picking ? stopPicking() : startPicking()));
       sb.querySelector("#oc-dd-btn").addEventListener("click", (e) => {
         e.stopPropagation();
         sb.querySelector("#oc-dd").classList.toggle("open");
@@ -548,7 +667,7 @@
     sb.style.display = "flex";
     renderCards();
     refreshStatus();
-    if (!statusTimer) statusTimer = setInterval(refreshStatus, 15000);
+    if (!statusTimer) statusTimer = setInterval(refreshStatus, 3500);
   }
 
   function closeSidebar() {
@@ -559,6 +678,7 @@
       clearInterval(statusTimer);
       statusTimer = null;
     }
+    lastStatusState = null; // re-check cleanly on reopen
   }
 
   function toggleSidebar() {
@@ -598,27 +718,33 @@
 
   // ---------- status + submit ----------
 
+  // Apply a status only when it actually changes, so routine polls don't make
+  // the text flicker. Only the very first check shows "Checking…".
+  function setStatus(state, text) {
+    const el = root && root.getElementById("oc-status");
+    if (!el) return;
+    if (lastStatusState === state) return; // stable during polls
+    lastStatusState = state;
+    el.className = `oc-status ${state}`;
+    el.textContent = text;
+  }
+
   function refreshStatus() {
     if (!root) return;
-    const el = root.getElementById("oc-status");
-    if (!el) return;
-    el.className = "oc-status checking";
-    el.textContent = "Checking connection…";
+    if (lastStatusState === null) setStatus("checking", "Checking connection…");
     sendMsg({ type: "oc-status" }, (res) => {
       if (!res) {
-        el.className = "oc-status bad";
-        el.textContent = "Extension error";
+        setStatus("bad", "Extension error");
         return;
       }
       if (res.ok && res.data?.ok) {
+        // Session list updates every poll; the status text stays stable.
         sessions = Array.isArray(res.data.sessions) ? res.data.sessions : [];
         autoSessionID = res.data.sessionID || null;
         renderSessions();
-        el.className = "oc-status good";
-        el.textContent = "Connected";
+        setStatus("good", "Connected");
       } else {
-        el.className = "oc-status bad";
-        el.textContent = "Not connected — check the SSH tunnel";
+        setStatus("bad", "Not connected — check the SSH tunnel");
       }
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-browser-annotation-plugin",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Select an element in your browser, type an instruction, and send it to your OpenCode agent over a loopback + SSH tunnel. Text and element metadata only (no screenshots).",
   "keywords": [
     "opencode",