From e216b7a2b0093a6d58ddbde8b2900d8fdb878479 Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Wed, 21 Oct 2026 11:15:57 +1100
Subject: [PATCH 1/7] refactor(core): share the warn-once dev guard as
 useOnceWarnings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../core/src/components/ai-chat/ai-chat.tsx   | 24 +------------------
 .../components/filter-rail/filter-rail.tsx    | 12 +++-------
 packages/core/src/hooks/use-once-warnings.ts  | 22 +++++++++++++++++
 3 files changed, 26 insertions(+), 32 deletions(-)
 create mode 100644 packages/core/src/hooks/use-once-warnings.ts

diff --git a/packages/core/src/components/ai-chat/ai-chat.tsx b/packages/core/src/components/ai-chat/ai-chat.tsx
index 2dae9973b..c280def42 100644
--- a/packages/core/src/components/ai-chat/ai-chat.tsx
+++ b/packages/core/src/components/ai-chat/ai-chat.tsx
@@ -1,15 +1,14 @@
 import {
   Children,
   isValidElement,
-  useEffect,
   useMemo,
-  useRef,
   type ComponentProps,
   type ReactElement,
   type ReactNode,
 } from "react";
 
 import type { AIChatStatus } from "@/ai/use-ai-chat";
+import { useOnceWarnings } from "@/hooks/use-once-warnings";
 import { cn } from "@/lib/utils";
 import { Action, Actions } from "./actions";
 import { AIChatContext } from "./ai-chat-context";
@@ -79,27 +78,6 @@ type AIChatProps = Omit<ComponentProps<"div">, "children"> & {
  * </Card.Root>
  * ```
  */
-/**
- * Emits each distinct message once per mounted root.
- *
- * The root re-renders on every streamed token, so warning inline during
- * render would repeat the same line hundreds of times in a single response —
- * and twice per render again under StrictMode. Deliberately not gated on
- * `process.env.NODE_ENV`: this package has no other reference to `process`,
- * and adding one would break consumers whose bundler does not shim it.
- */
-function useOnceWarnings(warnings: readonly string[]) {
-  const seen = useRef<Set<string>>(new Set());
-
-  useEffect(() => {
-    for (const warning of warnings) {
-      if (seen.current.has(warning)) continue;
-      seen.current.add(warning);
-      console.warn(warning);
-    }
-  });
-}
-
 type Regions = {
   header?: ReactElement;
   conversation?: ReactElement;
diff --git a/packages/core/src/components/filter-rail/filter-rail.tsx b/packages/core/src/components/filter-rail/filter-rail.tsx
index 43069ef6d..2f8229dbe 100644
--- a/packages/core/src/components/filter-rail/filter-rail.tsx
+++ b/packages/core/src/components/filter-rail/filter-rail.tsx
@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { useCallback, useMemo, useRef, useState, type ReactNode } from "react";
+import { useOnceWarnings } from "@/hooks/use-once-warnings";
 import { cn } from "@/lib/utils";
 import type { CollectionControl, Filter } from "@/types/collection";
 import { Sheet } from "../sheet";
@@ -50,14 +51,7 @@ function Provider<TField extends string = string, TSectionField extends TField =
   onChangeRef.current = onFilterChange;
 
   // Dev guard: two sections on one field silently overwrite each other.
-  const warned = useRef(new Set<string>());
-  useEffect(() => {
-    for (const problem of findRailProblems(anySections)) {
-      if (warned.current.has(problem)) continue;
-      warned.current.add(problem);
-      console.warn(problem);
-    }
-  }, [anySections]);
+  useOnceWarnings(useMemo(() => findRailProblems(anySections), [anySections]));
 
   const owned = useMemo(() => railFields(anySections), [anySections]);
   const filters = anyControl.filters;
diff --git a/packages/core/src/hooks/use-once-warnings.ts b/packages/core/src/hooks/use-once-warnings.ts
new file mode 100644
index 000000000..6fa6afdb0
--- /dev/null
+++ b/packages/core/src/hooks/use-once-warnings.ts
@@ -0,0 +1,22 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Dev guard: logs each distinct warning once per mounted component.
+ *
+ * Runs in an effect rather than inline so a component that re-renders often
+ * (or twice under StrictMode) doesn't repeat the same line. Deliberately not
+ * gated on `process.env.NODE_ENV`: this package has no other reference to
+ * `process`, and adding one would break consumers whose bundler does not
+ * shim it.
+ */
+export function useOnceWarnings(warnings: readonly string[]) {
+  const seen = useRef<Set<string>>(new Set());
+
+  useEffect(() => {
+    for (const warning of warnings) {
+      if (seen.current.has(warning)) continue;
+      seen.current.add(warning);
+      console.warn(warning);
+    }
+  });
+}

From 4b01802351e2944e43d270d7ed95f4e6b2bfdfee Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Wed, 21 Oct 2026 11:16:00 +1100
Subject: [PATCH 2/7] fix(field): warn when Field.Control renders a self-framed
 control

Passing Select, Combobox, Autocomplete, Checkbox, Textarea or the date
controls to Field.Control's render draws a second frame. Warn in the
console and document which controls go directly under Field.Root.

Refs tailor-inc/platform-planning#1977

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/field-control-render-warning.md    |  5 ++
 docs-manifest.json                            | 18 +++----
 docs-src/components/form.docs.outline.md      | 26 ++++++----
 docs-src/components/select.docs.outline.md    | 11 +++++
 docs-src/patterns/form-modal.docs.outline.md  |  5 +-
 docs/components/form.md                       | 26 ++++++----
 docs/components/select.md                     | 11 +++++
 docs/patterns/form-modal.md                   |  5 +-
 .../core/src/components/field/field.test.tsx  | 48 +++++++++++++++++++
 packages/core/src/components/field/field.tsx  | 45 +++++++++++++++--
 10 files changed, 167 insertions(+), 33 deletions(-)
 create mode 100644 .changeset/field-control-render-warning.md

diff --git a/.changeset/field-control-render-warning.md b/.changeset/field-control-render-warning.md
new file mode 100644
index 000000000..465a9d07d
--- /dev/null
+++ b/.changeset/field-control-render-warning.md
@@ -0,0 +1,5 @@
+---
+"@tailor-platform/app-shell": patch
+---
+
+`Field.Control` now logs a console warning when it is given an AppShell control that draws its own frame through `render`, such as `<Field.Control render={<Select />} />`. That composition renders a double border. `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, and `DateRangePicker` go directly under `Field.Root` instead. The Form, Select, and form-modal docs now say which controls go where.
diff --git a/docs-manifest.json b/docs-manifest.json
index d77b51ac4..03272dfac 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -699,9 +699,9 @@
       "symbols": ["Form", "FormProps"],
       "hashes": {
         "typeSurface": "7b374d45d53d4535",
-        "outline": "79c9b0f08ca38027",
+        "outline": "a2cfe48049a3e5ea",
         "snapshot": "88a0c82baaaa2a08",
-        "outputMd": "91d901b17aed7781",
+        "outputMd": "d6ec66ffc180b303",
         "examples": null
       }
     },
@@ -733,9 +733,9 @@
       "symbols": [],
       "hashes": {
         "typeSurface": null,
-        "outline": "3301b263f6802090",
+        "outline": "a39589955fe582c8",
         "snapshot": null,
-        "outputMd": "9d068e568c9f3bdc",
+        "outputMd": "be00d1109761b7f1",
         "examples": "7836309f2df327ee"
       }
     },
@@ -1209,9 +1209,9 @@
       "symbols": ["Select", "SelectAsyncFetcher"],
       "hashes": {
         "typeSurface": "429710973dfa912b",
-        "outline": "721e8995f53f0e8f",
+        "outline": "3eba8d13da1df95c",
         "snapshot": "68fd61885280b114",
-        "outputMd": "ae287e2bb5abc1c6",
+        "outputMd": "a55198c8cc711bd8",
         "examples": "1ce89cec30045466"
       }
     },
@@ -1759,14 +1759,14 @@
     "packages/core/skills/app-shell-patterns/references/components/dialog.md": "ec6a0ac098d1d87a",
     "packages/core/skills/app-shell-patterns/references/components/document-progress-card.md": "d0fb940f685f8869",
     "packages/core/skills/app-shell-patterns/references/components/filter-rail.md": "c6a48c4d8e8b0078",
-    "packages/core/skills/app-shell-patterns/references/components/form.md": "91d901b17aed7781",
+    "packages/core/skills/app-shell-patterns/references/components/form.md": "d6ec66ffc180b303",
     "packages/core/skills/app-shell-patterns/references/components/global-header-layout.md": "dd2b0da3702cf8d9",
     "packages/core/skills/app-shell-patterns/references/components/grid.md": "9051eb53dde4179f",
     "packages/core/skills/app-shell-patterns/references/components/input.md": "a3a6c9679af99d37",
     "packages/core/skills/app-shell-patterns/references/components/layout.md": "66696139a46fabb0",
     "packages/core/skills/app-shell-patterns/references/components/menu.md": "ceb4a05822538d20",
     "packages/core/skills/app-shell-patterns/references/components/metric-card.md": "5a1c557768c6590f",
-    "packages/core/skills/app-shell-patterns/references/components/select.md": "ae287e2bb5abc1c6",
+    "packages/core/skills/app-shell-patterns/references/components/select.md": "a55198c8cc711bd8",
     "packages/core/skills/app-shell-patterns/references/components/sheet.md": "1f81ebd562c50371",
     "packages/core/skills/app-shell-patterns/references/components/sidebar-group.md": "a36192df64f16adc",
     "packages/core/skills/app-shell-patterns/references/components/sidebar-item.md": "9236c03e53aa79f2",
@@ -1807,7 +1807,7 @@
     "packages/core/skills/app-shell-patterns/references/api/use-time-zone.md": "30c15545ab3c4954",
     "packages/core/skills/app-shell-patterns/references/api/use-toast.md": "30983a761bc61593",
     "packages/core/skills/app-shell-patterns/references/patterns/form-composer.md": "ed187ac3a0773d3d",
-    "packages/core/skills/app-shell-patterns/references/patterns/form-modal.md": "9d068e568c9f3bdc",
+    "packages/core/skills/app-shell-patterns/references/patterns/form-modal.md": "be00d1109761b7f1",
     "packages/core/skills/app-shell-patterns/references/patterns/form-sectioned.md": "d31cd3ae6ad0790c",
     "packages/core/skills/app-shell-patterns/references/patterns/form-single-page.md": "10a0f4d91a120752",
     "packages/core/skills/app-shell-patterns/references/patterns/form-wizard.md": "851afb4672da6673",
diff --git a/docs-src/components/form.docs.outline.md b/docs-src/components/form.docs.outline.md
index 08958cbd5..1bef5f943 100644
--- a/docs-src/components/form.docs.outline.md
+++ b/docs-src/components/form.docs.outline.md
@@ -102,14 +102,14 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Sub-components
 
-| Sub-component       | Description                                                                                   |
-| ------------------- | --------------------------------------------------------------------------------------------- |
-| `Field.Root`        | Context boundary for a single field. Manages validation state.                                |
-| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                            |
-| `Field.Control`     | Styled `<input>`. Can be omitted when using a Base UI-backed AppShell component as the input. |
-| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                         |
-| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                     |
-| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.             |
+| Sub-component       | Description                                                                            |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `Field.Root`        | Context boundary for a single field. Manages validation state.                         |
+| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                     |
+| `Field.Control`     | Styled text `<input>`. Other AppShell controls go directly under `Field.Root` instead. |
+| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                  |
+| `Field.Error`       | Validation error message. Use `match` to target specific validity states.              |
+| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.      |
 
 ### Field.Root Props
 
@@ -136,7 +136,15 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Using Another AppShell Component as the Control
 
-`Field.Control` can be omitted when using a Base UI-backed AppShell component (e.g. `Select`, `Combobox`). The component registers itself with the `Field` context automatically, inheriting label association and validation state.
+`Field.Control` is a text input. It is the control for plain text-like fields, and you can pass it a native element such as `render={<textarea />}`. Every other AppShell control goes **directly under `Field.Root`**, as a sibling of `Field.Label`. The control registers itself with the `Field` context, so it gets label association, `aria-describedby`, `disabled`, and validation state without `Field.Control`.
+
+| Control                                                                                                                         | Where it goes                                     |
+| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Plain text, email, number, password, … input                                                                                    | `<Field.Control type="…" />`                      |
+| Native element (`<textarea>`, `<input type="…">`)                                                                               | `<Field.Control render={<textarea />} />`         |
+| `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, `DateRangePicker` (and their `.Async`) | Directly under `Field.Root` — not `Field.Control` |
+
+Do not pass these controls to `Field.Control`'s `render` prop. They draw their own frame, so `<Field.Control render={<Select />} />` renders a second border around the select. `Field.Control` also passes them `<input>` props they don't take. `Field.Control` logs a console warning when it detects this.
 
 ```tsx
 const [country, setCountry] = React.useState<string | null>(null);
diff --git a/docs-src/components/select.docs.outline.md b/docs-src/components/select.docs.outline.md
index 1c89d19cc..9c499555a 100644
--- a/docs-src/components/select.docs.outline.md
+++ b/docs-src/components/select.docs.outline.md
@@ -161,6 +161,17 @@ const { Root, Trigger, Value, Content, Item, Group, GroupLabel, Separator } = Se
 
 ## Form submission
 
+Inside a form, place `Select` directly under `Field.Root`, not inside `Field.Control`. `Select` draws
+its own trigger and registers with the field itself, so `<Field.Control render={<Select />} />`
+renders a second frame around it.
+
+```tsx
+<Field.Root name="country">
+  <Field.Label>Country</Field.Label>
+  <Select items={["Japan", "United States"]} placeholder="Select a country" />
+</Field.Root>
+```
+
 Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary —
 see [Form](./form.md). They matter for **native** submission: a plain `<form>`, `new FormData(form)`,
 or a server action.
diff --git a/docs-src/patterns/form-modal.docs.outline.md b/docs-src/patterns/form-modal.docs.outline.md
index 7298de034..b1f76d24c 100644
--- a/docs-src/patterns/form-modal.docs.outline.md
+++ b/docs-src/patterns/form-modal.docs.outline.md
@@ -67,7 +67,9 @@ placeholder.
   render_ — a submit gate, a dependent placeholder, a live character count. That state is
   load-bearing, not mirrored; see `form/composer`.
 - **`Field.Control` is already a styled input.** Write `<Field.Control />`, not
-  `<Field.Control render={<Input />} />`.
+  `<Field.Control render={<Input />} />`. Every other control — `Select`, `Combobox`,
+  `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker` — goes directly under
+  `Field.Root`. Passing one to `Field.Control`'s `render` draws a second frame around it.
 - **Object items need `itemToStringValue`.** Items shaped `{ value, label }` submit `value`
   automatically; any other object submits as a JSON string unless you supply it.
 - **Server errors go through `Form`'s `errors` prop**, keyed by field `name` — not a toast or a
@@ -85,4 +87,5 @@ placeholder.
 - Registering the create path as a separate top-level route — that unmounts the parent list
 - Reaching for React Hook Form on a form this size — `onFormSubmit` already covers it
 - Holding a `Select`/`Combobox` value in `useState` just to submit it — `Field.Root` already does
+- Wrapping a `Select`/`Combobox` in `Field.Control` (`render={<Select />}`) — a double frame
 - Surfacing API validation failures in a toast or banner instead of routing them via `errors`
diff --git a/docs/components/form.md b/docs/components/form.md
index be7acb69f..5ac472ccb 100644
--- a/docs/components/form.md
+++ b/docs/components/form.md
@@ -100,14 +100,14 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Sub-components
 
-| Sub-component       | Description                                                                                   |
-| ------------------- | --------------------------------------------------------------------------------------------- |
-| `Field.Root`        | Context boundary for a single field. Manages validation state.                                |
-| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                            |
-| `Field.Control`     | Styled `<input>`. Can be omitted when using a Base UI-backed AppShell component as the input. |
-| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                         |
-| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                     |
-| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.             |
+| Sub-component       | Description                                                                            |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `Field.Root`        | Context boundary for a single field. Manages validation state.                         |
+| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                     |
+| `Field.Control`     | Styled text `<input>`. Other AppShell controls go directly under `Field.Root` instead. |
+| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                  |
+| `Field.Error`       | Validation error message. Use `match` to target specific validity states.              |
+| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.      |
 
 ### Field.Root Props
 
@@ -134,7 +134,15 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Using Another AppShell Component as the Control
 
-`Field.Control` can be omitted when using a Base UI-backed AppShell component (e.g. `Select`, `Combobox`). The component registers itself with the `Field` context automatically, inheriting label association and validation state.
+`Field.Control` is a text input. It is the control for plain text-like fields, and you can pass it a native element such as `render={<textarea />}`. Every other AppShell control goes **directly under `Field.Root`**, as a sibling of `Field.Label`. The control registers itself with the `Field` context, so it gets label association, `aria-describedby`, `disabled`, and validation state without `Field.Control`.
+
+| Control                                                                                                                         | Where it goes                                     |
+| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Plain text, email, number, password, … input                                                                                    | `<Field.Control type="…" />`                      |
+| Native element (`<textarea>`, `<input type="…">`)                                                                               | `<Field.Control render={<textarea />} />`         |
+| `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, `DateRangePicker` (and their `.Async`) | Directly under `Field.Root` — not `Field.Control` |
+
+Do not pass these controls to `Field.Control`'s `render` prop. They draw their own frame, so `<Field.Control render={<Select />} />` renders a second border around the select. `Field.Control` also passes them `<input>` props they don't take. `Field.Control` logs a console warning when it detects this.
 
 ```tsx
 const [country, setCountry] = React.useState<string | null>(null);
diff --git a/docs/components/select.md b/docs/components/select.md
index c141ab87c..9d82b7562 100644
--- a/docs/components/select.md
+++ b/docs/components/select.md
@@ -171,6 +171,17 @@ const { Root, Trigger, Value, Content, Item, Group, GroupLabel, Separator } = Se
 
 ## Form submission
 
+Inside a form, place `Select` directly under `Field.Root`, not inside `Field.Control`. `Select` draws
+its own trigger and registers with the field itself, so `<Field.Control render={<Select />} />`
+renders a second frame around it.
+
+```tsx
+<Field.Root name="country">
+  <Field.Label>Country</Field.Label>
+  <Select items={["Japan", "United States"]} placeholder="Select a country" />
+</Field.Root>
+```
+
 Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary —
 see [Form](./form.md). They matter for **native** submission: a plain `<form>`, `new FormData(form)`,
 or a server action.
diff --git a/docs/patterns/form-modal.md b/docs/patterns/form-modal.md
index 4b2e471fb..e436d6e39 100644
--- a/docs/patterns/form-modal.md
+++ b/docs/patterns/form-modal.md
@@ -147,7 +147,9 @@ placeholder.
   render_ — a submit gate, a dependent placeholder, a live character count. That state is
   load-bearing, not mirrored; see `form/composer`.
 - **`Field.Control` is already a styled input.** Write `<Field.Control />`, not
-  `<Field.Control render={<Input />} />`.
+  `<Field.Control render={<Input />} />`. Every other control — `Select`, `Combobox`,
+  `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker` — goes directly under
+  `Field.Root`. Passing one to `Field.Control`'s `render` draws a second frame around it.
 - **Object items need `itemToStringValue`.** Items shaped `{ value, label }` submit `value`
   automatically; any other object submits as a JSON string unless you supply it.
 - **Server errors go through `Form`'s `errors` prop**, keyed by field `name` — not a toast or a
@@ -165,4 +167,5 @@ placeholder.
 - Registering the create path as a separate top-level route — that unmounts the parent list
 - Reaching for React Hook Form on a form this size — `onFormSubmit` already covers it
 - Holding a `Select`/`Combobox` value in `useState` just to submit it — `Field.Root` already does
+- Wrapping a `Select`/`Combobox` in `Field.Control` (`render={<Select />}`) — a double frame
 - Surfacing API validation failures in a toast or banner instead of routing them via `errors`
diff --git a/packages/core/src/components/field/field.test.tsx b/packages/core/src/components/field/field.test.tsx
index e3ce5aaca..ce42e2215 100644
--- a/packages/core/src/components/field/field.test.tsx
+++ b/packages/core/src/components/field/field.test.tsx
@@ -2,6 +2,8 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { renderRHFForm } from "../../../tests/rhf-test-utils";
+import { Checkbox } from "../checkbox";
+import { Select } from "../select";
 import { Field } from "./field";
 
 afterEach(() => {
@@ -202,4 +204,50 @@ describe("Field", () => {
       expect(screen.getByText("Something went wrong")).toBeDefined();
     });
   });
+
+  describe("render misuse warning", () => {
+    it("warns when a self-wired control is passed to render", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      render(
+        <Field.Root name="country">
+          <Field.Control render={<Select items={["Japan"]} />} />
+        </Field.Root>,
+      );
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0][0]).toContain("render={<Select />}");
+      expect(warn.mock.calls[0][0]).toContain("directly under <Field.Root>");
+      warn.mockRestore();
+    });
+
+    it("names the compound member", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      render(
+        <Field.Root name="country">
+          <Field.Control render={<Select.Async fetcher={async () => []} />} />
+        </Field.Root>,
+      );
+      expect(warn.mock.calls[0][0]).toContain("render={<Select.Async />}");
+      warn.mockRestore();
+    });
+
+    it("warns once across re-renders", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const { rerender } = render(<Field.Control render={<Checkbox />} />);
+      rerender(<Field.Control render={<Checkbox />} />);
+      expect(warn).toHaveBeenCalledTimes(1);
+      warn.mockRestore();
+    });
+
+    it("stays silent for a plain control or a native element", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      render(
+        <Field.Root name="bio">
+          <Field.Control />
+          <Field.Control render={<textarea />} />
+        </Field.Root>,
+      );
+      expect(warn).not.toHaveBeenCalled();
+      warn.mockRestore();
+    });
+  });
 });
diff --git a/packages/core/src/components/field/field.tsx b/packages/core/src/components/field/field.tsx
index 1f7c29a5e..7a9187892 100644
--- a/packages/core/src/components/field/field.tsx
+++ b/packages/core/src/components/field/field.tsx
@@ -1,8 +1,15 @@
 import * as React from "react";
 import { Field as BaseField } from "@base-ui/react/field";
 
+import { useOnceWarnings } from "@/hooks/use-once-warnings";
 import { cn } from "@/lib/utils";
 import { inputBaseClasses } from "@/lib/input-classes";
+import { Autocomplete } from "../autocomplete";
+import { Checkbox } from "../checkbox";
+import { Combobox } from "../combobox";
+import { DateField, DatePicker, DateRangePicker } from "../date-field";
+import { Select } from "../select";
+import { Textarea } from "../textarea";
 
 // Only the props relevant to the Field abstraction are picked from BaseField.Root.
 // Base UI-internal props (e.g. actionsRef) are intentionally excluded
@@ -127,14 +134,44 @@ function Label({ className, ...props }: React.ComponentProps<typeof BaseField.La
 }
 Label.displayName = "Field.Label";
 
+// Controls that draw their own frame and connect to `Field.Root` themselves.
+// Passed to `Field.Control`'s `render`, they get a second frame plus `<input>`
+// props they don't take (platform-planning#1977).
+const selfWiredControls = new Map<unknown, string>([
+  [Select, "Select"],
+  [Select.Async, "Select.Async"],
+  [Combobox, "Combobox"],
+  [Combobox.Async, "Combobox.Async"],
+  [Autocomplete, "Autocomplete"],
+  [Autocomplete.Async, "Autocomplete.Async"],
+  [Checkbox, "Checkbox"],
+  [Textarea, "Textarea"],
+  [DateField, "DateField"],
+  [DatePicker, "DatePicker"],
+  [DateRangePicker, "DateRangePicker"],
+]);
+
+function renderMisuseWarnings(render: unknown): string[] {
+  if (!React.isValidElement(render)) return [];
+  const name = selfWiredControls.get(render.type);
+  if (!name) return [];
+  return [
+    `Field.Control: \`render={<${name} />}\` draws a second frame around ${name}. ${name} connects to Field.Root by itself — place it directly under <Field.Root> instead of inside Field.Control.`,
+  ];
+}
+
 /**
- * A styled input control for the field.
+ * A styled text input for the field.
  *
- * Can be omitted when using another Base UI-backed AppShell input component
- * (e.g. Select, Combobox, Autocomplete) as a sibling — those components
- * register themselves with the Field context automatically.
+ * Use it for plain text-like inputs, or pass a native element to `render`
+ * (e.g. `render={<textarea />}`). Every other AppShell control — `Select`,
+ * `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`,
+ * `DatePicker`, `DateRangePicker` — goes directly under `Field.Root` instead:
+ * it draws its own frame and registers with the Field context itself.
+ * Passing one to `render` draws a second frame and logs a warning.
  */
 function Control({ className, ...props }: React.ComponentProps<typeof BaseField.Control>) {
+  useOnceWarnings(renderMisuseWarnings(props.render));
   return (
     <BaseField.Control
       data-slot="field-control"

From 21e773d6e01c4d0e932c10f7c390ebadc549c068 Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Wed, 21 Oct 2026 12:03:10 +1100
Subject: [PATCH 3/7] docs(field): carve out Input and note the warning logs in
 all builds

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/field-control-render-warning.md   |  2 +-
 docs-manifest.json                           |  6 +++---
 docs-src/components/form.docs.outline.md     | 22 +++++++++++---------
 docs/components/form.md                      | 22 +++++++++++---------
 packages/core/src/components/field/field.tsx | 11 +++++-----
 5 files changed, 34 insertions(+), 29 deletions(-)

diff --git a/.changeset/field-control-render-warning.md b/.changeset/field-control-render-warning.md
index 465a9d07d..e9104146a 100644
--- a/.changeset/field-control-render-warning.md
+++ b/.changeset/field-control-render-warning.md
@@ -2,4 +2,4 @@
 "@tailor-platform/app-shell": patch
 ---
 
-`Field.Control` now logs a console warning when it is given an AppShell control that draws its own frame through `render`, such as `<Field.Control render={<Select />} />`. That composition renders a double border. `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, and `DateRangePicker` go directly under `Field.Root` instead. The Form, Select, and form-modal docs now say which controls go where.
+`Field.Control` now logs a console warning when it is given an AppShell control that draws its own frame through `render`, such as `<Field.Control render={<Select />} />`. That composition renders a double border. The warning logs in every build, not only in development, because it only fires for UI that is already broken. `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, and `DateRangePicker` go directly under `Field.Root` instead. The Form, Select, and form-modal docs now say which controls go where.
diff --git a/docs-manifest.json b/docs-manifest.json
index 03272dfac..9b0780d06 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -699,9 +699,9 @@
       "symbols": ["Form", "FormProps"],
       "hashes": {
         "typeSurface": "7b374d45d53d4535",
-        "outline": "a2cfe48049a3e5ea",
+        "outline": "7fefd291a00de910",
         "snapshot": "88a0c82baaaa2a08",
-        "outputMd": "d6ec66ffc180b303",
+        "outputMd": "e4a66f7b1ee4aa98",
         "examples": null
       }
     },
@@ -1759,7 +1759,7 @@
     "packages/core/skills/app-shell-patterns/references/components/dialog.md": "ec6a0ac098d1d87a",
     "packages/core/skills/app-shell-patterns/references/components/document-progress-card.md": "d0fb940f685f8869",
     "packages/core/skills/app-shell-patterns/references/components/filter-rail.md": "c6a48c4d8e8b0078",
-    "packages/core/skills/app-shell-patterns/references/components/form.md": "d6ec66ffc180b303",
+    "packages/core/skills/app-shell-patterns/references/components/form.md": "e4a66f7b1ee4aa98",
     "packages/core/skills/app-shell-patterns/references/components/global-header-layout.md": "dd2b0da3702cf8d9",
     "packages/core/skills/app-shell-patterns/references/components/grid.md": "9051eb53dde4179f",
     "packages/core/skills/app-shell-patterns/references/components/input.md": "a3a6c9679af99d37",
diff --git a/docs-src/components/form.docs.outline.md b/docs-src/components/form.docs.outline.md
index 1bef5f943..7e6f81d83 100644
--- a/docs-src/components/form.docs.outline.md
+++ b/docs-src/components/form.docs.outline.md
@@ -102,14 +102,14 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Sub-components
 
-| Sub-component       | Description                                                                            |
-| ------------------- | -------------------------------------------------------------------------------------- |
-| `Field.Root`        | Context boundary for a single field. Manages validation state.                         |
-| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                     |
-| `Field.Control`     | Styled text `<input>`. Other AppShell controls go directly under `Field.Root` instead. |
-| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                  |
-| `Field.Error`       | Validation error message. Use `match` to target specific validity states.              |
-| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.      |
+| Sub-component       | Description                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `Field.Root`        | Context boundary for a single field. Manages validation state.                                                         |
+| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                                                     |
+| `Field.Control`     | Styled text `<input>`. `Select`, `Combobox`, and the other self-wired controls go directly under `Field.Root` instead. |
+| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                                                  |
+| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                                              |
+| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.                                      |
 
 ### Field.Root Props
 
@@ -136,7 +136,7 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Using Another AppShell Component as the Control
 
-`Field.Control` is a text input. It is the control for plain text-like fields, and you can pass it a native element such as `render={<textarea />}`. Every other AppShell control goes **directly under `Field.Root`**, as a sibling of `Field.Label`. The control registers itself with the `Field` context, so it gets label association, `aria-describedby`, `disabled`, and validation state without `Field.Control`.
+`Field.Control` is a text input. It is the control for plain text-like fields, and you can pass it a native element such as `render={<textarea />}`. The controls in the last row of the table below go **directly under `Field.Root`**, as a sibling of `Field.Label`. Each one registers itself with the `Field` context, so it gets label association, `aria-describedby`, `disabled`, and validation state without `Field.Control`.
 
 | Control                                                                                                                         | Where it goes                                     |
 | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
@@ -144,7 +144,9 @@ A compound component that groups all parts of a form field and manages its valid
 | Native element (`<textarea>`, `<input type="…">`)                                                                               | `<Field.Control render={<textarea />} />`         |
 | `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, `DateRangePicker` (and their `.Async`) | Directly under `Field.Root` — not `Field.Control` |
 
-Do not pass these controls to `Field.Control`'s `render` prop. They draw their own frame, so `<Field.Control render={<Select />} />` renders a second border around the select. `Field.Control` also passes them `<input>` props they don't take. `Field.Control` logs a console warning when it detects this.
+`Input` is the exception. It is a plain `<input>` that does not connect to `Field.Root`, so inside a field use `<Field.Control />` in its place.
+
+Do not pass the self-wired controls to `Field.Control`'s `render` prop. They draw their own frame, so `<Field.Control render={<Select />} />` renders a second border around the select. `Field.Control` also passes them `<input>` props they don't take. `Field.Control` logs a console warning when it is given one of these controls directly as an element. A wrapper component or the function form of `render` is not detected.
 
 ```tsx
 const [country, setCountry] = React.useState<string | null>(null);
diff --git a/docs/components/form.md b/docs/components/form.md
index 5ac472ccb..8825ce9f4 100644
--- a/docs/components/form.md
+++ b/docs/components/form.md
@@ -100,14 +100,14 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Sub-components
 
-| Sub-component       | Description                                                                            |
-| ------------------- | -------------------------------------------------------------------------------------- |
-| `Field.Root`        | Context boundary for a single field. Manages validation state.                         |
-| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                     |
-| `Field.Control`     | Styled text `<input>`. Other AppShell controls go directly under `Field.Root` instead. |
-| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                  |
-| `Field.Error`       | Validation error message. Use `match` to target specific validity states.              |
-| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.      |
+| Sub-component       | Description                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `Field.Root`        | Context boundary for a single field. Manages validation state.                                                         |
+| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                                                     |
+| `Field.Control`     | Styled text `<input>`. `Select`, `Combobox`, and the other self-wired controls go directly under `Field.Root` instead. |
+| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                                                  |
+| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                                              |
+| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.                                      |
 
 ### Field.Root Props
 
@@ -134,7 +134,7 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Using Another AppShell Component as the Control
 
-`Field.Control` is a text input. It is the control for plain text-like fields, and you can pass it a native element such as `render={<textarea />}`. Every other AppShell control goes **directly under `Field.Root`**, as a sibling of `Field.Label`. The control registers itself with the `Field` context, so it gets label association, `aria-describedby`, `disabled`, and validation state without `Field.Control`.
+`Field.Control` is a text input. It is the control for plain text-like fields, and you can pass it a native element such as `render={<textarea />}`. The controls in the last row of the table below go **directly under `Field.Root`**, as a sibling of `Field.Label`. Each one registers itself with the `Field` context, so it gets label association, `aria-describedby`, `disabled`, and validation state without `Field.Control`.
 
 | Control                                                                                                                         | Where it goes                                     |
 | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
@@ -142,7 +142,9 @@ A compound component that groups all parts of a form field and manages its valid
 | Native element (`<textarea>`, `<input type="…">`)                                                                               | `<Field.Control render={<textarea />} />`         |
 | `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, `DateRangePicker` (and their `.Async`) | Directly under `Field.Root` — not `Field.Control` |
 
-Do not pass these controls to `Field.Control`'s `render` prop. They draw their own frame, so `<Field.Control render={<Select />} />` renders a second border around the select. `Field.Control` also passes them `<input>` props they don't take. `Field.Control` logs a console warning when it detects this.
+`Input` is the exception. It is a plain `<input>` that does not connect to `Field.Root`, so inside a field use `<Field.Control />` in its place.
+
+Do not pass the self-wired controls to `Field.Control`'s `render` prop. They draw their own frame, so `<Field.Control render={<Select />} />` renders a second border around the select. `Field.Control` also passes them `<input>` props they don't take. `Field.Control` logs a console warning when it is given one of these controls directly as an element. A wrapper component or the function form of `render` is not detected.
 
 ```tsx
 const [country, setCountry] = React.useState<string | null>(null);
diff --git a/packages/core/src/components/field/field.tsx b/packages/core/src/components/field/field.tsx
index 7a9187892..94d0a9faf 100644
--- a/packages/core/src/components/field/field.tsx
+++ b/packages/core/src/components/field/field.tsx
@@ -164,11 +164,12 @@ function renderMisuseWarnings(render: unknown): string[] {
  * A styled text input for the field.
  *
  * Use it for plain text-like inputs, or pass a native element to `render`
- * (e.g. `render={<textarea />}`). Every other AppShell control — `Select`,
- * `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`,
- * `DatePicker`, `DateRangePicker` — goes directly under `Field.Root` instead:
- * it draws its own frame and registers with the Field context itself.
- * Passing one to `render` draws a second frame and logs a warning.
+ * (e.g. `render={<textarea />}`). `Select`, `Combobox`, `Autocomplete`,
+ * `Checkbox`, `Textarea`, `DateField`, `DatePicker` and `DateRangePicker` go
+ * directly under `Field.Root` instead: each draws its own frame and registers
+ * with the Field context itself. Passing one to `render` draws a second frame
+ * and logs a warning. `Input` does not connect to `Field.Root` — use
+ * `Field.Control` in its place inside a field.
  */
 function Control({ className, ...props }: React.ComponentProps<typeof BaseField.Control>) {
   useOnceWarnings(renderMisuseWarnings(props.render));

From c064f0abdf1e221ec0e277b4b5296ab288150e53 Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Wed, 21 Oct 2026 13:35:30 +1100
Subject: [PATCH 4/7] docs(select): trim the Field.Control note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs-manifest.json                         | 6 +++---
 docs-src/components/select.docs.outline.md | 3 +--
 docs/components/select.md                  | 3 +--
 3 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs-manifest.json b/docs-manifest.json
index 9b0780d06..8bf885e1a 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -1209,9 +1209,9 @@
       "symbols": ["Select", "SelectAsyncFetcher"],
       "hashes": {
         "typeSurface": "429710973dfa912b",
-        "outline": "3eba8d13da1df95c",
+        "outline": "a8b7834a8817e0d5",
         "snapshot": "68fd61885280b114",
-        "outputMd": "a55198c8cc711bd8",
+        "outputMd": "b3dd3b9a58a9d290",
         "examples": "1ce89cec30045466"
       }
     },
@@ -1766,7 +1766,7 @@
     "packages/core/skills/app-shell-patterns/references/components/layout.md": "66696139a46fabb0",
     "packages/core/skills/app-shell-patterns/references/components/menu.md": "ceb4a05822538d20",
     "packages/core/skills/app-shell-patterns/references/components/metric-card.md": "5a1c557768c6590f",
-    "packages/core/skills/app-shell-patterns/references/components/select.md": "a55198c8cc711bd8",
+    "packages/core/skills/app-shell-patterns/references/components/select.md": "b3dd3b9a58a9d290",
     "packages/core/skills/app-shell-patterns/references/components/sheet.md": "1f81ebd562c50371",
     "packages/core/skills/app-shell-patterns/references/components/sidebar-group.md": "a36192df64f16adc",
     "packages/core/skills/app-shell-patterns/references/components/sidebar-item.md": "9236c03e53aa79f2",
diff --git a/docs-src/components/select.docs.outline.md b/docs-src/components/select.docs.outline.md
index 9c499555a..6e90e8fb1 100644
--- a/docs-src/components/select.docs.outline.md
+++ b/docs-src/components/select.docs.outline.md
@@ -162,8 +162,7 @@ const { Root, Trigger, Value, Content, Item, Group, GroupLabel, Separator } = Se
 ## Form submission
 
 Inside a form, place `Select` directly under `Field.Root`, not inside `Field.Control`. `Select` draws
-its own trigger and registers with the field itself, so `<Field.Control render={<Select />} />`
-renders a second frame around it.
+its own trigger and registers with the field itself.
 
 ```tsx
 <Field.Root name="country">
diff --git a/docs/components/select.md b/docs/components/select.md
index 9d82b7562..df4e7e7cd 100644
--- a/docs/components/select.md
+++ b/docs/components/select.md
@@ -172,8 +172,7 @@ const { Root, Trigger, Value, Content, Item, Group, GroupLabel, Separator } = Se
 ## Form submission
 
 Inside a form, place `Select` directly under `Field.Root`, not inside `Field.Control`. `Select` draws
-its own trigger and registers with the field itself, so `<Field.Control render={<Select />} />`
-renders a second frame around it.
+its own trigger and registers with the field itself.
 
 ```tsx
 <Field.Root name="country">

From b821991d1b2cea86c7fcb2edd2373b0c7dc8783d Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Wed, 21 Oct 2026 13:40:15 +1100
Subject: [PATCH 5/7] refactor(field): register self-wired controls next to
 their definitions

Replaces the central list in field.tsx, so a new form control picks up the
Field.Control warning by copying its neighbours. Adds the step to the
composite-field-controls review reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .agents/references/README.md                  |  2 +-
 .../references/composite-field-controls.md    |  4 +++
 .../autocomplete/autocomplete-standalone.tsx  |  4 +++
 .../core/src/components/checkbox/checkbox.tsx |  3 +++
 .../combobox/combobox-standalone.tsx          |  4 +++
 .../src/components/date-field/date-field.tsx  |  4 +++
 .../date-field/date-range-picker.tsx          |  3 +++
 packages/core/src/components/field/field.tsx  | 26 ++-----------------
 .../components/select/select-standalone.tsx   |  4 +++
 .../core/src/components/textarea/textarea.tsx |  3 +++
 packages/core/src/lib/self-wired-controls.ts  | 15 +++++++++++
 11 files changed, 47 insertions(+), 25 deletions(-)
 create mode 100644 packages/core/src/lib/self-wired-controls.ts

diff --git a/.agents/references/README.md b/.agents/references/README.md
index 790336f6d..a8bc7f2ba 100644
--- a/.agents/references/README.md
+++ b/.agents/references/README.md
@@ -10,7 +10,7 @@ Use these references from both implementation-time and review-time skills. Treat
 - [react-use-effect.md](react-use-effect.md) — state ownership, `useEffect`, async lifecycle, subscriptions, memoization
 - [accessibility.md](accessibility.md) — interactive semantics, keyboard support, focus, labels, announced state
 - [low-level-apis.md](low-level-apis.md) — timers, measurement, observers, imperative DOM, browser coordination
-- [composite-field-controls.md](composite-field-controls.md) — field semantics, composite inputs, `Field` / `Form` bridging, proxy or hidden inputs, validation wiring, and alignment with nearby Base UI-backed control contracts
+- [composite-field-controls.md](composite-field-controls.md) — field semantics, composite inputs, `Field` / `Form` bridging, proxy or hidden inputs, validation wiring, self-wired registration for `Field.Control`, and alignment with nearby Base UI-backed control contracts
 
 ## Inclusion Criteria
 
diff --git a/.agents/references/composite-field-controls.md b/.agents/references/composite-field-controls.md
index e39f230df..33dec0112 100644
--- a/.agents/references/composite-field-controls.md
+++ b/.agents/references/composite-field-controls.md
@@ -37,6 +37,10 @@ Review for consistency around:
 
 Be skeptical when a composite field control invents a parallel API unless the underlying semantics truly differ.
 
+### Register as self-wired
+
+Every control that draws its own frame and connects to `Field.Root` by itself — composite or a thin Base UI wrapper — calls `markSelfWired(Component, "Name")` from `@/lib/self-wired-controls` next to its definition, including compound members such as `.Async`. `Field.Control` uses this registry to warn when the control is passed to its `render` prop, which draws a double frame. A control missing from the registry fails silently: no warning, the same double frame.
+
 ### One semantic value across all input paths
 
 Check whether these paths still converge on the same meaning when they exist:
diff --git a/packages/core/src/components/autocomplete/autocomplete-standalone.tsx b/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
index c7c1d8551..8c26deae8 100644
--- a/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
+++ b/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
@@ -20,6 +20,7 @@ import { defaultMapItem, isGroupedItems } from "../dropdown-items";
 import type { MappedItem, ItemGroup, ExtractItem } from "../dropdown-items";
 import { AsyncErrorState, resolveAsyncContent } from "../internals/async-error-state";
 import type { AsyncFetcher } from "@/hooks/use-async-items";
+import { markSelfWired } from "@/lib/self-wired-controls";
 
 /** Fetcher type for `Autocomplete.Async`. */
 export type AutocompleteAsyncFetcher<T> = AsyncFetcher<T>;
@@ -331,4 +332,7 @@ const Autocomplete: AutocompleteComponent = Object.assign(AutocompleteStandalone
   useFilter,
 });
 
+markSelfWired(Autocomplete, "Autocomplete");
+markSelfWired(Autocomplete.Async, "Autocomplete.Async");
+
 export { Autocomplete };
diff --git a/packages/core/src/components/checkbox/checkbox.tsx b/packages/core/src/components/checkbox/checkbox.tsx
index b3574ff31..f2d3ead01 100644
--- a/packages/core/src/components/checkbox/checkbox.tsx
+++ b/packages/core/src/components/checkbox/checkbox.tsx
@@ -3,6 +3,7 @@ import { Checkbox as BaseCheckbox } from "@base-ui/react/checkbox";
 import { Check, Minus } from "lucide-react";
 
 import { cn } from "@/lib/utils";
+import { markSelfWired } from "@/lib/self-wired-controls";
 
 // `children` and `render` are intentionally excluded: the component owns the
 // box + indicator structure so the visual stays stable, and consumers get a
@@ -133,4 +134,6 @@ function Checkbox({ className, label, ...props }: CheckboxProps) {
   );
 }
 
+markSelfWired(Checkbox, "Checkbox");
+
 export { Checkbox, type CheckboxProps };
diff --git a/packages/core/src/components/combobox/combobox-standalone.tsx b/packages/core/src/components/combobox/combobox-standalone.tsx
index 286824fa1..9b2c18cc7 100644
--- a/packages/core/src/components/combobox/combobox-standalone.tsx
+++ b/packages/core/src/components/combobox/combobox-standalone.tsx
@@ -26,6 +26,7 @@ import { defaultMapItem, isGroupedItems } from "../dropdown-items";
 import type { MappedItem, ItemGroup, ExtractItem } from "../dropdown-items";
 import { AsyncErrorState, resolveAsyncContent } from "../internals/async-error-state";
 import type { AsyncFetcher } from "@/hooks/use-async-items";
+import { markSelfWired } from "@/lib/self-wired-controls";
 
 /** Fetcher type for `Combobox.Async`. */
 export type ComboboxAsyncFetcher<T> = AsyncFetcher<T>;
@@ -713,4 +714,7 @@ const Combobox: ComboboxComponent = Object.assign(ComboboxStandalone, {
   useCreatable,
 });
 
+markSelfWired(Combobox, "Combobox");
+markSelfWired(Combobox.Async, "Combobox.Async");
+
 export { Combobox };
diff --git a/packages/core/src/components/date-field/date-field.tsx b/packages/core/src/components/date-field/date-field.tsx
index 7eb719007..1228f3e80 100644
--- a/packages/core/src/components/date-field/date-field.tsx
+++ b/packages/core/src/components/date-field/date-field.tsx
@@ -11,6 +11,7 @@ import {
 import { toCalendarDate, today, type DateValue } from "@internationalized/date";
 import { useFieldRootContext } from "@base-ui/react/internals/field-root-context";
 import { cn } from "@/lib/utils";
+import { markSelfWired } from "@/lib/self-wired-controls";
 import { useResolvedLocale, useTimeZone } from "@/contexts/appshell-context";
 import {
   useDateFieldState,
@@ -423,5 +424,8 @@ const DatePicker = forwardRef(function DatePicker<T extends DateValue = DateValu
   props: DatePickerProps<T> & { ref?: Ref<HTMLInputElement> },
 ) => ReactElement;
 
+markSelfWired(DateField, "DateField");
+markSelfWired(DatePicker, "DatePicker");
+
 export { DateField, DatePicker };
 export type { DateControlProps };
diff --git a/packages/core/src/components/date-field/date-range-picker.tsx b/packages/core/src/components/date-field/date-range-picker.tsx
index 0334240dc..375d62d33 100644
--- a/packages/core/src/components/date-field/date-range-picker.tsx
+++ b/packages/core/src/components/date-field/date-range-picker.tsx
@@ -11,6 +11,7 @@ import {
 } from "react";
 import { toCalendarDate, today, type DateValue } from "@internationalized/date";
 import { cn } from "@/lib/utils";
+import { markSelfWired } from "@/lib/self-wired-controls";
 import { useFieldRootContext } from "@base-ui/react/internals/field-root-context";
 import { useResolvedLocale, useTimeZone } from "@/contexts/appshell-context";
 import {
@@ -437,4 +438,6 @@ const DateRangePicker = forwardRef(function DateRangePicker<T extends DateValue
   props: DateRangePickerProps<T> & { ref?: Ref<HTMLInputElement> },
 ) => ReactElement;
 
+markSelfWired(DateRangePicker, "DateRangePicker");
+
 export { DateRangePicker };
diff --git a/packages/core/src/components/field/field.tsx b/packages/core/src/components/field/field.tsx
index 94d0a9faf..fe5cd86b8 100644
--- a/packages/core/src/components/field/field.tsx
+++ b/packages/core/src/components/field/field.tsx
@@ -2,14 +2,9 @@ import * as React from "react";
 import { Field as BaseField } from "@base-ui/react/field";
 
 import { useOnceWarnings } from "@/hooks/use-once-warnings";
+import { getSelfWiredName } from "@/lib/self-wired-controls";
 import { cn } from "@/lib/utils";
 import { inputBaseClasses } from "@/lib/input-classes";
-import { Autocomplete } from "../autocomplete";
-import { Checkbox } from "../checkbox";
-import { Combobox } from "../combobox";
-import { DateField, DatePicker, DateRangePicker } from "../date-field";
-import { Select } from "../select";
-import { Textarea } from "../textarea";
 
 // Only the props relevant to the Field abstraction are picked from BaseField.Root.
 // Base UI-internal props (e.g. actionsRef) are intentionally excluded
@@ -134,26 +129,9 @@ function Label({ className, ...props }: React.ComponentProps<typeof BaseField.La
 }
 Label.displayName = "Field.Label";
 
-// Controls that draw their own frame and connect to `Field.Root` themselves.
-// Passed to `Field.Control`'s `render`, they get a second frame plus `<input>`
-// props they don't take (platform-planning#1977).
-const selfWiredControls = new Map<unknown, string>([
-  [Select, "Select"],
-  [Select.Async, "Select.Async"],
-  [Combobox, "Combobox"],
-  [Combobox.Async, "Combobox.Async"],
-  [Autocomplete, "Autocomplete"],
-  [Autocomplete.Async, "Autocomplete.Async"],
-  [Checkbox, "Checkbox"],
-  [Textarea, "Textarea"],
-  [DateField, "DateField"],
-  [DatePicker, "DatePicker"],
-  [DateRangePicker, "DateRangePicker"],
-]);
-
 function renderMisuseWarnings(render: unknown): string[] {
   if (!React.isValidElement(render)) return [];
-  const name = selfWiredControls.get(render.type);
+  const name = getSelfWiredName(render.type);
   if (!name) return [];
   return [
     `Field.Control: \`render={<${name} />}\` draws a second frame around ${name}. ${name} connects to Field.Root by itself — place it directly under <Field.Root> instead of inside Field.Control.`,
diff --git a/packages/core/src/components/select/select-standalone.tsx b/packages/core/src/components/select/select-standalone.tsx
index 33bc428ed..f93edb9bb 100644
--- a/packages/core/src/components/select/select-standalone.tsx
+++ b/packages/core/src/components/select/select-standalone.tsx
@@ -13,6 +13,7 @@ import {
 import { defaultMapItem, isGroupedItems } from "../dropdown-items";
 import type { MappedItem, ItemGroup, ExtractItem } from "../dropdown-items";
 import { AsyncErrorState, resolveAsyncContent } from "../internals/async-error-state";
+import { markSelfWired } from "@/lib/self-wired-controls";
 
 /**
  * Fetcher type for `Select.Async`.
@@ -601,4 +602,7 @@ const Select: SelectComponent = Object.assign(SelectStandalone, {
   useAsync,
 });
 
+markSelfWired(Select, "Select");
+markSelfWired(Select.Async, "Select.Async");
+
 export { Select, useAsync };
diff --git a/packages/core/src/components/textarea/textarea.tsx b/packages/core/src/components/textarea/textarea.tsx
index 914cc56f4..57a414376 100644
--- a/packages/core/src/components/textarea/textarea.tsx
+++ b/packages/core/src/components/textarea/textarea.tsx
@@ -2,6 +2,7 @@ import * as React from "react";
 import { Field as BaseField } from "@base-ui/react/field";
 
 import { cn } from "@/lib/utils";
+import { markSelfWired } from "@/lib/self-wired-controls";
 import { textareaBaseClasses } from "@/lib/input-classes";
 
 // `render` is intentionally excluded: the component owns the `<textarea>` tag
@@ -108,4 +109,6 @@ function Textarea({ className, ...props }: TextareaProps) {
   );
 }
 
+markSelfWired(Textarea, "Textarea");
+
 export { Textarea, type TextareaProps };
diff --git a/packages/core/src/lib/self-wired-controls.ts b/packages/core/src/lib/self-wired-controls.ts
new file mode 100644
index 000000000..1e8f2a39f
--- /dev/null
+++ b/packages/core/src/lib/self-wired-controls.ts
@@ -0,0 +1,15 @@
+// Registry of controls that draw their own frame and connect to `Field.Root`
+// themselves. Each control registers next to its own definition, so a new
+// form control copies the call from its neighbours. `Field.Control` reads it to
+// warn when one is passed to `render` (platform-planning#1977).
+const selfWired = new WeakMap<object, string>();
+
+export function markSelfWired(component: object, name: string) {
+  selfWired.set(component, name);
+}
+
+export function getSelfWiredName(type: unknown): string | undefined {
+  return typeof type === "function" || (typeof type === "object" && type !== null)
+    ? selfWired.get(type)
+    : undefined;
+}

From b2f7b30576967b4eb9e481d6690326b8f02cf3a8 Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Thu, 22 Oct 2026 16:20:33 +1100
Subject: [PATCH 6/7] perf(field): make self-wired registrations tree-shakeable

markSelfWired now returns the component and wraps each definition with a
PURE annotation, so a bundle that drops a control drops its registration
too. A bare top-level call kept every registered control alive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs-manifest.json                            |  4 +-
 .../autocomplete/autocomplete-standalone.tsx  | 18 ++++----
 .../core/src/components/checkbox/checkbox.tsx | 10 +++--
 .../combobox/combobox-standalone.tsx          | 20 ++++-----
 .../src/components/date-field/date-field.tsx  | 32 +++++++-------
 .../date-field/date-range-picker.tsx          |  4 +-
 .../components/select/select-standalone.tsx   | 44 +++++++++----------
 .../core/src/components/textarea/textarea.tsx |  9 ++--
 packages/core/src/lib/self-wired-controls.ts  | 10 ++++-
 9 files changed, 80 insertions(+), 71 deletions(-)

diff --git a/docs-manifest.json b/docs-manifest.json
index 8bf885e1a..4959bcd9b 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -257,7 +257,7 @@
       "claims": [],
       "symbols": ["Checkbox", "CheckboxProps"],
       "hashes": {
-        "typeSurface": "3886bf7012f24283",
+        "typeSurface": "74553f38c0752227",
         "outline": "916645fe8e5baf10",
         "snapshot": "2d057b30b9401e12",
         "outputMd": "14f7ba23f441df38",
@@ -1412,7 +1412,7 @@
       "claims": [],
       "symbols": ["Textarea", "TextareaProps"],
       "hashes": {
-        "typeSurface": "3d9225f7356a29b2",
+        "typeSurface": "d78798cfa7c90a76",
         "outline": "40952524e46c333e",
         "snapshot": "c8500808c03baa29",
         "outputMd": "c940bc01cd573334",
diff --git a/packages/core/src/components/autocomplete/autocomplete-standalone.tsx b/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
index 8c26deae8..c86a9618f 100644
--- a/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
+++ b/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
@@ -325,14 +325,14 @@ type AutocompleteComponent = typeof AutocompleteStandalone & {
   useFilter: typeof useFilter;
 };
 
-const Autocomplete: AutocompleteComponent = Object.assign(AutocompleteStandalone, {
-  Async: AutocompleteAsyncStandalone,
-  Parts: AutocompleteParts,
-  useAsync,
-  useFilter,
-});
-
-markSelfWired(Autocomplete, "Autocomplete");
-markSelfWired(Autocomplete.Async, "Autocomplete.Async");
+const Autocomplete: AutocompleteComponent = /* @__PURE__ */ markSelfWired(
+  Object.assign(AutocompleteStandalone, {
+    Async: /* @__PURE__ */ markSelfWired(AutocompleteAsyncStandalone, "Autocomplete.Async"),
+    Parts: AutocompleteParts,
+    useAsync,
+    useFilter,
+  }),
+  "Autocomplete",
+);
 
 export { Autocomplete };
diff --git a/packages/core/src/components/checkbox/checkbox.tsx b/packages/core/src/components/checkbox/checkbox.tsx
index f2d3ead01..e3563f9d3 100644
--- a/packages/core/src/components/checkbox/checkbox.tsx
+++ b/packages/core/src/components/checkbox/checkbox.tsx
@@ -88,7 +88,11 @@ const checkboxBoxClasses = cn(
  * />
  * ```
  */
-function Checkbox({ className, label, ...props }: CheckboxProps) {
+const Checkbox = /* @__PURE__ */ markSelfWired(function Checkbox({
+  className,
+  label,
+  ...props
+}: CheckboxProps) {
   const box = (
     <BaseCheckbox.Root
       data-slot="checkbox"
@@ -132,8 +136,6 @@ function Checkbox({ className, label, ...props }: CheckboxProps) {
       {label}
     </label>
   );
-}
-
-markSelfWired(Checkbox, "Checkbox");
+}, "Checkbox");
 
 export { Checkbox, type CheckboxProps };
diff --git a/packages/core/src/components/combobox/combobox-standalone.tsx b/packages/core/src/components/combobox/combobox-standalone.tsx
index 9b2c18cc7..bfc0a75c5 100644
--- a/packages/core/src/components/combobox/combobox-standalone.tsx
+++ b/packages/core/src/components/combobox/combobox-standalone.tsx
@@ -706,15 +706,15 @@ type ComboboxComponent = typeof ComboboxStandalone & {
   useCreatable: typeof useCreatable;
 };
 
-const Combobox: ComboboxComponent = Object.assign(ComboboxStandalone, {
-  Async: ComboboxAsyncStandalone,
-  Parts: ComboboxParts,
-  useAsync,
-  useFilter,
-  useCreatable,
-});
-
-markSelfWired(Combobox, "Combobox");
-markSelfWired(Combobox.Async, "Combobox.Async");
+const Combobox: ComboboxComponent = /* @__PURE__ */ markSelfWired(
+  Object.assign(ComboboxStandalone, {
+    Async: /* @__PURE__ */ markSelfWired(ComboboxAsyncStandalone, "Combobox.Async"),
+    Parts: ComboboxParts,
+    useAsync,
+    useFilter,
+    useCreatable,
+  }),
+  "Combobox",
+);
 
 export { Combobox };
diff --git a/packages/core/src/components/date-field/date-field.tsx b/packages/core/src/components/date-field/date-field.tsx
index 1228f3e80..668b90eba 100644
--- a/packages/core/src/components/date-field/date-field.tsx
+++ b/packages/core/src/components/date-field/date-field.tsx
@@ -79,13 +79,7 @@ export type DatePickerProps<T extends DateValue = DateValue> = DateControlProps<
   timeZone?: string;
 };
 
-/**
- * A segmented date/time input field with no popover.
- *
- * Compose with `Field.Root` for label / description / error presentation, or
- * provide standalone ARIA wiring yourself.
- */
-const DateField = forwardRef(function DateField<T extends DateValue = DateValue>(
+const DateFieldImpl = forwardRef(function DateField<T extends DateValue = DateValue>(
   {
     id,
     className,
@@ -207,13 +201,7 @@ const DateField = forwardRef(function DateField<T extends DateValue = DateValue>
   props: DateFieldProps<T> & { ref?: Ref<HTMLInputElement> },
 ) => ReactElement;
 
-/**
- * A date/time input with a popover calendar.
- *
- * Compose with `Field.Root` for label / description / error presentation, or
- * provide standalone ARIA wiring yourself.
- */
-const DatePicker = forwardRef(function DatePicker<T extends DateValue = DateValue>(
+const DatePickerImpl = forwardRef(function DatePicker<T extends DateValue = DateValue>(
   {
     id,
     className,
@@ -424,8 +412,20 @@ const DatePicker = forwardRef(function DatePicker<T extends DateValue = DateValu
   props: DatePickerProps<T> & { ref?: Ref<HTMLInputElement> },
 ) => ReactElement;
 
-markSelfWired(DateField, "DateField");
-markSelfWired(DatePicker, "DatePicker");
+/**
+ * A segmented date/time input field with no popover.
+ *
+ * Compose with `Field.Root` for label / description / error presentation, or
+ * provide standalone ARIA wiring yourself.
+ */
+const DateField = /* @__PURE__ */ markSelfWired(DateFieldImpl, "DateField");
+/**
+ * A date/time input with a popover calendar.
+ *
+ * Compose with `Field.Root` for label / description / error presentation, or
+ * provide standalone ARIA wiring yourself.
+ */
+const DatePicker = /* @__PURE__ */ markSelfWired(DatePickerImpl, "DatePicker");
 
 export { DateField, DatePicker };
 export type { DateControlProps };
diff --git a/packages/core/src/components/date-field/date-range-picker.tsx b/packages/core/src/components/date-field/date-range-picker.tsx
index 375d62d33..de5fd811f 100644
--- a/packages/core/src/components/date-field/date-range-picker.tsx
+++ b/packages/core/src/components/date-field/date-range-picker.tsx
@@ -110,7 +110,7 @@ function rangesEqual(a: DateRange | null, b: DateRange | null): boolean {
   return a.start.compare(b.start as never) === 0 && a.end.compare(b.end as never) === 0;
 }
 
-const DateRangePicker = forwardRef(function DateRangePicker<T extends DateValue = DateValue>(
+const DateRangePickerImpl = forwardRef(function DateRangePicker<T extends DateValue = DateValue>(
   {
     id,
     className,
@@ -438,6 +438,6 @@ const DateRangePicker = forwardRef(function DateRangePicker<T extends DateValue
   props: DateRangePickerProps<T> & { ref?: Ref<HTMLInputElement> },
 ) => ReactElement;
 
-markSelfWired(DateRangePicker, "DateRangePicker");
+const DateRangePicker = /* @__PURE__ */ markSelfWired(DateRangePickerImpl, "DateRangePicker");
 
 export { DateRangePicker };
diff --git a/packages/core/src/components/select/select-standalone.tsx b/packages/core/src/components/select/select-standalone.tsx
index f93edb9bb..7f6a64d6d 100644
--- a/packages/core/src/components/select/select-standalone.tsx
+++ b/packages/core/src/components/select/select-standalone.tsx
@@ -582,27 +582,27 @@ type SelectComponent = typeof SelectStandalone & {
   useAsync: typeof useAsync;
 };
 
-const Select: SelectComponent = Object.assign(SelectStandalone, {
-  /**
-   * Async select that fetches items when the dropdown opens.
-   *
-   * **Limitation:** This component defaults to `modal={false}` and
-   * `alignItemWithTrigger={false}` to work around Base UI scroll-lock bugs
-   * with dynamically loaded items. As a result, it may not function correctly
-   * inside focus-trapping containers such as `Dialog` or `Sheet` — the
-   * focus trap can block interaction with the dropdown, or the portal may
-   * render outside the modal's visible area.
-   *
-   * If you need an async dropdown inside a `Dialog` or `Sheet`, prefer
-   * `Combobox.Async` which uses Popover-based positioning and does not
-   * suffer from these constraints.
-   */
-  Async: SelectAsyncStandalone,
-  Parts: SelectParts,
-  useAsync,
-});
-
-markSelfWired(Select, "Select");
-markSelfWired(Select.Async, "Select.Async");
+const Select: SelectComponent = /* @__PURE__ */ markSelfWired(
+  Object.assign(SelectStandalone, {
+    /**
+     * Async select that fetches items when the dropdown opens.
+     *
+     * **Limitation:** This component defaults to `modal={false}` and
+     * `alignItemWithTrigger={false}` to work around Base UI scroll-lock bugs
+     * with dynamically loaded items. As a result, it may not function correctly
+     * inside focus-trapping containers such as `Dialog` or `Sheet` — the
+     * focus trap can block interaction with the dropdown, or the portal may
+     * render outside the modal's visible area.
+     *
+     * If you need an async dropdown inside a `Dialog` or `Sheet`, prefer
+     * `Combobox.Async` which uses Popover-based positioning and does not
+     * suffer from these constraints.
+     */
+    Async: /* @__PURE__ */ markSelfWired(SelectAsyncStandalone, "Select.Async"),
+    Parts: SelectParts,
+    useAsync,
+  }),
+  "Select",
+);
 
 export { Select, useAsync };
diff --git a/packages/core/src/components/textarea/textarea.tsx b/packages/core/src/components/textarea/textarea.tsx
index 57a414376..da4d81d7a 100644
--- a/packages/core/src/components/textarea/textarea.tsx
+++ b/packages/core/src/components/textarea/textarea.tsx
@@ -86,7 +86,10 @@ type TextareaProps = Omit<
  * />
  * ```
  */
-function Textarea({ className, ...props }: TextareaProps) {
+const Textarea = /* @__PURE__ */ markSelfWired(function Textarea({
+  className,
+  ...props
+}: TextareaProps) {
   return (
     <BaseField.Control
       data-slot="textarea"
@@ -107,8 +110,6 @@ function Textarea({ className, ...props }: TextareaProps) {
       {...(props as React.ComponentProps<typeof BaseField.Control>)}
     />
   );
-}
-
-markSelfWired(Textarea, "Textarea");
+}, "Textarea");
 
 export { Textarea, type TextareaProps };
diff --git a/packages/core/src/lib/self-wired-controls.ts b/packages/core/src/lib/self-wired-controls.ts
index 1e8f2a39f..2eb410553 100644
--- a/packages/core/src/lib/self-wired-controls.ts
+++ b/packages/core/src/lib/self-wired-controls.ts
@@ -1,11 +1,17 @@
 // Registry of controls that draw their own frame and connect to `Field.Root`
-// themselves. Each control registers next to its own definition, so a new
+// themselves. Each control registers in its own definition, so a new
 // form control copies the call from its neighbours. `Field.Control` reads it to
 // warn when one is passed to `render` (platform-planning#1977).
 const selfWired = new WeakMap<object, string>();
 
-export function markSelfWired(component: object, name: string) {
+/**
+ * Returns `component`, so the call wraps the definition and stays removable:
+ * `const X = /* @__PURE__ *\/ markSelfWired(XImpl, "X")`. A bare top-level
+ * call would keep every control in a bundle that only imports `Field`.
+ */
+export function markSelfWired<T extends object>(component: T, name: string): T {
   selfWired.set(component, name);
+  return component;
 }
 
 export function getSelfWiredName(type: unknown): string | undefined {

From 6cfb9a106becbcf55be09059e5d20facfe83b8ae Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Fri, 23 Oct 2026 13:24:27 +1100
Subject: [PATCH 7/7] refactor(field): go back to a plain self-wired list in
 field.tsx

Reverts the per-component markSelfWired registry (b821991d, b2f7b305). The
PURE-annotated wrappers have side effects, so marking them pure risks
bundlers dropping the registration. A central list is simpler; the
composite-field-controls reference now says new controls must be added to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .agents/references/README.md                  |  2 +-
 .../references/composite-field-controls.md    |  2 +-
 docs-manifest.json                            |  4 +-
 .../autocomplete/autocomplete-standalone.tsx  | 16 +++----
 .../core/src/components/checkbox/checkbox.tsx |  9 +---
 .../combobox/combobox-standalone.tsx          | 18 ++++----
 .../src/components/date-field/date-field.tsx  | 32 +++++++-------
 .../date-field/date-range-picker.tsx          |  5 +--
 packages/core/src/components/field/field.tsx  | 26 +++++++++++-
 .../components/select/select-standalone.tsx   | 42 +++++++++----------
 .../core/src/components/textarea/textarea.tsx |  8 +---
 packages/core/src/lib/self-wired-controls.ts  | 21 ----------
 12 files changed, 79 insertions(+), 106 deletions(-)
 delete mode 100644 packages/core/src/lib/self-wired-controls.ts

diff --git a/.agents/references/README.md b/.agents/references/README.md
index a8bc7f2ba..c2fc3f134 100644
--- a/.agents/references/README.md
+++ b/.agents/references/README.md
@@ -10,7 +10,7 @@ Use these references from both implementation-time and review-time skills. Treat
 - [react-use-effect.md](react-use-effect.md) — state ownership, `useEffect`, async lifecycle, subscriptions, memoization
 - [accessibility.md](accessibility.md) — interactive semantics, keyboard support, focus, labels, announced state
 - [low-level-apis.md](low-level-apis.md) — timers, measurement, observers, imperative DOM, browser coordination
-- [composite-field-controls.md](composite-field-controls.md) — field semantics, composite inputs, `Field` / `Form` bridging, proxy or hidden inputs, validation wiring, self-wired registration for `Field.Control`, and alignment with nearby Base UI-backed control contracts
+- [composite-field-controls.md](composite-field-controls.md) — field semantics, composite inputs, `Field` / `Form` bridging, proxy or hidden inputs, validation wiring, the `Field.Control` self-wired list, and alignment with nearby Base UI-backed control contracts
 
 ## Inclusion Criteria
 
diff --git a/.agents/references/composite-field-controls.md b/.agents/references/composite-field-controls.md
index 33dec0112..ee8130248 100644
--- a/.agents/references/composite-field-controls.md
+++ b/.agents/references/composite-field-controls.md
@@ -39,7 +39,7 @@ Be skeptical when a composite field control invents a parallel API unless the un
 
 ### Register as self-wired
 
-Every control that draws its own frame and connects to `Field.Root` by itself — composite or a thin Base UI wrapper — calls `markSelfWired(Component, "Name")` from `@/lib/self-wired-controls` next to its definition, including compound members such as `.Async`. `Field.Control` uses this registry to warn when the control is passed to its `render` prop, which draws a double frame. A control missing from the registry fails silently: no warning, the same double frame.
+Every control that draws its own frame and connects to `Field.Root` by itself — composite or a thin Base UI wrapper — gets an entry in `selfWiredControls` in `components/field/field.tsx`, including compound members such as `.Async`. `Field.Control` uses that list to warn when the control is passed to its `render` prop, which draws a double frame. A control missing from the list fails silently: no warning, the same double frame.
 
 ### One semantic value across all input paths
 
diff --git a/docs-manifest.json b/docs-manifest.json
index 5657c6503..387f19560 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -257,7 +257,7 @@
       "claims": [],
       "symbols": ["Checkbox", "CheckboxProps"],
       "hashes": {
-        "typeSurface": "74553f38c0752227",
+        "typeSurface": "3886bf7012f24283",
         "outline": "916645fe8e5baf10",
         "snapshot": "8d4d6148a3df5d61",
         "outputMd": "14f7ba23f441df38",
@@ -1412,7 +1412,7 @@
       "claims": [],
       "symbols": ["Textarea", "TextareaProps"],
       "hashes": {
-        "typeSurface": "d78798cfa7c90a76",
+        "typeSurface": "3d9225f7356a29b2",
         "outline": "40952524e46c333e",
         "snapshot": "c8500808c03baa29",
         "outputMd": "c940bc01cd573334",
diff --git a/packages/core/src/components/autocomplete/autocomplete-standalone.tsx b/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
index c86a9618f..c7c1d8551 100644
--- a/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
+++ b/packages/core/src/components/autocomplete/autocomplete-standalone.tsx
@@ -20,7 +20,6 @@ import { defaultMapItem, isGroupedItems } from "../dropdown-items";
 import type { MappedItem, ItemGroup, ExtractItem } from "../dropdown-items";
 import { AsyncErrorState, resolveAsyncContent } from "../internals/async-error-state";
 import type { AsyncFetcher } from "@/hooks/use-async-items";
-import { markSelfWired } from "@/lib/self-wired-controls";
 
 /** Fetcher type for `Autocomplete.Async`. */
 export type AutocompleteAsyncFetcher<T> = AsyncFetcher<T>;
@@ -325,14 +324,11 @@ type AutocompleteComponent = typeof AutocompleteStandalone & {
   useFilter: typeof useFilter;
 };
 
-const Autocomplete: AutocompleteComponent = /* @__PURE__ */ markSelfWired(
-  Object.assign(AutocompleteStandalone, {
-    Async: /* @__PURE__ */ markSelfWired(AutocompleteAsyncStandalone, "Autocomplete.Async"),
-    Parts: AutocompleteParts,
-    useAsync,
-    useFilter,
-  }),
-  "Autocomplete",
-);
+const Autocomplete: AutocompleteComponent = Object.assign(AutocompleteStandalone, {
+  Async: AutocompleteAsyncStandalone,
+  Parts: AutocompleteParts,
+  useAsync,
+  useFilter,
+});
 
 export { Autocomplete };
diff --git a/packages/core/src/components/checkbox/checkbox.tsx b/packages/core/src/components/checkbox/checkbox.tsx
index 15992672d..63c45eae1 100644
--- a/packages/core/src/components/checkbox/checkbox.tsx
+++ b/packages/core/src/components/checkbox/checkbox.tsx
@@ -3,7 +3,6 @@ import { Checkbox as BaseCheckbox } from "@base-ui/react/checkbox";
 import { Check, Minus } from "lucide-react";
 
 import { cn } from "@/lib/utils";
-import { markSelfWired } from "@/lib/self-wired-controls";
 import { Text } from "../text";
 
 // `children` and `render` are intentionally excluded: the component owns the
@@ -89,11 +88,7 @@ const checkboxBoxClasses = cn(
  * />
  * ```
  */
-const Checkbox = /* @__PURE__ */ markSelfWired(function Checkbox({
-  className,
-  label,
-  ...props
-}: CheckboxProps) {
+function Checkbox({ className, label, ...props }: CheckboxProps) {
   const box = (
     <BaseCheckbox.Root
       data-slot="checkbox"
@@ -139,6 +134,6 @@ const Checkbox = /* @__PURE__ */ markSelfWired(function Checkbox({
       {label}
     </Text>
   );
-}, "Checkbox");
+}
 
 export { Checkbox, type CheckboxProps };
diff --git a/packages/core/src/components/combobox/combobox-standalone.tsx b/packages/core/src/components/combobox/combobox-standalone.tsx
index bfc0a75c5..286824fa1 100644
--- a/packages/core/src/components/combobox/combobox-standalone.tsx
+++ b/packages/core/src/components/combobox/combobox-standalone.tsx
@@ -26,7 +26,6 @@ import { defaultMapItem, isGroupedItems } from "../dropdown-items";
 import type { MappedItem, ItemGroup, ExtractItem } from "../dropdown-items";
 import { AsyncErrorState, resolveAsyncContent } from "../internals/async-error-state";
 import type { AsyncFetcher } from "@/hooks/use-async-items";
-import { markSelfWired } from "@/lib/self-wired-controls";
 
 /** Fetcher type for `Combobox.Async`. */
 export type ComboboxAsyncFetcher<T> = AsyncFetcher<T>;
@@ -706,15 +705,12 @@ type ComboboxComponent = typeof ComboboxStandalone & {
   useCreatable: typeof useCreatable;
 };
 
-const Combobox: ComboboxComponent = /* @__PURE__ */ markSelfWired(
-  Object.assign(ComboboxStandalone, {
-    Async: /* @__PURE__ */ markSelfWired(ComboboxAsyncStandalone, "Combobox.Async"),
-    Parts: ComboboxParts,
-    useAsync,
-    useFilter,
-    useCreatable,
-  }),
-  "Combobox",
-);
+const Combobox: ComboboxComponent = Object.assign(ComboboxStandalone, {
+  Async: ComboboxAsyncStandalone,
+  Parts: ComboboxParts,
+  useAsync,
+  useFilter,
+  useCreatable,
+});
 
 export { Combobox };
diff --git a/packages/core/src/components/date-field/date-field.tsx b/packages/core/src/components/date-field/date-field.tsx
index 668b90eba..7eb719007 100644
--- a/packages/core/src/components/date-field/date-field.tsx
+++ b/packages/core/src/components/date-field/date-field.tsx
@@ -11,7 +11,6 @@ import {
 import { toCalendarDate, today, type DateValue } from "@internationalized/date";
 import { useFieldRootContext } from "@base-ui/react/internals/field-root-context";
 import { cn } from "@/lib/utils";
-import { markSelfWired } from "@/lib/self-wired-controls";
 import { useResolvedLocale, useTimeZone } from "@/contexts/appshell-context";
 import {
   useDateFieldState,
@@ -79,7 +78,13 @@ export type DatePickerProps<T extends DateValue = DateValue> = DateControlProps<
   timeZone?: string;
 };
 
-const DateFieldImpl = forwardRef(function DateField<T extends DateValue = DateValue>(
+/**
+ * A segmented date/time input field with no popover.
+ *
+ * Compose with `Field.Root` for label / description / error presentation, or
+ * provide standalone ARIA wiring yourself.
+ */
+const DateField = forwardRef(function DateField<T extends DateValue = DateValue>(
   {
     id,
     className,
@@ -201,7 +206,13 @@ const DateFieldImpl = forwardRef(function DateField<T extends DateValue = DateVa
   props: DateFieldProps<T> & { ref?: Ref<HTMLInputElement> },
 ) => ReactElement;
 
-const DatePickerImpl = forwardRef(function DatePicker<T extends DateValue = DateValue>(
+/**
+ * A date/time input with a popover calendar.
+ *
+ * Compose with `Field.Root` for label / description / error presentation, or
+ * provide standalone ARIA wiring yourself.
+ */
+const DatePicker = forwardRef(function DatePicker<T extends DateValue = DateValue>(
   {
     id,
     className,
@@ -412,20 +423,5 @@ const DatePickerImpl = forwardRef(function DatePicker<T extends DateValue = Date
   props: DatePickerProps<T> & { ref?: Ref<HTMLInputElement> },
 ) => ReactElement;
 
-/**
- * A segmented date/time input field with no popover.
- *
- * Compose with `Field.Root` for label / description / error presentation, or
- * provide standalone ARIA wiring yourself.
- */
-const DateField = /* @__PURE__ */ markSelfWired(DateFieldImpl, "DateField");
-/**
- * A date/time input with a popover calendar.
- *
- * Compose with `Field.Root` for label / description / error presentation, or
- * provide standalone ARIA wiring yourself.
- */
-const DatePicker = /* @__PURE__ */ markSelfWired(DatePickerImpl, "DatePicker");
-
 export { DateField, DatePicker };
 export type { DateControlProps };
diff --git a/packages/core/src/components/date-field/date-range-picker.tsx b/packages/core/src/components/date-field/date-range-picker.tsx
index de5fd811f..0334240dc 100644
--- a/packages/core/src/components/date-field/date-range-picker.tsx
+++ b/packages/core/src/components/date-field/date-range-picker.tsx
@@ -11,7 +11,6 @@ import {
 } from "react";
 import { toCalendarDate, today, type DateValue } from "@internationalized/date";
 import { cn } from "@/lib/utils";
-import { markSelfWired } from "@/lib/self-wired-controls";
 import { useFieldRootContext } from "@base-ui/react/internals/field-root-context";
 import { useResolvedLocale, useTimeZone } from "@/contexts/appshell-context";
 import {
@@ -110,7 +109,7 @@ function rangesEqual(a: DateRange | null, b: DateRange | null): boolean {
   return a.start.compare(b.start as never) === 0 && a.end.compare(b.end as never) === 0;
 }
 
-const DateRangePickerImpl = forwardRef(function DateRangePicker<T extends DateValue = DateValue>(
+const DateRangePicker = forwardRef(function DateRangePicker<T extends DateValue = DateValue>(
   {
     id,
     className,
@@ -438,6 +437,4 @@ const DateRangePickerImpl = forwardRef(function DateRangePicker<T extends DateVa
   props: DateRangePickerProps<T> & { ref?: Ref<HTMLInputElement> },
 ) => ReactElement;
 
-const DateRangePicker = /* @__PURE__ */ markSelfWired(DateRangePickerImpl, "DateRangePicker");
-
 export { DateRangePicker };
diff --git a/packages/core/src/components/field/field.tsx b/packages/core/src/components/field/field.tsx
index 41b0954bc..c74e36b8a 100644
--- a/packages/core/src/components/field/field.tsx
+++ b/packages/core/src/components/field/field.tsx
@@ -2,10 +2,15 @@ import * as React from "react";
 import { Field as BaseField } from "@base-ui/react/field";
 
 import { useOnceWarnings } from "@/hooks/use-once-warnings";
-import { getSelfWiredName } from "@/lib/self-wired-controls";
 import { cn } from "@/lib/utils";
 import { inputBaseClasses } from "@/lib/input-classes";
 import { Text } from "../text";
+import { Autocomplete } from "../autocomplete";
+import { Checkbox } from "../checkbox";
+import { Combobox } from "../combobox";
+import { DateField, DatePicker, DateRangePicker } from "../date-field";
+import { Select } from "../select";
+import { Textarea } from "../textarea";
 
 // Only the props relevant to the Field abstraction are picked from BaseField.Root.
 // Base UI-internal props (e.g. actionsRef) are intentionally excluded
@@ -130,9 +135,26 @@ function Label({ className, ...props }: React.ComponentProps<typeof BaseField.La
 }
 Label.displayName = "Field.Label";
 
+// Controls that draw their own frame and connect to `Field.Root` themselves.
+// Passed to `Field.Control`'s `render`, they get a second frame plus `<input>`
+// props they don't take (platform-planning#1977).
+const selfWiredControls = new Map<unknown, string>([
+  [Select, "Select"],
+  [Select.Async, "Select.Async"],
+  [Combobox, "Combobox"],
+  [Combobox.Async, "Combobox.Async"],
+  [Autocomplete, "Autocomplete"],
+  [Autocomplete.Async, "Autocomplete.Async"],
+  [Checkbox, "Checkbox"],
+  [Textarea, "Textarea"],
+  [DateField, "DateField"],
+  [DatePicker, "DatePicker"],
+  [DateRangePicker, "DateRangePicker"],
+]);
+
 function renderMisuseWarnings(render: unknown): string[] {
   if (!React.isValidElement(render)) return [];
-  const name = getSelfWiredName(render.type);
+  const name = selfWiredControls.get(render.type);
   if (!name) return [];
   return [
     `Field.Control: \`render={<${name} />}\` draws a second frame around ${name}. ${name} connects to Field.Root by itself — place it directly under <Field.Root> instead of inside Field.Control.`,
diff --git a/packages/core/src/components/select/select-standalone.tsx b/packages/core/src/components/select/select-standalone.tsx
index e0ac258d1..b13576951 100644
--- a/packages/core/src/components/select/select-standalone.tsx
+++ b/packages/core/src/components/select/select-standalone.tsx
@@ -13,7 +13,6 @@ import {
 import { defaultMapItem, isGroupedItems } from "../dropdown-items";
 import type { MappedItem, ItemGroup, ExtractItem } from "../dropdown-items";
 import { AsyncErrorState, resolveAsyncContent } from "../internals/async-error-state";
-import { markSelfWired } from "@/lib/self-wired-controls";
 
 /**
  * Fetcher type for `Select.Async`.
@@ -582,27 +581,24 @@ type SelectComponent = typeof SelectStandalone & {
   useAsync: typeof useAsync;
 };
 
-const Select: SelectComponent = /* @__PURE__ */ markSelfWired(
-  Object.assign(SelectStandalone, {
-    /**
-     * Async select that fetches items when the dropdown opens.
-     *
-     * **Limitation:** This component defaults to `modal={false}` and
-     * `alignItemWithTrigger={false}` to work around Base UI scroll-lock bugs
-     * with dynamically loaded items. As a result, it may not function correctly
-     * inside focus-trapping containers such as `Dialog` or `Sheet` — the
-     * focus trap can block interaction with the dropdown, or the portal may
-     * render outside the modal's visible area.
-     *
-     * If you need an async dropdown inside a `Dialog` or `Sheet`, prefer
-     * `Combobox.Async` which uses Popover-based positioning and does not
-     * suffer from these constraints.
-     */
-    Async: /* @__PURE__ */ markSelfWired(SelectAsyncStandalone, "Select.Async"),
-    Parts: SelectParts,
-    useAsync,
-  }),
-  "Select",
-);
+const Select: SelectComponent = Object.assign(SelectStandalone, {
+  /**
+   * Async select that fetches items when the dropdown opens.
+   *
+   * **Limitation:** This component defaults to `modal={false}` and
+   * `alignItemWithTrigger={false}` to work around Base UI scroll-lock bugs
+   * with dynamically loaded items. As a result, it may not function correctly
+   * inside focus-trapping containers such as `Dialog` or `Sheet` — the
+   * focus trap can block interaction with the dropdown, or the portal may
+   * render outside the modal's visible area.
+   *
+   * If you need an async dropdown inside a `Dialog` or `Sheet`, prefer
+   * `Combobox.Async` which uses Popover-based positioning and does not
+   * suffer from these constraints.
+   */
+  Async: SelectAsyncStandalone,
+  Parts: SelectParts,
+  useAsync,
+});
 
 export { Select, useAsync };
diff --git a/packages/core/src/components/textarea/textarea.tsx b/packages/core/src/components/textarea/textarea.tsx
index da4d81d7a..914cc56f4 100644
--- a/packages/core/src/components/textarea/textarea.tsx
+++ b/packages/core/src/components/textarea/textarea.tsx
@@ -2,7 +2,6 @@ import * as React from "react";
 import { Field as BaseField } from "@base-ui/react/field";
 
 import { cn } from "@/lib/utils";
-import { markSelfWired } from "@/lib/self-wired-controls";
 import { textareaBaseClasses } from "@/lib/input-classes";
 
 // `render` is intentionally excluded: the component owns the `<textarea>` tag
@@ -86,10 +85,7 @@ type TextareaProps = Omit<
  * />
  * ```
  */
-const Textarea = /* @__PURE__ */ markSelfWired(function Textarea({
-  className,
-  ...props
-}: TextareaProps) {
+function Textarea({ className, ...props }: TextareaProps) {
   return (
     <BaseField.Control
       data-slot="textarea"
@@ -110,6 +106,6 @@ const Textarea = /* @__PURE__ */ markSelfWired(function Textarea({
       {...(props as React.ComponentProps<typeof BaseField.Control>)}
     />
   );
-}, "Textarea");
+}
 
 export { Textarea, type TextareaProps };
diff --git a/packages/core/src/lib/self-wired-controls.ts b/packages/core/src/lib/self-wired-controls.ts
deleted file mode 100644
index 2eb410553..000000000
--- a/packages/core/src/lib/self-wired-controls.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-// Registry of controls that draw their own frame and connect to `Field.Root`
-// themselves. Each control registers in its own definition, so a new
-// form control copies the call from its neighbours. `Field.Control` reads it to
-// warn when one is passed to `render` (platform-planning#1977).
-const selfWired = new WeakMap<object, string>();
-
-/**
- * Returns `component`, so the call wraps the definition and stays removable:
- * `const X = /* @__PURE__ *\/ markSelfWired(XImpl, "X")`. A bare top-level
- * call would keep every control in a bundle that only imports `Field`.
- */
-export function markSelfWired<T extends object>(component: T, name: string): T {
-  selfWired.set(component, name);
-  return component;
-}
-
-export function getSelfWiredName(type: unknown): string | undefined {
-  return typeof type === "function" || (typeof type === "object" && type !== null)
-    ? selfWired.get(type)
-    : undefined;
-}