@archie/devtools 0.0.36 → 0.0.37

package/dist/inspector.standalone.js

@@ -1527,80 +1527,172 @@
         }
       }
 
+      // ─────────────────────────────────────────────────────────────────
+      // THE HANDSHAKE PAYLOAD — ONE BUILDER, THREE EMISSIONS.
+      //
+      // `INSPECTOR_SCRIPT_LOADED` is emitted exactly ONCE per execution of
+      // this script and is never replayed. A host whose `message` listener
+      // is not attached yet when it fires loses it IRRECOVERABLY, and with
+      // it every `capabilities` bit — including `bindingContract`, the one
+      // that decides whether a text edit on a data row is writable or gets
+      // the "Regenerate this prototype" refusal. That race is real and
+      // routinely lost after a host page refresh: this page is served warm
+      // from the CDN while the host still resolves the async probe that
+      // decides whether to mount its bridge at all.
+      //
+      // The cure is to make the announcement RECOVERABLE, by two
+      // independent routes that both reuse THIS builder (never a
+      // second, drifting literal):
+      //   1. PULL — the host asks (`QUERY_CAPABILITIES`) and gets
+      //      `CAPABILITIES_RESULT` back, correlated by `requestId`.
+      //   2. PUSH — every `SET_EDITOR_MODE`/`SYNC_EDITOR_STATE` re-announces
+      //      `CAPABILITIES_RESULT` (unsolicited, `requestId: null`) BEFORE
+      //      its `EDITOR_MODE_CHANGED`, so a host that lost the handshake
+      //      is healed by the message it was already going to send, without
+      //      knowing the new message exists.
+      // Both are idempotent: they report state, they never mutate it.
+      // ─────────────────────────────────────────────────────────────────
+      function buildInspectorHandshakePayload() {
+        return {
+          // 2.2.0 (ARCH-1065): additive only — `bindingChain` on element data,
+          // `QUERY_SLICE_FIELD` in the message protocol, and
+          // `capabilities.bindingContract` below. No existing field changed
+          // shape, so `protocolVersion` stays 1.
+          // 2.3.0 (ARCH-1065 A17-support): additive only — `QUERY_COLLECTION_ORDER`
+          // in the message protocol and `capabilities.collectionOrderQuery`
+          // below. No existing field changed shape, so `protocolVersion` stays 1.
+          // 2.4.0 (ARCH-883-KOI, CREW round): additive only — `origin` on
+          // `EditorMeta`, the usage-projected `ownMetaNodeId`/`inspectorSource`/
+          // `editorInstance` resolution, and `capabilities.kitOriginIdentity`
+          // below. No existing field changed shape, so `protocolVersion` stays 1.
+          // 2.5.0: additive only — `CONFIGURE_INSPECTOR` inbound (labels +
+          // permissions), and the `CHAT_CONTEXT_REQUESTED` /
+          // `ADD_COMMENT_REQUESTED` outbound pair behind the right-click menu
+          // (`capabilities.contextMenuActions` below). No existing field
+          // changed shape, so `protocolVersion` stays 1.
+          // 2.6.0: additive only — `QUERY_CAPABILITIES` inbound, the
+          // `CAPABILITIES_RESULT` outbound it answers with (also pushed
+          // unsolicited on every editor-mode command), and
+          // `capabilities.capabilitiesQuery` below. No existing field
+          // changed shape, so `protocolVersion` stays 1.
+          version: "2.6.0",
+          protocolVersion: 1,
+          capabilities: {
+            // 2.1.1: function-valued __editorMeta props are invoked before any
+            // postMessage, so meta payloads stay structured-cloneable. Hosts can
+            // gate on this bit to confirm the deployed CDN artifact carries the
+            // fix (the 2.1.0 URL is overwritten in place on publish).
+            functionValuedEditorMeta: true,
+            inspect: true,
+            dndMove: true,
+            dndResize: true,
+            fiberInspectorSource: true,
+            hostControlledHistory: true,
+            arrangeStructuredHistory: true,
+            arrangeStrongNodeIdentity: true,
+            // Unified mode: SET_EDITOR_MODE "inspect" also enables the arrange
+            // (design) runtime — selection and drag/resize coexist. Hosts MUST
+            // feature-detect on this flag: a frozen 2.0.x inspector disables
+            // design mode on "inspect" and needs the legacy "design" mode.
+            unifiedInspectArrange: true,
+            // ARCH-1065: the M2 codemod's data-agent-* grammar is readable
+            // (`bindingChain` on element data) and slice-field-queryable
+            // (`QUERY_SLICE_FIELD`). Hosts MUST feature-detect on this flag
+            // before relying on either — a frozen pre-1065 inspector has
+            // neither.
+            collectionBinding: true,
+            // ARCH-1065 A17-support (v2.3.0): `QUERY_COLLECTION_ORDER` resolves
+            // the enclosing collection's order ("stable"/"derived") and row
+            // ids/count for a target node, off the same data-agent-* grammar
+            // as `collectionBinding`. Hosts MUST feature-detect on this flag —
+            // a frozen pre-2.3.0 inspector has no handler for the message.
+            collectionOrderQuery: true,
+            // Host draw mode: the inspector can map a drawn rect to the
+            // elements under it (`QUERY_ELEMENTS_IN_RECT` →
+            // `ELEMENTS_IN_RECT_RESULT`) and rasterize its own viewport
+            // (`CAPTURE_VIEWPORT` → `VIEWPORT_CAPTURED`). Hosts MUST
+            // feature-detect: a frozen earlier inspector has no handler for
+            // either message and would never reply.
+            rectElementQuery: true,
+            // Best-effort by construction — the foreignObject round-trip drops
+            // web fonts, cross-origin images and <canvas> pixels, and answers
+            // VIEWPORT_CAPTURE_FAILED when the rasterization throws.
+            viewportCapture: true,
+            // The BUILD-TIME contract version this specific page was stamped
+            // with, forwarded verbatim from `<meta name="archie-binding-contract">`
+            // when the kit build emitted one — null on any page built before
+            // that meta tag existed, or that never carried collection-bound
+            // data. Opaque to this script: validating/interpreting the value is
+            // the host's job (mirrors how `slot` and `bindingContract` — plural
+            // concept, singular mechanism — are treated as opaque strings
+            // elsewhere in this file).
+            bindingContract: readBindingContractMeta(),
+            // ARCH-883-KOI F4 (v2.4.0) — this SCRIPT resolves `EditorMeta.origin`
+            // and projects identity across an instrumented kit boundary
+            // (`ownMetaNodeId`, `projectUsageMetaFromElement`,
+            // `getInspectorInfoFromElement`, `resolveInstanceIdentity`). Hosts
+            // MUST feature-detect on this flag before trusting `origin`
+            // (absent or `editorMeta.origin === 'kit'`) as meaningful: a frozen
+            // pre-2.4.0 inspector never reads the field at all, so its
+            // `inspectorSource`/`editorInstance` on an instrumented-kit page
+            // reproduce the exact F1 bug this version fixes.
+            //
+            // What this bit CANNOT tell the host: whether the PAGE's own build
+            // emitted `origin` on its metas in the first place — that is the
+            // `@archie/devtools` version the acg/kitgen esbuild path had
+            // installed when the screen (or the kit) was built, a completely
+            // separate axis from this CDN script's version (see the `origin`
+            // field's docstring in `types/editor-meta.ts` for the full
+            // reasoning, and why NO per-node signal can close that gap).
+            kitOriginIdentity: true,
+            // v2.5.0 — right-click menu in navigate AND inspect mode, emitting
+            // `CHAT_CONTEXT_REQUESTED` (with the node's full metadata) and
+            // `ADD_COMMENT_REQUESTED` (with the anchor target). Labels and the
+            // chat-entry permission gate arrive via `CONFIGURE_INSPECTOR`.
+            // Hosts MUST feature-detect: a frozen pre-2.5.0 inspector ignores
+            // `CONFIGURE_INSPECTOR` and never emits either message.
+            contextMenuActions: true,
+            // v2.6.0 — the handshake is RECOVERABLE: `QUERY_CAPABILITIES`
+            // answers with `CAPABILITIES_RESULT` carrying this exact payload,
+            // and every `SET_EDITOR_MODE`/`SYNC_EDITOR_STATE` re-announces it
+            // unsolicited. Hosts MUST feature-detect before WAITING on a
+            // reply — a frozen pre-2.6.0 inspector has no handler for
+            // `QUERY_CAPABILITIES` and never answers — but a host that lost
+            // the one-shot handshake has no capabilities to detect ON, so
+            // asking blindly (and treating silence as "still unknown", never
+            // as "reported empty") is the correct posture.
+            capabilitiesQuery: true,
+          },
+        }
+      }
+
+      /**
+       * Emit the capabilities payload as `CAPABILITIES_RESULT`.
+       *
+       * `requestId` echoes the pull's correlation id, or is `null` for the
+       * unsolicited push. `reason` names which route produced it, purely
+       * for host-side tracing.
+       */
+      function announceInspectorCapabilities(requestId, reason) {
+        var handshake = buildInspectorHandshakePayload()
+        postMessageToParent({
+          type: "CAPABILITIES_RESULT",
+          requestId:
+            typeof requestId === "string" && requestId !== "" ? requestId : null,
+          reason: typeof reason === "string" && reason !== "" ? reason : null,
+          version: handshake.version,
+          protocolVersion: handshake.protocolVersion,
+          capabilities: handshake.capabilities,
+        })
+      }
+
+      var initialHandshake = buildInspectorHandshakePayload()
       postMessageToParent({
         type: "INSPECTOR_SCRIPT_LOADED",
         timestamp: Date.now(),
-        // 2.2.0 (ARCH-1065): additive only — `bindingChain` on element data,
-        // `QUERY_SLICE_FIELD` in the message protocol, and
-        // `capabilities.bindingContract` below. No existing field changed
-        // shape, so `protocolVersion` stays 1.
-        // 2.3.0 (ARCH-1065 A17-support): additive only — `QUERY_COLLECTION_ORDER`
-        // in the message protocol and `capabilities.collectionOrderQuery`
-        // below. No existing field changed shape, so `protocolVersion` stays 1.
-        // 2.4.0 (ARCH-883-KOI, CREW round): additive only — `origin` on
-        // `EditorMeta`, the usage-projected `ownMetaNodeId`/`inspectorSource`/
-        // `editorInstance` resolution, and `capabilities.kitOriginIdentity`
-        // below. No existing field changed shape, so `protocolVersion` stays 1.
-        version: "2.4.0",
-        protocolVersion: 1,
-        capabilities: {
-          // 2.1.1: function-valued __editorMeta props are invoked before any
-          // postMessage, so meta payloads stay structured-cloneable. Hosts can
-          // gate on this bit to confirm the deployed CDN artifact carries the
-          // fix (the 2.1.0 URL is overwritten in place on publish).
-          functionValuedEditorMeta: true,
-          inspect: true,
-          dndMove: true,
-          dndResize: true,
-          fiberInspectorSource: true,
-          hostControlledHistory: true,
-          arrangeStructuredHistory: true,
-          arrangeStrongNodeIdentity: true,
-          // Unified mode: SET_EDITOR_MODE "inspect" also enables the arrange
-          // (design) runtime — selection and drag/resize coexist. Hosts MUST
-          // feature-detect on this flag: a frozen 2.0.x inspector disables
-          // design mode on "inspect" and needs the legacy "design" mode.
-          unifiedInspectArrange: true,
-          // ARCH-1065: the M2 codemod's data-agent-* grammar is readable
-          // (`bindingChain` on element data) and slice-field-queryable
-          // (`QUERY_SLICE_FIELD`). Hosts MUST feature-detect on this flag
-          // before relying on either — a frozen pre-1065 inspector has
-          // neither.
-          collectionBinding: true,
-          // ARCH-1065 A17-support (v2.3.0): `QUERY_COLLECTION_ORDER` resolves
-          // the enclosing collection's order ("stable"/"derived") and row
-          // ids/count for a target node, off the same data-agent-* grammar
-          // as `collectionBinding`. Hosts MUST feature-detect on this flag —
-          // a frozen pre-2.3.0 inspector has no handler for the message.
-          collectionOrderQuery: true,
-          // The BUILD-TIME contract version this specific page was stamped
-          // with, forwarded verbatim from `<meta name="archie-binding-contract">`
-          // when the kit build emitted one — null on any page built before
-          // that meta tag existed, or that never carried collection-bound
-          // data. Opaque to this script: validating/interpreting the value is
-          // the host's job (mirrors how `slot` and `bindingContract` — plural
-          // concept, singular mechanism — are treated as opaque strings
-          // elsewhere in this file).
-          bindingContract: readBindingContractMeta(),
-          // ARCH-883-KOI F4 (v2.4.0) — this SCRIPT resolves `EditorMeta.origin`
-          // and projects identity across an instrumented kit boundary
-          // (`ownMetaNodeId`, `projectUsageMetaFromElement`,
-          // `getInspectorInfoFromElement`, `resolveInstanceIdentity`). Hosts
-          // MUST feature-detect on this flag before trusting `origin`
-          // (absent or `editorMeta.origin === 'kit'`) as meaningful: a frozen
-          // pre-2.4.0 inspector never reads the field at all, so its
-          // `inspectorSource`/`editorInstance` on an instrumented-kit page
-          // reproduce the exact F1 bug this version fixes.
-          //
-          // What this bit CANNOT tell the host: whether the PAGE's own build
-          // emitted `origin` on its metas in the first place — that is the
-          // `@archie/devtools` version the acg/kitgen esbuild path had
-          // installed when the screen (or the kit) was built, a completely
-          // separate axis from this CDN script's version (see the `origin`
-          // field's docstring in `types/editor-meta.ts` for the full
-          // reasoning, and why NO per-node signal can close that gap).
-          kitOriginIdentity: true,
-        },
+        version: initialHandshake.version,
+        protocolVersion: initialHandshake.protocolVersion,
+        capabilities: initialHandshake.capabilities,
       })
 
       if (window._inspectorMessageHandler) {
@@ -1690,6 +1782,10 @@
           element === selectedElementBadge ||
           element.id === "inspector-ping-effect" ||
           (element.closest && element.closest("[data-inspector-badge]")) ||
+          // Right-click menu: its buttons must survive setupEventBlockers'
+          // "click" blocker and never be treated as an inspect target.
+          (element.closest &&
+            element.closest("[data-inspector-context-menu]")) ||
           // Design-mode (arrange) overlay elements: HitArea, resize handles,
           // drop-line, etc. These belong to the unified visual editor and must
           // pass mousedown/click events through to React (dnd-kit) instead of
@@ -2224,6 +2320,15 @@
       }
 
       function setEditorModeFromHost(mode, options) {
+        // PUSH route of the recoverable handshake (see
+        // `buildInspectorHandshakePayload`). Emitted BEFORE the
+        // `EDITOR_MODE_CHANGED` echo below — deliberately, not incidentally:
+        // a host that lost the one-shot `INSPECTOR_SCRIPT_LOADED` refuses
+        // every inbound message until it knows who it is talking to, so the
+        // capabilities have to land FIRST or the very `EDITOR_MODE_CHANGED`
+        // this command exists to confirm would be the message dropped.
+        announceInspectorCapabilities(null, "editor-mode")
+
         var historyMode =
           options && options.hostControlledHistory ? "host" : "local"
 
@@ -2758,6 +2863,310 @@
         return element
       }
 
+      // ── Annotation support (host draw mode) ──────────────────────────────
+      // Two OPTIONAL queries the host uses to turn a drawing over the preview
+      // into actionable context. Both are advertised as capabilities
+      // (`rectElementQuery`, `viewportCapture`); a host that sees neither
+      // degrades to sending the raw drawing, so failures here must never
+      // throw into the shared message handler.
+
+      var ANNOTATION_MAX_ELEMENTS = 8
+      var ANNOTATION_CAPTURE_TIMEOUT_MS = 5000
+      var ANNOTATION_MIN_SIDE_PX = 4
+      var ANNOTATION_SKIP_TAGS = {
+        HTML: true,
+        HEAD: true,
+        SCRIPT: true,
+        STYLE: true,
+        META: true,
+        LINK: true,
+        TITLE: true,
+        BR: true,
+      }
+
+      function annotationIntersection(a, b) {
+        var x = Math.max(a.left, b.x)
+        var y = Math.max(a.top, b.y)
+        var right = Math.min(a.right, b.x + b.width)
+        var bottom = Math.min(a.bottom, b.y + b.height)
+        if (right <= x || bottom <= y) return 0
+        return (right - x) * (bottom - y)
+      }
+
+      /**
+       * Elements intersecting a viewport-relative rect, most specific first.
+       *
+       * "Most specific" is deliberately NOT smallest-area: a mark drawn around
+       * a card should report the card, not the innermost text node inside it.
+       * Ranking therefore puts nodes carrying an inspector source (i.e. ones
+       * the agent can actually edit) ahead of anonymous wrappers, then favours
+       * higher coverage of the drawn rect.
+       */
+      function collectElementsInRect(rect) {
+        if (
+          !rect ||
+          typeof rect.x !== "number" ||
+          typeof rect.y !== "number" ||
+          !(rect.width > 0) ||
+          !(rect.height > 0)
+        ) {
+          return []
+        }
+
+        var all = _rawDocumentQuerySelectorAll.call(document, "body *")
+        var scored = []
+
+        for (var i = 0; i < all.length; i++) {
+          var el = all[i]
+          if (ANNOTATION_SKIP_TAGS[el.tagName]) continue
+          if (el.closest && el.closest("[data-inspector-badge]")) continue
+
+          var box = el.getBoundingClientRect()
+          if (
+            box.width < ANNOTATION_MIN_SIDE_PX ||
+            box.height < ANNOTATION_MIN_SIDE_PX
+          ) {
+            continue
+          }
+
+          var overlap = annotationIntersection(box, rect)
+          if (overlap <= 0) continue
+
+          var style = window.getComputedStyle(el)
+          if (
+            style.visibility === "hidden" ||
+            style.display === "none" ||
+            style.opacity === "0"
+          ) {
+            continue
+          }
+
+          var elementArea = box.width * box.height
+          var rectArea = rect.width * rect.height
+          // Skip nodes the mark barely grazes, and page-sized wrappers the
+          // mark covers a negligible fraction of.
+          if (overlap / elementArea < 0.25 && overlap / rectArea < 0.5) continue
+
+          var info = null
+          try {
+            info = getInspectorInfoFromElement(el)
+          } catch (error) {
+            info = null
+          }
+
+          scored.push({
+            element: el,
+            info: info,
+            hasSource: info && info.file ? 1 : 0,
+            coverage: overlap / rectArea,
+          })
+        }
+
+        scored.sort(function (a, b) {
+          if (a.hasSource !== b.hasSource) return b.hasSource - a.hasSource
+          return b.coverage - a.coverage
+        })
+
+        var result = []
+        var seenSelectors = {}
+        for (var j = 0; j < scored.length; j++) {
+          if (result.length >= ANNOTATION_MAX_ELEMENTS) break
+          var entry = scored[j]
+          var selector = getStableSelector(entry.element)
+          if (!selector || seenSelectors[selector]) continue
+          seenSelectors[selector] = true
+
+          var box2 = entry.element.getBoundingClientRect()
+          var text = entry.element.textContent
+          result.push({
+            cssSelector: selector,
+            tagName: String(entry.element.tagName || "").toLowerCase(),
+            textPreview: text ? text.trim().slice(0, 120) : "",
+            sourceRef:
+              entry.info && entry.info.file
+                ? entry.info.file +
+                  ":" +
+                  (entry.info.line || 0) +
+                  ":" +
+                  (entry.info.column || 0)
+                : undefined,
+            componentName:
+              entry.info && entry.info.componentName
+                ? entry.info.componentName
+                : undefined,
+            boundingRect: {
+              x: box2.x,
+              y: box2.y,
+              width: box2.width,
+              height: box2.height,
+            },
+          })
+        }
+
+        return result
+      }
+
+      /** Same-origin CSS text, concatenated. Cross-origin sheets throw on
+       *  `cssRules` and are skipped — their styling is simply absent from the
+       *  capture, which is why the host treats it as best-effort. */
+      function collectSameOriginCss() {
+        var chunks = []
+        for (var i = 0; i < document.styleSheets.length; i++) {
+          var sheet = document.styleSheets[i]
+          var rules = null
+          try {
+            rules = sheet.cssRules
+          } catch (error) {
+            continue
+          }
+          if (!rules) continue
+          for (var j = 0; j < rules.length; j++) {
+            chunks.push(rules[j].cssText)
+          }
+        }
+        return chunks.join("\n")
+      }
+
+      function fetchAsDataUrl(url) {
+        return fetch(url, { mode: "same-origin" })
+          .then(function (response) {
+            if (!response.ok) throw new Error("bad status")
+            return response.blob()
+          })
+          .then(function (blob) {
+            return new Promise(function (resolve, reject) {
+              var reader = new FileReader()
+              reader.onload = function () {
+                resolve(String(reader.result))
+              }
+              reader.onerror = reject
+              reader.readAsDataURL(blob)
+            })
+          })
+      }
+
+      /** Rasterizing an SVG cannot fetch subresources, so same-origin <img>
+       *  sources are inlined first. Failures leave the image blank rather
+       *  than aborting the whole capture. */
+      function inlineImages(root) {
+        var images = root.querySelectorAll("img")
+        var jobs = []
+        for (var i = 0; i < images.length; i++) {
+          ;(function (img) {
+            var src = img.getAttribute("src")
+            if (!src || src.indexOf("data:") === 0) return
+            var absolute
+            try {
+              absolute = new URL(src, document.baseURI)
+            } catch (error) {
+              return
+            }
+            if (absolute.origin !== window.location.origin) return
+            jobs.push(
+              fetchAsDataUrl(absolute.href)
+                .then(function (dataUrl) {
+                  img.setAttribute("src", dataUrl)
+                })
+                .catch(function () {
+                  img.removeAttribute("src")
+                })
+            )
+          })(images[i])
+        }
+        return Promise.all(jobs)
+      }
+
+      /**
+       * Rasterizes the CURRENT viewport into a PNG data URL via an
+       * `<svg><foreignObject>` round-trip. Best-effort by construction: web
+       * fonts, cross-origin images and <canvas> pixels do not survive it. The
+       * host composes the result with the user's drawing, and falls back to
+       * the drawing alone when this rejects.
+       */
+      function captureViewportDataUrl(pixelRatio) {
+        var width = window.innerWidth
+        var height = window.innerHeight
+        var ratio = Math.min(Math.max(Number(pixelRatio) || 1, 1), 2)
+
+        var clone = document.documentElement.cloneNode(true)
+        var strip = clone.querySelectorAll(
+          "script, noscript, [data-inspector-badge], #archie-inspector-styles"
+        )
+        for (var i = 0; i < strip.length; i++) {
+          if (strip[i].parentNode) strip[i].parentNode.removeChild(strip[i])
+        }
+
+        var styleEl = document.createElement("style")
+        styleEl.textContent = collectSameOriginCss()
+        var head = clone.querySelector("head")
+        if (head) head.appendChild(styleEl)
+        else clone.insertBefore(styleEl, clone.firstChild)
+
+        return inlineImages(clone).then(function () {
+          var markup = new XMLSerializer().serializeToString(clone)
+          var svg =
+            '<svg xmlns="http://www.w3.org/2000/svg" width="' +
+            width +
+            '" height="' +
+            height +
+            '">' +
+            '<foreignObject x="0" y="0" width="' +
+            width +
+            '" height="' +
+            height +
+            '">' +
+            '<div xmlns="http://www.w3.org/1999/xhtml" style="width:' +
+            width +
+            "px;transform:translate(" +
+            -window.scrollX +
+            "px," +
+            -window.scrollY +
+            'px)">' +
+            markup +
+            "</div></foreignObject></svg>"
+
+          return new Promise(function (resolve, reject) {
+            var image = new Image()
+            // An SVG the browser refuses to decode can fire NEITHER onload nor
+            // onerror (malformed serialization, blocked subresource). Without
+            // this guard the host would sit on the request until its own
+            // timeout with no diagnostic; the deadline turns that into an
+            // explicit VIEWPORT_CAPTURE_FAILED.
+            var settled = false
+            var deadline = setTimeout(function () {
+              if (settled) return
+              settled = true
+              reject(new Error("svg rasterization timed out"))
+            }, ANNOTATION_CAPTURE_TIMEOUT_MS)
+            var finish = function (fn, value) {
+              if (settled) return
+              settled = true
+              clearTimeout(deadline)
+              fn(value)
+            }
+            image.onload = function () {
+              try {
+                var canvas = document.createElement("canvas")
+                canvas.width = Math.round(width * ratio)
+                canvas.height = Math.round(height * ratio)
+                var context = canvas.getContext("2d")
+                context.fillStyle = "#ffffff"
+                context.fillRect(0, 0, canvas.width, canvas.height)
+                context.drawImage(image, 0, 0, canvas.width, canvas.height)
+                finish(resolve, canvas.toDataURL("image/png"))
+              } catch (error) {
+                finish(reject, error)
+              }
+            }
+            image.onerror = function () {
+              finish(reject, new Error("svg rasterization failed"))
+            }
+            image.src =
+              "data:image/svg+xml;charset=utf-8," + encodeURIComponent(svg)
+          })
+        })
+      }
+
       function extractMetadata(element) {
         if (!element) return null
 
@@ -3416,7 +3825,20 @@
           }
         }
 
-        if (event.data && event.data.type === "SET_EDITOR_MODE") {
+        if (event.data && event.data.type === "CONFIGURE_INSPECTOR") {
+          // Origin adoption already happened above; this carries the
+          // right-click menu's i18n labels and permission gate.
+          applyInspectorConfiguration(event.data)
+        } else if (event.data && event.data.type === "QUERY_CAPABILITIES") {
+          // PULL route of the recoverable handshake (v2.6.0). Idempotent and
+          // side-effect free: it reports the SAME payload
+          // `INSPECTOR_SCRIPT_LOADED` carried, rebuilt from the one builder,
+          // so a host that lost the one-shot announcement can recover it on
+          // demand instead of living forever with "capabilities unknown".
+          // Mirrors QUERY_SLICE_FIELD / QUERY_COLLECTION_ORDER's standalone
+          // request/response envelope (`requestId` echoed on the reply).
+          announceInspectorCapabilities(event.data.requestId, "query")
+        } else if (event.data && event.data.type === "SET_EDITOR_MODE") {
           setEditorModeFromHost(event.data.mode || "off", {
             hostControlledHistory: event.data.hostControlledHistory !== false,
             theme: event.data.theme || null,
@@ -3589,6 +4011,59 @@
               },
             })
           }
+        } else if (
+          event.data &&
+          event.data.type === "QUERY_ELEMENTS_IN_RECT"
+        ) {
+          var rectRequestId = event.data.requestId
+          var queryElements = []
+          try {
+            queryElements = collectElementsInRect(event.data.rect)
+            var rectLimit = Number(event.data.limit)
+            if (rectLimit > 0 && queryElements.length > rectLimit) {
+              queryElements = queryElements.slice(0, rectLimit)
+            }
+          } catch (error) {
+            inspectorWarn("[Inspector] QUERY_ELEMENTS_IN_RECT failed", error)
+            queryElements = []
+          }
+          // Always answers — an empty list is a valid result, and the host's
+          // pending request would otherwise sit until its timeout.
+          postMessageToParent({
+            type: "ELEMENTS_IN_RECT_RESULT",
+            requestId: rectRequestId,
+            elements: queryElements,
+          })
+        } else if (event.data && event.data.type === "CAPTURE_VIEWPORT") {
+          var captureRequestId = event.data.requestId
+          try {
+            captureViewportDataUrl(event.data.pixelRatio)
+              .then(function (dataUrl) {
+                postMessageToParent({
+                  type: "VIEWPORT_CAPTURED",
+                  requestId: captureRequestId,
+                  dataUrl: dataUrl,
+                  width: window.innerWidth,
+                  height: window.innerHeight,
+                  scrollX: window.scrollX,
+                  scrollY: window.scrollY,
+                })
+              })
+              .catch(function (error) {
+                inspectorWarn("[Inspector] CAPTURE_VIEWPORT failed", error)
+                postMessageToParent({
+                  type: "VIEWPORT_CAPTURE_FAILED",
+                  requestId: captureRequestId,
+                  error: String((error && error.message) || error),
+                })
+              })
+          } catch (error) {
+            postMessageToParent({
+              type: "VIEWPORT_CAPTURE_FAILED",
+              requestId: captureRequestId,
+              error: String((error && error.message) || error),
+            })
+          }
         } else if (event.data && event.data.type === "APPLY_STYLE_CHANGE") {
           const { selector, property, value } = event.data
 
@@ -4503,8 +4978,289 @@
         }
       }
 
+      // ── Right-click context menu ────────────────────────────────────────
+      // Two entries — pin the node as chat context, or open a comment
+      // anchored to it. Active in plain navigate mode as well as inspect, so
+      // the listeners are registered here at load time: setupEventBlockers()
+      // blocks "contextmenu" with stopImmediatePropagation once inspection
+      // starts, and only a listener registered earlier in the capture phase
+      // still runs.
+
+      var inspectorLabels = null
+      var inspectorPermissions = { sendToChat: true }
+      var contextMenuEl = null
+      var contextMenuChatButton = null
+      var contextMenuCommentButton = null
+      var contextMenuTarget = null
+      // Snapshotted when the menu opens: the comment anchor needs the
+      // right-click POINT, which is gone by the time the entry is activated.
+      var contextMenuTargetPayload = null
+
+      function getSendToChatLabel() {
+        var configured =
+          inspectorLabels &&
+          inspectorLabels.badge &&
+          typeof inspectorLabels.badge.sendToChat === "string"
+            ? inspectorLabels.badge.sendToChat.trim()
+            : ""
+        return configured || "Send to chat"
+      }
+
+      function getAddCommentLabel() {
+        var configured =
+          inspectorLabels &&
+          inspectorLabels.contextMenu &&
+          typeof inspectorLabels.contextMenu.addComment === "string"
+            ? inspectorLabels.contextMenu.addComment.trim()
+            : ""
+        return configured || "Add a comment"
+      }
+
+      // CONFIGURE_INSPECTOR payload — i18n labels plus the host's permission
+      // gate for the chat entry (a viewer who can't send chat messages gets
+      // the comment entry only).
+      function applyInspectorConfiguration(data) {
+        if (data && data.labels && typeof data.labels === "object") {
+          inspectorLabels = data.labels
+        }
+        if (data && data.permissions && typeof data.permissions === "object") {
+          inspectorPermissions = {
+            sendToChat: data.permissions.sendToChat !== false,
+          }
+        }
+        syncContextMenuLabels()
+      }
+
+      function syncContextMenuLabels() {
+        if (contextMenuChatButton) {
+          contextMenuChatButton.textContent = getSendToChatLabel()
+          contextMenuChatButton.style.display = inspectorPermissions.sendToChat
+            ? "block"
+            : "none"
+        }
+        if (contextMenuCommentButton) {
+          contextMenuCommentButton.textContent = getAddCommentLabel()
+        }
+      }
+
+      function hideSelectionContextMenu() {
+        if (contextMenuEl) contextMenuEl.style.display = "none"
+      }
+
+      function ensureSelectionContextMenu() {
+        if (contextMenuEl && document.contains(contextMenuEl)) {
+          return contextMenuEl
+        }
+        // A previous run's node (or one orphaned by a body wipe) would
+        // otherwise linger with dead click handlers.
+        var orphan = document.getElementById("__archie-inspector-context-menu__")
+        if (orphan && orphan.parentNode) orphan.parentNode.removeChild(orphan)
+
+        var menu = document.createElement("div")
+        menu.id = "__archie-inspector-context-menu__"
+        menu.setAttribute("data-inspector-context-menu", "true")
+        menu.style.cssText =
+          "position:fixed;display:none;z-index:2147483647;box-sizing:border-box;min-width:136px;padding:4px;border:1px solid rgba(15,23,42,0.16);border-radius:6px;background:#fff;box-shadow:0 10px 30px rgba(15,23,42,0.18);font-family:system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;"
+
+        function createMenuButton(labelText, onActivate) {
+          var button = document.createElement("button")
+          button.type = "button"
+          button.textContent = labelText
+          button.style.cssText =
+            "display:block;width:100%;border:0;border-radius:4px;background:transparent;padding:6px 8px;text-align:left;color:#0f172a;font-size:12px;line-height:16px;cursor:pointer;"
+          button.addEventListener("mouseenter", function () {
+            button.style.background = inspectorTheme.accentSoft
+          })
+          button.addEventListener("mouseleave", function () {
+            button.style.background = "transparent"
+          })
+          button.addEventListener("click", function (event) {
+            event.preventDefault()
+            event.stopPropagation()
+            event.stopImmediatePropagation()
+            try {
+              onActivate()
+            } catch (err) {
+              inspectorWarn("[archie-inspector] context menu action failed", err)
+            }
+            hideSelectionContextMenu()
+          })
+          return button
+        }
+
+        contextMenuChatButton = createMenuButton(
+          getSendToChatLabel(),
+          function () {
+            if (!contextMenuTarget) return
+            // TWO messages on purpose — the host splits this request in two
+            // and neither half alone is visible:
+            //
+            //   bare      -> arms the editor surface ("inspect"), which is
+            //                what makes the chat's source bar render at all.
+            //   + metadata-> pins the node as the chat context and opens the
+            //                chat, but leaves the surface untouched.
+            //
+            // Sending only the metadata one pinned an element behind a bar
+            // that was never rendered, which is why the entry looked dead.
+            // The bare half is skipped while inspecting so it can't yank an
+            // open visual-editor session into source-selection mode.
+            if (!isInspecting) {
+              postMessageToParent({ type: "CHAT_CONTEXT_REQUESTED" })
+            }
+            // `extractMetadata` carries the node's whole attribute map (the
+            // `data-archie-id` the plain-render prototype stamps included) plus
+            // `inspectorSource`; the host derives the chip's file from the
+            // latter and its componentId from the former, falling back to
+            // `data-dnd-node-id` on kit pages that stamp no archie id.
+            postMessageToParent({
+              type: "CHAT_CONTEXT_REQUESTED",
+              metadata: extractMetadata(contextMenuTarget),
+            })
+          }
+        )
+
+        contextMenuCommentButton = createMenuButton(
+          getAddCommentLabel(),
+          function () {
+            postMessageToParent({
+              type: "ADD_COMMENT_REQUESTED",
+              target: contextMenuTargetPayload,
+            })
+          }
+        )
+
+        menu.appendChild(contextMenuChatButton)
+        menu.appendChild(contextMenuCommentButton)
+        ;(document.body || document.documentElement).appendChild(menu)
+        contextMenuEl = menu
+        syncContextMenuLabels()
+        return menu
+      }
+
+      function buildCommentTarget(element, event) {
+        if (!element) return null
+        try {
+          var rect = element.getBoundingClientRect()
+          var viewportWidth =
+            window.innerWidth || document.documentElement.clientWidth || 0
+          var viewportHeight =
+            window.innerHeight || document.documentElement.clientHeight || 0
+          var preview = element.textContent
+            ? element.textContent.trim().slice(0, 120)
+            : ""
+          return {
+            cssSelector: getStableSelector(element),
+            elementTag: String(element.tagName || "").toLowerCase(),
+            elementPreview: preview || null,
+            rect: {
+              x: rect.left,
+              y: rect.top,
+              width: rect.width,
+              height: rect.height,
+            },
+            // Fractions of the iframe viewport — the host re-projects them
+            // against the iframe's own rect (see AddCommentRequestTarget).
+            relativeX: viewportWidth ? event.clientX / viewportWidth : 0,
+            relativeY: viewportHeight ? event.clientY / viewportHeight : 0,
+            viewportWidth: viewportWidth,
+            viewportHeight: viewportHeight,
+            scrollTop:
+              window.scrollY || document.documentElement.scrollTop || 0,
+          }
+        } catch (err) {
+          return null
+        }
+      }
+
+      function showSelectionContextMenu(target, event) {
+        var menu = ensureSelectionContextMenu()
+        contextMenuTarget = target
+        contextMenuTargetPayload = buildCommentTarget(target, event)
+        menu.style.left =
+          Math.min(event.clientX, window.innerWidth - 150) + "px"
+        menu.style.top = Math.min(event.clientY, window.innerHeight - 60) + "px"
+        menu.style.display = "block"
+      }
+
+      var onContextMenuOpen = function (e) {
+        var target = e.target
+        if (!target || target === document.documentElement) return
+        if (contextMenuEl && contextMenuEl.contains(target)) return
+        if (isInspectorElement(target)) return
+
+        var resolved = resolveExactInspectTarget(target)
+        if (!isValidContentElement(resolved)) {
+          resolved = getElementFromPoint(e.clientX, e.clientY, target)
+        }
+        if (!isValidContentElement(resolved)) return
+
+        e.preventDefault()
+        e.stopPropagation()
+        // Beat setupEventBlockers' "contextmenu" blocker, which would
+        // otherwise swallow the event before it reaches us again.
+        e.stopImmediatePropagation()
+        showSelectionContextMenu(resolved, e)
+      }
+
+      var onContextMenuDismissPointer = function (e) {
+        if (contextMenuEl && contextMenuEl.contains(e.target)) return
+        hideSelectionContextMenu()
+      }
+
+      var onContextMenuDismissKey = function (e) {
+        if (e.key === "Escape") hideSelectionContextMenu()
+      }
+
+      // Each runInspector() call builds a fresh closure, so drop the previous
+      // run's listeners (and its orphaned menu node) the same way the message
+      // handler above is deduped — otherwise a re-run stacks handlers that
+      // each open their own menu.
+      var previousContextMenuHandlers =
+        window.__ARCHIE_INSPECTOR_CONTEXT_MENU_HANDLERS__
+      if (previousContextMenuHandlers) {
+        try {
+          document.removeEventListener(
+            "contextmenu",
+            previousContextMenuHandlers.contextmenu,
+            true
+          )
+          document.removeEventListener(
+            "mousedown",
+            previousContextMenuHandlers.mousedown,
+            true
+          )
+          window.removeEventListener(
+            "scroll",
+            previousContextMenuHandlers.scroll,
+            true
+          )
+          document.removeEventListener(
+            "keydown",
+            previousContextMenuHandlers.keydown,
+            true
+          )
+        } catch (err) {
+          // Ignore cleanup errors
+        }
+      }
+
+      document.addEventListener("contextmenu", onContextMenuOpen, true)
+      document.addEventListener("mousedown", onContextMenuDismissPointer, true)
+      window.addEventListener("scroll", hideSelectionContextMenu, true)
+      document.addEventListener("keydown", onContextMenuDismissKey, true)
+
+      window.__ARCHIE_INSPECTOR_CONTEXT_MENU_HANDLERS__ = {
+        contextmenu: onContextMenuOpen,
+        mousedown: onContextMenuDismissPointer,
+        scroll: hideSelectionContextMenu,
+        keydown: onContextMenuDismissKey,
+      }
+
       // Register inspector click handler BEFORE event blockers
-      // This ensures it runs first and can mark events as handled
+      // This ensures it runs first and can mark events as handled.
+      // It stays AFTER the context-menu mousedown listener above, which must
+      // still run (to dismiss the menu) even when a selection click calls
+      // stopImmediatePropagation.
       document.addEventListener("mousedown", inspectorClickHandler, true)
 
       // Block clicks when element is selected but not inspecting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archie/devtools",
-  "version": "0.0.36",
+  "version": "0.0.37",
   "description": "DevTools for Archie generated applications - Route synchronization and editor communication",
   "repository": {
     "type": "git",