themelia-react-ui 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,170 @@
+# Composition
+
+The [design contract](design-contract.md) separates application layout freedom
+from library-owned anatomy. Use supported props and slots inside shared surfaces;
+keep placement, width, wrapping and overflow with the surrounding composition.
+
+| Need | Owner |
+| --- | --- |
+| Headings, prose, labels, links | Typography |
+| Money, date, identity, contact, empty values | Primitives |
+| Identity/title/description/actions row | Item |
+| Label/control/hint/error | FormField |
+| Visible surface and card-level actions | Card |
+| Peer gaps and responsive columns | Stack, Grid, GridCell, AdaptiveGrid |
+| Page/application regions | Layout |
+| Reusable subject presentation | Blocks |
+| Editing/selection/async lifecycle | Features with app callbacks |
+
+Use the exact family declarations from public-api.json. Catalogue URLs and source folders are not import contracts.
+
+## Card anatomy
+
+Card surface="card" is the ordinary bordered surface; surface="framed" retains its ring recipe; surface="flat" padding="none" composes within an existing boundary. headerPlacement="frame" places title/icon/actions above an inset body, retaining default corners and using rounded-inner on that body.
+
+Use titleSuffix for status/count/version badges. Long titles/suffixes wrap through the shared owner; no literal spaces/local margins to manufacture gaps. headerAction/actions are trailing controls, headerStart pre-title context. footerSlot/footer definitions own card-level actions; footerDivider owns the rule and inset. Do not simulate a footer inside children. SmartCard and ContentBlock are deprecated migration names; use Card in new code.
+
+Reusable blocks/features stay card-free unless their explicit purpose is a card. Frame them at the composition boundary.
+
+## Structure and spacing
+
+Shells own gutters, surfaces own padding, sections own rhythm, Stack/Grid own sibling gaps, typography owns none. Prefer gap/padding/size props to local appearance overrides.
+
+Grid exposes viewport columns; AdaptiveGrid responds to parent width and a semantic minimum column size. GridCell spans belong to the nearest Grid. Keep narrow DOM order meaningful. Horizontal Stack wraps by default; disable it only when overflow is intentionally handled. Tailwind is appropriate for min-w-0, positioning, overflow and drawing geometry.
+
+## Menus and controls
+
+PopoverContent type="display" owns substantive-content padding; type="menu" compact collection padding around already-padded rows. Popover and Command share inset="default" and inset="compact" paradigms. Mixed searchable shells use inset="flush"; public header/search/list/footer anatomy owns its insets automatically. CommandInput composes the public Input for control geometry and focus styling; its search region adds only outer spacing. Do not pass padding through className, contentClassName or inline styles. Compact header controls and footer actions align with row highlight edges; header text and footer captions align with row labels. Use PopoverHeader start for a leading control and PopoverFooter caption for supporting content alongside trailing action children. Dividers use the same semantic recipe. density selects vertical row rhythm without changing inline padding. ActionMenu owns action definitions, PopoverMenu searchable selection, DropdownMenu bespoke menu anatomy. Shared appearance preserves their accessible menu/listbox/dialog behavior.
+
+| Choice | Responsibility |
+| --- | --- |
+| PopoverContent type="display" / type="menu" | Display versus collection anatomy and typography |
+| inset="default" / "compact" | Full versus half surface-root inset |
+| inset="flush" | Delegate insets to owned regions; not a density |
+| density="compact" / "default" / "comfortable" | Collection row block rhythm, independent from inline spacing |
+| size="sm" / "md" / "lg" | Supported control's scale; consult its declaration and provider precedence |
+
+PopoverContent defaults to display/default; Command defaults to compact. An explicit PopoverContent type controls anatomy; explicit inset controls padding and takes precedence over the type's inferred inset. Without type, compact implies menu, other insets imply display. Put type="menu" inset="flush" on PopoverContent for a headed searchable picker. Popover is the interaction root and receives no surface props. PopoverMenu already assembles that picker anatomy; use its declared selection/search props. ComboboxPopup is flush because ComboboxList owns its inset. Do not add another wrapper inset around a normal collection list.
+
+At shipped roots, compact shell padding is 8px; row inline padding is 12px; default row block padding is 8px and minimum height 36px. Compact/comfortable rows use 6/10px block padding and 32/40px minimum heights. Content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer shell padding matches the list (8px inline). Header text bodies without a leading control and footer captions add the row inset once, aligning text at 20px. Actions keep the 8px shell edge. Nested public slots do not repeat these insets.
+
+Input frames use the input semantic token; collection dividers use border/60; focus uses ring separately. Equal responsibilities share recipes, while different semantic roles retain their own treatment. CommandInput keeps its existing onValueChange search contract and native refs; use the actual public Input through its default composition rather than restyling an unframed native field.
+
+ActionMenu density="table" remains a legacy table/overflow adapter. AsyncPreview padding="lg" owns a compatibility content boundary. Neither expands the default/compact surface vocabulary.
+
+Button separates tone from buttonStyle (solid, outline, ghost). ActionButtons renders the same definitions as ActionMenu. Badge tones describe actual states, not a decorative palette.
+
+## Migration
+
+Use exact themelia-react-ui paths. Presentation imports use blocks/<family>, replacing composed/<family>. Raw UI, Radix, cmdk and routers are not consumer foundations. Read installed types instead of assuming historical CSS-kit props.
+
+
+## Copy rhythm
+
+For title/supporting-copy rhythm use `textGap="normal" | "dense"` on Card,
+PageHeading and public surface headers; normal is 8px and dense is 4px before
+spacing scaling. Item/ItemContent and menu popover headers default to dense.
+Stack/Grid accept the same semantic gaps, including responsive objects and
+axis overrides. Keep surface insets and action-cluster gaps on their owners;
+do not add a second margin to descriptions.
+
+## Receipts
+
+Import `Receipt` and `ReceiptItems` from `themelia-react-ui/blocks/commerce/receipt`. Receipt is an explicit paper surface: use its `header`, `footer`, `qrCode` slots and Card-backed `padding`; compose the body with Stack, MetadataList, Separator and Money. No extra Card or copied surface padding is needed. Pass authoritative line `total` values when discounts or tax have already been calculated; `unit`, currency, locale and formatting follow Money. The fallback quantity × unit price is display convenience, not an accounting engine. QRCode is an optional app composition from `themelia-react-ui/base/qr-code`; ordinary receipts need none of its optional peers. See [the installed receipt recipe](../examples/receipt.tsx).
+
+
+## Hierarchies, capture and guided forms
+
+Use `themelia-react-ui/base/tree` for inline hierarchy navigation/selection, and
+`themelia-react-ui/base/cascader` for choosing a path in an anchored picker. Values
+must be unique and stable throughout the tree; labels are presentation.
+Cascader supports drill, columns and tree modes. Opening a resolved selection
+reveals its ancestors. Nested drill/column headers provide a back caret;
+returning remembers the departed branch and aborts its pending child request.
+Backspace in an empty search returns while retaining input focus. The active
+keyboard cursor is independent of multiple selection. Supply
+`loadChildren(node, { signal })` for unloaded branches. The picker caches loaded
+children for stable data/loader identities; the app owns network requests and
+backend policy. A picker search covers known nodes, not undiscovered server data.
+Tree defaults to single-line compact navigation rows, sharing Sidebar row
+geometry and logical child insets. Density does not shrink primary text.
+Use `rowLayout="rich"` explicitly for supporting copy and wrapping; put
+non-interactive badges or metadata in node `trailing` for ordinary rows. `branchActivation="toggle"` makes directories open on
+activation while leaves retain selection. `AiFileTree` from `themelia-react-ui/blocks/ai`
+uses that hierarchy and remains card-free: add Card at the framing boundary.
+Use `expandedIds`/`onExpandedIdsChange` independently of `selectedId`/`onSelect`;
+file ids are globally unique and file opening stays app-owned.
+Selection and disclosure are distinct state contracts. See the installed
+[hierarchy/capture recipe](../examples/hierarchy-capture.tsx).
+
+`SignaturePad` retains normalized structured strokes and an optional typed-name
+alternative. Store its value through `onValueChange`; use the ref for history,
+clear/focus or PNG/SVG/JSON serialization. The application owns persistence and verification. Use our
+FormField/Card at the composition boundary, without additional internal padding.
+
+`Questionnaire` is a guided form workflow. Supply typed questions, conditional
+visibility and validation; the app supplies `onSubmit(answers, { signal })`.
+Hidden answers remain available when editing, but hidden/disabled questions are
+excluded from validation and submission. Submission supports busy, cancellation,
+error/retry and completion states. Native form reset and controlled answers are
+separate supported contracts. Do not replace the form's internal button actions
+with application request state.
+Keep the question schema and unchanged controlled answers referentially stable
+(module constants or `useMemo`). Replacing either object invalidates the active
+request and completion state; unrelated parent renders should reuse them.
+
+## Files, code and messages
+
+Use `Attachment` for file presentation in lists, compact chips or galleries.
+Use `onOpen` for the whole-body preview trigger or `onPreview` for an explicit
+preview action; download/remove actions remain independent. Supply preview
+content through your application's overlay composition. With custom children,
+keep independent controls in `AttachmentActions`. Upload queues offer
+cancel for queued/uploading files when supplied, or queued removal when only
+removal is available. Omit uploading progress for indeterminate transfers.
+It supplies shared status/progress, filename, size and file-kind rendering;
+preview/download/remove are application callbacks. FileUpload and upload queues
+use that same anatomy, keeping validation, queue state and transfer callbacks
+on their existing owners. URLs and object-URL cleanup remain app-owned.
+
+`CodeBlock` owns code surface, scrolling, clipboard feedback and line display.
+`renderLine` accepts caller-prepared syntax nodes without adding a highlighting
+engine or theme variables to the package. Keep `code` as authoritative plain
+text: line numbers, diff marks and rendered spans are never included in copy.
+
+`Message` from `themelia-react-ui/blocks/collaboration` owns conversation presentation
+and slots. It remains transport-free; use a feature for full sending/retry/data
+workflows. AI adapters preserve their existing APIs while sharing these lower
+owners. See the [message/file recipe](../examples/content-workflow.tsx).
+
+
+## Application layouts
+
+Import `AppLayout` from `themelia-react-ui/layout/app-shell`. Choose `light-header`
+(default), `dark-header`, `sidebar`, `inset` or `stacked`. Each preset delegates
+to the existing shell and retains its typed slots; topbar props and toolbar
+props are specific to their variants. The low-level TopbarSidebarLayout,
+SidebarInsetLayout and StackedLayout remain available for deliberate composition.
+
+The shell owns one PageViewport and framing. Give the root a constrained height
+(`h-svh min-h-0` for full-screen apps). Page owns width, page gutters and
+header/body rhythm, Card owns its insets, and Stack/Grid owns peer gaps. With
+stacked/contained content, use Page gutter="none" to avoid repeating the shell's
+Container gutter. Metric card size changes copy/media scale, keeping the default
+surface inset in ready, loading and error states.
+
+Compose LayoutSidebarProvider around AppSidebar and SidebarTrigger. Use
+`adaptTo="container"` on the provider for embedded workspaces: it measures its
+own width and switches navigation to the same mobile drawer below 768px, even
+on a wide viewport. The default remains viewport-driven. Account/search/page
+actions remain application callbacks. Do not add another scroll viewport
+inside the page. Header menus retain the header theme through their portal host.
+
+Header forwards native attributes, handlers and refs. PageHeader supports
+textGap="normal" or "dense" without changing control or page insets. Header
+search/brand visibility follows the actual header width; trailing actions wrap.
+TwoColumnLayout defaults to its existing viewport breakpoint; choose
+adaptTo="container" inside Container/PageViewport to adapt at 48rem of usable
+parent width while preserving main-before-aside DOM/focus order.
+
+See the installed [workspace recipe](../examples/app-layout.tsx).

package/docs/consumer-skill/references/design-contract.md

@@ -0,0 +1,145 @@
+# Structural composition contract
+
+Build application layouts freely with the public structures, slots and callbacks.
+Keep the geometry inside each control, row and surface with its library owner.
+Theme changes should move related components together. An application-specific
+layout should not require a copied Input, menu or card implementation.
+
+## What applications choose
+
+- Content, data, permissions, routing, translations and persistence.
+- Which public components to compose, their order, responsive columns and widths.
+- Actions, icons, supporting content and render/slot composition supported by that API.
+- Supported surface, inset, density, size and text-gap props.
+- Shared CSS theme values at the root or a ThemeScope boundary.
+- Placement, alignment, wrapping, overflow and application-owned drawing geometry.
+
+Consult the installed declarations: size and density are not universal props.
+Use native navigation integration and the component's supported callbacks rather
+than rebuilding its accessible interaction behavior.
+
+## What the library owns
+
+| Responsibility | Shared owner | Application seam |
+| --- | --- | --- |
+| Page gutters and region rhythm | Layout/container/section | Public layout props and responsive structure |
+| Peer spacing and columns | Stack/Grid/AdaptiveGrid | Semantic gap, axis, column and wrapping props |
+| Title/supporting-copy rhythm | Headed owner or ItemContent | `textGap="normal"` / `"dense"`; semantic Stack/Grid gap for custom copy groups |
+| Card header/body/footer insets | Card | `surface`, `padding`, anatomy and slots |
+| Anchored shell and region insets | Popover/Command and public collection parts | `type`, `inset`, `density` where supported |
+| Native field frame and editable text | Input and the owning form-control family | Size, validation, icons/add-ons, native attributes |
+| Action geometry and centered text | Button/IconButton/Badge recipes | Supported size/tone/style/variant |
+| Row labels, icons and selection indicators | Item and collection recipes | Supported row content, descriptions and density |
+| Semantic surfaces and states | Central theme and family state recipes | Theme foreground/surface pairs and supported tone/state props |
+| Corners and elevation | Shared radius and theme shadow ladder | Theme roots and supported surface variants |
+| Presence, dismissal and focus | Base UI plus library overlay/motion owners | Public open/state/dismissal callbacks and library overlays |
+
+An inset has one owner. A searchable menu needs the search region's outer inset
+and the Input's inner text inset; it does not need a third padded wrapper. A
+card-free block can be framed by a Card at its composition boundary.
+
+Card omits an empty body when neither children nor content slots contain
+renderable content. With only an inside header and footer, either divider prop
+requests one shared boundary. Setting both does not add a second line or a blank
+body strip. Real body/alert regions retain their distinct requested boundaries;
+an explicitly expandable card retains its collapse region.
+
+## Keep these choices independent
+
+| Choice | Purpose | Does not choose |
+| --- | --- | --- |
+| `textGap` normal/dense | Vertical title/description rhythm | Action spacing, row density or outer padding |
+| Collection density | Row block padding and minimum height | Inline padding, text size, surface inset or corners |
+| Item size | Legacy text/media scale, including provider fallback | Vertical row density |
+| Control size | That owner's action/field geometry | Page rhythm or surface padding |
+| Surface inset default/compact | Full/half surface roots | Row density |
+| Surface inset flush | Delegate padding to public regions | Remove Input padding or create a third density |
+| `--space-scale` | Shared gaps, inline insets and surface padding | Row block/control-height density |
+| `--density-scale` | Action/control heights and row block padding | Inline room or primary text hierarchy |
+
+`--gap-normal` and `--gap-dense` default to 0.5rem and 0.25rem. Their utilities
+multiply once by `--space-scale`. Descriptions have no extra margin. These are
+copy gaps; larger section and action-cluster gaps remain on their own owners.
+The [token reference](tokens.json) records the installed defaults and vocabulary.
+
+Use `rounded-radius` for ordinary controls and shells; `rounded-inner` is an
+intentional nested role. Density does not change radius. Circular indicators and
+avatars retain their shape. Elevation uses the existing shadow ladder, with
+family recipes selecting the tier; do not add a separate card/menu shadow root.
+
+Structural dividers use one private recipe owner with explicit frame, anchored
+and modal roles. They share the semantic `border` root; their established strength
+is a library recipe, not a separate theme knob. A field's
+`input` frame and its focus `ring` are separate roles. Do not replace either with
+a divider, or recolor a divider to simulate focus. Theme status colors keep their
+foreground pairs; a status tone is not a decorative brand palette.
+
+Native fields, field-shaped triggers and compound field frames share the same
+focus and invalid treatment. Invalid state marks the frame and error copy;
+editable values keep their normal semantic foreground. Compound fields show one
+outer ring. Use validation and disabled/loading props instead of supplying a
+second local state recipe. Selected rows retain the owning primitive's indicator;
+highlighted, selected and destructive states are distinct responsibilities.
+
+Clear affordances share one density-scaled target and spacing-scaled glyph recipe
+across Input, Textarea and Combobox. Toggle and loading affordances retain their own interaction
+and presence. Collection labels share the configured primary text size and medium
+weight, including mixed icon/text rows; descriptions use smaller secondary copy
+and `gap-dense`. Empty descriptions do not create a copy region. Custom JSX and
+render slots preserve their supplied content and the owning primitive's behavior.
+
+Inline affordances reserve room using the actual action size, gap and logical
+end inset. Dialog and drawer headers reserve dismiss-control room only when the
+control exists; its offsets follow the same surface roots as the header/body/footer.
+Long copy wraps inside that space. Native `dir` and DirectionProvider must agree
+for logical geometry, keyboard navigation and anchored positioning; see
+[integration](integration.md). Physical drawer edges remain explicit API choices.
+
+## How to extend
+
+1. Find the responsible public owner in the [composition guide](composition.md).
+2. Use its supported prop or slot. Keep width/position/overflow on the surrounding layout.
+3. Change an existing shared root at the intended [theme boundary](theming.md) when several related components should move together.
+4. If the public API cannot express a recurring composition, request an additive seam at that owner. Keep genuinely application-specific geometry namespaced in the application.
+
+Do not fix a shared mismatch with padding on Popover, Command, Select popup or
+Combobox anatomy, including `contentClassName`, inline styles, descendants and
+forwarding wrappers. Likewise, do not locally replace fixed control typography
+or make descriptions carry surrounding margins. The same restriction applies
+to token-backed overrides: a semantic utility can still be used on the wrong owner.
+
+Theme inheritance belongs to CSS. Use ThemeScope for scoped portals; an explicit
+portal container must live in the intended boundary. Provider defaults and app
+callbacks do not form a parallel JavaScript styling system. Opening a popup is
+necessary to verify its actual inherited theme.
+
+Portaled anchored surfaces share viewport positioning so a scoped host inside a
+scroll region does not clip or displace the popup. Anatomy that exposes native
+`positionMethod` still accepts an explicit override. A deliberately inline
+Popover (`disablePortal`) retains absolute positioning. CSS theme inheritance
+and Base UI focus/dismissal remain with their respective owners; a stacking
+issue is not a reason to add a z-index token for each component.
+
+Dropdown submenus default to `side="inline-end"`: right in LTR and left in
+RTL, with native collision fallback. Nested collection back actions use a mirrored caret in the canonical small icon Button; keep its accessible label and navigation callback on the owning surface. Explicit `side="right"` or `side="left"`
+remains a physical placement override. Pair DirectionProvider with the DOM
+reading direction when switching a scoped application to RTL.
+
+## What enforcement proves
+
+Repository checks validate root ownership/budgets, generated utilities and class
+merging, public exports/layers, recognized fixed typography/radius/padding
+overrides, semantic borders, and new raw spacing/control drift. The shipped
+typed examples go through the same design checks as library compositions.
+
+Those repository checks do not run automatically in a consuming application.
+Adopt equivalent component-import-aware lint rules in the application's CI, and
+run its types, build and interaction tests. The package does not strip arbitrary
+CSS at runtime or advertise a consumer audit/install CLI.
+
+Static lint cannot prove alignment, readable wrapping, CSS authored elsewhere,
+unknown dynamic styles, focus restoration or callback behavior. Verify long
+copy, narrow/desktop widths, light/dark scopes, opened surfaces, keyboard
+selection/dismissal, validation and failure/retry as relevant. Motion recipes
+respect reduced motion while the interaction owner preserves focus and presence.
+Use [integration guidance](integration.md) and [workflow checks](workflows.md).

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

@@ -0,0 +1,33 @@
+# Installed discovery
+
+First resolve the installed package and verify copied guidance using
+[installed setup](installation.md). The commands below assume a conventional
+node_modules layout; use the reported absolute package root for other layouts
+or a nested working directory.
+
+Run the bundled dependency-free finder with Node from the application directory:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs overflow action menu --layer base --limit 5
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs ThemeScope --limit 10
+```
+
+For a copied skill, replace the script path with that copy's `scripts/find-components.mjs`. Copy the complete skill folder: the script resolves its adjacent `references/public-api.json` relative to itself, regardless of the working directory. It needs Node compatible with the package's engine requirement, not an npm/global CLI or extra dependency.
+
+Queries accept multiple words, quoted or separate. Every term must match candidate metadata; an unknown term produces empty results. Exact imports and exported symbols rank first. `--layer` filters the technical package layer: `foundations`, `base`, `layout`, `blocks` or `features`. This is independent of responsibility-based browse sections: `themelia-react-ui/base/structure` browses Foundations but filters under `--layer base`; a theme-tweaker recipe browses Recipes but filters under `--layer features`. `--limit` is an integer from 1 to 100 and defaults to 5. Unknown flags, duplicate options, missing values and incompatible/malformed indexes exit nonzero with an error on stderr.
+
+If a query returns no results, shorten it to the main responsibility or an exact
+symbol, then remove the layer filter. Read choose/avoid guidance and alternatives
+before selecting the owner. For routine compact searchable selection, search
+`PopoverMenu` or `compact searchable selection`; surface adjectives describe
+variants, not permission to rebuild the owner's padding.
+
+Output is deterministic JSON: package/version, query/options, total matching families and a bounded `results` list. Each result includes exact `import`, packaged `declaration`, technical `layer`, responsibility, required `optionalPeers`, match kind, exact matched symbols and up to three relevant guidance entries. Family `sections` and guidance `section` reflect responsibility-based documentation placement. Guidance carries jobs, tags, aliases, selection/avoidance, application ownership, canonical browse group/domain plus catalogue category/collection, search-section labels/symbols and alternatives resolved to exact published imports. Read the [full index](public-api.json) for all symbols/guidance. A result suggests an owner; declarations establish its actual props and behavior.
+
+Read each declaration relative to the installed package root, for example `node_modules/themelia-react-ui/dist/components/base/cards/index.d.ts`, following its relative exports as needed. Copying this skill copies metadata, not the declaration tree: use declarations from the same installed package version. Never combine metadata from one version with another version's declarations.
+
+`ThemeScope` has distinct contracts. Root and `themelia-react-ui/ui-provider` export the basic CSS-inheritance boundary with native div/style props and portal hosting. `themelia-react-ui/features/theme-tweaker` exports the advanced theme-definition scope. Inspect the result's responsibility and that exact family's declaration before selecting props.
+
+The index retains `schemaVersion: 1` and adds `discoveryVersion: 1`. Package name/version and peer ranges come from the published manifest; symbols and declaration paths come from live public exports; jobs and guidance come from the live consumer catalogue. Utility/root responsibilities have explicit owners when no catalogue family represents them. Optional peer requirements follow transitive local source imports, including type-only and resolved `@types` peers; the manifest supplies their compatible ranges. This describes whole-family declaration/runtime requirements, not the smaller graph a bundler may obtain after tree shaking.
+
+Routing, records, translation, permissions and backend effects stay in the application. Discovery grants no publication or global installation authority.

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

@@ -0,0 +1,66 @@
+# Installed package and skill setup
+
+Run from the consuming app or one of its subdirectories. Resolve a public
+entrypoint rather than guessing a hoisted node_modules path or importing
+`themelia-react-ui/package.json`, which is not an exported entrypoint. The following
+read-only Node recipe finds the physical package and checks the guidance identity.
+It requires no repository checkout or extra dependency.
+
+```sh
+node --input-type=module <<'JS'
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let root = path.dirname(fileURLToPath(import.meta.resolve('themelia-react-ui')));
+const readJson = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+let manifest;
+while (true) {
+  const file = path.join(root, 'package.json');
+  if (fs.existsSync(file) && (manifest = readJson(file)).name === 'themelia-react-ui') break;
+  const parent = path.dirname(root);
+  assert(parent !== root, 'Cannot locate the installed themelia-react-ui package');
+  root = parent;
+}
+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']) {
+  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');
+}
+console.log(JSON.stringify({ package: manifest.name, version: manifest.version, root, skill: selectedSkill }, null, 2));
+JS
+```
+
+Use the reported root for the bundled finder, 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.
+
+To check a copied skill, set `THEMELIA_SKILL_DIR` to its complete directory when
+running the recipe. The comparison checks metadata contents as well as version,
+so stale copies with the same development version are caught. A successful check
+does not compare every prose file: recopy the complete folder after package
+upgrades or guidance updates, and read declarations from the installed package.
+
+## 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.

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

@@ -0,0 +1,57 @@
+# 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.
+
+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:
+
+```css
+@layer theme, base, components, utilities;
+
+@layer base {
+  *, *::before, *::after { box-sizing: border-box; }
+  body { margin: 0; }
+  button, input, textarea, select { font: inherit; }
+}
+```
+
+Load intentional, scoped app overrides after the package stylesheet. Keep broad resets in `base` so shared control recipes retain ownership of typography and geometry.
+
+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.
+
+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`.
+Both boundaries must include the controls and their themed portal host:
+
+```tsx
+import { DirectionProvider, ThemeScope } from 'themelia-react-ui/ui-provider';
+
+<DirectionProvider direction="rtl">
+  <ThemeScope dir="rtl"><App /></ThemeScope>
+</DirectionProvider>
+```
+
+Use an app-owned direction value for both. DirectionProvider may be scoped and
+does not replace the single mount-time UIProvider configuration boundary.
+
+Routing comes through href, callbacks or Base UI render composition. React Router is not required. Component chunks preserve client boundaries; pure utilities remain separate.
+
+Use ActionDialog, ActionDrawer, ConfirmDialog and useOverlayVisibility from features/overlays. Pass overlayProps for visibility. onAsyncConfirm awaits the operation; onError reports failure. Do not also pass onConfirm, which takes precedence. Sheet is structural infrastructure, not another workflow API.
+
+PlaceAutocomplete from themelia-react-ui/features/map uses Photon by default. Supply a stable or useCallback-memoized searchPlaces: PlaceSearchCallback to use your geocoder; it receives PlaceSearchOptions and an AbortSignal and returns Promise<PlaceFeature[]>. Adapt provider results to the existing place shape and OSM identifiers (duplicates are removed by osm_id). Changing provider identity or search options cancels the old lookup and searches the current query. Respect the signal; superseded responses are ignored even if a provider cannot cancel. Keep provider identity stable during ordinary renders. Notification callbacks may be inline. onSearchError reports current failures; the built-in Retry action repeats the lookup and strings.retry localizes its label.
+
+Verify callbacks update actual app state. Cover relevant loading, empty, error, invalid/disabled, cancel/retry and success behavior. Check keyboard entry, dismissal and focus return. Inspect opened content in light/dark and narrow/wide layouts; a closed trigger screenshot cannot approve its popup.
+
+EmailComposer from `themelia-react-ui/features/email-composer` requires the Tiptap optional peers and composes our controls, Card/overlays and editor toolbar. Keep the structured draft separate from prepared delivery output: `onChange` persists an immutable draft proposal; `onSend` receives resolved, sanitized HTML/plain text. Supply pure placeholder resolvers and immutable context, and keep delivery/authentication in the app. Imported HTML retains supported email layout in preview until explicit rich-text conversion. See the [typed email recipe](../examples/email-composer.tsx) and the family catalogue for commands, strings and placement examples.
+Empty recipient groups show our input immediately; the inline plus adds another address, and Cc/Bcc reveal inputs. Template registries, placeholder sets and per-field recipient options accept application-owned `loading`, `error` and `onRetry`; templates additionally expose `onOpenChange` for lazy loading. Loading/error replace stale data. Required recipient/variable resources block preparation and sending until ready; an optional template registry does not block ordinary composing. Preserve the selected template in the supplied registry and let your data client cancel or ignore stale requests.
+
+Keep `value` authoritative and accept `onChange` proposals in the controlled parent. Keep controlled/uncontrolled mode fixed while mounted; remount with a new key for a different message and discard baseline. Callback proposals and delivery payloads are detached from the local draft and from one another. Recipient modes and subject read-only flags constrain user editing; application API commands may still replace these fields. Commit recipient input with Enter, the plus, or blur before an imperative preparation command.
+
+`api.prepare()` rejects validation failures. `api.send()` and `api.discard()` report failures through the alert and `onError` and resolve after handling them; use `onSent` to observe delivery success. `onBeforeSend` may cancel with false or transform the payload under your application's validation policy. Success neither closes nor resets the composer. Unmounting during review prevents delivery; once your `onSend` starts, cancellation belongs to your transport. Unmounting suppresses success/reset/close completion, while failures still reach `onError`.
+
+Server code imports pure helpers from `themelia-react-ui/features/email-composer/engine`, which has no React/editor runtime or client directive. The UI family remains a client boundary; in server-component frameworks, mount it from an app client wrapper and pass callbacks there. `renderEmail` returns sanitized output and unresolved keys; call `validate` before delivering it and enforce your server policy. The optional `createHttpSender` uses JSON POST, same-origin credentials, supplied headers and a timeout; use an app-owned `onSend` transport for other authentication, cancellation or cross-origin requirements. Rich document declarations reference Tiptap types even though the pure engine does not require its runtime.
+
+
+Maintainer enforcement uses @shadcn/lint through Oxlint plus AST/contract checks. These are not runtime dependencies or a published consumer audit CLI. Configure app lint using published utilities/imports; do not copy repository migration-debt allowances. There is no Sass/SASSC pipeline in this Tailwind package.
+
+The maintainer installed-tarball harness proves the basic provider/control/overlay SSR and hydration fixture, pure email preparation without editor peers, controlled table and email-composer workflows, and optional client module initialization. It checks hydration diagnostics and real callbacks in light/dark at narrow/wide widths. Optional module initialization alone does not prove its complete workflow or server-rendering support; verify the features your app uses. `check:all` runs the serial package and curated browser gates; evidence collection is a separate `collect:browser` command. Both are repository maintainer commands, not installed consumer CLIs.