@abuzareal/contour-ui 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 Changes to the published `@abuzareal/contour-ui` package. Version headings refer to package versions, not catalogue or application versions. Consumer projects pin their own version and update separately.
 
+## Unreleased
+
+No changes recorded.
+
+## 0.2.1
+
+A baseline contract release with compatible Checkbox ARIA and clipboard lifecycle fixes. Export names, prop types, visual defaults, dependencies and optional peer boundaries are unchanged from 0.2.0.
+
+- Checkbox preserves caller-supplied validation attributes and associates its description and error with the native input.
+- Clipboard feedback ignores writes that settle after unmount or after a newer copy request. No reset timer is created for an obsolete result.
+
+- Publish the complete public-export and maturity register, including runtime/type-only distinctions, ownership, intended use, documentation destinations, known limits and scoped verification references.
+- Publish architecture, adoption scope, environment/support evidence, dependency/size explanations and compatibility/deprecation rules.
+- Clarify native form/ref limitations, local overlay behavior, inherited CSS/theme contracts and experimental/legacy APIs. Disclosure exposes defaultOpen; controlled open state belongs to Popover and DropdownMenu.
+- Include both reference documents in the verified npm archive. Existing 0.2.0 consumers need no API or style migration; update the exact package pin and lockfile to receive the documents.
+
+```sh
+npm install @abuzareal/contour-ui@0.2.1 --save-exact
+```
+
+Publication is not established by this source heading. Verify npm availability; the catalogue's installed and hosted versions are separate.
+
+## 0.2.0
+
+- TextField, TextArea and SelectField expose native refs while retaining React 18/19 compatibility. Caller-supplied aria-invalid is preserved when no component error overrides it.
+- Uncontrolled field counters and textarea height follow native form reset, including external form association and canceled resets. A browser task waits for the native reset default action, and native input keeps counters current when an edit repeats the pre-reset value.
+- Tabs adds activeTabId/onTabChange; Popover and DropdownMenu add open/defaultOpen/onOpenChange. Existing uncontrolled defaults remain.
+- DropdownMenu skips disabled items, opens from ArrowUp/ArrowDown, supports label typeahead and accepts stable item ids.
+- Three stages release resources after partial initialization failure; setup can register disposal immediately. ObjectStudy reflows paused scenes on resize instead of arranging every animation frame.
+- Interactive modules retain client boundaries; ESM export targets also provide a default condition for framework dynamic-module resolution. A pinned packed Next.js App Router fixture checks the candidate. Latin font assets use relative packaged URLs with their licenses for webpack compatibility.
+- Contributor setup and issue/PR templates are portable. Release checks reuse one archive across compatibility consumers and publish that verified archive without rerunning source lifecycle gates.
+
+These changes are absent from 0.1.2. A separate Next.js fixture mode covers lazy Three.js; Lenis, alternate-bundler and wider framework support remain outside these checks.
+
 ## 0.1.2 — 2026-10-07
 
 An optional font-loading entry and clearer setup documentation. Component APIs and runtime dependencies are unchanged from 0.1.1.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of conduct
+
+Treat contributors and users with respect. Focus criticism on behavior and code. Harassment, discrimination, threats, sharing private information without permission and repeated personal attacks are unacceptable.
+
+Maintainers may remove disruptive material or restrict participation to keep the project usable. Send conduct concerns privately to abuzart1999@gmail.com, including links or evidence you are comfortable sharing. Reports are handled privately where possible; do not publish other people's personal details in issues.

package/CONTRACTS.md

@@ -0,0 +1,93 @@
+# Architecture, scope and compatibility
+
+Contract version **0.2.1**, reviewed 12 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.
+
+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.
+
+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.
+
+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.
+
+## Package and application ownership
+
+| Area | Owner |
+| --- | --- |
+| Reusable controls, semantic tokens, shared theme/motion/browser lifecycle, public APIs and package releases | contour-ui |
+| Catalogue shell/chapters, executable documentation/source display, discovery, examples and site delivery | Design-System |
+| Product layouts/routes, domain data/calculations, workflows, requests, validation and product-specific scenes | Each application |
+
+Repositories remain independent. Contour source is public and MIT licensed; catalogue source is currently private while hosted documentation is public. The catalogue's `private: true` prevents npm publication; it is separate from GitHub visibility. Visibility, history/assets/licensing review and CI runner policy are separate decisions.
+
+Catalogue UI/hook/scene compatibility modules intentionally forward public package APIs; they are not copied implementations. Preserve them while callers exist. New integrations can import public exports directly. Editing library source does not update an installed or deployed application.
+
+## Implementation and dependency model
+
+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: `^18.3.1 || ^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. |
+
+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, with no consumer install scripts or private research.
+
+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. |
+
+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).
+
+Interactive modules retain emitted client directives. Server-importable pure helpers do not mean interactive hooks run as Server Components. Keep handlers/state/providers in client boundaries. The bootstrap string has no user interpolation; restrictive CSP requires nonce/hash authorization. A fixture does not certify every deployment/CSP composition.
+
+## 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.
+
+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.
+
+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.
+
+## Native semantics and known integration limits
+
+Preserve native input/select/details/dialog behavior where appropriate. Future replacements require a written rationale and equivalent labels/descriptions, submission/disabled omission, validation/reset timing, keyboard/focus, modal scroll locking and cleanup, with relevant component/browser checks.
+
+- TextField/TextArea/SelectField forward native refs; Button/IconButton do not on React 18. Ref/native-prop support varies; inspect declarations.
+- Checkbox owns its ID/ref; 0.2.1 preserves caller ARIA validity and composes external descriptions with its own description/error. Switch/Slider/RadioGroup lack caller-named form contracts; serialize state deliberately.
+- 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 have closed customization props. Do not invent root refs, slots or arbitrary attributes absent from declarations.
+- 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.
+
+## Change, deprecation and migration policy
+
+The public contract includes documented exports/paths, props/events, types, styles/imports/tokens, native/ref/state behavior, visual defaults, theme/storage ownership and support environments. Undocumented private DOM structure is not a customization API; existing global classes used by consumers nevertheless need deliberate migration.
+
+During 0.x, compatible fixes/docs use patch and compatible additions use minor. Incompatible API/type/CSS/token/visual/environment changes require a 0.x minor, explicit release notes and a tested migration. Do not hide narrower props, class/key renames or removals in a patch. Retain aliases/compatibility styles where feasible; document unavoidable changes before upgrade. Legacy status is not formal deprecation or permission to delete.
+
+Formal deprecation identifies replacement/affected versions, marks the API/docs where feasible, and supplies migration guidance; no silent patch removal. After 1.0, incompatible public contracts require a major, additions minor and compatible fixes patch. No fixed support-window or response SLA is promised by this single-maintainer project.
+
+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.

package/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing to Contour UI
+
+Contour is a styled React library. The catalogue is a separate application at [contour.abuzr.in](https://contour.abuzr.in/). Domain workflows and product scenes belong in applications; reusable controls, semantic tokens and shared browser lifecycles belong here.
+
+Start with an issue describing the user task, current behavior and a small reproduction. For a new component, describe its stable props, native semantics, keyboard behavior, failure/empty states and why existing exports cannot compose the result. Do not include secrets or private application data. Report security concerns through [SECURITY.md](SECURITY.md).
+
+Use Node 22.12+ or 24+, then `npm ci --ignore-scripts`. Install Chromium once with `npx playwright install chromium`. Run `npm run validate` for types, lint, build, component and browser regressions, and archive checks. Run `npm run test:compat` for packed React 18/19 consumers and source declarations; run `npm run test:next` for the pinned App Router fixture. Compatibility installs need network access. The core fixture must work without Three.js or Lenis. Optional entries have separate consumers.
+
+Keep strict types and validate untrusted data before use. Components own presentation and nearby state; hooks own subscriptions and browser lifecycles; helpers own pure calculations. Use native controls, linked labels/errors, visible focus and explicit button types. Respect reduced motion. Release every listener, timer, observer and GPU resource on unmount and partial initialization failure. Use `onDispose` immediately for resources allocated in a custom stage setup.
+
+For a fix, add a regression that fails for the previous behavior. Use component tests for interaction contracts and real browsers for native dialogs, event timing, layout and GPU integration. Check narrow layouts, long content and both themes. Do not replace browser evidence with jsdom when a browser owns the behavior. Avoid duplicate tests that only restate implementation.
+
+Update the README and Unreleased changelog when public behavior changes. Keep documented APIs consistent with the archive. New APIs need a migration/usage example. Generic CSS class names and the legacy `aa-theme` storage key are existing compatibility constraints; do not rename them silently.
+
+A pull request should name the concrete behavior change, why it helps, which checks passed and any remaining limitation. Review public exports, packed files and dependency changes. No publish, deploy or merge is implied by opening a pull request. Consumers adopt an exact published release with a lockfile update; local source edits do not update them.
+
+Public API changes must follow [the compatibility policy](CONTRACTS.md#change-deprecation-and-migration-policy) and update [the maturity register](PUBLIC-API.md). Preserve native semantics and optional entry isolation; an experimental or legacy label does not authorize an undocumented removal.

package/NEXTJS.md

@@ -0,0 +1,51 @@
+# Next.js App Router integration
+
+This guide describes **Contour 0.2.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:
+
+```tsx
+import "@abuzareal/contour-ui/styles.css";
+import "@abuzareal/contour-ui/fonts-latin.css"; // Optional; use your own fonts if preferred.
+import { themeBootstrapScript } from "@abuzareal/contour-ui/theme-bootstrap";
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeBootstrapScript }} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+The narrowly scoped hydration suppression handles the root theme attribute changed before hydration; do not use it to hide arbitrary mismatch errors. A restrictive CSP requires a nonce or hash for the bootstrap script. `reset.css` is optional and global; decide whether your host reset already supplies equivalent defaults, visible focus and a `[hidden]` rule.
+
+A client component owns event handlers, state and providers:
+
+```tsx
+"use client";
+import { useState } from "react";
+import { TextField, Button } from "@abuzareal/contour-ui";
+
+export default function SearchForm() {
+  const [query, setQuery] = useState("");
+  return (
+    <form>
+      <TextField
+        label="Search"
+        name="query"
+        value={query}
+        onChange={(event) => setQuery(event.target.value)}
+      />
+      <Button type="submit">Search</Button>
+    </form>
+  );
+}
+```
+
+Provide real submission behavior in the application. Toast consumers need ToastProvider; dialogs need application-owned open/onClose. Keep function props inside client boundaries. A server component can pass serializable props to a package client component or import pure `safeHref`; a client directive does not remove normal server prerendering.
+
+Run `npm run test:next` to rebuild and consume the candidate archive. The fixture checks server imports/prerendering, hydration, CSS/fonts, refs, native resets, dialog dismissal/focus, toast, tabs, theme persistence and client navigation without Three.js/Lenis installed. Run `CONTOUR_NEXT_OPTIONAL=1 node scripts/test-next.mjs` for the separate lazy `/three` route; ordinary consumers still require neither optional peer. Compatibility evidence applies to the fixture's exact pair and local runtime, not deployment.

package/PUBLIC-API.md

@@ -0,0 +1,231 @@
+# Public API and maturity register
+
+Contract version: **0.2.1**, reviewed 12 October 2026. Export names, prop types and stylesheet APIs are unchanged from 0.2.0; Checkbox ARIA and clipboard lifecycle behavior receive compatible fixes. This register inventories the public entry declarations and actual JavaScript module exports; a catalogue specimen is not automatically a package export. Source links target the matching release tag. The catalogue URLs are discovery links, not immutable versioned documentation; its displayed example version may differ.
+
+Maintainer: [@abuzareal](https://github.com/abuzareal). Every row has the same named owner; there is no implied support team or response-time guarantee. See [architecture, scope and compatibility](CONTRACTS.md), [contributing](CONTRIBUTING.md) and [private security reporting](SECURITY.md).
+
+## Status definitions
+
+- **Stable (0.x):** the current documented contract is supported and changes require release notes and validation. This is not a 1.0 compatibility promise, full documentation coverage or proof of every state/browser.
+- **Experimental:** supported only within the stated limits; interaction/scene APIs may change in an explicitly documented 0.x minor release. Existing users still receive migration instructions.
+- **Legacy:** retained for existing editorial/personal-site integrations. It is not removed or formally deprecated by this register. Prefer application-owned identity/layout in new products.
+- Types inherit their defining module's status. Type-only exports cannot be imported as runtime values. New 1.0 promotions require complete docs, relevant behavior/integration evidence and outside-use feedback.
+
+## Validation evidence key
+
+**D**: emitted `.d.ts` contract and TypeScript checks. **C**: core import and packed consumers, with selected component regressions. **N**: separate packed optional-peer/declaration/build fixtures. **P**: package/bootstrap and exact pinned Next fixture. **G**: selected graphics lifecycle/paused-resize browser checks. The source fixtures are [public API](https://github.com/abuzareal/contour-ui/blob/v0.2.1/tests/public-api.test.mjs), [component behavior](https://github.com/abuzareal/contour-ui/blob/v0.2.1/tests/components.test.mjs), [native dialog](https://github.com/abuzareal/contour-ui/blob/v0.2.1/tests/dialog.browser.mjs), [graphics lifecycle](https://github.com/abuzareal/contour-ui/blob/v0.2.1/tests/stage.browser.mjs), [React matrix](https://github.com/abuzareal/contour-ui/blob/v0.2.1/scripts/test-compat.mjs) and [Next](https://github.com/abuzareal/contour-ui/blob/v0.2.1/scripts/test-next.mjs).
+
+These identify reproducible checks, not claims that every row has a dedicated behavioral test. In particular, declaration compilation is not runtime validation, passing Chromium/axe is not manual screen-reader verification, and no blanket WCAG or framework certification is claimed. Release gates must run against the candidate archive before publication.
+
+## Core: @abuzareal/contour-ui
+
+72 runtime exports; 60 type-only exports.
+
+### Runtime exports
+
+| Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| [`Alert`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Alert.tsx#L37) | @abuzareal | stable (0.x) | Inline feedback or banner | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Avatar`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Avatar.tsx#L19) | @abuzareal | stable (0.x) | Image or initials identity | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Badge`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Badge.tsx#L16) | @abuzareal | stable (0.x) | Short status label | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`BrandMark`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/BrandMark.tsx#L12) | @abuzareal | legacy | Fixed inherited AA mark | Fixed inherited personal mark; supported for existing consumers, not a general logo system. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Breadcrumbs`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Breadcrumbs.tsx#L9) | @abuzareal | stable (0.x) | Page hierarchy navigation | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Button`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Button.tsx#L19) | @abuzareal | stable (0.x) | Native action button | No forwarded DOM ref on React 18; native attributes otherwise supported. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Card`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Card.tsx#L16) | @abuzareal | stable (0.x) | Content and footer container | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Checkbox`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Checkbox.tsx#L18) | @abuzareal | stable (0.x) | Native checkbox with label/error | Internal ref/generated ID; no caller ID/ref contract; 0.2.1 preserves external ARIA and composes description/error. | [Reference](https://contour.abuzr.in/docs/components/checkbox) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`CountUp`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/CountUp.tsx#L18) | @abuzareal | stable (0.x) | Animated numeric display | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DataTable`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DataTable.tsx#L24) | @abuzareal | stable (0.x) | Scalar rows with local sorting | String/number row values and local sort only; no remote sort, selection, loading controller or virtualization. | [Reference](https://contour.abuzr.in/docs#data-table) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DepthButton`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DepthButton.tsx#L8) | @abuzareal | stable (0.x) | Native action with CSS depth | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Dialog`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Dialog.tsx#L19) | @abuzareal | stable (0.x) | Native modal or edge drawer | Closed props; no native ref/root/part or initial-focus customization; app owns open/onClose. | [Reference](https://contour.abuzr.in/docs/components/dialog) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Disclosure`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Disclosure.tsx#L14) | @abuzareal | stable (0.x) | Native details/summary disclosure | Native details; defaultOpen only, no controlled open/onOpenChange; className is required. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Divider`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Divider.tsx#L6) | @abuzareal | stable (0.x) | Content separation | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DropdownMenu`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DropdownMenu.tsx#L30) | @abuzareal | experimental | Action menu with keyboard selection | Local absolute panel; no portal/collision/submenu API; shares nested-dismissal limitation. | [Reference](https://contour.abuzr.in/docs/components/dropdown-menu) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`EmptyState`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/EmptyState.tsx#L11) | @abuzareal | stable (0.x) | Empty-result content and action | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ExternalLink`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ExternalLink.tsx#L10) | @abuzareal | stable (0.x) | Styled native external anchor | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Field`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Field.tsx#L19) | @abuzareal | stable (0.x) | Label, hint and error frame | Caller wires the child ID/describedby; wrapper does not wire arbitrary children automatically. | [Reference](https://contour.abuzr.in/docs#field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`FlipCard`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/FlipCard.tsx#L19) | @abuzareal | stable (0.x) | Button-controlled two-face card | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`IconButton`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/IconButton.tsx#L14) | @abuzareal | stable (0.x) | Native button with required accessible label | No forwarded DOM ref on React 18; caller supplies meaningful label. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Kbd`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Kbd.tsx#L4) | @abuzareal | stable (0.x) | Keyboard shortcut label | Displays a shortcut, does not register one. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Magnetic`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Magnetic.tsx#L13) | @abuzareal | stable (0.x) | Pointer-dependent decorative movement | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Marquee`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Marquee.tsx#L12) | @abuzareal | stable (0.x) | Repeated moving content strip | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Pagination`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Pagination.tsx#L25) | @abuzareal | stable (0.x) | Page-selection controls | Positive integer pages and in-range one-based page; application owns URL/fetch/slicing. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Popover`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Popover.tsx#L20) | @abuzareal | experimental | Nonmodal panel with owned trigger | Local absolute panel; no portal/collision/custom-trigger/initial-focus API; nested Escape closes multiple layers. | [Reference](https://contour.abuzr.in/docs#floating) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ProgressBar`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ProgressBar.tsx#L12) | @abuzareal | stable (0.x) | Determinate or indeterminate progress | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs/components/progress-bar) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`RadioGroup`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RadioGroup.tsx#L21) | @abuzareal | stable (0.x) | Native radio choices | Uses generated name; no caller field-name/form/ref contract; submit application state for stable keys. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Reveal`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Reveal.tsx#L13) | @abuzareal | stable (0.x) | Visibility-triggered content reveal | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`RevealHeading`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RevealHeading.tsx#L15) | @abuzareal | legacy | Editorial heading-line composition | Editorial h2 composition; application must preserve heading order. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ScrollProgress`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ScrollProgress.tsx#L6) | @abuzareal | stable (0.x) | Document scroll readout | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SectionLabel`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SectionLabel.tsx#L11) | @abuzareal | legacy | Editorial section metadata | Depends on Section editorial metadata/aside contract; not a general label primitive. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SegmentedControl`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SegmentedControl.tsx#L14) | @abuzareal | stable (0.x) | Controlled single-choice buttons | No native named field or disabled-option API; application owns value and submission. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SelectField`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SelectField.tsx#L17) | @abuzareal | stable (0.x) | Labelled native select | Native forwarded select ref; native choices, not searchable Combobox. | [Reference](https://contour.abuzr.in/docs/components/select-field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Skeleton`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Skeleton.tsx#L11) | @abuzareal | stable (0.x) | Loading placeholder | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Slider`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Slider.tsx#L18) | @abuzareal | stable (0.x) | Controlled native range input | No name/form/ref contract; submit application state; keep numeric values within meaningful bounds. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`GitHubIcon`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SocialIcons.tsx#L5) | @abuzareal | stable (0.x) | GitHub SVG mark | SVG only; caller owns link destination and accessible name. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`LinkedInIcon`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SocialIcons.tsx#L16) | @abuzareal | stable (0.x) | LinkedIn SVG mark | SVG only; caller owns link destination and accessible name. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Spinner`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Spinner.tsx#L13) | @abuzareal | stable (0.x) | Loading status indicator | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Stat`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Stat.tsx#L10) | @abuzareal | stable (0.x) | Supplied value and label display | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Stepper`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Stepper.tsx#L13) | @abuzareal | stable (0.x) | Step-progress display | Progress display, not a navigable wizard; application owns state and validation. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Switch`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Switch.tsx#L14) | @abuzareal | stable (0.x) | Controlled on/off button | State callback only; no name/form/ref/uncontrolled reset contract; submit application state. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Tabs`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tabs.tsx#L29) | @abuzareal | stable (0.x) | Controlled or default tab selection | Closed props; selected ID controlled or default; no general slot/disabled-tab/orientation API. | [Reference](https://contour.abuzr.in/docs/components/tabs) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Tag`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tag.tsx#L11) | @abuzareal | stable (0.x) | Short label with optional removal | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TextArea`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TextArea.tsx#L24) | @abuzareal | stable (0.x) | Native textarea, counter and resize | Native forwarded textarea ref; parent owns controlled reset; sizing is browser dependent. | [Reference](https://contour.abuzr.in/docs/components/text-area) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TextField`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TextField.tsx#L26) | @abuzareal | stable (0.x) | Native input with label/counter | Native forwarded input ref; parent owns controlled values/reset; do not switch state ownership. | [Reference](https://contour.abuzr.in/docs/components/text-field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ThemeToggle`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ThemeToggle.tsx#L12) | @abuzareal | stable (0.x) | Document-theme control | Root data-theme and aa-theme origin storage; no independently scoped theme provider. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TiltCard`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TiltCard.tsx#L13) | @abuzareal | stable (0.x) | Pointer-dependent CSS depth | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Timeline`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Timeline.tsx#L8) | @abuzareal | stable (0.x) | Ordered entries supplied by caller | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ToastProvider`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ToastProvider.tsx#L67) | @abuzareal | stable (0.x) | Toast context, queue and announcements | No application persistence; important failures need a durable visible record as well. | [Reference](https://contour.abuzr.in/docs/components/toast-provider) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Tooltip`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tooltip.tsx#L14) | @abuzareal | experimental | Supplemental text hint | Pointer leave closes it and CSS prevents content hover; supplemental noninteractive text only; no collision engine. | [Reference](https://contour.abuzr.in/docs#floating) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useClipboardCopy`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useClipboardCopy.ts#L10) | @abuzareal | stable (0.x) | Clipboard operation and feedback state | Clipboard access can fail; obsolete text/request/unmount completions are discarded in 0.2.1; app presents truthful feedback. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useDismiss`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useDismiss.ts#L6) | @abuzareal | experimental | Document Escape/outside-press subscription | Independent global document listeners; no layer stack/portal/owner-document model; caller manages focus. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useHeaderScroll`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useHeaderScroll.ts#L9) | @abuzareal | legacy | Editorial header/section state | Assumes main section[id] and header-theme regions; application owns page structure. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useIdleTrigger`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useIdleTrigger.ts#L9) | @abuzareal | stable (0.x) | Idle-time activation | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useInitialHashScroll`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useInitialHashScroll.ts#L8) | @abuzareal | legacy | Initial document-hash scrolling | Initial hash only; application owns routing and unknown targets. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useMobileMenu`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useMobileMenu.ts#L8) | @abuzareal | experimental | Menu open/close and resize state | Caller provides semantics/focus; closes on Escape/outside press and desktop resize. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useMotionPreference`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useMotionPreference.ts#L8) | @abuzareal | stable (0.x) | System reduced-motion subscription | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`usePrintPreparation`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/usePrintPreparation.ts#L6) | @abuzareal | legacy | Temporary print theme/disclosure changes | Mutates root theme/details during printing; application must verify print layout. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useScrollSpy`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useScrollSpy.ts#L9) | @abuzareal | stable (0.x) | Active section observation | Stable section IDs and existing DOM anchors required; does not provide routing. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useTheme`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useTheme.ts#L84) | @abuzareal | stable (0.x) | Shared document-theme preference | Root data-theme and aa-theme origin storage; client lifecycle; embedding needs one theme owner. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`useToast`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useToast.ts#L19) | @abuzareal | stable (0.x) | Toast commands from provider | Must be called under ToastProvider; ephemeral feedback is not an operation result. | [Reference](https://contour.abuzr.in/docs#toasts) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SceneBoundary`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/hero/SceneBoundary.tsx#L9) | @abuzareal | experimental | Hide failed scene subtree | Renders null after failure; no fallback prop/reset API; keep usable static content outside it. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`safeHref`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/safeHref.ts#L2) | @abuzareal | stable (0.x) | Reject executable URL schemes | Scheme validation only, not URL trust/authorization validation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`cx`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/classNames.ts#L2) | @abuzareal | stable (0.x) | Join optional CSS class names | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`buttonClassName`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/classNames.ts#L10) | @abuzareal | stable (0.x) | Shared button-class recipe for buttons/anchors | Returns existing global classes; styled anchor retains native link responsibilities. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`formatIndex`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/format.ts#L4) | @abuzareal | stable (0.x) | Two-digit index formatting | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`readStorage`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/storage.ts#L14) | @abuzareal | legacy | Read local/session string safely | Returns raw string/null; caller parses and validates; no persistence guarantee. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`writeStorage`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/storage.ts#L23) | @abuzareal | legacy | Attempt local/session string persistence | Returns success boolean; browser policy can block persistence. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`storageKeys`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/storage.ts#L3) | @abuzareal | legacy | Inherited shared storage key names | Legacy aa-* keys are public compatibility constraints; no silent rename. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`nextIndexForKey`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/keyboard.ts#L14) | @abuzareal | stable (0.x) | Keyboard navigation index calculation | Calculates index, does not move focus or perform selection. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`fieldDescribedBy`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/a11y.ts#L4) | @abuzareal | stable (0.x) | Field hint/error ID calculation | Error description takes precedence over hint; caller connects the target input. | [Reference](https://contour.abuzr.in/docs#field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`motionDisabledFor`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/motion.ts#L4) | @abuzareal | stable (0.x) | System and ancestor motion check | Browser/ancestor check; app still owns animation cancellation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+
+### Type-only exports
+
+| Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| [`Section`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/types.ts#L1) | @abuzareal | stable (0.x) | Type contract for Section | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`AlertTone`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Alert.tsx#L15) | @abuzareal | stable (0.x) | Type contract for Alert | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`AlertProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Alert.tsx#L27) | @abuzareal | stable (0.x) | Type contract for Alert | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`AvatarProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Avatar.tsx#L4) | @abuzareal | stable (0.x) | Type contract for Avatar | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`BadgeTone`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Badge.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Badge | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`BadgeProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Badge.tsx#L8) | @abuzareal | stable (0.x) | Type contract for Badge | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`BrandMarkProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/BrandMark.tsx#L6) | @abuzareal | legacy | Type contract for BrandMark | Type-only; no runtime value. Fixed inherited personal mark; supported for existing consumers, not a general logo system. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`BreadcrumbsProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Breadcrumbs.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Breadcrumbs | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ButtonProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Button.tsx#L10) | @abuzareal | stable (0.x) | Type contract for Button | Type-only; no runtime value. No forwarded DOM ref on React 18; native attributes otherwise supported. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`CardProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Card.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Card | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`CheckboxProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Checkbox.tsx#L8) | @abuzareal | stable (0.x) | Type contract for Checkbox | Type-only; no runtime value. Internal ref/generated ID; no caller ID/ref contract; 0.2.1 preserves external ARIA and composes description/error. | [Reference](https://contour.abuzr.in/docs/components/checkbox) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`CountUpProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/CountUp.tsx#L7) | @abuzareal | stable (0.x) | Type contract for CountUp | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TableColumn`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DataTable.tsx#L7) | @abuzareal | stable (0.x) | Type contract for DataTable | Type-only; no runtime value. String/number row values and local sort only; no remote sort, selection, loading controller or virtualization. | [Reference](https://contour.abuzr.in/docs#data-table) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DataTableProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DataTable.tsx#L15) | @abuzareal | stable (0.x) | Type contract for DataTable | Type-only; no runtime value. String/number row values and local sort only; no remote sort, selection, loading controller or virtualization. | [Reference](https://contour.abuzr.in/docs#data-table) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DepthButtonProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DepthButton.tsx#L4) | @abuzareal | stable (0.x) | Type contract for DepthButton | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DialogProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Dialog.tsx#L9) | @abuzareal | stable (0.x) | Type contract for Dialog | Type-only; no runtime value. Closed props; no native ref/root/part or initial-focus customization; app owns open/onClose. | [Reference](https://contour.abuzr.in/docs/components/dialog) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DisclosureProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Disclosure.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Disclosure | Type-only; no runtime value. Native details; defaultOpen only, no controlled open/onOpenChange; className is required. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DividerProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Divider.tsx#L2) | @abuzareal | stable (0.x) | Type contract for Divider | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`MenuItem`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DropdownMenu.tsx#L11) | @abuzareal | experimental | Type contract for DropdownMenu | Type-only; no runtime value. Local absolute panel; no portal/collision/submenu API; shares nested-dismissal limitation. | [Reference](https://contour.abuzr.in/docs/components/dropdown-menu) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`DropdownMenuProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DropdownMenu.tsx#L21) | @abuzareal | experimental | Type contract for DropdownMenu | Type-only; no runtime value. Local absolute panel; no portal/collision/submenu API; shares nested-dismissal limitation. | [Reference](https://contour.abuzr.in/docs/components/dropdown-menu) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`EmptyStateProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/EmptyState.tsx#L4) | @abuzareal | stable (0.x) | Type contract for EmptyState | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ExternalLinkProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ExternalLink.tsx#L5) | @abuzareal | stable (0.x) | Type contract for ExternalLink | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`FieldProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Field.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Field | Type-only; no runtime value. Caller wires the child ID/describedby; wrapper does not wire arbitrary children automatically. | [Reference](https://contour.abuzr.in/docs#field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`FlipCardProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/FlipCard.tsx#L8) | @abuzareal | stable (0.x) | Type contract for FlipCard | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`IconButtonProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/IconButton.tsx#L5) | @abuzareal | stable (0.x) | Type contract for IconButton | Type-only; no runtime value. No forwarded DOM ref on React 18; caller supplies meaningful label. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`MagneticProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Magnetic.tsx#L7) | @abuzareal | stable (0.x) | Type contract for Magnetic | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`MarqueeProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Marquee.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Marquee | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`PaginationProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Pagination.tsx#L7) | @abuzareal | stable (0.x) | Type contract for Pagination | Type-only; no runtime value. Positive integer pages and in-range one-based page; application owns URL/fetch/slicing. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`PopoverProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Popover.tsx#L9) | @abuzareal | experimental | Type contract for Popover | Type-only; no runtime value. Local absolute panel; no portal/collision/custom-trigger/initial-focus API; nested Escape closes multiple layers. | [Reference](https://contour.abuzr.in/docs#floating) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ProgressBarProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ProgressBar.tsx#L5) | @abuzareal | stable (0.x) | Type contract for ProgressBar | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs/components/progress-bar) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`RadioGroupProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RadioGroup.tsx#L7) | @abuzareal | stable (0.x) | Type contract for RadioGroup | Type-only; no runtime value. Uses generated name; no caller field-name/form/ref contract; submit application state for stable keys. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`RevealProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Reveal.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Reveal | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`HeadingLine`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RevealHeading.tsx#L4) | @abuzareal | legacy | Type contract for RevealHeading | Type-only; no runtime value. Editorial h2 composition; application must preserve heading order. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`RevealHeadingProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RevealHeading.tsx#L10) | @abuzareal | legacy | Type contract for RevealHeading | Type-only; no runtime value. Editorial h2 composition; application must preserve heading order. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SectionLabelProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SectionLabel.tsx#L5) | @abuzareal | legacy | Type contract for SectionLabel | Type-only; no runtime value. Depends on Section editorial metadata/aside contract; not a general label primitive. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SegmentedControlProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SegmentedControl.tsx#L7) | @abuzareal | stable (0.x) | Type contract for SegmentedControl | Type-only; no runtime value. No native named field or disabled-option API; application owns value and submission. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SelectFieldProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SelectField.tsx#L9) | @abuzareal | stable (0.x) | Type contract for SelectField | Type-only; no runtime value. Native forwarded select ref; native choices, not searchable Combobox. | [Reference](https://contour.abuzr.in/docs/components/select-field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SkeletonProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Skeleton.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Skeleton | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SliderProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Slider.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Slider | Type-only; no runtime value. No name/form/ref contract; submit application state; keep numeric values within meaningful bounds. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SocialIconProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SocialIcons.tsx#L3) | @abuzareal | stable (0.x) | Type contract for LinkedInIcon | Type-only; no runtime value. SVG only; caller owns link destination and accessible name. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SpinnerProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Spinner.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Spinner | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`StatProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Stat.tsx#L4) | @abuzareal | stable (0.x) | Type contract for Stat | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`StepperProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Stepper.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Stepper | Type-only; no runtime value. Progress display, not a navigable wizard; application owns state and validation. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`SwitchProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Switch.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Switch | Type-only; no runtime value. State callback only; no name/form/ref/uncontrolled reset contract; submit application state. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TabItem`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tabs.tsx#L14) | @abuzareal | stable (0.x) | Type contract for Tabs | Type-only; no runtime value. Closed props; selected ID controlled or default; no general slot/disabled-tab/orientation API. | [Reference](https://contour.abuzr.in/docs/components/tabs) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TabsProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tabs.tsx#L20) | @abuzareal | stable (0.x) | Type contract for Tabs | Type-only; no runtime value. Closed props; selected ID controlled or default; no general slot/disabled-tab/orientation API. | [Reference](https://contour.abuzr.in/docs/components/tabs) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TagProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tag.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Tag | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TextAreaProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TextArea.tsx#L16) | @abuzareal | stable (0.x) | Type contract for TextArea | Type-only; no runtime value. Native forwarded textarea ref; parent owns controlled reset; sizing is browser dependent. | [Reference](https://contour.abuzr.in/docs/components/text-area) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TextFieldProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TextField.tsx#L16) | @abuzareal | stable (0.x) | Type contract for TextField | Type-only; no runtime value. Native forwarded input ref; parent owns controlled values/reset; do not switch state ownership. | [Reference](https://contour.abuzr.in/docs/components/text-field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ThemeToggleProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ThemeToggle.tsx#L7) | @abuzareal | stable (0.x) | Type contract for ThemeToggle | Type-only; no runtime value. Root data-theme and aa-theme origin storage; no independently scoped theme provider. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TiltCardProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TiltCard.tsx#L7) | @abuzareal | stable (0.x) | Type contract for TiltCard | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TimelineProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Timeline.tsx#L4) | @abuzareal | stable (0.x) | Type contract for Timeline | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`TooltipProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tooltip.tsx#L7) | @abuzareal | experimental | Type contract for Tooltip | Type-only; no runtime value. Pointer leave closes it and CSS prevents content hover; supplemental noninteractive text only; no collision engine. | [Reference](https://contour.abuzr.in/docs#floating) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`CopyStatus`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useClipboardCopy.ts#L6) | @abuzareal | stable (0.x) | Type contract for useClipboardCopy | Type-only; no runtime value. Clipboard access can fail; obsolete text/request/unmount completions are discarded in 0.2.1; app presents truthful feedback. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`Theme`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useTheme.ts#L9) | @abuzareal | stable (0.x) | Type contract for useTheme | Type-only; no runtime value. Root data-theme and aa-theme origin storage; client lifecycle; embedding needs one theme owner. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ToastInput`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useToast.ts#L7) | @abuzareal | stable (0.x) | Type contract for useToast | Type-only; no runtime value. Must be called under ToastProvider; ephemeral feedback is not an operation result. | [Reference](https://contour.abuzr.in/docs#toasts) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ToastContextValue`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useToast.ts#L13) | @abuzareal | stable (0.x) | Type contract for useToast | Type-only; no runtime value. Must be called under ToastProvider; ephemeral feedback is not an operation result. | [Reference](https://contour.abuzr.in/docs#toasts) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ToastContext`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useToast.ts#L17) | @abuzareal | stable (0.x) | Type contract for useToast | Type-only; no runtime value. Must be called under ToastProvider; ephemeral feedback is not an operation result. | [Reference](https://contour.abuzr.in/docs#toasts) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ButtonVariant`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/classNames.ts#L5) | @abuzareal | stable (0.x) | Type contract for buttonClassName | Type-only; no runtime value. Returns existing global classes; styled anchor retains native link responsibilities. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+| [`ButtonSize`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/classNames.ts#L7) | @abuzareal | stable (0.x) | Type contract for buttonClassName | Type-only; no runtime value. Returns existing global classes; styled anchor retains native link responsibilities. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
+
+## Optional: @abuzareal/contour-ui/three
+
+11 runtime exports; 7 type-only exports.
+
+### Runtime exports
+
+| Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| [`Sculpture`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/hero/Sculpture.tsx#L73) | @abuzareal | experimental | Experimental link sculpture scene | WebGL, sized container, lazy/static fallback and motionEnabled required; setup captured on mount. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`ObjectStudy`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/three/ObjectStudy.tsx#L34) | @abuzareal | experimental | Experimental material/geometry scene | WebGL, sized container, study/label/motionEnabled required; experimental scene contract. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`useThreeStage`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useThreeStage.ts#L41) | @abuzareal | experimental | Experimental renderer and scene lifecycle | Setup captured on mount; register owned cleanup immediately with onDispose; do not double-dispose. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`createLinkGeometry`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L58) | @abuzareal | experimental | Create owned link geometry | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`createChrome`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L4) | @abuzareal | experimental | Create owned chrome material | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`createLime`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L12) | @abuzareal | experimental | Create owned lime material | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`createInk`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L20) | @abuzareal | experimental | Create owned ink material | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`createGlass`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L29) | @abuzareal | experimental | Create owned glass material | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`createMaterialSet`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L18) | @abuzareal | experimental | Create owned material-study objects | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`createGeometrySet`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L31) | @abuzareal | experimental | Create owned geometry-study objects | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`objectStudies`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L52) | @abuzareal | experimental | Named scene factories | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+
+### Type-only exports
+
+| Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| [`StageFrame`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useThreeStage.ts#L8) | @abuzareal | experimental | Type contract for useThreeStage | Type-only; no runtime value. Setup captured on mount; register owned cleanup immediately with onDispose; do not double-dispose. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`StageScene`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useThreeStage.ts#L15) | @abuzareal | experimental | Type contract for useThreeStage | Type-only; no runtime value. Setup captured on mount; register owned cleanup immediately with onDispose; do not double-dispose. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`StageContext`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useThreeStage.ts#L24) | @abuzareal | experimental | Type contract for useThreeStage | Type-only; no runtime value. Setup captured on mount; register owned cleanup immediately with onDispose; do not double-dispose. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`SculptureProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/hero/Sculpture.tsx#L16) | @abuzareal | experimental | Type contract for Sculpture | Type-only; no runtime value. WebGL, sized container, lazy/static fallback and motionEnabled required; setup captured on mount. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`ObjectStudyProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/three/ObjectStudy.tsx#L12) | @abuzareal | experimental | Type contract for ObjectStudy | Type-only; no runtime value. WebGL, sized container, study/label/motionEnabled required; experimental scene contract. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`ObjectSet`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L12) | @abuzareal | experimental | Type contract for objectStudies | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+| [`ObjectStudyKind`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L57) | @abuzareal | experimental | Type contract for objectStudies | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
+
+## Optional: @abuzareal/contour-ui/scroll
+
+1 runtime exports; 0 type-only exports.
+
+### Runtime exports
+
+| Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| [`useSmoothScroll`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useSmoothScroll.ts#L7) | @abuzareal | experimental | Optional Lenis lifecycle | Install Lenis and its CSS explicitly; one owner; caller disables it for pause/reduced motion. | [Reference](https://contour.abuzr.in/docs#optional-scroll) | D: emitted declaration; N: optional declaration/build fixture |
+
+## Server-safe string/helpers: @abuzareal/contour-ui/theme-bootstrap
+
+2 runtime exports; 0 type-only exports.
+
+### Runtime exports
+
+| Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| [`themeColors`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/themeBootstrap.ts#L6) | @abuzareal | stable (0.x) | Theme-background constants | Fixed backgrounds must match token defaults; consumer themes may need own metadata. | [Reference](https://contour.abuzr.in/docs/getting-started#theme-motion) | D: emitted declaration; P: bootstrap package/Next fixture |
+| [`themeBootstrapScript`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/themeBootstrap.ts#L11) | @abuzareal | stable (0.x) | Pre-paint theme initialization string | Authorize inline script through CSP nonce/hash; no user interpolation; root preference only. | [Reference](https://contour.abuzr.in/docs/getting-started#theme-motion) | D: emitted declaration; P: bootstrap package/Next fixture |
+
+## Stylesheet exports
+
+| Import | Maintainer | Status | Purpose and limits | Documentation | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| `styles.css` | @abuzareal | stable (0.x) | Aggregate component CSS, tokens and utilities; global classes, not selective CSS tree shaking. | [Styles](README.md#styles-and-customization) | Package/export and consumer build checks |
+| `tokens.css` | @abuzareal | stable (0.x) | Root semantic tokens; includes inherited product values, no general scoped-theme contract. | [Theme contract](CONTRACTS.md#styles-theme-and-motion) | Package/export and source-token inspection |
+| `reset.css` | @abuzareal | legacy | Optional global element defaults plus inherited page-width/site-shell/section offsets; affects the host document. | [Reset scope](CONTRACTS.md#styles-theme-and-motion) | Package/export and consumer build checks |
+| `fonts.css` | @abuzareal | stable (0.x) | Optional Fontsource CSS; branded font dependencies still install; wider character coverage. | [Fonts](README.md#optional-latin-fonts) | Core packed consumer/CSS build checks |
+| `fonts-latin.css` | @abuzareal | stable (0.x) | Optional relative Latin WOFF2 files and notices; choose instead of fonts.css; narrower coverage. | [Fonts](README.md#optional-latin-fonts) | Optional consumer asset and Next webpack checks |
+
+The inventory has 86 runtime entries, 67 type-only entries and five stylesheet entries across public paths. Core includes 48 default UI components, two social icons, SceneBoundary, 11 hooks and ten helpers/constants. No `Drawer`, `Banner`, `Combobox`, `FocusBand` or `ProjectCard` runtime export is implied. Drawer is Dialog placement; banner is Alert layout; native Disclosure supplies disclosure behavior. Catalogue page/grid/spacing/resource-card and workflow specimens are application examples.
+
+`SceneBoundaryProps` is declared in its module but is not re-exported from the core entry. `ToastContext` is exposed only through a type-only star export; it is not a root runtime value. Use public paths and emitted declarations rather than deep imports into dist internals.