@tailor-platform/app-shell 1.12.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -37,6 +37,10 @@
     "./vite-plugin": {
       "types": "./dist/vite-plugin.d.ts",
       "default": "./dist/vite-plugin.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "publishConfig": {
@@ -46,7 +50,7 @@
     "@base-ui/react": "1.6.0",
     "@internationalized/date": "3.12.2",
     "@standard-schema/spec": "^1.1.0",
-    "@tailor-platform/auth-public-client": "^0.5.1",
+    "@tailor-platform/auth-public-client": "^0.6.1",
     "change-case": "^5.4.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -57,29 +61,31 @@
     "react-router": "^8.3.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.6.0",
-    "@tailor-platform/app-shell-vite-plugin": "0.2.3"
+    "@tailor-platform/vite-plugin-app-shell": "0.3.0"
   },
   "devDependencies": {
-    "@tailwindcss/postcss": "^4.3.0",
-    "@testing-library/react": "16.3.2",
-    "@testing-library/user-event": "14.6.3",
-    "@types/encoding-japanese": "^2.2.1",
+    "@fontsource-variable/noto-sans-jp": "5.3.0",
+    "@microsoft/api-extractor": "7.58.12",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@testing-library/react": "16.3.3",
+    "@testing-library/user-event": "14.6.7",
+    "@types/encoding-japanese": "2.2.1",
     "@types/node": "^25.9.5",
-    "@types/papaparse": "^5.5.2",
+    "@types/papaparse": "5.5.2",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@vitejs/plugin-react": "^5.2.0",
+    "@vitejs/plugin-react": "^6.1.0",
+    "@vitest/coverage-v8": "4.1.10",
     "happy-dom": "20.9.0",
     "postcss": "8.5.26",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "tailwindcss": "^4.2.4",
-    "tw-animate-css": "^1.4.0",
+    "react-hook-form": "7.71.2",
+    "tailwindcss": "^4.3.3",
+    "tw-animate-css": "1.4.0",
     "typescript": "5.9.3",
-    "vite": "^7.3.2",
-    "vite-plugin-dts": "^4.5.0",
-    "vite-plugin-externalize-deps": "^0.10.0",
-    "vite-tsconfig-paths": "^6.1.1",
+    "vite": "^8.2.2",
+    "vite-plugin-dts": "5.0.3",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
@@ -89,6 +95,8 @@
   "scripts": {
     "dev": "vite build --watch --mode development",
     "build": "vite build",
+    "check-dts": "node scripts/check-dts.mjs",
+    "vendor:fonts": "node scripts/sync-noto-fonts.mjs",
     "lint": "oxlint -c .oxlintrc.jsonc",
     "test": "vitest run",
     "type-check": "tsc --incremental"

package/skills/app-shell-patterns/SKILL.md

@@ -25,6 +25,12 @@ These are the foundational rules that underpin all patterns. All patterns build
 
 Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, theming, or dark mode looks wrong after a version bump. These breakages are silent: the build succeeds and nothing warns, so the cause is not discoverable from the error output. The package ships no CHANGELOG, so this file is the only migration record available locally.
 
+## Available Pages
+
+A page is the shape of a whole screen — the outer choice, made before picking patterns for the parts inside it. Where a pattern is one recipe, a page compares the layouts a screen could take and says when each applies. Match the screen first, then use the patterns the entry cites for the pieces within it.
+
+
+
 ## Available Patterns
 
 ### detail
@@ -35,12 +41,13 @@ Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, themi
 
 ### form
 
-| Slug                                                          | Name             | Description                                                                       |
-| ------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
-| [`form/modal`](references/patterns/form-modal.md)             | Modal Form       | Default form pattern for Create/Edit — keeps user in context on the parent screen |
-| [`form/sectioned`](references/patterns/form-sectioned.md)     | Sectioned Form   | Complex form with 15+ fields organized into named fieldset sections               |
-| [`form/single-page`](references/patterns/form-single-page.md) | Single Page Form | Routed full-page form for moderate field count (6-15) without natural sectioning  |
-| [`form/wizard`](references/patterns/form-wizard.md)           | Wizard Form      | Multi-stage create flow with 3-7 steps and per-step validation gates              |
+| Slug                                                          | Name             | Description                                                                                                              |
+| ------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| [`form/composer`](references/patterns/form-composer.md)       | Composer         | Free-text composer — a multi-line input above a trailing action row, for notes, replies, and comments submitted in place |
+| [`form/modal`](references/patterns/form-modal.md)             | Modal Form       | Default form pattern for Create/Edit — keeps user in context on the parent screen                                        |
+| [`form/sectioned`](references/patterns/form-sectioned.md)     | Sectioned Form   | Complex form with 15+ fields organized into named fieldset sections                                                      |
+| [`form/single-page`](references/patterns/form-single-page.md) | Single Page Form | Routed full-page form for moderate field count (6-15) without natural sectioning                                         |
+| [`form/wizard`](references/patterns/form-wizard.md)           | Wizard Form      | Multi-stage create flow with 3-7 steps and per-step validation gates                                                     |
 
 ### interaction
 
@@ -82,4 +89,5 @@ Full rationale in [`design-system.md`](references/fundamental/design-system.md)
 - **Action placement:** primary CTA + status in `Layout.Header`; workflow actions in `ActionPanel`; back/navigation in the breadcrumb — never in `ActionPanel`.
 - **Metric tiles always go in a `Grid`** (`columns={{ initial: 1, md: 2, xl: 4 }}`) — never one-per-row.
 - **Forms default to `form/modal`** — only build a routed full-page form when the design explicitly calls for one.
+- **Forms use AppShell `Form` + `Field`**, submitting via `onFormSubmit` — never a bare `<form onSubmit>` with `FormData`. `onFormSubmit` reads registered `Field.Root`s, so every control (dropdowns included) just needs a wrapping `Field.Root name="…"` — no `name` on the control, no `useState`. React Hook Form is optional, consumer-installed, and only warranted for cross-field validation, field arrays, or a Zod resolver. Details in [`components.md`](references/fundamental/components.md) → Forms.
 - **Handle every state:** loading (skeleton), empty (labelled empty state), and error (inline + retry) — never ship only the happy path.

package/skills/app-shell-patterns/references/fundamental/components.md

@@ -194,6 +194,13 @@ import { Button, Link } from '@tailor-platform/app-shell';
 **API:** `to`, `replace`, `state`, etc. — same as `react-router`.
 **Used in patterns:** all (navigation).
 
+### `NavLink`
+
+**Import:** `import { NavLink } from '@tailor-platform/app-shell'`
+**Purpose:** `Link` that knows when it is active — for nav menus and tab bars.
+**API:** `to`, plus `className` / `style` / `children` as render functions receiving `{ isActive, isPending }`.
+**Used in patterns:** navigation shells.
+
 ### `Dialog`
 
 > Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/dialog.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/dialog.md)
@@ -426,7 +433,7 @@ const table = useDataTable({
 
 **Column alignment:** each `Column` accepts **`align`** (`"left" | "right"`) applied to both header and body cell. Numeric `type` columns (`"number"`, `"money"`) default to `"right"` automatically so digits align on the decimal place — pass `align="left"` to opt out; everything else defaults to `"left"`.
 
-**Metadata path:** Prefer `createColumnHelper` + `inferColumns(tableMetadata.order)` (`@tailor-platform/app-shell-sdk-plugin` codegen) when available so enum/datetime/string filters bind to the right editors.
+**Metadata path:** Prefer `createColumnHelper` + `inferColumns(tableMetadata.order)` (`@tailor-platform/sdk-plugin-app-shell` codegen) when available so enum/datetime/string filters bind to the right editors.
 
 **Bucket tabs / segmented UX:** AppShell defines **toolbar chips**, not lifecycle tabs. When design places **`Tabs`** (All / Draft / …) inside the card, compose them **above** `DataTable.Root` and synchronize tab-driven bucket state with **`useCollectionVariables`** (`variables.query` / filters)—see **`patterns/list/dense-scan.md`**.
 
@@ -612,13 +619,41 @@ const table = useDataTable({
 
 ## Forms
 
+> **Which form stack?** AppShell's `Form` / `Field` / `Fieldset` wrap Base UI primitives and are the
+> default — they need no extra dependency. They own **accessibility wiring and visual state only**
+> (`htmlFor`, `aria-describedby`, `data-invalid` / `data-dirty` / `data-touched`); they do **not** own
+> your values. React Hook Form is **optional** and consumer-installed — reach for it only when a form
+> genuinely needs cross-field validation, field arrays, or a Zod resolver. The two compose; they are
+> not alternatives. `react-hook-form` stopped being a runtime dependency in 1.4.0; it is a dev-only
+> dependency of the package today, used to test the RHF integration contracts — if you use it,
+> install it in your own app.
+
 ### `Form`
 
 > Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/form.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/form.md)
 
 **Import:** `import { Form } from '@tailor-platform/app-shell'`
-**Purpose:** Form root wired to react-hook-form. Use with `Field`, `Fieldset`, and Zod for validation.
-**API:** `FormProps` — `errors`, `actionsRef`, `validationMode`, `noValidate`, plus a namespace exposing form-related sub-helpers. Generic over `FormValues`.
+**Purpose:** Form root that wraps Base UI's form primitive. Provides shared validation context for
+child `Field.Root`s, consolidated error display, and server-error routing by field `name`.
+**API:** `FormProps` — `onFormSubmit`, `onSubmit`, `errors`, `actionsRef`, `validationMode`,
+`noValidate`, `id`. Generic over `FormValues`.
+**Actions outside the form:** give the `Form` an `id` and point a detached submit button at it with
+the native `form` attribute. This is how a page-header Save reaches a body form (1.13.0+):
+
+```tsx
+<Layout.Header
+  title="Create product"
+  actions={[<Button key="save" type="submit" form="product-form">Save</Button>]}
+/>
+<Form id="product-form" onFormSubmit={save}>…</Form>
+```
+
+**Submit:** use `onFormSubmit(values)` — it receives parsed form values and is the default. Use the
+low-level `onSubmit` **only** when handing the native event to React Hook Form's `handleSubmit`.
+**Never** hand-roll `<form onSubmit={e => new FormData(e.currentTarget)}>` — that skips validation
+and error routing.
+**Server errors:** pass `errors={{ fieldName: "message" }}`; they route to the matching
+`Field.Error` and clear when the user edits that field.
 **Example:** see `form/single-page.md`.
 **Used in patterns:** all `form/*`.
 
@@ -626,9 +661,71 @@ const table = useDataTable({
 
 **Import:** `import { Field } from '@tailor-platform/app-shell'`
 **Purpose:** Single form field with label + control + error message wiring.
-**API:** Compound. Wraps any input control (`Input`, `Select`, `Combobox`, etc.) and binds it to react-hook-form via `name`.
+**API:** Compound — `Field.Root`, `Field.Label`, `Field.Control`, `Field.Description`, `Field.Error`,
+`Field.Validity`. `Field.Root` establishes a context boundary; every Base UI-backed AppShell control
+placed inside it inherits label association, `aria-describedby`, `disabled`, and invalid state
+automatically.
+**`Field.Control` is already a styled input** — write `<Field.Control />`, not
+`<Field.Control render={<Input />} />`. `Input` and `Field.Control` share the same base classes, so
+the `render` form just double-wraps. Reach for `Input` directly when you need a control outside a
+`Field.Root`, or when the value is React-controlled.
+**RHF interop (optional):** `Field.Root` accepts `isTouched`, `isDirty`, `invalid`, and `error`,
+matching RHF's `fieldState` shape — so `<Field.Root {...fieldState}>` works with no adapter.
 **Used in patterns:** all `form/*`.
 
+### How values reach your submit handler
+
+There are three separate mechanisms. Picking the wrong mental model is the most common
+form mistake, so be explicit about which one a screen uses.
+
+**1. `Form` + `Field.Root` → `onFormSubmit` (the default).** `onFormSubmit` does **not** read
+`FormData`; it collects values from the `Field.Root`s registered inside the `Form`, keyed by each
+field's `name`. Every AppShell control works this way once wrapped in a `Field.Root name="…"` —
+including `Select`, `Combobox`, and `Autocomplete`. They need **no `name` of their own and no React
+state**:
+
+```tsx
+<Form onFormSubmit={(values) => save(values)}>
+  <Field.Root name="category">
+    <Field.Label>Category</Field.Label>
+    <Select items={CATEGORIES} placeholder="Select category" />
+  </Field.Root>
+</Form>
+```
+
+**2. Native submission** — a plain `<form>`, `new FormData(form)`, or a server action. This reads the
+DOM, so each control needs its own `name`. `Select`, `Combobox`, and `Autocomplete` gained `name`
+(plus `form`, `required`, `inputRef`) in 1.13.0; before that they contributed nothing to a native
+payload.
+
+**3. React Hook Form** — optional, consumer-installed. RHF owns the values; drive the control with
+`value` / `onValueChange` from a `Controller` and spread `fieldState` onto `Field.Root`. Warranted
+for cross-field validation, field arrays, or a Zod resolver — not for ordinary CRUD forms.
+
+#### Object items
+
+Under mechanism 1, a non-string item is serialised into the submitted value:
+
+| Item shape                             | Value in `onFormSubmit`              |
+| -------------------------------------- | ------------------------------------ |
+| `string`                               | the string                           |
+| `{ value, label }`                     | `value`, automatically               |
+| any other object                       | **JSON string** — usually not wanted |
+| any other object + `itemToStringValue` | whatever that function returns       |
+
+So for arbitrary objects, pass `itemToStringValue` to choose the submitted key. It is distinct from
+`mapItem`, which controls what the user sees:
+
+```tsx
+<Combobox
+  items={warehouses}
+  mapItem={(w) => ({ label: w.name, key: String(w.id) })}
+  itemToStringValue={(w) => String(w.id)}
+/>
+```
+
+Multi-select submits an array.
+
 ### `Fieldset`
 
 **Import:** `import { Fieldset } from '@tailor-platform/app-shell'`
@@ -643,6 +740,26 @@ const table = useDataTable({
 **API:** `InputProps` — extends native `<input>` props.
 **Used in patterns:** all `form/*`.
 
+### `Textarea`
+
+> Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/textarea.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/textarea.md)
+
+**Import:** `import { Textarea } from '@tailor-platform/app-shell'`
+**Purpose:** Multi-line text input. Maps to spec field types: `text`, long-form `string`. Use instead of `Input` whenever the value is prose (notes, descriptions, replies, reasons).
+**API:** `TextareaProps` — Base UI's field control (`value`, `defaultValue`, `onChange`, `onValueChange`, `disabled`, `required`, `readOnly`, `name`, aria-\*) rendered as a `<textarea>`, plus `rows`. `cols` / `wrap` are not accepted — the control is `w-full`, so neither can take effect.
+**Sizing:** no fixed height — `rows` sets the visible line count and the user can drag it taller. `min-h-16` is a hard floor, so `rows` only takes effect from 3 up. Width is the parent's job: the control is `w-full`, and `cols` is not accepted because it could never win against that. Do **not** reach for `Input` and a height override; `Input` is locked to `h-9`, and an `astw:h-*` override from a consuming app resolves to nothing unless that exact utility was compiled into the package CSS.
+**Field integration:** drops straight into `Field.Root` for label/description/error wiring exactly like `Input` and `Checkbox` — no bespoke `error` prop.
+**Example:**
+
+```tsx
+<Field.Root name="reason">
+  <Field.Label>Reason</Field.Label>
+  <Textarea rows={4} placeholder="Why is this being rejected?" />
+</Field.Root>
+```
+
+**Used in patterns:** `form/composer`, `form/*` (long-text fields).
+
 ### `Checkbox`
 
 **Import:** `import { Checkbox } from '@tailor-platform/app-shell'`
@@ -730,6 +847,32 @@ Types for authoring guard functions used by `WithGuard` and `appShellPageProps.g
 **Purpose:** Re-exported from `react-router`. Use the AppShell barrel — never import from `react-router` directly.
 **Used in patterns:** all (navigation, route params, query state).
 
+### `useMatch`, `useResolvedPath`, `useNavigation`
+
+**Import:** `import { useMatch, useResolvedPath, useNavigation } from '@tailor-platform/app-shell'`
+**Purpose:** `useMatch` tests a pattern against the current location (active states); `useResolvedPath` resolves a relative path; `useNavigation` exposes the in-flight navigation for pending UI.
+**Used in patterns:** navigation shells, list→detail transitions.
+
+### `useBlocker`, `useBeforeUnload`
+
+**Import:** `import { useBlocker, useBeforeUnload } from '@tailor-platform/app-shell'`
+**Purpose:** Guard navigation away from unsaved work — `useBlocker` for in-app navigation, `useBeforeUnload` for closing or reloading the tab.
+**Used in patterns:** form-heavy screens.
+
+### Types
+
+**Import:** `import type { Location, NavigateFunction, NavigateOptions, To, Params, PathMatch, LinkProps, NavLinkProps, Navigation, Blocker, BlockerFunction } from '@tailor-platform/app-shell'`
+**Purpose:** The React Router types that go with the hooks above, so app code never imports types from `react-router` either.
+
+### Not exported
+
+`createBrowserRouter`, `RouterProvider`, `MemoryRouter`, `Routes`, `Route` — AppShell builds the router; a second one nested inside it breaks navigation. `useLoaderData`, `Form`, `useSubmit`, `useFetcher`, `useActionData` — AppShell does not wire up React Router's data layer. Load data in the page component or the app's data layer.
+
+### Testing
+
+**Import:** `import { AppShell, TestRouter } from '@tailor-platform/app-shell/testing'`
+**Purpose:** Test routing without a `react-router` dependency. `AppShell` from this entry also accepts `memory` / `initialEntries`, for mounting a page at a fixed URL; `TestRouter` gives a single component router context, and takes `path` when that component reads the route (`useParams` is `{}` without it).
+
 ### `createTypedPaths`
 
 **Import:** `import { createTypedPaths } from '@tailor-platform/app-shell'`

package/skills/app-shell-patterns/references/fundamental/design-system.md

@@ -184,7 +184,7 @@ Hand-typing `padding: 13px` is a smell. Round to the nearest scale step; if noth
 
 ### Typography
 
-**AppShell defines no typography scale tokens.** There is no `text-h1`, `text-body`, or `text-caption`. The only typography token is `--font-sans` (Inter Variable) → `font-sans`, which the base layer already applies to `body`.
+**AppShell defines no typography scale tokens.** There is no `text-h1`, `text-body`, or `text-caption`. The only typography token is `--font-sans` (Inter Variable for Latin, Noto Sans JP Variable for Japanese) → `font-sans`, which the base layer already applies to `body`. Both are variable fonts, so every weight token is real in both scripts. Override the whole stack by setting `--app-shell-font-sans` on `:root`.
 
 Compose roles from stock Tailwind utilities. These pairings are what AppShell's own components use — match them so your screens sit consistently alongside the primitives:
 

package/skills/app-shell-patterns/references/fundamental/graphql.md

@@ -108,7 +108,7 @@ For `pnpm gql-tada:check` to pass, always destructure with optional chaining and
 
 For **standard list pages**, do not hand-roll only `first` / `after`. Compose AppShell **`DataTable`** + **`useCollectionVariables`** + **`useDataTable`**: derive query variables from `variables.pagination`, `variables.query`, `variables.order`, map `edges` / `pageInfo` / `total` into `useDataTable`’s `data`. See **`patterns/list/dense-scan.md`** and **`components.md` → DataTable**.
 
-When `@tailor-platform/app-shell-sdk-plugin` codegen is enabled, pass generated **`tableMetadata`** into **`useCollectionVariables`** so `variables.query` / `variables.order` are typed against your Tailor GraphQL inputs (upstream **data-table.md** Typed query variables).
+When `@tailor-platform/sdk-plugin-app-shell` codegen is enabled, pass generated **`tableMetadata`** into **`useCollectionVariables`** so `variables.query` / `variables.order` are typed against your Tailor GraphQL inputs (upstream **data-table.md** Typed query variables).
 
 ## Mutations and cache invalidation
 

package/skills/app-shell-patterns/references/patterns/form-composer.md

@@ -0,0 +1,142 @@
+---
+slug: pattern/form/composer
+name: Composer
+category: pattern
+subcategory: form
+description: Free-text composer — a multi-line input above a trailing action row, for notes, replies, and comments submitted in place
+requiredImports: [Card, Textarea, Button, Checkbox]
+tags: [composer, textarea, note, reply, comment, actions, discard, send]
+do:
+  - A free-text box the user fills and submits in place — add a note, reply on a thread, leave a comment, give a rejection reason
+  - The prose IS the interaction; any other controls only qualify how the text is submitted
+dont:
+  - The text is one field among many on a record form — use form/modal, form/single-page or form/sectioned with a Textarea field
+  - A chat input where Enter sends and there is no Discard — that is a different layout
+---
+
+# pattern/form/composer
+
+## When to Use
+
+- A free-text box the user fills and submits in place — add a note, reply on a thread, leave a comment, give a rejection reason
+- The prose IS the interaction; any other controls only qualify how the text is submitted
+
+## Layout
+
+```
++---------------------------------------------------------+
+| Card.Root / Card.Content                                 |
+|  +-----------------------------------------------------+ |
+|  | Textarea                                            | |
+|  |                                                     | |
+|  +-----------------------------------------------------+ |
+|  [ options slot … ]                  [Discard] [ Send ] |
++---------------------------------------------------------+
+```
+
+Two rows inside one `Card`:
+
+1. **Body** — a single `Textarea`, sized with `rows`. Tall enough to read as "write here", short enough that the action row stays on screen.
+2. **Action row** — one `flex items-center justify-between` line with a fixed right side and a free left side.
+
+## The action row
+
+This is the part the pattern actually fixes. Everything sits on **one line**, never stacked.
+
+**Right side — fixed.** Reading left to right: an optional `variant="ghost"` **Discard**, then exactly **one** primary submit. Nothing else goes here.
+
+- Discard clears the body; it does not close or navigate. Omit it when there is nothing to discard back to.
+- The submit is the view's single primary `Button` — never a second filled button beside it.
+- Both disable while `submitting`; the submit also disables on empty/whitespace-only input.
+- Swap the submit's label for a pending label while in flight ("Send" → "Sending…"). Do not swap in a spinner-only button — the label is what tells the user what is happening.
+
+**Left side — open.** Zero or more controls that qualify the submission, laid out `flex items-center gap-2` and allowed to shrink (`min-w-0`) so the buttons never get pushed off. Common occupants:
+
+- a `Checkbox` toggle — visibility, "internal note", "notify watchers" (the worked example below)
+- an attachment or template `Button` with `variant="ghost"`
+- a small `Select` — reply-as, channel, canned response
+
+Leave it empty and the buttons still sit correctly at the right; `justify-between` needs no placeholder element.
+
+## Page Implementation
+
+```tsx
+/* pattern: form/composer */
+import { useState } from "react";
+import { Button, Card, Checkbox, Textarea } from "@tailor-platform/app-shell";
+
+type Props = {
+  onSubmit: (body: string, internal: boolean) => void;
+  submitting?: boolean;
+};
+
+export default function Composer({ onSubmit, submitting = false }: Props) {
+  const [body, setBody] = useState("");
+  const [internal, setInternal] = useState(false);
+
+  return (
+    <Card.Root>
+      <Card.Content>
+        <div className="space-y-3">
+          <Textarea
+            aria-label="Reply"
+            value={body}
+            onChange={(e) => setBody(e.target.value)}
+            placeholder={internal ? "Internal context for teammates…" : "Reply to customer…"}
+            rows={4}
+          />
+          <div className="flex items-center justify-between gap-2">
+            {/* Options slot — 0..N controls that qualify the submission. An
+                internal-note toggle here; swap for an attachment button, a
+                visibility Select, a template picker, or drop it entirely. */}
+            <div className="flex min-w-0 items-center gap-2">
+              <Checkbox
+                label="Internal note (not sent to customer)"
+                checked={internal}
+                onCheckedChange={setInternal}
+              />
+            </div>
+            {/* Action slot — fixed shape: optional ghost Discard, then exactly
+                one primary submit. Never more than one primary. */}
+            <div className="flex shrink-0 gap-2">
+              <Button
+                variant="ghost"
+                onClick={() => setBody("")}
+                disabled={body.length === 0 || submitting}
+              >
+                Discard
+              </Button>
+              <Button
+                onClick={() => onSubmit(body, internal)}
+                disabled={body.trim().length === 0 || submitting}
+              >
+                {submitting ? "Sending…" : "Send"}
+              </Button>
+            </div>
+          </div>
+        </div>
+      </Card.Content>
+    </Card.Root>
+  );
+}
+```
+
+## Constraints
+
+- The body control is `Textarea`, never `Input` — `Input` is locked to `h-9` and clips prose to one 36px line.
+- Size the body with `rows` (3–5 is the usual range). Don't reach for an `astw:h-*` / `astw:min-h-*` override: `astw:` utilities only resolve if that exact class was compiled into the AppShell package CSS, so an arbitrary one written in a consuming app silently does nothing.
+- The `Textarea` needs an accessible name. There is usually no visible label in a composer, so pass `aria-label`; a placeholder is not a label.
+- One primary `Button` in the action row. Discard is `ghost`, and any left-side action is `ghost` too.
+- The action row is one row at every width — the left side shrinks, the buttons do not wrap under the body.
+- Disable the submit on empty or whitespace-only input, and disable both buttons while `submitting`.
+- Wrap the composer in `Card.Root` when it sits among other cards (a detail page, the end of a thread). A composer that is already inside a `Sheet` or `Dialog` body does not need its own card.
+
+## Anti-patterns
+
+- `Input` (or `Field.Control` with no override) for the body — a single-line box for multi-line text.
+- Discard rendered as `outline` or filled — it competes with the submit for the eye.
+- Submit and Discard both filled, or a third action added to the right side.
+- The action row stacked above the `Textarea`, or the buttons wrapped onto their own line — the composer stops reading as one unit.
+- A left-side toggle that silently changes what the submit does without changing the submit's own affordance — if "internal note" changes the destination, the placeholder (or the label) should say so.
+- Submit enabled on an empty body, so the user can post nothing.
+- A body so tall (`rows={12}`) that the action row falls below the fold — the composer stops reading as one unit.