@abuzareal/contour-ui 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ Changes to the published `@abuzareal/contour-ui` package. Version headings refer
 
 No changes recorded.
 
+## 0.3.0
+
+Native refs and focused composition APIs for existing components. This heading records source work, not npm publication.
+
+- Button/IconButton/DepthButton/ThemeToggle, ExternalLink, Checkbox, Slider and Switch forward their native targets on React 18/19. Existing native field refs remain; callback refs stay stable across ordinary prop updates and support React 19 cleanup.
+- Dialog, Tabs and Popover accept native root props and typed props/refs for existing parts. Custom IDs preserve relationships; internal state/ARIA/classes remain intact. Caller handlers can prevent default selection/toggle/dismissal, while native dialog cancel remains prop-controlled.
+- Tabs retain ID-based focus/refs on reorder and remeasure the underline when root/list customization changes. Existing controlled/default state, menu disabled items/typeahead/stable IDs and focus return remain supported.
+- Publish native anchor and pinned Next Link recipes, preserving ordinary/canceled/middle-click navigation without nesting interactive elements or adding Button polymorphism. No runtime dependency or CSS/theme/form contract change is introduced.
+
+Existing JSX calls remain valid. Render components through React; newly ref-enabled exports are forwardRef components rather than plain callable functions. Named Switch/Slider/RadioGroup submission, overlay positioning/nesting corrections and CSS isolation remain separate work. See [COMPOSITION.md](COMPOSITION.md).
+
+```sh
+npm install @abuzareal/contour-ui@0.3.0 --save-exact
+```
+
+Use that command after registry availability is verified; update the exact pin/lockfile and validate your app.
+
 ## 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.

package/COMPOSITION.md

@@ -0,0 +1,193 @@
+# Refs, parts, state and links
+
+Contract version **0.3.0**. These additions are absent from npm 0.2.1; a source heading does not establish publication. Use the version named by the release notes. Import components directly and load CSS once. This guide describes existing DOM parts; no copying step or polymorphic Button system is required.
+
+## Native ref targets
+
+| Export                                       | Target and use                                                                                     |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Button, IconButton, DepthButton, ThemeToggle | HTMLButtonElement: focus, measurement, external trigger adapter                                    |
+| ExternalLink                                 | HTMLAnchorElement: focus and native-link integration                                               |
+| TextField, Checkbox, Slider                  | HTMLInputElement: focus/measurement; Checkbox retains indeterminate behavior                       |
+| TextArea / SelectField                       | HTMLTextAreaElement / HTMLSelectElement; existing native reset/validation preserved                |
+| Dialog                                       | HTMLDialogElement: focus/measurement; open stays prop-owned, do not bypass it with showModal/close |
+| Tabs                                         | Root HTMLDivElement; list/button/panel parts have separate native refs                             |
+| Popover                                      | Root HTMLDivElement; triggerProps.ref is its owned button, panelProps.ref its local panel          |
+
+Object refs become null on unmount/ref replacement. Callback refs receive the node then null; on React 19 they may return cleanup instead. Internal refs coexist with caller refs. Stable callback identities avoid deliberate ref replacement. Targets remain mounted while a dialog/panel is closed/hidden.
+
+RadioGroup, SegmentedControl, Pagination and DropdownMenu contain multiple controls; no singular input/action ref is claimed. Field is a frame, Tooltip describes a caller-owned child, Disclosure has native details semantics, and FlipCard/Tag have conditional controls. Presentation/scene wrappers receive no arbitrary native control handle. Part refs for those require a demonstrated reusable need.
+
+React 18 compatibility uses forwardRef; React 19 uses the same JSX API. Render through React; do not call exports as plain functions or depend on typeof being function. [React ref guidance](https://react.dev/reference/react/forwardRef) explains why low-level controls expose DOM nodes.
+
+```tsx
+import { useRef } from "react";
+import { Button, TextField } from "@abuzareal/contour-ui";
+export function FocusName() {
+  const action = useRef<HTMLButtonElement>(null);
+  const input = useRef<HTMLInputElement>(null);
+  return (
+    <>
+      <TextField ref={input} label="Name" name="name" />
+      <Button ref={action} onClick={() => input.current?.focus()}>
+        Focus name
+      </Button>
+    </>
+  );
+}
+```
+
+JavaScript uses the same imports/JSX and `useRef(null)` without type arguments.
+
+## Root and part customization
+
+Root className/style/id/data/ARIA and supported native handlers target the documented native root. Classes append to defaults. Part props customize existing DOM; children/raw markup/replacement components stay owned by Contour. CSS stays global; this API adds no isolation, scoped theme, portal or collision engine.
+
+| API                                        | DOM target                                                                                 |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| Dialog root/ref                            | dialog; title is its visible heading, onClose remains a no-argument request                |
+| Dialog panelProps/bodyProps/footerProps    | div.dialog-panel / div.dialog-body / footer.dialog-footer; footer only mounts with content |
+| Dialog closeButtonProps                    | Native close button; protected type=button, default label Close dialog                     |
+| Tabs root/ref / listProps                  | Outer div.tabs / div with tablist role and state-owned indicator variables                 |
+| TabItem.buttonProps/panelProps             | Tab button / div tabpanel, each with native ref/id/class/style/events/data/ARIA            |
+| Popover root/ref / triggerProps/panelProps | Outer div / owned trigger button / local nonmodal panel                                    |
+
+Roles, button types, tabIndex, selected/expanded/hidden state and ARIA relationships stay component-owned. Custom tab/panel IDs update both sides of their relationships. Extra label/description IDs compose with required IDs; callers supply referenced nodes. Native styles/classes can still make a composition unusable. Disabled-tab semantics are not introduced by buttonProps.
+
+```tsx
+import { useRef, useState } from "react";
+import { Button, Dialog, Popover, Tabs } from "@abuzareal/contour-ui";
+export function SettingsParts() {
+  const [open, setOpen] = useState(false);
+  const [activeTabId, setActiveTabId] = useState("profile");
+  const dialog = useRef<HTMLDialogElement>(null);
+  const body = useRef<HTMLDivElement>(null);
+  const help = useRef<HTMLButtonElement>(null);
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open settings</Button>
+      <Dialog
+        ref={dialog}
+        id="settings"
+        className="account-dialog"
+        open={open}
+        onClose={() => setOpen(false)}
+        title="Settings"
+        bodyProps={{ ref: body, "data-owner": "account" }}
+        closeButtonProps={{ "aria-label": "Close settings" }}
+      >
+        <Tabs
+          label="Settings sections"
+          activeTabId={activeTabId}
+          onTabChange={setActiveTabId}
+          listProps={{ className: "account-tabs" }}
+          tabs={[
+            {
+              id: "profile",
+              label: "Profile",
+              content: <p>Profile content</p>,
+            },
+            {
+              id: "preferences",
+              label: "Preferences",
+              content: <p>Preferences content</p>,
+            },
+          ]}
+        />
+        <Popover
+          trigger="Help"
+          title="Settings help"
+          triggerProps={{ ref: help }}
+          panelProps={{ id: "settings-help", className: "account-help" }}
+        >
+          <p>Local panels need room in their layout.</p>
+        </Popover>
+      </Dialog>
+    </>
+  );
+}
+```
+
+Popover still has local absolute placement and the known nested-dismissal limit. trigger is content inside an owned button, not an arbitrary interactive replacement. No submenu/initial-focus API is implied. Overlay corrections remain separate.
+
+## Event composition
+
+For the composed action handlers on Dialog, Tabs and Popover, the caller handler on the same owned element runs first. preventDefault vetoes internal tab click/arrow selection, popover trigger toggle, and dialog close-button/backdrop dismissal. stopPropagation controls propagation, not this cancellation contract. Root bubbling handlers run after descendant handlers; intercept through the relevant part or capture phase.
+
+Dialog onCancel receives the native event. Caller preventDefault vetoes onClose; Contour always prevents the browser from closing independently of open. An allowed cancel requests onClose and the parent must update open. Native disabled buttons cannot activate; Button loading also disables it. Native field counter/resize bookkeeping runs before its caller input/change handler and remains intact; preventDefault on those notifications is not a counter-reset API.
+
+```tsx
+// Fragment: the application owns open, saving and its operation/recovery.
+<Dialog
+  open={open}
+  title="Unsaved changes"
+  onClose={() => setOpen(false)}
+  onCancel={(event) => {
+    if (saving) event.preventDefault();
+  }}
+  closeButtonProps={{ disabled: saving }}
+>
+  <p>Finish the current operation before closing.</p>
+</Dialog>
+```
+
+If dismissal is suppressed, provide a usable cancel/recovery path. Do not disable essential interaction indefinitely.
+
+## State and callback audit
+
+| Family                                     | Existing ownership/callback contract                                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| Button/IconButton/DepthButton/ExternalLink | Native events; supported button disabled/loading; navigation remains browser/router-owned                     |
+| TextField/TextArea/SelectField/Checkbox    | Native event callbacks; controlled value/checked or native defaults; refs, validity/reset remain intact       |
+| Slider / Switch                            | Required number value / boolean checked, onChange(value); no new name/form/default/reset API                  |
+| RadioGroup / SegmentedControl              | Required string value, onChange(value); generated radio name / button group                                   |
+| Tabs                                       | activeTabId + onTabChange(id), or internal defaultTabId; invalid/removed IDs fall back to first available     |
+| Popover / DropdownMenu                     | open + onOpenChange(boolean), or internal defaultOpen; unchanged values do not notify                         |
+| Dialog                                     | Required open and onClose() request; no independent imperative ownership                                      |
+| Disclosure                                 | defaultOpen on native details; no controlled open/onOpenChange                                                |
+| Pagination                                 | page/pageCount and onChange(page); app owns URL/fetch/bounds                                                  |
+| FlipCard / Tooltip                         | Internal flipped / hover-focus state; no new controlled API                                                   |
+| ThemeToggle/useTheme                       | Shared document theme/preference, not scoped provider                                                         |
+| Tag, EmptyState, Alert, toast APIs         | Caller removal/actions or supplied feedback/library toast commands; no business operation/persistence implied |
+
+Do not switch controlled/uncontrolled ownership mid-mount. A later default does not reset established state. Controlled callbacks never silently overwrite parent state. Native event callbacks are not cosmetically renamed into value callbacks. Switch/Slider/RadioGroup form integration remains FORM scope.
+
+## Native and router links
+
+Use Button for actions and an anchor/router Link for navigation. buttonClassName supplies existing styles without interception. Preserve modified clicks, context menus, open-in-new-tab, destinations and keyboard activation. Do not nest interactive Buttons and anchors.
+
+```tsx
+import { buttonClassName } from "@abuzareal/contour-ui";
+export function ReportsLink() {
+  return (
+    <a href="/reports" className={buttonClassName("secondary")}>
+      Open reports
+    </a>
+  );
+}
+```
+
+The pinned Next App Router configuration renders a native anchor and owns client navigation. Put interactive handlers in a client boundary. This does not claim universal router support.
+
+```tsx
+"use client";
+import { useRef } from "react";
+import Link from "next/link";
+import { buttonClassName } from "@abuzareal/contour-ui";
+export function NextReportsLink() {
+  const link = useRef<HTMLAnchorElement>(null);
+  return (
+    <Link ref={link} href="/reports" className={buttonClassName("secondary")}>
+      Open reports
+    </Link>
+  );
+}
+```
+
+Other routers can use the same recipe when their documented Link forwards standard anchor props/ref. Browser checks cover native links and middle-click background tabs; the pinned Next fixture covers ordinary, canceled and middle-click navigation. [Next Link documentation](https://nextjs.org/docs/app/api-reference/components/link) distinguishes onClick from onNavigate: modified clicks retain native behavior.
+
+Anchors have no native disabled state. Render a suitable non-link explanation when navigation is unavailable, or omit the destination with explicit disabled semantics and app-owned keyboard/pointer behavior. Use a disabled Button when it is an action. CSS alone does not disable a link. ExternalLink retains scheme filtering and new-tab opener protection; internal routes use the router Link.
+
+## Abstraction review
+
+Each addition serves a bounded need: native focus/measurement/trigger refs; existing Dialog/Tabs/Popover root/part access; ID-based reorder-safe tab focus; caller handler cancellation. Private helpers implement those lifecycles. No runtime dependency, provider, build/distribution/styling system, generic component-replacement API or blanket polymorphism is introduced. Existing menu disabled items, keyboard opening, typeahead, stable identity and focus return remain covered.

package/CONTRACTS.md

@@ -1,6 +1,6 @@
 # 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.
+Contract version **0.3.0**, 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
 
@@ -16,10 +16,10 @@ No promise of enterprise completeness, universal embedding, all locales/RTL, eve
 
 ## 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 |
+| 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.
@@ -30,12 +30,12 @@ Catalogue UI/hook/scene compatibility modules intentionally forward public packa
 
 React is the UI runtime. Strict TypeScript/TSX source compiles through `tsc` into ES2022 ESM modules and declarations. The build copies CSS and selected licensed Latin font assets. It does not bundle React or compile the library into a Vite app. Vite serves development/consumer fixtures; Design-System is the Vite application. Consumers can write JavaScript or TypeScript.
 
-| Category | Current packages | Consumer consequence |
-| --- | --- | --- |
-| Runtime dependencies | lucide-react; @fontsource-variable/dm-sans; @fontsource-variable/space-grotesk; @fontsource/dm-mono | Install with Contour. Selected imports determine browser output. Font CSS is optional; font installation currently is not. |
-| Required peers | react/react-dom: `^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. |
+| Category                 | Current packages                                                                                       | Consumer consequence                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| Runtime dependencies     | lucide-react; @fontsource-variable/dm-sans; @fontsource-variable/space-grotesk; @fontsource/dm-mono    | Install with Contour. Selected imports determine browser output. Font CSS is optional; font installation currently is not. |
+| Required peers           | react/react-dom: React 18 (`^18.3.1`) or React 19 (`^19.0.0`)                                          | App supplies a matching pair; allowed range is broader than individually tested versions.                                  |
+| Optional peers           | three: `^0.186.1`; lenis: `^1.3.26`                                                                    | Core works without either. Install explicitly for the matching optional entry.                                             |
+| Development dependencies | TypeScript, Vite, Oxlint, Testing Library, jsdom, Playwright, React/types and optional peer dev copies | Source authoring/tests/build; not downstream Contour production dependencies.                                              |
 
 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.
 
@@ -43,16 +43,16 @@ Archive bytes, installed dependency bytes, browser JS/CSS, emitted fonts and act
 
 ## Environment and validation policy
 
-| Environment | Declared or exercised scope | Limits |
-| --- | --- | --- |
-| React/ReactDOM | Peer range above; packed matrix exercises 18.3.1, 19.0.0 and 19.3.0 | Matching pairs required. Other allowed patches are not individually certified. |
-| TypeScript | Strict source/fixtures; pinned optional/Next fixtures use 5.9.3; React 18 and 19 declarations compiled | No universal older/newer compiler support claim; JS users need no compiler at runtime. |
-| Node | Manifest >=22 for installation/tooling; use 22.12+ or 24+ with current Vite tooling | Browser components do not need Node in the browser. Actual runner versions are recorded per check. |
-| ESM/CSS-capable bundler | Packed Vite consumers exercise imports/declarations/CSS/fonts with no optional peers | No CommonJS build or unbundled-browser CSS loader promised. |
-| Next.js | Next 16.4.0 / React and ReactDOM 19.3.0, App Router, webpack production build | [NEXTJS.md](NEXTJS.md); other versions, Turbopack, Pages Router and Next Lenis remain unverified. |
-| Optional Three | Separate consumers and lazy Next mode; explicit Three/types, WebGL, sized host and static fallback | Experimental API; sampled lifecycle checks do not validate every custom scene/GPU/device. |
-| Optional scroll | Separate declaration/build consumer with Lenis and one scroll owner | Caller handles pause/reduced motion; generic Next Lenis integration unverified. |
-| Browsers | Playwright Chromium exercises selected native-dialog/reset/graphics/hydration/catalogue journeys | Emulation is not a physical device. Chromium/axe is not Firefox/WebKit/Safari or manual VoiceOver/NVDA verification. |
+| Environment             | Declared or exercised scope                                                                            | Limits                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| React/ReactDOM          | Peer range above; packed matrix exercises 18.3.1, 19.0.0 and 19.3.0                                    | Matching pairs required. Other allowed patches are not individually certified.                                       |
+| TypeScript              | Strict source/fixtures; 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).
 
@@ -70,11 +70,11 @@ Respect system reduced motion and app pause. CSS depth is core; WebGL is separat
 
 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.
+- Actions, ExternalLink, native fields/choices, Dialog and the documented Tabs/Popover parts forward their native targets on React 18/19. Multi-control/presentation wrappers do not imply a singular input ref; see [the composition contract](COMPOSITION.md).
+- Checkbox retains its generated ID and internal indeterminate behavior alongside the forwarded input ref; caller ARIA validity and descriptions remain composed. 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.
+- Dialog/Tabs/Popover expose typed root and owned-part props/refs; state and ARIA wiring stay protected and caller cancellation composes with internal behavior. Arbitrary trigger replacement, portals/collision and general polymorphism remain outside this API.
 - 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.
 

package/NEXTJS.md

@@ -1,6 +1,6 @@
 # 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.
+This guide describes **Contour 0.3.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:
 
@@ -49,3 +49,5 @@ export default function SearchForm() {
 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.
+
+The 0.3.0 fixture also verifies Button native-ref focus and styled Next Link ordinary/canceled/middle-click navigation. Use [the composition guide](COMPOSITION.md#native-and-router-links) for the Link recipe; Button remains an action rather than a polymorphic navigation component.