@archie/devtools 0.0.48 → 0.1.0

package/dist/client/client.mjs

@@ -4081,13 +4081,21 @@ function summarizeRuntimeEvent(detail) {
         container: summarizeIdentity(detail.container),
         beforeSibling: summarizeIdentity(detail.beforeSibling),
         sourceContainer: summarizeIdentity(detail.sourceContainer),
-        diagnostics: detail.diagnostics ?? null
+        diagnostics: detail.diagnostics ?? null,
+        targetVid: detail.targetVid ?? null,
+        containerVid: detail.containerVid ?? null,
+        index: detail.index
       };
+    case "drag-started":
+      return { targetVid: detail.targetVid, droppableCount: detail.droppable.length };
+    case "drag-refused":
+      return { code: detail.code, cause: detail.cause, vid: detail.vid };
     case "element-resized":
       return {
         operationId: detail.operationId,
         selected: summarizeIdentity(detail.selected),
         anchor: summarizeIdentity(detail.anchor),
+        targetVid: detail.targetVid ?? null,
         resize: {
           mode: detail.resize.mode,
           selectedNodeKey: detail.resize.selectedNodeKey,
@@ -4104,6 +4112,8 @@ function summarizeRuntimeEvent(detail) {
         nodeKey: detail.nodeKey,
         displayName: detail.displayName,
         container: summarizeIdentity(detail.container),
+        containerVid: detail.containerVid ?? null,
+        insertedVid: detail.insertedVid ?? null,
         index: detail.index,
         beforeSibling: summarizeIdentity(detail.beforeSibling),
         hasTsxCode: !!detail.tsxCode,
@@ -4185,6 +4195,58 @@ function isValidLaneContainer(containerId, projection, nodeMap) {
   if (container.children.length === 0) return false;
   return !isStructuralContainer(containerId, nodeMap);
 }
+function isNonDroppableNodeMeta(meta) {
+  if (!meta) return false;
+  if (meta.containerKind && meta.containerKind !== "plain") return true;
+  if (meta.isChrome) return true;
+  if (meta.isKitOrigin) return true;
+  return false;
+}
+function isNonDraggableNodeMeta(meta) {
+  if (!meta) return false;
+  if (meta.dynamicType && meta.dynamicType !== "STATIC") return true;
+  if (meta.isChrome) return true;
+  if (meta.isKitOrigin) return true;
+  return false;
+}
+function collectSubtreeIds(rootId, projection) {
+  const ids2 = /* @__PURE__ */ new Set([rootId]);
+  const stack = [rootId];
+  while (stack.length > 0) {
+    const id = stack.pop();
+    const node = projection.containerIndex.get(id);
+    if (!node) continue;
+    for (const childId of node.children) {
+      if (ids2.has(childId)) continue;
+      ids2.add(childId);
+      stack.push(childId);
+    }
+  }
+  return ids2;
+}
+function computeDroppableSet(sourceId, projection, nodeMap) {
+  const excluded = collectSubtreeIds(sourceId, projection);
+  const droppable = /* @__PURE__ */ new Set();
+  for (const containerId of projection.containerIndex.keys()) {
+    if (excluded.has(containerId)) continue;
+    if (isStructuralContainer(containerId, nodeMap)) continue;
+    if (isNonDroppableNodeMeta(nodeMap.get(containerId)?.editorMeta)) continue;
+    droppable.add(containerId);
+  }
+  return droppable;
+}
+function buildBlockedNodeMetaContainerIds(projection, nodeMap) {
+  const blocked = /* @__PURE__ */ new Set();
+  for (const containerId of projection.containerIndex.keys()) {
+    if (isNonDroppableNodeMeta(nodeMap.get(containerId)?.editorMeta)) {
+      blocked.add(containerId);
+    }
+  }
+  return blocked;
+}
+function resolveRefusalCode(meta, fallback) {
+  return meta?.lockReason ?? fallback;
+}
 function buildBlockedStructuralContainerIds(projection, nodeMap, sourceContainerId) {
   const blocked = /* @__PURE__ */ new Set();
   for (const containerId of projection.containerIndex.keys()) {
@@ -4195,6 +4257,7 @@ function buildBlockedStructuralContainerIds(projection, nodeMap, sourceContainer
 }
 
 // src/client/dnd/design-mode/fiber-bridge.ts
+import { NodeMetaSchema } from "@8base-archie/editor-protocol";
 var FIBER_KEY_PREFIX = "__reactFiber$";
 var PROPS_KEY_PREFIX = "__reactProps$";
 var metaCache = /* @__PURE__ */ new WeakMap();
@@ -4457,6 +4520,9 @@ function resolveDragSurface(el) {
   };
 }
 
+// src/types/editor-meta.ts
+import { VID_PATTERN, VID_ATTR } from "@8base-archie/editor-protocol";
+
 // src/client/dnd/design-mode/node-key.ts
 var _runtimeKeyMap = /* @__PURE__ */ new WeakMap();
 var _runtimeKeyCounter = 0;
@@ -4474,11 +4540,18 @@ function getNodeKeyFromElement(el) {
   const resolved = resolveDragSurface(el);
   const host = resolved.host ?? el;
   const meta = identityMeta(host);
+  if (meta?.vid) return meta.vid;
+  const domVid = host.getAttribute("data-vid");
+  if (domVid) return domVid;
   if (meta) return meta.nodeId;
   const persisted = host.getAttribute("data-dnd-node-id");
   if (persisted) return persisted;
   return getRuntimeKey(host);
 }
+function resolveVidFromElement(el) {
+  const key2 = getNodeKeyFromElement(el);
+  return VID_PATTERN.test(key2) ? key2 : null;
+}
 function getInspectorRefFromElement(el) {
   const resolved = resolveDragSurface(el);
   const host = resolved.host ?? el;
@@ -4805,6 +4878,8 @@ var useDesignModeStore = create((set, get) => ({
     afterSibling,
     diagnostics,
     binding,
+    targetVid,
+    containerVid,
     componentName,
     before,
     after
@@ -4832,6 +4907,8 @@ var useDesignModeStore = create((set, get) => ({
       afterSibling: afterSibling ?? null,
       diagnostics: diagnostics ?? null,
       binding: binding ?? null,
+      targetVid: targetVid ?? null,
+      containerVid: containerVid ?? null,
       payload: { before, after },
       at: now
     };
@@ -4860,6 +4937,7 @@ var useDesignModeStore = create((set, get) => ({
     nodeId,
     inspectorRef,
     componentName,
+    targetVid,
     before,
     after
   }) => {
@@ -4871,6 +4949,7 @@ var useDesignModeStore = create((set, get) => ({
       nodeKey,
       nodeId,
       inspectorRef,
+      targetVid: targetVid ?? null,
       payload: { before, after },
       at: now
     };
@@ -4904,6 +4983,8 @@ var useDesignModeStore = create((set, get) => ({
     tsxImports,
     containerId,
     containerNodeKey,
+    containerVid,
+    insertedVid,
     index,
     beforeSiblingInspectorRef,
     beforeSiblingNodeKey
@@ -4922,6 +5003,8 @@ var useDesignModeStore = create((set, get) => ({
       tsxImports: tsxImports ?? null,
       containerId,
       containerNodeKey,
+      containerVid: containerVid ?? null,
+      insertedVid: insertedVid ?? null,
       index,
       beforeSiblingInspectorRef: beforeSiblingInspectorRef ?? null,
       beforeSiblingNodeKey: beforeSiblingNodeKey ?? null,
@@ -5035,6 +5118,7 @@ function shouldShowGrabFeedback(target, scannedByNodeId) {
 }
 function isEligibleForDrag(sc) {
   if (sc.draggable === false) return false;
+  if (isNonDraggableNodeMeta(sc.editorMeta)) return false;
   const source = sc.eligibilitySource ?? "editor-meta";
   return source === "editor-meta" || source === "force-allow" || source === "inferred-sortable-descendant" || // RFC E2.4 P1: single host root of a kit-component usage (MetricCard,
   // Section, …) carrying the usage's projected meta.
@@ -6657,6 +6741,15 @@ function serializeArrangeChange(event, index) {
     diagnostics: event.kind === "move" ? event.diagnostics : void 0,
     // ARCH-1065 D17 — which slice row this move addresses.
     binding: event.kind === "move" ? event.binding : void 0,
+    // `data-vid` identity migration (`host-bridge.ts`'s `RuntimeMoveDetail`
+    // fields). `index` here is `event.payload.after.index` — the MOVE's own
+    // JSX-child index — never the `index` PARAMETER above (this change's
+    // sequence position in the session). `targetVid` also carries the
+    // resized node's vid on a `resize` change; `containerVid` also carries
+    // the drop container's vid on an `insert` change.
+    targetVid: event.kind === "move" || event.kind === "resize" ? event.targetVid : void 0,
+    containerVid: event.kind === "move" || event.kind === "insert" ? event.containerVid : void 0,
+    index: event.kind === "move" ? event.payload.after.index : void 0,
     // Insert-specific fields
     displayName: event.kind === "insert" ? event.displayName : void 0,
     html: event.kind === "insert" ? event.html : void 0,
@@ -6664,6 +6757,7 @@ function serializeArrangeChange(event, index) {
     tsxImports: event.kind === "insert" ? event.tsxImports : void 0,
     containerId: event.kind === "insert" ? event.containerId : void 0,
     containerNodeKey: event.kind === "insert" ? event.containerNodeKey : void 0,
+    insertedVid: event.kind === "insert" ? event.insertedVid : void 0,
     insertIndex: event.kind === "insert" ? event.index : void 0,
     beforeSiblingInspectorRef: event.kind === "insert" ? event.beforeSiblingInspectorRef : void 0,
     beforeSiblingNodeKey: event.kind === "insert" ? event.beforeSiblingNodeKey : void 0,
@@ -6920,6 +7014,7 @@ function useOverlayRefs(undoRequestId, redoRequestId) {
   const resolvedReorderRef = useRef8(null);
   const finalVisualKeyRef = useRef8(null);
   const dragStartPositionRef = useRef8(null);
+  const droppableContainerIdsRef = useRef8(null);
   const sourceCommitLaneRef = useRef8(null);
   const commitLaneCacheRef = useRef8(/* @__PURE__ */ new Map());
   const safeZoneRef = useRef8(null);
@@ -6951,6 +7046,7 @@ function useOverlayRefs(undoRequestId, redoRequestId) {
     resolvedReorderRef,
     finalVisualKeyRef,
     dragStartPositionRef,
+    droppableContainerIdsRef,
     sourceCommitLaneRef,
     commitLaneCacheRef,
     safeZoneRef,
@@ -8152,6 +8248,14 @@ function useDragVisualLoop({
 
 // src/client/dnd/design-mode/useDragLifecycle.ts
 import { useState as useState5, useCallback as useCallback6 } from "react";
+function emitRefused(code, cause, element) {
+  dispatchRuntimeEvent({
+    type: "drag-refused",
+    code,
+    cause,
+    vid: element ? resolveVidFromElement(element) : null
+  });
+}
 function resolveLaneAllowedContainers(anchorElement, srcContainerId) {
   if (!srcContainerId) return null;
   if (!resolveRowBinding(anchorElement)) return null;
@@ -8268,6 +8372,10 @@ function recordCommittedMove(args) {
   });
   const componentName = getEditorMeta(anchorEl)?.componentName;
   const operationId = `${command.at}:${anchorNodeId}`;
+  const targetVid = resolveVidFromElement(selectedEl);
+  const targetContainerId = command.to.parentNodeId ?? command.to.laneContainerId;
+  const targetContainerEl = targetContainerId ? resolveNodeElement(targetContainerId) : null;
+  const containerVid = targetContainerEl ? resolveVidFromElement(targetContainerEl) : null;
   const binding = resolveRowBinding(selectedEl);
   const beforePayload = buildMovePayloadWithEffectiveIdentities({
     placement: command.from,
@@ -8299,6 +8407,8 @@ function recordCommittedMove(args) {
     sourceAfterSibling: sourceAfterSiblingIdentity,
     diagnostics,
     binding,
+    targetVid,
+    containerVid,
     container: containerIdentity,
     beforeSibling: beforeSiblingIdentity,
     afterSibling: afterSiblingIdentity,
@@ -8310,6 +8420,9 @@ function recordCommittedMove(args) {
     type: "element-moved",
     operationId,
     commandType: command.type,
+    targetVid,
+    containerVid,
+    index: command.to.index,
     selected: {
       nodeId: selectedNodeId,
       nodeKey: selectedNodeKey,
@@ -8372,6 +8485,7 @@ function useDragLifecycle({
     refs.resolvedReorderRef.current = null;
     refs.finalVisualKeyRef.current = null;
     refs.dragStartPositionRef.current = null;
+    refs.droppableContainerIdsRef.current = null;
     clearCommitLaneCache();
     refs.safeZoneRef.current = null;
     setInsideRect(null);
@@ -8405,6 +8519,11 @@ function useDragLifecycle({
         eligibilitySource: found.eligibilitySource ?? "editor-meta",
         draggable: found.draggable
       });
+      emitRefused(
+        resolveRefusalCode(found.editorMeta, "GATE_REJECT"),
+        "Node is not draggable (dynamic render, chrome, or kit-origin).",
+        found.element
+      );
       return;
     }
     veTrace("dnd", "drag:start", {
@@ -8428,12 +8547,29 @@ function useDragLifecycle({
     clearCommitLaneCache();
     const anchor = resolveDragAnchor(activeId, proj, refs.nodeMapRef.current);
     const anchorScanned = refs.nodeMapRef.current.get(anchor.anchorNodeId) ?? found;
-    if (!anchorScanned || !isEligibleForDrag(anchorScanned)) return;
+    if (!anchorScanned || !isEligibleForDrag(anchorScanned)) {
+      emitRefused(
+        resolveRefusalCode(anchorScanned?.editorMeta, "GATE_REJECT"),
+        "Resolved drag anchor is not draggable.",
+        anchorScanned?.element ?? found.element
+      );
+      return;
+    }
     const anchorNodeId = anchor.anchorNodeId;
     const srcContainerId = anchor.sourceContainerId;
     const sourceCommitLane = getCommitLaneSnapshot(srcContainerId);
     const startPosition = getCurrentCommitPlacement(anchorNodeId, srcContainerId);
     const blockedContainerIds = buildBlockedStructuralContainerIds(proj, refs.nodeMapRef.current, srcContainerId);
+    for (const id of buildBlockedNodeMetaContainerIds(proj, refs.nodeMapRef.current)) {
+      blockedContainerIds.add(id);
+    }
+    const droppableSet = computeDroppableSet(anchorNodeId, proj, refs.nodeMapRef.current);
+    refs.droppableContainerIdsRef.current = droppableSet;
+    dispatchRuntimeEvent({
+      type: "drag-started",
+      targetVid: resolveVidFromElement(anchorScanned.element),
+      droppable: Array.from(droppableSet)
+    });
     const engineOptions = buildDragIntentEngineOptions(anchorScanned.element, srcContainerId, blockedContainerIds);
     refs.rowLockedRef.current = !!engineOptions.laneAllowedContainers;
     refs.engineRef.current = createDragIntentEngine(proj, anchorNodeId, engineOptions);
@@ -8506,6 +8642,19 @@ function useDragLifecycle({
         syncHistoryAvailability();
         return;
       }
+      if (dropTargetId && !refs.droppableContainerIdsRef.current?.has(dropTargetId)) {
+        const targetContainerEl = resolveNodeElement(dropTargetId);
+        const targetMeta = refs.nodeMapRef.current.get(dropTargetId)?.editorMeta;
+        const fallbackCode = targetMeta?.containerKind === "expression" ? "EXPRESSION_CONTAINER" : "CONTAINER_NOT_PLAIN";
+        emitRefused(
+          resolveRefusalCode(targetMeta, fallbackCode),
+          "Drop target is outside the droppable set for this node.",
+          targetContainerEl
+        );
+        clearDragState();
+        syncHistoryAvailability();
+        return;
+      }
       let command = null;
       if (nestTarget) {
         if (!activeEl.contains(nestTarget.element) && !nestTarget.element.contains(activeEl) && sourcePos?.commitNodeId) {
@@ -8717,6 +8866,7 @@ function useResizeSession({
       return;
     }
     const inspectorRef = getInspectorRefFromElement(element);
+    const targetVid = resolveVidFromElement(element);
     const resizeCmd = {
       type: "resize",
       mode,
@@ -8736,12 +8886,14 @@ function useResizeSession({
       nodeId: selectedNodeId,
       inspectorRef,
       componentName: getEditorMeta(element)?.componentName,
+      targetVid,
       before: { mode, selectedNodeKey, targetNodeKey, targetNodeId, width: resizeCmd.before.width, height: resizeCmd.before.height, colSpan: resizeCmd.before.colSpan, rowSpan: resizeCmd.before.rowSpan, styleDiff: { before: beforeStyles, after: afterStyles } },
       after: { mode, selectedNodeKey, targetNodeKey, targetNodeId, width: resizeCmd.after.width, height: resizeCmd.after.height, colSpan: resizeCmd.after.colSpan, rowSpan: resizeCmd.after.rowSpan, styleDiff: { before: beforeStyles, after: afterStyles } }
     });
     dispatchRuntimeEvent({
       type: "element-resized",
       operationId,
+      targetVid,
       selected: {
         nodeId: selectedNodeId,
         nodeKey: selectedNodeKey,
@@ -8964,6 +9116,8 @@ function commitExternalDrop(x, y, engine, component, refs, resolveNodeElement, s
       };
     }
     const operationId = `${insertCommand.at}:${nodeId}`;
+    const containerVid = containerEl ? resolveVidFromElement(containerEl) : null;
+    const insertedVid = resolveVidFromElement(newElement);
     useDesignModeStore.getState().recordInsertChange({
       operationId,
       nodeKey,
@@ -8975,6 +9129,8 @@ function commitExternalDrop(x, y, engine, component, refs, resolveNodeElement, s
       tsxImports: component.tsxImports ?? null,
       containerId: intent.containerId,
       containerNodeKey,
+      containerVid,
+      insertedVid,
       index: intent.index,
       beforeSiblingInspectorRef: beforeSiblingIdentity?.inspectorRef ?? null,
       beforeSiblingNodeKey: beforeSiblingIdentity?.nodeKey ?? null
@@ -8989,6 +9145,8 @@ function commitExternalDrop(x, y, engine, component, refs, resolveNodeElement, s
       tsxCode: component.tsxCode ?? null,
       tsxImports: component.tsxImports ?? null,
       container: containerIdentity,
+      containerVid,
+      insertedVid,
       index: intent.index,
       beforeSibling: beforeSiblingIdentity
     });

package/dist/collection-binding.js

@@ -26,6 +26,7 @@ module.exports = __toCommonJS(babel_plugin_collection_binding_exports);
 var import_types = require("@babel/types");
 
 // src/babel-plugin-editor-meta.ts
+var import_editor_protocol = require("@8base-archie/editor-protocol");
 function meaningfulChildren(t, children) {
   return children.filter((child) => {
     if (t.isJSXText(child)) return child.value.trim() !== "";

package/dist/collection-binding.mjs

@@ -1,6 +1,6 @@
 import {
   meaningfulChildren
-} from "./chunk-P5XMHBFS.mjs";
+} from "./chunk-THKKWDMJ.mjs";
 
 // src/babel-plugin-collection-binding.ts
 import { VISITOR_KEYS } from "@babel/types";

package/dist/index.d.mts

@@ -16,6 +16,13 @@ import { types, PluginObj } from '@babel/core';
  *   + (ARCH-1450) childrenSource, propSources — same-file identifier tracing
  *     for values `propBindings` cannot reach (no destructured-prop component
  *     in scope, or a value that never touches a prop at all)
+ *   + (data-vid identity migration) vid, isKitOrigin, dynamicType, isChrome,
+ *     containerKind, lockReason — read from a `data-vid` attribute (stamped
+ *     into persisted source by the Genesis stamper) plus the `NodeMeta`
+ *     contract fields (`@8base-archie/editor-protocol`) computed from the
+ *     element's own JSX/function ancestry. `nodeId === vid` when `data-vid`
+ *     is present; `allowLegacyIds` (default `true`, transitional) governs
+ *     what happens when it is not — see `EditorMetaPluginOptions` below.
  *
  * At runtime the Fiber bridge reads `memoizedProps.__editorMeta` to resolve
  * element identity without any DOM attributes.
@@ -136,6 +143,28 @@ interface EditorMetaPluginOptions {
      * @default false
      */
     templateOrigin?: boolean;
+    /**
+     * `data-vid` identity migration (vid-identity, decision binding). When a
+     * `JSXOpeningElement` carries a well-formed `data-vid` attribute
+     * (`VID_PATTERN`, `/^[a-z0-9]{6,8}$/`, stamped into persisted source by
+     * the Genesis stamper — see `@8base-archie/editor-protocol`'s
+     * `src/ids.ts`), the plugin ALWAYS reads it and uses it as `nodeId`
+     * (`meta.vid` is also emitted). This option only controls what happens
+     * when NO `data-vid` is present:
+     *
+     * - `true` (default in this version — TRANSITIONAL, to be removed once
+     *   every source tree is stamped) — fall back to the legacy
+     *   `"file:line:col:componentName"` addressing, exactly as before this
+     *   change.
+     * - `false` — an element with no `data-vid` is NOT instrumented at all
+     *   (no `__editorMeta` is emitted for it): a stable identity contract
+     *   cannot be met by an addressing scheme that invalidates on every
+     *   source write, so the plugin declines rather than silently hand out
+     *   one.
+     *
+     * @default true
+     */
+    allowLegacyIds?: boolean;
 }
 declare function babelPluginEditorMeta({ types: t }: {
     types: typeof types;
@@ -347,10 +376,27 @@ type PropSource = {
 } | {
     kind: 'other';
 };
+
 /** Metadata injected into every JSX element by babel-plugin-editor-meta. */
 interface EditorMeta {
-    /** Stable identifier: "file:line:col:componentName" */
+    /**
+     * Stable identifier for this node. `vid` identity (see below) is the
+     * canonical shape going forward: when the persisted source carries a
+     * `data-vid` attribute, `nodeId === vid`. Absent a `data-vid` (a bundle
+     * built with `allowLegacyIds: true`, the plugin's transitional default),
+     * this falls back to the legacy `"file:line:col:componentName"` shape,
+     * which invalidates on every write to the source.
+     */
     nodeId: string;
+    /**
+     * `data-vid` identity (vid-identity migration) — present only when the
+     * source element carried a well-formed `data-vid` attribute
+     * (`VID_PATTERN`, `/^[a-z0-9]{6,8}$/`). Stamped into PERSISTED source by
+     * the Genesis stamper, NOT computed here — the plugin only reads it.
+     * Absent on a node with no `data-vid` (legacy addressing) and on every
+     * bundle built before this change.
+     */
+    vid?: string;
     /** Relative file path from project root. */
     file: string;
     line: number;
@@ -553,6 +599,51 @@ interface EditorMeta {
      * already says). Absent on every bundle built before ARCH-1450.
      */
     propSources?: Record<string, PropSource>;
+    /**
+     * `NodeMeta` fields (vid-identity migration, `@8base-archie/editor-protocol`
+     * contract). Emitted only alongside `vid` (a legacy, `data-vid`-less node
+     * has no NodeMeta to report) — read via `fiber-bridge.ts`'s `getNodeMeta`,
+     * which validates the assembled `NodeMeta` object with `NodeMetaSchema`
+     * rather than trusting these fields individually.
+     *
+     * `isKitOrigin` restates the existing `origin === 'kit'` fact as a plain
+     * boolean (the `NodeMeta` contract's shape) — `origin` itself is
+     * unchanged and stays the field every existing consumer already reads.
+     */
+    isKitOrigin?: boolean;
+    /**
+     * Whether this node renders under a `.map`/`forEach`/`flatMap` callback
+     * (`'ARRAY'`), under a `ConditionalExpression`/`LogicalExpression` inside a
+     * `JSXExpressionContainer` (`'CONDITIONAL'`), or neither (`'STATIC'`).
+     * Computed at compile time by walking JSX/function ancestors — see
+     * `computeDynamicType` in `babel-plugin-editor-meta.ts` for the exact walk
+     * and its stopping rule at the first non-qualifying function boundary.
+     */
+    dynamicType?: 'STATIC' | 'ARRAY' | 'CONDITIONAL';
+    /**
+     * True for a node inside `shell.jsx`, `components/shell/**`, or with a
+     * `nav`/`aside`/`header` ancestor in the same file — the app shell/chrome
+     * region, structurally locked against drag/drop regardless of
+     * `isKitOrigin`. See `computeIsChrome` in `babel-plugin-editor-meta.ts`.
+     */
+    isChrome?: boolean;
+    /**
+     * Shape of this element's JSX children for drop-target purposes: `'plain'`
+     * when every child is a `JSXElement` or whitespace-trimmed `JSXText`,
+     * `'expression'` when any child is a `JSXExpressionContainer`/spread/
+     * iteration, `'none'` when the element has no element children (including
+     * self-closing). See `computeContainerKind` in `babel-plugin-editor-meta.ts`.
+     */
+    containerKind?: 'plain' | 'expression' | 'none';
+    /**
+     * Derived refusal reason, in priority order: `KIT_INTERNAL` (kit-origin) >
+     * `CHROME_STRUCTURAL` (shell/chrome) > `DYNAMIC_ARRAY`/`DYNAMIC_CONDITIONAL`
+     * (dynamic rendering shape) > `EXPRESSION_CONTAINER` (only relevant when
+     * this node is considered as a DROP TARGET, i.e. `containerKind ===
+     * 'expression'`). Absent when none of these apply — the node is a normal,
+     * writable, static, non-chrome, non-kit element.
+     */
+    lockReason?: 'KIT_INTERNAL' | 'DYNAMIC_ARRAY' | 'DYNAMIC_CONDITIONAL' | 'CHROME_STRUCTURAL' | 'EXPRESSION_CONTAINER';
 }
 
 interface ArchieDevToolsOptions {

package/dist/index.d.ts

@@ -16,6 +16,13 @@ import { types, PluginObj } from '@babel/core';
  *   + (ARCH-1450) childrenSource, propSources — same-file identifier tracing
  *     for values `propBindings` cannot reach (no destructured-prop component
  *     in scope, or a value that never touches a prop at all)
+ *   + (data-vid identity migration) vid, isKitOrigin, dynamicType, isChrome,
+ *     containerKind, lockReason — read from a `data-vid` attribute (stamped
+ *     into persisted source by the Genesis stamper) plus the `NodeMeta`
+ *     contract fields (`@8base-archie/editor-protocol`) computed from the
+ *     element's own JSX/function ancestry. `nodeId === vid` when `data-vid`
+ *     is present; `allowLegacyIds` (default `true`, transitional) governs
+ *     what happens when it is not — see `EditorMetaPluginOptions` below.
  *
  * At runtime the Fiber bridge reads `memoizedProps.__editorMeta` to resolve
  * element identity without any DOM attributes.
@@ -136,6 +143,28 @@ interface EditorMetaPluginOptions {
      * @default false
      */
     templateOrigin?: boolean;
+    /**
+     * `data-vid` identity migration (vid-identity, decision binding). When a
+     * `JSXOpeningElement` carries a well-formed `data-vid` attribute
+     * (`VID_PATTERN`, `/^[a-z0-9]{6,8}$/`, stamped into persisted source by
+     * the Genesis stamper — see `@8base-archie/editor-protocol`'s
+     * `src/ids.ts`), the plugin ALWAYS reads it and uses it as `nodeId`
+     * (`meta.vid` is also emitted). This option only controls what happens
+     * when NO `data-vid` is present:
+     *
+     * - `true` (default in this version — TRANSITIONAL, to be removed once
+     *   every source tree is stamped) — fall back to the legacy
+     *   `"file:line:col:componentName"` addressing, exactly as before this
+     *   change.
+     * - `false` — an element with no `data-vid` is NOT instrumented at all
+     *   (no `__editorMeta` is emitted for it): a stable identity contract
+     *   cannot be met by an addressing scheme that invalidates on every
+     *   source write, so the plugin declines rather than silently hand out
+     *   one.
+     *
+     * @default true
+     */
+    allowLegacyIds?: boolean;
 }
 declare function babelPluginEditorMeta({ types: t }: {
     types: typeof types;
@@ -347,10 +376,27 @@ type PropSource = {
 } | {
     kind: 'other';
 };
+
 /** Metadata injected into every JSX element by babel-plugin-editor-meta. */
 interface EditorMeta {
-    /** Stable identifier: "file:line:col:componentName" */
+    /**
+     * Stable identifier for this node. `vid` identity (see below) is the
+     * canonical shape going forward: when the persisted source carries a
+     * `data-vid` attribute, `nodeId === vid`. Absent a `data-vid` (a bundle
+     * built with `allowLegacyIds: true`, the plugin's transitional default),
+     * this falls back to the legacy `"file:line:col:componentName"` shape,
+     * which invalidates on every write to the source.
+     */
     nodeId: string;
+    /**
+     * `data-vid` identity (vid-identity migration) — present only when the
+     * source element carried a well-formed `data-vid` attribute
+     * (`VID_PATTERN`, `/^[a-z0-9]{6,8}$/`). Stamped into PERSISTED source by
+     * the Genesis stamper, NOT computed here — the plugin only reads it.
+     * Absent on a node with no `data-vid` (legacy addressing) and on every
+     * bundle built before this change.
+     */
+    vid?: string;
     /** Relative file path from project root. */
     file: string;
     line: number;
@@ -553,6 +599,51 @@ interface EditorMeta {
      * already says). Absent on every bundle built before ARCH-1450.
      */
     propSources?: Record<string, PropSource>;
+    /**
+     * `NodeMeta` fields (vid-identity migration, `@8base-archie/editor-protocol`
+     * contract). Emitted only alongside `vid` (a legacy, `data-vid`-less node
+     * has no NodeMeta to report) — read via `fiber-bridge.ts`'s `getNodeMeta`,
+     * which validates the assembled `NodeMeta` object with `NodeMetaSchema`
+     * rather than trusting these fields individually.
+     *
+     * `isKitOrigin` restates the existing `origin === 'kit'` fact as a plain
+     * boolean (the `NodeMeta` contract's shape) — `origin` itself is
+     * unchanged and stays the field every existing consumer already reads.
+     */
+    isKitOrigin?: boolean;
+    /**
+     * Whether this node renders under a `.map`/`forEach`/`flatMap` callback
+     * (`'ARRAY'`), under a `ConditionalExpression`/`LogicalExpression` inside a
+     * `JSXExpressionContainer` (`'CONDITIONAL'`), or neither (`'STATIC'`).
+     * Computed at compile time by walking JSX/function ancestors — see
+     * `computeDynamicType` in `babel-plugin-editor-meta.ts` for the exact walk
+     * and its stopping rule at the first non-qualifying function boundary.
+     */
+    dynamicType?: 'STATIC' | 'ARRAY' | 'CONDITIONAL';
+    /**
+     * True for a node inside `shell.jsx`, `components/shell/**`, or with a
+     * `nav`/`aside`/`header` ancestor in the same file — the app shell/chrome
+     * region, structurally locked against drag/drop regardless of
+     * `isKitOrigin`. See `computeIsChrome` in `babel-plugin-editor-meta.ts`.
+     */
+    isChrome?: boolean;
+    /**
+     * Shape of this element's JSX children for drop-target purposes: `'plain'`
+     * when every child is a `JSXElement` or whitespace-trimmed `JSXText`,
+     * `'expression'` when any child is a `JSXExpressionContainer`/spread/
+     * iteration, `'none'` when the element has no element children (including
+     * self-closing). See `computeContainerKind` in `babel-plugin-editor-meta.ts`.
+     */
+    containerKind?: 'plain' | 'expression' | 'none';
+    /**
+     * Derived refusal reason, in priority order: `KIT_INTERNAL` (kit-origin) >
+     * `CHROME_STRUCTURAL` (shell/chrome) > `DYNAMIC_ARRAY`/`DYNAMIC_CONDITIONAL`
+     * (dynamic rendering shape) > `EXPRESSION_CONTAINER` (only relevant when
+     * this node is considered as a DROP TARGET, i.e. `containerKind ===
+     * 'expression'`). Absent when none of these apply — the node is a normal,
+     * writable, static, non-chrome, non-kit element.
+     */
+    lockReason?: 'KIT_INTERNAL' | 'DYNAMIC_ARRAY' | 'DYNAMIC_CONDITIONAL' | 'CHROME_STRUCTURAL' | 'EXPRESSION_CONTAINER';
 }
 
 interface ArchieDevToolsOptions {