@abuzareal/contour-ui 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -6,6 +6,22 @@ Changes to the published `@abuzareal/contour-ui` package. Version headings refer
 
 No changes recorded.
 
+## 0.6.1
+
+Compatible source corrections; publication is pending. Restore print theme/disclosures on repeated events or unmount, cancel delayed hash alignment after unmount, preserve delimiter-containing scroll-spy IDs, and close an open Combobox on Tab without cancelling native traversal or changing selection. Add hook/helper/optional-entry references, emitted prop/example drift checks, JavaScript onboarding and migration/history material. Correct the open Combobox background hiding with a labelled non-modal popup, keeping Base UI selection/navigation/positioning parts. Strict whole-document accessibility scans now pass in selected Chromium/WebKit fixtures; the unmodified upstream composition remains a separate failing diagnostic. Add visual QA without excluding axe rules. Manual screen-reader checks remain pending; no universal accessibility claim is made.
+
+## 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.

package/COMBOBOX.md

@@ -0,0 +1,87 @@
+# Combobox — 0.6.1
+
+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.1/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 correction in 0.6.1:** Contour uses a labelled non-modal popup region and listbox, retaining Base UI's public selection/navigation/positioning parts. Opening it no longer hides the surrounding page. Whole-document axe scans pass in the selected Chromium/WebKit fixtures with no excluded rules; Tab and Shift+Tab close it while preserving native traversal. The older Base UI Popup composition's failing diagnostic remains available separately. See [support evidence and limitations](SUPPORT.md); manual VoiceOver/NVDA review remains pending. These fixtures do not establish WCAG conformance.
+
+[Report Combobox 0.6.1](https://github.com/abuzareal/contour-ui/issues/new?template=bug_report.yml&title=Combobox%200.6.1%3A%20&component=Combobox&version=0.6.1), using the [public minimal reproduction](examples/reproduction). Source links for this version resolve when its release tag is published.

package/COMPOSITION.md

@@ -191,3 +191,7 @@ Anchors have no native disabled state. Render a suitable non-link explanation wh
 ## Abstraction review
 
 Each addition serves a bounded need: native focus/measurement/trigger refs; existing Dialog/Tabs/Popover root/part access; ID-based reorder-safe tab focus; caller handler cancellation. Private helpers implement those lifecycles. No runtime dependency, provider, build/distribution/styling system, generic component-replacement API or blanket polymorphism is introduced. Existing menu disabled items, keyboard opening, typeahead, stable identity and focus return remain covered.
+
+## Version and reproduction
+
+Reference version **0.6.1** (candidate until published). [Versioned source](https://github.com/abuzareal/contour-ui/tree/v0.6.1/src) and [emitted type inventory](PUBLIC-API.md) describe this contract; tag links resolve after release. [Report Composition 0.6.1](https://github.com/abuzareal/contour-ui/issues/new?template=bug_report.yml&component=Composition&version=0.6.1), using the [public minimal reproduction](examples/reproduction) and synthetic data.

package/CONTRACTS.md

@@ -1,16 +1,16 @@
 # Architecture, scope and compatibility
 
-Contract version **0.5.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.1**, 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,29 +30,29 @@ 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.
 
 ## Environment and validation policy
 
-| Environment             | Declared or exercised scope                                                                            | Limits                                                                                                               |
-| ----------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| React/ReactDOM          | Peer range above; packed matrix exercises 18.3.1, 19.0.0 and 19.3.0                                    | Matching pairs required. Other allowed patches are not individually certified.                                       |
-| TypeScript              | Strict source/fixtures; pinned optional/Next fixtures use 5.9.3; React 18 and 19 declarations compiled | No universal older/newer compiler support claim; JS users need no compiler at runtime.                               |
-| Node                    | Manifest >=22 for installation/tooling; use 22.12+ or 24+ with current Vite tooling                    | Browser components do not need Node in the browser. Actual runner versions are recorded per check.                   |
-| ESM/CSS-capable bundler | Packed Vite consumers exercise imports/declarations/CSS/fonts with no optional peers                   | No CommonJS build or unbundled-browser CSS loader promised.                                                          |
-| Next.js                 | Next 16.4.0 / React and ReactDOM 19.3.0, App Router, webpack production build                          | [NEXTJS.md](NEXTJS.md); other versions, Turbopack, Pages Router and Next Lenis remain unverified.                    |
-| Optional Three          | Separate consumers and lazy Next mode; explicit Three/types, WebGL, sized host and static fallback     | Experimental API; sampled lifecycle checks do not validate every custom scene/GPU/device.                            |
-| Optional scroll         | Separate declaration/build consumer with Lenis and one scroll owner                                    | Caller handles pause/reduced motion; generic Next Lenis integration unverified.                                      |
-| Browsers                | Playwright Chromium exercises selected native-dialog/reset/graphics/hydration/catalogue journeys       | Emulation is not a physical device. Chromium/axe is not Firefox/WebKit/Safari or manual VoiceOver/NVDA verification. |
+| Environment             | Declared or exercised scope                                                                                                                          | Limits                                                                                                                                 |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| React/ReactDOM          | Peer range above; packed matrix exercises 18.3.1, 19.0.0 and 19.3.0                                                                                  | Matching pairs required. Other allowed patches are not individually certified.                                                         |
+| TypeScript              | Strict source/fixtures; optional/existing Next fixtures use 5.9.3; standalone current Next starter uses 7.0.2; React 18 and 19 declarations compiled | No universal older/newer compiler support claim; JS users need no compiler at runtime.                                                 |
+| Node                    | Manifest >=22 for installation/tooling; use 22.12+ or 24+ with current Vite tooling                                                                  | Browser components do not need Node in the browser. Actual runner versions are recorded per check.                                     |
+| ESM/CSS-capable bundler | Packed Vite consumers exercise imports/declarations/CSS/fonts with no optional peers                                                                 | No CommonJS build or unbundled-browser CSS loader promised.                                                                            |
+| Next.js                 | Next 16.4.0 / React and ReactDOM 19.3.0, App Router, webpack production build                                                                        | [NEXTJS.md](NEXTJS.md); other versions, Turbopack, Pages Router and Next Lenis remain unverified.                                      |
+| Optional Three          | Separate consumers and lazy Next mode; explicit Three/types, WebGL, sized host and static fallback                                                   | Experimental API; sampled lifecycle checks do not validate every custom scene/GPU/device.                                              |
+| Optional scroll         | Separate declaration/build consumer with Lenis and one scroll owner                                                                                  | Caller handles pause/reduced motion; generic Next Lenis integration unverified.                                                        |
+| Browsers                | Selected Chromium and WebKit production fixtures; exact results and known failures in SUPPORT.md                                                     | Emulation is not a physical device. Engine emulation is not physical Safari or manual VoiceOver/NVDA; local Firefox launch is blocked. |
 
 Release gates use one exact archive: types/lint/build, Node/component tests, native-dialog/graphics browser checks, exports/archive inspection, React matrix, optional consumers, pinned Next core/lazy-Three modes and dependency audit. Catalogue has separate required checks/affected journeys. Record checksum, actual environments and passed/failed/skipped/blocked results. Historical results are dated evidence, not a fresh pass; see [RELEASING.md](RELEASING.md).
 
@@ -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
 

package/DOCS.md

@@ -0,0 +1,86 @@
+# Public documentation contract and coverage
+
+For Contour 0.6.1, 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, full website prop-page generation and versioned website archives remain separate work. A bounded emitted-declaration prototype and drift gate now live in PROP-REFERENCE.md and docs/prop-metadata.json; REFERENCE.md maps all symbols and style/data paths. 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.
+
+## Library reference work
+
+[HOOKS.md](HOOKS.md), [HELPERS.md](HELPERS.md) and [THREE.md](THREE.md) document non-component contracts and lifecycle ownership. [PROP-REFERENCE.md](PROP-REFERENCE.md) audits the nine historical guides and explains generated versus authored metadata. [MIGRATION.md](MIGRATION.md) preserves version-specific contracts and upgrade/rollback steps; [MODELS.md](MODELS.md) distinguishes package/source/company documentation models. [SUPPORT.md](SUPPORT.md) records automated/manual results and failures. Full PAGE website promotion remains separate.
+
+JavaScript and TypeScript onboarding use the same source contract: scripts/build-onboarding.mjs strips types into the shipped JSX example and check:onboarding detects drift. The examples are copied from the actual archive for strict TS/build checks and exercised as independent browser journeys. No private workspace guidance is required to consume them.

package/FORMS.md

@@ -92,3 +92,7 @@ Native TextField registration forwards name/onChange/onBlur/ref. RHF submits its
 The recipe uses useForm defaultValues, RHF field validation/server errors, handleSubmit, controller refs and reset. Its reset command performs native form.reset() first so registered field counters/auto-resize observe the reset, then reset(defaults) updates RHF state. For arbitrary programmatic RHF setValue calls on fields with counters/auto-resize, use Controller and pass the controlled value; direct DOM writes through a registered ref do not dispatch native input events. Its shared submission lifecycle ignores late results after reset/cancel/unmount even if the service disregards AbortSignal. Real services must enforce validation, authentication, authorization, CSRF policy and idempotency/overlap handling at the server boundary. Treat parsed responses as unknown until your adapter validates them; TypeScript alone does not validate network data.
 
 References: [React native input ownership](https://react.dev/reference/react-dom/components/input), [native range semantics](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/range), [RHF Controller](https://react-hook-form.com/docs/usecontroller/controller), [RHF reset](https://react-hook-form.com/docs/useform/reset), [Radix Switch form contract](https://www.radix-ui.com/primitives/docs/components/switch). These inform bounded contracts; Contour does not add a second interaction foundation or copy their implementation. Native-form checks are scoped Chromium evidence, not cross-browser/screen-reader certification.
+
+## Version and reproduction
+
+Reference version **0.6.1** (candidate until published). [Versioned source](https://github.com/abuzareal/contour-ui/tree/v0.6.1/src) and [emitted type inventory](PUBLIC-API.md) describe this contract; tag links resolve after release. [Report Forms 0.6.1](https://github.com/abuzareal/contour-ui/issues/new?template=bug_report.yml&component=Forms&version=0.6.1), using the [public minimal reproduction](examples/reproduction) and synthetic data.

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).
+
+In 0.6.1, Contour replaces the Base UI Popup wrapper with its own labelled non-modal region, composed around the public Positioner/List/Item parts. This corrects the observed input-outside-popup background hiding without changing the selection/form contract, removing ARIA or patching private internals. The listbox uses the visible field label; closed popup content is hidden. Contour completes the public Root actions close lifecycle after hiding its non-animated popup so controlled query text returns to the selected label. Whole-document strict axe and keyboard checks pass in selected Chromium/WebKit fixtures. The original unmodified upstream composition remains a separate strict failing diagnostic, documented in SUPPORT.md; manual AT review remains pending. The adapter continues to use public virtual-anchor and collision-Rect extension points to keep fixed-position coordinates correct under inherited CSS zoom.
+
+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,67 @@
+# Adopt Contour — 0.6.1
+
+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.1
+```
+
+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.1%3A%20&component=Integration&version=0.6.1) contains version/component, not private data. Report only synthetic records and public reproducible source. [Documentation coverage and limits](DOCS.md).
+
+## JavaScript and TypeScript examples
+
+Copy [SettingsForm.jsx](examples/onboarding/SettingsForm.jsx) for a JavaScript React app or [SettingsForm.tsx](examples/onboarding/SettingsForm.tsx) for TypeScript. Render SettingsForm after importing scoped.css; both inspect the same native FormData locally, reset defaults/output and focus the native name input. Neither saves data or needs a provider. The JSX is generated by stripping types from the TSX source, not a second hand-maintained example; it contains no TypeScript syntax. Bring your own React entry/router and server validation. See MIGRATION.md for upgrades and older contracts.

package/HELPERS.md

@@ -0,0 +1,33 @@
+# Helpers and public types
+
+Use direct imports from `@abuzareal/contour-ui`. [PUBLIC-API.md](PUBLIC-API.md) links exact release source/types; [REFERENCE.md](REFERENCE.md) checks complete export coverage. Helpers do not require a provider. Only the pure operations below are server-call safe; importing the module and invoking a browser operation are different contracts.
+
+| Helper            | Inputs/defaults and result                                                                                               | Boundaries                                                                                                                                                                                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| cx                | Variadic string/false/null/undefined; joins truthy parts with spaces.                                                    | No class parsing, deduplication, token validation or prefixing. Use for arbitrary consumer strings/IDs only when joining is appropriate.                                                                                                                         |
+| ccx               | Same inputs; deduplicates whitespace-separated names and appends contour-prefixed equivalents for known library classes. | Compatibility class helper, not an ID/ARIA builder. Unknown consumer classes remain unchanged.                                                                                                                                                                   |
+| buttonClassName   | variant="primary", size="md", optional className; returns compatibility/prefixed button classes.                         | ButtonVariant: primary/accent/secondary/ghost/danger; ButtonSize: sm/md/lg. Styling an anchor does not give it button semantics.                                                                                                                                 |
+| formatIndex       | number; String(value).padStart(2,"0").                                                                                   | 3 → "03", 12 → "12". It does not round, add one, validate finite values, format a locale or normalize negative/fractional inputs. Pass an already chosen index.                                                                                                  |
+| fieldDescribedBy  | id, optional hint/error; error → id-error, else hint → id-hint, else undefined.                                          | Matches Field's message priority. Does not render an element or preserve arbitrary caller description IDs; callers merge those separately.                                                                                                                       |
+| nextIndexForKey   | key/current/count, orientation="horizontal", direction="ltr"; wrapped index or null.                                     | count<=0 and unrelated keys return null. Home/End choose extremes. RTL reverses horizontal arrows. It does not skip disabled items, focus DOM nodes or validate every numeric input. Caller owns a valid current index/count and disabled-item policy.           |
+| safeHref          | string or undefined; returns allowed href unchanged or undefined.                                                        | Rejects executable/disallowed schemes, including whitespace-obfuscated forms. Relative/hash/protocol-relative and permitted https/http/mailto/tel links are not a trusted-destination allowlist. Validate destination/origin and authorize redirects separately. |
+| storageKeys       | openingSeen="aa-opening-seen", theme="aa-theme".                                                                         | Retained legacy origin-wide keys; not namespaced per application/scope.                                                                                                                                                                                          |
+| readStorage       | area="local" or "session", key; string or null.                                                                          | Browser storage access wrapped in try/catch; blocked/missing/SSR access returns null. It does not parse/validate JSON or distinguish missing from denied.                                                                                                        |
+| writeStorage      | area/key/string value; boolean success.                                                                                  | False for inaccessible/throwing storage. It does not encrypt data, provide a schema, broadcast an app event or write a server cookie.                                                                                                                            |
+| motionDisabledFor | Element; boolean.                                                                                                        | Browser-only synchronous preference/ancestor check; see HOOKS.md.                                                                                                                                                                                                |
+
+## Public types
+
+Section is `{id: string; label: string; title: string; number: number}`. It describes repeated page metadata, not a router, validator or React element. The application supplies stable IDs and valid numbers. CopyStatus, Theme, DismissReason/Options, PanelFocusOptions, FloatingOptions, ToastInput and ToastContextValue are described with their hooks in HOOKS.md. Component Props/item/variant aliases remain in the emitted declarations; they are types, not additional component exports. Generic TableColumn and TabItem must be read with their associated component contracts.
+
+Use `import type` for type-only values. Do not deep-import dist files or assume a type-named symbol exists at runtime. Native inherited React props and overloads are retained by the declarations; generated metadata is a discovery aid and does not replace them. No arbitrary polymorphic component or enterprise grid contract is implied by these helpers.
+
+## Data and URL responsibility
+
+Read parsed storage/network data as unknown. Validate structures, elements, finite numbers/ranges and IDs before supplying components. A successful storage write is not server persistence. A safe URL scheme is not proof of a safe destination, a permitted server redirect or sanitized remote HTML. React escaping does not authorize data access; server validation and permissions remain at the relevant boundary.
+
+The JavaScript onboarding example in [GETTING-STARTED.md](GETTING-STARTED.md) uses the same native form payload contract without requiring TypeScript syntax. Report synthetic reproductions and exact package/browser versions; never include private storage contents or credentials.
+
+## Version and reproduction
+
+Reference version **0.6.1** (candidate until published). [Versioned source](https://github.com/abuzareal/contour-ui/tree/v0.6.1/src) and [emitted type inventory](PUBLIC-API.md) describe this contract; tag links resolve after release. [Report Helpers 0.6.1](https://github.com/abuzareal/contour-ui/issues/new?template=bug_report.yml&component=Helpers&version=0.6.1), using the [public minimal reproduction](examples/reproduction) and synthetic data.