themelia-react-ui 2.0.3 → 2.0.4

package/docs/consumer-skill/references/review.md

@@ -24,21 +24,26 @@ one solid primary command per page or surface, so the next action stays obvious.
 
 ## Done means
 
-UI work is done when the source checker below reports no errors on the files you
-changed, and the app's typecheck, lint and tests then pass. Run the checker, fix
+UI work is complete only with three separate proofs: source/API checks, inspected
+rendered appearance and executed interactions. The source checker below must
+report no errors on changed files, and the app's typecheck, lint and tests must
+pass. Inspect the actual narrow/wide and light/dark states relevant to the change,
+including opened surfaces; execute the affected callbacks, keyboard/focus and
+error/retry paths. Record any missing proof as an unverified limit. Run the checker, fix
 the owner or prop each finding names, and run it again; after three rounds, stop
 and report what remains. Warnings are review findings: fix each one or keep it
 with a reason. This is the agent's completion condition, not the build's; app CI
 may stay non-blocking on warnings. The [project instructions
 block](agents-md.md) states the same condition in the app's `AGENTS.md`.
 
-Hand back five lines, so a skipped check is visible:
+Hand back a short evidence record, so skipped checks and missing proof are visible:
 
 1. Owners used for the route, its commands and each data region.
 2. Checker: run or not run, with its error and warning counts.
 3. Typecheck, lint and tests: each run or not run, and why.
 4. Kept warnings, each with file:line and its reason.
-5. States covered or missing: loading, empty, error, disabled and validation.
+5. Rendered: widths/themes/states measured and images actually inspected, with judgment.
+6. Interactions: actions and resulting states executed, including relevant focus, cancellation, loading, error/retry and validation; list missing coverage.
 
 ## Source checker
 

package/docs/consumer-skill/references/rhf-workflows.md

@@ -0,0 +1,86 @@
+# React Hook Form workflows
+
+Use `react-hook-form` for form state in create/edit pages, settings and overlays. Import chrome from `themelia-react-ui/base/forms`, text controls from `base/text-inputs`, choices from `base/choice-inputs`, dates from `base/date-pickers` and structured values from `base/value-inputs`. RHF is optional at package level, but the whole `base/forms` family requires its peer, including presentation-only FormField imports. A schema resolver is an application choice, not another required library dependency.
+
+## Screen and state ownership
+
+The complete [order edit page](../examples/rhf-edit-page.tsx) composes:
+
+`Page render={<form ... />}` owns the native form, containing `DirtyStateBanner / ErrorSummary → TwoColumnLayout → FormSection → ControlledFormField → sticky FormActionsBar / SubmitStateButton`.
+
+Page owns the route title/gutters and TwoColumnLayout owns peer rhythm. FormSection owns its surface and field gaps; do not wrap a framed FormSection in another Card. Inside an already padded boundary, use `surface="flat" padding="none"`. Inside an unpadded boundary, a flat FormSection keeps its ordinary inset; flat surface alone does not remove padding. `handleSubmit` validates and awaits persistence. `isSubmitting` drives the submit button and disabled fields; `isDirty` drives dirty feedback and pristine submit protection. An in-flight ref also blocks duplicate same-tick requests. Native form validation is disabled in these RHF examples so the schema/rules produce one consistent error source.
+
+Page forwards `render` to its existing Container, so rendering it as the form preserves one width, gutter and query-boundary owner. Its body already spaces direct subjects; no extra Container or Stack is needed around the layout and action bar. `TwoColumnLayout adaptTo="container"` adapts to that Page width. A standalone form outside Page needs its own deliberate query boundary when it selects container adaptation.
+
+Use `useFieldArray`'s stable `field.id` as the React key, preserve names such as `lines.${index}.quantity`, and set complete append defaults. Derive totals from `useWatch`; do not persist a second total that can drift. Collect nested client/server errors into ErrorSummary while keeping each field's local message. Use `setFocus` or summary links for focusable controls when the app's error-summary design requires it.
+
+Mount an editor with `key={record.id}` when switching records. `defaultValues` establishes the saved baseline. On accepted success call `reset(authoritativeSavedValues)` to clear dirty state and keep server normalization. `reset()` discards to that baseline. Failed validation, transport failure or cancellation keeps the draft. Do not reset on every background cache refresh. If the product allows editing during a request, reconcile the accepted response with later edits explicitly; these recipes disable editing while saving.
+
+## Typed control bindings
+
+[TypedControlBindings](../examples/rhf-bindings.tsx) typechecks every supported binding without `any`, control casts or a generic spread adapter. A public control's event contract is part of its API:
+
+| Control | Controlled state | Change and RHF focus/touch binding |
+| --- | --- | --- |
+| Input / Textarea | `value: string` | `onValueChange(value)` → `field.onChange`; `ref`, `onBlur` |
+| Select | `value: string` | `onValueChange(value)` → `field.onChange(value ?? '')`; trigger `ref`, `onBlur` |
+| Switch / Checkbox | `checked: boolean` | `onValueChange(checked)` → `field.onChange`; `ref`, `onBlur` |
+| ToggleField / SwitchCard | `value: boolean` | `onValueChange(checked)`; `controlRef`, `onBlur`; their own label owns the control name |
+| DatePicker (single) | `value: Date \| undefined` | `onValueChange(output)` → `field.onChange(output.date ?? null)`; `triggerRef`, `onBlur` |
+| DateTimeInput | ISO `value: string \| undefined` | `onValueChange(value)` → `field.onChange(value ?? '')`; `triggerRef`, `onBlur` |
+| PhoneInput | `value: string` | native `onChange(event.target.value)`; input `ref`, `onBlur` |
+| TagsInput | `value: string[]` (or typed objects) | `onValueChange(values)`; `inputRef`, `onBlur` |
+| SliderField (public slider name) | scalar `value: number` | `onValueChange(value)`; `inputRef`, `onBlur` |
+| ColorInput | `value: string` | `onValueChange(value)`; input `ref`, `onBlur` |
+
+For numeric Input fields normalize `event.target.valueAsNumber` according to the schema (an empty field is NaN); keep numeric validation explicit. Date-only fields need an application serialization policy; do not turn a local calendar date into a UTC instant accidentally. DateTimeInput uses ISO instants. Use `modal={false}` on pickers inside modal forms to avoid competing focus traps.
+
+ControlledFormField accepts a ReactNode error override or a name-based error getter, falling back to RHF validation. Its render callback's error argument remains string/undefined for compatibility. A direct supported control receives the generated label/control ID and supporting-text association automatically; omit routine `htmlFor`/`id` pairs. Each mount stays unique even when forms share field names. ToggleField and SwitchCard own their visible labels and forward the automatic supporting description to their editable control; omit an outer duplicate label.
+
+Compound children own their nested association. SliderField's `id` and forwarded `ref` name its group, while `inputRef` names the native range. The binding recipe uses visible copy with an ID, `aria-labelledby` on SliderField and `supportingTextId`/`aria-describedby` for its hint or error. Keep explicit IDs per mount when a passive wrapper separates chrome from the editable control; do not point `htmlFor` at a group or infer one common ref target across control families.
+
+## Transport lifecycle
+
+The app owns transport. RHF's submit callback must return a Promise spanning the complete request; otherwise `isSubmitting` drops early and repeated submissions become possible. The [callback bridge](../examples/rhf-transport.tsx) records success/errors/cancellation, then settles only from `onFinish`. It has no framework import or runtime dependency.
+
+For Laravel/Inertia, adapt the application's typed router and page props at this seam:
+
+```tsx
+const submit = form.handleSubmit(async values => {
+  const result = await awaitCallbackSave(values, (data, lifecycle) => {
+    router.put(`/orders/${order.id}`, data, {
+      preserveScroll: true,
+      onSuccess: page => lifecycle.onSuccess(readSavedOrder(page)),
+      onError: lifecycle.onError,
+      onCancel: lifecycle.onCancel,
+      onFinish: lifecycle.onFinish,
+    });
+  });
+  if (result.ok) form.reset(result.values);
+  else {
+    applyServerErrors(form.setError, result.errors, {
+      fields: ['reference', 'email', 'notes', 'priority', 'notify',
+        ...values.lines.flatMap((_, index) => [
+          `lines.${index}.product` as const,
+          `lines.${index}.quantity` as const,
+          `lines.${index}.priceMinor` as const,
+        ])],
+    });
+    if (result.message) form.setError('root.server', { message: result.message });
+  }
+});
+```
+
+`router`, `order` and `readSavedOrder(page)` belong to the app; readSavedOrder validates/reads its typed authoritative response. Import `applyServerErrors` from `themelia-react-ui/base/forms` and `awaitCallbackSave` from the copied bridge. The helper accepts unknown payloads, maps only string/string-array messages to an explicit typed FieldPath allowlist, and sends unknown keys to `root.server`. Include current array paths. Avoid casting arbitrary server keys to `keyof FormValues`; a server key may be unknown or a nested path. Client validation, Laravel errors and transport errors then render through one RHF error state. Handle rejection with try/catch as in the complete edit recipe; do not swallow errors or reset a failed draft.
+
+For TanStack Start/Query, pass an app-owned async function: `onSave={async values => { const saved = await saveOrder(values); await invalidateOrders(); return { ok: true, values: saved }; }}`. If server validation returns a structured result, return `{ok:false, errors, message}` instead. Await the server function/mutateAsync Promise and any cache work required before the form becomes editable. Do not pass a fire-and-forget `mutate` callback. A router/framework adapter does not replace RHF's frontend state ownership.
+
+## Overlay create and edit
+
+The complete [customer drawer](../examples/rhf-overlay-form.tsx) uses ActionDrawer and useOverlayVisibility from `features/overlays`. ActionDialog uses the same formId/loading contract for shorter forms. Opening explicitly calls `reset(recordSnapshot)` (or complete empty defaults); onSubmit owns validation and persistence. The overlay footer's `formId` calls requestSubmit on that actual form. Do not combine it with onConfirm/onAsyncConfirm, which would introduce a second submit path.
+
+Pass `loading={isSubmitting}` so confirm/cancel/close/Escape/outside dismissal follow the pending lock. A failed request shows ErrorSummary and field errors while the drawer stays open with its values. Success resets to the returned record, publishes it through onSaved, and hides the controlled overlay. Cancelling without saving leaves the committed record unchanged; reopening begins a new snapshot. If a product requires drafts across dismissal, store drafts outside the overlay and make that policy explicit rather than resetting on open.
+
+## Verify the real workflow
+
+Run the bundled composition checker and the app's type/lint/test scripts. Then execute required-field errors, field focus, typed edits, arrays/reorder/removal, computed totals, duplicate-submit protection, server errors, retry with retained draft, accepted reset and discard. Open the actual date/select/tag surfaces and drawer; check keyboard/dismissal/focus return and light/dark at narrow/wide widths. Static typechecks prove the bindings and exports, not an application's server behavior.

package/docs/consumer-skill/references/screen-archetypes.md

@@ -0,0 +1,22 @@
+# Screen archetypes
+
+Choose by the user's job, then inspect the exact declaration with the [finder](discovery.md).
+The [complete shipped blueprint index](../../../templates/README.md) includes
+the application shell and every domain example. These are source assets at the
+installed package's `templates/`; complete skill copying places them under the
+shared skill's `templates/` and rebases the links below.
+
+| Screen | Main owner and regions | Starting blueprint | Application-owned state |
+| --- | --- | --- | --- |
+| Index / directory | Page → fixed scope/context → FilterLayout → DataView/DataTable; maxWidth="full" when comparison needs it | [Scoped directory](../examples/scoped-directory.tsx), [index table](../examples/index-table.tsx) | URL/query, facets, paging, selection, bulk commands, loading/empty/error/retry |
+| Detail workspace | Page title/status/commands/tabs above TwoColumnLayout; subject Cards in main, facts/support in aside | [Orders](../../../templates/orders-template.tsx), [customers](../../../templates/customers-template.tsx), [record detail](../examples/detail.tsx) | Record snapshot, section/tab, permitted commands, overlay drafts, accepted server results |
+| Settings / edit | `Page render={<form ... />}` → dirty/error feedback → TwoColumnLayout → FormSection → ControlledFormField → sticky FormActionsBar | [RHF edit page](../examples/rhf-edit-page.tsx), [RHF drawer](../examples/rhf-overlay-form.tsx) | RHF values, rules/schema, arrays, computed totals, transport/errors, saved baseline |
+| Product editor | Page → product subjects and publishing/support regions → variant editor workflow | [Products](../../../templates/products-template.tsx) | Product snapshot, option/variant drafts, publishing settings, validation and persistence |
+| User access / permissions | Page → profile and role context → editable permission groups → save/discard feedback | [User permissions](../../../templates/user-permissions-template.tsx) | Role presets, permission draft, permitted commands, accepted-save/discard baseline and server enforcement |
+| Analytics overview | Page period control → numeric MetricBar/MetricGrid → comparison/chart Cards → operations/usage regions | [Operations analytics](../../../templates/analytics-operations-template.tsx), [analytics states](../examples/analytics.tsx) | Period/query, metric formatting, accepted series, independent loading/error/retry states |
+
+Page owns its h1, gutters and direct-child rhythm; TwoColumnLayout owns the column split and peer-region rhythm. Stack/Grid own nested sibling gaps. Card owns framing and aligned header/body/footer insets. Authentication uses [AuthShell](authentication.md), and content sites use [Container/Section](../examples/website.tsx).
+
+Headers carry one primary command and ordered secondary commands; period selects and similar non-command controls use header actions. Put destructive commands behind ConfirmDialog. Longer create/edit work belongs in ActionDrawer; a short focused form uses ActionDialog. Preserve a snapshot until save succeeds. Templates are copyable application sources, not package component entrypoints.
+
+Read only the relevant detail: [composition ownership](composition.md), [workflow states](workflows.md), [RHF transport and bindings](rhf-workflows.md), or [analytics contracts](analytics.md). The [review checklist](review.md) separates static checks from opened-surface and interaction evidence.

package/docs/consumer-skill/references/theming.md

@@ -4,7 +4,7 @@ The [design contract](design-contract.md) records which geometry changes togethe
 and which variant choices remain independent. Retheme shared responsibilities;
 avoid overriding individual components to imitate another density or inset.
 
-Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration. `--input` is the one resting control boundary: fields, select and date triggers, checkboxes, radios, switch tracks and outline buttons all draw it, so adjoining controls read as one family. It provides at least 3:1 contrast on the declared background, card, popover, muted, accent and secondary surfaces in both modes. Focus and invalid edges retain their separate 3:1 contract. `--border` is for quieter dividers and surface edges. When rebranding, check resting controls as well as focused controls, including the outside edge of fields with their own fill.
+Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration. `--input` is the shared resting control boundary: fields, select and date triggers, checkboxes, radios, switch tracks and outline buttons draw it. Its defaults follow shadcn neutral: `oklch(0.922 0 0)` in light mode and `oklch(1 0 0 / 15%)` in dark mode. `--border` remains the surface/divider role, and `--ring` owns the stronger focus indicator. No extra border variable or component opacity is needed. Resting borders have no blanket 3:1 requirement in this palette; focus retains its separate tested 3:1 contract. When rebranding, review resting, focused and invalid states on the actual surfaces; an application requiring stronger boundaries can override the existing `--input` role.
 
 tokens.json distinguishes 23 structural roots, advanced typography/status settings, and derived utility spellings. A utility is not another public variable. Keep overrides in one stylesheet at root or ThemeScope, without copying computed CSS into JavaScript.
 
@@ -15,8 +15,8 @@ surface, use Text/Value `type="inherit"` and Label `className="text-inherit"`;
 standalone typography keeps its documented defaults. Keep secondary, link, status
 and inverse roles explicit, and use a secondary text role instead of fading text
 with opacity. Component disabled props own dimming; an extra faded wrapper can
-multiply it. Brand colors alone do not guarantee input/focus contrast: retain the
-central `--input`/`--ring` roles or verify their replacements on every host surface.
+multiply it. Brand colors should preserve the shared resting `--input` palette
+and `--ring` focus role; review deliberate replacements on every host surface.
 
 The default `--radius` is 0.75rem (12px). One public root drives two shared
 roles; component owners choose the role, so ordinary callers add no radius class.
@@ -50,8 +50,8 @@ replacing individual components' owned corners.
   --radius: 0.75rem;
   --height-action: 2.5rem;
   --height-control: 2.5rem;
-  --surface-x: 1.25rem;
-  --surface-y: 1.25rem;
+  --surface-x: 1.5rem;
+  --surface-y: 1.5rem;
 }
 ```
 
@@ -65,9 +65,8 @@ under their intentionally tighter leading, so independently enlarged type can
 produce different fitted heights even with equal action/control roots. Check
 type size, leading and height roots together when exact custom pairing matters.
 
-Both surface roots default to 1.25rem. At a 16px root font and space-scale 1,
-ordinary surface insets are 20px, compact insets are 10px and large insets are
-36px. Page's default large gutters inherit that same recipe. Row insets,
+Both surface roots default to 1.5rem. At a 16px root font and space-scale 1,
+the xs/sm/md/lg surface tiers are 12/16/24/32px. Page's default large gutters inherit that same recipe. Row insets,
 control heights and copy gaps keep their independent roots.
 
 | Shared geometry | Root / derivation |
@@ -76,7 +75,7 @@ control heights and copy gaps keep their independent roots.
 | Native field text inset | `--control-x` times space-scale; icons/add-ons use shared derived clearance |
 | Collection inline inset | `--row-x` times space-scale |
 | Collection block inset | `--row-y` times density-scale; compact/comfortable use 0.75/1.25 multipliers |
-| Default / compact surfaces | `--surface-x` / `--surface-y`, times space-scale; compact uses half |
+| Surface tiers | `--surface-x` / `--surface-y`, times space-scale; xs/sm/md/lg use 1/2, 2/3, 1 and 4/3 |
 | Menu header/footer inline inset | Half surface-x plus row-x, then space-scale; no additional public token |
 
 Use discrete inset, density and size props for the component responsibility described in [composition](composition.md). CSS scales are independent continuous theme settings. Primary row text does not shrink to xs merely because a density is compact. Public Input and Command search retain normal desktop editable text; coarse-pointer devices use text-base at mobile and tablet widths. Typography components remain margin-free.

package/docs/consumer-skill/references/tokens.json

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "structural": [
     {
       "name": "--space-scale",
@@ -49,12 +49,12 @@
     },
     {
       "name": "--surface-x",
-      "default": "1.25rem",
+      "default": "1.5rem",
       "purpose": "Default inline inset for cards and multi-content surfaces."
     },
     {
       "name": "--surface-y",
-      "default": "1.25rem",
+      "default": "1.5rem",
       "purpose": "Default block inset for cards and multi-content surfaces."
     },
     {
@@ -561,30 +561,39 @@
       "py-row-y",
       "py-row-y-lg",
       "p-surface-xs",
+      "p-surface-sm",
       "p-surface",
       "p-surface-lg",
       "px-surface-xs",
+      "px-surface-sm",
       "px-surface",
       "px-surface-lg",
       "py-surface-xs",
+      "py-surface-sm",
       "py-surface",
       "py-surface-lg",
       "pt-surface-xs",
+      "pt-surface-sm",
       "pt-surface",
       "pt-surface-lg",
       "pb-surface-xs",
+      "pb-surface-sm",
       "pb-surface",
       "pb-surface-lg",
       "ps-surface-xs",
+      "ps-surface-sm",
       "ps-surface",
       "ps-surface-lg",
       "pe-surface-xs",
+      "pe-surface-sm",
       "pe-surface",
       "pe-surface-lg",
       "pl-surface-xs",
+      "pl-surface-sm",
       "pl-surface",
       "pl-surface-lg",
       "pr-surface-xs",
+      "pr-surface-sm",
       "pr-surface",
       "pr-surface-lg"
     ]

package/docs/consumer-skill/references/workflows.md

@@ -122,7 +122,8 @@ definitions; the app then chooses appropriate destination focus.
 Use `Page` from `themelia-react-ui/layout/page` for the record route's identity,
 back navigation, content bounds, commands and section tabs. Pass the record's
 main command as `header.primaryAction`, supporting commands as
-`header.secondaryActions` and sections as `header.tabs`; one status badge goes in
+`header.secondaryActions` and separately selected/routed sections as `header.tabs`;
+continuous sections can stay in the body. One status badge goes in
 `header.titleBadges`. `PageHeader` serves a custom shell; `PageActions` is
 deprecated. The [layout recipe](../examples/app-layout.tsx) demonstrates that
 route boundary; the [detail recipe](../examples/detail.tsx) demonstrates the

package/docs/consumer-skill/scripts/composition-schema.d.mts

@@ -0,0 +1,2 @@
+/** Pure metadata validator shared by the preview and dependency-free consumer tools. */
+export function validateMappings(value: unknown): unknown[];

package/docs/consumer-skill/scripts/composition-schema.mjs

@@ -0,0 +1,32 @@
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const fail = (condition, message) => { if (!condition) throw new Error(`Invalid composition mapping: ${message}`); };
+const name = value => typeof value === 'string' && /^[A-Za-z][A-Za-z0-9]*$/.test(value);
+const uniqueList = (value, valid, maximum) => Array.isArray(value) && value.length <= maximum && value.every(valid) && new Set(value).size === value.length;
+const scalar = value => value === null || typeof value === 'boolean' || (typeof value === 'string' && value.length <= 500) || (typeof value === 'number' && Number.isFinite(value));
+const kinds = ['shell', 'page', 'layout', 'surface', 'content', 'workflow'];
+const placements = ['region', 'cell', 'overlay'];
+const surfaces = ['none', 'parent', 'self', 'variant'];
+
+/** One literal metadata shape shared by authored catalogue and copied tools. */
+export function validateMappings(mappings) {
+ fail(Array.isArray(mappings) && mappings.length <= 64, 'expected an array of at most 64 mappings');
+ for (const mapping of mappings) {
+  fail(record(mapping), 'expected a plain mapping object');
+  fail(Object.keys(mapping).every(key => ['symbol', 'roles', 'kind', 'placement', 'surface', 'slots', 'props', 'routeSlot'].includes(key)), 'unknown mapping field');
+  fail(typeof mapping.symbol === 'string' && /^[A-Z][A-Za-z0-9]*$/.test(mapping.symbol), 'symbol must be an exact public component name');
+  fail(uniqueList(mapping.roles, value => typeof value === 'string' && /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value), 8) && mapping.roles.length > 0, `${mapping.symbol}: use 1..8 distinct kebab-case roles`);
+  fail(kinds.includes(mapping.kind), `${mapping.symbol}: invalid kind`);
+  fail(placements.includes(mapping.placement), `${mapping.symbol}: invalid placement`);
+  fail(surfaces.includes(mapping.surface), `${mapping.symbol}: invalid surface`);
+  if (mapping.slots !== undefined) fail(uniqueList(mapping.slots, name, 16), `${mapping.symbol}: invalid or duplicate slots`);
+  if (mapping.routeSlot !== undefined) fail(mapping.kind === 'shell' && name(mapping.routeSlot) && (mapping.slots ?? []).includes(mapping.routeSlot), `${mapping.symbol}: routeSlot must name a mapped shell insertion slot`);
+  if (mapping.props !== undefined) {
+   fail(record(mapping.props) && Object.keys(mapping.props).length <= 16, `${mapping.symbol}: props must be a small literal object`);
+   for (const [key, value] of Object.entries(mapping.props)) {
+    fail(/^[A-Za-z][\w-]*$/.test(key) && !['__proto__', 'constructor', 'prototype'].includes(key) && scalar(value), `${mapping.symbol}: invalid literal prop ${key}`);
+    fail(!(mapping.slots ?? []).includes(key), `${mapping.symbol}: ${key} cannot be both an insertion slot and a fixed prop`);
+   }
+  }
+ }
+ return mappings;
+}

package/docs/consumer-skill/scripts/composition.mjs

@@ -0,0 +1,198 @@
+import {validateIndex} from './discovery.mjs';
+import {validateComponentContracts} from './inspection.mjs';
+import {validateMappings} from './composition-schema.mjs';
+
+const fail = (condition, message) => { if (!condition) throw new Error(message); };
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const unique = values => [...new Set(values)].sort(compare);
+const patterns = ['record-detail', 'collection', 'edit', 'analytics', 'embedded'];
+const roleKey = value => value.trim().toLowerCase().replace(/\s+/g, '-');
+const identity = mapping => `${mapping.import}#${mapping.symbol}`;
+
+function publicProps(contract, contracts) {
+ const inherited = contracts.nativeProfiles[contract.inheritedProfile] ?? {};
+ return Object.assign(Object.create(null), Object.fromEntries(Object.entries(inherited).map(([key, value]) => [key, typeof value === 'string' ? contracts.nativeProperties[value] : value])), contract.props);
+}
+
+/** Resolve authored rows against the same qualified contracts as API inspection. */
+export function validateCompositionMappings(index, contracts) {
+ validateIndex(index);
+ validateComponentContracts(contracts, index);
+ const byContract = new Map(contracts.contracts.map(contract => [identity(contract), contract]));
+ const seen = new Set();
+ const mappings = [];
+ for (const family of index.families) for (const guidance of family.guidance) {
+  for (const mapping of validateMappings(guidance.composition?.mappings ?? [])) {
+   const key = `${family.import}#${mapping.symbol}`;
+   fail(!seen.has(key), `Duplicate composition mapping: ${key}`); seen.add(key);
+   fail(family.symbols.includes(mapping.symbol), `Composition mapping is not a public export: ${key}`);
+   fail(!Object.hasOwn(family.deprecated ?? {}, mapping.symbol), `Composition mapping uses a deprecated export: ${key}`);
+   const contract = byContract.get(key);
+   fail(contract, `Composition mapping has no callable component contract: ${key}`);
+   const props = publicProps(contract, contracts);
+   for (const slot of mapping.slots ?? []) {
+    fail(props[slot], `Unknown composition slot ${slot} on ${key}`);
+    fail(/\b(?:ReactNode|ReactElement)\b|JSX\.Element/.test(props[slot].type), `Composition slot ${slot} on ${key} is not a documented React insertion prop`);
+   }
+   for (const prop of Object.keys(mapping.props ?? {})) fail(props[prop], `Unknown composition prop ${prop} on ${key}`);
+   const recipes = (family.recipes ?? []).filter(recipe => recipe.symbols.includes(mapping.symbol));
+   mappings.push({...mapping, import: family.import, declaration: family.declaration, optionalPeers: family.optionalPeers,
+    guidance, nextReads: {declaration: family.declaration,
+     inspect: `node scripts/inspect-component.mjs ${mapping.symbol} --import ${family.import}`,
+     references: unique([...(family.references ?? []), ...recipes.flatMap(recipe => recipe.references)]),
+     examples: recipes.map(({file, exports, optionalPeers = []}) => ({file, exports, optionalPeers})),
+    }});
+  }
+ }
+ return mappings.sort((a, b) => compare(identity(a), identity(b)));
+}
+
+function validateOptions(options) {
+ const value = {...options, main: options.main ?? [], aside: options.aside ?? [], limit: options.limit ?? 3};
+ fail(Number.isInteger(value.limit) && value.limit >= 1 && value.limit <= 10, 'Invalid limit: use 1..10');
+ fail(Number(value.roles === true) + Number(value.role !== undefined) + Number(value.pattern !== undefined) === 1, 'Choose one mode: --roles, --role or --pattern');
+ for (const region of ['main', 'aside']) fail(Array.isArray(value[region]) && value[region].length <= 24 && value[region].every(need => typeof need === 'string' && need.trim().length > 0 && need.length <= 300), `Invalid ${region} needs; use up to 24 explicit role tags or qualified selectors`);
+ if (value.pattern !== undefined) {
+  fail(patterns.includes(value.pattern), `Invalid pattern: choose ${patterns.join(', ')}`);
+  fail(value.main.length + value.aside.length > 0, 'A plan needs at least one --main or --aside requirement');
+ } else {
+  fail(value.main.length + value.aside.length === 0, 'Main/aside needs require --pattern');
+  if (value.role !== undefined) fail(typeof value.role === 'string' && value.role.trim().length > 0, 'A nonempty role is required');
+ }
+ if (value.parent !== undefined) fail(value.pattern === 'embedded' && typeof value.parent === 'string' && /^[A-Z][A-Za-z0-9]*$/.test(value.parent), '--parent must be an exact component name with --pattern embedded');
+ if (value.publicImport !== undefined) fail(value.parent !== undefined && typeof value.publicImport === 'string' && value.publicImport.length > 0, '--import qualifies an explicit embedded --parent');
+ return value;
+}
+
+export function parseCompositionArguments(args) {
+ const options = {main: [], aside: [], limit: 3};
+ const seen = new Set();
+ for (let index = 0; index < args.length; index++) {
+  const arg = args[index];
+  fail(['--roles', '--role', '--pattern', '--main', '--aside', '--parent', '--import', '--limit'].includes(arg), `Unknown argument: ${arg}`);
+  fail(['--main', '--aside'].includes(arg) || !seen.has(arg), `Duplicate argument: ${arg}`); seen.add(arg);
+  if (arg === '--roles') { options.roles = true; continue; }
+  const value = args[++index];
+  fail(typeof value === 'string' && value.trim() && !value.startsWith('--'), `Missing value for ${arg}`);
+  if (arg === '--main' || arg === '--aside') options[arg.slice(2)].push(value.trim());
+  else if (arg === '--limit') { fail(/^[1-9]\d*$/.test(value), 'Invalid limit: use 1..10'); options.limit = Number(value); }
+  else options[arg === '--import' ? 'publicImport' : arg.slice(2)] = value.trim();
+ }
+ validateOptions(options);
+ return options;
+}
+
+function candidate(mapping) {
+ return {import: mapping.import, symbol: mapping.symbol, roles: mapping.roles, kind: mapping.kind,
+  placement: mapping.placement, surface: mapping.surface, slots: mapping.slots ?? [], props: mapping.props ?? {},
+  ...(mapping.routeSlot ? {routeSlot: mapping.routeSlot} : {}),
+  optionalPeers: mapping.optionalPeers, applicationOwns: mapping.guidance.appOwned,
+  chooseWhen: mapping.guidance.chooseWhen, avoidWhen: mapping.guidance.avoidWhen, nextReads: mapping.nextReads};
+}
+
+/** Exact roles and explicit regions yield an advisory structure, never guessed APIs. */
+export function mapComposition(index, contracts, rawOptions) {
+ const options = validateOptions(rawOptions);
+ const mappings = validateCompositionMappings(index, contracts);
+ const base = {package: index.package, version: index.version, advisory: true,
+  baselinePeers: unique((index.peers ?? []).filter(peer => !peer.optional).map(peer => peer.name)),
+  peerScope: 'requiredPeers covers selected-family optional peers; baselinePeers apply to every consumer'};
+ const matches = request => request.includes('#')
+  ? mappings.filter(mapping => identity(mapping) === request)
+  : /^[A-Z][A-Za-z0-9]*$/.test(request) || /[\/#]/.test(request) ? []
+   : mappings.filter(mapping => mapping.roles.includes(roleKey(request)));
+ if (options.roles) {
+  const roles = unique(mappings.flatMap(mapping => mapping.roles)).map(role => ({role, owners: mappings.filter(mapping => mapping.roles.includes(role)).length}));
+  return {...base, mode: 'roles', total: roles.length, roles};
+ }
+ if (options.role !== undefined) {
+  const found = matches(options.role);
+  return {...base, mode: 'lookup', status: found.length ? 'mapped' : 'unresolved', query: options.role, total: found.length,
+   results: found.slice(0, options.limit).map(candidate), omittedResults: Math.max(0, found.length - options.limit)};
+ }
+
+ const unresolved = [], warnings = [], selected = [];
+ const node = (mapping, decision = 'none') => {
+  selected.push(mapping);
+  return {import: mapping.import, symbol: mapping.symbol, kind: mapping.kind, surface: mapping.surface,
+   surfaceDecision: decision, props: {...mapping.props}, slots: {}};
+ };
+ const issue = (request, region, reason, found = []) => unresolved.push({request, region, reason, totalCandidates: found.length, candidates: found.slice(0, options.limit).map(candidate)});
+ const resolve = (request, region, found = matches(request)) => {
+  if (found.length !== 1) { issue(request, region, found.length ? 'Role is ambiguous; select an exact import#symbol or a more specific mapped role.' : 'No exact mapping covers this requirement. Use --roles or the component finder; do not infer an API.', found); return null; }
+  return found[0];
+ };
+ const insertion = (mapping, slot, request, region) => {
+  if (!(mapping.slots ?? []).includes(slot)) { issue(request, region, `${mapping.symbol} has no mapped ${slot} insertion slot. Inspect its API rather than nesting into an invented prop.`, [mapping]); return false; }
+  return true;
+ };
+ const structure = (role, kind, slots, region = 'structure') => {
+  const mapping = resolve(role, region);
+  if (!mapping) return null;
+  if (mapping.kind !== kind || mapping.placement !== 'region' || (kind === 'surface' && mapping.surface !== 'self')) {
+   issue(role, region, `The ${role} mapping does not establish the required ${kind} boundary. Inspect the authored mapping.`, [mapping]); return null;
+  }
+  if (!slots.every(slot => insertion(mapping, slot, role, region))) return null;
+  return mapping;
+ };
+ let rootMapping = null, root = null, host = null, mainSlot = 'main', asideSlot = 'aside';
+ if (options.pattern === 'embedded') {
+  if (options.parent) {
+   rootMapping = resolve(options.parent, 'structure', mappings.filter(mapping => mapping.symbol === options.parent && (!options.publicImport || mapping.import === options.publicImport)));
+   if (rootMapping && rootMapping.placement !== 'region') { issue(options.parent, 'structure', 'This parent belongs to a renderer or overlay boundary, not a subject region.', [rootMapping]); rootMapping = null; }
+   if (rootMapping) {
+    root = host = node(rootMapping, rootMapping.surface === 'self' ? 'existing-surface' : rootMapping.surface === 'variant' ? 'inspect-variant-host' : 'existing-host');
+    mainSlot = (rootMapping.slots ?? []).includes('children') ? 'children' : 'main';
+    if (rootMapping.surface === 'variant') warnings.push({code: 'variant-host-surface', message: `${rootMapping.symbol} may already provide framing in its current variant or state. Inspect its contract and existing ancestors before composing another surface.`});
+   }
+  } else warnings.push({code: 'host-ownership-unverified', message: 'Embedded requirements retain the caller\'s host. Confirm its insertion slot, framing, padding and gaps; no Page or new surface was added.'});
+ } else {
+  rootMapping = structure('route', 'page', ['children']);
+  if (rootMapping) root = host = node(rootMapping);
+  mainSlot = 'children';
+  if (rootMapping && options.aside.length) {
+   const layout = structure('main-support-layout', 'layout', ['main', 'aside']);
+   if (layout && insertion(rootMapping, 'children', 'main-support-layout', 'structure')) {
+    host = node(layout); root.slots.children = [host]; rootMapping = layout; mainSlot = 'main';
+   } else host = null;
+  }
+ }
+
+ let resolved = 0;
+ const regions = {main: [], aside: []};
+ for (const region of ['main', 'aside']) for (const request of options[region]) {
+  const mapping = resolve(request, region);
+  if (!mapping) continue;
+  if (mapping.placement !== 'region') { issue(request, region, mapping.placement === 'cell' ? 'This owner belongs in a table/collection renderer, not directly in a subject region.' : 'This owner belongs at the app/feature overlay boundary; open it through callbacks.', [mapping]); continue; }
+  const slot = region === 'main' ? mainSlot : asideSlot;
+  if (['page', 'shell'].includes(mapping.kind) && !(options.pattern === 'embedded' && rootMapping?.routeSlot === slot && mapping.kind === 'page')) { issue(request, region, 'A page or shell is not an independent content subject. Only an explicit route-host slot may receive a Page; keep one route title/gutter owner.', [mapping]); continue; }
+  if ((!host && options.pattern !== 'embedded') || (!host && options.parent)) { issue(request, region, 'The structural owner is unresolved, so this requirement has not been placed.', [mapping]); continue; }
+  if (host && !insertion(rootMapping, slot, request, region)) continue;
+  let child;
+  const insideSurface = rootMapping?.surface === 'self';
+  if (mapping.surface === 'parent' && host && !insideSurface && options.pattern !== 'embedded') {
+   const frame = structure('subject-surface', 'surface', ['children'], region);
+   if (!frame) continue;
+   child = node(frame, 'recommended-frame');
+   child.slots.children = [node(mapping, 'uses-parent')];
+  } else {
+   child = node(mapping, mapping.surface === 'self' ? 'owns-surface' : mapping.surface === 'parent' ? insideSurface ? 'uses-parent' : 'caller-surface-unverified' : mapping.surface === 'variant' ? 'inspect-variant' : 'none');
+  }
+  if (mapping.surface === 'variant') warnings.push({code: 'variant-surface', request, region, message: `${mapping.symbol} owns framing only in some variants or states. Inspect its contract before adding a surface.`});
+  if (mapping.surface === 'parent' && options.pattern === 'embedded' && host && !insideSurface) warnings.push({code: 'host-surface-unverified', request, region, message: 'The explicit host does not establish a known surface boundary. Confirm its ancestors before adding framing; no extra Card was added.'});
+  if (insideSurface && mapping.surface === 'self') warnings.push({code: 'nested-surface-review', request, region, message: `${mapping.symbol} already owns a surface. Review its supported embedded variant or use an unframed host; no props were guessed.`});
+  else if (rootMapping?.surface === 'variant' && mapping.surface === 'self') warnings.push({code: 'nested-surface-review', request, region, message: `${mapping.symbol} owns a surface and its host may also frame it. Inspect both variants before keeping nested surfaces; no embedded props were guessed.`});
+  regions[region].push(child);
+  if (host) (host.slots[slot] ??= []).push(child);
+  resolved++;
+ }
+ const requested = options.main.length + options.aside.length;
+ const selectedMappings = [...new Map(selected.map(mapping => [identity(mapping), mapping])).values()];
+ if (options.pattern === 'edit') warnings.push({code: 'native-form-required', message: 'Provide the application-owned native form, validation and awaited submit/save/discard lifecycle. This structural plan does not create form state or transport.'});
+ return {...base, mode: 'plan', status: unresolved.length ? resolved ? 'partial' : 'unresolved' : 'mapped', pattern: options.pattern, patternScope: 'structural-context-only',
+  tree: root, ...(root ? {} : {regions}), coverage: {requested, resolved, unresolved: requested - resolved}, unresolved,
+  requiredPeers: unique(selectedMappings.flatMap(mapping => mapping.optionalPeers)),
+  applicationOwns: unique(selectedMappings.flatMap(mapping => mapping.guidance.appOwned)), warnings,
+  nextReads: selectedMappings.map(mapping => ({import: mapping.import, symbol: mapping.symbol, ...mapping.nextReads})),
+  limits: 'This is an advisory role/slot map. Supply application data, state, callbacks and content; inspect APIs and execute visual/interaction checks before delivery.'};
+}