@archie/devtools 0.0.25 → 0.0.27

package/dist/inspector.standalone.js

@@ -367,13 +367,28 @@
         return projected && projected.nodeId ? projected.nodeId : null
       }
 
-      // The repeated-row boundary above `el`, or null. INNERMOST repetition
-      // wins (a tag inside a card inside a list is identified by the tag's key).
+      // The repeated-row boundary above `el`, or a search outcome explaining
+      // why none was found. INNERMOST repetition wins (a tag inside a card
+      // inside a list is identified by the tag's key).
+      //
+      // ARCH-1065 D8-v1/D26 — three-way outcome, matching instance-identity.ts:
+      // a CollectionWindow object (found), the string "exhausted" (walked to
+      // the true DOM root having found nothing — a COMPLETED search, safe to
+      // report as SINGLETON), or null (gave up without a definitive answer:
+      // no ancestor to compare against at all, or the depth budget ran out
+      // before reaching the root). The PREVIOUS version of this function
+      // collapsed "exhausted" and budget-exhaustion into one `null` verdict
+      // that `resolveInstanceIdentity` then always read as SINGLETON — more
+      // permissive than the TS twin ever intended: a walk that stopped early
+      // because it ran out of depth budget never PROVED there was no
+      // collection ancestor above it.
       function findCollectionWindow(el) {
+        if (!el.parentElement) return null
+
         var node = el
         for (var depth = 0; depth < MAX_ROW_ROOT_DEPTH; depth++) {
           var parent = node.parentElement
-          if (!parent) return null
+          if (!parent) return "exhausted"
 
           var nodeId = ownMetaNodeId(node)
           if (nodeId !== null) {
@@ -411,12 +426,19 @@
         return null
       }
 
-      // WHICH instance of a possibly-repeated node this element is.
+      // WHICH instance of a possibly-repeated node this element is, or NULL
+      // when resolution could not reach a definitive answer (ARCH-1065
+      // D8-v1/D26 — matches `resolveInstanceIdentity` in instance-identity.ts;
+      // this file cannot import it, so the same three-way outcome is
+      // re-derived here rather than left more permissive than the TS twin).
       // `scanOrdinal` is telemetry/UI only — the host must REJECT an intent
-      // with inCollection && fiberKey === null, never fall back to it.
+      // with inCollection && fiberKey === null, never fall back to it, and
+      // must treat a NULL editorInstance exactly like that same refusal.
       function resolveInstanceIdentity(el) {
+        if (!(el instanceof HTMLElement)) return null
         var win = findCollectionWindow(el)
-        if (!win) return { fiberKey: null, scanOrdinal: 0, inCollection: false }
+        if (win === null) return null
+        if (win === "exhausted") return { fiberKey: null, scanOrdinal: 0, inCollection: false }
         return {
           fiberKey: keyWithinWindow(win.rowRoot, win.container),
           scanOrdinal: win.ordinal,
@@ -453,6 +475,146 @@
         return anchors
       }
 
+      // ARCH-1065 M3 — the D1 grammar attributes babel-plugin-collection-binding
+      // stamps at build time (data-agent-entity/-row/-field/-field-state/
+      // -field-parts/-field-slot/-collection-order). One frame per DOM
+      // attribute name; a leaf typically carries only `field` (+ `fieldSlot`
+      // or `fieldState`/`fieldParts`), while its row-root ancestor carries
+      // `entity` + `row` + `collectionOrder` — reading both frames is what
+      // lets the host recover the full (entity, field, rowId) triple for a
+      // click anywhere inside a bound leaf.
+      var BINDING_ATTRS = [
+        ["entity", "data-agent-entity"],
+        ["row", "data-agent-row"],
+        ["field", "data-agent-field"],
+        ["fieldState", "data-agent-field-state"],
+        ["fieldParts", "data-agent-field-parts"],
+        ["fieldSlot", "data-agent-field-slot"],
+        ["collectionOrder", "data-agent-collection-order"],
+      ]
+
+      function readBindingFrame(el) {
+        if (!el || el.nodeType !== 1 || typeof el.getAttribute !== "function") return null
+        var frame = null
+        for (var i = 0; i < BINDING_ATTRS.length; i++) {
+          var value = el.getAttribute(BINDING_ATTRS[i][1])
+          if (value !== null) {
+            if (!frame) frame = {}
+            frame[BINDING_ATTRS[i][0]] = value
+          }
+        }
+        return frame
+      }
+
+      // Walks SELF-outward (unlike collectAncestorAnchors, which is strict
+      // ancestors — a click on a leaf's own `data-agent-field` must appear in
+      // its own chain entry), one frame per element carrying >=1 binding
+      // attribute, bounded by MAX_ANCHOR_CHAIN (the same bound the ARCH-906
+      // anchor walk uses — a binding chain never needs to reach deeper than
+      // that one does).
+      function collectBindingChain(el) {
+        var chain = []
+        var node = el
+        for (var depth = 0; node && depth < MAX_ANCHOR_CHAIN; depth++) {
+          var frame = readBindingFrame(node)
+          if (frame) chain.push(frame)
+          node = node.parentElement
+        }
+        return chain
+      }
+
+      // The nearest data-agent-row value SELF-outward, or null. Used to
+      // resolve "the currently selected row" for QUERY_SLICE_FIELD when the
+      // caller does not pass an explicit rowId.
+      function nearestRowId(el) {
+        var node = el
+        for (var depth = 0; node && depth < MAX_ANCHOR_CHAIN; depth++) {
+          if (node.nodeType === 1 && typeof node.getAttribute === "function") {
+            var rowId = node.getAttribute("data-agent-row")
+            if (typeof rowId === "string" && rowId !== "") return rowId
+          }
+          node = node.parentElement
+        }
+        return null
+      }
+
+      // ARCH-1065 — the BUILD-TIME contract version this page was stamped
+      // with. Opaque here; the host interprets it (SDD analog of `slot`).
+      function readBindingContractMeta() {
+        try {
+          var metaEl = document.querySelector('meta[name="archie-binding-contract"]')
+          if (metaEl && typeof metaEl.getAttribute === "function") {
+            var content = metaEl.getAttribute("content")
+            return typeof content === "string" && content !== "" ? content : null
+          }
+        } catch (e) {
+          // Best-effort — capability forwarding must never throw at boot.
+        }
+        return null
+      }
+
+      // ARCH-1065 M3 — `window.__slice` read live for the FE's typed controls
+      // (design D7): given an entity + field, the DISTINCT values that field
+      // takes across every row of that entity in the current slice (the
+      // vocabulary a status-SELECT control offers) and, when a row is known,
+      // that row's CURRENT value. Nothing about type/format is STAMPED at
+      // build time (per the M1/M2/M3 split) — it is read here, live, so it
+      // reflects the actual data the page is showing right now.
+      function resolveSliceEntityRows(entity) {
+        var slice = window.__slice
+        if (!slice || typeof slice !== "object") return null
+        var rows = slice[entity]
+        return Array.isArray(rows) ? rows : null
+      }
+
+      var ISO_DATE_PATTERN =
+        /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?)?$/
+
+      function inferSliceValueType(value) {
+        if (value === null || value === undefined || value === "") return "empty-null"
+        if (typeof value === "boolean") return "boolean"
+        if (typeof value === "number") return "number"
+        if (typeof value === "string") {
+          return ISO_DATE_PATTERN.test(value) ? "date" : "string"
+        }
+        return "unknown"
+      }
+
+      function querySliceField(entity, field, rowId) {
+        var rows = resolveSliceEntityRows(entity)
+        if (!rows) return null
+
+        var distinctValues = []
+        var seenDistinct = {}
+        for (var i = 0; i < rows.length; i++) {
+          var candidate = rows[i] ? rows[i][field] : undefined
+          if (candidate === undefined) continue
+          var key = String(candidate)
+          if (!seenDistinct[key]) {
+            seenDistinct[key] = true
+            distinctValues.push(candidate)
+          }
+        }
+
+        var currentValue = null
+        if (rowId != null) {
+          for (var j = 0; j < rows.length; j++) {
+            if (rows[j] && String(rows[j].id) === String(rowId)) {
+              var rowValue = rows[j][field]
+              currentValue = rowValue === undefined ? null : rowValue
+              break
+            }
+          }
+        }
+
+        var typeSample = currentValue !== null ? currentValue : distinctValues[0]
+        return {
+          currentValue: currentValue,
+          valueType: inferSliceValueType(typeSample),
+          distinctValues: distinctValues,
+        }
+      }
+
       if (window._inspectorSharedTargetObserver) {
         try {
           window._inspectorSharedTargetObserver.disconnect()
@@ -1065,7 +1227,11 @@
       postMessageToParent({
         type: "INSPECTOR_SCRIPT_LOADED",
         timestamp: Date.now(),
-        version: "2.1.1",
+        // 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.
+        version: "2.2.0",
         protocolVersion: 1,
         capabilities: {
           // 2.1.1: function-valued __editorMeta props are invoked before any
@@ -1085,6 +1251,21 @@
           // 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,
+          // 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(),
         },
       })
 
@@ -1684,6 +1865,30 @@
       // misread by the host as a stale mode (see runtimeBridgeHandler).
       var hostCommandedEditorMode = "off"
 
+      // ARCH-886 — per-page runtime feature-detection for the unified
+      // inspect+arrange coexistence. This inspector build is served fresh
+      // from the CDN (same URL, overwritten in place — see
+      // docs/deploy-order.md) to EVERY published prototype, old and new
+      // alike, so it cannot assume the PAGE it is currently inspecting was
+      // built with a @archie/devtools new enough to understand
+      // `set-design-mode`'s unified role. The page's own DndProvider
+      // registers `window.__ARCHIE_DESIGN_MODE__` synchronously on mount —
+      // well before a user can trigger SET_EDITOR_MODE from the host — so
+      // its presence at message-handling time is an accurate, live,
+      // per-page signal (no version number or capability handshake needed).
+      // Pages built before this bridge existed (pre-PR#12, e.g. the 0.0.21
+      // release) already handle the legacy `set-design-mode` command (that
+      // handler predates the bridge and is unchanged by it) — so
+      // unconditionally dispatching it there does not no-op, it ARMS that
+      // page's design-mode/arrange overlay with no selection routing,
+      // producing a second, uncoordinated hit-area layer on top of the
+      // inspector's own hover/selection UI. Gating on the bridge avoids
+      // that: an old page just gets clean inspect-only behavior, same as
+      // before unification shipped.
+      function pageSupportsUnifiedDesignMode() {
+        return typeof window.__ARCHIE_DESIGN_MODE__ !== "undefined"
+      }
+
       function setEditorModeFromHost(mode, options) {
         var historyMode =
           options && options.hostControlledHistory ? "host" : "local"
@@ -1704,11 +1909,14 @@
         hostCommandedEditorMode = mode === "inspect" || mode === "design" ? mode : "off"
 
         if (mode === "inspect") {
-          // Unified mode: visual editor (inspect) + arrange (design) coexist.
-          // The arrange overlay stays passive until the inspector publishes a
+          // Unified mode: visual editor (inspect) + arrange (design) coexist
+          // — gated on pageSupportsUnifiedDesignMode() (ARCH-886). The
+          // arrange overlay stays passive until the inspector publishes a
           // single-element selection (via publishSelectionToDesignMode), at
           // which point it lights up the resize/drag controls on that element.
-          dispatchHostCommand({ type: "set-design-mode", enabled: true })
+          if (pageSupportsUnifiedDesignMode()) {
+            dispatchHostCommand({ type: "set-design-mode", enabled: true })
+          }
           if (isInspecting) {
             // Recovery re-send (focus/visibility/online): the session is
             // already live. Activating again would wipe the user's current
@@ -2255,6 +2463,12 @@
           //     nodeId is a source position and collides across instances; the
           //     only identity that survives an insert above the edited row is
           //     React's `key`, which exists on the fiber and nowhere else.
+          //     ARCH-1065 D8-v1/D26: NULL here means resolution never reached
+          //     a definitive answer (detached node, non-HTMLElement, or the
+          //     depth-bounded walk ran out before reaching the DOM root) — the
+          //     host MUST treat a null editorInstance exactly like the
+          //     existing `inCollection && fiberKey === null` refusal, never as
+          //     "not in a collection".
           //
           // Both are plain data, so an already-published copy of this script
           // forwards them through structured clone unchanged.
@@ -2276,6 +2490,12 @@
           // already-published copy of this script forwards it unchanged through
           // structured clone; a host that does not read it is unaffected.
           ancestorAnchors: collectAncestorAnchors(element),
+          // ARCH-1065 M3 — the data-agent-* (D1 grammar) chain, self-outward,
+          // for whatever binding attributes the M2 codemod (or a hand-written
+          // kit component, M1) stamped. A host that does not read it is
+          // unaffected; a pre-1065 page simply yields an empty array (`[]`),
+          // same as `ancestorAnchors` does for a page with no anchors.
+          bindingChain: collectBindingChain(element),
           computedStyles: {
             display: computed.display,
             position: computed.position,
@@ -3629,6 +3849,38 @@
           dispatchHostCommand({
             type: "external-drag-cancel",
           })
+        } else if (event.data && event.data.type === "QUERY_SLICE_FIELD") {
+          // ARCH-1065 M3 — {entity, field} -> {currentValue, valueType,
+          // distinctValues} read live off window.__slice, for the FE's typed
+          // controls (D7). `rowId` is optional: when omitted, the CURRENTLY
+          // SELECTED (falling back to hovered) element's nearest
+          // data-agent-row supplies it — the common case is "the user just
+          // clicked a bound cell and wants its type/vocabulary", where the
+          // row is already implied by that click.
+          var queryEntity = event.data.entity
+          var queryField = event.data.field
+          var queryRowId =
+            typeof event.data.rowId === "string" && event.data.rowId !== ""
+              ? event.data.rowId
+              : null
+
+          var queryResult = null
+          if (typeof queryEntity === "string" && typeof queryField === "string") {
+            var contextElement = queryRowId
+              ? null
+              : getSelectedElement() || highlightedElement
+            var effectiveRowId =
+              queryRowId || (contextElement ? nearestRowId(contextElement) : null)
+            queryResult = querySliceField(queryEntity, queryField, effectiveRowId)
+          }
+
+          postMessageToParent({
+            type: "SLICE_FIELD_RESULT",
+            requestId: event.data.requestId,
+            entity: queryEntity,
+            field: queryField,
+            result: queryResult,
+          })
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archie/devtools",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "DevTools for Archie generated applications - Route synchronization and editor communication",
   "repository": {
     "type": "git",
@@ -24,6 +24,11 @@
       "import": "./dist/client/client.mjs",
       "require": "./dist/client/client.js"
     },
+    "./collection-binding": {
+      "types": "./dist/collection-binding.d.ts",
+      "import": "./dist/collection-binding.mjs",
+      "require": "./dist/collection-binding.js"
+    },
     "./inspector.standalone.js": "./dist/inspector.standalone.js"
   },
   "scripts": {