@archie/devtools 0.0.21 → 0.0.23

package/dist/index.d.mts

@@ -10,9 +10,44 @@ import { types, PluginObj } from '@babel/core';
  *
  * The injected prop contains:
  *   nodeId, file, line, col, componentName, staticProps, movable, parentNodeId
+ *   + (ARCH-883 F1) slot, propBindings, propOwner
  *
  * At runtime the Fiber bridge reads `memoizedProps.__editorMeta` to resolve
  * element identity without any DOM attributes.
+ *
+ * ARCH-883 F1 (SDD §2.3/§2.6) adds three compile-time-only things:
+ *
+ *   1. `propBindings` — which of this node's rendered expressions trace back to
+ *      a prop of the enclosing component, and whether that trace is safe enough
+ *      to OFFER as an edit. It never decides what code to write; the write goes
+ *      through the existing server write-paths. Anything the resolver is not
+ *      certain about degrades to a GAP, never to a wrong binding.
+ *   2. `data-kit-slot` consumption — the curated slot label is lifted into the
+ *      meta and the ATTRIBUTE IS STRIPPED, so it never reaches the DOM. The
+ *      plugin treats the string as opaque; validating it against the canonical
+ *      vocabulary (kit-runtime's `slot-vocabulary` export) belongs to the
+ *      consumer. devtools deliberately takes no dependency on kit-runtime.
+ *   3. `movable: false` for kit-origin nodes — reordering inside a kit template
+ *      affects N usages, a permanent non-objective (PRD §1.3).
+ *
+ * `parentNodeId` stays INTRA-FILE by construction (it only ever walks JSX
+ * ancestors within the file being transformed), so it never links a kit template
+ * node to a screen usage; per SDD §2.3 it must not be used across that seam.
+ * See the type docs in `types/editor-meta.ts`.
+ *
+ * ARCH-883 P0-1: the prop value is emitted as a ZERO-ARG ARROW FUNCTION that
+ * returns the meta object literal — `__editorMeta={() => ({...})}` — NOT the
+ * object literal directly. React serializes unknown OBJECT-valued props on
+ * host elements into the DOM (`__editorMeta="[object Object]"` on every
+ * published prototype page — a live production bug, proven by an executed
+ * SSR test in `src/client/dnd/design-mode/__tests__/editor-meta-react-behavior.test.ts`).
+ * Function- and symbol-valued unknown props are silently dropped by React in
+ * SSR, hydration, and client render — never written to the DOM — while
+ * remaining fully readable on `fiber.memoizedProps.__editorMeta` via a call.
+ * Every reader in the Fiber bridge (`fiber-bridge.ts`, `useElementScanner.ts`,
+ * `inspector.standalone.js`) invokes the value when it is a function and
+ * tolerates a raw object when it is not, so bundles built before this change
+ * keep resolving correctly until they are rebuilt.
  */
 
 interface EditorMetaPluginOptions {
@@ -22,11 +57,157 @@ interface EditorMetaPluginOptions {
     instrumentImported?: boolean;
     /** Include exact host source refs for runtime DOM lookup. */
     includeHostSourceRef?: boolean;
+    /**
+     * Where the transformed sources come from (ARCH-883 F1).
+     *
+     * - `'screen'` (default) — per-project `screens/<slug>.jsx`. Reorder is a real
+     *   operation there, so `movable` keeps its structural meaning.
+     * - `'kit'` — the shared kit component library (the `vendor.editor.js` babel
+     *   pre-pass over the kit's `.gen/` sources, SDD §2.1). Every node emits
+     *   `movable: false`: one template backs N usages across N projects, so
+     *   reordering it is a permanent non-objective (PRD §1.3).
+     *
+     * Independently of this flag, a slot-carrying node is kit-origin by definition
+     * and also emits `movable: false`.
+     */
+    origin?: 'screen' | 'kit';
 }
 declare function babelPluginEditorMeta({ types: t }: {
     types: typeof types;
 }, opts?: EditorMetaPluginOptions): PluginObj;
 
+/**
+ * A link between a rendered JSX expression and a prop of the component whose
+ * template contains it (ARCH-883 F1, SDD §2.3).
+ *
+ * `propBindings` decides what UI the editor may OFFER — never what code gets
+ * written. The server resolves the actual write through the existing
+ * `rebuild-screen` / `screen-slice` / `update-shell` paths.
+ *
+ * ROUTABILITY IS AN ALLOWLIST with THREE conditions, both required:
+ *
+ *     const routable =
+ *       (b.kind === 'direct' || b.kind === 'derived') &&
+ *       usageValueIsStringLiteralOrAbsent(usage, b.prop) &&   // consumer-side
+ *       propOwnerMatchesUsageComponent(meta, usage);          // consumer-side
+ *
+ * Everything else is a gap: a `kind: 'formatted'` entry (prop-reachable but not
+ * safely routable) or no entry at all for that target. A resolver false positive
+ * must always degrade to a gap, never to a wrong binding.
+ *
+ * THE USAGE-VALUE LAW APPLIES TO BOTH ROUTABLE KINDS, not only to `derived`.
+ * The plugin sees the kit template, never the usage site, so it cannot enforce
+ * it — the consumer must, for `direct` too. Real-corpus evidence for why: on the
+ * kit, `direct` outnumbers `derived` ~26:1, and a `direct` binding whose usage
+ * value is a computed object (`config={{…}}`, `widgets={list}`) is exactly as
+ * unwritable as a `derived` one. Scoping the law to `derived` would leave the
+ * overwhelming majority of bindings unguarded.
+ *
+ * Attributes that are machine contracts rather than content (`on*` handlers,
+ * `data-*` — including the durable `data-agent-id` key — and structural ones like
+ * `id`/`htmlFor`/`name`/`type`/`role`/`slot`) are downgraded to `formatted` by the
+ * PRODUCER, because no usage value could make them a text edit. The consumer does
+ * not need to re-derive that list; it only needs the allowlist above.
+ */
+interface PropBinding {
+    /**
+     * Where the bound expression renders: the element's children, or an attribute.
+     *
+     * Parse `attr:` by splitting on the FIRST colon only — namespaced JSX attributes
+     * keep their own colon (`attr:xlink:href` is the attribute `xlink:href`). A
+     * naive `split(':')[1]` silently truncates those.
+     */
+    target: 'children' | `attr:${string}`;
+    /**
+     * Prop name on the OWNING component — the one named by `EditorMeta.propOwner`,
+     * NOT necessarily the component at the usage site. The consumer MUST verify
+     * `propOwner` against the usage component it resolved from the fiber chain and
+     * treat a mismatch as a gap.
+     */
+    prop: string;
+    /**
+     * Routing verdict.
+     *
+     * - `direct`   — the expression is a bare identifier that is a prop of the
+     *                owning component (`{headline}`). Routable.
+     * - `derived`  — the expression's root is a SINGLE prop identifier carrying a
+     *                string-literal fallback, reached directly or through one
+     *                local-const hop (`{title}` where `const title = headline || '…'`).
+     *                Subject to the same consumer-side usage-value law as `direct`
+     *                (see above) — being `derived` is not a stricter licence, just a
+     *                longer trace.
+     * - `formatted`— prop-reachable but NOT routable: member expressions, ternaries,
+     *                template literals, calls (`{brand.slice(0, 1)}`), more than one
+     *                prop identifier, or an expression among mixed children. This is
+     *                the explicit gap marker; `prop` on it is telemetry only.
+     */
+    kind: 'direct' | 'derived' | 'formatted';
+}
+/** Metadata injected into every JSX element by babel-plugin-editor-meta. */
+interface EditorMeta {
+    /** Stable identifier: "file:line:col:componentName" */
+    nodeId: string;
+    /** Relative file path from project root. */
+    file: string;
+    line: number;
+    col: number;
+    /** PascalCase component name or lowercase HTML tag. */
+    componentName: string;
+    /** Safely serializable literal prop values. Dynamic expressions are "__dynamic__". */
+    staticProps: Record<string, unknown> | null;
+    /**
+     * Whether the JSX node is in a reorderable position (2+ siblings).
+     *
+     * ARCH-883 F1: forced to `false` for every kit-origin node (slot-carrying
+     * nodes, and everything emitted with `origin: 'kit'`). Reordering inside a kit
+     * template affects N usages across N projects — a permanent non-objective per
+     * the PRD (§1.3), not a missing feature.
+     */
+    movable: boolean;
+    /**
+     * nodeId of the enclosing JSX parent element, or null for top-level.
+     *
+     * INTRA-FILE BY CONSTRUCTION: the plugin only walks JSX ancestors inside the
+     * file it is transforming, so this never links a kit template node to a screen
+     * usage. Per SDD §2.3 it must NOT be used across the kit↔screen seam — the
+     * editor tree there is derived from the fiber chain, and projection from the
+     * DOM. The root node of a kit template emits `null` here.
+     */
+    parentNodeId: string | null;
+    /**
+     * Curated kit slot label, e.g. `"AuthFrame/aside/headline"` (SDD §2.6).
+     *
+     * Consumed from a `data-kit-slot` attribute at compile time; the attribute is
+     * STRIPPED from the output and never reaches the DOM — it travels on the fiber.
+     * A UI/telemetry label, NEVER a persisted key.
+     *
+     * The plugin treats any well-formed slot string as OPAQUE (non-empty, `/`
+     * separated, ≤4 segments). Validating it against the canonical vocabulary
+     * (`slot-vocabulary`, published by kit-runtime) is the consumer's job — devtools
+     * deliberately takes no dependency on kit-runtime.
+     *
+     * Absent (`undefined`) on nodes with no slot and on bundles built before F1.
+     */
+    slot?: string | null;
+    /**
+     * Prop bindings for this node's rendered expressions (SDD §2.3).
+     *
+     * Emitted only when non-empty — read it as `meta.propBindings ?? []`. Absent on
+     * bundles built before ARCH-883 F1.
+     */
+    propBindings?: PropBinding[];
+    /**
+     * Name of the component whose props `PropBinding.prop` refers to — the nearest
+     * enclosing, module-level component function that destructures its props.
+     *
+     * Emitted only alongside `propBindings`. The consumer MUST check it against the
+     * usage component before offering an edit: a kit-internal helper component
+     * (`function TableRow({ row })`) yields bindings in ITS prop namespace, which is
+     * not the usage's, and routing those would write the wrong prop. Mismatch = gap.
+     */
+    propOwner?: string | null;
+}
+
 interface ArchieDevToolsOptions {
     /**
      * Enable debug logging.
@@ -61,4 +242,4 @@ interface ArchieDevToolsPlugin {
 }
 declare function archieDevTools(options?: ArchieDevToolsOptions): ArchieDevToolsPlugin;
 
-export { type EditorMetaPluginOptions, archieDevTools, babelPluginEditorMeta };
+export { type EditorMeta, type EditorMetaPluginOptions, type PropBinding, archieDevTools, babelPluginEditorMeta };

package/dist/index.d.ts

@@ -10,9 +10,44 @@ import { types, PluginObj } from '@babel/core';
  *
  * The injected prop contains:
  *   nodeId, file, line, col, componentName, staticProps, movable, parentNodeId
+ *   + (ARCH-883 F1) slot, propBindings, propOwner
  *
  * At runtime the Fiber bridge reads `memoizedProps.__editorMeta` to resolve
  * element identity without any DOM attributes.
+ *
+ * ARCH-883 F1 (SDD §2.3/§2.6) adds three compile-time-only things:
+ *
+ *   1. `propBindings` — which of this node's rendered expressions trace back to
+ *      a prop of the enclosing component, and whether that trace is safe enough
+ *      to OFFER as an edit. It never decides what code to write; the write goes
+ *      through the existing server write-paths. Anything the resolver is not
+ *      certain about degrades to a GAP, never to a wrong binding.
+ *   2. `data-kit-slot` consumption — the curated slot label is lifted into the
+ *      meta and the ATTRIBUTE IS STRIPPED, so it never reaches the DOM. The
+ *      plugin treats the string as opaque; validating it against the canonical
+ *      vocabulary (kit-runtime's `slot-vocabulary` export) belongs to the
+ *      consumer. devtools deliberately takes no dependency on kit-runtime.
+ *   3. `movable: false` for kit-origin nodes — reordering inside a kit template
+ *      affects N usages, a permanent non-objective (PRD §1.3).
+ *
+ * `parentNodeId` stays INTRA-FILE by construction (it only ever walks JSX
+ * ancestors within the file being transformed), so it never links a kit template
+ * node to a screen usage; per SDD §2.3 it must not be used across that seam.
+ * See the type docs in `types/editor-meta.ts`.
+ *
+ * ARCH-883 P0-1: the prop value is emitted as a ZERO-ARG ARROW FUNCTION that
+ * returns the meta object literal — `__editorMeta={() => ({...})}` — NOT the
+ * object literal directly. React serializes unknown OBJECT-valued props on
+ * host elements into the DOM (`__editorMeta="[object Object]"` on every
+ * published prototype page — a live production bug, proven by an executed
+ * SSR test in `src/client/dnd/design-mode/__tests__/editor-meta-react-behavior.test.ts`).
+ * Function- and symbol-valued unknown props are silently dropped by React in
+ * SSR, hydration, and client render — never written to the DOM — while
+ * remaining fully readable on `fiber.memoizedProps.__editorMeta` via a call.
+ * Every reader in the Fiber bridge (`fiber-bridge.ts`, `useElementScanner.ts`,
+ * `inspector.standalone.js`) invokes the value when it is a function and
+ * tolerates a raw object when it is not, so bundles built before this change
+ * keep resolving correctly until they are rebuilt.
  */
 
 interface EditorMetaPluginOptions {
@@ -22,11 +57,157 @@ interface EditorMetaPluginOptions {
     instrumentImported?: boolean;
     /** Include exact host source refs for runtime DOM lookup. */
     includeHostSourceRef?: boolean;
+    /**
+     * Where the transformed sources come from (ARCH-883 F1).
+     *
+     * - `'screen'` (default) — per-project `screens/<slug>.jsx`. Reorder is a real
+     *   operation there, so `movable` keeps its structural meaning.
+     * - `'kit'` — the shared kit component library (the `vendor.editor.js` babel
+     *   pre-pass over the kit's `.gen/` sources, SDD §2.1). Every node emits
+     *   `movable: false`: one template backs N usages across N projects, so
+     *   reordering it is a permanent non-objective (PRD §1.3).
+     *
+     * Independently of this flag, a slot-carrying node is kit-origin by definition
+     * and also emits `movable: false`.
+     */
+    origin?: 'screen' | 'kit';
 }
 declare function babelPluginEditorMeta({ types: t }: {
     types: typeof types;
 }, opts?: EditorMetaPluginOptions): PluginObj;
 
+/**
+ * A link between a rendered JSX expression and a prop of the component whose
+ * template contains it (ARCH-883 F1, SDD §2.3).
+ *
+ * `propBindings` decides what UI the editor may OFFER — never what code gets
+ * written. The server resolves the actual write through the existing
+ * `rebuild-screen` / `screen-slice` / `update-shell` paths.
+ *
+ * ROUTABILITY IS AN ALLOWLIST with THREE conditions, both required:
+ *
+ *     const routable =
+ *       (b.kind === 'direct' || b.kind === 'derived') &&
+ *       usageValueIsStringLiteralOrAbsent(usage, b.prop) &&   // consumer-side
+ *       propOwnerMatchesUsageComponent(meta, usage);          // consumer-side
+ *
+ * Everything else is a gap: a `kind: 'formatted'` entry (prop-reachable but not
+ * safely routable) or no entry at all for that target. A resolver false positive
+ * must always degrade to a gap, never to a wrong binding.
+ *
+ * THE USAGE-VALUE LAW APPLIES TO BOTH ROUTABLE KINDS, not only to `derived`.
+ * The plugin sees the kit template, never the usage site, so it cannot enforce
+ * it — the consumer must, for `direct` too. Real-corpus evidence for why: on the
+ * kit, `direct` outnumbers `derived` ~26:1, and a `direct` binding whose usage
+ * value is a computed object (`config={{…}}`, `widgets={list}`) is exactly as
+ * unwritable as a `derived` one. Scoping the law to `derived` would leave the
+ * overwhelming majority of bindings unguarded.
+ *
+ * Attributes that are machine contracts rather than content (`on*` handlers,
+ * `data-*` — including the durable `data-agent-id` key — and structural ones like
+ * `id`/`htmlFor`/`name`/`type`/`role`/`slot`) are downgraded to `formatted` by the
+ * PRODUCER, because no usage value could make them a text edit. The consumer does
+ * not need to re-derive that list; it only needs the allowlist above.
+ */
+interface PropBinding {
+    /**
+     * Where the bound expression renders: the element's children, or an attribute.
+     *
+     * Parse `attr:` by splitting on the FIRST colon only — namespaced JSX attributes
+     * keep their own colon (`attr:xlink:href` is the attribute `xlink:href`). A
+     * naive `split(':')[1]` silently truncates those.
+     */
+    target: 'children' | `attr:${string}`;
+    /**
+     * Prop name on the OWNING component — the one named by `EditorMeta.propOwner`,
+     * NOT necessarily the component at the usage site. The consumer MUST verify
+     * `propOwner` against the usage component it resolved from the fiber chain and
+     * treat a mismatch as a gap.
+     */
+    prop: string;
+    /**
+     * Routing verdict.
+     *
+     * - `direct`   — the expression is a bare identifier that is a prop of the
+     *                owning component (`{headline}`). Routable.
+     * - `derived`  — the expression's root is a SINGLE prop identifier carrying a
+     *                string-literal fallback, reached directly or through one
+     *                local-const hop (`{title}` where `const title = headline || '…'`).
+     *                Subject to the same consumer-side usage-value law as `direct`
+     *                (see above) — being `derived` is not a stricter licence, just a
+     *                longer trace.
+     * - `formatted`— prop-reachable but NOT routable: member expressions, ternaries,
+     *                template literals, calls (`{brand.slice(0, 1)}`), more than one
+     *                prop identifier, or an expression among mixed children. This is
+     *                the explicit gap marker; `prop` on it is telemetry only.
+     */
+    kind: 'direct' | 'derived' | 'formatted';
+}
+/** Metadata injected into every JSX element by babel-plugin-editor-meta. */
+interface EditorMeta {
+    /** Stable identifier: "file:line:col:componentName" */
+    nodeId: string;
+    /** Relative file path from project root. */
+    file: string;
+    line: number;
+    col: number;
+    /** PascalCase component name or lowercase HTML tag. */
+    componentName: string;
+    /** Safely serializable literal prop values. Dynamic expressions are "__dynamic__". */
+    staticProps: Record<string, unknown> | null;
+    /**
+     * Whether the JSX node is in a reorderable position (2+ siblings).
+     *
+     * ARCH-883 F1: forced to `false` for every kit-origin node (slot-carrying
+     * nodes, and everything emitted with `origin: 'kit'`). Reordering inside a kit
+     * template affects N usages across N projects — a permanent non-objective per
+     * the PRD (§1.3), not a missing feature.
+     */
+    movable: boolean;
+    /**
+     * nodeId of the enclosing JSX parent element, or null for top-level.
+     *
+     * INTRA-FILE BY CONSTRUCTION: the plugin only walks JSX ancestors inside the
+     * file it is transforming, so this never links a kit template node to a screen
+     * usage. Per SDD §2.3 it must NOT be used across the kit↔screen seam — the
+     * editor tree there is derived from the fiber chain, and projection from the
+     * DOM. The root node of a kit template emits `null` here.
+     */
+    parentNodeId: string | null;
+    /**
+     * Curated kit slot label, e.g. `"AuthFrame/aside/headline"` (SDD §2.6).
+     *
+     * Consumed from a `data-kit-slot` attribute at compile time; the attribute is
+     * STRIPPED from the output and never reaches the DOM — it travels on the fiber.
+     * A UI/telemetry label, NEVER a persisted key.
+     *
+     * The plugin treats any well-formed slot string as OPAQUE (non-empty, `/`
+     * separated, ≤4 segments). Validating it against the canonical vocabulary
+     * (`slot-vocabulary`, published by kit-runtime) is the consumer's job — devtools
+     * deliberately takes no dependency on kit-runtime.
+     *
+     * Absent (`undefined`) on nodes with no slot and on bundles built before F1.
+     */
+    slot?: string | null;
+    /**
+     * Prop bindings for this node's rendered expressions (SDD §2.3).
+     *
+     * Emitted only when non-empty — read it as `meta.propBindings ?? []`. Absent on
+     * bundles built before ARCH-883 F1.
+     */
+    propBindings?: PropBinding[];
+    /**
+     * Name of the component whose props `PropBinding.prop` refers to — the nearest
+     * enclosing, module-level component function that destructures its props.
+     *
+     * Emitted only alongside `propBindings`. The consumer MUST check it against the
+     * usage component before offering an edit: a kit-internal helper component
+     * (`function TableRow({ row })`) yields bindings in ITS prop namespace, which is
+     * not the usage's, and routing those would write the wrong prop. Mismatch = gap.
+     */
+    propOwner?: string | null;
+}
+
 interface ArchieDevToolsOptions {
     /**
      * Enable debug logging.
@@ -61,4 +242,4 @@ interface ArchieDevToolsPlugin {
 }
 declare function archieDevTools(options?: ArchieDevToolsOptions): ArchieDevToolsPlugin;
 
-export { type EditorMetaPluginOptions, archieDevTools, babelPluginEditorMeta };
+export { type EditorMeta, type EditorMetaPluginOptions, type PropBinding, archieDevTools, babelPluginEditorMeta };