@grampro/kit 2.7.2 → 2.7.3

package/README.md

@@ -14,6 +14,9 @@ Figma design.
 npx @grampro/kit add DataGrid
 ```
 
+Or `npx @grampro/kit add` with no names, to pick from the list: type to search,
+space to select, enter to install.
+
 The source lands in `component-lib/`, or `src/component-lib/` in a project
 with a `src/` folder; `--dest` puts it anywhere you like, and later installs
 follow the first. There is no runtime package to depend on, and nothing to
@@ -218,6 +221,10 @@ version. What is built and tested:
   application supplies. No model is bundled, downloaded or named.
 - **WebMCP** — one tool, `operate_grid`, exposing the same validated boundary to
   a browser agent. Needs no model at all.
+- **`<AgentSurface>`** — wrap a page and every field and grid in it describes
+  itself to a browser agent, from its own props, and is operated through its own
+  validator. One WebMCP tool, `operate_page`, for the whole page; no tool
+  definitions to write
 - A model evaluation harness, with the measurements that justify both
 
 Every producer — a model, a browser agent, a form — proposes. The validator
@@ -227,9 +234,10 @@ it is why no AI path gets a second route into the component.
 Nine of the 27 are agent-operable. The executor abstraction was the open
 question — a grid is driven through an imperative API, and a field is not — and
 it is settled: Combobox and DatePicker are driven through their handles,
-Input, Textarea, NumberInput, Checkbox, Switch and RadioGroup through the
-element their ref already hands back. Neither the contract, the schemas, the
-validator nor the refusals know which.
+Input, Textarea, Checkbox and Switch through the element their ref already
+hands back, and NumberInput and RadioGroup, inside an `<AgentSurface>`, through
+their own commit path — a number is not text, and a group is not one radio.
+Neither the contract, the schemas, the validator nor the refusals know which.
 
 Still open: the components whose value is in what they contain rather than what
 they hold — Menu, Tabs, Accordion, Modal, FileUploader — and the question of

package/index.cjs

@@ -24,7 +24,7 @@ const path = require("path");
 const crypto = require("crypto");
 const yargs = require("yargs/yargs");
 const { hideBin } = require("yargs/helpers");
-const readline = require("readline");
+const ui = require("./tools/ui.cjs");
 
 // Configuration
 const CONFIG = {
@@ -391,7 +391,7 @@ const copyCommonFiles = async (destPath) => {
     const src = path.join(LEGACY_SOURCE_PATH, ...file.src);
     const dest = path.join(destPath, file.dest);
     await fs.copy(src, dest, { overwrite: true });
-    console.log(`✓ ${file.dest} copied successfully`);
+    console.log(`${ui.check()} ${file.dest} copied successfully`);
   }
 };
 
@@ -467,7 +467,7 @@ const installShared = async (destPath, { force = false } = {}) => {
 
     if (order > 0) {
       console.error(
-        `\n✗ This project has shared v${installedVersion}, newer than the v${srcVersion} in this installer.`,
+        `\n${ui.cross()} This project has shared v${installedVersion}, newer than the v${srcVersion} in this installer.`,
       );
       console.error(
         "  Installing it would downgrade the folder and break the components already here.",
@@ -478,11 +478,17 @@ const installShared = async (destPath, { force = false } = {}) => {
       process.exit(1);
     }
 
-    if (order === 0) {
+    // The same version is only "already installed" when it is the same files:
+    // a release that changed shared/ without bumping it must still reach the
+    // project, or the components it brings import files that are not there.
+    const sameFiles = listFiles(src).every(
+      (file) => manifest.files[file] === sha256(path.join(src, file)),
+    );
+    if (order === 0 && sameFiles) {
       console.log(
         edited.length > 0
-          ? `✓ shared v${installedVersion} is already installed (keeping your ${edited.length} edited file(s))`
-          : `✓ shared v${installedVersion} is already installed`,
+          ? `${ui.check()} shared v${installedVersion} is already installed (keeping your ${edited.length} edited file(s))`
+          : `${ui.check()} shared v${installedVersion} is already installed`,
       );
       return;
     }
@@ -490,7 +496,7 @@ const installShared = async (destPath, { force = false } = {}) => {
 
   if (edited.length > 0 && !force) {
     console.error(
-      `\n✗ These files in component-lib/${SHARED_DIR} have local changes:`,
+      `\n${ui.cross()} These files in component-lib/${SHARED_DIR} have local changes:`,
     );
     edited.forEach((file) => console.error(`  - ${file}`));
     console.error(
@@ -541,8 +547,8 @@ const installShared = async (destPath, { force = false } = {}) => {
 
   console.log(
     installedVersion
-      ? `✓ shared updated ${installedVersion} → ${srcVersion}`
-      : `✓ shared v${srcVersion} installed`,
+      ? `${ui.check()} shared updated ${installedVersion} → ${srcVersion}`
+      : `${ui.check()} shared v${srcVersion} installed`,
   );
 };
 
@@ -656,7 +662,7 @@ const writeAntigravityRule = async (root) => {
 
 /**
  * Codex: a pointer in AGENTS.md rather than the skill itself, because that file
- * is always in context and the skill is 5 KB. Everything outside our markers is
+ * is always in context and the skill is about 10 KB. Everything outside our markers is
  * left exactly as it was.
  */
 const writeAgentsPointer = async (root) => {
@@ -727,7 +733,7 @@ const installSkill = async (
   const edited = locallyEdited(destRoot, manifest);
 
   if (edited.length > 0 && !force) {
-    console.error(`${NL}✗ These skill files have local changes:`);
+    console.error(`${NL}${ui.cross()} These skill files have local changes:`);
     edited.forEach((file) => console.error(`  - ${file}`));
     console.error(
       NL +
@@ -793,8 +799,8 @@ const installSkill = async (
 
   console.log(
     installedVersion
-      ? `✓ skill updated ${installedVersion} → ${PACKAGE_VERSION}`
-      : `✓ skill v${PACKAGE_VERSION} installed`,
+      ? `${ui.check()} skill updated ${installedVersion} → ${PACKAGE_VERSION}`
+      : `${ui.check()} skill v${PACKAGE_VERSION} installed`,
   );
   console.log(`  ${SKILL_DEST_DIR}/ (canonical, ${listFiles(src).length} files)`);
   if (targets.includes("claude")) {
@@ -902,10 +908,17 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
     process.exit(1);
   }
 
-  const pkgPath = path.join(process.cwd(), "package.json");
-  const libraryVersion = fs.existsSync(pkgPath)
-    ? readJson(pkgPath, {}).version || "unknown"
-    : "unknown";
+  /*
+   * Each component is stamped with the kit version it was installed from —
+   * its install record, else the passport it shipped with — not with this
+   * project's own version. Stamping the project's version made every
+   * regenerated passport differ from the shipped one, so `passport --check`
+   * failed for components nobody had touched.
+   */
+  const libraryVersion = (name, dir) =>
+    readJson(path.join(dir, ".install-manifest.json"), {})?.version ||
+    readJson(path.join(dir, "passport.json"), {})?.source?.libraryVersion ||
+    PACKAGE_VERSION;
 
   const options = {
     libRoot: dest,
@@ -913,6 +926,7 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
     libraryVersion,
     includeLocal: true,
     coverageThreshold: undefined,
+    regenerate: `npx ${CLI_NAME} passport`,
   };
 
   try {
@@ -924,7 +938,7 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
           continue;
         }
         for (const issue of row.problems) {
-          console.log(`  ${issue.level === "error" ? "✗" : "!"} ${issue.component}: ${issue.message}`);
+          console.log(`  ${issue.level === "error" ? ui.cross(process.stdout) : ui.c.yellow("!")} ${issue.component}: ${issue.message}`);
         }
       }
       console.log(`${NL}${report.length} component(s) · ${errors} error(s) · ${warnings} warning(s)`);
@@ -934,9 +948,9 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
 
     const { results, written } = passport.generate(options);
     const errors = results.flatMap((r) => r.issues.filter((i) => i.level === "error"));
-    for (const issue of errors) console.error(`  ✗ ${issue.component}: ${issue.message}`);
+    for (const issue of errors) console.error(`  ${ui.cross()} ${issue.component}: ${issue.message}`);
     console.log(
-      `${NL}✓ ${results.length} passport(s) regenerated · ${written.length} changed`,
+      `${NL}${ui.check()} ${results.length} passport(s) regenerated · ${written.length} changed`,
     );
     if (errors.length > 0) process.exit(1);
   } catch (error) {
@@ -1038,14 +1052,14 @@ const copyComponent = async (component, destPath, current = false, { force = fal
     if (outcome === "updated") {
       console.log(
         previous && previous !== PACKAGE_VERSION
-          ? `✓ Component ${component} updated ${previous} → ${PACKAGE_VERSION}`
-          : `✓ Component ${component} replaced with ${PACKAGE_VERSION}${force ? " (--force)" : ""}`,
+          ? `${ui.check()} Component ${component} updated ${previous} → ${PACKAGE_VERSION}`
+          : `${ui.check()} Component ${component} replaced with ${PACKAGE_VERSION}${force ? " (--force)" : ""}`,
       );
     } else if (outcome === "unchanged") {
-      console.log(`✓ Component ${component} already up to date (${PACKAGE_VERSION})`);
+      console.log(`${ui.check()} Component ${component} already up to date (${PACKAGE_VERSION})`);
     } else {
       console.log(
-        `✓ Component ${component} installed successfully ${
+        `${ui.check()} Component ${component} installed successfully ${
           component === "Grid"
             ? "This Version of Grid will be deprecated soon. Please Install The New Data Grid Component"
             : ""
@@ -1069,8 +1083,8 @@ const reportKept = (component, status) => {
     files.length ? `    ${label}: ${files.slice(0, 6).join(", ")}${files.length > 6 ? `, +${files.length - 6} more` : ""}` : null;
   console.error(
     status.state === "unknown"
-      ? `✗ ${component} was not replaced: it was installed before 2.7.2 and differs from ${PACKAGE_VERSION}, so it may hold your changes.`
-      : `✗ ${component} was not replaced: it has changes made since it was installed.`,
+      ? `${ui.cross()} ${component} was not replaced: it was installed before 2.7.2 and differs from ${PACKAGE_VERSION}, so it may hold your changes.`
+      : `${ui.cross()} ${component} was not replaced: it has changes made since it was installed.`,
   );
   for (const line of [list("changed", status.changed), list("deleted", status.missing)].filter(Boolean)) {
     console.error(line);
@@ -1098,7 +1112,7 @@ const installComponentWithDependencies = async (
 
   if (pendingInstalls.length === 0) {
     console.log(
-      `✓ ${component} and all its dependencies are already installed.`,
+      `${ui.check()} ${component} and all its dependencies are already installed.`,
     );
     return;
   }
@@ -1144,7 +1158,7 @@ const installMultipleComponents = async (
 
   if (pendingInstalls.length === 0) {
     console.log(
-      "✓ All selected components and their dependencies are already installed.",
+      `${ui.check()} All selected components and their dependencies are already installed.`,
     );
     return;
   }
@@ -1175,95 +1189,44 @@ const installMultipleComponents = async (
   console.log(`\nFor documentation visit: ${CONFIG.docs}`);
 };
 
-const interactiveComponentSelector = async (current = false) => {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    let selectedComponents = new Set();
-    let currentIndex = 0;
-
-    const renderMenu = () => {
-      console.clear();
-      console.log("🚀 Component Installer - Interactive Mode");
-      console.log(
-        "Use ↑/↓ arrow keys to navigate, SPACE to select/deselect, ENTER to install\n",
-      );
-
-      const availableComponents = getAvailableComponents(current);
-
-      availableComponents.forEach((component, index) => {
-        const isSelected = selectedComponents.has(component);
-        const isCurrentIndex = index === currentIndex;
-        const deps = CONFIG.dependencies[component]
-          ? ` (requires: ${CONFIG.dependencies[component].join(", ")})`
-          : "";
-
-        const prefix = isCurrentIndex ? ">" : " ";
-        const checkbox = isSelected ? "☑" : "☐";
-        const line = `${prefix} ${checkbox} ${component}${deps}`;
-
-        if (isCurrentIndex) {
-          console.log(`\x1b[36m${line}\x1b[0m`); // Cyan highlight
-        } else {
-          console.log(line);
-        }
-      });
-
-      console.log(`\nSelected: ${selectedComponents.size} components`);
-      console.log("Press ENTER to install selected components, or 'q' to quit");
-    };
-
-    const handleKeyPress = (key) => {
-      switch (key) {
-        case "": // Up arrow
-          currentIndex = Math.max(0, currentIndex - 1);
-          renderMenu();
-          break;
-        case "": // Down arrow
-          currentIndex = Math.min(
-            getAvailableComponents(current).length - 1,
-            currentIndex + 1,
-          );
-          renderMenu();
-          break;
-        case " ": // Space bar
-          const component = getAvailableComponents(current)[currentIndex];
-          if (selectedComponents.has(component)) {
-            selectedComponents.delete(component);
-          } else {
-            selectedComponents.add(component);
-          }
-          renderMenu();
-          break;
-        case "\r": // Enter
-          if (selectedComponents.size > 0) {
-            rl.close();
-            resolve(Array.from(selectedComponents));
-          }
-          break;
-        case "q":
-          rl.close();
-          resolve([]);
-          break;
-      }
-    };
-
-    // Enable raw mode to capture arrow keys
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("data", handleKeyPress);
-
-    renderMenu();
+/*
+ * Where each component sits in the docs' navigation, shown beside it in the
+ * picker and searchable: typing "overlay" narrows the list to the overlays.
+ */
+const GROUPS = {
+  Inputs: ["Button", "Checkbox", "Combobox", "DatePicker", "FileUploader", "Input", "NumberInput", "RadioGroup", "Switch", "Textarea"],
+  Data: ["DataGrid"],
+  Overlays: ["Dialog", "Menu", "Modal", "Popover", "Tooltip"],
+  Feedback: ["Alert", "Progress", "Skeleton", "Spinner", "Toaster"],
+  Display: ["Accordion", "Avatar", "Badge", "Card"],
+  Navigation: ["Breadcrumb", "Tabs"],
+};
+const groupOf = (component) =>
+  Object.keys(GROUPS).find((group) => GROUPS[group].includes(component)) || "";
+
+/** The one-line purpose a component's passport gives, for the picker's hint line. */
+const purposeOf = (component, current) => {
+  if (!current) return "";
+  const passport = readJson(path.join(SOURCE_PATH, folderFor(component, true), "passport.json"));
+  return (passport && passport.purpose) || "";
+};
 
-    rl.on("close", () => {
-      process.stdin.setRawMode(false);
-      process.stdin.pause();
+const interactiveComponentSelector = async (current = false, destPath) => {
+  const { multiselect } = require("./tools/prompt.cjs");
+  const options = getAvailableComponents(current)
+    .map((component) => ({
+      value: component,
+      tag: current ? groupOf(component) : "",
+      hint: purposeOf(component, current),
+      note: destPath && checkComponentExists(component, destPath, current) ? "installed" : "",
+    }))
+    // The docs' order of groups, alphabetical within each.
+    .sort((a, b) => {
+      const order = Object.keys(GROUPS);
+      return order.indexOf(a.tag) - order.indexOf(b.tag) || a.value.localeCompare(b.value);
     });
-  });
+  const picked = await multiselect({ message: "Which components?", options });
+  return picked || [];
 };
 
 const parseMultipleComponents = (componentString) => {
@@ -1420,7 +1383,7 @@ const main = async () => {
     .example("$0 mcp install --for codex", "Only write the Codex config")
     .example("$0 secret set figma", "Store a Figma token in the OS credential store")
     .example("$0 design ./design.json", "Split a whole-file Figma export into design/")
-    .example("$0 -i", "Interactive selection")
+    .example("$0 add", "Pick components interactively (same as -i)")
     .help().argv;
 
   /*
@@ -1497,10 +1460,15 @@ const main = async () => {
     if (parsed.command === "passport") argv.passport = true;
     if (parsed.command === "add") {
       if (parsed.operands.length === 0) {
-        console.log(`Which component? Try: ${CLI_NAME} add Button    (or: ${CLI_NAME} list)`);
-        return;
+        // In a terminal, a bare `add` opens the picker; in a script it says what to type.
+        if (process.stdin.isTTY && process.stdout.isTTY) argv.interactive = true;
+        else {
+          console.log(`Which component? Try: ${CLI_NAME} add Button    (or: ${CLI_NAME} list)`);
+          return;
+        }
+      } else {
+        argv.add = parsed.operands.join(",");
       }
-      argv.add = parsed.operands.join(",");
     }
   } else if (argv.add || argv.list || argv.skill || argv.passport) {
     console.log(`Tip: the shorter form is \`${CLI_NAME} add <Component>\`.`);
@@ -1532,21 +1500,38 @@ const main = async () => {
 
   // Interactive mode
   if (argv.interactive) {
-    console.log("Starting interactive component selector...\n");
-    const selectedComponents = await interactiveComponentSelector(current);
+    const destPath = resolveDestPath(argv.dest);
+    const where = path.relative(process.cwd(), destPath) || ".";
+    ui.intro(`GramproKit ${PACKAGE_VERSION}`);
+    let selectedComponents;
+    try {
+      selectedComponents = await interactiveComponentSelector(current, destPath);
+    } catch (error) {
+      ui.outro(ui.c.red(error.message));
+      process.exitCode = 1;
+      return;
+    }
 
     if (selectedComponents.length === 0) {
-      console.log("No components selected. Exiting...");
+      ui.outro(ui.c.dim("Nothing installed."));
       return;
     }
+    console.log(ui.c.gray(ui.s.bar));
+    console.log(`${ui.c.gray(ui.s.bar)}  ${ui.c.dim(`Installing into ${where}/`)}`);
+    console.log("");
 
-    const destPath = resolveDestPath(argv.dest);
     await fs.ensureDir(destPath);
 
     await copySupportFiles(destPath, current, { force: argv.force });
 
     // Install selected components
     await installMultipleComponents(selectedComponents, destPath, current, { force: argv.force });
+    console.log("");
+    ui.outro(
+      process.exitCode
+        ? ui.c.yellow("Done, with the warnings above.")
+        : `${ui.c.green("Done.")} Import them from ${ui.c.cyan(`${where}/`)}`,
+    );
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grampro/kit",
-  "version": "2.7.2",
+  "version": "2.7.3",
   "description": "GramproKit — an agent-native UI runtime for React. Copy-in components you own, each publishing a contract that software can read.",
   "type": "module",
   "files": [

package/source/components/accordion/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/open.ts",

package/source/components/alert/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/live.ts",

package/source/components/avatar/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/identity.ts",
       "core/index.ts",

package/source/components/badge/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/breadcrumb/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/trail.ts",

package/source/components/button/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/state.ts",

package/source/components/card/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/trend.ts",

package/source/components/checkbox/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/agent.ts",
       "core/group.ts",
@@ -23,7 +23,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:864a782462120954cea168efe6df111474541556f8518107677c1098cceaa035"
+    "sourceHash": "sha256:3bb3c0d76ef4b8d42f6b3bc0a3cdd203a90a1662175ec62ae40eba49ce7ad423"
   },
   "purpose": "A single native checkbox, and CheckboxGroup for several that share a name, with mixed state, a select-all and group-level validation.",
   "props": [

package/source/components/checkbox/passport.manual.json

@@ -5,7 +5,7 @@
   "intentDomains": [
     "ActionIntent"
   ],
-  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap.",
+  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap. Inside an <AgentSurface> the component registers itself with these operations; NumberInput and RadioGroup are then written through their own commit path rather than the element.",
   "operations": {
     "setValue": {
       "summary": "Write a value into the field, as though a person had entered it.",

package/source/components/checkbox/react/Checkbox.tsx

@@ -14,6 +14,7 @@ import {
 } from "react";
 import { useControllableState } from "../../shared/react/useControllableState";
 import { describeField } from "../../shared/core/field";
+import { labelText, useAgentSurfaceField } from "../../shared/react/agentSurfaceContext";
 import type { CheckboxSize, CheckedState } from "../core/types";
 import { CheckboxGroupContext } from "./context";
 import { cx, type CheckboxSlot } from "./props";
@@ -107,6 +108,19 @@ export function Checkbox(props: CheckboxProps) {
     onCheckedChange?.(next);
   };
 
+  // Inside an <AgentSurface>, offered to an agent as a yes/no it can set.
+  useAgentSurfaceField(() => ({
+    contract: {
+      component: "Checkbox",
+      kind: "boolean",
+      label: labelText(label, inputProps["aria-label"], name, value),
+      disabled: disabled || group?.disabled,
+      required,
+      operations: ["setValue", "clear", "focus"],
+    },
+    target: () => inputRef.current,
+  }));
+
   const invalid = Boolean(error) || (group?.invalid ?? false);
   const describedBy = describeField(id, { extra: describedByProp, description, error });
 

package/source/components/combobox/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/agent.ts",
       "core/filter.ts",
@@ -24,9 +24,10 @@
       "react/icons.tsx",
       "react/locale.ts",
       "react/props.ts",
+      "react/surface.ts",
       "react/useCombobox.ts"
     ],
-    "sourceHash": "sha256:5243c2cc6863f8c2dcd248c2fd46417390fec66a8d5b0d405177a372e9c0566f"
+    "sourceHash": "sha256:c8001ea7c65beeed1b50d9f35cb0fcc447d01cea88128dda3d8b3584bd542496"
   },
   "purpose": "Select and MultiSelect: a searchable combobox for one or many values, with options in the browser's top layer, optional virtualisation and create-on-type.",
   "props": [

package/source/components/combobox/passport.manual.json

@@ -7,7 +7,7 @@
     "Recommendation",
     "Classification"
   ],
-  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap.",
+  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap. Inside an <AgentSurface> the component registers itself with these operations; NumberInput and RadioGroup are then written through their own commit path rather than the element.",
   "operations": {
     "setValue": {
       "summary": "Write a value into the field, as though a person had entered it.",

package/source/components/combobox/react/MultiSelect.tsx

@@ -8,6 +8,7 @@ import { Listbox } from "./Listbox";
 import { defaultComboboxText } from "./locale";
 import { ComboboxPopover } from "./Popover";
 import { cx, type ComboboxHandle, type ComboboxSharedProps } from "./props";
+import { useComboboxSurface } from "./surface";
 import { useCombobox } from "./useCombobox";
 
 export interface MultiSelectProps<V extends OptionValue = string> extends ComboboxSharedProps<V> {
@@ -89,6 +90,18 @@ export function MultiSelect<V extends OptionValue = string>(props: MultiSelectPr
   const visibleTags = hidden > 0 ? selectedOptions.slice(0, maxVisibleTags) : selectedOptions;
 
   useImperativeHandle(ref, () => combobox.handle, [combobox.handle]);
+  useComboboxSurface({
+    component: "MultiSelect",
+    label,
+    ariaLabel: props["aria-label"],
+    name,
+    required,
+    disabled,
+    options,
+    mode: props.mode,
+    max: max,
+    handle: combobox.handle,
+  });
 
   const selectableVisible = combobox.entries.filter(
     (entry) => !entry.option.disabled && !combobox.isSelected(entry.option.value),

package/source/components/combobox/react/Select.tsx

@@ -8,6 +8,7 @@ import { ChevronIcon, XIcon } from "./icons";
 import { Listbox } from "./Listbox";
 import { ComboboxPopover } from "./Popover";
 import { cx, type ComboboxHandle, type ComboboxSharedProps } from "./props";
+import { useComboboxSurface } from "./surface";
 import { useCombobox } from "./useCombobox";
 
 export interface SelectProps<V extends OptionValue = string> extends ComboboxSharedProps<V> {
@@ -83,6 +84,18 @@ export function Select<V extends OptionValue = string>(props: SelectProps<V>) {
   const selected = combobox.selectedOptions[0];
 
   useImperativeHandle(ref, () => combobox.handle, [combobox.handle]);
+  useComboboxSurface({
+    component: "Select",
+    label,
+    ariaLabel: props["aria-label"],
+    name,
+    required,
+    disabled,
+    options,
+    mode: props.mode,
+    max: undefined,
+    handle: combobox.handle,
+  });
 
   return (
     <div