themelia-react-ui 2.0.3 → 2.0.5

package/docs/consumer-skill/references/domain-structures.md

@@ -0,0 +1,124 @@
+# Token-backed domain structures
+
+Use when a business relationship needs its own structure: an allocation ledger,
+stock comparison, schedule, reconciliation or other subject whose arrangement is
+more specific than a ready-made block. Start with [screen decisions](screen-decisions.md)
+and the installed component discovery tools. Mostly compose public base
+components, layout blocks, typography and value primitives; add semantic JSX and
+Tailwind where the subject needs custom tracks, grouping or responsive behavior.
+This is a normal application seam, not a fallback that requires a missing API.
+
+## Divide the work deliberately
+
+| Requirement | Owner |
+| --- | --- |
+| Route identity, commands, gutters and page regions | Page and the chosen app layout |
+| A titled/framed/transparent subject with aligned insets | Card; paint and padding are independent |
+| Routine stack, wrapping actions, equal tracks or column split | Stack, Grid, AdaptiveGrid, TwoColumnLayout |
+| A product-specific comparison, local container adaptation or irregular tracks | App component with semantic JSX and Tailwind on its own elements |
+| Display text and formatted values | Heading, Text, Money, Number, Date and related primitives |
+| Selection, commands, menus, forms and overlays | The relevant public interactive owner and its supported parts |
+| Business calculations, allocation rules and accepted state | App/domain logic or authoritative backend results |
+
+Do not recreate Input, Menu, Button, Card anatomy or keyboard behavior in custom
+markup. An app-owned region can still contain these owners. Extract a component
+when it gives a coherent domain contract; a new file or custom component count
+does not itself improve a screen.
+
+## Choose classes by responsibility
+
+Use `inspect-tokens.mjs` to verify the installed utility spelling and overrideRoot.
+The following are shipped classes, not new variables:
+
+| Intent on app-owned markup | Vocabulary |
+| --- | --- |
+| Close label/supporting copy | `gap-dense`, `gap-normal` or the equivalent Stack gap |
+| Related values/fields | `gap-space-xl` |
+| Separate subjects | `gap-space-2xl` |
+| A custom surface region | `p-surface`, `px-surface`, `py-surface` when that element owns the inset |
+| A custom plain row | `px-row-x`, `py-row-y` when its row inset is required |
+| Layout and responsive geometry | `min-w-0`, `grid`, `grid-cols-[…]`, `@container/name`, named container queries, wrapping and overflow |
+| App surface/foreground | `bg-card text-card-foreground`, `bg-background text-foreground`, `bg-sidebar text-sidebar-foreground` |
+| Quiet copy / structural rule | Text type="secondary" / `border-border` |
+
+Pick the relationship before the size. Page/Card already owning an inset means
+the inner subject does not add `p-surface`. Flat Card retains md padding unless
+explicitly changed; use padding="none" only under another inset owner or for an
+intentional flush region. Transparent and painted peers can use the same inset
+so their heading/body edges align.
+
+Continuous sections can share one padded host and an unpadded internal Stack.
+Separate padded flat Cards can accidentally add bottom inset + peer gap + top
+inset; a valid token on each layer does not justify that combined distance.
+
+Use a local container query when a subject can live in either a main column or
+a narrow aside. Viewport width alone does not establish available space. An
+arbitrary grid track or breakpoint can express product geometry; arbitrary
+spacing, text sizes, radius or state palettes usually recreate a shared role.
+Do not force essential rows into horizontal scrolling merely to retain every
+desktop column. Preserve the important identity/value relationship in the
+narrow composition and keep other detail accessible.
+
+## Customize the theme, not each control
+
+Keep shadcn surface/foreground pairs and use component tone/status props.
+Use Heading/Text props instead of typography classes on imported text owners.
+Use supported sizes/insets on controls and surfaces. Do not add local hover,
+focus, selected or disabled recipes to a public component.
+
+Typography props are not interchangeable: Heading selects semantic level and
+visual size with tag/size; Text has its own supported tags and weight/type
+contract. Inspect the exact export instead of assuming that a prop supported by
+one typography owner exists on another.
+
+Custom table cells retain those primitives' alignment and flow. Match the column
+header and every line of the cell deliberately: a right-aligned Money above
+left-aligned cost copy under a left-aligned header creates three conflicting
+axes. Preserve the table's chosen alignment or use its supported column seam;
+do not assume the surrounding cell overrides a child primitive's own default.
+Keep primary prices/SKUs readable and move secondary detail to its inspection
+subject when it prevents useful comparison.
+
+Canonical roots are the settings: `--space-scale` changes shared gaps/insets;
+`--density-scale` changes action/control/row geometry; `--surface-x` and
+`--surface-y` own surface room. They have different responsibilities. A smaller
+mobile viewport does not automatically justify globally shrinking all of them.
+First repair duplicated insets, wrong group spacing and low-priority content.
+When the product needs a shared responsive spacing policy, set the appropriate
+existing root at its app/theme boundary in CSS and review affected siblings.
+Preserve usable controls and copy; avoid component-specific token copies.
+
+Use derived utilities as classes. Never override or read derived `--spacing-*`,
+`--radius-*` or `--container-*` aliases inside a scoped formula: they resolve at
+the root. If custom drawing needs a formula, derive from the canonical roots
+and apply each scale once. ThemeScope handles scoped/portaled theme inheritance;
+do not copy computed variables through JavaScript.
+
+## Executable example
+
+The [allocation subject](../examples/token-domain-structure.tsx) combines public
+Card/Stack/Text/value owners with an app-owned definition grid. It compares
+reserved quantities across locations, a relationship no block represents. Goods
+that share one fulfillment status and ship-from location, with the commands that
+move them on, are a `FulfillmentGroup` instead; see the
+[order and invoice map](commerce-composition.md). Warehouse groups
+and unavailable quantities stay near their goods. The custom grid changes at
+its own container width; no control or surface recipe is replaced. The caller
+supplies accepted quantities and optional public actions; the example does not
+invent inventory allocation or fulfillment policy.
+
+The [assessment comparison](../examples/custom-composition.tsx) is a smaller
+example, and [commerce lines](../examples/commerce-lines.tsx) demonstrates a
+block's typed content seam. Run these through the consumer checker after
+adapting them. Ensure the app compiles its own Tailwind utilities as described in
+[theming](theming.md); shipped component CSS does not compile app-authored classes.
+
+## Inspect the result
+
+Review actual hierarchy, peer content edges, spacing and wrapping in narrow/wide
+parents, light/dark themes and independently changed spacing/density. Inspect
+the image; zero overflow is not enough. Open a menu/editor in the active scope,
+then verify keyboard/focus, invalid/disabled and accepted/error states. If a
+supported public composition still drifts, report the exact owner and a minimal
+reproduction so the shared component is repaired instead of patched with local
+CSS. See [review](review.md) for separate source, appearance and interaction proof.

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

@@ -1,6 +1,21 @@
 # Installed package and skill setup
 
-Themelia 2.0.3 requires the official `@base-ui/react ^1.9.0` npm peer alongside
+## Choose the CSS path
+
+**Standalone compiled CSS:** import `themelia-react-ui/style.css` once in the app entry. It includes component styles and the documented public utility vocabulary; components work without a host reset, Tailwind processing or private-source scanning. It deliberately omits global preflight. This path does not generate arbitrary utility classes written in app source.
+
+**Tailwind v4 application utilities:** when the app authors Tailwind classes, process this application stylesheet through its Tailwind v4 build integration:
+
+```css
+@import "tailwindcss";
+@import "themelia-react-ui/style.css";
+@import "themelia-react-ui/theme.css";
+```
+
+Tailwind supplies app-generated utilities and its layered preflight; theme.css makes the semantic and structural vocabulary available to that compilation. No package-private source scan is required. The default layer order is `theme, base, components, utilities`. Keep app resets inside `@layer base`; unlayered universal/tag resets outrank layered package styles regardless of import order. Do not blanket-reset `[data-slot]`, which also belongs to third-party and app markup. Put intentional scoped app overrides after these imports. See [integration](integration.md) for an optional app-owned reset and provider setup.
+
+
+Themelia 2.0.5 requires the official `@base-ui/react ^1.9.0` npm peer alongside
 React, React DOM and Lucide. An app already using `^1.9.0` can retain that range.
 Remove any older private Base UI archive pin or override before refreshing the
 lockfile; dismissal translations and nested popup focus belong to Themelia's
@@ -31,27 +46,15 @@ while (true) {
 }
 const installedSkill = path.join(root, 'docs/consumer-skill');
 const selectedSkill = process.env.THEMELIA_SKILL_DIR ?? installedSkill;
-for (const file of ['public-api.json', 'tokens.json']) {
+for (const file of ['public-api.json', 'tokens.json', 'component-contracts.json']) {
   const installed = readJson(path.join(installedSkill, 'references', file));
   assert.equal(installed.package, manifest.name, 'Installed guidance package mismatch');
   assert.equal(installed.version, manifest.version, 'Installed guidance version mismatch');
-  const selected = readJson(path.join(selectedSkill, 'references', file));
-  assert.deepEqual(selected, installed, 'Copied skill is stale; refresh the complete folder');
 }
 if (fs.realpathSync(selectedSkill) !== fs.realpathSync(installedSkill)) {
-  function compareAssets(directory) {
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      if (entry.name === '.DS_Store') continue;
-      const installed = path.join(directory, entry.name);
-      const selected = path.join(selectedSkill, path.relative(installedSkill, installed));
-      const info = fs.lstatSync(installed);
-      assert(!info.isSymbolicLink(), 'Installed guidance must contain real assets');
-      assert(fs.existsSync(selected) && !fs.lstatSync(selected).isSymbolicLink(), 'Copied skill is stale; missing or linked asset');
-      if (info.isDirectory()) compareAssets(installed);
-      else assert(fs.readFileSync(installed).equals(fs.readFileSync(selected)), 'Copied skill is stale; refresh the complete folder');
-    }
-  }
-  compareAssets(installedSkill);
+  const { pathToFileURL } = await import('node:url');
+  const { checkCopiedConsumerBundle } = await import(pathToFileURL(path.join(installedSkill, 'scripts/setup-skills.mjs')).href);
+  checkCopiedConsumerBundle({ packageRoot: root, destination: path.dirname(selectedSkill) });
 }
 // The app's project instructions block records the version it was pasted from.
 const instructions = ['AGENTS.md', 'CLAUDE.md'].find(file => fs.existsSync(file));
@@ -61,7 +64,7 @@ console.log(JSON.stringify({ package: manifest.name, version: manifest.version,
 JS
 ```
 
-Use the reported root for the bundled finder, stylesheet paths and published
+Use the reported root for the bundled finder/inspectors, stylesheet paths and published
 declarations. Install required peers from that manifest and optional peers for
 the exact imported families from `references/public-api.json`. A copied skill's
 finder reports its own metadata version; it does not inspect the app installation.
@@ -71,7 +74,7 @@ running the recipe. The comparison checks metadata contents as well as version,
 so stale copies with the same development version are caught. Every installed
 guidance/script/example asset is also compared byte-for-byte; extra app-owned
 files or publisher markers in the copy are not checked. Keep local product policy
-outside the package guidance. Recopy the complete folder after upgrades, and
+outside the package guidance. Recopy the complete bundle after upgrades, and
 read declarations from the installed package.
 
 `agentsBlock` reports whether the app's `AGENTS.md` (or `CLAUDE.md`) carries the
@@ -102,20 +105,32 @@ need the codemod; `button: { defaultTone: 'primary', defaultButtonStyle: 'solid'
 restores the previous default app-wide. Afterwards, demote extra primaries so
 each page or surface keeps one.
 
-## Manual skill copying
-
-1. Choose an agent skill destination in the user's configured skills directory,
-   named `themelia-react-ui-consumer`. For Codex the usual destination is
-   `~/.codex/skills/themelia-react-ui-consumer`; honor a configured alternative.
-2. Copy the **entire** installed `docs/consumer-skill` directory, including
-   references, scripts and examples. Do not copy only SKILL.md or merge files from
-   different releases. Preserve an existing user-customized copy before replacing it.
-3. Run the identity recipe with `THEMELIA_SKILL_DIR` pointing to that copy. Invoke
-   `$themelia-react-ui-consumer` or let the agent select it by task context.
-
-Copying into an agent's global skill directory is a separate user-requested
-action; reading these instructions does not perform or authorize it. The npm
-package does not install a skill automatically. Run the consuming app's own
-type/lint/test/build scripts after integration; repository check scripts are not
-installed consumer commands. See [integration](integration.md) for workflow and
-opened-surface verification.
+## Copy the complete skill bundle
+
+The package ships four focused capabilities, one compatibility/shared root and one agent definition. One copy of API/token/contract metadata, scripts and examples is shared by all three. Do not copy only an individual SKILL.md or duplicate the generated indexes into each skill.
+
+When the user requests installation, run the bundled copy helper with their configured agent skills directory. For Codex the usual destination is `~/.codex/skills`; honor a configured alternative:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination "$HOME/.codex/skills"
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination "$HOME/.codex/skills"
+```
+
+It copies `themelia-components`, `themelia-tokenization`, `themelia-composition`, `themelia-design`, and `themelia-react-ui-consumer` as real sibling directories. Rich templates are copied once under the shared directory. Markdown links are rebased for this installed layout; no symlinks or repository paths are required. Existing canonical/shared destinations are rejected before writing: preserve or move the previous complete bundle before an upgrade, then copy the release together. `--check` compares every expected asset after rebasing, so stale content with an unchanged development version is caught.
+
+### Copy the designer agent
+
+`docs/consumer-skill/agents/themelia-ui-designer.md` is a Claude Code agent definition: a product designer that reads the records, writes a view spec, builds with public owners, renders 390 and 1440 wide in light and dark, scores the critique rubric and fixes. Its body reads skills and scripts through `node_modules/themelia-react-ui/...`, so it works wherever the skills were copied; other agents can follow it as a prompt. When the user requests it, copy it into the project's agents directory with the skills or on its own:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --agents .claude/agents
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --agents .claude/agents
+```
+
+An existing `themelia-ui-designer.md` is never overwritten; move it before copying a newer release. Other agent files are left untouched.
+
+The package retains `docs/consumer-skills/themelia-foundation/SKILL.md` and `themelia-forms/SKILL.md` as compatibility routers. They are not added by fresh copying. Existing legacy or unrelated skills are left untouched; review older agent routing separately when upgrading. Keep app policy outside the copied package bundle.
+
+For the identity recipe above, set `THEMELIA_SKILL_DIR` to the copied shared `themelia-react-ui-consumer` directory. In project instructions, use the generated [AGENTS.md block](agents-md.md) pointing at package skills, or point the four skill paths to their copied siblings. Invoke `$themelia-components` for setup, discovery and typed APIs/forms; `$themelia-tokenization` for themes and shared visual roles; `$themelia-composition` for screen hierarchy, workflows and visual repair; and `$themelia-design` for data briefs, view specs and rubric-scored critique of rendered views. The compatibility `$themelia-react-ui-consumer` entrypoint remains available.
+
+Copying into an agent's global skill directory requires a user request. The npm package does not perform installation automatically. Run the consuming app's own type/lint/test/build scripts after integration; repository maintainer commands are not installed consumer commands.

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

@@ -1,6 +1,6 @@
 # Integration
 
-Install required peers from the installed package.json; public-api.json records required/optional peers. Install optional peers for the imported families, including base families such as charts and QR code. Whole-family declaration requirements can exceed a tree-shaken runtime graph; follow the exact family's index and declarations. Import style.css once before overrides; it omits preflight, so the app supplies its reset. Basic controls must not pull in unrelated map/editor/chart dependencies.
+Install required peers from the installed package.json; public-api.json records required/optional peers. Install optional peers for the imported families, including base families such as charts and QR code. Whole-family declaration requirements can exceed a tree-shaken runtime graph; follow the exact family's index and declarations. Import style.css once before overrides; it omits global preflight and components remain usable without a host reset. Use the [installation CSS paths](installation.md#choose-the-css-path) when generating app utilities. Basic controls must not pull in unrelated map/editor/chart dependencies.
 
 Put global resets in the lower-priority `base` layer, or use your framework's layered preflight. The package uses the `theme, base, components, utilities` layer order. Unlayered rules outrank layered component styles regardless of import order; a global `button { font: inherit }` can replace the library's control size and weight. For an app-owned reset:
 
@@ -18,7 +18,7 @@ Load intentional, scoped app overrides after the package stylesheet. Keep broad
 
 UIProvider supplies stable mount-time defaults: explicit prop, provider default, fallback. Per-mount requests/data/callbacks stay on components. ThemeScope from themelia-react-ui/ui-provider places descendant portals inside its CSS boundary. A styled div does not relocate body portals; explicit Base UI portal containers take precedence.
 
-Framed card regions are ruled apart by default. To separate them by spacing
+Cards omit the header rule and keep the footer rule by default. To separate them by spacing
 alone, configure the single application provider with
 `card: { defaultHeaderDivider: false, defaultFooterDivider: false }`.
 Explicit Card booleans override these defaults. Ordinary card
@@ -33,6 +33,41 @@ the installed contract. Fix that app policy through its own review rather than
 compensating with card or field padding. Bounded AppSidebar instances use h-full
 inside the shell's constrained column; standalone sidebars may use viewport height.
 
+Use one LayoutSidebarProvider for AppLayout's primary and secondarySidebar
+slots. Named scopes infer each AppSidebar/LayoutSidebar panel ID. Keep
+desktop openPanels separate from mobilePanel, the single active undocked drawer;
+update controlled props from their matching callbacks. Controlled openPanels
+takes precedence over legacy primary open. Target essential supporting panels
+with SidebarTrigger panelId, and use navigationPanel for the ordinary navigation
+trigger/shortcut. The WorkspaceRegionsLayout recipe accepts primaryNavigation
+and sidebarPresentation="rail" for a SidebarNavigationRail beside contextual
+navigation, with grouped primary navigation as an alternative. It demonstrates
+named state without a router dependency or another UIProvider. Inset framing
+does not supply Page padding, and shell header slots take Header partials.
+An embedded provider with adaptTo="container" contains its drawer and backdrop.
+Use one explicit trigger for the inline full navigation beside the static left
+area rail. Choose the contextual AppSidebar/LayoutSidebar `collapsible`
+independently of the shell preset or sidebar skin: `icon` retains a second
+compact column, `offcanvas` hides that panel and leaves only the primary rail,
+and `none` keeps it expanded. Keep the static primary rail on its own `none`
+policy. Current examples default to `icon` with a preview selector, and
+standalone sidebars support the same choices. The copied
+WorkspaceRegionsLayout recipe exposes `contextualCollapsible` with an `icon`
+default; a secondarySidebar replacement owns its own mode. The app's
+area-selection callback opens the corresponding contextual panel.
+At narrow widths the inline cluster pans a minimum
+page canvas, with its area rail pinned, and preserves expansion state. Shared
+header, navigation and Page owners supply spacing. Dedicated area rails use the
+background surface and an adjacent divider; their width is independent of
+full-sidebar icon collapse.
+
+SidebarNavigationRail shares AppSidebar's header, beforeNavigation,
+afterNavigation and footer render slots. Header/footer stay pinned and
+before/after content scrolls. Searchable AppSidebar retains its search band in
+icon mode; its search button expands and focuses the field. Current
+matching chooses the most-specific href and exposes ancestor state separately
+to custom item renderers.
+
 For RTL, pair the native DOM direction with `DirectionProvider` from the same
 entrypoint. Native `dir` owns text flow and logical CSS geometry; the provider
 owns Base UI keyboard navigation and popup positioning. It does not set `dir`.
@@ -113,3 +148,7 @@ both container content edges without global preflight; Container and DataTable
 own border-box sizing. Stabilize lifecycle inputs as explained in
 [workflows](workflows.md#scoped-directory). These are example/runtime proofs,
 not evidence of an independent agent choosing the same composition.
+
+## Form transport and router adapters
+
+Use [RHF workflows](rhf-workflows.md#transport-lifecycle) for frontend state with Inertia callback visits or TanStack async mutations. Await the complete transport before resetting dirty state or closing an overlay. The framework stays in the app. `renderLink` on AppSidebar/Page headers adapts the app router: forward href, children, className, accessible/native attributes and onClick; preserve modifier/new-tab behavior and invoke the supplied click handler so mobile navigation can close. Use the [typed shell recipe](../examples/app-layout.tsx) for the exact public renderLink type rather than inventing a router prop. React Router Link, Inertia Link and TanStack Link each need an app adapter matching their own installed version.

package/docs/consumer-skill/references/product-composition.md

@@ -0,0 +1,94 @@
+# Product composition capability map
+
+Compare the product's actual tasks with these public contracts before writing
+JSX. A product view may combine existing owners and custom domain content; a new
+wrapper name or a similar screenshot does not establish a missing capability.
+Inspect exact types through `inspect-component.mjs`, including the prop/slot you
+intend to use. The app owns authoritative data, permissions and persistence.
+
+## Product view responsibilities
+
+| Task and input contract | Existing owner and supported seam | App responsibility / reason to extend |
+| --- | --- | --- |
+| Product identity, facts and optional supporting regions | `ProductOverview` from `themelia-react-ui/features/products`: `details`, `options`, `variants`, `readiness` and named `slots` | Choose only relevant regions. Page still owns route identity/commands/gutters. Add a domain subject through a region slot when its relationships need a different structure. |
+| Product imagery within identity | `ProductOverview.details.media`; a standalone region can use `slots.mainTop` | There is no top-level `ProductOverview.media` prop. `details.media` also supports a media-only subject; no dummy facts are required. |
+| Color/size definitions and their values, independently from a table | `ProductOptionsMatrix`: `optionGroups`, editing/collapse state, awaited `onSaveEditingOption`, `onError`, cancellation, `renderValue`, `renderOptionActions` | Preserve IDs, reconcile accepted changes with sellable variants and historical orders, and apply validation/transport. Do not replace this editor with custom buttons just to rename/remove values. |
+| Definitions and variant rows in one coordinated subject | `ProductVariantsManager`: `optionGroups`, `variants`, editing/grouping/selection state, row/bulk callbacks and render seams; `showGroupBy={false}` drops the Group by control for a short list. Each option's summary row is its edit button; `renderOptionActions` adds explicit commands | Its convenience arrangement is a choice. Supply accepted rows and real commands; it does not invent combinations or warehouse policy. Use separate matrix/table owners when placement needs to differ. |
+| Compare sellable SKUs, prices, availability and status | `ProductVariantsBulkTable`: `visibleColumns`, `groupByOptionId`, `cellDisplay`, `renderCell`, row and bulk callbacks. `ProductVariantsTable` supplies a simpler variant list. | Pass meaningful values and stable IDs. For one stock figure the inventory cell may suffice; keep per-location reservations or shortages as a richer related subject. |
+| Inspect the selected SKU and its chosen options | `ProductVariantDetails`: `variant`, `metadata`, `media`, `renderMetadata`, `renderOption`, `footerSlot` and action callbacks | Keep its identity/actions while adding warehouse, costing or allocation evidence through an appropriate slot or sibling region. A custom fact does not require rebuilding the whole variant subject. |
+| Edit ordinary variant fields and selected option choices | `ProductVariantEditor`: controlled/default values, `optionFields`, `statusOptions`, `visibleFields`, per-field `errors`, app-owned `children` fields, awaited `onSubmit`, `submitting`, `onError`, cancel and footer. Inside `ActionDrawer`, share one `formId` and set `showHeader={false}` so the drawer owns the title and commands | App validates and returns accepted state. Its inventory field is one string; hide it with `visibleFields={{ inventory: false }}` and add per-warehouse balances or unit cost as `children`, which render inside the form before its commands. |
+| Upload new local product images | `MediaGallery` from `themelia-react-ui/base/media-gallery`: controlled `File[]`, `onValueChange`, MIME/extension acceptance, file limit, previews, removal and keyboard/drag sorting | Transfer and persistence remain app-owned. The first file is the cover. This is not a persisted URL-record gallery. |
+| Existing images attached to a product | `MediaResourceGallery` from `themelia-react-ui/features/media-library`: `items`, typed `accessors`, `primaryId`, primary/remove/reorder callbacks, `onAdd`, `readOnly` and `renderItem` | Adapt existing IDs/URLs; accept attachment changes through app state/transport. Do not fetch remote URLs merely to manufacture `File` objects. |
+| Search/select reusable assets or upload into an asset catalogue | `MediaLibrary` or `MediaLibraryDialog`: item accessors, controlled selection, fetch/upload handlers and picker callbacks | The app owns catalogue requests and attachment persistence. A simple local file field does not require this complete workflow. |
+
+For a simple single-SKU product, omit option-definition/combination work that the
+model does not have. For an optioned product, definitions, sellable combinations
+and a selected variant are different jobs; they need not be three custom cards.
+The [products template](../../../templates/products-template.tsx) demonstrates
+the larger public workflow. Its data and callbacks are examples, not your
+product's business rules. Deprecated standalone product region-card exports are
+compatibility APIs; use ProductOverview regions or the dedicated active owners.
+
+## Media identity and lifecycle
+
+Ask whether the input is a new browser `File[]` or already stored asset records.
+Both can belong to a product gallery. The finder query `product media gallery`
+therefore exposes both owners; `local product images` and `existing product
+images` narrow the decision. Inspect their value and callback types before
+choosing one.
+
+MediaResourceGallery's accessors can read the app's own keys, filenames, image
+URLs and alt text. It owns its frame, title and insets; use it as the region
+surface instead of nesting it inside another Card. Choose `layout="grid"` or `"list"` to expose primary and
+move commands; the compact `"field"` layout focuses on attachment/removal.
+`onReorder` proposes IDs and records in the next order; these move controls differ
+from MediaGallery's drag/keyboard file sorting. `onAdd`
+usually opens the app's existing MediaLibraryDialog flow. Read-only presentation
+needs no attachment commands.
+
+`renderItem` replaces a complete gallery item, including its default controls.
+Use it for an actual media-representation requirement, such as a supplied sprite
+crop, while retaining the gallery's collection ownership. Reuse public buttons
+and the render context's permitted primary/remove/move actions if the custom
+item remains editable. A regular image URL needs no custom tile implementation.
+
+## Existing owners and domain-specific structure
+
+The comparison above is not a rule to force every product into ProductOverview
+or to forbid custom components. Record the required task, candidate, inspected
+prop/callback/render seam and remaining mismatch. For example, a warehouse
+comparison may extend ProductVariantDetails.renderMetadata or sit beside it;
+option name/value editing already has ProductOptionsMatrix. Keep controls,
+focus, action states and ordinary text roles with their public owners.
+
+Return the actual save Promise from ProductOptionsMatrix/Manager's
+`onSaveEditingOption`. The owner keeps the editor pending, retains a rejected
+draft with retry feedback, and requests closure through
+`onEditingOptionIdChange` after acceptance or cancellation. `onError` can report
+the failure to the app. Do not close/reset before the Promise settles or swallow
+the rejection in a fire-and-forget wrapper.
+
+Stock reservation arithmetic, option-to-variant reconciliation, unique SKU
+validation, accepted prices and publication policy belong to the app. Changing
+today's catalogue never rewrites a purchased order's selected options or prices.
+A thumbnail, a file picker, an attached-asset gallery and a selected variant's
+media slot have different contracts even if they show the same photograph.
+
+## Executable product parts
+
+The [product parts recipes](../examples/product-parts.tsx) show real option IDs,
+save/cancel editing, a variant comparison with SKU/price/availability values,
+the coordinated manager and a details/editor flow that retains a failed draft
+until the caller returns accepted values. The option-only example edits local
+definitions; it deliberately does not claim to reconcile a complete catalogue.
+
+The [product media recipes](../examples/product-media.tsx) contrast caller-owned
+File[] with typed persisted-asset accessors and attachment callbacks.
+`MediaOnlyProductOverview` uses the actual details.media slot without dummy
+metadata. No recipe changes a URL record into a File or imports private source.
+
+Verify the chosen configuration: edit then cancel/save an option, preserve its
+ID, select a different variant, inspect its media/stock, reject and retry a
+variant save, change a cover/remove/reorder assets when supported, and inspect
+narrow/wide light/dark output. Source typechecks, a retrieved symbol and the
+presence of a callback do not prove those interactions or useful composition.