themelia-react-ui 2.0.5 → 2.0.6

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

@@ -42,7 +42,10 @@ just name components or repeat an archetype.
 
 These criteria allow different product layouts. Do not impose a universal card
 count, row-line limit or one-column form rule. Emphasis is the exception: keep
-one solid primary command per page or surface, so the next action stays obvious.
+one leading primary command per task/surface, so the next action stays obvious.
+Independent forms can each own a primary submit. Fix a warning by reviewing its
+scope and owner; a DOM-lookup submit handler or flattening every FormSection
+does not establish a better composition.
 
 ## Done means
 
@@ -104,11 +107,20 @@ disabled 50% treatment remain valid; component disabled props keep that dimming
 with its owner.
 
 Standalone compact Cards and Page gutter removal also produce review warnings.
-`uncontained-table-in-card` flags a table in a padded Card: place DataTable in
-the layout, or deliberately use Card padding="none" and a flat table.
+`uncontained-table-in-card` follows tables through passive wrappers and known
+slots in padded Card/FormSection/explicit ChartCard surfaces. It also warns on
+tables in card/chart footers: place substantial tables in a body or peer layout
+region, or deliberately use Card padding="none" and a flat table.
+`form-actions-bar-placement` reviews a FormActionsBar under a padded surface or
+in a footer that already owns geometry; put action nodes directly in the footer
+or use an edge-to-edge bar in a zero-padding host. Both remain warnings because
+custom hosts need contextual review.
 `detached-filter-layout` recommends DataTable topbarContent for a sibling filter
 strip, or DataView for the complete workflow. `wide-single-column-form` suggests
-Page narrow for a simple form lacking explicit width or aside. These contextual
+Page narrow for a simple form lacking explicit width or aside. On mixed/tabbed
+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.
@@ -120,9 +132,24 @@ For PageHeader's `slots.actions`, wrapping or returning the callback's
 keyboard, overflow and action semantics. Inspect the compact menu below 40rem of
 header width, including in a narrow parent on desktop: every command, including
 primary, belongs in one More actions menu.
-A Page with more than one solid primary command, counting `header.primaryAction`
-and every Button with `tone="primary"` and no other style, warns as well. Overlays own
-their own primary command and are not counted. Raw palette classes such as
+A Page with more than one solid primary command in the same task scope warns,
+counting `header.primaryAction`, solid Button tone="primary", and
+SubmitStateButton's default primary. Native forms (including a public owner's
+native form `render`) and overlays own separate command scopes; exclusive
+conditional branches use their maximum count. Local submits stay with their
+form. `remote-header-form-submit` reviews header handlers that call
+document.getElementById and requestSubmit, including same-file callback values;
+a deliberate single full-page editor can keep its header submit with native
+validation and appropriate form association.
+
+`heavy-cell-disclosure` reviews Accordion, SmartAccordion, DataTable and CodeBlock
+inside statically visible DataTable `columns.cell` renderers, separately from
+column headers and portaled record details. Prefer a summary plus rowActions
+opening an overlay or detail route; intentional accessible inline disclosure is
+valid. `single-option-choice-group` suggests boolean controls for one static
+choice, without banning two-option sets or filtered real choice domains.
+
+Raw palette classes such as
 `bg-blue-500`, `text-gray-600` or `border-white` warn on any element; use a
 semantic surface/foreground pair or a status tone. A Card title icon and an icon on
 more than one MetadataList fact warn as decoration; keep a glyph only when it
@@ -133,7 +160,9 @@ native button passed as a package owner's `render`, such as an Item row
 rendered as a button, is that owner's root and does not warn.
 Verified Card-owning Metric/card-grid, UsageCard and TaskCard compositions also
 participate in nested-surface and peer-gap review. Metric without its card variant,
-compact MetricGrid, flat TaskCard, ChartCard and Receipt do not establish a frame.
+compact MetricGrid, flat TaskCard, default ChartCard and Receipt do not establish
+a frame. FormSection has a Card by default; ChartCard establishes one only with
+an explicit non-flat surface. Unknown surface values/spreads are not proof of a frame.
 Direct framed/default Card peers, including GridCell-wrapped peers, in a statically
 small Stack/Grid gap also warn; omitted gaps use the actual component defaults.
 Review visible ring clearance and the application's ordinary surface policy.
@@ -148,9 +177,20 @@ Use existing app lint/typechecking for wider language, utility and accessibility
 coverage. The script is deliberately small and does not replace them.
 
 Coverage is limited to direct public imports, aliases/namespaces, native paragraph/
-heading copy and same-file static classes/styles/props. Dynamic expressions are reported as unresolved;
-cross-file wrappers, external CSS, render functions and runtime values require
-review. Do not treat an empty report as proof of complete compliance or taste.
+heading copy and same-file static classes/styles/props/JSX slot values. Paired
+and self-closing elements retain their slot owner; opaque app components and
+known portals form separate regions. Inline cell renderers are inspected when
+their JSX is available, without executing application code. Dynamic geometry,
+classes and spread values are disclosed as unresolved where inspected;
+cross-file wrappers, external CSS and runtime composition require review. Do not
+treat an empty report as proof of complete compliance or taste. Test source
+rules through analyzer findings, and UI behavior through executed outcomes;
+regex assertions over app JSX cannot establish either visual quality or callbacks.
+Local helpers invoked to produce JSX (for example `footerSlot={renderFooter()}`)
+are not evaluated. Dynamically constructed whole header objects are disclosed
+as unresolved; review their action scopes separately. Native ReactDOM
+createPortal calls retain their lexical binding and start a separate rendered
+region, like the supported public overlay owners.
 
 ## Rendered and interaction evidence
 

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

@@ -17,6 +17,27 @@ The complete [order edit page](../examples/rhf-edit-page.tsx) composes:
 
 Page owns the route title/gutters and TwoColumnLayout owns peer rhythm. FormSection owns its surface and field gaps; do not wrap a framed FormSection in another Card. Inside an already padded boundary, use `surface="flat" padding="none"`. Inside an unpadded boundary, a flat FormSection keeps its ordinary inset; flat surface alone does not remove padding. `handleSubmit` validates and awaits persistence. `isSubmitting` drives the submit button and disabled fields; `isDirty` drives dirty feedback and pristine submit protection. An in-flight ref also blocks duplicate same-tick requests. Native form validation is disabled in these RHF examples so the schema/rules produce one consistent error source.
 
+Choose each section's frame from its actual parent. Independent FormSections on
+the page can keep their default card surface; flattening a section whose content
+already consists of Cards does not require flattening unrelated sibling forms.
+
+`FormActionsBar` owns a top divider, opaque background and surface inset. Use
+`leading` for status and `trailing` (or `children`) for action nodes. In
+`Card padding="none"`, flat FormSections keep their body inset and the bar sits
+edge-to-edge after them. In an ordinary Card's `footerSlot` or FormSection's
+`footer`, place the buttons directly: the host already owns the footer geometry.
+`SubmitStateButton` defaults to `type="submit"` and primary tone; pass
+`submitting`, `dirty` and `disableWhenPristine` for pending/pristine behavior.
+
+Independent forms own independent submit commands. Keep a lookup beside its
+input and settings saves with their edited fields; page command guidance does
+not require moving these into `Page.header`. For a single full-page editor, a
+deliberate header submit can use native form association (`type="submit"` and
+`form` on a Button in a supported slot). Preserve browser validation and one
+submit lifecycle; routine `document.getElementById(...).requestSubmit()` handlers
+add unnecessary coupling. Tests should execute validation, pending, error/draft
+retention and accepted persistence rather than assert a particular source string.
+
 Page forwards `render` to its existing Container, so rendering it as the form preserves one width, gutter and query-boundary owner. Its body already spaces direct subjects; no extra Container or Stack is needed around the layout and action bar. `TwoColumnLayout adaptTo="container"` adapts to that Page width. A standalone form outside Page needs its own deliberate query boundary when it selects container adaptation.
 
 Use `useFieldArray`'s stable `field.id` as the React key, preserve names such as `lines.${index}.quantity`, and set complete append defaults. Derive totals from `useWatch`; do not persist a second total that can drift. Collect nested client/server errors into ErrorSummary while keeping each field's local message. Use `setFocus` or summary links for focusable controls when the app's error-summary design requires it.
@@ -40,12 +61,63 @@ Mount an editor with `key={record.id}` when switching records. `defaultValues` e
 | SliderField (public slider name) | scalar `value: number` | `onValueChange(value)`; `inputRef`, `onBlur` |
 | ColorInput | `value: string` | `onValueChange(value)`; input `ref`, `onBlur` |
 
+Set DatePicker's `mode` explicitly when binding its callback. `mode="single"`
+narrows the output to `DateOutput`; range and multiple modes have their own
+value/output shapes. The runtime's single-mode default does not narrow the
+unified callback's contextual TypeScript type.
+
+Bind an empty controlled date field with `value={field.value ?? undefined}`.
+An external reset to that empty value clears single, multiple, range and
+month/year selections. Do not also pass `defaultValue` unless restoring that
+fallback is intentional; RHF's `defaultValues` owns the saved form baseline.
+
 For numeric Input fields normalize `event.target.valueAsNumber` according to the schema (an empty field is NaN); keep numeric validation explicit. Date-only fields need an application serialization policy; do not turn a local calendar date into a UTC instant accidentally. DateTimeInput uses ISO instants. Use `modal={false}` on pickers inside modal forms to avoid competing focus traps.
 
 ControlledFormField accepts a ReactNode error override or a name-based error getter, falling back to RHF validation. Its render callback's error argument remains string/undefined for compatibility. A direct supported control receives the generated label/control ID and supporting-text association automatically; omit routine `htmlFor`/`id` pairs. Each mount stays unique even when forms share field names. ToggleField and SwitchCard own their visible labels and forward the automatic supporting description to their editable control; omit an outer duplicate label.
 
+Use `FormRichTextEditor` from `themelia-react-ui/features/rich-text-editor`
+inside an RHF `FormProvider`. Pass its field name and wrap it in `FormField`
+with the field's validation message. The binding handles touch, focus,
+invalid and disabled state. Both editor modes use the same field association.
+Native form data includes the committed HTML for enabled, named editors.
+Switch from HTML source to rich text to commit a source draft.
+
+WeightInput, DimensionsInput and CoordinatesInput can bind `field.onChange`
+through `onValueChange` and `field.onBlur` through `onBlur`. Their legacy
+event-shaped callbacks still receive the same value. Native `name` submits
+one numeric string, using `widthxheightxdepth` for dimensions and
+`latitude,longitude` for coordinates. The React callback retains the
+selected string or object format.
+
+TimePicker accepts the same direct `value` and `onValueChange` binding
+and submits a named 24-hour value in either mode. Bind `field.onBlur`
+to report leaving the complete picker, including its open popover.
+
+### Empty selections
+
+| Owner | Empty value |
+| --- | --- |
+| PillRadioGroup with `allowClear` | `null` |
+| Combobox and AsyncResourceCombobox | `null` |
+| MultiCombobox | An empty array |
+| Select and RoundingModeSelect with `allowClear` | `undefined` |
+| DateTimeInput | `undefined` |
+| TimePicker | A controlled `null` shows an empty time. Editing emits aligned strings. |
+
+Normalize nullable callbacks at the form boundary when the app uses one
+empty value. An explicit `value={undefined}` keeps PillRadioGroup controlled.
+Omit `value` to use its `defaultValue`. A shared clear sentinel would require
+a major release.
+
 Compound children own their nested association. SliderField's `id` and forwarded `ref` name its group, while `inputRef` names the native range. The binding recipe uses visible copy with an ID, `aria-labelledby` on SliderField and `supportingTextId`/`aria-describedby` for its hint or error. Keep explicit IDs per mount when a passive wrapper separates chrome from the editable control; do not point `htmlFor` at a group or infer one common ref target across control families.
 
+FormField honors an explicit `htmlFor` target already declared in descendant JSX,
+including arrays/fragments, without copying its ID or name onto the outer wrapper.
+It does not inspect custom component bodies. If a compound creates its nested
+controls internally, put it inside Stack or a native container and assign the
+target ID and supporting-text attributes to the actual control. Direct controls
+without an ID retain automatic association.
+
 ## Transport lifecycle
 
 The app owns transport. RHF's submit callback must return a Promise spanning the complete request; otherwise `isSubmitting` drops early and repeated submissions become possible. The [callback bridge](../examples/rhf-transport.tsx) records success/errors/cancellation, then settles only from `onFinish`. It has no framework import or runtime dependency.

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

@@ -4,6 +4,10 @@ The [design contract](design-contract.md) records which geometry changes togethe
 and which variant choices remain independent. Retheme shared responsibilities;
 avoid overriding individual components to imitate another density or inset.
 
+Set the application's document font and page background/foreground through the
+[host CSS setup](installation.md#set-the-application-canvas). Importing package
+styles defines theme roles without painting the document or resetting app markup.
+
 Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration. `--input` is the shared resting control boundary: fields, select and date triggers, checkboxes, radios, switch tracks and outline buttons draw it. Its defaults follow shadcn neutral: `oklch(0.922 0 0)` in light mode and `oklch(1 0 0 / 15%)` in dark mode. `--border` remains the surface/divider role, and `--ring` owns the stronger focus indicator. No extra border variable or component opacity is needed. Resting borders have no blanket 3:1 requirement in this palette; focus retains its separate tested 3:1 contract. When rebranding, review resting, focused and invalid states on the actual surfaces; an application requiring stronger boundaries can override the existing `--input` role.
 
 tokens.json distinguishes 23 structural roots, advanced typography/status settings, and derived utility spellings. A utility is not another public variable. Keep overrides in one stylesheet at root or ThemeScope, without copying computed CSS into JavaScript.
@@ -66,9 +70,10 @@ control heights and copy gaps keep their independent roots.
 | Actions versus fields | `--height-action` versus `--height-control`; default size uses the root times density-scale |
 | Native field text inset | `--control-x` times space-scale; icons/add-ons use shared derived clearance |
 | Collection inline inset | `--row-x` times space-scale |
-| Collection block inset | `--row-y` times density-scale; compact/comfortable use 0.75/1.25 multipliers |
+| Item/table row block inset | `--row-y` times density-scale; compact/comfortable use 0.75/1.25 multipliers where supported |
+| Anchored collection block inset | Default/comfortable use 0.75/1 × `--row-y` × density-scale; compact uses the spacing-scaled 2xs step |
 | Surface tiers | `--surface-x` / `--surface-y`, times space-scale; xs/sm/md/lg use 1/2, 2/3, 1 and 4/3 |
-| Menu header/footer inline inset | Half surface-x plus row-x, then space-scale; no additional public token |
+| Menu header/footer inline inset | Compact bands use the md spacing step; plain header/footer copy adds the xs step. Leading controls and actions stay on the band edge. |
 
 Rich display popovers use the surface roots (24px by default); compact menu/list shells use the md spacing role (8px), scaled once by --space-scale. Row inline padding and density stay independent.
 

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

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "structural": [
     {
       "name": "--space-scale",

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

@@ -44,6 +44,8 @@ export function analyzeComposition(text, { filename, index, ts }) {
   const families = new Map(index.families.map(owner => [owner.import, owner]));
   const bindings = new Map();
   const namespaces = new Map();
+  const portalBindings = new Set();
+  const portalNamespaces = new Set();
   const declarations = new Map();
   const findings = [];
   const unresolved = [];
@@ -135,14 +137,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (names && ts.isNamespaceImport(names)) namespaces.set(symbolFor(names.name), specifier);
   }
   function gather(node) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier) && node.moduleSpecifier.text === 'react-dom') {
+      const names = node.importClause?.namedBindings;
+      if (names && ts.isNamedImports(names)) for (const item of names.elements) if ((item.propertyName ?? item.name).text === 'createPortal') portalBindings.add(symbolFor(item.name));
+      if (names && ts.isNamespaceImport(names)) portalNamespaces.add(symbolFor(names.name));
+      if (node.importClause?.name) portalNamespaces.add(symbolFor(node.importClause.name));
+    }
     if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier) && importsModal(node, ts)) add(node, 'raw-overlay-primitive', 'warning', `${node.moduleSpecifier.text} builds a second dialog system. ${overlayRemedy}`);
     if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) declarations.set(symbolFor(node.name), node.initializer);
+    if (ts.isFunctionDeclaration(node) && node.name && node.body) declarations.set(symbolFor(node.name), node);
     if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) importOwner(node, node.moduleSpecifier.text);
     if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteralLike(node.argument.literal)) importOwner(node, node.argument.literal.text);
     if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && ts.isStringLiteralLike(node.arguments[0])) importOwner(node, node.arguments[0].text);
     ts.forEachChild(node, gather);
   }
   gather(source);
+  const portalCall = node => ts.isCallExpression(node) && (ts.isIdentifier(node.expression) && portalBindings.has(symbolFor(node.expression))
+    || ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'createPortal' && ts.isIdentifier(node.expression.expression) && portalNamespaces.has(symbolFor(node.expression.expression)));
   for (const diagnostic of source.parseDiagnostics) add(source, 'syntax', 'error', ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
   const ownerFor = tag => {
     if (ts.isIdentifier(tag)) return bindings.get(symbolFor(tag));
@@ -157,16 +168,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     const expression = ts.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
     return [[attribute.name.getText(source), expression]];
   });
+  const unknownSpread = (expression, visiting = new Set()) => {
+    const value = resolve(expression);
+    if (!value || !ts.isObjectLiteralExpression(value) || visiting.has(value)) return true;
+    const next = new Set(visiting).add(value);
+    return value.properties.some(property => ts.isSpreadAssignment(property) && unknownSpread(property.expression, next));
+  };
   const isOwner = (owner, suffix, names) => owner?.import === `${index.package}/${suffix}` && names.includes(owner.symbol);
   const framedOwner = (owner, props) => {
-    if (literal(props.get('surface')) === 'flat') return false;
-    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'features/data-view', ['DataView'])) return true;
+    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';
     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;
-  // ChartCard is card-free; Receipt's flat paper has no ordinary Card frame.
+  // ChartCard is card-free by default; Receipt's paper has no ordinary Card frame.
   const contentElements = element => {
     const found = [];
     function collect(child) {
@@ -260,25 +278,43 @@ export function analyzeComposition(text, { filename, index, ts }) {
   };
   // tone="primary" is solid unless a buttonStyle says otherwise; untoned Buttons are neutral.
   const solidPrimary = (opening, owner) => {
-    if (!isOwner(owner, 'base/buttons', ['Button'])) return false;
+    const submit = isOwner(owner, 'base/forms', ['SubmitStateButton']);
+    if (!submit && !isOwner(owner, 'base/buttons', ['Button'])) return false;
     const props = new Map(attributes(opening));
     const style = props.has('buttonStyle') ? literal(props.get('buttonStyle')) : 'solid';
-    return literal(props.get('tone')) === 'primary' && style === 'solid';
+    return (literal(props.get('tone')) ?? (submit && !props.has('tone') ? 'primary' : undefined)) === 'primary' && style === 'solid';
+  };
+  const formRoot = opening => {
+    if (opening.tagName.getText(source) === 'form') return true;
+    const render = resolve(new Map(attributes(opening)).get('render'));
+    return render && (ts.isJsxElement(render) ? render.openingElement : ts.isJsxSelfClosingElement(render) ? render : undefined)?.tagName.getText(source) === 'form';
   };
-  // Overlays are separate surfaces with their own primary command.
+  // A form owns its submit command; overlays and exclusive branches are not
+  // simultaneously competing page commands. Follow same-file slot values only.
   const solidPrimaryCount = root => {
-    let count = 0;
-    const walk = child => {
+    const count = (expression, visiting = new Set()) => {
+      if (!expression) return 0;
+      const child = resolve(expression) ?? expression;
+      if (visiting.has(child)) return 0;
+      const next = new Set(visiting).add(child);
+      if (portalCall(child)) return 0;
+      if (ts.isConditionalExpression(child)) return Math.max(count(child.whenTrue, next), count(child.whenFalse, next));
+      if (ts.isBinaryExpression(child) && [ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(child.operatorToken.kind)) return Math.max(count(child.left, next), count(child.right, next));
       if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
         const opening = ts.isJsxElement(child) ? child.openingElement : child;
         const owner = ownerFor(opening.tagName);
-        if (isOwner(owner, 'features/overlays', overlayOwners)) return;
-        if (solidPrimary(opening, owner)) count++;
+        if (isOwner(owner, 'features/overlays', overlayOwners) || formRoot(opening) || !owner && /^[A-Z]/.test(opening.tagName.getText(source))) return 0;
+        const props = new Map(attributes(opening));
+        if (resolve(props.get('hidden'))?.kind === ts.SyntaxKind.TrueKeyword || props.has('hidden') && props.get('hidden') === undefined) return 0;
+        const children = ts.isJsxElement(child) ? child.children.reduce((total, item) => total + count(item, next), 0) : 0;
+        const slots = [...props].filter(([name]) => !['header', 'render'].includes(name)).reduce((total, [, value]) => total + count(value, next), 0);
+        return Number(solidPrimary(opening, owner)) + children + slots;
       }
-      ts.forEachChild(child, walk);
+      let total = 0;
+      ts.forEachChild(child, item => { total += count(item, next); });
+      return total;
     };
-    ts.forEachChild(root, walk);
-    return count;
+    return count(root);
   };
   const peerCards = element => {
     if (!ts.isJsxElement(element.parent)) return new Set();
@@ -322,18 +358,78 @@ export function analyzeComposition(text, { filename, index, ts }) {
       return smallPeerGaps.has(row ?? gap) || smallPeerGaps.has(column ?? gap);
     });
   };
-  function visit(node, parents = []) {
+  const separateRegion = owner => isOwner(owner, 'features/overlays', overlayOwners)
+    || isOwner(owner, 'base/popover', ['PopoverContent'])
+    || isOwner(owner, 'base/navigation', ['DropdownMenuContent', 'DropdownMenuSubContent', 'ContextMenuContent', 'ContextMenuSubContent'])
+    || isOwner(owner, 'base/combobox', ['ComboboxContent', 'ComboboxPopup'])
+    || isOwner(owner, 'base/choice-inputs', ['SelectPopupContent']);
+  function regionParents(element, parents, context, slot) {
+    if (slot === 'render') return parents;
+    if (separateRegion(context?.owner) || !context && /^[A-Z]/.test(element.tagName.getText(source))) parents = [];
+    return context ? [...parents, { ...context, slot }] : parents;
+  }
+  function visitValue(value, parents, visiting) {
+    if (value) visit(resolve(value) ?? value, parents, visiting);
+  }
+  function visit(node, parents = [], visiting = new Set()) {
+    if (visiting.has(node)) return;
+    const next = new Set(visiting).add(node);
     if (ts.isJsxElement(node)) {
       const element = node.openingElement;
       const context = inspect(element, parents);
-      for (const child of node.children) visit(child, context ? [...parents, context] : parents);
-      // JSX in props is a separate region, not a child frame.
-      for (const attribute of element.attributes.properties) ts.forEachChild(attribute, child => visit(child, parents));
+      for (const child of node.children) visit(child, regionParents(element, parents, context, 'children'), next);
+      for (const [slot, value] of attributes(element)) visitValue(value, regionParents(element, parents, context, slot), next);
+      return;
+    }
+    if (ts.isJsxSelfClosingElement(node)) {
+      const context = inspect(node, parents);
+      for (const [slot, value] of attributes(node)) visitValue(value, regionParents(node, parents, context, slot), next);
+      return;
+    }
+    if (ts.isJsxExpression(node)) { visitValue(node.expression, parents, next); return; }
+    if (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node) || ts.isMethodDeclaration(node)) {
+      const member = ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name) ? node.name.text : undefined;
+      // columns contains header/footer renderers as well as cells. Only a cell
+      // owns the table-row height addressed by heavy-cell-disclosure.
+      const nextParents = parents.map(parent => parent.slot === 'columns' && ['cell', 'header', 'footer'].includes(member) ? {...parent, member} : parent);
+      if (ts.isMethodDeclaration(node)) { if (node.body) visit(node.body, nextParents, next); }
+      else visitValue(ts.isShorthandPropertyAssignment(node) ? node.name : node.initializer, nextParents, next);
+      return;
+    }
+    if (portalCall(node)) {
+      for (const [index, value] of node.arguments.entries()) visitValue(value, index === 0 ? [] : parents, next);
       return;
     }
-    if (ts.isJsxSelfClosingElement(node)) inspect(node, parents);
-    ts.forEachChild(node, child => visit(child, parents));
+    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 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;
+    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;
+  };
+  const remoteSubmit = expression => {
+    const calls = new Set();
+    const walk = (node, visiting = new Set()) => {
+      if (!node) return;
+      const value = resolve(node) ?? node;
+      if (visiting.has(value)) return;
+      const next = new Set(visiting).add(value);
+      if (ts.isCallExpression(value) && ts.isPropertyAccessExpression(value.expression)) {
+        if (value.expression.name.text === 'requestSubmit') calls.add('submit');
+        if (value.expression.name.text === 'getElementById' && value.expression.expression.getText(source) === 'document' && !symbolFor(value.expression.expression)) calls.add('lookup');
+      }
+      ts.forEachChild(value, child => walk(child, next));
+    };
+    walk(expression);
+    return calls.size === 2;
+  };
   // A native element passed as a package owner's `render` is that owner's root, such as
   // an Item row rendered as a button; the owner keeps its focus, hover and row anatomy.
   const renderRoots = new Set();
@@ -375,9 +471,10 @@ export function analyzeComposition(text, { filename, index, ts }) {
       add(node, 'public-symbol', 'error', `${owner.import} does not export ${owner.symbol}.`);
       return;
     }
-    const unresolvedBeforeProps = unresolved.length;
     const props = new Map(attributes(node));
-    const unknownProps = unresolved.length !== unresolvedBeforeProps;
+    // Other reviews can have already disclosed this spread. Deduplication of
+    // unresolved output must not turn an unknown value into a known default.
+    const unknownProps = node.attributes.properties.some(attribute => ts.isJsxSpreadAttribute(attribute) && unknownSpread(attribute.expression));
     const family = owner.import.split('/base/')[1];
     const anatomy = surfaceParts[family]?.test(owner.symbol);
     const forwarder = surfaceForwarders[family] === owner.symbol;
@@ -410,7 +507,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
     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.`);
     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 = framedOwner(owner, props);
+    const framed = !unknownProps && framedOwner(owner, props);
     if (isOwner(owner, 'base/cards', ['Card', 'SmartCard'])) {
       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);
@@ -423,22 +520,36 @@ 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".');
+    if (isOwner(owner, 'base/forms', ['FormActionsBar'])) {
+      const footer = parents.findLast(footerRegion);
+      const padded = parents.findLast(paddedRegion);
+      if (footer || padded) add(node, 'form-actions-bar-placement', 'warning', `FormActionsBar owns a divider, background and inset; ${footer ? `${footer.owner.symbol}.${footer.slot} already owns footer geometry` : `${padded.owner.symbol} already owns body padding`}. Put action buttons directly in the footer slot, or place the bar at the end of the form inside Card padding="none" with flat FormSection siblings. Review intentional custom hosts.`);
+    }
+    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 ((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.`);
+    }
+    if (isOwner(owner, 'base/choice-inputs', ['CardCheckboxGroup', 'CardRadioGroup', 'ListRadioGroup', 'PillRadioGroup'])) {
+      const options = resolve(props.get('options'));
+      if (options && ts.isArrayLiteralExpression(options) && options.elements.length === 1 && !ts.isSpreadElement(options.elements[0])) add(node, 'single-option-choice-group', 'warning', `${owner.symbol} has one static option. For a boolean setting prefer Checkbox, Switch, ToggleField or SwitchCard; retain a genuine choice set whose available options happen to contain one item.`);
     }
     const routeOwner = isOwner(owner, 'layout/page', ['Page']) || isOwner(owner, 'layout', ['Page']);
     if (routeOwner) {
+      for (const name of ['narrow', 'maxWidth']) {
+        const value = resolve(props.get(name));
+        if (value && (ts.isConditionalExpression(value) || ts.isBinaryExpression(value) || ts.isPrefixUnaryExpression(value))) add(props.get(name), 'dynamic-page-measure', 'warning', `Page ${name} depends on an expression and may resize the header and tabs when sections change. Keep the route measure stable and constrain a focused tab panel with Container maxWidth="md" gutter="none"; responsive route sizing can be intentional.`);
+      }
       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 (onlyForms && !unknownProps && !['narrow', 'maxWidth', 'aside'].some(name => props.has(name)) && !hasAsideSlot) add(node, 'wide-single-column-form', 'warning', 'Review this single-column form measure: a focused form can use Page narrow (48rem centered), an explicit maxWidth, or a supporting aside. In a mixed/tabbed route, keep Page stable and constrain only the form panel with Container maxWidth="md" gutter="none".');
     }
     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.');
@@ -447,6 +558,8 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (framed && parents.some(parent => parent.framed)) add(node, 'nested-surface', 'warning', `${owner.symbol} is inside a framed owner. Review subject boundaries; use surface="flat" when the parent owns the frame.`);
     const header = properties(props.get('header'), false);
     const pageOwner = owner.import === `${index.package}/layout/page` || owner.import === `${index.package}/layout`;
+    const headerValue = resolve(props.get('header'));
+    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']);
@@ -454,11 +567,12 @@ export function analyzeComposition(text, { filename, index, ts }) {
     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. Keep one primary per page as header.primaryAction; leave other commands untoned (the neutral button) or list them in secondaryActions.`);
+      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.`);
     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'));