themelia-ui 3.1.0 → 3.2.0

package/.agents/skills/themelia-ui/references/migration.md

@@ -3,6 +3,25 @@
 What changes between versions, what to do when you upgrade, and which changes a stable major
 allows.
 
+## Upgrading to 3.2
+
+3.2 adds consumer diagnostics, complete reference workflows and optional `scopeKey` support
+for asynchronous combobox lookups, alongside responsive grid, dialog and navigation fixes.
+Applications already on 3.1 need no new codemod replacements. Applications upgrading from
+3.0 or earlier must also follow [Upgrading to 3.1](#upgrading-to-31).
+
+After updating the package, refresh the installed consumer skill with the
+[packaged installer](verification.md#offline-diagnosis-and-skill-freshness). Review any
+local edits before replacing them, then run the read-only diagnostics and your application's
+type, build and interaction checks. The [structural guide](structure-and-spacing.md),
+[blocks guide](blocks.md) and [complete workflows](reference-workflows.md) describe the
+public composition contracts.
+
+For lookups whose results depend on a workspace, tenant or similar context, pass a stable
+`scopeKey` that changes with that context. The lookup aborts and invalidates old responses;
+the application still owns clearing a selection or query that is no longer valid. See the
+[scoped resource selection workflow](reference-workflows.md).
+
 ## Upgrading to 3.1
 
 3.1 renames and removes public API as well as adding to it. Upgrade deliberately, not
@@ -83,8 +102,9 @@ selects `[data-row-density]`, `[data-media-density]` or `[data-activity-density]
 colour a `light-dark(light, dark)` pair. For a theme of your own:
 
 - Declare it on `:root` alone. The selector list 3.0 asked for (`:root, [data-ui-scope],
-  [data-density], [data-theme], .light, .dark`) is not needed: nothing below `:root` declares a
-  theme variable again.
+  [data-density], [data-theme], .light, .dark`) is not needed: component styles inherit the
+  root defaults. Explicit regional overrides and density presets replace their corresponding
+  inherited values; set a preset-specific spacing override on that preset.
 - Write a dark value into the colour's pair, `--primary: light-dark(#2563eb, #60a5fa)`, rather
   than a `.dark { … }` block, which colours a dark page but misses a dark region inside a light
   one.

package/.agents/skills/themelia-ui/references/provider-and-scoping.md

@@ -1,5 +1,11 @@
 # Provider and scoping
 
+Choose one document density owner, then use UIScope for a deliberately different region.
+Changing density changes spacing; keep primary copy in Text and headings in Heading or their
+component owners. Check the last field/next heading together: CardContent, FormSection and
+Stack can each contribute separation. A portal must stay inside its intended token scope;
+UIPortalHost provides that boundary. Test open popups as well as the page beneath them.
+
 Three components, and the difference between them is what they are allowed to touch.
 
 | | Renders | Reaches | Use for |
@@ -71,8 +77,10 @@ value, and a value is replaced, not merged.
 
 That is the configuration components read, and the CSS follows it: each scope writes the
 merged overrides on its element, so inside the nested scope above `--primary` is red and
-`--secondary` is green. Nothing below `:root` declares a theme variable again, so every value
-inherits through any element, a `Scope` or a `data-density` region included; see
+`--secondary` is green. Component styles inherit global tokens rather than redeclaring
+theme defaults. Explicit Scope/UIScope overrides replace inherited values; a density preset
+also resets its spacing and control heights on that region. A value outside that boundary
+does not override its local declaration; see
 [Theming](theming.md#setting-a-theme).
 
 ## Scope — tokens only
@@ -85,17 +93,18 @@ inherits through any element, a `Scope` or a `data-density` region included; see
 </Scope>
 ```
 
-`Scope` renders a `div` without layout. `render` picks another element, as on every
-component (`render={<section />}`), and `transparent={false}` gives it a box. Every
+`Scope` renders a `div` without layout. Its `render` prop picks another element
+(`render={<section />}`), and `transparent={false}` gives it a box. Every
 component inside reads the variables it sets, because components compute from the theme where
 they use it; any element with a `style` does the same, and `Scope` only adds the missing
 layout rule and the `data-ui-scope` marker.
 
 ## Portals and scopes
 
-A scope works through CSS custom properties and the `[data-density]` / `[data-theme]`
-attribute selectors, and both inherit down the DOM subtree. A portal renders elsewhere in the
-document, so by default neither follows it:
+A scope uses CSS custom properties; its `data-density` and `data-theme` attributes establish
+spacing and colour-scheme values that inherit through the DOM subtree. The attributes
+themselves are not copied to descendants. A portal renders elsewhere in the document, so
+those inherited values do not follow it by default:
 
 ```tsx fragment — a template with a hole in it
 <UIScope config={{ density: "compact" }}>
@@ -136,7 +145,7 @@ in — a shadow root, or a positioned overlay element it manages itself.
 
 ## Strict Content Security Policy
 
-Some Base UI-backed controls emit a tiny inline style or pre-hydration script for behavior
+Some Base UI-backed controls emit a tiny inline style element or pre-hydration script for behavior
 the component stylesheet cannot express. Put `CSPProvider` at the same application boundary
 as `UIRoot` and pass the request nonce through:
 
@@ -154,7 +163,7 @@ React 19 hoists styles that carry `precedence`. During streaming SSR, configure
 renderer with the same style nonce as the provider; otherwise React omits the attribute and
 warns about the mismatch.
 
-When the policy permits no inline elements at all, suppress Base UI's style elements and
+When the policy forbids inline style elements, suppress Base UI's style elements and
 ship the scrollbar rule in the consuming application's stylesheet:
 
 ```tsx fragment — App comes from the consuming application
@@ -171,6 +180,15 @@ ship the scrollbar rule in the consuming application's stylesheet:
 `disableStyleElements` does not disable kit behavior; it moves those small rules into the
 consuming app. It does not change how the kit's CSS loads.
 
+This option does not remove inline scripts or `style` attributes. A nonce authorizes the
+matching style/script elements; it does not authorize style attributes in server-rendered
+HTML. Providers, responsive structure and popup positioning can use style attributes, so
+a policy that blocks them needs a separate SSR strategy for the adopted components.
+Inspect the rendered HTML and browser CSP reports; `disableStyleElements` alone does not
+establish compatibility with that policy. See the
+[Base UI CSP reference](https://base-ui.com/react/utils/csp-provider#inline-style-attributes)
+for the distinction and available integration strategies.
+
 ## Reading the config
 
 Resolution, in every component:

package/.agents/skills/themelia-ui/references/reference-workflows.md

@@ -0,0 +1,43 @@
+# Complete reference workflows
+
+These sources use public package imports and fixed local mock operations. Copy the complete
+workflow directory, including relative helpers, then replace its transport and policy with
+your application's. The versioned inventory (`node_modules/themelia-ui/docs/generated/workflows/index.json`) lists every
+file, import and API reference. Its package version must match the installed package.
+
+| Workflow | Owners and application seam | Complete entry source |
+| --- | --- | --- |
+| Record detail | Page owns route heading; sibling Cards own subjects; MetadataList owns facts; app owns record commands | Record detail (`node_modules/themelia-ui/docs/generated/workflows/record-detail/page-layout/record-detail-reference.tsx`) |
+| Server resource index | DataView owns browser presentation; app owns server matching, unknown totals, cursor and page selection | Resource index (`node_modules/themelia-ui/docs/generated/workflows/resource-index/data-view/resource-index-reference.tsx`) |
+| Multi-section form | Card owns surface; flat FormSections retain insets; FieldGroup and FormField own names; app owns validation and completion | Form (`node_modules/themelia-ui/docs/generated/workflows/multi-section-form/form-workflow/multi-section-reference.tsx`) |
+| Scoped resource selection | ResourceCombobox owns lookup; app owns scopeKey and selection validity; Overlay owns task | Selector (`node_modules/themelia-ui/docs/generated/workflows/scoped-resource-selection/combobox/scoped-resource-reference.tsx`) |
+| Nested action flow | Parent owns draft; child owns confirmation; app closes explicitly after successful mutation | Nested action (`node_modules/themelia-ui/docs/generated/workflows/nested-action-flow/action-overlays/nested-action-reference.tsx`) |
+| Workspace navigation | Shell owns geometry; workspace owns disclosure; app owns router and same-app policy | Workspace (`node_modules/themelia-ui/docs/generated/workflows/workspace-navigation/app-shell/workspace-navigation-reference.tsx`) |
+| Media picking | MediaLibraryDialog owns query/picking UI; app commits a separate picker draft on confirmation, pages through footer slots, hydrates saved ids independently, reports unavailable selection and authorizes fetches | Media (`node_modules/themelia-ui/docs/generated/workflows/media-picking/media-library/media-picking-reference.tsx`) |
+| Communications overview | MetricGrid owns quantities; MetadataList owns prose facts; app owns period, delivery state and retry | Communications (`node_modules/themelia-ui/docs/generated/workflows/communications-overview/analytics/communications-reference.tsx`) |
+| Website editor | RichTextEditor owns editing; app retains locale drafts and alt text; RichText sanitizes preview | Website editor (`node_modules/themelia-ui/docs/generated/workflows/website-content-editor/rich-text-editor/website-content-reference.tsx`) |
+
+Forms using plain state need no form peer. The optional forms-rhf adapter connects existing
+React Hook Form state without duplicating it. The resource-index workflow uses features/table and
+needs its table peer; record-detail uses peer-free base/table; analytics and rich editing require the peers listed in their generated
+API pages. The general reference consumer stays free of optional peers; the admin reference
+consumer demonstrates adopted adapters.
+
+Pending, empty, failed refresh, unavailable selection and resolved validation errors are
+different states. These fixtures demonstrate local feedback and retained drafts. They do
+not establish real persistence, permissions, cache invalidation or backend sanitization.
+Exercise the named cases in your app; [record the evidence](verification.md#completion-record)
+and identify conditions you could not inspect.
+
+The inventory's `verification` entries map required cases to behavioral tests or visual
+inspection conditions. They specify coverage to run, not a claim that your application passed.
+`repositoryFile` identifies a maintainer test in the source repository; copy workflow files
+from the inventory's generated source list and adapt the named behaviors to your test runner.
+The browser cases use explicit mock actions; the read-only observer supplies advisory geometry
+findings. Review screenshots and semantics separately in both themes and densities at mobile,
+desktop and wide widths, including long copy and RTL. Build/type checks prove the complete
+sources and public imports; rich-text security tests exercise the sanitization boundary.
+
+When embedding a contained app shell in an existing main landmark, use `contentRender={<div />}`
+so the composition keeps one main. For a shell that owns the application's main, omit that
+override. The reference uses the embedded form because it also appears inside a documentation page.

package/.agents/skills/themelia-ui/references/structure-and-spacing.md

@@ -0,0 +1,147 @@
+# Structure and spacing
+
+Choose the semantic owner first, then arrange its siblings. A Page owns route geometry;
+Card owns an independent subject; ContentBlock owns supporting content; FormSection owns
+an editable region. Stack and Grid arrange those owners without adding a heading, landmark,
+surface or inset. See [Composition](composition.md#decide-the-owners-before-jsx) for names,
+commands and field ownership, and [Blocks](blocks.md) for ready subject arrangements.
+
+## Choose a structural block
+
+| Need | Public owner | What it supplies |
+| --- | --- | --- |
+| Route title, description and commands | `Page` from `layout/page` | Container, page header and body rhythm. It does not create a main landmark or own scrolling. |
+| Page scroll inside a bounded shell | `PageViewport` from `layout/containers` | Scroll region and an inline-size query container. Focusable by default for keyboard scrolling. |
+| Centred width and inline gutter | `Container` from `layout/containers` | Width and gutter only. Page already includes it. |
+| Semantic section with rhythm between groups | `Section` from `layout/containers` | A native section and twice the group gap; supply its heading or accessible name. |
+| Primary work beside a secondary summary | `TwoColumnLayout` from `layout/containers` | Main/aside arrangement, optional full-width header/footer; stacks below `lg`. Aside stays second in the DOM. |
+| One row or column of passive siblings | `Stack` from `base/structure` | Direction, gap, alignment, distribution and optional wrapping. No padding prop. |
+| An explicit column count | `Grid` and `GridCell` from `base/structure` | One to four columns, responsive gaps and cell spans. |
+| As many equal columns as fit | `AdaptiveGrid` from `base/structure` | Auto-fit tracks; `minColumnWidth` is `default` (16rem), `sm` (12rem) or a CSS length. |
+| A fluid main region and a constrained rail | `Split` from `base/structure` | Two direct children: main first, side second. `sideWidth` defaults to 18rem; `collapseBelow` defaults to `md`. |
+| Intentional edge-to-edge content in an inset | `Bleed` from `base/structure` | Negative margins on the selected axis. Match `amount` to the inset it cancels. |
+
+Read the exact structure API (`node_modules/themelia-ui/docs/generated/components/base--structure.md`),
+containers API (`node_modules/themelia-ui/docs/generated/components/layout--containers.md`) and
+page API (`node_modules/themelia-ui/docs/generated/components/layout--page.md`) before adding props. Container's
+`maxWidth` (`sm`, `md`, `lg`, `xl`, `2xl`, `full`) and `gutter` (`none`, `sm`, `md`, `lg`)
+are a different contract from Stack/Grid widths (`default`, `sm`, `full`, `none` or a CSS
+length). Container gutters are zero, one, one-and-a-half or twice `--padding`; they do not
+add spacing tokens. Stack/Grid `maxWidth` caps width without centring it or adding a gutter.
+
+An app shell normally owns the single main landmark and page scroller. Do not add another
+PageViewport around each section. For document scrolling without a bounded shell, Page can
+live in the application's existing main. When embedding a shell inside another main, use
+its documented `contentRender` seam; see [complete workflows](reference-workflows.md).
+
+## Use the two spacing roles
+
+| Role | Public tokens | Typical use |
+| --- | --- | --- |
+| Container inset | `--padding` | Card regions and decorated ContentBlocks |
+| Item inset | `--padding-sm` | Rows, cells and compact items |
+| Between groups | `--gap`, `gap="default"` | Fields, sibling Cards, sections |
+| Within a group | `--gap-sm`, `gap="sm"` | Title/description, icon/label, toolbar controls |
+
+The omitted structure gap is `default`. `gap="none"` removes separation; it is not a third
+spacing step. Insets belong to the child surface and gaps to the parent arrangement. Avoid
+giving both the same separation job. Density changes these lengths together; it does not
+choose smaller text roles. [Theming](theming.md#scale-and-density) explains density, scale
+and typography scale, including overriding a preset's values.
+
+CardContent supplies its inset and a group gap between direct children; it drops its top
+padding after an undivided CardHeader. Card `surface="flat"` removes decoration and retains
+region insets. FormSection is a Card composition, so a flat FormSection inside CardContent
+still adds its own inset. Use `Stack gap="none"` between such sections when their insets
+already supply the intended rhythm; do not assume flat means flush.
+
+ContentBlock is different: its default `surface="plain"` supplies heading/content spacing
+without an inset or frame. Its `bordered`, `muted` and `card` surfaces add an inset.
+`flush` drops that decorated surface's inset for children that own their own padding.
+Neither flat nor flush changes field associations or heading semantics.
+
+```tsx compile
+import { Card } from "themelia-ui/base/cards"
+import { ContentBlock, MetadataList } from "themelia-ui/base/display"
+import { Grid, Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { Page } from "themelia-ui/layout/page"
+import { TwoColumnLayout } from "themelia-ui/layout/containers"
+
+export function AccountOverview() {
+  return <Page header={{ title: "Account" }} maxWidth="lg">
+    <TwoColumnLayout
+      main={<Stack>
+        <Grid columns={{ base: 1, md: 2 }}>
+          <Card title="Contact" titleLevel={2}>
+            <MetadataList items={[{ id: "email", label: "Email", value: "alex@example.com" }]} />
+          </Card>
+          <Card title="Billing" titleLevel={2}>
+            <MetadataList items={[{ id: "status", label: "Status", value: "Active" }]} />
+          </Card>
+        </Grid>
+        <Card title="Notes" titleLevel={2}>
+          <ContentBlock description="Context for the next account review.">
+            <Text>The customer prefers email updates.</Text>
+          </ContentBlock>
+        </Card>
+      </Stack>}
+      aside={<Card title="Summary" titleLevel={2}><Text>Review due next month.</Text></Card>}
+    />
+  </Page>
+}
+```
+
+The example has one route heading, three independent subjects in the main region and a
+secondary summary. Page supplies the gutter; TwoColumnLayout supplies main/aside separation;
+Stack/Grid separate subjects; each Card supplies its inset. The complete record and form
+workflows add application-owned commands, validation and asynchronous states.
+
+## Know which width drives responsiveness
+
+A responsive structure prop accepts a single value or an object such as
+`gap={{ base: "sm", md: "default" }}`. Values carry forward until another named step replaces
+them; omitted lower steps use the component's defaults. `sm` as a gap value means the small
+gap; `sm` as an object key means a breakpoint.
+
+| Step | Viewport minimum | Grid's nearest query-container minimum |
+| --- | --- | --- |
+| `base` | All widths | All widths |
+| `sm` | 40rem | 24rem |
+| `md` | 48rem | 32rem |
+| `lg` | 64rem | 40rem |
+| `xl` | 80rem | 52rem |
+| `2xl` | 96rem | 64rem |
+
+Grid uses viewport steps when no ancestor establishes inline-size containment. With a query
+container, such as PageViewport or ContentBlock, Grid's columns, gaps, alignment and maximum
+width use the nearest container and the smaller thresholds above. Grid does not create its
+own query container. Stack, Split, Bleed, AdaptiveGrid's responsive gap/alignment and
+GridCell spans use viewport steps. AdaptiveGrid's **column count** always follows available
+width through auto-fit. TwoColumnLayout stacks below the viewport's `lg` step.
+
+Grid defaults to one column and two from `md`; `columns={1}` stays one at every width.
+Use `GridCell span="full"` for a full row at every width. Numeric spans must fit the current
+column count; `span={{ base: 1, md: "full", xl: 2 }}` can switch between numeric and full
+placement. Coordinate responsive spans with the Grid, especially inside a query
+container where their thresholds differ. Prefer AdaptiveGrid when the available panel width
+should decide the count without coordinating breakpoints. Visual side positioning in Split
+or TwoColumnLayout does not change reading or keyboard order.
+
+## Bleed, custom CSS and verification
+
+Bleed's default amount is `none` and its default axis is `inline`. An intentional image
+escape can use `amount="default"` inside an inset of `--padding`, or `sm` inside
+`--padding-sm`. The shipped spacing pairs have matching padding/gap values; a custom theme
+that separates those values must account for the actual inset. Bleed does not create a
+surface or crop media. Check edges and focus visibility in the surrounding surface.
+
+Application-specific geometry can use `className` and CSS over public tokens; use the
+documented props first. Do not target private `--_…` variables or CSS Module hashes. Keep
+copy in Text/Heading and field labels in FormField rather than setting local type styles.
+For product CSS, prefer logical properties so inline start/end follow RTL.
+
+Check a narrow **parent** as well as a narrow viewport, long headings and translated labels,
+both themes and densities, and keyboard access to the scroller. Verify that additional
+surfaces or gaps serve an independent subject. [Consumer verification](verification.md)
+separates compiled examples, interaction evidence and visual inspection.

package/.agents/skills/themelia-ui/references/theming.md

@@ -3,7 +3,8 @@
 The theme is about eighty variables, declared once at `:root` in `src/styles/theme/`. Each
 colour holds both modes as `light-dark(light, dark)`, and every length, shadow, tint and
 duration comes as a pair. Components derive everything else where they use it, so a value
-you set anywhere reaches every component below it. `src/styles/TOKENS.md` (`node_modules/themelia-ui/src/styles/TOKENS.md`)
+you set on a region reaches its descendants unless another scope or preset overrides it.
+`src/styles/TOKENS.md` (`node_modules/themelia-ui/src/styles/TOKENS.md`)
 names the variable for each role.
 
 ## Setting a theme
@@ -22,7 +23,8 @@ for both modes:
 ```
 
 That one block reaches every region, including popups portalled to `<body>` and a dark
-region inside a light page: nothing below `:root` declares a colour again.
+region inside a light page. Component styles do not redeclare theme colour defaults;
+an explicit regional theme override takes precedence within that region.
 
 The same values work on any element, for a region of their own:
 
@@ -139,6 +141,8 @@ and headings fall back to the interface font.
 Compose title and description regions with CardHeader, ContentBlock or OverlayHeader, action
 regions with CardFooter or OverlayFooter, and label/value facts with MetadataList. These
 components own their spacing, so the application does not reproduce it.
+See [Structure and spacing](structure-and-spacing.md) for the owner and responsive-width
+contracts before changing layout values.
 
 ## Scale and density
 

package/.agents/skills/themelia-ui/references/troubleshooting.md

@@ -1,5 +1,22 @@
 # Troubleshooting
 
+Before patching a shared component, trace its callers and inspect one representative of
+every affected surface. Recheck open portals, nested forms and small screens when shared
+spacing or naming changes. Use the [read-only diagnosis and completion record](verification.md)
+to distinguish contract errors, advisory composition findings and unavailable coverage.
+
+## A lookup still shows another workspace
+
+Set `scopeKey` on ResourceCombobox, SuggestionsCombobox or useSuggestions. Callback identity is not an invalidation API.
+The key invalidates answers and errors while keeping query/open/value ownership; explicitly
+clear a selected id if it is invalid in the new scope. See the [complete selector](reference-workflows.md).
+
+## Validation resolves but the dialog closes
+
+Set `closeOnAsyncComplete={false}` and close controlled `open` after successful validation
+and mutation. Use `formId` for native submission and keep one mutation owner. Nested child
+cancel/Escape should leave the parent draft visible; verify focus returns to the child invoker.
+
 ## A component is unstyled
 
 A component brings its own CSS in a bundler. When it arrives unstyled:
@@ -74,8 +91,8 @@ listed there, report it as a package containment defect.
 
 ## A theme or density override does not apply
 
-Every theme variable is declared once, at `:root`, and inherits from wherever you set it. When
-an override does not show:
+Theme defaults are declared at `:root` and inherit until an explicit scope override or
+density preset establishes another value. When an override does not show:
 
 - **Is it the theme's name?** A 3.0 name such as `--space-md`, `--control-h` or
   `--primary-10` is gone; the codemod renames or reports each one, and
@@ -121,6 +138,10 @@ set `disableStyleElements` and serve the documented Base UI behaviour rules from
 stylesheet. The kit's stylesheets are ordinary static CSS. See
 [Provider and scoping](provider-and-scoping.md#strict-content-security-policy).
 
+If the report names `style-src-attr`, a nonce or `disableStyleElements` will not authorize
+server-rendered style attributes. Inspect the adopted components' SSR output and use the
+separate attribute-policy strategy described in that guide.
+
 In a bundled app the kit's CSS follows your own pipeline: stylesheet files in production,
 while a dev server or `style-loader` that injects `<style>` elements needs the nonce, as your
 own CSS does.
@@ -128,11 +149,13 @@ own CSS does.
 ## The design looks inconsistent after overrides
 
 Override global semantic tokens first: colour roles, radius, spacing and density,
-typography, and control geometry. Component-level variables are implementation detail
-unless the module reference describes one as an extension point. Do not target hashed CSS
+typography, and control geometry. Variables prefixed `--_` are private implementation detail.
+Use a component-level variable only when its module reference documents a public extension
+point. Do not target hashed CSS
 Module names; use the stable `data-slot` attributes and BEM hooks such as
 `{name}--component`, and for a state the attributes the primitives set (`data-open`, `data-checked`, `data-disabled`,
-`data-highlighted`, `data-popup-open`). Radix's `[data-state="open"]` matches nothing here.
+`data-highlighted`, `data-popup-open`). Do not assume Radix's `[data-state="open"]` for Base
+UI primitives. Use a module's own `data-state` only when its API documents that contract.
 
 ## Rich text and untrusted HTML
 

package/.agents/skills/themelia-ui/references/verification.md

@@ -32,8 +32,9 @@ test("global search returns focus after dismissal", async ({ page }) => {
 Prefer role- and name-based assertions over CSS Module selectors. When a visual or state
 assertion needs a DOM hook, use `data-slot`, documented BEM hooks, or the state attributes
 the primitives set (`data-open`, `data-checked`, `data-disabled`, `data-highlighted`,
-`data-popup-open`). These are Base UI's attributes, not Radix's: `[data-state="open"]`
-matches nothing.
+`data-popup-open`). Use Base UI's documented attributes for its primitive states rather
+than assuming Radix's `[data-state="open"]`. Some kit modules expose their own `data-state`
+contract; use it only where the selected API documents it.
 
 ## Theme contract check
 
@@ -41,6 +42,61 @@ Create one application fixture that changes primary colour, surface/background r
 radius, density, and typography scale at a scope boundary. If a component ignores it, report
 the module and token before adding a local patch: the package may be missing a derivation.
 
+## Offline diagnosis and skill freshness
+
+Run the commands from the package installed in this application:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=. --check --json
+node node_modules/themelia-ui/scripts/consumer/diagnose.mjs --project=. --json src/
+```
+
+Both checks are read-only. Diagnostics use the consumer's installed TypeScript parser and
+the package's generated export/migration facts. Supply explicit paths. Unsupported formats,
+parse failures, missing paths, metadata or parser produce exit 2 (incomplete); definite
+contract errors produce exit 1; complete checks without errors produce exit 0. Advisory
+composition/private-style warnings do not establish a defect. Excluded build/dependency
+directories and symlinks are not followed. Reports name the checked and skipped rules/files.
+
+Freshness reports expected and installed versions plus missing, stale, modified or unmanaged
+copies. Review modifications before reinstalling a generated copy. The installer refuses local edits
+until `--overwrite-modified` explicitly replaces reviewed generated content. Keep application policy
+in a separate skill; an unmanaged same-name skill is preserved. Missing metadata requires
+repairing the package installation or consulting the matching release, never inventing an API.
+
+If an installed copy's manifest is missing or invalid, the installer repairs it automatically
+only when its remaining files match the packaged content. Differing or extra files require
+review and `--overwrite-modified`, just like edits to a copy with a valid manifest.
+
+Replacements are staged before writes, and caught write failures restore backups. An abrupt
+process termination can leave mixed versions across targets and sibling `.backup-*` or
+`.installing-*` directories. Run `--check`, review those retained directories, preserve any
+local policy, and reinstall the intended generated copies. A backup-cleanup error means the
+new copies were installed; the error names the retained backup for review and manual cleanup.
+
+The browser observer (`node_modules/themelia-ui/docs/build/browser-composition-fixture.ts`) accepts an already open caller
+fixture and observes overflow, repeated sibling headings and control visibility. It performs
+no navigation, click or submission. These geometry/semantic observations are advisory; they
+do not establish accessibility or business acceptance. Optional browser tooling belongs in
+the application's test dependencies, not the UI runtime.
+
+Opt into interaction tests only against explicit mock actions. The [complete workflows](reference-workflows.md)
+provide scoped late responses, pending/empty/error lists, nested cancel, resolved validation,
+workspace selection and retained locale drafts. Assert keyboard selection without accidental
+form submission, one Escape layer at a time, focus return, associated errors and explicit
+successful completion. Do not crawl unknown application routes or submit business forms.
+
+## Completion record
+
+Record installed package/skill versions; selected owners and seams; shared callers inspected;
+fixture routes and states; viewport widths; themes, densities and locales; keyboard/focus
+interactions; commands and observed results. Separate type/build evidence, behavior tests,
+visual inspection and application acceptance. Name unavailable conditions explicitly.
+
+When no browser is available, report types/build/static findings and mark interaction and
+visual checks unverified. Passing named static/browser checks does not establish permissions,
+data integrity, persistence, backend sanitization or every product workflow.
+
 ## Upgrade check
 
 Read the changelog (`node_modules/themelia-ui/CHANGELOG.md`), run the package's codemod when a release names one

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 3.2.0 — 2026-10-04
+
+- Skill installation preserves edits when installed metadata is missing and keeps installed
+  copies intact if backup cleanup fails. Diagnostics check namespace accesses, escaped CSS
+  imports and private variables from core styles.
+- Nested action success closes both layers; nested-action and media references use packaged
+  triggers to restore focus in Safari. Escape leaves a modal child in control when its parent
+  is nonmodal. Scope changes abort old lookups before committed layout callbacks.
+- The media-picking reference commits replacement ids only after explicit confirmation.
+- Responsive GridCell spans support `full` at individual breakpoints and restore numeric spans.
+- Consumer guides cover structural owners, spacing, responsive widths and subject blocks;
+  framework guidance distinguishes ordinary SSR from React Server Components boundaries.
+- Mobile workspace disclosure keeps navigation open until a same-app destination is selected.
+- ResourceCombobox, SuggestionsCombobox and useSuggestions accept `scopeKey` to invalidate
+  asynchronous lookups while retaining controlled selection and query state.
+- Open combobox lists guard Enter during loading, empty results and IME composition;
+  nested native dialogs preserve their parent's draft and focus on child dismissal.
+- Nine complete public-API reference workflows cover record details, server collections,
+  forms, scoped lookups, nested actions, navigation, media, communications and rich content.
+- Context-aware discovery, ownership guides and the generated consumer skill share those
+  sources. Skill checks report version and content drift; reinstalling local edits requires
+  explicit `--overwrite-modified`.
+- The packaged read-only diagnostic command checks imports and stylesheet contracts,
+  reports conservative composition warnings and identifies incomplete analysis.
+
 ## 3.1.0 — 2026-09-28
 
 This release renames and removes public API. Read

package/README.md

@@ -314,11 +314,14 @@ Guides:
 - [Theming and Tailwind CSS v4](docs/learn/theming.md)
 - [Provider and scoping](docs/learn/provider-and-scoping.md)
 - [Composition](docs/learn/composition.md)
+- [Structure, spacing and responsive widths](docs/learn/structure-and-spacing.md)
+- [Choosing and composing blocks](docs/learn/blocks.md)
 - [Framework wiring](docs/learn/framework-wiring.md)
 - [Forms](docs/learn/forms.md)
 - [Localization](docs/learn/i18n.md)
 - [Troubleshooting](docs/learn/troubleshooting.md)
 - [Verifying a consuming application](docs/learn/verification.md)
+- [Complete reference workflows](docs/learn/reference-workflows.md)
 
 Reference, generated from the source when the package is built. It ships in the package
 under `node_modules/themelia-ui/docs`, and the links open the latest published copy:

package/dist/{alert-dialog-Bmo1YrTm.js → alert-dialog-Cg2HhuBe.js}

@@ -1,5 +1,5 @@
 import { t as e } from "./cx--CBrhWH0.js";
-import { n as t, r as n } from "./overlay-C8RAgi2_.js";
+import { n as t, r as n } from "./overlay-BuQOl8aP.js";
 import "react";
 import { jsx as r } from "react/jsx-runtime";
 //#region src/components/base/alert-dialog/alert-dialog.tsx

package/dist/base/alert-dialog.js

@@ -1,2 +1,2 @@
-import { i as e, n as t, r as n, t as r } from "../alert-dialog-Bmo1YrTm.js";
+import { i as e, n as t, r as n, t as r } from "../alert-dialog-Cg2HhuBe.js";
 export { r as AlertDialogAction, t as AlertDialogCancel, n as AlertDialogContent, e as AlertDialogMedia };

package/dist/base/cards.js

@@ -1,3 +1,3 @@
 "use client";
-import { a as e, c as t, i as n, n as r, o as i, r as a, s as o, t as s } from "../cards-DdiICdMM.js";
+import { a as e, c as t, i as n, n as r, o as i, r as a, s as o, t as s } from "../cards-Ddhz43Bz.js";
 export { n as Card, r as CardActionStrip, e as CardContent, i as CardFooter, o as CardHeader, a as CardPrimaryAction, s as CardSkeleton, t as defaultCardStrings };

package/dist/base/choice-inputs.js

@@ -1,3 +1,3 @@
 "use client";
-import { _ as e, a as t, b as n, c as r, d as i, f as a, g as o, h as s, i as c, l, m as u, n as d, o as f, p, r as m, s as h, t as g, u as _, v, x as y, y as b } from "../choice-inputs-CCw-0gD6.js";
+import { _ as e, a as t, b as n, c as r, d as i, f as a, g as o, h as s, i as c, l, m as u, n as d, o as f, p, r as m, s as h, t as g, u as _, v, x as y, y as b } from "../choice-inputs-NwRxvmZN.js";
 export { t as CardCheckboxGroup, f as CardRadioGroup, y as Checkbox, c as ListRadioGroup, m as PillRadioGroup, b as Radio, n as RadioGroup, h as Select, r as SelectIconPrimitive, l as SelectPopupContent, _ as SelectPopupGroup, i as SelectPopupItem, a as SelectPopupLabel, p as SelectPopupSeparator, u as SelectRoot, s as SelectTriggerPrimitive, o as SelectValuePrimitive, v as Switch, g as SwitchCard, d as ToggleField, e as defaultSelectStrings };

package/dist/base/combobox.js

@@ -1,3 +1,3 @@
 "use client";
-import { C as e, E as t, S as n, T as r, _ as i, a, b as o, c as s, d as c, f as l, g as u, h as d, i as f, l as p, m, n as h, o as g, p as _, r as v, s as y, t as b, u as x, v as S, w as C, x as w, y as T } from "../combobox-Byu8N-Oe.js";
+import { C as e, E as t, S as n, T as r, _ as i, a, b as o, c as s, d as c, f as l, g as u, h as d, i as f, l as p, m, n as h, o as g, p as _, r as v, s as y, t as b, u as x, v as S, w as C, x as w, y as T } from "../combobox-519ubijc.js";
 export { h as ComboboxArrow, v as ComboboxBackdrop, f as ComboboxChip, a as ComboboxChips, g as ComboboxChipsInput, y as ComboboxClear, s as ComboboxCollection, p as ComboboxEmpty, x as ComboboxGroup, c as ComboboxGroupLabel, l as ComboboxInput, _ as ComboboxInputTrigger, m as ComboboxItem, d as ComboboxItemIndicator, u as ComboboxList, i as ComboboxPopup, S as ComboboxPopupInput, T as ComboboxPortal, o as ComboboxPositioner, w as ComboboxRoot, n as ComboboxSeparator, e as ComboboxStatus, C as ComboboxTrigger, r as ComboboxValue, t as defaultComboboxStrings, b as useComboboxFilter };

package/dist/base/command.js

@@ -1,3 +1,3 @@
 "use client";
-import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c, u as l } from "../command-CnB_IZSo.js";
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c, u as l } from "../command-JjApYFds.js";
 export { c as Command, i as CommandDialog, o as CommandEmpty, n as CommandGroup, e as CommandInput, a as CommandItem, s as CommandList, t as CommandSeparator, r as CommandShortcut, l as defaultCommandStrings };

package/dist/base/date-pickers.js

@@ -1,3 +1,3 @@
 "use client";
-import { a as e, c as t, d as n, f as r, i, l as a, m as o, n as s, o as c, p as l, r as u, s as d, t as f, u as p } from "../date-pickers-C2HgjpFU.js";
+import { a as e, c as t, d as n, f as r, i, l as a, m as o, n as s, o as c, p as l, r as u, s as d, t as f, u as p } from "../date-pickers-BwCwKIVM.js";
 export { n as Calendar, p as DatePicker, f as DatePickerFooter, s as DatePickerHeader, u as MonthYearPicker, i as MultipleDatePicker, e as RangeDatePicker, c as SingleDatePicker, t as TimePicker, d as createRangePresets, r as defaultCalendarStrings, l as defaultDatePickerStrings, o as defaultRangePresetStrings, a as defaultTimePickerStrings };

package/dist/base/dialog.js

@@ -1,3 +1,3 @@
 "use client";
-import { t as e } from "../dialog-0nRFg5Zs.js";
+import { t as e } from "../dialog-CAnwRNrm.js";
 export { e as DialogContent };

package/dist/base/display.js

@@ -1,3 +1,3 @@
 "use client";
-import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g, v as _ } from "../display-BGN834xV.js";
+import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g, v as _ } from "../display-a7AoX_u7.js";
 export { i as BooleanIndicator, o as Collapsible, a as CollapsibleContent, e as CollapsibleTrigger, c as ContentBlock, n as DateBlock, g as IconBadge, h as InlineStat, t as Kbd, d as KbdGroup, u as MetadataList, s as MetadataValue, m as PlaceholderPattern, l as ScrollArea, _ as Separator, r as VisuallyHidden, f as defaultBooleanIndicatorStrings, p as defaultMetadataListStrings };

package/dist/base/forms-numeric.js

@@ -1,3 +1,3 @@
 "use client";
-import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g } from "../forms-numeric-C6NMdj6G.js";
+import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g } from "../forms-numeric-IwQ1ltNf.js";
 export { n as CURRENCY_SYMBOLS, s as CoordinatesInput, m as CurrencyInput, g as DecimalInput, t as DimensionsInput, h as MoneyInput, c as PercentageInput, u as RoundingModeSelect, d as WeightInput, r as applyRounding, f as defaultCoordinatesInputStrings, l as defaultCurrencyInputStrings, o as defaultDecimalInputStrings, a as defaultDimensionsInputStrings, p as defaultRoundingModeStrings, e as defaultUnitInputStrings, i as formatDecimal };

package/dist/base/forms.js

@@ -1,3 +1,3 @@
 "use client";
-import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c, u as l } from "../forms-NxbJK4Mh.js";
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c, u as l } from "../forms-C0WeNPFF.js";
 export { c as DirtyStateBanner, i as ErrorSummary, r as FieldGroup, o as FormActionsBar, l as FormField, n as FormSection, e as SubmitStateButton, a as defaultDirtyStateBannerStrings, s as defaultErrorSummaryStrings, t as defaultSubmitStateButtonStrings };

package/dist/base/item.js

@@ -1,3 +1,3 @@
 "use client";
-import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c, u as l } from "../item-CuUJyETl.js";
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c, u as l } from "../item-M2pmpWXh.js";
 export { c as Item, i as ItemActions, o as ItemContent, n as ItemDescription, e as ItemFooter, a as ItemGroup, s as ItemHeader, t as ItemMedia, r as ItemSeparator, l as ItemTitle };

package/dist/base/navigation.js

@@ -1,3 +1,3 @@
 "use client";
-import { a as e, c as t, d as n, f as r, g as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "../navigation-BTX5Ti0Z.js";
+import { a as e, c as t, d as n, f as r, g as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "../navigation-Bgu7Vc0M.js";
 export { s as Breadcrumbs, m as LanguageSwitcher, f as NavigationTabs, l as OverflowTabBar, u as PageHeading, p as Pagination, h as Tab, n as TabList, r as TabPanel, d as Tabs, c as defaultBreadcrumbsStrings, o as defaultNavigationTabsStrings, e as defaultOverflowTabBarStrings, a as defaultPaginationStrings, i as defaultTabListStrings, t as paginationRange };

package/dist/base/otp-input.js

@@ -2,7 +2,7 @@
 import "#core.css";
 import { c as e } from "../typography-DmeR05Er.js";
 import { t } from "../cx--CBrhWH0.js";
-import { d as n } from "../display-BGN834xV.js";
+import { d as n } from "../display-a7AoX_u7.js";
 import * as r from "react";
 import { jsx as i, jsxs as a } from "react/jsx-runtime";
 import { OTPField as o } from "@base-ui/react/otp-field";