@abuzareal/contour-ui 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,10 +1,79 @@
 # Changelog
 
+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.
+
+## 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.
+
+### Added
+
+- `fonts-latin.css`: load Latin WOFF2 files for the three system typefaces. The existing `fonts.css` retains full character coverage.
+
+### Documentation
+
+- Clarify installation, CSS import order, public exports, optional dependencies, and upgrade guidance.
+- Pair live examples with their source code on the documentation site. Site navigation, theme transitions, responsive layouts, and the homepage specimen were refined; these site changes do not alter package component APIs.
+
+### Compatibility
+
+- React 18 and 19 remain supported. Three.js and Lenis remain optional. Packed optional-entry checks cover strict TypeScript declarations and production builds.
+
+### Upgrading from 0.1.1
+
+```sh
+npm install @abuzareal/contour-ui@0.1.2 --save-exact
+```
+
+No component changes are required. To use the smaller Latin font set, replace your `fonts.css` import with `@abuzareal/contour-ui/fonts-latin.css`. Keep the existing import for additional character coverage. Update your manifest and lockfile and check your application's rendered text.
+
+## 0.1.1
+
+A compatibility and interaction update for apps using React 18.3.1 or React 19.
+
+### Compatibility
+
+- Extend the React and React DOM peer ranges to React 19. The compatibility script checks packed consumers on 18.3.1, 19.0.0, and 19.3.0 and compiles library source against React 19 types.
+- Preserve inert flip-card faces in both React majors, accept nullable refs in public hooks, and initialize the clipboard timer ref for React 19 types.
+
+### Fixes
+
+- **Dialog and drawers:** lock background scrolling while open. Nested dialogs retain the lock until the last closes; closing or unmounting restores the document's previous styles and scrollbar space. Dialog content remains scrollable on short screens.
+- **TextField, TextArea, SelectField:** accept caller IDs and retain caller `aria-describedby` references alongside field hints and errors.
+- **Text counters:** reflect programmatic changes to controlled values.
+- **ThemeToggle:** use a button type that doesn't submit an enclosing form.
+- **CountUp:** show the final value when IntersectionObserver is unavailable.
+
+### Upgrading from 0.1.0
+
+```sh
+npm install @abuzareal/contour-ui@0.1.1 --save-exact
+```
+
+Commit `package.json` and `package-lock.json`, then run your app's checks. Review dialogs and drawers on short screens and with nested overlays. If your app has its own background-scroll workaround, test its interaction with the library lock before removing it. Check caller-supplied field IDs/descriptions and controlled counter updates.
+
+React 18.3.1 remains supported; adopting React 19 isn't required. Three.js and Lenis remain optional peers behind `/three` and `/scroll`. The 3D API remains experimental. The compatibility matrix doesn't establish React Server Component support or universal framework compatibility.
+
+### Developer tooling
+
+- Document direct package imports and add a repeatable packed-consumer compatibility check before publication.
+
 ## 0.1.0
 
-- Extract reusable React components, theme tokens, styling, and optional 3D/scroll entries from the standalone design-system app.
-- Synchronize theme controls, tolerate blocked preference storage, and honor system reduced motion for theme changes.
-- Reject executable link schemes, preserve tooltip descriptions, make hidden flip-card faces inert, and handle empty tabs and zero-range sliders.
-- Ship typed ESM exports, optional font/reset styles, regression tests, and archive-content validation.
+The first package release, extracted from the portfolio and standalone catalogue.
+
+### Added
+
+- Reusable React components, theme tokens, CSS, and separate optional 3D and smooth-scroll entries.
+- Typed ESM exports with font and reset styles available as opt-in imports.
+- Regression tests, archive-content checks, and consumer build validation.
+
+### Interaction behavior
+
+- Synchronize theme controls, tolerate blocked preference storage, and respect system reduced motion for theme changes.
+- Reject executable link schemes, preserve tooltip descriptions, and make hidden flip-card faces inert.
+- Handle empty tab lists and zero-range sliders.
+
+### Compatibility at release
 
-This is the first release. The 3D interface is experimental; React 19 compatibility has not been verified.
+React 18.3.1 was the verified baseline for 0.1.0; React 19 compatibility was added in 0.1.1. The 3D API was introduced as experimental.

package/README.md

@@ -1,111 +1,187 @@
 # Contour UI
 
-An independent React component library for editorial interfaces: paper and ink surfaces, an acid accent, readable typography, restrained motion, and optional Three.js objects.
+React components and CSS tokens for interfaces with paper and ink surfaces, a lime accent, and light and dark themes. Contour started as the shared UI in a personal portfolio; it now supplies components to the portfolio, its catalogue, Atmos, and Orbit.
 
-The npm package is public under MIT; the development repository is private. Public consumers can inspect the distributed JavaScript, declarations, and CSS, but the repository and its issue tracker are accessible only to invited collaborators.
+Use it when you want this visual style with typed controls, feedback, navigation, and motion. Applications own their layouts, data, validation, and workflows. Three.js scenes and smooth scrolling are separate, optional entries.
 
-**Status:** initial `0.1.0` release. React 18.3 is supported; React 19 and React Server Component execution are not advertised as tested. Interactive components belong in a client boundary in frameworks such as Next.js. The root module can be imported on the server, and basic components can render there.
+[Live catalogue](https://contour.abuzr.in/) · [npm package](https://www.npmjs.com/package/@abuzareal/contour-ui) · [Maintainer](https://github.com/abuzareal)
+
+The catalogue currently uses **0.1.1**; this release is **0.1.2**. Catalogue examples include application patterns as well as package components. Check the exports below before treating an example as an importable component.
 
 ## Install
 
+Use an existing React application with a bundler that resolves package CSS imports. Contour ships ESM and TypeScript declarations. The package declares Node.js 22 or newer; repository tooling uses Vite 8, which needs Node.js 22.12+ or 24+.
+
 ```sh
-npm install @abuzareal/contour-ui react@18 react-dom@18
+npm install @abuzareal/contour-ui@0.1.2 --save-exact
 ```
 
+Your app must provide matching `react` and `react-dom` versions: **18.3.1 or React 19**. The compatibility script covers 18.3.1, 19.0.0, and 19.3.0; it doesn't establish support for every framework or React Server Component setup. Put interactive components inside a client boundary when your framework requires one.
+
+## First component
+
+Import the styles once in your application entry. Import components directly from the package; no generated files or local re-exports are needed.
+
 ```tsx
-import "@abuzareal/contour-ui/reset.css"; // optional, global reset; omit with an existing reset
-import "@abuzareal/contour-ui/fonts.css"; // optional, self-hosted font assets bundled by your app
+import { useState } from "react";
+import "@abuzareal/contour-ui/reset.css";
+import "@abuzareal/contour-ui/fonts.css";
 import "@abuzareal/contour-ui/styles.css";
-import {
-  Button,
-  TextField,
-  ToastProvider,
-  ThemeToggle,
-} from "@abuzareal/contour-ui";
-
-export function App() {
+import { Button, TextField, ThemeToggle } from "@abuzareal/contour-ui";
+
+export default function App() {
+  const [name, setName] = useState("");
+  const [savedName, setSavedName] = useState("");
+
   return (
-    <ToastProvider>
-      <main data-motion="off">
-        <ThemeToggle animate={false} />
-        <TextField label="City" placeholder="Pune" />
-        <Button variant="accent">Show forecast</Button>
-      </main>
-    </ToastProvider>
+    <main data-motion="off">
+      <ThemeToggle animate={false} />
+      <TextField
+        label="Name"
+        value={name}
+        onChange={(event) => setName(event.target.value)}
+      />
+      <Button variant="accent" onClick={() => setSavedName(name)}>
+        Save locally
+      </Button>
+      <p role="status">{savedName && `Saved for this session: ${savedName}`}</p>
+    </main>
   );
 }
 ```
 
-For an app with its own reset, include equivalent native button/input defaults, border-box sizing, focus outlines, and the `[hidden]` rule. Styles use globally named component classes and `:root` theme tokens; they are not Shadow DOM isolated. Avoid redefining generic classes such as `.card` or `.button` elsewhere.
+This example keeps the value in React state until the component unmounts. To persist it or send it to a server, add that behavior in your app.
+
+`Button` and ordinary controls need no provider. Toasts require `ToastProvider` around components that call `useToast()`.
+
+### Optional Latin fonts
+
+`fonts-latin.css`, added in 0.1.2, keeps DM Sans, Space Grotesk, and DM Mono while loading only Latin WOFF2 files. Use it instead of `fonts.css` for Latin text; keep `fonts.css` when the additional character sets are needed. Existing font imports continue to work.
+
+```tsx
+import "@abuzareal/contour-ui/fonts-latin.css";
+```
+
+## Styles and customization
+
+| Import            | Purpose                                                                                                                                            |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `styles.css`      | Required for the supplied appearance: tokens, component styles, and utilities.                                                                     |
+| `reset.css`       | Optional global reset. Omit it if your app already has equivalent native-control defaults, border-box sizing, focus styles, and a `[hidden]` rule. |
+| `fonts-latin.css` | Optional Latin-only WOFF2 fonts, available since 0.1.2. Use instead of `fonts.css`, not alongside it.                                              |
+| `fonts.css`       | Optional self-hosted Space Grotesk, DM Sans, and DM Mono via Fontsource. Your bundler emits the font assets.                                       |
+| `tokens.css`      | Tokens alone, for an app that supplies its own component styles. Already included by `styles.css`.                                                 |
+
+Override semantic tokens after importing the styles:
+
+```css
+:root {
+  --font-sans: system-ui, sans-serif;
+  --font-display: system-ui, sans-serif;
+}
+
+:root[data-theme="dark"] {
+  --bg: #111411;
+  --fg: #edf0e8;
+}
+```
 
-## Theme and motion setup
+Styles use global component classes and document-level theme tokens. Scope your application's classes to avoid collisions with names such as `.card` and `.button`. Contour's CSS isn't isolated with Shadow DOM or CSS Modules.
 
-All theme toggles read the same document state. Set `data-theme="light"` or `"dark"` on `<html>`. `useTheme(animate)` returns `{ theme, toggle }`; call `toggle(buttonElement)` for a user action. The existing `aa-theme` local-storage key is preserved for compatibility with the original portfolio. Preference storage is origin-local, not shared across different website domains.
+The three Fontsource packages and `lucide-react` are direct dependencies. Omitting `fonts.css` keeps its font assets out of your application's bundle; the font packages still install. React and React DOM are peers. Three.js and Lenis are optional peers. Development tools aren't installed as Contour's consumer dependencies; tests and tooling are excluded from the npm archive.
 
-To avoid a first-paint theme flash, inject the exported static `themeBootstrapScript` from `@abuzareal/contour-ui/theme-bootstrap` into the HTML head at build time. It has no user-supplied interpolation. A strict Content Security Policy needs the appropriate script hash or nonce; do not enable unsafe inline scripts generally.
+## Theme and motion
 
-Set `data-motion="off"` on your application wrapper when animation is disabled. `useMotionPreference()` tracks the system setting; combine it with your app's pause state. Pass the resulting `motionEnabled` to Three.js scenes and `animate` to theme controls. Reduced motion overrides theme reveal animations even if `animate` is true. No animation is required to operate the UI.
+Set `data-theme="light"` or `"dark"` on `<html>`. `ThemeToggle` and `useTheme(animate)` read the same document state. The hook returns `{ theme, toggle }`; call `toggle(buttonElement)` from a user action. Preferences use the `aa-theme` local-storage key and are local to the site's origin.
 
-`useToast()` must run below `ToastProvider`. The library does not send messages, collect analytics, fetch application data, or require a service account. Links reject executable URL schemes; application authentication, validation, authorization, and data handling remain the application's responsibility.
+For theme selection before first paint, inject `themeBootstrapScript` from `@abuzareal/contour-ui/theme-bootstrap` into the HTML head at build time. The exported string has no user interpolation. With a strict Content Security Policy, authorize that script with a nonce or hash.
 
-## Optional entries
+`useMotionPreference()` returns whether the user prefers reduced motion. Combine it with your app's pause state, set `data-motion="off"` on the app wrapper when needed, and pass `motionEnabled` to scenes and `animate` to theme controls. System reduced motion also disables the theme reveal.
+
+## Components
+
+| Area                        | Public exports                                                                                                                                                  |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions                     | `Button`, `IconButton`, `ExternalLink`, `SegmentedControl`, `ThemeToggle`                                                                                       |
+| Forms                       | `Field`, `TextField`, `TextArea`, `SelectField`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`                                                                   |
+| Navigation                  | `Tabs`, `Breadcrumbs`, `Pagination`, `Stepper`, `DropdownMenu`                                                                                                  |
+| Data and layout             | `Avatar`, `Badge`, `Card`, `DataTable`, `Disclosure`, `Divider`, `EmptyState`, `Kbd`, `SectionLabel`, `Stat`, `Tag`, `Timeline`                                 |
+| Feedback                    | `Alert`, `ProgressBar`, `Skeleton`, `Spinner`, `ToastProvider`, `useToast`                                                                                      |
+| Motion and identity         | `BrandMark`, `CountUp`, `DepthButton`, `FlipCard`, `Magnetic`, `Marquee`, `Reveal`, `RevealHeading`, `ScrollProgress`, `TiltCard`, `GitHubIcon`, `LinkedInIcon` |
+| Overlays and scene fallback | `Dialog`, `Popover`, `Tooltip`, `SceneBoundary`                                                                                                                 |
+
+The root entry also exports theme, motion, clipboard, dismissal, navigation, and browser-lifecycle hooks plus utility functions. Check `src/index.ts` in a source checkout or `dist/index.d.ts` in the installed package for the complete API. Component declarations describe their props.
+
+Use visible field labels, accessible names for icon buttons, and text alongside status colors. `DataTable` sorts scalar string/number values; `Pagination` expects a positive integer page count and a page within that range. Flip cards use a button and make the hidden face inert.
+
+Props support varies between components. Don't assume every export forwards DOM refs, accepts arbitrary native attributes, supports router `asChild` composition, or integrates with form libraries through refs. Verify the relevant type before adopting it.
+
+## Optional scenes and scrolling
+
+Core imports don't load Three.js or Lenis. Install either only if you use its entry:
 
 ```sh
-npm install three@^0.186.1      # only for the /three entry
-npm install lenis@^1.3.26      # only for the /scroll entry
+npm install three@^0.186.1 # @abuzareal/contour-ui/three
+npm install lenis@^1.3.26 # @abuzareal/contour-ui/scroll
+# TypeScript consumers of /three also need the matching declarations:
+npm install -D @types/three@^0.186.0
 ```
 
+`/scroll` exports `useSmoothScroll`. `/three` exports `Sculpture`, `ObjectStudy`, `useThreeStage`, geometry/material helpers, and associated types. CSS depth controls such as `TiltCard` and `FlipCard` are core exports and don't require Three.js.
+
 ```tsx
 import { lazy, Suspense } from "react";
+import { SceneBoundary } from "@abuzareal/contour-ui";
+
 const Sculpture = lazy(() =>
   import("@abuzareal/contour-ui/three").then((module) => ({
     default: module.Sculpture,
   })),
 );
 
-// Provide a sized container and an application-owned static fallback.
-<Suspense fallback={<p>Loading preview…</p>}>
-  <Sculpture motionEnabled={false} />
-</Suspense>;
+export function Preview() {
+  return (
+    <div>
+      <p>Three interlocking links, shown in a WebGL preview when available.</p>
+      <SceneBoundary>
+        <Suspense fallback={<p>Loading preview…</p>}>
+          <Sculpture motionEnabled={false} />
+        </Suspense>
+      </SceneBoundary>
+    </div>
+  );
+}
 ```
 
-`/three` also exports `ObjectStudy`, `useThreeStage`, geometry/material helpers, and their types. Treat the 3D API as experimental in this initial release. Scene setup functions are captured on mount; remount the scene when its setup configuration changes. Scenes require WebGL and should always have a visible fallback. No Three.js or Lenis imports occur in the core runtime graph.
-
-## Components and typed APIs
-
-The package exports named components and props types. TypeScript declarations are shipped with every entry; editors provide the complete props API.
-
-- Actions: `Button`, `IconButton`, `ExternalLink`, `SegmentedControl`, `ThemeToggle`.
-- Forms: `Field`, `TextField`, `TextArea`, `SelectField`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`.
-- Navigation: `Tabs`, `Breadcrumbs`, `Pagination`, `Stepper`, `DropdownMenu`.
-- Data and layout: `Avatar`, `Badge`, `Card`, `DataTable`, `Disclosure`, `Divider`, `EmptyState`, `Kbd`, `SectionLabel`, `Stat`, `Tag`, `Timeline`.
-- Feedback: `Alert`, `ProgressBar`, `Skeleton`, `Spinner`, `ToastProvider`, `useToast`.
-- Motion and signature: `BrandMark`, `CountUp`, `DepthButton`, `FlipCard`, `Magnetic`, `Marquee`, `Reveal`, `RevealHeading`, `ScrollProgress`, `TiltCard`, `GitHubIcon`, `LinkedInIcon`.
-- Overlays: `Dialog`, `Popover`, `Tooltip`, `SceneBoundary`.
+Give scenes a sized container and a usable static fallback. `SceneBoundary` hides a scene on failure; it doesn't supply fallback content, so keep that content outside the boundary. The 3D API is experimental. Stage setup functions are captured on mount; remount a scene when its setup configuration changes. WebGL availability is a runtime requirement for scenes.
 
-Use visible labels for fields, concise action labels for buttons, accessible labels for icon-only controls, and text alongside status colors. Sortable tables expect scalar string/number row values. Pagination expects a positive integer page count and a page in that range. Flip cards switch through their button; the hidden side is inert.
+## Release notes and upgrades
 
-Global colors, fonts, radii, duration, and spacing variables are in `tokens.css`. Override semantic tokens rather than copying components into your app. `styles.css` includes tokens and component styles; `fonts.css` and `reset.css` are separately opt-in. Do not import catalogue or portfolio CSS into other apps.
-
-## Independent repositories and updates
-
-This repository contains only the library. The catalogue and portfolio remain separate repositories and consume the same published npm version. During first-release validation, a packed archive can be installed locally; replace the archive dependency with the registry version before committing consumer manifests.
+**0.1.2** adds the optional `fonts-latin.css` export, clearer setup documentation, and links to the Contour UI documentation site. Component APIs and runtime dependencies remain unchanged from 0.1.1. React 19 support and the interaction fixes from 0.1.1 are retained. `CHANGELOG.md` is included in the package archive and [npm's Code view](https://www.npmjs.com/package/@abuzareal/contour-ui?activeTab=code); it contains the upgrade details for each version.
 
 ```sh
-npm install @abuzareal/contour-ui@0.1.0 --save-exact
+npm install @abuzareal/contour-ui@0.1.2 --save-exact
 ```
 
-Commit both `package.json` and `package-lock.json`. Dependabot proposes version updates in each consumer repository. Updates reach production after that project's checks, merge, rebuild, and deployment. A registry release does not change deployed applications automatically.
+Commit your manifest and lockfile, run your application's checks, and review both themes, dialogs, forms, and motion before deploying. Version 0.1.1 includes a document scroll lock for dialogs and drawers. Review any app-level lock before removing it, including nested dialogs and short screens. Package publication doesn't update deployed consumers automatically.
+
+The package is public under MIT. The source repository and its issue tracker currently require collaborator access. Public users can inspect the distributed code, CSS, declarations, and release documents through npm. Contact the [maintainer](https://github.com/abuzareal) for support; see `SECURITY.md` in the package for vulnerability reporting guidance.
 
-## Development and release
+## Develop this library
+
+From a source checkout:
 
 ```sh
 npm ci --ignore-scripts
+npx playwright install chromium
 npm run validate
+npm run test:compat
 npm audit
 npm pack --dry-run
 ```
 
-See `RELEASING.md` for the release checklist, authentication, and trusted-publishing setup. The package ships only built code/styles and release documents, with no consumer installation scripts. The complete-source Git repository contains tests and tooling; those are excluded from the npm archive.
+`validate` checks types, lint, builds, Node/component tests, dialog browser behavior, and archive contents. `test:compat` builds packed React 18/19 consumers and compiles the source with React 19 types. `test:consumer` checks one packed consumer, with optional peers absent. `test:optional` verifies strict `/three` and `/scroll` declarations and builds their imports with explicit peers and Three.js types. The compatibility gate runs both checks and verifies the Latin font assets. Compatibility runs need registry access for clean installs.
+
+`src/` owns components, hooks, helpers, and public entries. `styles/` owns CSS. `tests/` owns regressions and browser checks; `scripts/` owns builds and package/consumer checks. `dist/` is generated. `RELEASING.md` in the source checkout and package archive covers validation and publication.
 
-MIT licensed. Font dependencies retain their own font licenses; Lucide, React, Three.js, and Lenis retain their respective licenses.
+MIT licensed. Fontsource fonts and dependencies retain their own licenses.

package/RELEASING.md

@@ -1,10 +1,20 @@
 # Releasing Contour UI
 
+## Package-page documentation and release notes
+
+The npm Readme tab renders the root `README.md`. npm updates it when a new package version is published; editing this repository does not update the existing npm page. Follow [npm's README update guidance](https://docs.npmjs.com/about-package-readme-files/). Do not try to overwrite a published version or unpublish it to change documentation.
+
+Keep installation, a working example, CSS/theme setup, supported APIs, optional dependencies, limits, and a release summary in the README. Keep the detailed version history in `CHANGELOG.md`, which ships in the archive and is available through npm's Code view. The private GitHub repository is not a public documentation destination. When public docs and changelog routes exist, add their verified URLs to the README and package metadata.
+
+Write new changes under **Unreleased**, or under a version heading explicitly marked **Pending release** when the next version has been chosen. At publication, remove the pending label and record the verified publication date. Use sections only when they contain useful changes: Added, Fixes, Compatibility, Upgrading, and Known limitations. Each entry should name the affected component/API and describe the user's resulting behavior. Include a migration example for incompatible changes. For a documentation-only patch, state that runtime behavior and dependency contracts are unchanged.
+
+Link each release to available evidence: changed APIs, relevant tests, and public issues/PRs when readers can access them. Do not invent dates, issue numbers, performance gains, accessibility certification, or compatibility results. Confirm that README examples use the exports and props in the release archive. Run the same release gates for a documentation patch; the archive, manifest, tag, changelog, and registry version must agree. Publishing still requires the maintainer's authorization.
+
 ## Initial release
 
 1. Verify `npm whoami` is `abuzareal`; the package is `@abuzareal/contour-ui` and public under MIT.
-2. Run `npm ci --ignore-scripts`, `npm run validate`, and `npm audit`. Review every advisory; do not release with unexplained audit findings.
-3. Test the actual packed archive in a clean React consumer without optional Three.js or Lenis, and in the catalogue and portfolio with their full browser suites.
+2. Run `npm ci --ignore-scripts`, install Chromium with `npx playwright install chromium` on a new machine, then run `npm run validate`, `npm run test:compat`, and `npm audit`. Review every advisory; do not release with unexplained audit findings.
+3. Test the actual packed archive in clean React 18 and React 19 consumers without optional Three.js or Lenis, and in the catalogue and portfolio with their full browser suites.
 4. Check `npm pack --dry-run --json` and licenses. No private data, credentials, unrelated assets, maps, or app content may enter the archive.
 5. Push the reviewed source and release commit to the independent GitHub repository. The owner currently keeps this repository private; the npm distribution remains public under MIT.
 6. Set `private` to `false` only for an approved, validated release. Publish from the verified owner account: `npm publish --access public`. Complete npm's required authentication/2FA personally.
@@ -32,6 +42,8 @@ Increment PATCH for compatible fixes, MINOR for compatible additions, and MAJOR
 
 Dependabot is selected because it is integrated with GitHub and requires no extra hosted service or bot account. It proposes weekly npm and action updates; the library is not auto-merged. npm distribution is public. Standard-hosted Actions run only if the repository is public; checks run locally while it stays private. Do not enable paid runners, private npm distribution, or paid security subscriptions as part of this setup.
 
-The validation workflows deliberately skip private repositories. If a consumer stays private, run its checks locally before merging dependency updates. Enabling private-repository Actions later requires reviewing that account's included usage and spending settings first.
+The library's validation workflows deliberately skip private repositories. Consumer policies vary: Portfolio allows private pull requests to opt in with the `run-validation` label. Check each consumer's workflow and run its required checks locally when CI is skipped. Enabling private-repository Actions requires reviewing that account's included usage and spending settings first.
+
+Consumers install with `npm install @abuzareal/contour-ui@VERSION --save-exact`, commit their lockfile, run their checks, and redeploy. Portfolio, Design-System, Atmos, Orbit, and the library remain independent repositories.
 
-Consumers install with `npm install @abuzareal/contour-ui@VERSION --save-exact`, commit their lockfile, run their checks, and redeploy. Keep the three Git repositories independent.
+The compatibility gate also installs the optional Three.js and Lenis peers in separate packed consumers. It checks `/three` and `/scroll` with `skipLibCheck: false`, builds their imports, and verifies the Latin WOFF2 export. Core consumers continue to run without those optional peers. Run `npm run test:optional` for that focused check.

package/dist/components/ui/CountUp.js

@@ -10,7 +10,9 @@ export default function CountUp({ to, duration = 1400, digits = 0, suffix = "",
         const element = ref.current;
         if (!element)
             return;
-        if (motionDisabledFor(element) || duration <= 0) {
+        if (motionDisabledFor(element) ||
+            duration <= 0 ||
+            typeof IntersectionObserver === "undefined") {
             setCurrent(to);
             return;
         }

package/dist/components/ui/Dialog.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useId, useRef } from "react";
 import { X } from "lucide-react";
 import { cx } from "../../lib/classNames.js";
+import { lockDocumentScroll } from "../../lib/lockDocumentScroll.js";
 export default function Dialog({ open, onClose, title, children, description, footer, placement = "center", }) {
     const ref = useRef(null);
     const titleId = useId();
@@ -15,6 +16,14 @@ export default function Dialog({ open, onClose, title, children, description, fo
             dialog.showModal();
         if (!open && dialog.open)
             dialog.close();
+        if (!open)
+            return;
+        const release = lockDocumentScroll(dialog.ownerDocument);
+        dialog.addEventListener("close", release);
+        return () => {
+            dialog.removeEventListener("close", release);
+            release();
+        };
     }, [open]);
     return (_jsx("dialog", { ref: ref, className: cx("dialog", `dialog-${placement}`), "aria-labelledby": titleId, "aria-describedby": description ? descriptionId : undefined, onCancel: (event) => {
             event.preventDefault();

package/dist/components/ui/FlipCard.js

@@ -1,9 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Two-sided card that flips in 3D; a button toggles it so the back is reachable without hover. */
-import { useState } from "react";
+import { useState, version } from "react";
 import { RefreshCw } from "lucide-react";
 import { cx } from "../../lib/classNames.js";
+// React 18 treats inert as an unknown string attribute; React 19 treats it as boolean.
+const inertAttributes = {
+    inert: Number.parseInt(version, 10) >= 19 ? true : "",
+};
 export default function FlipCard({ front, back, label }) {
     const [flipped, setFlipped] = useState(false);
-    return (_jsxs("div", { className: "flip-stage", children: [_jsxs("div", { className: cx("flip-card", flipped && "is-flipped"), children: [_jsx("div", { className: "flip-face flip-front", "aria-hidden": flipped, ...(flipped ? { inert: "" } : {}), children: front }), _jsx("div", { className: "flip-face flip-back", "aria-hidden": !flipped, ...(!flipped ? { inert: "" } : {}), children: back })] }), _jsxs("button", { type: "button", className: "flip-toggle mono", "aria-pressed": flipped, onClick: () => setFlipped((value) => !value), children: [_jsx(RefreshCw, { size: 13, "aria-hidden": "true" }), label] })] }));
+    return (_jsxs("div", { className: "flip-stage", children: [_jsxs("div", { className: cx("flip-card", flipped && "is-flipped"), children: [_jsx("div", { className: "flip-face flip-front", "aria-hidden": flipped, ...(flipped ? inertAttributes : {}), children: front }), _jsx("div", { className: "flip-face flip-back", "aria-hidden": !flipped, ...(!flipped ? inertAttributes : {}), children: back })] }), _jsxs("button", { type: "button", className: "flip-toggle mono", "aria-pressed": flipped, onClick: () => setFlipped((value) => !value), children: [_jsx(RefreshCw, { size: 13, "aria-hidden": "true" }), label] })] }));
 }

package/dist/components/ui/SelectField.d.ts

@@ -1,6 +1,6 @@
 /** Native select styled as an underlined field with a chevron. */
 import { type SelectHTMLAttributes } from "react";
-export type SelectFieldProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, "id"> & {
+export type SelectFieldProps = SelectHTMLAttributes<HTMLSelectElement> & {
     label: string;
     options: {
         value: string;
@@ -10,4 +10,4 @@ export type SelectFieldProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, "id
     error?: string;
     placeholder?: string;
 };
-export default function SelectField({ label, options, hint, error, placeholder, ...rest }: SelectFieldProps): import("react").JSX.Element;
+export default function SelectField({ id: providedId, "aria-describedby": describedBy, label, options, hint, error, placeholder, ...rest }: SelectFieldProps): import("react").JSX.Element;

package/dist/components/ui/SelectField.js

@@ -4,7 +4,10 @@ import { useId } from "react";
 import { ChevronDown } from "lucide-react";
 import { fieldDescribedBy } from "../../lib/a11y.js";
 import Field from "./Field.js";
-export default function SelectField({ label, options, hint, error, placeholder, ...rest }) {
-    const id = useId();
-    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, children: _jsxs("div", { className: "field-control field-select", children: [_jsxs("select", { ...rest, id: id, "aria-invalid": error ? true : undefined, "aria-describedby": fieldDescribedBy(id, hint, error), children: [placeholder && (_jsx("option", { value: "", disabled: true, children: placeholder })), options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] }), _jsx(ChevronDown, { className: "field-chevron", size: 16, "aria-hidden": "true" })] }) }));
+export default function SelectField({ id: providedId, "aria-describedby": describedBy, label, options, hint, error, placeholder, ...rest }) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
+    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, children: _jsxs("div", { className: "field-control field-select", children: [_jsxs("select", { ...rest, id: id, "aria-invalid": error ? true : undefined, "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
+                        .filter(Boolean)
+                        .join(" ") || undefined, children: [placeholder && (_jsx("option", { value: "", disabled: true, children: placeholder })), options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] }), _jsx(ChevronDown, { className: "field-chevron", size: 16, "aria-hidden": "true" })] }) }));
 }

package/dist/components/ui/TextArea.d.ts

@@ -1,10 +1,10 @@
 /** Multi-line text input with optional auto-resize and character counter. */
 import { type TextareaHTMLAttributes } from "react";
-export type TextAreaProps = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "id"> & {
+export type TextAreaProps = TextareaHTMLAttributes<HTMLTextAreaElement> & {
     label: string;
     hint?: string;
     error?: string;
     /** Grows with its content instead of scrolling. */
     autoResize?: boolean;
 };
-export default function TextArea({ label, hint, error, autoResize, maxLength, onChange, rows, ...rest }: TextAreaProps): import("react").JSX.Element;
+export default function TextArea({ id: providedId, "aria-describedby": describedBy, label, hint, error, autoResize, maxLength, onChange, rows, ...rest }: TextAreaProps): import("react").JSX.Element;

package/dist/components/ui/TextArea.js

@@ -3,8 +3,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useId, useLayoutEffect, useRef, useState, } from "react";
 import { fieldDescribedBy } from "../../lib/a11y.js";
 import Field from "./Field.js";
-export default function TextArea({ label, hint, error, autoResize = false, maxLength, onChange, rows = 3, ...rest }) {
-    const id = useId();
+export default function TextArea({ id: providedId, "aria-describedby": describedBy, label, hint, error, autoResize = false, maxLength, onChange, rows = 3, ...rest }) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
     const ref = useRef(null);
     const [length, setLength] = useState(String(rest.value ?? rest.defaultValue ?? "").length);
     const fitContent = () => {
@@ -15,7 +16,11 @@ export default function TextArea({ label, hint, error, autoResize = false, maxLe
         element.style.height = `${element.scrollHeight}px`;
     };
     useLayoutEffect(fitContent);
-    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, counter: maxLength ? `${length}/${maxLength}` : undefined, children: _jsx("div", { className: "field-control", children: _jsx("textarea", { ...rest, ref: ref, id: id, rows: rows, maxLength: maxLength, "data-auto-resize": autoResize || undefined, "aria-invalid": error ? true : undefined, "aria-describedby": fieldDescribedBy(id, hint, error), onChange: (event) => {
+    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, counter: maxLength
+            ? `${rest.value !== undefined ? String(rest.value).length : length}/${maxLength}`
+            : undefined, children: _jsx("div", { className: "field-control", children: _jsx("textarea", { ...rest, ref: ref, id: id, rows: rows, maxLength: maxLength, "data-auto-resize": autoResize || undefined, "aria-invalid": error ? true : undefined, "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
+                    .filter(Boolean)
+                    .join(" ") || undefined, onChange: (event) => {
                     setLength(event.target.value.length);
                     fitContent();
                     onChange?.(event);

package/dist/components/ui/TextField.d.ts

@@ -1,6 +1,6 @@
 /** Single-line text input with underline styling, optional icon/adornment, and character counter. */
 import { type InputHTMLAttributes, type ReactNode } from "react";
-export type TextFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, "id"> & {
+export type TextFieldProps = InputHTMLAttributes<HTMLInputElement> & {
     label: string;
     hint?: string;
     error?: string;
@@ -9,4 +9,4 @@ export type TextFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, "id"> &
     /** Content after the input, e.g. a unit or an icon button. */
     trailing?: ReactNode;
 };
-export default function TextField({ label, hint, error, hideLabel, leadingIcon, trailing, maxLength, onChange, ...rest }: TextFieldProps): import("react").JSX.Element;
+export default function TextField({ id: providedId, "aria-describedby": describedBy, label, hint, error, hideLabel, leadingIcon, trailing, maxLength, onChange, ...rest }: TextFieldProps): import("react").JSX.Element;

package/dist/components/ui/TextField.js

@@ -3,10 +3,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId, useState, } from "react";
 import { fieldDescribedBy } from "../../lib/a11y.js";
 import Field from "./Field.js";
-export default function TextField({ label, hint, error, hideLabel, leadingIcon, trailing, maxLength, onChange, ...rest }) {
-    const id = useId();
+export default function TextField({ id: providedId, "aria-describedby": describedBy, label, hint, error, hideLabel, leadingIcon, trailing, maxLength, onChange, ...rest }) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
     const [length, setLength] = useState(String(rest.value ?? rest.defaultValue ?? "").length);
-    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, hideLabel: hideLabel, disabled: rest.disabled, counter: maxLength ? `${length}/${maxLength}` : undefined, children: _jsxs("div", { className: "field-control", children: [leadingIcon && _jsx("span", { className: "field-icon", children: leadingIcon }), _jsx("input", { ...rest, id: id, maxLength: maxLength, "aria-invalid": error ? true : undefined, "aria-describedby": fieldDescribedBy(id, hint, error), onChange: (event) => {
+    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, hideLabel: hideLabel, disabled: rest.disabled, counter: maxLength
+            ? `${rest.value !== undefined ? String(rest.value).length : length}/${maxLength}`
+            : undefined, children: _jsxs("div", { className: "field-control", children: [leadingIcon && _jsx("span", { className: "field-icon", children: leadingIcon }), _jsx("input", { ...rest, id: id, maxLength: maxLength, "aria-invalid": error ? true : undefined, "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
+                        .filter(Boolean)
+                        .join(" ") || undefined, onChange: (event) => {
                         setLength(event.target.value.length);
                         onChange?.(event);
                     } }), trailing && _jsx("span", { className: "field-trailing", children: trailing })] }) }));

package/dist/components/ui/ThemeToggle.js

@@ -5,5 +5,5 @@ import useTheme from "../../hooks/useTheme.js";
 export default function ThemeToggle({ animate }) {
     const { theme, toggle } = useTheme(animate);
     const dark = theme === "dark";
-    return (_jsxs("button", { className: "theme-toggle", "aria-label": "Dark theme", "aria-pressed": dark, title: dark ? "Switch to light theme" : "Switch to dark theme", onClick: (event) => toggle(event.currentTarget), children: [_jsx(Moon, { className: "theme-icon-moon", size: 16, "aria-hidden": "true" }), _jsx(Sun, { className: "theme-icon-sun", size: 17, "aria-hidden": "true" })] }));
+    return (_jsxs("button", { type: "button", className: "theme-toggle", "aria-label": "Dark theme", "aria-pressed": dark, title: dark ? "Switch to light theme" : "Switch to dark theme", onClick: (event) => toggle(event.currentTarget), children: [_jsx(Moon, { className: "theme-icon-moon", size: 16, "aria-hidden": "true" }), _jsx(Sun, { className: "theme-icon-sun", size: 17, "aria-hidden": "true" })] }));
 }

package/dist/fonts-latin.css

@@ -0,0 +1,35 @@
+/* Optional Latin-only WOFF2 fonts. Use fonts.css for the complete character sets. */
+@font-face {
+  font-family: "DM Sans Variable";
+  font-style: normal;
+  font-display: swap;
+  font-weight: 100 1000;
+  src: url(@fontsource-variable/dm-sans/files/dm-sans-latin-wght-normal.woff2)
+    format("woff2-variations");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC,
+    U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212,
+    U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: "Space Grotesk Variable";
+  font-style: normal;
+  font-display: swap;
+  font-weight: 300 700;
+  src: url(@fontsource-variable/space-grotesk/files/space-grotesk-latin-wght-normal.woff2)
+    format("woff2-variations");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC,
+    U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212,
+    U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: "DM Mono";
+  font-style: normal;
+  font-display: swap;
+  font-weight: 400;
+  src: url(@fontsource/dm-mono/files/dm-mono-latin-400-normal.woff2)
+    format("woff2");
+}

package/dist/hooks/useClipboardCopy.js

@@ -3,7 +3,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 const resetDelay = 4000;
 export default function useClipboardCopy(text) {
     const [status, setStatus] = useState("idle");
-    const resetTimer = useRef();
+    const resetTimer = useRef(undefined);
     useEffect(() => () => clearTimeout(resetTimer.current), []);
     const copy = useCallback(async () => {
         clearTimeout(resetTimer.current);

package/dist/hooks/useDismiss.d.ts

@@ -1,3 +1,3 @@
 /** Calls onDismiss on Escape or a pointer press outside the container while `active`. */
 import { type RefObject } from "react";
-export default function useDismiss(container: RefObject<HTMLElement>, active: boolean, onDismiss: (reason: "escape" | "outside") => void): void;
+export default function useDismiss(container: RefObject<HTMLElement | null>, active: boolean, onDismiss: (reason: "escape" | "outside") => void): void;

package/dist/hooks/useHeaderScroll.d.ts

@@ -1,6 +1,6 @@
 /** Derives header state from scroll position: scrolled, over a dark area, and the active section. */
 import { type RefObject } from "react";
-export default function useHeaderScroll(header: RefObject<HTMLElement>): {
+export default function useHeaderScroll(header: RefObject<HTMLElement | null>): {
     scrolled: boolean;
     overDark: boolean;
     activeId: string;

package/dist/hooks/useMobileMenu.d.ts

@@ -1,3 +1,3 @@
 /** Open state for the mobile menu, closing on Escape, outside pointer, or desktop resize. */
 import { type RefObject } from "react";
-export default function useMobileMenu(container: RefObject<HTMLElement>, toggleButton: RefObject<HTMLButtonElement>): readonly [boolean, import("react").Dispatch<import("react").SetStateAction<boolean>>];
+export default function useMobileMenu(container: RefObject<HTMLElement | null>, toggleButton: RefObject<HTMLButtonElement | null>): readonly [boolean, import("react").Dispatch<import("react").SetStateAction<boolean>>];

package/dist/hooks/useThreeStage.d.ts

@@ -24,5 +24,5 @@ type StageOptions = {
     /** Camera z for a given aspect ratio, keeping the subject framed. */
     cameraDistance: (aspect: number) => number;
 };
-export default function useThreeStage(hostRef: RefObject<HTMLDivElement>, { motionEnabled, setup, cameraDistance }: StageOptions): void;
+export default function useThreeStage(hostRef: RefObject<HTMLDivElement | null>, { motionEnabled, setup, cameraDistance }: StageOptions): void;
 export {};

package/dist/kit/overlays.css

@@ -67,6 +67,7 @@
 }
 
 .dialog {
+  overscroll-behavior: contain;
   width: min(560px, calc(100vw - 32px));
   max-width: none;
   max-height: calc(100dvh - 48px);

package/dist/lib/lockDocumentScroll.d.ts

@@ -0,0 +1 @@
+export declare function lockDocumentScroll(document: Document): () => void;

package/dist/lib/lockDocumentScroll.js

@@ -0,0 +1,43 @@
+/** Reference-counted per document so nested dialogs cannot unlock each other. */
+const locks = new WeakMap();
+export function lockDocumentScroll(document) {
+    let lock = locks.get(document);
+    if (!lock) {
+        const root = document.documentElement;
+        const properties = ["overflow", "overscroll-behavior", "scrollbar-gutter"];
+        const previous = properties.map((name) => ({
+            name,
+            value: root.style.getPropertyValue(name),
+            priority: root.style.getPropertyPriority(name),
+        }));
+        // Preserve an existing scrollbar's space; short pages should gain no gutter.
+        if (document.defaultView &&
+            document.defaultView.innerWidth > root.clientWidth)
+            root.style.setProperty("scrollbar-gutter", "stable", "important");
+        root.style.setProperty("overflow", "hidden", "important");
+        root.style.setProperty("overscroll-behavior", "none", "important");
+        lock = {
+            count: 0,
+            restore: () => {
+                for (const { name, value, priority } of previous) {
+                    if (value)
+                        root.style.setProperty(name, value, priority);
+                    else
+                        root.style.removeProperty(name);
+                }
+            },
+        };
+        locks.set(document, lock);
+    }
+    lock.count += 1;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        if (--lock.count === 0) {
+            lock.restore();
+            locks.delete(document);
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abuzareal/contour-ui",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Editorial React components, themes, restrained motion, and optional Three.js objects.",
   "type": "module",
@@ -35,17 +35,21 @@
     "./styles.css": "./dist/styles.css",
     "./reset.css": "./dist/reset.css",
     "./tokens.css": "./dist/tokens.css",
-    "./fonts.css": "./dist/fonts.css"
+    "./fonts.css": "./dist/fonts.css",
+    "./fonts-latin.css": "./dist/fonts-latin.css"
   },
   "scripts": {
     "build": "node scripts/build.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "oxlint src --deny-warnings",
     "test": "node --test tests/*.test.mjs",
+    "test:browser": "node --test tests/*.browser.mjs",
     "check:package": "node scripts/check-package.mjs",
-    "validate": "npm run typecheck && npm run lint && npm run build && npm test && npm run check:package",
-    "prepublishOnly": "npm run validate",
-    "test:consumer": "node scripts/test-consumer.mjs"
+    "validate": "npm run typecheck && npm run lint && npm run build && npm test && npm run test:browser && npm run check:package",
+    "prepublishOnly": "npm run validate && npm run test:compat",
+    "test:consumer": "node scripts/test-consumer.mjs",
+    "test:compat": "node scripts/test-compat.mjs",
+    "test:optional": "node scripts/test-optional-consumer.mjs"
   },
   "dependencies": {
     "@fontsource-variable/dm-sans": "^5.3.0",
@@ -55,8 +59,8 @@
   },
   "peerDependencies": {
     "lenis": "^1.3.26",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "^18.3.1 || ^19.0.0",
+    "react-dom": "^18.3.1 || ^19.0.0",
     "three": "^0.186.1"
   },
   "peerDependenciesMeta": {
@@ -68,8 +72,8 @@
     }
   },
   "devDependencies": {
+    "@playwright/test": "1.63.0",
     "@testing-library/react": "^16.3.3",
-    "@types/node": "^24.13.3",
     "@types/react": "^18.3.5",
     "@types/react-dom": "^18.3.0",
     "@types/three": "^0.186.0",
@@ -94,8 +98,15 @@
     "type": "git",
     "url": "git+https://github.com/abuzareal/contour-ui.git"
   },
-  "homepage": "https://github.com/abuzareal/contour-ui#readme",
+  "homepage": "https://contour.abuzr.in/",
   "bugs": {
     "url": "https://github.com/abuzareal/contour-ui/issues"
-  }
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "components",
+    "design-system",
+    "contour-ui"
+  ]
 }