fix(field): warn when Field.Control renders a self-framed control

.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, the `Field.Control` self-wired list, and alignment with nearby Base UI-backed control contracts
 
 ## Inclusion Criteria
 

.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 — 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
 
 Check whether these paths still converge on the same meaning when they exist:

.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. 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.

docs-manifest.json

@@ -699,9 +699,9 @@
       "symbols": ["Form", "FormProps"],
       "hashes": {
         "typeSurface": "7b374d45d53d4535",
-        "outline": "79c9b0f08ca38027",
+        "outline": "7fefd291a00de910",
         "snapshot": "5d7a7904c5256f29",
-        "outputMd": "91d901b17aed7781",
+        "outputMd": "e4a66f7b1ee4aa98",
         "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": "a8b7834a8817e0d5",
         "snapshot": "2ef5b7324018ff8f",
-        "outputMd": "ae287e2bb5abc1c6",
+        "outputMd": "b3dd3b9a58a9d290",
         "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": "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",
     "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": "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",
@@ -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",

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>`. `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,17 @@ 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 />}`. 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                                     |
+| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| 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` |
+
+`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);

docs-src/components/select.docs.outline.md

@@ -161,6 +161,16 @@ 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.
+
+```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.

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`