opencode-browser-annotation-plugin 0.4.0 → 0.5.0

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.0",
   "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

@@ -228,9 +228,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}]`;
+    if (el.classList && el.classList.length) s += "." + Array.from(el.classList).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,
@@ -246,9 +336,14 @@
       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;
   }
 
@@ -548,7 +643,7 @@
     sb.style.display = "flex";
     renderCards();
     refreshStatus();
-    if (!statusTimer) statusTimer = setInterval(refreshStatus, 15000);
+    if (!statusTimer) statusTimer = setInterval(refreshStatus, 3500);
   }
 
   function closeSidebar() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-browser-annotation-plugin",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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",