@archie/devtools 0.0.26 → 0.0.28

package/dist/client/client.mjs

@@ -4063,6 +4063,19 @@ function dispatchRuntimeEvent(detail) {
   if (typeof window === "undefined") return;
   window.dispatchEvent(new CustomEvent(DND_RUNTIME_EVENT, { detail }));
 }
+function resolveRowBinding(el) {
+  let node = el;
+  for (let depth = 0; node && depth < MAX_ROW_BINDING_ANCESTOR_DEPTH; depth += 1) {
+    const rowId = node.getAttribute("data-agent-row");
+    if (rowId !== null && rowId !== "") {
+      const entity = node.getAttribute("data-agent-entity");
+      return entity ? { entity, rowId } : null;
+    }
+    node = node.parentElement;
+  }
+  return null;
+}
+var MAX_ROW_BINDING_ANCESTOR_DEPTH = 12;
 function mergeInspectorTheme(theme) {
   return {
     ...DEFAULT_INSPECTOR_THEME,
@@ -4449,16 +4462,6 @@ function createCommitLaneIdentitySnapshot(params) {
     committable: true
   };
 }
-function hasSafeOccurrenceIdentities(lane, duplicateNodeKey) {
-  const effectiveNodeIds = lane.commitNodeIds.filter(
-    (commitNodeId) => lane.nodeKeysByCommitNodeId.get(commitNodeId) === duplicateNodeKey
-  ).map(
-    (commitNodeId) => lane.effectiveNodeIdsByCommitNodeId.get(commitNodeId) ?? null
-  );
-  return effectiveNodeIds.length > 1 && effectiveNodeIds.every(
-    (effectiveNodeId) => typeof effectiveNodeId === "string" && effectiveNodeId.length > 0
-  ) && new Set(effectiveNodeIds).size === effectiveNodeIds.length;
-}
 function buildLanePersistenceDiagnostics(params) {
   const duplicateNodeKeys = detectDuplicateSourceBackedNodeKeys(
     buildNodeKeysFromCommitIds(
@@ -4469,24 +4472,10 @@ function buildLanePersistenceDiagnostics(params) {
   if (duplicateNodeKeys.length === 0) {
     return null;
   }
-  const safeDuplicateNodeKeys = duplicateNodeKeys.filter(
-    (nodeKey) => hasSafeOccurrenceIdentities(params.lane, nodeKey)
-  );
-  if (safeDuplicateNodeKeys.length === duplicateNodeKeys.length) {
-    return {
-      notes: safeDuplicateNodeKeys.map(
-        (nodeKey) => `Arrange lane ${params.lane.laneContainerId} repeats source-backed nodeKey ${nodeKey}, but runtime assigned explicit occurrence identities for each commit root.`
-      )
-    };
-  }
   return {
-    structurallyUnsafe: true,
-    blockedReasons: duplicateNodeKeys.map(
-      (nodeKey) => `Arrange lane ${params.lane.laneContainerId} contains multiple commit roots with the same source-backed nodeKey (${nodeKey}), so local save is unsafe.`
-    ),
-    notes: [
-      `Lane ${params.lane.laneContainerId} duplicates source-backed nodeKeys: ${duplicateNodeKeys.join(", ")}`
-    ]
+    notes: duplicateNodeKeys.map(
+      (nodeKey) => `Arrange lane ${params.lane.laneContainerId} repeats source-backed nodeKey ${nodeKey}, but runtime assigned explicit occurrence identities for each commit root.`
+    )
   };
 }
 function removeCommitNodeId(commitNodeIds, commitNodeId) {
@@ -4701,6 +4690,7 @@ var useDesignModeStore = create((set, get) => ({
     beforeSibling,
     afterSibling,
     diagnostics,
+    binding,
     componentName,
     before,
     after
@@ -4727,6 +4717,7 @@ var useDesignModeStore = create((set, get) => ({
       beforeSibling: beforeSibling ?? null,
       afterSibling: afterSibling ?? null,
       diagnostics: diagnostics ?? null,
+      binding: binding ?? null,
       payload: { before, after },
       at: now
     };
@@ -6416,6 +6407,8 @@ function serializeArrangeChange(event, index) {
     sourceBeforeSibling: event.kind === "move" ? event.sourceBeforeSibling : void 0,
     sourceAfterSibling: event.kind === "move" ? event.sourceAfterSibling : void 0,
     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,
     // Insert-specific fields
     displayName: event.kind === "insert" ? event.displayName : void 0,
     html: event.kind === "insert" ? event.html : void 0,
@@ -7946,6 +7939,7 @@ function recordCommittedMove(args) {
   });
   const componentName = getEditorMeta(anchorEl)?.componentName;
   const operationId = `${command.at}:${anchorNodeId}`;
+  const binding = resolveRowBinding(selectedEl);
   const beforePayload = buildMovePayloadWithEffectiveIdentities({
     placement: command.from,
     containerIdentity: sourceContainerIdentity,
@@ -7975,6 +7969,7 @@ function recordCommittedMove(args) {
     sourceBeforeSibling: sourceBeforeSiblingIdentity,
     sourceAfterSibling: sourceAfterSiblingIdentity,
     diagnostics,
+    binding,
     container: containerIdentity,
     beforeSibling: beforeSiblingIdentity,
     afterSibling: afterSiblingIdentity,

package/dist/collection-binding.d.mts

@@ -0,0 +1,221 @@
+import { types, PluginObj } from '@babel/core';
+
+/**
+ * babel-plugin-collection-binding (ARCH-1065 M2)
+ *
+ * Build-time codemod that stamps the DATA-BINDING GRAMMAR (ARCH-1065 design
+ * v2, D1) onto `.map()` collections whose source statically resolves back to
+ * the screen's slice — so the runtime inspector (M3, `window.__slice`) and the
+ * kit editing surfaces can offer per-row, per-field edits over bespoke
+ * (non-kit-component) rendered collections, the same way hand-written kit
+ * components (M1) already do.
+ *
+ * Applied in kit `build-d.mjs` to `s.source` BEFORE the SSR + client
+ * transforms, so the stamped attributes are present in both the SSR HTML and
+ * the hydrated client tree (hydration-safe by construction — nothing here
+ * reads the DOM or depends on a render pass).
+ *
+ * ── Grammar (D1) ──────────────────────────────────────────────────────────
+ *
+ *   data-agent-entity            static string, on the row root
+ *   data-agent-row                {String(param?.id)}, on the row root
+ *   data-agent-field              static string OR a runtime expression
+ *                                 (??/ternary field selection, D5.5)
+ *   data-agent-field-state        "mixed" | "unresolved"
+ *   data-agent-field-parts        comma-separated field list (mixed leaves)
+ *   data-agent-field-slot         text-node index of the dynamic part
+ *                                 (label+value leaves, D6)
+ *   data-agent-collection-order   "stable" | "derived" (D18), on the row root
+ *
+ * ── What counts as a slice source ────────────────────────────────────────
+ *
+ * `slice.<Entity>` or `slice['Entity Name']` / `slice["Entity Name"]`
+ * (both quote styles — Babel normalizes both to the same StringLiteral
+ * value, entities may contain spaces), threaded through any combination of
+ * `.filter()/.slice()/.sort()/.map()` chain calls, through single-assignment
+ * (`const`, never reassigned) local-variable hops (bounded to
+ * `MAX_SOURCE_CHAIN_HOPS`), and through a `useMemo(() => …, deps)` /
+ * `React.useMemo(() => …, deps)` unwrap (the common `() => expr` shape only —
+ * see `resolveSliceSource`). A `.sort(` ANYWHERE in the chain marks the
+ * collection `data-agent-collection-order="derived"`; otherwise `"stable"`
+ * (D18). The identifier root must be exactly `slice` — this mirrors the
+ * runtime's `window.__slice` (M3); the codemod does not trace how a `slice`
+ * binding entered scope (prop, destructure, import), only that its name at
+ * the point of use is literally `slice`.
+ *
+ * ── Row identity ──────────────────────────────────────────────────────────
+ *
+ * The `.map()` callback's first parameter is either a bare identifier (the
+ * whole row object — `data-agent-row` becomes `String(<param>?.id)`) or an
+ * ObjectPattern destructuring it (`data-agent-row` becomes `String(<local>)`
+ * using whichever local name the pattern bound the `id` key to). A
+ * destructured pattern that never binds `id` cannot form a row identity, so
+ * the ENTIRE map is left unstamped — row identity is foundational; there is
+ * no such thing as a field-only stamp without it.
+ *
+ * ── Row-component projection (D5.4) ─────────────────────────────────────
+ *
+ * `{list.map(e => <EventCard event={e} />)}` with a MODULE-LOCAL
+ * `function EventCard({ event }) { … }` co-located in the same source file
+ * (kit `build-d.mjs` hands this plugin the whole page/screen source, so
+ * screen-local helper components live in the same AST) resolves ACROSS that
+ * boundary: the row root is stamped on EventCard's OWN returned host
+ * element, using EventCard's own local parameter name for row-id and field
+ * resolution. The row-root projection specifically requires the WHOLE mapped
+ * item to be forwarded through one prop, verbatim (`event={e}`) — a partial
+ * field forward at that point cannot carry row identity, so the projection
+ * (and with it the whole map) fails closed.
+ *
+ * The SAME projection mechanism runs recursively for NESTED leaf components
+ * inside an already-established row (`<StatusBadge status={a.status} />`):
+ * there it is permissive about WHICH fields are forwarded (whole item OR a
+ * specific field OR several), because no row identity is at stake — only
+ * further field leaves.
+ *
+ * ── Forwarding-component allowlist descent (ARCH-1065 M-COV fix) ──────────
+ *
+ * D5.4 only ever sees THROUGH a component whose own source is available
+ * (module-local, co-located in the same file). Kit/imported components
+ * (`Card`, `CardContent`, `StatusBadge`, …) are opaque to the AST — the
+ * plugin has no body to project into — but many of them forward unrecognized
+ * JSX attributes onto their own root DOM element (typically via
+ * `{...rest}`), which makes them valid attribute CARRIERS even though
+ * they're not valid PROJECTION targets. `forwardingComponents` (a plugin
+ * option, see `CollectionBindingPluginOptions`) names exactly which ones.
+ *
+ * Two independent mechanisms use that allowlist:
+ *
+ *   - (a2) ROW ROOT: when the `.map()` callback's own returned JSX element
+ *     is an allowlisted component (`<Card key={r.id}>…</Card>` as the row
+ *     root itself), the row-identity attributes stamp directly onto that
+ *     component usage — NOT a projection into a separate definition, since
+ *     there is none to project into. The field walk continues into the
+ *     component's own JSX children with the SAME binding scope the row
+ *     callback already established.
+ *   - (c2-ii) LEAF: when a component usage directly hugs a field expression
+ *     with no host element beneath it (`<StatusBadge>{w.status}</StatusBadge>`),
+ *     the field attribute stamps onto the component itself IFF its name is
+ *     allowlisted; otherwise the leaf is left unstamped — a leaf is never
+ *     given an invented carrier.
+ *
+ * Separately, and regardless of allowlist membership at all — walking a
+ * component's own JSX children costs nothing, since no attribute lands
+ * anywhere until a valid carrier (host, or allowlisted leaf) is actually
+ * found — (a1) DESCENT: the field walk always continues INTO a structural
+ * child that is a component usage, as long as that usage has its own JSX
+ * children in source. `<Card><span>{w.name}</span></Card>` reaches the
+ * `<span>` (a host, stamped unconditionally) even though `Card` itself is
+ * never a stamp target unless allowlisted. This is what makes (c2-ii) safe
+ * to leave allowlist-gated: a wrapper with a host descendant never needs the
+ * wrapper itself to carry anything.
+ *
+ * The allowlist is ALWAYS an explicit option, never a built-in default list
+ * baked into this plugin — kit-manifest is the single source of truth for
+ * which components forward attributes (`forwardsDataAttributes`), and the
+ * kit build (`build-d.mjs`) is what threads that list in. An absent/empty
+ * option is exactly today's fail-closed behavior: zero component-carried
+ * stamps, byte-identical to the plugin before this mechanism existed.
+ *
+ * ── Field resolution ────────────────────────────────────────────────────
+ *
+ * Reuses `meaningfulChildren` from `babel-plugin-editor-meta.ts` (the exact
+ * same purity classifier both plugins must agree on) to find LEAF elements:
+ * JSX elements whose only meaningful children are text/expressions, never
+ * nested JSX elements. A leaf's dynamic part(s) classify as:
+ *
+ *   - a bare member expression off a "whole row object" binding
+ *     (`a.title`) → static field, UNLESS the member is `id` (id is NEVER
+ *     stamped as a field — it already carries the row identity);
+ *   - `a.x ?? a.y [?? …]` (an N-part nullish chain of member fields) →
+ *     a RUNTIME field-selector expression mirroring the chain
+ *     (`a.x != null ? "x" : a.y != null ? "y" : "z"`), or, when the chain
+ *     ends in a static literal fallback, a plain static field;
+ *   - `a.x || 'fallback'` → static field (literal-fallback only; `||`
+ *     does not get the N-part runtime treatment `??` does);
+ *   - `cond ? a.x : a.y` (both branches member fields of the row object) →
+ *     a RUNTIME field-selector expression duplicating `cond` verbatim
+ *     (`cond ? "x" : "y"`) — CONSTRAINED (C3): `cond` must be CALL-FREE
+ *     (checked recursively over the whole test subtree); a call anywhere in
+ *     the duplicated test would double-evaluate it across SSR and hydration,
+ *     so the whole leaf is left unstamped instead;
+ *   - `cond ? 'Literal' : 'Other'` where `cond` is itself a bare field
+ *     member (a boolean-typed field driving two literal branches) → static
+ *     field named by `cond` — the FE's typed controls (D7, a different
+ *     mechanism, M3) read the boolean's true/false rendering from
+ *     `window.__slice`, not from this attribute;
+ *   - a COMPUTED member (`a[expr]`, `expr` not a string literal) → no field
+ *     name, `data-agent-field-state="unresolved"` (a positive "this is
+ *     row-scoped data, but which field is unknown" signal — never silent).
+ *
+ * A leaf with exactly one meaningful child (no surrounding text) gets a bare
+ * `data-agent-field`. A leaf with 2+ meaningful children (label + value,
+ * D6) where EXACTLY ONE is dynamic gets the same `data-agent-field` PLUS
+ * `data-agent-field-slot`: the dynamic part's 0-based index among the
+ * element's own meaningful children. This is deliberately equal to its
+ * text-node index in the eventual SSR/hydrated DOM: every meaningful JSXText
+ * or JSXExpressionContainer child renders as exactly one text node (React 18
+ * inserts `<!-- -->` comment separators BETWEEN adjacent text-producing
+ * outputs to keep them independently locatable during hydration, but those
+ * comments are not text nodes and do not shift text-node indices). A leaf
+ * with 2+ dynamic parts that all resolve to STATIC fields with more than one
+ * DISTINCT field name gets `data-agent-field-state="mixed"` plus
+ * `data-agent-field-parts` (a comma-separated, source-order field list); any
+ * other multi-dynamic-part shape (an unresolvable part, or every part naming
+ * the same field) is left unstamped.
+ *
+ * Recursion into a leaf's structural siblings stops at the nearest NESTED
+ * `.map()` collection (a JSXExpressionContainer wrapping a call, not a JSX
+ * element child, so it is never a "structural child" this walker descends
+ * into) — the innermost-stamped-param rule: a field leaf only ever binds
+ * against its nearest enclosing map's own parameter. A nested collection
+ * that is itself slice-rooted gets discovered and stamped independently by
+ * the same Program-wide `.map()` scan, with its own entity/row identity.
+ *
+ * ── Failure posture ─────────────────────────────────────────────────────
+ *
+ * Every resolution step is an explicit allowlist; anything the resolver is
+ * not sure about degrades to NO STAMP, never a guessed one — a fragment or
+ * conditional expression at the callback's JSX root, an unresolvable
+ * component usage, a non-slice source, an ObjectPattern without an `id` key,
+ * a call inside a duplicated ternary test, ambiguous control flow (2+ return
+ * statements) — all leave the subtree untouched.
+ *
+ * ── Idempotence ─────────────────────────────────────────────────────────
+ *
+ * The plugin never rewrites SOURCE (D15) and never touches an existing
+ * attribute: every stamp is guarded by a same-name attribute-presence check,
+ * and a row root that already carries `data-agent-entity` short-circuits the
+ * whole map (no re-resolution, no field re-walk) — running the plugin twice
+ * produces byte-identical output.
+ */
+
+interface CollectionBindingPluginOptions {
+    /** Skip files matching this pattern. @default /node_modules/ */
+    fileExclude?: RegExp;
+    /**
+     * Component names known to forward unrecognized JSX attributes onto their
+     * own root DOM element (e.g. via `{...rest}`) — the exact set that makes
+     * a component usage a valid attribute CARRIER (row-root or leaf) even
+     * though it's opaque to the AST (see the "Forwarding-component allowlist
+     * descent" section above).
+     *
+     * Sourced from kit-manifest's `forwardsDataAttributes` flags by the kit
+     * build (`build-d.mjs` passes it) — this plugin NEVER hardcodes a default
+     * list here; that would be a shadow copy of kit-manifest's own truth, and
+     * would drift the moment a kit component's forwarding behavior changed
+     * without this plugin's knowledge. Synthetic lists are fine in tests, to
+     * keep the plugin testable standalone.
+     *
+     * Absent or empty = today's fail-closed behavior: no component ever
+     * carries a stamp, byte-identical to the plugin before this option
+     * existed.
+     *
+     * @default []
+     */
+    forwardingComponents?: string[];
+}
+declare function babelPluginCollectionBinding({ types: t }: {
+    types: typeof types;
+}, opts?: CollectionBindingPluginOptions): PluginObj;
+
+export { type CollectionBindingPluginOptions, babelPluginCollectionBinding };

package/dist/collection-binding.d.ts

@@ -0,0 +1,221 @@
+import { types, PluginObj } from '@babel/core';
+
+/**
+ * babel-plugin-collection-binding (ARCH-1065 M2)
+ *
+ * Build-time codemod that stamps the DATA-BINDING GRAMMAR (ARCH-1065 design
+ * v2, D1) onto `.map()` collections whose source statically resolves back to
+ * the screen's slice — so the runtime inspector (M3, `window.__slice`) and the
+ * kit editing surfaces can offer per-row, per-field edits over bespoke
+ * (non-kit-component) rendered collections, the same way hand-written kit
+ * components (M1) already do.
+ *
+ * Applied in kit `build-d.mjs` to `s.source` BEFORE the SSR + client
+ * transforms, so the stamped attributes are present in both the SSR HTML and
+ * the hydrated client tree (hydration-safe by construction — nothing here
+ * reads the DOM or depends on a render pass).
+ *
+ * ── Grammar (D1) ──────────────────────────────────────────────────────────
+ *
+ *   data-agent-entity            static string, on the row root
+ *   data-agent-row                {String(param?.id)}, on the row root
+ *   data-agent-field              static string OR a runtime expression
+ *                                 (??/ternary field selection, D5.5)
+ *   data-agent-field-state        "mixed" | "unresolved"
+ *   data-agent-field-parts        comma-separated field list (mixed leaves)
+ *   data-agent-field-slot         text-node index of the dynamic part
+ *                                 (label+value leaves, D6)
+ *   data-agent-collection-order   "stable" | "derived" (D18), on the row root
+ *
+ * ── What counts as a slice source ────────────────────────────────────────
+ *
+ * `slice.<Entity>` or `slice['Entity Name']` / `slice["Entity Name"]`
+ * (both quote styles — Babel normalizes both to the same StringLiteral
+ * value, entities may contain spaces), threaded through any combination of
+ * `.filter()/.slice()/.sort()/.map()` chain calls, through single-assignment
+ * (`const`, never reassigned) local-variable hops (bounded to
+ * `MAX_SOURCE_CHAIN_HOPS`), and through a `useMemo(() => …, deps)` /
+ * `React.useMemo(() => …, deps)` unwrap (the common `() => expr` shape only —
+ * see `resolveSliceSource`). A `.sort(` ANYWHERE in the chain marks the
+ * collection `data-agent-collection-order="derived"`; otherwise `"stable"`
+ * (D18). The identifier root must be exactly `slice` — this mirrors the
+ * runtime's `window.__slice` (M3); the codemod does not trace how a `slice`
+ * binding entered scope (prop, destructure, import), only that its name at
+ * the point of use is literally `slice`.
+ *
+ * ── Row identity ──────────────────────────────────────────────────────────
+ *
+ * The `.map()` callback's first parameter is either a bare identifier (the
+ * whole row object — `data-agent-row` becomes `String(<param>?.id)`) or an
+ * ObjectPattern destructuring it (`data-agent-row` becomes `String(<local>)`
+ * using whichever local name the pattern bound the `id` key to). A
+ * destructured pattern that never binds `id` cannot form a row identity, so
+ * the ENTIRE map is left unstamped — row identity is foundational; there is
+ * no such thing as a field-only stamp without it.
+ *
+ * ── Row-component projection (D5.4) ─────────────────────────────────────
+ *
+ * `{list.map(e => <EventCard event={e} />)}` with a MODULE-LOCAL
+ * `function EventCard({ event }) { … }` co-located in the same source file
+ * (kit `build-d.mjs` hands this plugin the whole page/screen source, so
+ * screen-local helper components live in the same AST) resolves ACROSS that
+ * boundary: the row root is stamped on EventCard's OWN returned host
+ * element, using EventCard's own local parameter name for row-id and field
+ * resolution. The row-root projection specifically requires the WHOLE mapped
+ * item to be forwarded through one prop, verbatim (`event={e}`) — a partial
+ * field forward at that point cannot carry row identity, so the projection
+ * (and with it the whole map) fails closed.
+ *
+ * The SAME projection mechanism runs recursively for NESTED leaf components
+ * inside an already-established row (`<StatusBadge status={a.status} />`):
+ * there it is permissive about WHICH fields are forwarded (whole item OR a
+ * specific field OR several), because no row identity is at stake — only
+ * further field leaves.
+ *
+ * ── Forwarding-component allowlist descent (ARCH-1065 M-COV fix) ──────────
+ *
+ * D5.4 only ever sees THROUGH a component whose own source is available
+ * (module-local, co-located in the same file). Kit/imported components
+ * (`Card`, `CardContent`, `StatusBadge`, …) are opaque to the AST — the
+ * plugin has no body to project into — but many of them forward unrecognized
+ * JSX attributes onto their own root DOM element (typically via
+ * `{...rest}`), which makes them valid attribute CARRIERS even though
+ * they're not valid PROJECTION targets. `forwardingComponents` (a plugin
+ * option, see `CollectionBindingPluginOptions`) names exactly which ones.
+ *
+ * Two independent mechanisms use that allowlist:
+ *
+ *   - (a2) ROW ROOT: when the `.map()` callback's own returned JSX element
+ *     is an allowlisted component (`<Card key={r.id}>…</Card>` as the row
+ *     root itself), the row-identity attributes stamp directly onto that
+ *     component usage — NOT a projection into a separate definition, since
+ *     there is none to project into. The field walk continues into the
+ *     component's own JSX children with the SAME binding scope the row
+ *     callback already established.
+ *   - (c2-ii) LEAF: when a component usage directly hugs a field expression
+ *     with no host element beneath it (`<StatusBadge>{w.status}</StatusBadge>`),
+ *     the field attribute stamps onto the component itself IFF its name is
+ *     allowlisted; otherwise the leaf is left unstamped — a leaf is never
+ *     given an invented carrier.
+ *
+ * Separately, and regardless of allowlist membership at all — walking a
+ * component's own JSX children costs nothing, since no attribute lands
+ * anywhere until a valid carrier (host, or allowlisted leaf) is actually
+ * found — (a1) DESCENT: the field walk always continues INTO a structural
+ * child that is a component usage, as long as that usage has its own JSX
+ * children in source. `<Card><span>{w.name}</span></Card>` reaches the
+ * `<span>` (a host, stamped unconditionally) even though `Card` itself is
+ * never a stamp target unless allowlisted. This is what makes (c2-ii) safe
+ * to leave allowlist-gated: a wrapper with a host descendant never needs the
+ * wrapper itself to carry anything.
+ *
+ * The allowlist is ALWAYS an explicit option, never a built-in default list
+ * baked into this plugin — kit-manifest is the single source of truth for
+ * which components forward attributes (`forwardsDataAttributes`), and the
+ * kit build (`build-d.mjs`) is what threads that list in. An absent/empty
+ * option is exactly today's fail-closed behavior: zero component-carried
+ * stamps, byte-identical to the plugin before this mechanism existed.
+ *
+ * ── Field resolution ────────────────────────────────────────────────────
+ *
+ * Reuses `meaningfulChildren` from `babel-plugin-editor-meta.ts` (the exact
+ * same purity classifier both plugins must agree on) to find LEAF elements:
+ * JSX elements whose only meaningful children are text/expressions, never
+ * nested JSX elements. A leaf's dynamic part(s) classify as:
+ *
+ *   - a bare member expression off a "whole row object" binding
+ *     (`a.title`) → static field, UNLESS the member is `id` (id is NEVER
+ *     stamped as a field — it already carries the row identity);
+ *   - `a.x ?? a.y [?? …]` (an N-part nullish chain of member fields) →
+ *     a RUNTIME field-selector expression mirroring the chain
+ *     (`a.x != null ? "x" : a.y != null ? "y" : "z"`), or, when the chain
+ *     ends in a static literal fallback, a plain static field;
+ *   - `a.x || 'fallback'` → static field (literal-fallback only; `||`
+ *     does not get the N-part runtime treatment `??` does);
+ *   - `cond ? a.x : a.y` (both branches member fields of the row object) →
+ *     a RUNTIME field-selector expression duplicating `cond` verbatim
+ *     (`cond ? "x" : "y"`) — CONSTRAINED (C3): `cond` must be CALL-FREE
+ *     (checked recursively over the whole test subtree); a call anywhere in
+ *     the duplicated test would double-evaluate it across SSR and hydration,
+ *     so the whole leaf is left unstamped instead;
+ *   - `cond ? 'Literal' : 'Other'` where `cond` is itself a bare field
+ *     member (a boolean-typed field driving two literal branches) → static
+ *     field named by `cond` — the FE's typed controls (D7, a different
+ *     mechanism, M3) read the boolean's true/false rendering from
+ *     `window.__slice`, not from this attribute;
+ *   - a COMPUTED member (`a[expr]`, `expr` not a string literal) → no field
+ *     name, `data-agent-field-state="unresolved"` (a positive "this is
+ *     row-scoped data, but which field is unknown" signal — never silent).
+ *
+ * A leaf with exactly one meaningful child (no surrounding text) gets a bare
+ * `data-agent-field`. A leaf with 2+ meaningful children (label + value,
+ * D6) where EXACTLY ONE is dynamic gets the same `data-agent-field` PLUS
+ * `data-agent-field-slot`: the dynamic part's 0-based index among the
+ * element's own meaningful children. This is deliberately equal to its
+ * text-node index in the eventual SSR/hydrated DOM: every meaningful JSXText
+ * or JSXExpressionContainer child renders as exactly one text node (React 18
+ * inserts `<!-- -->` comment separators BETWEEN adjacent text-producing
+ * outputs to keep them independently locatable during hydration, but those
+ * comments are not text nodes and do not shift text-node indices). A leaf
+ * with 2+ dynamic parts that all resolve to STATIC fields with more than one
+ * DISTINCT field name gets `data-agent-field-state="mixed"` plus
+ * `data-agent-field-parts` (a comma-separated, source-order field list); any
+ * other multi-dynamic-part shape (an unresolvable part, or every part naming
+ * the same field) is left unstamped.
+ *
+ * Recursion into a leaf's structural siblings stops at the nearest NESTED
+ * `.map()` collection (a JSXExpressionContainer wrapping a call, not a JSX
+ * element child, so it is never a "structural child" this walker descends
+ * into) — the innermost-stamped-param rule: a field leaf only ever binds
+ * against its nearest enclosing map's own parameter. A nested collection
+ * that is itself slice-rooted gets discovered and stamped independently by
+ * the same Program-wide `.map()` scan, with its own entity/row identity.
+ *
+ * ── Failure posture ─────────────────────────────────────────────────────
+ *
+ * Every resolution step is an explicit allowlist; anything the resolver is
+ * not sure about degrades to NO STAMP, never a guessed one — a fragment or
+ * conditional expression at the callback's JSX root, an unresolvable
+ * component usage, a non-slice source, an ObjectPattern without an `id` key,
+ * a call inside a duplicated ternary test, ambiguous control flow (2+ return
+ * statements) — all leave the subtree untouched.
+ *
+ * ── Idempotence ─────────────────────────────────────────────────────────
+ *
+ * The plugin never rewrites SOURCE (D15) and never touches an existing
+ * attribute: every stamp is guarded by a same-name attribute-presence check,
+ * and a row root that already carries `data-agent-entity` short-circuits the
+ * whole map (no re-resolution, no field re-walk) — running the plugin twice
+ * produces byte-identical output.
+ */
+
+interface CollectionBindingPluginOptions {
+    /** Skip files matching this pattern. @default /node_modules/ */
+    fileExclude?: RegExp;
+    /**
+     * Component names known to forward unrecognized JSX attributes onto their
+     * own root DOM element (e.g. via `{...rest}`) — the exact set that makes
+     * a component usage a valid attribute CARRIER (row-root or leaf) even
+     * though it's opaque to the AST (see the "Forwarding-component allowlist
+     * descent" section above).
+     *
+     * Sourced from kit-manifest's `forwardsDataAttributes` flags by the kit
+     * build (`build-d.mjs` passes it) — this plugin NEVER hardcodes a default
+     * list here; that would be a shadow copy of kit-manifest's own truth, and
+     * would drift the moment a kit component's forwarding behavior changed
+     * without this plugin's knowledge. Synthetic lists are fine in tests, to
+     * keep the plugin testable standalone.
+     *
+     * Absent or empty = today's fail-closed behavior: no component ever
+     * carries a stamp, byte-identical to the plugin before this option
+     * existed.
+     *
+     * @default []
+     */
+    forwardingComponents?: string[];
+}
+declare function babelPluginCollectionBinding({ types: t }: {
+    types: typeof types;
+}, opts?: CollectionBindingPluginOptions): PluginObj;
+
+export { type CollectionBindingPluginOptions, babelPluginCollectionBinding };