@abuzareal/contour-ui 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ Changes to the published `@abuzareal/contour-ui` package. Version headings refer
 
 No changes recorded.
 
+## 0.6.0
+
+Add allowed-value selection and public adoption material. This heading records source work, not npm publication.
+
+- Add single-select Combobox backed by pinned Base UI 1.9.0, with stable string IDs, controlled/default selection and query, visible input refs/native form association, missing-value validation, translated status strings, loading/error/retry and Contour theme/layer/native-dialog integration. Existing native controls and overlay APIs remain compatible; Base UI adds installed dependency cost that is disclosed and measured.
+- Add semantic Table with caption, native table ref/props and scroll-region part access. DataTable reuses the presentation frame while retaining its existing scalar/local-sort contract. TanStack Table 9.3.1/Store 0.11.2 stay application/development dependencies for a copyable controlled remote recipe.
+- Publish executable async search, destructive Dialog confirmation and input composition recipes with cancellation/stale-response guards and truthful failures. Record explicit NumberField, adornment, password and Text/Heading scope decisions rather than speculative new exports.
+- Ship independent pinned Vite/Next starters, an existing-app path, providers/forms/navigation/optional-feature guidance, script hash/nonce CSP integration and a public minimal reproduction. Add documentation coverage/issue links, copied-source checks and candidate-versus-registry starter verification.
+- Keep existing production size budgets; introduce separate measured Combobox journeys. Expand same-archive React 18/19, package/declaration, browser, starter and CI gates. Manual screen-reader/physical device evidence and private catalogue changes remain separate.
+
+See COMBOBOX.md, RECIPES.md, GETTING-STARTED.md, FOUNDATION.md and DOCS.md. This is an additive 0.x release, not a declaration of 1.0 readiness.
+
+## 0.5.0
+
+Combined overlay, styling and size work. This heading records source work, not npm publication.
+
+- Shared owner-document topmost dismissal and matching paint order for nested/sibling/portaled layers; cancellation, outside focus, ancestor visibility, native backdrop priority and cleanup are covered by regressions. Mobile-menu dismissal cooperates with the same registry.
+- Popover/Menu/Tooltip gain collision-aware placement, bounded scrolling, RTL and CSS-zoom handling via Floating UI DOM 1.8.0. Default body/native-modal portals escape clipping and carry theme values/direction. Default DOM placement changes ancestor selectors; use direct part hooks or portal=false for a deliberate local integration. Public refs/state callbacks and void useDismiss remain compatible.
+- Hoverable/persistent supplemental tooltips retain descriptions/names and Escape suppression. Public button renderTrigger and focus policies avoid nested controls; native Dialog preserves focus/scroll/lifecycle behavior and accepts explicit initial focus.
+- Add isolated scoped.css, prefixed classes/tokens, controlled ThemeScope, minimal-reset.css, token JSON generation, forced-color states, logical RTL layouts and configurable internal labels/formatters. Legacy globals, branded fonts and application-layout compatibility remain; no consumer migration is performed. Compact density is deferred pending a concrete need.
+- Add measured Vite/Next Button/settings/table fixtures, selected-icon comparison, actual network/install/archive categories, selective CSS entries and reviewed regression budgets. System fonts make no font requests; Fontsource/Lucide install costs are retained and disclosed. Three.js/Lenis remain optional and absent from core fixtures.
+
+See OVERLAYS.md, STYLING.md and SIZE.md for migration, behavior, measurements and evidence boundaries. Independent applications/site versions are not upgraded by this package release.
+
 ## 0.4.0
 
 Native forms and tested application recipes. This heading records source work, not npm publication.

package/COMBOBOX.md

@@ -0,0 +1,87 @@
+# Combobox — 0.6.0
+
+Search a list and choose **one allowed value**. Use native SelectField when its simpler platform interaction is sufficient. Combobox is not free-text autocomplete, global search, a command menu, a multi-select, or a virtualized picker. Selection is a string ID or null; query text is never a submitted selection. It needs no provider or consumer-installed foundation package. [Foundation decision](FOUNDATION.md).
+
+```tsx
+import { useRef } from "react";
+import { Button, Combobox } from "@abuzareal/contour-ui";
+import "@abuzareal/contour-ui/scoped.css";
+const projects = [
+  { value: "atlas", label: "Atlas" },
+  { value: "notes", label: "Field notes" },
+  { value: "closed", label: "Closed project", disabled: true },
+];
+export function ProjectForm() {
+  const input = useRef<HTMLInputElement>(null);
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        console.log(new FormData(event.currentTarget).get("project"));
+      }}
+    >
+      <Combobox
+        ref={input}
+        label="Project"
+        name="project"
+        options={projects}
+        defaultValue="atlas"
+        required
+        hint="Choose an available project."
+      />
+      <Button type="submit">Inspect selection</Button>
+      <Button type="reset" variant="secondary">
+        Reset
+      </Button>
+    </form>
+  );
+}
+```
+
+This is local inspection, not persistence. The application's server must validate and authorize the submitted ID. Do not log sensitive form data in a production application.
+
+## Types and defaults
+
+[ComboboxProps and ComboboxOption](PUBLIC-API.md) are emitted declarations; inherited native part props remain typed. [Released implementation](https://github.com/abuzareal/contour-ui/blob/v0.6.0/src/components/ui/Combobox.tsx). The ref targets the **visible HTMLInputElement**, including focus, selection and measurement; it does not target the hidden form input or popup.
+
+| Props                                                                  | Contract / default                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| label, options                                                         | Required visible label and readonly `{value: string; label: string; disabled?: boolean}` choices. Unique nonempty IDs; labels may repeat or translate.                                                                                                                                                               |
+| value / defaultValue / onValueChange                                   | Controlled or uncontrolled selection, null by default. Callback receives string or null. Keep the mode stable for the lifetime of the component.                                                                                                                                                                     |
+| inputValue / defaultInputValue / onInputValueChange                    | Independent controlled or uncontrolled query. Default derives from the selected label. Callback also reflects selection/close synchronization; a controlled parent must accept it.                                                                                                                                   |
+| filteredOptions                                                        | Omitted: foundation filters the known options by label. Provided: authoritative application results, drawn from options; no second local filtering.                                                                                                                                                                  |
+| open / defaultOpen / onOpenChange                                      | Controlled or uncontrolled popup; false by default. Disabled/readOnly/hidden ancestor suppresses visible opening.                                                                                                                                                                                                    |
+| id, name, form                                                         | Generated accessible ID unless supplied. Optional native name and external form owner. No name means no submitted entry.                                                                                                                                                                                             |
+| required, disabled, readOnly, hideLabel, loading                       | false by default. Hidden labels remain accessible; disabled omits submission. Readonly preserves the value without opening/editing.                                                                                                                                                                                  |
+| hint, error                                                            | Optional field help or validation failure. Error takes precedence over hint. Native aria-describedby IDs are merged.                                                                                                                                                                                                 |
+| searchError, onRetry                                                   | Separate service failure text and optional retry callback. Loading/failure hide selectable results. Retrying is caller-owned; it cannot create a successful result.                                                                                                                                                  |
+| loadingText / emptyText / retryLabel / triggerLabel / missingValueText | “Loading choices…”, “No matching choices.”, “Retry search”, “Show choices”, “Selected option is unavailable. Choose another.” Supply translated strings.                                                                                                                                                             |
+| inputProps / popupProps / rootProps                                    | Native attributes, events, styles, classes and refs for the existing input, popup and wrapper. Input value/name/form/id/type/state stay owned by the component. Input native events can observe/cancel foundation behavior; use onValueChange for selection. ARIA label references preserve the visible field label. |
+| side / align / sideOffset / collisionPadding                           | bottom / start / 8 / 8. Positioner flips/shifts within available space.                                                                                                                                                                                                                                              |
+| portal / container                                                     | true / automatic owner body or enclosing native dialog. A custom container must share the owner document and be inside its dialog. false keeps the popup inline; ancestor clipping remains the application's responsibility.                                                                                         |
+
+## Anatomy, states and forms
+
+The wrapper contains Field's label/help/error, input group, native text input, trigger button and a separate form-value input. The portaled fixed positioner contains a popup, status, optional retry and listbox/options. Input focus stays on the combobox during list navigation; an active-descendant ID identifies the highlighted option. Option content is text, not nested interactive actions. No placeholder is a substitute for the label; use inputProps.placeholder only as supplemental guidance.
+
+Uncontrolled form reset restores defaultValue. Controlled selection remains owned by the parent; update it in the form's onReset when a different value is required. The same applies to controlled query/open state. Preventing native reset preserves state. External form association uses form, and a disabled fieldset must retain native successful-control behavior. Required selection is validated by the selection value, not arbitrary query text. Always validate on the server as well.
+
+Reordering/translated labels preserve ID identity and update the selected label when the query is not being edited. If the selected ID disappears from **options**, Contour retains the parent's identity, displays the missing-value error, exposes an invalid visible input and serializes an empty value. It does not call onValueChange merely to rewrite parent data. Resolve the record, clear it, or ask the user to choose another; never silently substitute the first choice. A selected option that later becomes disabled remains a historical selection; disabled options cannot be newly selected. The application decides whether its server permits that historical value.
+
+For remote search, retain the selected record in options even when it is absent from filteredOptions. The [actual async recipe source](examples/recipes/AsyncProjectPicker.tsx) uses one selected snapshot plus current results, an AbortSignal and stale-result guards. See [recipes](RECIPES.md) for service validation and stable loader identity.
+
+Loading and service errors have separate live status text and visible popup messages. Empty results do not imply an empty overall database. The application owns permissions, cache, debounce, request limits, result counts and retry. Keep selected records separate from search results; showing yesterday's results under today's query is misleading.
+
+## Keyboard, layout and limits
+
+Typing searches; ArrowDown/ArrowUp moves among enabled choices, Enter selects the highlighted choice, Escape closes only the current popup, and Tab leaves without selecting an arbitrary highlighted item. Composition Enter must not select prematurely. A second Escape can dismiss an enclosing Contour layer; Escape on a closed picker preserves the selected ID. Contour suppresses the foundation's closed-Escape clear action without stopping the native document event. Outside press dismisses the popup; choosing an option keeps the enclosing Dialog/Popover open. Dialog focus containment and return remain owned by that Dialog.
+
+Scoped CSS uses `contour-combobox`, `contour-combobox-control`, `contour-combobox-trigger`, `contour-combobox-positioner`, `contour-combobox-popup`, `contour-combobox-option`, `contour-combobox-status` and `contour-combobox-retry`. Options expose data-highlighted/data-selected/data-disabled; the input exposes expanded/invalid/busy state. [Semantic tokens](STYLING.md) control surfaces, text, borders and focus. forms.css is the selective family; scoped.css is the aggregate. Legacy styles.css retains unprefixed compatibility classes. Consumer class names are preserved, never automatically prefixed.
+
+Inherited theme and direction travel into portals; collision bounds and long labels support narrow layouts. Options wrap rather than truncate. Forced-colors focus/selection and system reduced motion are respected. Provide localized labels and all status strings; custom matching/remote locale collation belongs to the application. Large collections need a bounded server result set; there is no virtualized/multiple/grouped API in this release.
+
+Automated Chromium keyboard, touch emulation, synthetic composition, RTL, forced colors, native-dialog and packed React tests are evidence for those fixtures only. Manual screen-reader, physical keyboard/IME and mobile keyboard checks remain separate; no universal accessibility certification is claimed.
+
+**Open-state accessibility review:** the foundation temporarily hides background content from the accessibility tree while the list is active. Static axe checks report `aria-hidden-focus` on that background. Browser regressions verify that Tab/Shift+Tab close the list and restore visibility before focus remains on an outside control. This is retained as a finding requiring manual VoiceOver/NVDA review, not waived as a universal false positive or reported as a zero-finding scan. The [ACT rule's assumptions](https://www.w3.org/WAI/standards-guidelines/act/rules/6cfa84/) explicitly distinguish interactions that change aria-hidden. Do not claim WCAG conformance from these fixtures.
+
+[Report Combobox 0.6.0](https://github.com/abuzareal/contour-ui/issues/new?template=bug_report.yml&title=Combobox%200.6.0%3A%20&component=Combobox&version=0.6.0), using the [public minimal reproduction](examples/reproduction). Source links for this version resolve when its release tag is published.

package/CONTRACTS.md

@@ -1,16 +1,16 @@
 # Architecture, scope and compatibility
 
-Contract version **0.4.0**, reviewed 13 October 2026. Contour is an early 0.x React library with typed controls, paper/ink surfaces, a lime accent, light/dark themes, restrained motion and separate optional depth/scene APIs. The [public API and maturity register](PUBLIC-API.md) lists every exported value, type and stylesheet, its maintainer, status, use and limits.
+Contract version **0.6.0**, reviewed 14 October 2026. Contour is an early 0.x React library with typed controls, paper/ink surfaces, a lime accent, light/dark themes, restrained motion and separate optional depth/scene APIs. The [public API and maturity register](PUBLIC-API.md) lists every exported value, type and stylesheet, its maintainer, status, use and limits.
 
 ## Intended adoption scope
 
-Use Contour in React web applications that want its supplied appearance and can manage global CSS and one document-level theme. Starting workflows are editable text/native choices, application-owned search/results, scalar locally sorted tables, modal settings and feedback. Existing editorial motion/identity exports remain available within their limits.
+Use Contour in React web applications that want its supplied appearance and can use either isolated scoped CSS/themes or the documented legacy global integration. Starting workflows are editable text/native choices, application-owned search/results, scalar locally sorted tables, modal settings and feedback. Existing editorial motion/identity exports remain available within their limits.
 
-The first acceptance workflow is settings/search/table composition: edit a named TextField/SelectField/Checkbox, submit or reset the native form, own pending/error/retry in the app, filter supplied scalar records, change the root theme and open a settings Dialog. The catalogue already has [application patterns](https://contour.abuzr.in/docs/patterns) with local simulated adapters, not a backend. Switch and Slider settings currently use application state; RadioGroup uses a generated field name. Do not claim a stable caller-named FormData contract for those three controls.
+The first acceptance workflow is settings/search/table composition: edit a named TextField/SelectField/Checkbox, submit or reset the native form, own pending/error/retry in the app, filter supplied scalar records, change the root theme and open a settings Dialog. The catalogue already has [application patterns](https://contour.abuzr.in/docs/patterns) with local simulated adapters, not a backend. Switch, Slider and RadioGroup have named/external native form and reset contracts since 0.4; their controlled state remains application-owned.
 
 Fetching, response validation, permissions, domain validation, persistence, URL state, server operations and truthful async outcomes belong to the application. A toast or demonstration does not mean data was saved. Apps supply labels, useful content, keyboard paths and accessible compositions.
 
-Current scope excludes a general Combobox, multi-select, date/range picker, remote grid, tree, command palette, upload backend, chart/editor engine and non-React adapters. DataTable supports scalar string/number rows and local sorting. Drawer is Dialog placement; banner is Alert layout. New capabilities require a bounded contract, tests, documentation and demonstrated need.
+Current scope includes one allowed-value single-select Combobox and a native Table presentation frame. It excludes multi-select, date/range picker, remote grid, tree, command palette, upload backend, chart/editor engine and non-React adapters. DataTable supports scalar string/number rows and local sorting. Drawer is Dialog placement; banner is Alert layout. New capabilities require a bounded contract, tests, documentation and demonstrated need.
 
 No promise of enterprise completeness, universal embedding, all locales/RTL, every browser/framework or accessibility certification is made. Early 0.x status and experimental limits are adoption information.
 
@@ -30,14 +30,14 @@ Catalogue UI/hook/scene compatibility modules intentionally forward public packa
 
 React is the UI runtime. Strict TypeScript/TSX source compiles through `tsc` into ES2022 ESM modules and declarations. The build copies CSS and selected licensed Latin font assets. It does not bundle React or compile the library into a Vite app. Vite serves development/consumer fixtures; Design-System is the Vite application. Consumers can write JavaScript or TypeScript.
 
-| Category                 | Current packages                                                                                       | Consumer consequence                                                                                                       |
-| ------------------------ | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| Runtime dependencies     | lucide-react; @fontsource-variable/dm-sans; @fontsource-variable/space-grotesk; @fontsource/dm-mono    | Install with Contour. Selected imports determine browser output. Font CSS is optional; font installation currently is not. |
-| Required peers           | react/react-dom: React 18 (`^18.3.1`) or React 19 (`^19.0.0`)                                          | App supplies a matching pair; allowed range is broader than individually tested versions.                                  |
-| Optional peers           | three: `^0.186.1`; lenis: `^1.3.26`                                                                    | Core works without either. Install explicitly for the matching optional entry.                                             |
-| Development dependencies | TypeScript, Vite, Oxlint, Testing Library, jsdom, Playwright, React/types and optional peer dev copies | Source authoring/tests/build; not downstream Contour production dependencies.                                              |
+| Category                 | Current packages                                                                                                                                                           | Consumer consequence                                                                                                       |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Runtime dependencies     | @base-ui/react 1.9.0 (Combobox); @floating-ui/dom 1.8.0 (positioning); lucide-react; @fontsource-variable/dm-sans; @fontsource-variable/space-grotesk; @fontsource/dm-mono | Install with Contour. Selected imports determine browser output. Font CSS is optional; font installation currently is not. |
+| Required peers           | react/react-dom: React 18 (`^18.3.1`) or React 19 (`^19.0.0`)                                                                                                              | App supplies a matching pair; allowed range is broader than individually tested versions.                                  |
+| Optional peers           | three: `^0.186.1`; lenis: `^1.3.26`                                                                                                                                        | Core works without either. Install explicitly for the matching optional entry.                                             |
+| Development dependencies | TypeScript, Vite, Oxlint, Testing Library, jsdom, Playwright, React/types, table-recipe development adapters and optional peer dev copies                                  | Source authoring/tests/build; not downstream Contour production dependencies.                                              |
 
-Use explicit public paths; deep imports into dist internals are unsupported. CSS is marked as side-effectful to retain imported styles. The archive contains built modules/declarations/assets and release documents, plus copyable form recipe sources, with no consumer install scripts or private research. React Hook Form is an example/application dependency, not a runtime dependency.
+Use explicit public paths; deep imports into dist internals are unsupported. CSS is marked as side-effectful to retain imported styles. The archive contains built modules/declarations/assets and release documents, plus public form/adoption/optional recipe sources, standalone starters and a minimal reproduction, with no consumer install scripts or private research. React Hook Form and TanStack Table/Store are example/application dependencies, not Contour runtime dependencies. See FOUNDATION.md for the bounded foundation decision and licensing.
 
 Archive bytes, installed dependency bytes, browser JS/CSS, emitted fonts and actual requested/cached network assets are different measurements. An installed icon collection is not proof all icons download. JavaScript tree shaking does not remove unused aggregate CSS rules automatically. Size claims require version, fixture, tool versions, compression and exclusions; independent component gzip samples cannot be added as an application total.
 
@@ -60,9 +60,9 @@ Interactive modules retain emitted client directives. Server-importable pure hel
 
 ## Styles, theme and motion
 
-`styles.css` supplies tokens/components/utilities; `tokens.css` supplies tokens alone. Reset and either font stylesheet are optional. Import deliberate app overrides afterward. Current classes such as button/card/menu/mono and variables --bg/--fg are global. Reset contains inherited page-width/site-shell/section offsets; tokens retain portfolio/header values. These contracts are preserved; later isolation requires a versioned compatibility path.
+`styles.css` supplies tokens/components/utilities; `tokens.css` supplies tokens alone. Reset and either font stylesheet are optional. Import deliberate app overrides afterward. The legacy aggregate retains global classes such as button/card/menu/mono and --bg/--fg for compatibility. The scoped aggregate and selective families use contour-prefixed classes and semantic tokens; minimal-reset.css is opt-in. Use STYLING.md and SIZE.md to choose imports instead of applying a legacy page reset to an embedded control.
 
-Theme follows root data-theme and legacy aa-theme origin storage. Independent subtree themes are not a general contract; choose one owner in a multi-library page. Optional branded fonts are DM Sans, Space Grotesk and DM Mono. Existing font tokens also permit system fonts. Select Latin or broader coverage intentionally and preserve notices.
+Theme follows root data-theme and legacy aa-theme origin storage. ThemeScope provides a controlled independent subtree with scoped CSS and inherited portal values; its caller owns initial state/persistence. Root useTheme remains document-owned. Optional branded fonts are DM Sans, Space Grotesk and DM Mono. Existing font tokens also permit system fonts. Select Latin or broader coverage intentionally and preserve notices.
 
 Respect system reduced motion and app pause. CSS depth is core; WebGL is separate. Lazy scenes need sized hosts, useful static content outside SceneBoundary, capped rendering cost, no unnecessary hidden/offscreen work and symmetric cleanup. Register owned custom cleanup immediately through onDispose, including failed initialization; avoid double disposal. Mount-captured setup changes need explicit remount.
 
@@ -72,13 +72,13 @@ Preserve native input/select/details/dialog behavior where appropriate. Future r
 
 - Actions, ExternalLink, native fields/choices, Dialog and the documented Tabs/Popover parts forward their native targets on React 18/19. Multi-control/presentation wrappers do not imply a singular input ref; see [the composition contract](COMPOSITION.md).
 - Checkbox accepts caller IDs while retaining a generated fallback and internal indeterminate behavior alongside the forwarded input ref; caller ARIA validity and descriptions remain composed. Switch/Slider/RadioGroup support named/external form submission and controlled/default/reset behavior; see [the form guide](FORMS.md). Switch refs remain buttons and its checkbox backing submits only while checked; a range has no required constraint.
-- Popover/DropdownMenu use local absolute panels without portal/collision/submenu/custom-trigger contracts. Independent document listeners close both nested Popovers on one Escape: a reproduced defect.
-- Tooltip closes on pointer leave and CSS prevents content hover: a source finding/accessibility risk requiring correction and pointer/focus verification, not a formal conformance audit. Hints must be supplemental and noninteractive.
-- Dialog/Tabs/Popover expose typed root and owned-part props/refs; state and ARIA wiring stay protected and caller cancellation composes with internal behavior. Arbitrary trigger replacement, portals/collision and general polymorphism remain outside this API.
+- Popover/DropdownMenu/Tooltip use collision-aware owner-body/native-dialog portals by default, preserve logical Contour nesting and dismiss one topmost layer. Use portal=false deliberately for inline content. General submenus/third-party modal interoperability are not promised; see OVERLAYS.md.
+- Tooltip remains hoverable while pointer/focus is in its trigger/content and supports Escape suppression. Hints remain supplemental/noninteractive; a hover check does not constitute formal accessibility certification.
+- Dialog/Tabs/Popover expose typed root and owned-part props/refs; state and ARIA wiring stay protected and caller cancellation composes with internal behavior. The public renderTrigger contract permits one ref-forwarding button where documented; arbitrary root replacement and general polymorphism remain outside the API.
 - Disclosure is native details with defaultOpen and required className, not controlled open/onOpenChange. Controlled open state belongs to Popover/DropdownMenu.
 - BrandMark/editorial section/heading helpers and selected navigation/print hooks retain inherited page assumptions. They remain supported legacy APIs, not universal product primitives.
 
-Recording these limits does not complete their later API/form/overlay/style fixes.
+Combobox forwards its visible input and Table its native table; their form/state/part boundaries are documented in COMBOBOX.md and RECIPES.md. Documentation promotion and manual assistive-technology verification remain separate work.
 
 ## Change, deprecation and migration policy
 
@@ -91,3 +91,9 @@ Formal deprecation identifies replacement/affected versions, marks the API/docs
 Releases choose an unused version, align manifest/lock/tag/changelog, validate a candidate archive and state material limits. Consumers keep exact pins until the released version is installed, their lockfile updated and relevant checks pass. Package publication does not deploy an application.
 
 1.0 requires settled supported contracts, appropriate docs/evidence, successful outside-use workflows and no known critical/high-impact defect in the promoted scope. Complete stabilization, then rerun final release gates. Deferred component backlog completion is not a prerequisite.
+
+## 0.5 overlay/style/size contract
+
+Default floating portals render in the owner body or active native modal, carrying scoped values/direction. Topmost dismissal, focus customization, closed-ancestor suspension and hover persistence follow OVERLAYS.md. Default portal DOM placement is an explicit 0.x migration; local placement remains available. Stable ref targets and the public void useDismiss return remain unchanged.
+
+Legacy aggregate/reset/tokens/classes remain compatibility mode. Isolated CSS, prefixed schema, controlled ThemeScope, optional minimal reset and measured family entries follow STYLING.md. Product/layout tokens remain legacy/app-owned. Scope persistence is caller-owned; document hooks retain aa-theme behavior. Compact density and a font-install packaging migration were evaluated and deferred with reasons in STYLING.md/SIZE.md. No zero-dependency, universal RTL/AT or production performance claim is added.

package/DOCS.md

@@ -0,0 +1,80 @@
+# Public documentation contract and coverage
+
+For Contour 0.6.0, the public package/repository is an independent source of installation, API, recipe and reproduction material. The separate catalogue can describe an older installed release; its visual demos are not proof that this source version is installed there. Catalogue editing and per-component website promotion are separate work.
+
+## Contract for a promoted guide
+
+Every promoted stable component page must contain: purpose and when not to use; public imports and executable TSX; emitted prop types, defaults and inherited native props; anatomy/parts; controlled/default state; native ref target; name/form/required/disabled/reset behavior; keyboard/focus/dismissal; CSS classes/tokens/state selectors; loading/empty/error/long content; RTL/localization; exact version/source; limitations and a version/component issue link with a public reproduction. Mark an item inapplicable with a reason rather than omitting it. A recipe is not a component export. An automated accessibility check is not a manual assistive-technology report.
+
+[Combobox](COMBOBOX.md) is the new full component guide. [Table and application recipes](RECIPES.md) share a guide because Table is a native presentation frame and each recipe owns a different application workflow. [GETTING-STARTED.md](GETTING-STARTED.md) covers standalone/embedded setup, providers by need, theme/bootstrap/CSP, navigation and optional features. [PUBLIC-API.md](PUBLIC-API.md) inventories every runtime/type export with versioned source and status; types without runtime values are not missing components.
+
+## Source and drift checks
+
+Displayed recipe links point to the actual shipped TSX modules, not a second copy. Packed tests copy those files into fresh React 18/19 consumers, compile with strict declarations and exercise behavior. Complete TSX fences in Combobox/onboarding references also compile. Starters are copied from the archive, installed independently and production-tested; final registry mode runs after publication. Source tags/issue versions match package.json; candidate tag links become available at publication. New release changes must update public guide labels, README, declarations and changelog together.
+
+The coverage register below maps public UI components to an explicit shared reference or dedicated guide. “Shared; promotion pending” means discovery/type coverage exists but a full component page has not been completed. It is a **documentation gap**, not an absent export or claim of stable-page completeness. Hook/helper/type coverage is retained in the complete PUBLIC-API register; optional entry setup/lifecycle is shared with GETTING-STARTED. The package's check:docs script compares the component list with source exports, requires guide targets and compiles advertised copyable source through the release gates.
+
+<!-- component-coverage:start -->
+
+| Component        | Public reference                         | Coverage                       |
+| ---------------- | ---------------------------------------- | ------------------------------ |
+| Alert            | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Avatar           | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Badge            | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| BrandMark        | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Breadcrumbs      | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Button           | [COMPOSITION.md](COMPOSITION.md)         | Shared; promotion pending      |
+| Card             | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Checkbox         | [FORMS.md](FORMS.md)                     | Shared; promotion pending      |
+| Combobox         | [COMBOBOX.md](COMBOBOX.md)               | New component contract covered |
+| CountUp          | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| DataTable        | [RECIPES.md](RECIPES.md)                 | Shared; promotion pending      |
+| DepthButton      | [COMPOSITION.md](COMPOSITION.md)         | Shared; promotion pending      |
+| Dialog           | [OVERLAYS.md](OVERLAYS.md)               | Shared; promotion pending      |
+| Disclosure       | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Divider          | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| DropdownMenu     | [OVERLAYS.md](OVERLAYS.md)               | Shared; promotion pending      |
+| EmptyState       | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| ExternalLink     | [COMPOSITION.md](COMPOSITION.md)         | Shared; promotion pending      |
+| Field            | [FORMS.md](FORMS.md)                     | Shared; promotion pending      |
+| FlipCard         | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| GitHubIcon       | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| IconButton       | [COMPOSITION.md](COMPOSITION.md)         | Shared; promotion pending      |
+| Kbd              | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| LinkedInIcon     | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Magnetic         | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Marquee          | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Pagination       | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Popover          | [OVERLAYS.md](OVERLAYS.md)               | Shared; promotion pending      |
+| ProgressBar      | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| RadioGroup       | [FORMS.md](FORMS.md)                     | Shared; promotion pending      |
+| Reveal           | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| RevealHeading    | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| SceneBoundary    | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| ScrollProgress   | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| SectionLabel     | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| SegmentedControl | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| SelectField      | [FORMS.md](FORMS.md)                     | Shared; promotion pending      |
+| Skeleton         | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Slider           | [FORMS.md](FORMS.md)                     | Shared; promotion pending      |
+| Spinner          | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Stat             | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Stepper          | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Switch           | [FORMS.md](FORMS.md)                     | Shared; promotion pending      |
+| Table            | [RECIPES.md](RECIPES.md)                 | New component contract covered |
+| Tabs             | [COMPOSITION.md](COMPOSITION.md)         | Shared; promotion pending      |
+| Tag              | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| TextArea         | [FORMS.md](FORMS.md)                     | Shared; promotion pending      |
+| TextField        | [FORMS.md](FORMS.md)                     | Shared; promotion pending      |
+| ThemeScope       | [GETTING-STARTED.md](GETTING-STARTED.md) | Shared; promotion pending      |
+| ThemeToggle      | [GETTING-STARTED.md](GETTING-STARTED.md) | Shared; promotion pending      |
+| TiltCard         | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Timeline         | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| ToastProvider    | [PUBLIC-API.md](PUBLIC-API.md)           | Shared; promotion pending      |
+| Tooltip          | [OVERLAYS.md](OVERLAYS.md)               | Shared; promotion pending      |
+
+<!-- component-coverage:end -->
+
+## Remaining promotion work
+
+The original website per-component pages, search/pattern discovery, legacy URL preservation, generated prop metadata and versioned website archives remain separate work. Existing shared guides must be audited against this contract before each component is promoted. Manual screen-reader/physical device evidence is tracked separately from automated fixture results. This register deliberately leaves those gaps visible.

package/FOUNDATION.md

@@ -0,0 +1,35 @@
+# Interaction foundation
+
+Decision for the 0.6.0 candidate, evaluated 14 October 2026: use **Base UI 1.9.0** for the new single-select Combobox. Existing native controls, Contour overlays, public APIs and CSS remain owned by Contour. This is a bounded decision, not a migration of every component or a claim that one foundation is universally better.
+
+## Comparison
+
+The same published Contour 0.5.0 host, data, CSS, nested Popover and application-owned asynchronous search were exercised with React 18.3.1 and 19.3.0 in Chromium 153. The candidates were installed from npm archives with strict peers. Each fixture was server-rendered and hydrated; refs, form reset, native modal placement, nested dismissal, stale requests, disabled options, synthetic IME events, RTL and forced colors were checked. Query cancellation belongs to the common application fixture, not to any foundation.
+
+| Candidate                                | Fit and cost in this fixture                                                                                                                             | Integration work                                                                                                                                                                                                                                           |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Base UI 1.9.0, MIT                       | Allowed-value Combobox, value/label collection mapping, forms and unstyled parts. Adds 6 packages / 11,574,796 installed bytes over the common baseline. | Preserve Contour layer ordering and inherited theme, use an owner-document/native-dialog portal, and define missing-value policy. Core nested Escape and native modal cases passed on both React majors.                                                   |
+| Radix Popover 1.3.1 + cmdk 1.1.1, MIT    | Radix supplies overlays, not a Combobox. Adds 33 packages / 1,381,618 installed bytes.                                                                   | A separate command-menu selection adapter supplies value mapping, hidden form input, validation and query semantics. React 18 nested dismissal was inconsistent in this prototype; this is bounded integration evidence, not a general Radix defect claim. |
+| React Aria Components 1.22.1, Apache-2.0 | Collection, localization and form facilities. Adds 13 packages / 30,671,216 installed bytes.                                                             | Controlled query/selection synchronization and portal configuration are explicit. Escape also dismissed the Contour parent in this fixture, requiring a dismissal bridge. Portal-container API migration adds adapter maintenance.                         |
+
+Installed bytes include declarations and upstream components that are not necessarily downloaded by the browser. The comparison is not a zero-dependency or tree-shaking claim. The library's production size gate separately measures Button, forms, table and Combobox journeys from its packed artifact. Base UI's date-fns and timezone peers are optional and are not needed for Combobox. No second foundation or table engine becomes a core dependency.
+
+## Ownership and limits
+
+Contour exports a single-select string-ID API, typed native input/popup parts and its own semantic styling. Base UI owns collection navigation, active-descendant behavior and selection mechanics. Contour bridges that popup into its dismissal stack and modal/top-layer boundary. Its adapter also prevents the foundation's closed-Escape clear action so an enclosing Contour layer can dismiss without silently clearing the selected ID. Existing Dialog, SelectField and Popover contracts are not replaced with upstream types.
+
+Stable IDs must be unique and nonempty. Labels may change or repeat. Filtering must not redefine identity. For remote search, the application retains the selected option separately from current results, cancels or ignores obsolete requests and validates its server data. An unresolved selected ID is visibly invalid and contributes an empty form value until resolved or changed; it is never invented as a valid choice. Disabled choices cannot be newly selected; disabled controls are omitted from form submission.
+
+Automated checks do not establish VoiceOver/NVDA certification, physical IME composition, mobile keyboard behavior or all browser/assistive-technology combinations. Those remain manual release evidence gaps. A descendant popup must be tested with any third-party modal library before claiming interoperability.
+
+## Upstream maintenance and licensing
+
+The primary implementations are TypeScript/React with JavaScript distributions and declarations. Base UI has versioned release/migration notes and active 1.9 releases; pinning the adapter dependency makes upgrades reviewable. React Aria and Radix likewise have their own versioned releases. cmdk is a separate project with its own cadence; an older release alone does not prove it is unmaintained. Supported React peer ranges do not prove every framework or browser configuration.
+
+Retain upstream copyright/license notices when redistributing their code. These packages retain their own licenses; Contour's authored code remains MIT. npm dependency packages include their upstream notices. We do not copy a foundation's source into Contour or claim its accessibility work as independent certification.
+
+Primary references: [Base UI Combobox](https://base-ui.com/react/components/combobox), [releases](https://base-ui.com/react/overview/releases), [MIT license](https://github.com/mui/base-ui/blob/master/LICENSE); [Radix Popover](https://www.radix-ui.com/primitives/docs/components/popover), [MIT license](https://github.com/radix-ui/primitives/blob/main/LICENSE), [cmdk](https://github.com/dip/cmdk); [React Aria ComboBox](https://react-aria.adobe.com/ComboBox), [Apache-2.0 license](https://github.com/adobe/react-spectrum/blob/main/LICENSE).
+
+Local open-state axe inspection reports aria-hidden-focus on temporarily hidden background controls. Tab/Shift+Tab/outside-focus behavior must be considered alongside that static result; the raw finding remains recorded and manual AT review is pending. See COMBOBOX.md. The adapter uses the public virtual-anchor and collision-Rect extension points to keep fixed-position coordinates correct under inherited CSS zoom; it does not copy or patch upstream internals.
+
+Contour also owns synchronous input activation to avoid an obsolete upstream touch-open timer reopening a selected/closed picker. Public event cancellation/propagation hooks preserve native document observers and caller Escape vetoes. These adapters are regression-tested without exposing upstream event types in Contour props.

package/GETTING-STARTED.md

@@ -0,0 +1,63 @@
+# Adopt Contour — 0.6.0
+
+Use [the standalone Vite starter](examples/starters/vite), [Next App Router starter](examples/starters/next), or add one component to an existing app. Each folder is public and independent; no private catalogue source, repository aliases, provider stack or application layout is required. Direct dependencies are exact; generate and commit your application's lockfile, then use npm ci. Candidate source requires an archive until its matching version is published.
+
+## Existing application
+
+```sh
+npm install --save-exact @abuzareal/contour-ui@0.6.0
+```
+
+Install matching react/react-dom versions in the supported ranges (^18.3.1 or ^19.0.0). React 18.3.1, 19.0.0 and 19.3.0 have independent packed consumer checks; a peer range is not a claim of every framework configuration. Native form/overlay APIs are client interactions. Use the library's emitted declarations instead of a copied API from an old catalogue.
+
+```tsx
+import { Button, ThemeScope } from "@abuzareal/contour-ui";
+import "@abuzareal/contour-ui/scoped.css";
+export function EmbeddedAction() {
+  return (
+    <ThemeScope theme="light">
+      <Button onClick={() => console.log("Local action")}>Continue</Button>
+    </ThemeScope>
+  );
+}
+```
+
+This fixed light scope is intentional: it does not own the host document theme/storage. To let ThemeToggle change it, supply controlled theme and onThemeChange to ThemeScope. A fixed scope without a callback disables its toggle. No document bootstrap is needed for a deterministic embedded scope. Keep your router, reset and fonts. scoped.css supplies tokens and all prefixed component styles; selective entry imports are documented in [SIZE.md](SIZE.md). The opt-in minimal-reset.css and legacy reset.css have different scopes; do not import a global reset accidentally. System fonts work without fonts.css/fonts-latin.css. Native button/anchor form roles remain intact.
+
+## Providers, forms and navigation
+
+Button, fields, Combobox, Table, Dialog, Popover and ordinary controls work without a provider. Dialog/Popover open state belongs to the caller. **ToastProvider** is required only around useToast consumers; mount one owner for the part of the app that needs its queue. ThemeScope is an optional embedded-theme boundary, not a universal installation requirement. No Base UI provider or table engine is required to consume Combobox. Direction/theme is inherited into its portal.
+
+The [native/RHF form recipes](FORMS.md) use the actual files in examples/forms. Native name/form/required/disabled/reset contracts remain native; RadioGroup/Slider/Switch differences are documented there. React Hook Form is an application dependency only for the RHF recipe; it is absent from core consumers. Application adapters own cross-field validation, parsed data, persistence, pending/error/retry and server validation. The [new recipes](RECIPES.md) add async selection, safe confirmation and remote tables without turning them into hidden services.
+
+Use Button for actions and native anchors or the router's Link for navigation. [COMPOSITION.md](COMPOSITION.md#native-and-router-links) has executable anchor/Next examples using buttonClassName("secondary"). Keep href/to, modified clicks, context menus and ref forwarding; never nest an anchor in a button. The Vite starter uses a native hash link; the Next starter uses Next Link with ordinary client navigation. Other router adapters need their own tested ref/anchor contract; do not infer universal support.
+
+## Document theme and CSP
+
+For a document-owned theme, import themeBootstrapScript/themeColors from the **pure server-safe** `@abuzareal/contour-ui/theme-bootstrap` subpath. Inject that exact script before the first paint. It reads aa-theme only for light/dark, falls back to the system preference, sets html[data-theme] and updates an existing theme-color meta. themeColors is light #f2f3ee / dark #0f100d. Blocked storage falls back without throwing; useTheme's root behavior owns document attributes/storage and follows system changes when there is no stored choice. It is not an arbitrary persisted settings provider. ThemeToggle's accessible name is constant (“Dark theme” by default); aria-pressed expresses state and title describes the next action.
+
+Hash **the exact script bytes** with SHA-256 and authorize that hash in script-src, or use a cryptographically random per-request nonce on the bootstrap and framework scripts. Do not copy a stale hash across versions or reuse/cache a nonce. The actual [Vite config](examples/starters/vite/vite.config.ts) calculates and inserts the hash; [Next proxy](examples/starters/next/proxy.ts) and [layout](examples/starters/next/app/layout.tsx) carry a new nonce through server rendering. Next's nonce setup is dynamic, not static export/ISR/shared-cache output. Both paths are production browser checks, not merely snippets. Only the html attribute touched before hydration uses suppressHydrationWarning in Next.
+
+Production scripts do not require unsafe-inline/unsafe-eval in these starters. **Inline styles are allowed** for library geometry and host styles; this is a restricted script policy, not a claim that every CSS directive can be nonce-only. Configure font/image/service origins deliberately. Root bootstrap does not initialize independent ThemeScope state; choose a deterministic scope or derive initial state explicitly in your app. Do not hide arbitrary hydration mismatches.
+
+## Optional features
+
+Core imports require neither Three.js nor Lenis. Opt in only for a real product need:
+
+```sh
+npm install --save-exact three@0.186.1
+# Only for the optional scrolling recipe:
+npm install --save-exact lenis@1.3.26
+```
+
+Copy [LazyScene.tsx](examples/optional/LazyScene.tsx) and [optional.css](examples/optional/optional.css). It imports /three only after “Load 3D study”, gives the host a real block size, retains useful static artwork outside SceneBoundary/Suspense, and passes both app pause and system reduced-motion state. SceneBoundary hides failed scenes; it has no fallback prop and cannot manufacture a visual replacement. Sculpture/ObjectStudy are decorative scene components; product meaning stays in adjacent DOM content. The optional entry includes the public scene APIs/types; use [PUBLIC-API.md](PUBLIC-API.md) for their exact experimental contracts.
+
+useThreeStage captures setup/cameraDistance once per mount. setup receives scene/camera/renderer and optional onDispose registration. Register cleanup immediately after every owned GPU allocation, including resources created before setup can throw. A returned StageScene supplies update, rest, dispose and optional resize. Do not double-dispose the same resource through both onDispose and dispose. The stage caps pixel ratio at 1.75, observes sizing, stops unnecessary hidden/offscreen animation and redraws a still pose when paused. The caller owns stable setup inputs, meaningful sizing, lazy boundaries, static fallback and content. Unavailable WebGL/partial setup must leave useful DOM content. No physical GPU/device coverage is implied by headless fixtures.
+
+Copy [OptionalSmoothScroll.tsx](examples/optional/OptionalSmoothScroll.tsx) and [SmoothScrollOwner.tsx](examples/optional/SmoothScrollOwner.tsx) only after installing Lenis. The lazy owner imports lenis/dist/lenis.css and calls /scroll's useSmoothScroll once. Native scroll works until opt-in. Reduced motion disables/unmounts that owner; unmount destroys Lenis. Do not mount multiple RAF/scroll owners, fight native focus/hash restoration or silently enable smooth motion for users who requested reduction. This recipe is for the Vite/client integration; Next Lenis is **unverified**.
+
+## Framework boundaries and reproduction
+
+Supported evidence names the exact pair: Next 16.4.0 App Router, React/React DOM 19.3.0, webpack production build, plus its separate optional lazy Three fixture. Turbopack, Pages Router, Next Lenis, static nonce export and arbitrary third-party modal interoperability are not promoted to supported configurations. Vite starter pins 8.3.2 with React 18.3.1. Server-safe helper imports, client directives, declarations and hydration are checked independently; SSR rendering alone does not prove hydration.
+
+Copy [the public reproduction folder](examples/reproduction), reduce it to the failing interaction, and include exact package/browser versions and keyboard steps. Its [issue link](https://github.com/abuzareal/contour-ui/issues/new?template=bug_report.yml&title=Integration%200.6.0%3A%20&component=Integration&version=0.6.0) contains version/component, not private data. Report only synthetic records and public reproducible source. [Documentation coverage and limits](DOCS.md).

package/NEXTJS.md

@@ -1,6 +1,6 @@
 # Next.js App Router integration
 
-This guide describes **Contour 0.4.0**. npm 0.1.2 does not include the client directives, native refs or relative Latin font files described here. Check npm for release availability before installing. The fixture pins Next 16.4.0 with React/React DOM 19.3.0, uses the webpack production build, and consumes an npm archive. It does not establish every Next version, Turbopack, Pages Router, scroll entries or hosting platform. A separate optional mode checks a lazy Three.js scene with SSR disabled and disposal on navigation.
+This guide describes **Contour 0.6.0**. npm 0.1.2 does not include the client directives, native refs or relative Latin font files described here. Check npm for release availability before installing. The fixture pins Next 16.4.0 with React/React DOM 19.3.0, uses the webpack production build, and consumes an npm archive. It does not establish every Next version, Turbopack, Pages Router, scroll entries or hosting platform. A separate optional mode checks a lazy Three.js scene with SSR disabled and disposal on navigation.
 
 In `app/layout.tsx`, load CSS once:
 
@@ -53,3 +53,7 @@ Run `npm run test:next` to rebuild and consume the candidate archive. The fixtur
 The 0.4.0 fixture also verifies Button native-ref focus and styled Next Link ordinary/canceled/middle-click navigation. Use [the composition guide](COMPOSITION.md#native-and-router-links) for the Link recipe; Button remains an action rather than a polymorphic navigation component.
 
 Named form/reset APIs and copyable form recipes are described in [FORMS.md](FORMS.md). They remain client interactions; server-side validation and persistence belong to your application.
+
+For embedded first use, substitute scoped.css, omit fonts/bootstrap/reset, and wrap client controls in controlled ThemeScope. The size fixture separately measures Button/settings/table routes with system fonts on the same pinned webpack configuration. Existing document-owned/branded integration above remains compatible; new portal migration and family imports are described in OVERLAYS.md and SIZE.md.
+
+The standalone [Next starter](examples/starters/next) adds a tested per-request nonce CSP and dynamic layout using Next 16.4.0/React 19.3.0/webpack and TypeScript 7.0.2. Its strict DOM/ES2024 declaration check is separate from the older generated JS fixture. Follow [onboarding](GETTING-STARTED.md) for the existing-app, provider and optional-feature paths.

package/OVERLAYS.md

@@ -0,0 +1,52 @@
+# Floating layers and focus
+
+0.5 adds shared dismissal, collision-aware placement and portals to Popover, DropdownMenu and Tooltip. Dialog remains a native modal/drawer. Contour uses MIT-licensed Floating UI DOM 1.8.0 for geometry and observers; it does not replace the public components with another component library.
+
+## Dismissal
+
+One Escape reaches the deepest active layer; independent siblings use most-recent activation. Paint order follows that dismissal order. One outside primary-pointer press dismisses at most one layer. Presses in portaled descendants are inside their owned layer. Explicit buttons can still perform their own actions. A native modal backdrop does not also dismiss its modal when that press already belongs to a child layer.
+
+Listeners attach to the layer's owner document, rebind on document moves and release on inactivity/unmount. They never stop event propagation. Handled Escape prevents its native default so a child dismissal does not also cancel its native parent dialog. Other keys and ordinary outside focus remain available. `onDismiss(reason, nativeEvent)` on Popover/Menu can call `preventDefault()` to veto dismissal. Dialog uses its existing `onCancel` and `onClick` cancellation contracts. `useDismiss(ref, active, callback, options)` uses the same registry; additional `branches` include a caller's trigger/portal. `layerElement` opts a custom floating element into owned stack order; its previous inline z-index is restored on release.
+
+A closed ancestor suspends descendant layers without clearing their controlled/uncontrolled state. Reopening resumes that state; reset child state in the parent's application callback when a different policy is wanted. Modal/native close buttons and controlled parent updates are application-owned.
+
+## Placement and containers
+
+Popover/Menu accept `side` (bottom by default), `align` (start by default; center/end supported), `sideOffset` (8 px) and `collisionPadding` (8 px). Tooltip retains `placement` (top), with center alignment and a 10 px offset. Alignment is logical in RTL. Placement flips, shifts on both axes and constrains scrollable content to the clipping boundary; scroll/resize/layout/element observers update it while open and clean up on close. Nonfinite offsets/padding fall back to defaults; negative collision padding clamps to zero. A geometry failure retains a viewport fallback and emits a warning rather than leaving an unhandled promise. Geometry properties and stack order are owned; use part props for appearance/content, not competing position/transform declarations. `--contour-z-overlay` configures the nonmodal stacking base (30); native modal top-layer ordering is browser-owned.
+
+Default `portal` is true. Content renders in the trigger's owner-document body, or **inside its open native dialog**. A small portal wrapper carries inherited variables, font, text color and direction and follows ancestor theme/style mutations. This escapes a clipped or transformed theme root without changing the document's theme. `container` selects an explicit element in the same document; outside/wrong-document containers inside an active modal fall back to that modal. Keep custom containers unclipped and provide enough space. `portal={false}` preserves local DOM placement for a deliberate integration; clipping ancestors may then clip it.
+
+**Migration from 0.4:** default portal DOM placement changes ancestor selectors and DOM-based tests. Target `panelProps.className` directly rather than `.host-root .host-panel`; use `portal={false}` when local placement is required. Root refs still target the wrapper, trigger refs target buttons and panel refs target panels, and may detach/reattach when the portal container changes. No deep import is needed.
+
+## Triggers and focus
+
+`trigger` still supplies button content. `renderTrigger` supplies a supported ref-forwarding button component. Spread the provided props so refs, caller handlers and owned type/expanded/controls/haspopup relationships survive; do not nest a button inside the default trigger. An ordinary native button or Contour Button works. Link/non-button triggers are not supported by this contract.
+
+```tsx
+import { Button, Popover, TextField } from "@abuzareal/contour-ui";
+export function HelpPanel() {
+  return (
+    <Popover
+      title="Help"
+      trigger="Help"
+      renderTrigger={(props) => <Button {...props} variant="secondary" />}
+    >
+      <TextField label="Question" />
+    </Popover>
+  );
+}
+```
+
+Popover focuses its panel on entry; `initialFocus={ref}` selects a mounted descendant and `initialFocus={false}` keeps the trigger focused. Cancelable `onOpenAutoFocus` / `onCloseAutoFocus` events allow caller control. Escape returns to a connected trigger by default, including controlled dismissal requests. Outside press does not steal focus from its destination. Programmatic close/unmount returns focus when the layer or a descendant owned it. A missing/removed trigger receives no forced substitute; the application owns its workflow fallback. Popover is nonmodal: it does not trap focus or make the background inert. Portal DOM order affects Tab order; choose inline placement or explicit focus customization for an application-specific sequence.
+
+Menu enters the first enabled action; ArrowUp from its trigger enters the last. ArrowUp/Down, Home/End and typeahead skip disabled entries. Selection/Escape return to the trigger; Tab dismisses without consuming Tab. Empty/all-disabled menus focus their panel. Labels/content are caller-owned. Dialog uses native focus confinement and focus return; its new `initialFocus` chooses a mounted modal descendant. `onOpenAutoFocus` can cancel that explicit override; it does not undo native showModal autofocus. Existing nested locks, drawer placement, long content and cleanup remain supported.
+
+## Supplemental hints
+
+Tooltip content is a noninteractive string. Hover and keyboard focus cooperate; leaving the pointer does not erase a focused hint. Trigger-to-content travel stays available through a bounded pointer corridor; the hint remains while pointer/focus applies. Escape suppresses it until the current hover/focus conditions end and a new session begins. Existing `aria-describedby` values and the child's accessible name/ref/events are retained. Pointer content is hoverable; tooltip content is never a substitute for a visible label, essential instruction, validation error or interactive panel. Touch users must have the same essential information visibly available.
+
+Production checks cover nested/sibling/portaled layers, native modal portals, touch outside press, RTL, narrow/resized viewports, long scrolling panels and CSS zoom. These are automated browser checks, not physical mobile-keyboard or assistive-technology certification. See [W3C hover/focus guidance](https://www.w3.org/WAI/WCAG21/Techniques/client-side-script/SCR39) and [Floating UI observer lifecycle](https://floating-ui.com/docs/autoupdate).
+
+Keep a portal container stable while open. Changing its DOM target can remount the portaled subtree; keep unsaved child state in the owner when container changes are required.
+
+Default-open children choose an enclosing native dialog even before its open attribute is set. When Dialog calls showModal in the same commit, these children enter its top layer without an additional click or render.