themelia-react-ui 2.0.3 → 2.0.5

package/docs/consumer-skill/references/view-craft.md

@@ -0,0 +1,153 @@
+# View craft
+
+Themelia already sets type, colour, spacing and surfaces. Craft is what remains:
+deciding what a view shows, how much emphasis each part gets and how the parts
+are arranged, so the user understands the screen at a glance. Each rule below is
+a decision you can explain and check on the rendered result. Most improvements
+remove something.
+
+Start from the [data brief](data-reading.md#write-the-data-brief). Owner
+selection, surfaces and inset ownership follow
+[screen decisions](screen-decisions.md); this reference does not restate them.
+
+## One focal point
+
+Each view, and each region in it, has one thing the eye reaches first: the
+figure that answers the question, the subject's identity and state, or the queue
+of records that need action. Choose it from the brief. When two things compete,
+demote one: a smaller text role, secondary tone, or a supporting region.
+
+Check it by looking at a reduced screenshot: the focal point is still the
+strongest mass. It sits in the first viewport at both 390 and 1440 wide.
+
+## Spend emphasis on purpose
+
+Emphasis works only by contrast, so it is a budget:
+
+- **Commands.** One solid primary command per page or surface. Other commands
+  are outline or ghost, or sit in the same scope's overflow menu.
+- **Text.** At most three levels in a region: title (`Heading`), body and values
+  (`Text`), supporting copy (`Text` secondary, smaller size). A fourth level
+  signals a hierarchy problem, not a missing style.
+- **Tone.** `success`, `warning`, `destructive` and `info` mark a status that
+  changes what the user does. Kinds, categories and counts stay neutral. When
+  everything is coloured, nothing reads as status.
+- **Size.** One hero figure size per region; peer figures share one size.
+
+Adding emphasis in one place means removing it from another.
+
+## Choose the encoding from the fact
+
+| The fact | Encoding | Owner family (confirm with the finder and inspector) |
+| --- | --- | --- |
+| A figure the user must judge | Figure with its baseline delta; a sparkline when the path matters | `Metric`, `MetricTrendChip`, `MetricSparkline`; `MetricComparison` for current versus previous |
+| Several peer figures for one period | One strip, not a grid of identical cards | `MetricBar`; `MetricGrid` with a quiet variant inside one surface |
+| A series whose shape is the message | Chart with one emphasised series and minimal axes | `ChartCard` with Recharts children |
+| Part of a whole, or use against a limit | Bar with the figure as its label | `Progress`, `UsageCard` |
+| Facts about one record | Label and value list; one inline line for two to four short facts | `MetadataList` (inline or stacked), `InlineStat` |
+| A lifecycle with a current stage | Steps with only the current stage emphasised | `StepsHorizontal`, `Timeline` |
+| Events and history | Newest first, grouped by day | `Timeline`, `features/activities` |
+| Many records compared on shared columns | Table whose columns are what users compare or sort | `DataTable`, `DataView` |
+| Records that differ in shape | List rows: identity, one line of context, state, action | `Item`, `ItemGroup` |
+| A money ledger | Right-aligned amounts, one rule above the grand total | `SummaryPanel` with `AmountRow`, `OrderSummary` |
+| Nothing to show yet | What is missing and the next action | `EmptyState` |
+
+Read [metrics and statistics](analytics.md) for the exact metric owner. A chart
+must answer a question you can write in one sentence; otherwise show the figure.
+Do not chart three values. Prefer a sparkline in a strip to a large chart that
+repeats what the figures already say.
+
+## Spend words carefully
+
+- Label a value only when it is ambiguous. A ledger amount needs "Total"; an
+  order number in a header does not need "Order number".
+- Do not repeat a column header inside its cells or a section title in each row.
+- State a unit once, in the header or the value.
+- A sentence fragment often reads better than three label and value pairs:
+  "2 of 3 shipped · 1 reserved at Plovdiv".
+- Omit zero and not-applicable counters, or collapse them into one "Nothing
+  outstanding" line.
+- Do not explain the interface on the page. A description states scope or
+  as-of time, not instructions.
+
+## Density follows the audience
+
+- **Queues** for operators: compact rows, more records per screen, identity,
+  state and amount; detail on open.
+- **Overviews**: fewer, larger figures with room around them, each answering a
+  question.
+- **Records**: the subject leads; evidence and history follow.
+
+Change global density through the provider and density roots described in
+[theming](theming.md). Do not shrink text roles to fit more data; remove
+low-value content first.
+
+## Rhythm groups content
+
+- Gaps grow outward: within a group, between groups, between sections. Equal
+  gaps everywhere mean nothing groups. Use `Stack` and `Grid` gap roles.
+- Few edges: peer regions share content start edges; numbers right-align on one
+  axis; labels share one axis.
+- Few frames: one `Card` per independent subject. Continuous sections of one
+  subject share one surface and are separated by space, not rules or nested
+  boxes.
+- Narrow widths keep the decision content first in reading order. Only data
+  tables that own horizontal scrolling may scroll sideways.
+
+## Numbers and copy
+
+- Numbers use tabular figures through the value primitives (`Money`, `Number`,
+  `Percent`, `Date`, `RelativeTime`) with one precision per column.
+- Recency reads as relative time with the exact date available; documents show
+  absolute dates.
+- A delta states direction and baseline: "↓ 0.9% vs September".
+- Sentence case everywhere. Buttons are a verb and an object ("Record payment").
+  Empty states say what is missing and what to do. Errors say what happened and
+  how to recover.
+
+## Modern patterns and their owners
+
+- **Overview.** A header with the period control, one figure strip (three to
+  five figures with deltas or sparklines), one chart answering the main
+  question, and a "needs attention" list that links to records. Not a wall of
+  identical cards.
+- **Index.** Search plus the work queues users actually work; rows lead with
+  identity and the deciding column; bulk actions appear with a selection;
+  export states how many rows match.
+- **Record.** The page header carries identity, status badges in `titleSuffix`,
+  one metadata line (date · channel · customer) and the primary command. The
+  main column holds the subject's working content, an aside holds context
+  (customer, payment, notes) and history comes last.
+- **Editing.** `InlineEdit` for one field; `ActionDrawer` for a focused
+  multi-field edit that keeps the record visible; `ActionDialog` for short
+  creation; `ConfirmDialog` for destructive commands.
+- **Progressive disclosure.** `Collapsible` or `Accordion` for evidence and
+  technical detail; overflow menus for rare commands.
+- **Loading.** Owners' loading states and `Skeleton` shaped like the content,
+  not spinners in empty boxes.
+
+Inspect each owner's declaration before using it; a pattern names a direction,
+not a prop list.
+
+## Anti-patterns seen in trials
+
+- A grid of identical metric cards whose figures have no baseline.
+- A facts card that repeats the header's identifier, status and date.
+- Every lifecycle counter on every line, zeros included.
+- Column headers repeated in cells; units on every value.
+- Filler cards added to balance a column's whitespace.
+- Decorative icons on titles, rows or badges; tinted icon tiles.
+- Status tones on kinds or categories; three badges on one row saying related
+  things.
+- A storefront hero image inside an operational editor.
+- A framed box inside a card for sub-content that is not a distinct object.
+- A chart of three values, or a chart whose question cannot be stated.
+- Prose explaining what the screen does.
+
+## When an owner limits the view
+
+When an owner cannot express the hierarchy the data needs, compose its public
+parts or app markup with token-backed utilities
+([domain structures](domain-structures.md)) and report the gap by owner and
+prop. Never override anatomy classes, add colours or add tokens to make a view
+look designed.

package/docs/consumer-skill/references/view-spec.md

@@ -0,0 +1,73 @@
+# View spec
+
+Write this before JSX for a new view or a substantial redesign. Keep it short
+enough to read in a minute; it is a working note, not an approval document. Every
+line should change a later decision. Save it beside the app's other design notes
+so a reviewer can compare the result with the intent.
+
+```md
+# <View name> (<route>)
+
+## Decision
+<who> decides <what>, <how often>. Success: <what they can do faster or with more confidence>.
+
+## Data brief
+<the data brief from data-reading.md>
+
+## Ranked information
+- Must (first viewport at 390 and 1440): …
+- Should (visible without interaction): …
+- Could (behind disclosure, overflow or a detail view): …
+- Omit: … (why: zero, not applicable, duplicated elsewhere, not used for this decision)
+
+## Focal point
+<the one element the eye reaches first, and why>
+
+## Wireframes
+1440:
+┌──────────────────────────────────────────────┐
+│ Title · status          [secondary] [Primary]│
+│ meta · meta · meta                           │
+├──────────────────────────────┬───────────────┤
+│ main subject                 │ context       │
+│ …                            │ …             │
+└──────────────────────────────┴───────────────┘
+
+390:
+┌────────────────────┐
+│ Title · status     │
+│ [Primary]   [⋯]    │
+│ main subject       │
+│ context            │
+└────────────────────┘
+
+## Encodings
+| Fact | Encoding | Why |
+| --- | --- | --- |
+
+## Owners
+| Region | Owner | Exact import | Verified with |
+| --- | --- | --- | --- |
+(found with find-components.mjs and map-composition.mjs; props checked with inspect-component.mjs)
+
+## Commands
+<command: scope, emphasis (primary, secondary, overflow), eligibility and disabled reason>
+
+## States
+Loading: … Empty: … Error and retry: … Accepted: … Long text and narrow parent: …
+
+## Open questions and data gaps
+…
+```
+
+## Notes
+
+- Draw wireframes in text so they survive any editor and diff. Boxes show
+  regions and order, not pixel sizes.
+- The ranked list is where most quality comes from. If "must" has more than
+  five items, the decision is not specific enough yet.
+- Fill "Owners" only after running the finder and inspector. An owner that does
+  not fit is recorded with the reason, and the region becomes app markup over
+  public parts.
+- After building, score the result with the [critique rubric](critique-rubric.md)
+  and note any departure from this spec with its reason.

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

@@ -122,8 +122,15 @@ 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.titleBadges`. `PageHeader` serves a custom shell; `PageActions` is
+`header.secondaryActions` and separately selected/routed sections as `header.tabs`;
+continuous sections can stay in the body. One status badge goes in
+`header.slots.titleSuffix` as a composed Badge. Place supporting facts in
+`header.slots.afterDescription` as a MetadataList when useful. The four header
+slots (`beforeTitle`, `titleSuffix`, `afterDescription`, `actions`) accept content
+or a callback receiving `{ renderLink, defaultContent }`; an actions callback
+can wrap or return `defaultContent` to retain responsive commands. A replacement
+owns its behavior. Below 40rem of actual header width, all commands, including
+primary, share one More actions trigger. `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
 record route and an independently framed subject with MetadataList and value

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

@@ -184,6 +184,25 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (ts.isJsxElement(element.parent)) element.parent.children.forEach(collect);
     return found;
   };
+  // Static region children only: inspect known passive wrappers and providers,
+  // never assume an opaque app component renders its lexical children.
+  const regionElements = (opening, deep = false) => {
+    const found = [];
+    const collect = (child, scope = opening, subject) => {
+      if (ts.isJsxFragment(child)) { child.children.forEach(item => collect(item, scope, subject)); return; }
+      if (ts.isJsxExpression(child)) { const value = resolve(child.expression); if (value) collect(value, scope, subject); return; }
+      const node = ts.isJsxElement(child) ? child.openingElement : ts.isJsxSelfClosingElement(child) ? child : undefined;
+      if (!node) return;
+      const owner = ownerFor(node.tagName);
+      found.push({node, owner, tag: node.tagName.getText(source), scope, subject});
+      const provider = isOwner(owner, 'features/filters', ['FilterProvider']);
+      const card = isOwner(owner, 'base/cards', ['Card', 'SmartCard']);
+      // Cards delimit independent subjects; providers delimit query state.
+      if (deep && ts.isJsxElement(child) && (/^(div|section|form)$/.test(node.tagName.getText(source)) || isOwner(owner, 'base/structure', ['Stack', 'Grid', 'AdaptiveGrid', 'GridCell']) || card || provider)) child.children.forEach(item => collect(item, provider ? node : scope, card ? node : subject));
+    };
+    if (ts.isJsxElement(opening.parent)) opening.parent.children.forEach(child => collect(child));
+    return found;
+  };
   const renderedText = element => ts.isJsxElement(element) ? element.children.map(child => ts.isJsxText(child) ? child.text : ts.isJsxExpression(child) ? literal(child.expression) ?? '' : '').join(' ').trim() : '';
   const slotBadge = expression => {
     const node = resolve(expression);
@@ -342,7 +361,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       if (modalRole || scrim) add(node, 'raw-overlay-primitive', 'warning', `A hand-rolled ${modalRole ? 'dialog' : 'full-screen layer'} must own focus, dismissal, pending state and theming itself. ${overlayRemedy}`);
       if (/^(?:input|textarea)$/.test(node.tagName.getText(source))) {
         const props = new Map(attributes(node));
-        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(value=>replacesSharedRadius(value,'inner'))) add(node,'shared-radius','error','Native editable controls follow bounded rounded-inner; change the global theme root, not per-field corners.');
+        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(value=>replacesSharedRadius(value,'radius'))) add(node,'shared-radius','error','Native editable controls follow bounded rounded-radius; change the global theme root, not per-field corners.');
         if (props.has('style') && properties(props.get('style')).some(([name])=>radiusProperty.test(name))) add(node,'shared-radius','error','Native editable corners belong to the global radius root, not inline styles.');
       }
       if (nativeDisplayNames.test(node.tagName.getText(source))) {
@@ -375,7 +394,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       const focusDrift = focusRingDrift(tokens);
       if ((anatomy || forwarder && name === 'contentClassName') && classes.some(value => paddingClass.test(value))) add(node, 'surface-padding', 'error', `${owner.symbol}: use inset/type/density and public regions; padding overrides replace owned anatomy.`);
       if (control && name === 'className' && classes.some(value => fixedControlClass.test(value))) add(node, 'control-anatomy', 'error', `${owner.symbol}: use its size/variant props; preserve shared control height, inset, corners and typography.`);
-      if ((name === 'className' && (control || sharedCorners) || name === 'contentClassName' && forwarder) && classes.some(value=>replacesSharedRadius(value, control && name === 'className' ? 'inner' : cornerRole(family,owner.symbol)))) add(node,'shared-radius','error',`${owner.symbol}: outer shells use rounded-radius; controls and collection rows use bounded rounded-inner. Preserve the owning role and joined-edge resets.`);
+      if ((name === 'className' && (control || sharedCorners) || name === 'contentClassName' && forwarder) && classes.some(value=>replacesSharedRadius(value, control && name === 'className' ? 'radius' : cornerRole(family,owner.symbol)))) add(node,'shared-radius','error',`${owner.symbol}: outer shells use rounded-surface; controls and collection rows use bounded rounded-radius. Preserve the owning role and joined-edge resets.`);
       if (display && classes.some(addsCopyMargin)) add(node,'copy-margin','error',`${owner.symbol}: typography is margin-free; use textGap on the headed owner or gap on Stack/Grid.`);
       if (textContent && name === 'className' && tokens.some(token=>fadedText(token)||textOpacityDrift(token))) add(node,'faded-text','error',`${owner.symbol}: use its semantic type instead of adding an opacity tier to the text. Presence endpoints and shared disabled state remain valid.`);
       if ((control || family === 'buttons' && owner.symbol === 'TextButton') && name === 'className' && focusDrift.length) add(node, 'focus-ring-recipe', 'error', `${owner.symbol}: keep the shared focus indicator (a ring-3 halo of ring-ring/50 around a full-strength ring edge); ${[...new Set(focusDrift)].join(', ')} redraws it.`);
@@ -404,6 +423,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     }
     if (isOwner(owner, 'base/feedback', ['Empty'])) add(node, 'reinvented-empty-state', 'warning', 'Empty exposes lower-level anatomy. Compare EmptyState from blocks/data-display for a routine no-data/no-results region; keep Empty when custom anatomy is required.');
     if (isOwner(owner, 'base/sheet', ['Sheet', 'SheetContent']) || isOwner(owner, 'base/display', ['Dialog', 'DialogContent', 'AlertDialog', 'AlertDialogContent'])) add(node, 'raw-overlay-primitive', 'warning', 'This lower-level modal needs application lifecycle coordination. Prefer ActionDialog, ConfirmDialog or ActionDrawer from features/overlays when their workflow fits.');
+    if (isOwner(owner, 'features/table', ['DataTable'])) {
+      const parent = parents.at(-1);
+      let ancestor = ts.isJsxOpeningElement(node) ? node.parent.parent : node.parent;
+      while (ancestor && !ts.isJsxElement(ancestor)) ancestor = ancestor.parent;
+      const directOwner = ancestor && ownerFor(ancestor.openingElement.tagName);
+      if (isOwner(directOwner, 'base/cards', ['Card', 'SmartCard']) && isOwner(parent?.owner, 'base/cards', ['Card', 'SmartCard']) && literal(parent.props.get('padding')) !== 'none' && !parent.unknownProps) add(node, 'uncontained-table-in-card', 'warning', 'DataTable owns its surface, topbar and edge-to-edge header band. Render it directly in Page or a layout region; a deliberate Card host must use padding="none".');
+    }
+    const routeOwner = isOwner(owner, 'layout/page', ['Page']) || isOwner(owner, 'layout', ['Page']);
+    if (routeOwner) {
+      const children = regionElements(node);
+      const contents = regionElements(node, true);
+      const tables = contents.filter(child => isOwner(child.owner, 'features/table', ['DataTable']));
+      for (const child of contents) if (isOwner(child.owner, 'features/filters', ['FilterLayout']) && tables.some(table => table.scope === child.scope && (!child.subject || table.subject === child.subject))) add(child.node, 'detached-filter-layout', 'warning', 'Pass FilterLayout into DataTable topbarContent with variant="compact", or use DataView so filters and table chrome share one surface.');
+      const hasAsideSlot = properties(props.get('slots'), false).some(([name]) => name === 'aside');
+      const onlyForms = children.length > 0 && children.every(child => child.tag === 'form' || isOwner(child.owner, 'base/forms', ['FormSection']));
+      if (onlyForms && !unknownProps && !['narrow', 'maxWidth', 'aside'].some(name => props.has(name)) && !hasAsideSlot) add(node, 'wide-single-column-form', 'warning', 'A single-column form should use Page narrow (48rem centered), an explicit maxWidth, or a supporting aside so fields do not stretch across the default route measure.');
+    }
     if (owner.symbol === 'Page' && literal(props.get('gutter')) === 'none' && !parents.some(parent => parent.framed)) add(node, 'page-gutter', 'warning', 'Page gutter="none" delegates inline padding to a real parent. PageViewport owns scrolling, not padding; verify the parent inset.');
     if (owner.symbol === 'Card' && framed && literal(props.get('padding')) === 'sm' && !parents.some(parent => parent.framed)) add(node, 'compact-card', 'warning', 'Standalone Card padding="sm" halves the normal inset. Omit padding for ordinary subjects; retain sm only for an intentional compact composition.');
     const peers = parents.findLast(parent => parent.structure);
@@ -432,7 +468,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
     const title = literal(props.get('title')) ?? literal(new Map(header).get('title'));
     if (title && parents.some(parent => parent.title === title)) add(node, 'duplicate-heading', 'warning', `The heading "${title}" repeats its ancestor. Keep one route/subject title unless a distinct task warrants repetition.`);
     const structure = owner.import === `${index.package}/base/structure` && Object.hasOwn(structureDefaults, owner.symbol);
-    return { framed, title, structure, cards: structure ? peerCards(node) : new Set(), smallGap: structure ? smallGap(props, owner.symbol, unknownProps) : false };
+    return { owner, props, unknownProps, framed, title, structure, cards: structure ? peerCards(node) : new Set(), smallGap: structure ? smallGap(props, owner.symbol, unknownProps) : false };
   }
   visit(source);
   return { findings, unresolved };

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', 'toolbar', '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,254 @@
+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}`;
+const stopWords = new Set(['and', 'for', 'the', 'with', 'from', 'into', 'show', 'list', 'page']);
+const roleTokens = value => value.toLowerCase().split(/[^a-z0-9]+/).filter(token => token.length > 2 && !stopWords.has(token)).map(token => token.length > 3 && token.endsWith('s') ? token.slice(0, -1) : token);
+
+/** Nearby mapped roles for a phrase that matched none. Hints only: the need stays unresolved. */
+function suggestRoles(mappings, request, limit = 5) {
+ if (/^[A-Z][A-Za-z0-9]*$/.test(request) || /[\/#]/.test(request)) return [];
+ const wanted = new Set(roleTokens(request));
+ return unique(mappings.flatMap(mapping => mapping.roles))
+  .map(role => ({role, shared: roleTokens(role).filter(token => wanted.has(token)).length}))
+  .filter(candidate => candidate.shared > 0)
+  .sort((a, b) => b.shared - a.shared || a.role.length - b.role.length || compare(a.role, b.role))
+  .slice(0, limit).map(candidate => candidate.role);
+}
+
+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);
+  const suggestions = found.length ? [] : suggestRoles(mappings, 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),
+   ...(suggestions.length ? {suggestedRoles: suggestions} : {})};
+ }
+
+ 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 = [], suggest = false) => {
+  // Only a phrase that matched no role gets hints; structural failures of a
+  // mapped role already name their candidates.
+  const suggestions = suggest ? suggestRoles(mappings, request) : [];
+  unresolved.push({request, region, reason, totalCandidates: found.length, candidates: found.slice(0, options.limit).map(candidate), ...(suggestions.length ? {suggestedRoles: suggestions} : {})});
+ };
+ 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. Retry with one of suggestedRoles when it names the same job, or use --roles or the component finder; do not infer an API.', found, !found.length); 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);
+   if (!options.aside.length && ['edit', 'record-detail'].includes(options.pattern)) {
+    const contract = contracts.contracts.find(contract => identity(contract) === identity(rootMapping));
+    if (publicProps(contract, contracts).narrow) root.props.narrow = true;
+   }
+  }
+  mainSlot = 'children';
+  if (rootMapping && options.aside.length && !(rootMapping.slots ?? []).includes('aside')) {
+   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: []};
+ const toolbars = [], placements = [], contextualized = new Set();
+ for (const region of ['main', 'aside']) for (const request of options[region]) {
+  const mapping = resolve(request, region);
+  if (!mapping) continue;
+  if (mapping.placement === 'toolbar') { toolbars.push({mapping, request, region}); 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.`});
+  placements.push({mapping, child, region, slot});
+  regions[region].push(child);
+  if (host) (host.slots[slot] ??= []).push(child);
+  resolved++;
+ }
+ // Toolbars are placed after subjects so request order cannot affect the tree.
+ // FilterLayout's context and the table seam are both authored, validated APIs.
+ for (const {mapping, request, region} of toolbars) {
+  const targets = placements.filter(item => item.region === region && item.mapping.roles.includes('comparison-table') && (item.mapping.slots ?? []).includes('topbarContent'));
+  if (targets.length !== 1) { issue(request, region, 'A toolbar needs exactly one mapped comparison table with a topbarContent slot in this region.', targets.map(item => item.mapping)); continue; }
+  const target = targets[0];
+  let provider;
+  if (mapping.symbol === 'FilterLayout') {
+   const contexts = mappings.filter(row => row.import === mapping.import && row.symbol === 'FilterProvider' && row.roles.includes('filter-context'));
+   if (contexts.length !== 1 || contexts[0].kind !== 'layout' || contexts[0].placement !== 'region' || !(contexts[0].slots ?? []).includes('children')) {
+    issue(request, region, 'FilterLayout needs its mapped FilterProvider context with a children insertion contract.', contexts); continue;
+   }
+   provider = contexts[0];
+  }
+  const toolbar = node(mapping, 'uses-parent');
+  (target.child.slots.topbarContent ??= []).push(toolbar);
+  if (provider && !contextualized.has(target.child)) {
+   contextualized.add(target.child);
+   const wrapped = node(provider, 'context-provider');
+   wrapped.slots.children = [target.child];
+   const replace = children => { const position = children.indexOf(target.child); if (position >= 0) children[position] = wrapped; };
+   replace(regions[region]);
+   if (host) replace(host.slots[target.slot] ?? []);
+   // Keep subsequent toolbar insertion addressed to the table, not its context.
+  }
+  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.'};
+}