themelia-react-ui 2.0.6 → 3.0.0

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

@@ -122,11 +122,13 @@ routes, constrain only a form panel with Container maxWidth="md" gutter="none";
 `dynamic-page-measure` warns about expressions that can resize the route header
 along with the body. Deliberate responsive sizing remains valid. These contextual
 warnings follow qualified import bindings; unrelated same-name components are
-not evidence. Deprecated resource shells use the existing deprecated-owner
-warning and direct new routes to Page.
-Buttons placed in a Page or PageHeader `actions` region warn as well: pass
+not evidence. The resource shells were removed in 3.0: importing one is an
+unknown-symbol error, and new routes use Page.
+Buttons placed in a header's `actions` region (AsideNavShell,
+WorkspaceRecordHeader or PageHeading) warn as well: pass
 commands as `primaryAction` and ordered `secondaryActions` so the header owns
-their emphasis, size and overflow. Non-command controls stay valid there.
+their emphasis, size and overflow. Non-command controls stay valid there; Page
+takes them in `toolbar`.
 For PageHeader's `slots.actions`, wrapping or returning the callback's
 `defaultContent` retains that command behavior; a full replacement owns its
 keyboard, overflow and action semantics. Inspect the compact menu below 40rem of

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

@@ -25,10 +25,10 @@ a simple facts subject does not require a custom component.
 | 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 → ChartCard with Recharts series and comparison 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 uses explicit maxWidth first, then narrow md (48rem), aside xl (80rem), otherwise lg (64rem). Settings navigation uses Page → SettingsShell → FormSection. 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).
+Page uses explicit maxWidth first, then narrow md (48rem), aside xl (80rem), otherwise lg (64rem). Settings navigation uses Page → AsideNavShell → FormSection. 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).
 
 Keep FilterLayout inside DataTable topbarContent with variant="compact" and showClearFilters, under FilterProvider; DataView is the complete alternative. Table owns its frame/topbar/header band and sits directly in the layout. A deliberate Card host uses padding="none" and a flat table. Fixed scope belongs in page context or tabs, independently of removable criteria.
 
-Headers carry one primary command and ordered secondary commands; below 40rem of header width all commands share one More actions trigger. Page header slots beforeTitle/titleSuffix/afterDescription/actions accept content or callbacks with {renderLink, defaultContent}. Compose status and facts with Badge/MetadataList; wrap or return actions defaultContent to retain the command row. Compatible direct actions add non-command controls. 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.
+Headers carry one primary command and ordered secondary commands; below 40rem of header width all commands share one More actions trigger. Page header slots beforeTitle/titleSuffix/afterDescription/actions accept content or callbacks with {renderLink, defaultContent}. Compose status and facts with Badge/MetadataList; wrap or return actions defaultContent to retain the command row. Non-command controls go in Page toolbar. 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

@@ -56,7 +56,7 @@ Action and editable-control heights are separate roles; keep roots equal for adj
 Control heights are nominal floors when custom typography needs more room.
 Native fields, Select and InputGroup frames fit their editable line plus the
 border, and cap vertical padding to the space remaining in the nominal height.
-The default 28/32/36px sizes (2rem roots, steps in eighths) and radius roles stay unchanged. Text actions grow
+The default sizes of about 30/34/38px (2.125rem roots, steps in eighths) and radius roles stay unchanged. Text actions grow
 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.

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

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "2.0.6",
+  "version": "3.0.0",
   "structural": [
     {
       "name": "--space-scale",
@@ -24,17 +24,17 @@
     },
     {
       "name": "--height-action",
-      "default": "2rem",
+      "default": "2.125rem",
       "purpose": "Default button and action-trigger height."
     },
     {
       "name": "--height-control",
-      "default": "2rem",
+      "default": "2.125rem",
       "purpose": "Default input, select, and field-control height."
     },
     {
       "name": "--control-x",
-      "default": "0.75rem",
+      "default": "0.875rem",
       "purpose": "Default inline padding for buttons and field controls."
     },
     {

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

@@ -130,8 +130,8 @@ slots (`beforeTitle`, `titleSuffix`, `afterDescription`, `actions`) accept conte
 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
+primary, share one More actions trigger. `PageHeader` serves a custom shell; `PageActions` was
+removed in 3.0. 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
 primitives. Decide whether the record needs that independent Card before nesting
@@ -141,11 +141,11 @@ scrolling only. App navigation, record loading/missing/error/retry, permissions,
 edit and delete callbacks remain application responsibilities.
 
 Use `WorkspaceLayout` from `themelia-react-ui/layout/workspace` when independently composed record header,
-sidebar/main/rail regions are needed; inspect `features/resource` for complete
-resource coordination. A single record does not automatically need either.
-Their headers (`WorkspaceRecordHeader`, `ResourceHeader` and the resource shells)
-take the same `primaryAction` and `secondaryActions` as Page; keep their
-`actions` for non-command controls.
+sidebar/main/rail regions are needed; `features/resource` keeps
+`ResourceActionBar`, `ResourceDetailsSection` and `ResourceEmptyState`. A single
+record does not automatically need either.
+`WorkspaceRecordHeader` takes the same `primaryAction` and `secondaryActions` as
+Page; keep its `actions` for non-command controls.
 Read [layout composition](composition.md#application-layouts) for boundary and
 parent-width behavior, then the exact selected declaration for its current props.
 

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

@@ -177,10 +177,10 @@ export function analyzeComposition(text, { filename, index, ts }) {
   const isOwner = (owner, suffix, names) => owner?.import === `${index.package}/${suffix}` && names.includes(owner.symbol);
   const framedOwner = (owner, props) => {
     if (props.has('surface') && (literal(props.get('surface')) === undefined || literal(props.get('surface')) === 'flat')) return false;
-    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'base/forms', ['FormSection']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'features/data-view', ['DataView'])) return true;
-    if (isOwner(owner, 'blocks/analytics', ['ChartCard']) || isOwner(owner, 'base/display', ['ContentBlock'])) return props.has('surface');
-    if (isOwner(owner, 'blocks/analytics', ['Metric'])) return literal(props.get('variant')) === 'card';
-    if (isOwner(owner, 'blocks/analytics', ['MetricGrid'])) return !props.has('variant') || literal(props.get('variant')) === 'card';
+    if (isOwner(owner, 'base/cards', ['Card']) || isOwner(owner, 'base/forms', ['FormSection']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'features/data-view', ['DataView'])) return true;
+    if (isOwner(owner, 'blocks/analytics/charts', ['ChartCard'])) return props.has('surface');
+    if (isOwner(owner, 'blocks/analytics/charts', ['Metric'])) return literal(props.get('variant')) === 'card';
+    if (isOwner(owner, 'blocks/analytics/charts', ['MetricGrid'])) return !props.has('variant') || literal(props.get('variant')) === 'card';
     return isOwner(owner, 'blocks/analytics/usage-card', ['UsageCard']) || isOwner(owner, 'blocks/analytics', ['UsageCard']) || isOwner(owner, 'blocks/planning', ['TaskCard']);
   };
   // Examine lexical JSX only. Names ending in Card are not evidence of framing;
@@ -192,7 +192,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
         const opening = ts.isJsxElement(child) ? child.openingElement : child;
         const owner = ownerFor(opening.tagName);
         found.push({ opening, owner, props: new Map(attributes(opening)), element: child });
-        if (isOwner(owner, 'base/cards', ['Card', 'SmartCard'])) return;
+        if (isOwner(owner, 'base/cards', ['Card'])) return;
         if (ts.isJsxElement(child)) child.children.forEach(collect);
         return;
       }
@@ -214,7 +214,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       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']);
+      const card = isOwner(owner, 'base/cards', ['Card']);
       // 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));
     };
@@ -239,14 +239,24 @@ export function analyzeComposition(text, { filename, index, ts }) {
   };
   // Buttons, command rows and command menus placed directly, conditionally or
   // inside a passive row of a page header's actions region. Unknown local
-  // components are custom controls.
+  // components are custom controls. A slot callback, such as `slots.actions`
+  // wrapping `defaultContent`, is read through what it returns.
+  const slotCallbacks = new Set();
   const commandButtons = expression => {
     const node = resolve(expression);
     if (!node) return false;
+    if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node)) && node.body) {
+      // A callback that returns itself is not followed twice.
+      if (slotCallbacks.has(node)) return false;
+      slotCallbacks.add(node);
+      const found = ts.isBlock(node.body) ? node.body.statements.some(statement => ts.isReturnStatement(statement) && commandButtons(statement.expression)) : commandButtons(node.body);
+      slotCallbacks.delete(node);
+      return found;
+    }
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
       const opening = ts.isJsxElement(node) ? node.openingElement : node;
       const owner = ownerFor(opening.tagName);
-      if (isOwner(owner, 'base/buttons', ['Button', 'TextButton', 'BaseButton', 'BaseButtonLink']) || isOwner(owner, 'base/forms', ['SubmitStateButton']) || isOwner(owner, 'base/action-menu', ['ActionMenu', 'ActionButtons']) || isOwner(owner, 'layout/page', ['PageActions']) || isOwner(owner, 'layout', ['PageActions']) || opening.tagName.getText(source) === 'button') return true;
+      if (isOwner(owner, 'base/buttons', ['Button', 'TextButton', 'BaseButton', 'BaseButtonLink']) || isOwner(owner, 'base/forms', ['SubmitStateButton']) || isOwner(owner, 'base/action-menu', ['ActionMenu', 'ActionButtons']) || opening.tagName.getText(source) === 'button') return true;
       if (!/^(div|span)$/.test(opening.tagName.getText(source)) && !isOwner(owner, 'base/structure', ['Stack', 'Grid'])) return false;
       return ts.isJsxElement(node) && node.children.some(commandButtons);
     }
@@ -402,17 +412,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     }
     ts.forEachChild(node, child => visit(child, parents, next));
   }
-  const surfaceOwner = owner => isOwner(owner, 'base/cards', ['Card', 'SmartCard', 'CardFooter']) || isOwner(owner, 'base/forms', ['FormSection']) || isOwner(owner, 'blocks/analytics', ['ChartCard']) || isOwner(owner, 'base/display', ['ContentBlock']);
+  const surfaceOwner = owner => isOwner(owner, 'base/cards', ['Card', 'CardFooter']) || isOwner(owner, 'base/forms', ['FormSection']) || isOwner(owner, 'blocks/analytics/charts', ['ChartCard']);
   const footerRegion = parent => surfaceOwner(parent.owner) && (['footerSlot', 'footer'].includes(parent.slot) || parent.owner.symbol === 'CardFooter');
   const paddedRegion = parent => {
     if (!surfaceOwner(parent.owner) || parent.unknownProps) return false;
+    // Card contentPadding sets the body inset alone, keeping the header inset:
+    // the seam for a titled card around a table or list that owns its edge.
+    if (isOwner(parent.owner, 'base/cards', ['Card']) && parent.props.has('contentPadding') && !['footerSlot', 'footer'].includes(parent.slot)) {
+      const padding = literal(parent.props.get('contentPadding'));
+      return padding !== undefined && padding !== 'none';
+    }
     if (parent.props.has('padding')) {
       const padding = literal(parent.props.get('padding'));
       return padding !== undefined && padding !== 'none';
     }
     // Flat removes the frame, not Card/FormSection's ordinary region insets.
-    // ChartCard and ContentBlock instead default to no inset when card-free.
-    return isOwner(parent.owner, 'base/cards', ['Card', 'SmartCard', 'CardFooter']) || isOwner(parent.owner, 'base/forms', ['FormSection']) || parent.framed;
+    // ChartCard instead defaults to no inset when card-free.
+    return isOwner(parent.owner, 'base/cards', ['Card', 'CardFooter']) || isOwner(parent.owner, 'base/forms', ['FormSection']) || parent.framed;
   };
   const remoteSubmit = expression => {
     const calls = new Set();
@@ -504,22 +520,22 @@ export function analyzeComposition(text, { filename, index, ts }) {
       if (display && marginProperty.test(name) && !/^['"]?0(?:px|rem|em|%)?['"]?$/.test(resolve(value)?.getText(source)??'')) add(node,'copy-margin','error',`${owner.symbol}: typography is margin-free; the surrounding structure owns its copy gap.`);
       if (fixedText && (textStyle.test(name) || badge && /^border.*Radius$/.test(name))) add(node, 'fixed-text-role', 'error', `${owner.symbol}: ${name} replaces its shared text/radius recipe.`);
     }
-    if ((isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'base/display', ['ContentBlock'])) && props.get('icon')) add(node, 'decorative-icon', 'warning', `${owner.symbol}: a title icon is decoration unless it encodes state or a brand; let the title name the subject.`);
+    if ((isOwner(owner, 'base/cards', ['Card'])) && props.get('icon')) add(node, 'decorative-icon', 'warning', `${owner.symbol}: a title icon is decoration unless it encodes state or a brand; let the title name the subject.`);
     const facts = isOwner(owner, 'base/metadata-list', ['MetadataList']) || isOwner(owner, 'blocks/data-display', ['MetadataList']) ? resolve(props.get('items')) : undefined;
     if (facts && ts.isArrayLiteralExpression(facts) && facts.elements.filter(item => properties(item, false).some(([name]) => name === 'icon')).length > 1) add(node, 'decorative-icon', 'warning', 'MetadataList: an icon on every fact repeats what its label says; keep labels and drop the icons.');
     const framed = !unknownProps && framedOwner(owner, props);
-    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard'])) {
+    if (isOwner(owner, 'base/cards', ['Card'])) {
       for (const slot of ['headerAction', 'headerStart']) if (slotBadge(props.get(slot))) add(node, 'card-badge-placement', 'error', `${owner.symbol}: put status/count/version badges in titleSuffix; ${slot} owns ${slot === 'headerAction' ? 'commands' : 'pre-title context'}.`);
       const contents = contentElements(node);
       const role = (item, names) => isOwner(item.owner, 'typography', names);
       const valueHeading = contents.some(item => role(item, ['Heading']) && /[$€£¥]|\d/.test(renderedText(item.element)));
-      if (valueHeading && contents.some(item => role(item, ['Text', 'DisplayLabel'])) && contents.some(item => isOwner(item.owner, 'base/badge', ['Badge']) && /[%+−-]|\d/.test(renderedText(item.element)))) add(node, 'reinvented-metric-card', 'warning', 'This label/value/change composition resembles a KPI. Compare Metric/MetricGrid from blocks/analytics or InlineStat from blocks/data-display; retain a custom subject when their metric lifecycle does not fit.');
+      if (valueHeading && contents.some(item => role(item, ['Text', 'DisplayLabel'])) && contents.some(item => isOwner(item.owner, 'base/badge', ['Badge']) && /[%+−-]|\d/.test(renderedText(item.element)))) add(node, 'reinvented-metric-card', 'warning', 'This label/value/change composition resembles a KPI. Compare Metric/MetricGrid from blocks/analytics/charts or InlineStat from blocks/data-display; retain a custom subject when their metric lifecycle does not fit.');
       const factRows = contents.filter(item => isOwner(item.owner, 'base/structure', ['Stack']) && literal(item.props.get('direction')) === 'horizontal' && literal(item.props.get('justify')) === 'between' && contentElements(item.opening).filter(child => role(child, ['Text', 'DisplayLabel'])).length >= 2);
       if (factRows.length >= 2) add(node, 'reinvented-metadata-list', 'warning', 'Repeated label/value rows resemble record facts. Compare MetadataList from base/metadata-list or InlineStat from blocks/data-display; preserve custom rows when they own distinct interactions or content.');
       if (contents.some(item => role(item, ['Heading']) && /^(?:no\b|nothing\b|empty\b)/i.test(renderedText(item.element))) && contents.some(item => isOwner(item.owner, 'base/structure', ['Stack']) && literal(item.props.get('align')) === 'center') && contents.some(item => isOwner(item.owner, 'base/buttons', ['Button', 'ButtonLink']))) add(node, 'reinvented-empty-state', 'warning', 'This centered empty region may fit EmptyState from blocks/data-display, with media, title, description and actions. Review the product state before choosing the complete owner.');
     }
     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, '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, 'base/forms', ['FormActionsBar'])) {
       const footer = parents.findLast(footerRegion);
       const padded = parents.findLast(paddedRegion);
@@ -528,7 +544,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'base/table', ['Table'])) {
       const footer = parents.findLast(footerRegion);
       const padded = parents.findLast(paddedRegion);
-      if (footer || padded) add(node, 'uncontained-table-in-card', 'warning', `${owner.symbol} is inside ${footer ? `${footer.owner.symbol}.${footer.slot}` : `a padded ${padded.owner.symbol}`}. Keep substantial tables in a body or peer region; a deliberate Card host uses padding="none" with a flat table. Review the actual surface and inset ownership.`);
+      if (footer || padded) add(node, 'uncontained-table-in-card', 'warning', `${owner.symbol} is inside ${footer ? `${footer.owner.symbol}.${footer.slot}` : `a padded ${padded.owner.symbol}`}. Keep substantial tables in a body or peer region; a titled Card host uses contentPadding="none" (padding="none" without a header) around a flat table. Review the actual surface and inset ownership.`);
     }
     if ((isOwner(owner, 'base/accordion', ['Accordion', 'SmartAccordion']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'base/code-block', ['CodeBlock'])) && parents.some(parent => isOwner(parent.owner, 'features/table', ['DataTable']) && parent.slot === 'columns' && parent.member === 'cell')) {
       add(node, 'heavy-cell-disclosure', 'warning', `${owner.symbol} in a DataTable cell can disrupt row scanning. Prefer a compact summary with rowActions opening an ActionDrawer, ActionDialog or detail route; retain an intentional inline disclosure after checking expanded rows and keyboard access.`);
@@ -562,18 +578,22 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (routeOwner && props.has('header') && headerValue && !ts.isObjectLiteralExpression(headerValue)) unknown(props.get('header'));
     // Every header owner takes role-based commands; its free-form regions hold
     // non-command controls only.
-    const commandHeader = (pageOwner && owner.symbol === 'PageHeader') || isOwner(owner, 'base/navigation', ['PageHeading']) || isOwner(owner, 'features/resource', ['ResourceHeader', 'ResourceIndexShell', 'ResourceShowShell', 'TabbedResourceShell']) || isOwner(owner, 'layout/settings', ['SettingsShell', 'AsideNavShell']) || isOwner(owner, 'layout', ['SettingsShell', 'AsideNavShell']) || isOwner(owner, 'layout/workspace', ['WorkspaceRecordHeader']);
-    const headerActions = pageOwner && owner.symbol === 'Page' ? new Map(header).get('actions') : commandHeader ? props.get('actions') : undefined;
+    const commandHeader = (pageOwner && owner.symbol === 'PageHeader') || isOwner(owner, 'base/navigation', ['PageHeading']) || isOwner(owner, 'layout/settings', ['AsideNavShell']) || isOwner(owner, 'layout', ['AsideNavShell']) || isOwner(owner, 'layout/workspace', ['WorkspaceRecordHeader']);
+    // Page and PageHeader take free-form header content through `slots.actions`;
+    // the other header owners keep an `actions` prop.
+    const slotActions = slots => new Map(properties(slots, false)).get('actions');
+    const headerActions = pageOwner && owner.symbol === 'Page' ? slotActions(new Map(header).get('slots'))
+      : pageOwner && owner.symbol === 'PageHeader' ? slotActions(props.get('slots'))
+      : commandHeader ? props.get('actions') : undefined;
     const elementSecondary = isOwner(owner, 'layout/workspace', ['WorkspaceRecordHeader']) ? props.get('secondaryActions') : undefined;
     if (pageOwner && owner.symbol === 'Page') {
       const primaries = solidPrimaryCount(ts.isJsxSelfClosingElement(node) ? node : node.parent) + (new Map(header).has('primaryAction') ? 1 : 0);
       if (primaries > 1) add(node, 'multiple-primary-commands', 'warning', `Page has ${primaries} solid primary commands in the same task scope. Keep one leading command per task/surface; forms keep their local SubmitStateButton or FormActionsBar. Use header.primaryAction for route-level commands and secondaryActions for supporting route commands.`);
     }
-    if ((headerActions && commandButtons(headerActions)) || (elementSecondary && commandButtons(elementSecondary))) add(node, 'page-command-roles', 'warning', `${owner.symbol}: buttons, command rows and menus in the header actions region choose their own emphasis, order and overflow. Pass commands as primaryAction (one) and ordered secondaryActions; keep actions for non-command controls.`);
+    if ((headerActions && commandButtons(headerActions)) || (elementSecondary && commandButtons(elementSecondary))) add(node, 'page-command-roles', 'warning', `${owner.symbol}: buttons, command rows and menus in the header actions region choose their own emphasis, order and overflow. Pass commands as primaryAction (one) and ordered secondaryActions; keep the actions region for non-command controls.`);
     const headerProps = pageOwner && owner.symbol === 'Page' ? new Map(header) : pageOwner && owner.symbol === 'PageHeader' ? props : undefined;
     if (headerProps) {
       for (const name of ['primaryAction', 'secondaryActions']) if (headerProps.has(name) && remoteSubmit(headerProps.get(name))) add(headerProps.get(name), 'remote-header-form-submit', 'warning', `${owner.symbol}: ${name} submits a form through document.getElementById(...).requestSubmit(). Keep task-local submission beside its fields or in the form footer. A single full-page editor can deliberately own a header submit; preserve native validation and avoid duplicate commands.`);
-      if (headerProps.has('titleIcon') && !headerProps.has('titleIconHref') && !headerProps.has('onTitleIconClick')) add(headerProps.get('titleIcon') ?? node, 'decorative-icon', 'warning', `${owner.symbol}: titleIcon decorates the page title; let the title name the page, or link the icon with titleIconHref.`);
       const hasIcon = action => properties(action, false).some(([name]) => name === 'icon');
       const secondary = resolve(headerProps.get('secondaryActions'));
       const iconCommands = (headerProps.has('primaryAction') && hasIcon(headerProps.get('primaryAction')) ? 1 : 0) + (secondary && ts.isArrayLiteralExpression(secondary) ? secondary.elements.filter(hasIcon).length : 0);

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

@@ -115,7 +115,10 @@ export function mapComposition(index, contracts, rawOptions) {
   : /^[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}));
+  const roles = unique(mappings.flatMap(mapping => mapping.roles)).map(role => {
+   const owners = mappings.filter(mapping => mapping.roles.includes(role));
+   return {role, owners: owners.length, symbols: unique(owners.map(mapping => mapping.symbol))};
+  });
   return {...base, mode: 'roles', total: roles.length, roles};
  }
  if (options.role !== undefined) {

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

@@ -132,7 +132,9 @@ function rankComponents(index, { query, layer = null, limit = 5 }, partial = fal
     const documentedSymbol = matchedSymbols.some(symbol => documented.has(symbol));
     const exactFamily = searchable(family.import.split('/').at(-1)) === terms.join(' ');
     const exactIntent = family.aliases.some(alias => normalized(alias) === needle);
-    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 + Number(documentedSymbol) : exactFamily ? 8500 : exactIntent ? 8000 : focusedSymbols.length ? 7100 + 1 / Math.min(...focusedSymbols.map(symbol => words(symbol).length)) : terms.reduce((sum, term) => sum + (family.guidance.some(guide => containsTerms(guide.title, [term])) ? 20 : family.tags.some(tag => containsTerms(tag, [term])) ? 10 : 1), 0);
+    // The family whose curated alias is the query is that symbol's owner too,
+    // even when the matched name is an undocumented alias export.
+    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 + Number(documentedSymbol || exactIntent) : exactFamily ? 8500 : exactIntent ? 8000 : focusedSymbols.length ? 7100 + 1 / Math.min(...focusedSymbols.map(symbol => words(symbol).length)) : terms.reduce((sum, term) => sum + (family.guidance.some(guide => containsTerms(guide.title, [term])) ? 20 : family.tags.some(tag => containsTerms(tag, [term])) ? 10 : 1), 0);
     const selectedSymbols = matchedSymbols.length ? matchedSymbols : focusedSymbols;
     const guidance = relevantGuidance(family, needle, terms, exactOwners.length ? selectedSymbols : [], exactImport);
     const candidateSymbols = exactImport ? family.symbols : exactOwners.length || matchedSymbols.length ? selectedSymbols : [...new Set([...selectedSymbols, ...guidance.flatMap(guide => guideSymbols(guide, family))])];

package/docs/consumer-skill/scripts/setup-skills.mjs

@@ -6,6 +6,8 @@ import { fileURLToPath } from 'node:url';
 export const focusedSkills = ['themelia-components', 'themelia-tokenization', 'themelia-composition', 'themelia-design'];
 export const sharedSkillName = 'themelia-react-ui-consumer';
 export const agentFiles = ['themelia-ui-designer.md'];
+/** Earlier releases copied these; a refresh removes them so no stale guidance remains. */
+export const retiredSkills = ['themelia-foundation', 'themelia-forms'];
 
 /** One metadata/example copy, four small discoverable entrypoints, and real templates. */
 export function consumerBundleFiles(packageRoot, destination) {
@@ -53,12 +55,23 @@ export function checkCopiedConsumerBundle({ packageRoot, destination }) {
     assert(fs.existsSync(target) && !fs.lstatSync(target).isSymbolicLink(), `Copied consumer bundle is stale: missing or linked asset ${target}`);
     assert(content.equals(fs.readFileSync(target)), `Copied consumer bundle is stale: refresh the whole bundle (${target})`);
   }
+  // A file the package no longer ships is stale guidance too.
+  const shipped = new Set(files.map(file => file.target));
+  for (const name of [sharedSkillName, ...focusedSkills]) {
+    for (const entry of fs.readdirSync(path.resolve(destination, name), { recursive: true, withFileTypes: true })) {
+      const file = path.join(entry.parentPath, entry.name);
+      assert(entry.isDirectory() || entry.name === '.DS_Store' || shipped.has(file), `Copied consumer bundle is stale: the package no longer ships ${file}`);
+    }
+  }
+  for (const name of retiredSkills) assert(!pathExists(path.resolve(destination, name)), `Copied consumer bundle is stale: ${name} was retired; copy again to remove it`);
   return { skills: [sharedSkillName, ...focusedSkills], assets: files.length };
 }
 
 export function copyConsumerBundle({ packageRoot, destination }) {
   const files = consumerBundleFiles(packageRoot, destination);
   assertSkillDestination(destination);
+  // Replace, never merge: files a newer release dropped must not survive.
+  for (const name of [sharedSkillName, ...focusedSkills, ...retiredSkills]) fs.rmSync(path.resolve(destination, name), { recursive: true, force: true });
   for (const { target, content } of files) {
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, content);
@@ -68,7 +81,6 @@ export function copyConsumerBundle({ packageRoot, destination }) {
 
 function assertSkillDestination(destination) {
   assertDirectoryPath(destination);
-  for (const name of [sharedSkillName, ...focusedSkills]) assert(!pathExists(path.join(destination, name)), `Destination exists: ${name}. Preserve or move the previous skill before copying.`);
 }
 
 function pathExists(target) {
@@ -103,21 +115,36 @@ export function copyAgents({ packageRoot, destination }) {
   const files = agentBundleFiles(packageRoot, destination);
   assertAgentDestination(files);
   fs.mkdirSync(destination, { recursive: true });
-  for (const { target, content } of files) fs.writeFileSync(target, content);
+  for (const { target, content } of files) { fs.rmSync(target, { force: true }); fs.writeFileSync(target, content); }
   return checkCopiedAgents({ packageRoot, destination });
 }
 
 function assertAgentDestination(files) {
   for (const { target } of files) {
     assertDirectoryPath(path.dirname(target));
-    assert(!pathExists(target), `Destination exists: ${path.basename(target)}. Preserve or move the previous agent before copying.`);
   }
 }
 
+/**
+ * The project instructions block for the app's AGENTS.md or CLAUDE.md. It is
+ * printed, never written: project instructions belong to the app.
+ */
+export function agentsBlock(packageRoot) {
+  const reference = fs.readFileSync(path.resolve(packageRoot, 'docs/consumer-skill/references/agents-md.md'), 'utf8');
+  const block = reference.match(/<!-- [\w@/.-]+:start \S+ -->[\s\S]*?<!-- [\w@/.-]+:end -->/);
+  assert(block, 'The packaged AGENTS.md block is missing');
+  return block[0];
+}
+
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
-    const usage = 'Usage: node setup-skills.mjs --copy|--check [--destination <agent-skills-directory>] [--agents <markdown-agent-directory> | --no-agents]';
+    const usage = 'Usage: node setup-skills.mjs --copy|--check [--destination <agent-skills-directory>] [--agents <markdown-agent-directory> | --no-agents]\n       node setup-skills.mjs --agents-block';
     const [mode, ...rest] = process.argv.slice(2);
+    if (mode === '--agents-block') {
+      assert(rest.length === 0, usage);
+      process.stdout.write(agentsBlock(fileURLToPath(new URL('../../..', import.meta.url))) + '\n');
+      process.exit(0);
+    }
     const options = {};
     for (let index = 0; index < rest.length; index++) {
       const flag = rest[index];

package/docs/consumer-skills/themelia-components/SKILL.md

@@ -1,22 +1,26 @@
 ---
 name: themelia-components
-description: Use when finding or integrating themelia-react-ui components, compound parts, blocks, features or typed forms in React apps; not library maintenance.
+description: Use before writing any React UI in an app that installs themelia-react-ui, to find the component, block or feature that already covers each region, then integrate it with its exact API and typed forms; not library maintenance.
 ---
 
 # Themelia components
 
 Installed types own the API. Resolve package/version and copied-skill freshness through [installation](../../consumer-skill/references/installation.md). Set up CSS, peers and UIProvider when missing. Skills share assets.
 
+## Start from what exists
+
+Simple views are 100% Themelia owners; domain views about 70%, the rest app-owned subjects made from its parts. Read [building views](../../consumer-skill/references/building-views.md): reach order, need → owner map, coverage plan. The [catalogue](../../consumer-skill/references/catalogue.md) lists every component; read Features and Blocks before deciding something is missing.
+
 ## Find and verify
 
-Split the task into responsibilities: facts, selection, editing, collection, disclosure or navigation. Search each separately. Empty strict results do not establish missing support; inspect related suggestions and unmatched terms, then shorten the query. See [discovery](../../consumer-skill/references/discovery.md).
+Split the task into responsibilities: facts, selection, editing, collection, disclosure or navigation. Search each separately, by its domain noun (invoice, shipment, quota) as well as its control noun. Empty strict results do not establish missing support; inspect related suggestions and unmatched terms, then shorten the query. See [discovery](../../consumer-skill/references/discovery.md).
 
 ```sh
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs "expandable form sections" --limit 3
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs AccordionContent --import themelia-react-ui/base/accordion --prop keepMounted
 ```
 
-Imports keep each family's published spelling (`base/cards`, `base/buttons`, `base/chart`); a near miss reports `importResolution`. Read choose/avoid, ownership and peers for the exact export. Qualify ambiguous names. Default inspection includes relevant inherited behavior; --prop retrieves exact callbacks/slots, and installed declarations cover omitted types/overloads. Unknown defaults stay unknown. Preserve generic/discriminated contracts and prefer canonical exports over migration names.
+Imports keep each family's published spelling (`base/cards`, `base/buttons`, `base/chart`); a near miss reports `importResolution`. Read choose/avoid, ownership and peers for the exact export. Qualify ambiguous names. Default inspection includes relevant inherited behavior; --prop retrieves exact callbacks/slots, and installed declarations cover omitted types/overloads. Unknown defaults stay unknown. Preserve generic/discriminated contracts.
 
 Search task-specific subjects/workflows as well as controls: options, variant editing and attached media have dedicated owners. Before rebuilding, compare their data contract, controlled/default state, mounting, callbacks, refs and render seams. A missing prop on a convenience wrapper can exist on its public parts. A custom badge/retained field does not establish a disclosure gap. See [capability comparison](../../consumer-skill/references/custom-composition.md).
 
@@ -28,4 +32,4 @@ Search task-specific subjects/workflows as well as controls: options, variant ed
 
 Use a fitting complete feature; otherwise compose public owners. Base controls and blocks already own local interaction/accessibility. Features coordinate a complete workflow. Data, routing, permissions and translations stay app-owned; see [integration](../../consumer-skill/references/integration.md). Dialogs/drawers/confirmations use features/overlays at the app/feature boundary.
 
-Use **themelia-composition** for hierarchy and custom composites, **themelia-tokenization** for theme roles and token-backed app geometry, and **themelia-design** for data-led view specs and rendered critique. Run app checks and [review](../../consumer-skill/references/review.md); execute relevant focus, validation and failure/retry paths. Report source, inspected appearance and executed behavior separately.
+Use **themelia-composition** for hierarchy, **themelia-tokenization** for theme roles and **themelia-design** for view specs and critique. Run app checks and [review](../../consumer-skill/references/review.md); execute relevant focus, validation and failure/retry paths. Report source, inspected appearance and executed behavior separately.

package/docs/consumer-skills/themelia-composition/SKILL.md

@@ -9,9 +9,13 @@ Start with the user's decision, representative records, related entities and edi
 
 Before JSX, settle task, reading priority, action scope and inset owners. Read [screen decisions](../../consumer-skill/references/screen-decisions.md) for new screens/repairs. Optional props are capabilities, not reasons to add navigation, cards or commands.
 
+## Cover the view first
+
+Name an owner per region, reaching for a feature, then a block, then layout and base owners, then an app-owned subject. A simple view has no custom region; a domain view is about 70% owners. [Building views](../../consumer-skill/references/building-views.md) has the need → owner map, plan format and custom-part rules; the [catalogue](../../consumer-skill/references/catalogue.md) lists every component. Build custom subjects the way [templates](../../../templates/README.md) and recipes are built.
+
 ## Let the data shape the subject
 
-Discover task-specific owners before choosing custom markup: product options, variant editing and attached media have different owners from generic controls. Compare their data/state/render seams; use a fitting owner or its parts. Custom JSX shapes additional relationships without requiring an API gap. Read [capability comparison and domain coverage](../../consumer-skill/references/custom-composition.md). More data and a new component name do not establish better composition.
+Discover task-specific owners before choosing custom markup: product options, variant editing and attached media have different owners from generic controls. Compare their data/state/render seams; use a fitting owner or its parts. Custom JSX shapes additional relationships without requiring an API gap. Read [capability comparison and domain coverage](../../consumer-skill/references/custom-composition.md).
 
 ## Choose the seam
 
@@ -23,9 +27,9 @@ Use the [mapper](../../consumer-skill/references/composition-mapping.md) with --
 
 ## Assign geometry once
 
-Page narrow centers one-column forms/details at 48rem; aside infers xl/80rem. Explicit TwoColumnLayout needs Page maxWidth="xl". Collections default to lg/64rem. Settings use Page → SettingsShell → FormSection.
+Page narrow centers one-column forms/details at 48rem; aside infers xl/80rem. Explicit TwoColumnLayout needs Page maxWidth="xl". Collections default to lg/64rem. Settings use Page → AsideNavShell → FormSection.
 
-Explicit maxWidth wins, then narrow, then aside width. Page owns h1, commands, lifecycle, gutters and subject gaps. AuthShell owns auth; Container/Section own sites. Header actions defaultContent preserves responsive commands. Loading precedes error then empty; supply copy/onRetry. Resource shells are migration APIs.
+Explicit maxWidth wins, then narrow, then aside width. Page owns h1, commands, lifecycle, gutters and subject gaps. AuthShell owns auth; Container/Section own sites. Header actions defaultContent preserves responsive commands. Loading precedes error then empty; supply copy/onRetry.
 
 Stack/Grid/AdaptiveGrid own peer relationships; Card owns frame/insets. Card flat removes chrome, not padding; use none under an existing inset owner. Blocks stay card-free unless their purpose is a card. Tailwind owns app-specific tracks/queries/overflow; read [domain structures](../../consumer-skill/references/domain-structures.md).
 

package/docs/consumer-skills/themelia-design/SKILL.md

@@ -22,7 +22,11 @@ themes and density.
    name the focal point; sketch 390 and 1440 wireframes in text; choose an
    encoding per fact. See [view spec](../../consumer-skill/references/view-spec.md)
    and [screen decisions](../../consumer-skill/references/screen-decisions.md).
-3. **Find owners.** Map regions to owners with the finder, mapper and inspector
+3. **Find owners.** Write the coverage plan from
+   [building views](../../consumer-skill/references/building-views.md): one owner per region, reaching
+   for a feature, then a block, then base and layout owners, and marking only
+   the product-specific subject as custom. Scan the
+   [catalogue](../../consumer-skill/references/catalogue.md), then use the finder, mapper and inspector
    described in [discovery](../../consumer-skill/references/discovery.md);
    [archetypes](../../consumer-skill/references/screen-archetypes.md) and
    [metrics](../../consumer-skill/references/analytics.md) give starting points.
@@ -38,6 +42,8 @@ themes and density.
 [View craft](../../consumer-skill/references/view-craft.md) holds the detail:
 
 - One focal point per view and per region.
+- Good design here is choosing and arranging owners, not drawing. A view
+  that looks off usually has hand-written markup where an owner exists.
 - One solid primary command per surface; at most three text levels per region;
   tones only for status that changes the action.
 - Encode by the fact's shape: a figure with its baseline, a trend where shape

package/docs/consumer-skills/themelia-tokenization/SKILL.md

@@ -5,7 +5,7 @@ description: Build consistent domain structures with Themelia base/layout compon
 
 # Themelia tokenization
 
-Use mostly public base components and layout blocks. When a domain needs a particular structure, compose their content with semantic JSX and token-backed Tailwind on app-owned elements. **themelia-components** verifies APIs; **themelia-composition** decides hierarchy; **themelia-design** judges the rendered view. Read [domain structures](../../consumer-skill/references/domain-structures.md) and its executable allocation example; the [design contract](../../consumer-skill/references/design-contract.md) owns shared roles.
+Use mostly public base components and layout blocks; [building views](../../consumer-skill/references/building-views.md) maps needs to owners and the [catalogue](../../consumer-skill/references/catalogue.md) lists them all. When a domain needs a particular structure, compose their content with semantic JSX and token-backed Tailwind on app-owned elements. **themelia-components** verifies APIs; **themelia-composition** decides hierarchy; **themelia-design** judges the rendered view. Read [domain structures](../../consumer-skill/references/domain-structures.md) and its executable allocation example; the [design contract](../../consumer-skill/references/design-contract.md) owns shared roles.
 
 ## Inspect before applying
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "themelia-react-ui",
-  "version": "2.0.6",
+  "version": "3.0.0",
   "description": "A composable React UI library for modern admin applications, built on Base UI and Tailwind with shadcn-compatible themes, shared design tokens, reusable layouts, blocks and workflows.",
   "publishConfig": {
     "access": "public",
@@ -194,10 +194,6 @@
       "types": "./dist/components/base/repeaters/index.d.ts",
       "import": "./dist/base/repeaters.js"
     },
-    "./base/sheet": {
-      "types": "./dist/components/base/sheet/index.d.ts",
-      "import": "./dist/base/sheet.js"
-    },
     "./base/sidebar": {
       "types": "./dist/components/base/sidebar/index.d.ts",
       "import": "./dist/base/sidebar.js"
@@ -338,10 +334,6 @@
       "types": "./dist/components/features/suggestions/index.d.ts",
       "import": "./dist/features/suggestions.js"
     },
-    "./features/sync": {
-      "types": "./dist/components/features/sync/index.d.ts",
-      "import": "./dist/features/sync.js"
-    },
     "./features/table": {
       "types": "./dist/components/features/table/index.d.ts",
       "import": "./dist/features/table.js"
@@ -450,6 +442,10 @@
     "./blocks/analytics/usage-card": {
       "types": "./dist/components/blocks/analytics/usage-card/index.d.ts",
       "import": "./dist/blocks/analytics/usage-card.js"
+    },
+    "./blocks/analytics/charts": {
+      "types": "./dist/components/blocks/analytics/charts/index.d.ts",
+      "import": "./dist/blocks/analytics/charts.js"
     }
   },
   "scripts": {
@@ -458,11 +454,12 @@
     "build:preview": "node scripts/generate-utilities.mjs && vite build --config vite.preview.config.ts",
     "preview": "vite preview --config vite.preview.config.ts",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "node scripts/run-unit.mjs",
     "test:watch": "vitest",
     "test:browser": "npm run build:preview && node scripts/run-browser.mjs",
+    "test:browser:quick": "npm run build:preview && node scripts/run-browser.mjs --quick",
     "check:package": "node scripts/check-package.mjs",
-    "check": "npm run check:contract && npm run check:preview && npm run check:docs && npm run lint && npm run check:design-lint && npm run typecheck && npm test && npm run build && npm run check:skill && npm run check:maps && npm run check:package && npm run build:preview",
+    "check": "node scripts/run-gate.mjs full",
     "check:contract": "node --test scripts/test-runtime-ownership.mjs scripts/test-primitive-geometry.mjs scripts/test-source-entrypoints.mjs scripts/test-utility-vocabulary.mjs scripts/test-example-utilities.mjs scripts/test-theme-contrast.mjs scripts/test-theme-modes.mjs && node scripts/check-contract.mjs",
     "lint": "node scripts/generate-utilities.mjs && oxlint src/components src/lib src/preview docs/consumer-skill/examples templates --deny-warnings",
     "check:design-lint": "node scripts/generate-utilities.mjs && node scripts/check-design-lint.mjs",
@@ -476,7 +473,7 @@
     "check:docs": "node --test scripts/test-public-docs.mjs && node scripts/refresh-prop-docs.mjs --check",
     "collect:browser": "npm run build:preview && node scripts/run-browser.mjs --collectors",
     "check:all": "npm run check && node scripts/run-browser.mjs",
-    "check:quick": "npm run check:contract && npm run lint && npm run check:design-lint && npm run typecheck && npm test && npm run build",
+    "check:quick": "node scripts/run-gate.mjs quick",
     "check:maps": "node scripts/test-client-boundaries.mjs --built",
     "build:docs": "node scripts/build-static-docs.mjs",
     "check:static-docs": "node scripts/check-static-docs.mjs",

package/templates/README.md

@@ -8,7 +8,7 @@ For production create/edit workflows, adapt the [RHF edit page](../docs/consumer
 
 | File | Export | Composition demonstrated |
 | --- | --- | --- |
-| [admin-shell-template.tsx](admin-shell-template.tsx) | `AdminStarterShell`, `AdminTemplatesShowcase` | UIProvider defaults, all five AppLayout presets, AppSidebar, workspace context, breadcrumbs, notifications and account/settings menus |
+| [admin-shell-template.tsx](admin-shell-template.tsx) | `AdminStarterShell`, `AdminTemplatesShowcase` | UIProvider defaults, all five AppLayout presets with a skip link, AppSidebar, NavigationTabs route links for the stacked preset, workspace context, breadcrumbs, notifications derived from each item's `read` flag and account/settings menus |
 | [orders-template.tsx](orders-template.tsx) | `OrdersAdminTemplate` | Page with a fulfillment primary command, TwoColumnLayout, Card, lifecycle-grouped Item rows, MetadataList, Money, AddressCard, PaymentMethod, ActivityLog and refund/tracking/note dialogs |
 | [products-template.tsx](products-template.tsx) | `ProductsAdminTemplate` | ProductVariantsManager, ProductVariantDetails/Editor, SeoListingCard, publishing/organization forms and variant duplication |
 | [customers-template.tsx](customers-template.tsx) | `CustomersAdminTemplate` | MetricBar, DataTable order history, MetadataList, AddressCard, ActivityLog, contact drafts and validated store-credit submission |
@@ -20,7 +20,7 @@ For layout selection, read the [owner map](../docs/consumer-skill/references/com
 ## Boundaries to preserve when adapting
 
 - `AdminTemplatesShowcase` supplies UIProvider defaults; embedded preview pages inherit the catalogue's provider. `AdminStarterShell` inherits the application's provider. `defaultDensity` belongs to the standalone showcase.
-- Page owns gutters and the default resource measure, TwoColumnLayout owns the main/aside split, and Stack/Grid own peer gaps. These record and overview routes keep the default measure; only a wide directory or comparison opts into `maxWidth="full"`. Ordinary Cards retain the default padding. Compact control density does not shrink Cards. Peer Card stacks use `gap="2xl"`, matching Page and TwoColumnLayout’s 24px default rhythm in both axes; copy and form groups keep their own gaps.
+- Page owns gutters and the default resource measure, TwoColumnLayout owns the main/aside split, and Stack/Grid own peer gaps. Inside a Page the split uses `adaptTo="container"`, so it follows the page's own width beside a docked sidebar instead of the viewport. In the stacked shell the contained measure owns the inline gutter and each Page keeps its defaults. These record and overview routes keep the default measure; only a wide directory or comparison opts into `maxWidth="full"`. Ordinary Cards retain the default padding. Compact control density does not shrink Cards. Peer Card stacks use `gap="2xl"`, matching Page and TwoColumnLayout’s 24px default rhythm in both axes; copy and form groups keep their own gaps.
 - A headed address, payment, SEO or variants panel uses its own `surface="card"`. It delegates to Card's aligned header/body anatomy and inherits provider separators. Do not wrap it in an untitled padded Card. Omitted surface keeps these blocks unframed for embedding; an embedded header does not inherit an unintended Card separator.
 - Put page commands in Page's header as `primaryAction` (one) and ordered
   `secondaryActions`; the header owns their treatment, overflow and narrow-width
@@ -29,6 +29,7 @@ For layout selection, read the [owner map](../docs/consumer-skill/references/com
   a status shown in the page header is not repeated in a card or fact list. Spacing separates a card's header, body and footer; a body separator is appropriate only between distinct body sections.
 - Metrics use numeric values and formatting hints. Context such as “12 orders” belongs in a subtitle; it is not a directional trend. The analytics period changes the KPI strip; comparisons, heatmap and quota data are separately described monthly/current snapshots.
 - Overlay edits start from a snapshot and update committed display state only on Save. Native forms use `formId` so required fields and submission ownership are preserved. App persistence should use the overlay's async contract with pending/error/retry handling before committing; do not bind a draft editor directly to committed record data.
+- Ids for unsaved rows come from a local counter (`useId` plus a ref). `crypto.randomUUID()` exists only in secure contexts and throws on a LAN dev server; let the server assign the real id on save.
 - Local sidebar navigation preserves native link modifiers and closes the mobile drawer. Replace the local route map with your router adapter and record-aware destinations. Sample records across these pages are independent; a customer route is not an order's customer resolver.
 - Choose the component that fits the subject. A lifecycle-specific order item group can use Item; editable permission groups can use ToggleField. Do not replace them with an unrelated block merely to increase the component count.