react-fresh-key 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Changes are recorded here before each release. During `0.x`, patches preserve
+the public API; minor releases may contain explicitly documented breaking changes.
+
+## 0.1.0 — 2026-09-11
+
+### Added
+
+- Declarative remount rules through `withRemount`, `Remount`, and the key hooks.
+- `useResettableState` for resetting a state value while preserving the component.
+- Shared and typed reset boundaries, including named reset requests and payloads.
+- TypeScript declarations and API documentation in editor tooltips.
+- ESM and CommonJS package builds with React 16.14 and later support.
+- A copy-in CLI with TypeScript and JavaScript modules, direct imports, and a
+  complete MIT notice in every copied file.
+
+The copy-in JSX modules require the automatic JSX transform. See the README
+for component compatibility and comparison semantics.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Buzatto de Campos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,475 @@
+# react-fresh-key
+
+**React remount and state reset utilities.**
+
+Reset component state when selected props change, or let a descendant reset an entire subtree. Define the reset rule alongside a reusable component so its callers can use it consistently.
+
+TypeScript support · No runtime dependencies beyond React · Copy into your project or install from npm
+
+Runtime: React 16.14 and later. Types are checked against React 17, 18, and 19.
+
+## Why?
+
+When a component needs a fresh start after a prop changes, it's tempting to reset its state in `useEffect`. This is a discouraged practice by React's team. For a full reset, [React recommends changing the component's `key`](https://react.dev/learn/you-might-not-need-an-effect#resetting-all-state-when-a-prop-changes):
+
+```tsx
+<Editor key={documentId} documentId={documentId} />
+```
+
+That's better, but putting the `key` at every call site makes the parent responsible for knowing **when the child's internals need a reset**. If Editor later needs a fresh mount when `mode` changes too, every parent must be updated. The component's internal reset requirements have become a concern for all of its consumers.
+
+`react-fresh-key` brings that responsibility back to where it belongs. Declare the reset rule alongside the component; callers pass its normal props. `withRemount` handles the keyed boundary, so changes to the reset rule stay with the component that needs them.
+
+## Quick start
+
+Copy the HOC into an existing React project:
+
+```bash
+npx react-fresh-key add with-remount
+# Or with pnpm:
+pnpm dlx react-fresh-key add with-remount
+```
+
+In a TypeScript project, put this example in `src/App.tsx`:
+
+```tsx
+import { useState } from 'react'
+import { withRemount } from './lib/fresh-key/withRemount'
+
+type EditorProps = { documentId: string }
+
+function Editor({ documentId }: EditorProps) {
+  const [draft, setDraft] = useState('')
+
+  return (
+    <label>
+      Draft for {documentId}
+      <textarea
+        value={draft}
+        onChange={(event) => setDraft(event.target.value)}
+      />
+    </label>
+  )
+}
+
+// Create the wrapper once, outside component rendering.
+const DocumentEditor = withRemount(Editor, ['documentId'])
+
+export default function App() {
+  const [documentId, setDocumentId] = useState('intro')
+
+  return (
+    <>
+      <button
+        onClick={() => setDocumentId((id) => id === 'intro' ? 'notes' : 'intro')}
+      >
+        Switch document
+      </button>
+      <DocumentEditor documentId={documentId} />
+    </>
+  )
+}
+```
+
+Type a draft, then switch documents. The editor mounts fresh and clears its draft each time the document changes. Re-rendering with the same `documentId` preserves the draft.
+
+For a package installation, use `npm install react-fresh-key` or `pnpm add react-fresh-key` and change the library import to `import { withRemount } from 'react-fresh-key'`.
+
+## Choosing a reset
+
+When the parent owns the identity decision, React's `key` prop is often enough. Otherwise, choose based on what needs to reset and where the reset decision belongs:
+
+| What needs to reset? | Use |
+| --- | --- |
+| One state value, while keeping the component mounted | `useResettableState` |
+| A whole component, with its rule declared at the definition site | `withRemount` |
+| An explicit subtree | `<Remount>` |
+| A subtree whose `key` you want to apply yourself | `useRemountKey` or `useRemountKeyWhen` |
+| A subtree, when one of its descendants requests it | `<ResetBoundary>` and `useResetBoundary` |
+| A subtree with named, typed reset requests or its own reset context | `createResetBoundary<Events>()` |
+| Identity controlled by the parent | React's `key` prop |
+
+**A remount discards local React state, refs, and DOM state throughout the affected subtree.** Effects clean up and run again. Focus, uncontrolled input values, and scroll position can be lost. Use `useResettableState` when resetting one value is enough.
+
+## Installation
+
+### Copy the source into your project
+
+The copy-in CLI is useful when you want to own and adapt these small utilities:
+
+```bash
+# Choose individual pieces; their local dependencies are included.
+npx react-fresh-key add with-remount reset-boundary --dir src/lib/fresh-key
+
+# Or copy every public API.
+npx react-fresh-key add all
+
+# List the available pieces.
+npx react-fresh-key list
+```
+
+The same commands work with `pnpm dlx` in place of `npx`.
+
+The CLI requires Node.js 18 or later. It chooses TypeScript when the directory you run it from contains `tsconfig.json`; otherwise it emits JavaScript. Use `--ts` or `--js` to choose explicitly.
+
+Copied `.tsx` and `.jsx` modules require the **automatic JSX transform**. For TypeScript, use `"jsx": "react-jsx"` in `tsconfig.json`, or `"jsx": "preserve"` when your framework handles the automatic transform. The npm builds already have JSX compiled and do not require this setting.
+
+| Option | Behavior |
+| --- | --- |
+| `--dir`, `-d` | Output directory; defaults to `src/lib/fresh-key` |
+| `--ts` / `--js` | Choose TypeScript or JavaScript output |
+| `--force`, `-f` | Replace existing source files |
+| `--dry-run` | Preview the operation without writing files |
+
+The CLI copies the selected source modules and their local dependencies. Existing source files are skipped unless you use `--force`. It does not create an index file; existing index files, including those generated by earlier versions, are left untouched.
+
+Each copied module includes the MIT license notice. Keep that notice when editing or redistributing the code.
+
+Import directly from each module using a path relative to your file, or your project's configured alias. For example, from `src/App.tsx` with the default output location:
+
+```tsx
+import { withRemount } from './lib/fresh-key/withRemount'
+import { ResetBoundary, useResetBoundary } from './lib/fresh-key/ResetBoundary'
+```
+
+### Install as a dependency
+
+Use a package dependency when you want to manage updates through your package manager:
+
+```bash
+npm install react-fresh-key
+# Or with pnpm:
+pnpm add react-fresh-key
+```
+
+```tsx
+import { withRemount, useResettableState } from 'react-fresh-key'
+```
+
+Both installation paths use the same implementation. A copy-in installation exposes the pieces you selected; use `add all` for the full API. The examples below use package imports; for a copy-in installation, copy the relevant pieces and import each API from its local module.
+
+## API
+
+### `withRemount(Component, watch)`
+
+Returns a component that remounts its wrapped component when the watch rule detects a change. Props continue to reach the wrapped component on ordinary updates.
+
+Using `Editor` from the quick start:
+
+```tsx
+import { withRemount } from 'react-fresh-key'
+
+const DocumentEditor = withRemount(Editor, ['documentId'])
+```
+
+Watch prop names, select a value or dependency list, or supply an explicit predicate:
+
+```tsx
+withRemount(Editor, ['documentId'])
+withRemount(Editor, (props) => props.documentId)
+withRemount(Editor, { select: (props) => [props.documentId] })
+withRemount(Editor, {
+  when: (previous, next) => previous.documentId !== next.documentId,
+})
+```
+
+A bare function is a selector. Use `{ when }` for predicates; a bare two-argument function is rejected. Selectors and prop-name lists use the [comparison rules](#comparison-rules) below.
+
+**Create the wrapper outside rendering.** Calling `withRemount` inside another component creates a new component type on each render and defeats state preservation.
+
+Selectors and predicates run during rendering. Keep them pure: do not send analytics, mutate inputs, or perform other side effects inside them. React may evaluate them more than once.
+
+Refs are forwarded when the wrapped component supports them. A parent can also supply a `key`; changing it causes an additional remount. A stable parent key does not disable the wrapper's own reset rule. See [TypeScript and component compatibility](#typescript-and-component-compatibility) for defaults, lazy components, and generics.
+
+### `<Remount>`
+
+Remounts its children when its dependencies change. The component containing the boundary stays mounted.
+
+Using the same `Editor`:
+
+```tsx
+import { Remount } from 'react-fresh-key'
+
+function EditorPanel({ documentId }: EditorProps) {
+  return (
+    <Remount deps={[documentId]}>
+      <Editor documentId={documentId} />
+    </Remount>
+  )
+}
+```
+
+For a predicate, provide both `watch` and `when`:
+
+```tsx
+function ConditionalEditorPanel({ documentId }: EditorProps) {
+  return (
+    <Remount
+      watch={documentId}
+      when={(previous, next) => previous !== next}
+    >
+      <Editor documentId={documentId} />
+    </Remount>
+  )
+}
+```
+
+Choose either `deps` or `watch` + `when`, and keep that mode for the lifetime of the boundary. A boundary can contain multiple children; they remount together.
+
+### `useRemountKey(deps)` and `useRemountKeyWhen(value, when)`
+
+Return a numeric key to apply to a child. A hook cannot remount the component calling it; put the key on the subtree you want to reset.
+
+```tsx
+import { useRemountKey, useRemountKeyWhen } from 'react-fresh-key'
+
+function EditorWithKey({ documentId }: EditorProps) {
+  const key = useRemountKey([documentId])
+  return <Editor key={key} documentId={documentId} />
+}
+
+function EditorWithPredicate({ documentId }: EditorProps) {
+  const key = useRemountKeyWhen(
+    documentId,
+    (previous, next) => previous !== next
+  )
+  return <Editor key={key} documentId={documentId} />
+}
+```
+
+The key starts at `0`. When a reset is detected, the hook returns the new key in that render. Follow the [comparison and input-stability rules](#comparison-rules) when passing objects or arrays directly to these hooks.
+
+### `useResettableState(initial, deps)`
+
+Returns `[value, setValue]`. When dependencies change, the value resets to the current `initial` value without remounting the component.
+
+```tsx
+import { useResettableState } from 'react-fresh-key'
+
+function CommentBox({ postId }: { postId: string }) {
+  const [draft, setDraft] = useResettableState('', [postId])
+
+  return (
+    <textarea
+      aria-label="Comment"
+      value={draft}
+      onChange={(event) => setDraft(event.target.value)}
+    />
+  )
+}
+```
+
+Changing `postId` clears the draft while preserving the mounted textarea and other component state. Functional updates such as `setDraft((draft) => draft + '!')` are supported, and the setter has a stable identity.
+
+A lazy initializer, such as `useResettableState(() => createDraft(), [postId])`, runs on initialization and when dependencies trigger a reset. It must be pure and may run more than once. Changing `initial` alone does not reset the state.
+
+### `<ResetBoundary>` and `useResetBoundary()`
+
+A descendant calls the returned `reset` function to remount everything inside the nearest boundary:
+
+```tsx
+import { useState } from 'react'
+import { ResetBoundary, useResetBoundary } from 'react-fresh-key'
+
+function Wizard() {
+  const [step, setStep] = useState(1)
+  const reset = useResetBoundary()
+
+  return (
+    <>
+      <p>Step {step}</p>
+      <button onClick={() => setStep((step) => step + 1)}>Next</button>
+      <button onClick={reset}>Start over</button>
+    </>
+  )
+}
+
+export function Checkout() {
+  return (
+    <ResetBoundary onReset={() => console.log('Restart requested')}>
+      <Wizard />
+    </ResetBoundary>
+  )
+}
+```
+
+Boundaries can nest, and `reset` has a stable identity. Calling `useResetBoundary` outside a boundary throws.
+
+`onReset` runs synchronously as part of the reset request. Use it to observe requests, such as for analytics; it is not a notification that the new subtree has mounted. Put focus setup for the newly mounted UI in that UI's own mount logic.
+
+### `createResetBoundary<Events>()`
+
+Creates a boundary and hook that share their own context. Define an event map whose keys name reset requests and whose values describe their payloads. Create the factory once at module scope, then export the boundary and hook under names that fit your feature:
+
+```tsx
+// clientReset.ts
+import { createResetBoundary } from 'react-fresh-key'
+
+const checkoutReset = createResetBoundary<{
+  restart: { step: number }
+  clear: void
+}>()
+
+export const ClientResetBoundary = checkoutReset.ResetBoundary
+export const useResetClientRegistration = checkoutReset.useResetBoundary
+```
+
+A descendant selects a request key by calling the hook. The returned function accepts that key's payload:
+
+```tsx
+// ClientRegistration.tsx
+import { useState } from 'react'
+import { ClientResetBoundary, useResetClientRegistration } from './clientReset'
+
+function RegistrationSteps() {
+  const [step, setStep] = useState(1)
+  const reset = useResetClientRegistration('restart')
+  const clear = useResetClientRegistration('clear')
+
+  return (
+    <>
+      <p>Step {step}</p>
+      <button onClick={() => setStep((step) => step + 1)}>Next</button>
+      <button onClick={() => reset({ step })}>Restart</button>
+      <button onClick={() => clear()}>Clear</button>
+    </>
+  )
+}
+
+export function ClientRegistration() {
+  return (
+    <ClientResetBoundary
+      onReset={(event) => {
+        if (event.key === 'restart') {
+          console.log('Restart requested from step', event.payload.step)
+        } else {
+          console.log('Clear requested')
+        }
+      }}
+    >
+      <RegistrationSteps />
+    </ClientResetBoundary>
+  )
+}
+```
+
+`onReset` receives a discriminated `{ key, payload }` event: checking `key` narrows the payload type. A required payload must be supplied; a payload type of `void`, `undefined`, or a union including `undefined` allows a call without arguments. Use arrow handlers as above to supply the intended payload explicitly. If the key is a union of several possible actions, the payload must be valid for every possible action.
+
+Each factory is isolated. Its hook targets the nearest boundary from **that same factory**, and throws if there is none; a boundary from another factory or the global `ResetBoundary` does not satisfy it. Exporting an alias or destructuring the returned hook is safe, with no binding required. The reset callback stays stable while its registered key and provider stay unchanged.
+
+Payloads are request metadata passed unchanged to `onReset`. The callback runs synchronously as part of the request, just like the global boundary. The global `ResetBoundary` and `useResetBoundary()` keep their zero-argument API, including `onClick={reset}`.
+
+For copy-in installations, `createResetBoundary` is included in the existing `reset-boundary` piece and imported directly from its `ResetBoundary` module.
+
+## Comparison rules
+
+React uses `Object.is` for its dependency arrays. This library extends that comparison for plain objects and ordinary arrays:
+
+| Watched value | Comparison |
+| --- | --- |
+| Primitives | `Object.is`, including its handling of `NaN` and signed zero |
+| Plain objects, including objects with a null prototype | Same own enumerable properties, compared one level deep with `Object.is`; symbol keys are included |
+| Ordinary arrays | Same length and own enumerable properties, compared one level deep; extra properties and symbol keys are included |
+| Functions, `Map`, `Set`, `Date`, and class instances, including Array subclasses | Reference identity |
+
+**Distinct flat objects with equal content preserve state.** This is an intentional reset-semantics choice: a new object reference alone may trigger a React effect but will not necessarily trigger a reset here. Treat watched values as immutable; mutating an existing reference is not detected.
+
+A selector that returns an array supplies a dependency list. Each dependency is compared using the table above; any other selector result is treated as one watched value.
+
+For `useRemountKeyWhen` and `<Remount watch={...} when={...}>`, the predicate runs when the watched value differs under these rules. For `withRemount`'s `{ when }` form, it runs when props differ shallowly, using `Object.is` per prop. Predicates receive the previous tracked snapshot and incoming input. The snapshot advances on a detected change even when the predicate returns `false`; it is not tied to the last remount.
+
+### Inputs to hooks must be able to compare equal
+
+Flat literals can be written directly inside a hook call:
+
+```tsx
+useRemountKey([documentId])
+useRemountKey([{ id: documentId }])
+useRemountKeyWhen({ id: documentId }, (previous, next) => previous.id !== next.id)
+```
+
+Values with a fresh nested reference on every render cannot settle:
+
+```tsx
+// Avoid creating these inside the hook call on every render.
+useRemountKey([{ document: { id: documentId } }])
+useRemountKey([new Date()])
+```
+
+These inputs can cause React's “Too many re-renders” error. Watch the relevant primitives, or use an existing reference from props, state, or a memoized value. The same constraint applies to `useResettableState` dependencies.
+
+`<Remount>` receives its inputs as props, which remain stable during its internal render retry. `withRemount` uses the props object to anchor its retry. Fresh nested values therefore do not create this internal loop in those components, but can cause remounts on each parent update.
+
+## TypeScript and component compatibility
+
+Props and ref types are inferred from the wrapped component. The package exposes both ESM and CommonJS builds with corresponding TypeScript declarations.
+
+| Component | `withRemount` behavior |
+| --- | --- |
+| Function or class component | Preserves declared props and supported ref types |
+| Class with `defaultProps`, including through `memo` | Defaulted props stay optional at call sites; selectors and predicates receive those defaults |
+| `lazy` component, including through nested `memo` | Requires props as declared, because inner defaults are unavailable before the lazy module loads |
+| Generic component | Does not preserve the generic type parameter; place `<Remount>` inside the generic component to retain inference |
+
+JavaScript parameter defaults inside a component run when that component renders; the wrapper cannot evaluate them for a selector. Selectors should handle any optional props they receive.
+
+The public types are `DepsList`, `WatchSpec`, `RemountedProps`, `RemountProps`, `RemountDepsProps`, `RemountWhenProps`, `ResetBoundaryProps`, `ResetEvent<Events>`, and `TypedResetBoundaryProps<Events>`.
+
+Server rendering, hydration, StrictMode, and interrupted transitions are covered by tests. Server and client inputs and initializers must still produce consistent output. In frameworks using React Server Components, consume these utilities behind a `'use client'` boundary.
+
+## How resets work
+
+The declarative remount APIs store a snapshot of watched inputs and a numeric key. When the watch rule calls for a remount, they update the key in their own state during rendering and return the new key immediately. React restarts that render before committing the keyed subtree. This follows React's documented [pattern for storing information from previous renders](https://react.dev/reference/react/useState#storing-information-from-previous-renders).
+
+`useResettableState` uses the same snapshot pattern to replace only its state value. Global and factory-created reset boundaries change their key when a descendant calls their reset function; typed request keys identify the event sent to `onReset`, while the whole boundary subtree remounts.
+
+Dependency-driven resets are not scheduled from an effect, avoiding an intermediate commit with state from the previous inputs. Ordinary component effects still follow React's lifecycle, and remounting still runs effect cleanup and setup.
+
+## Contributing
+
+Use Node.js 24 and pnpm 10.27.0 for development and release checks. The pnpm version is pinned in `package.json`; [install pnpm](https://pnpm.io/10.x/installation) before running the commands below. The installed package and CLI support Node.js 18 and later.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run check
+# Also verify the packed package against real React installations (needs network access).
+pnpm run check:release
+```
+
+Biome handles linting and formatting for maintained JavaScript, TypeScript, JSX, TSX, and JSON files, omitting optional JavaScript and TypeScript semicolons. `.editorconfig` keeps editors aligned with these formatting defaults, including two-space indentation and LF line endings.
+
+| Command | Behavior |
+| --- | --- |
+| `pnpm run lint` | Report lint findings without changing files |
+| `pnpm run lint:fix` | Apply safe lint fixes; review any remaining findings manually |
+| `pnpm run format` | Write formatting changes |
+| `pnpm run format:check` | Check formatting without changing files |
+| `pnpm run check:style` | Run the combined lint and formatting check with `biome ci --error-on-warnings .` |
+
+Generated `dist/` and `templates/`, dependency and store directories, `.tmp-vendor/`, and `pnpm-lock.yaml` are excluded from Biome. TypeScript checks remain part of validation: linting does not replace the API type assertions or React compatibility checks.
+
+`pnpm run check` includes `check:style`, type checks, tests, a build, and export checks. CI runs that same command; release checks and the `preversion` and `prepublishOnly` hooks include it too.
+
+`pnpm run test` includes runtime tests, type assertions, React 17/18/19 type compatibility, SSR/hydration, interrupted transitions, and CLI integration. Use `pnpm run test:types` to run only the type suite. Check the command's exit status and reported type errors as well as the passed-test count.
+
+| Path | Purpose |
+| --- | --- |
+| `src/` | Library source |
+| `bin/cli.mjs` | Copy-in CLI |
+| `registry.json` | Pieces, dependencies, and public exports |
+| `scripts/build-templates.mjs` | Generates TypeScript and JavaScript templates from source |
+| `test/` | Runtime, type, compatibility, and distribution tests |
+
+Templates are generated during the build. The CLI tests typecheck and run direct imports from copied modules, check that every public API is available, and verify that the registry matches the package's public exports. Package declarations and export resolution are checked with [Are the types wrong?](https://arethetypeswrong.github.io/).
+
+`pnpm run check:release` also installs the packed artifact into isolated consumers with React 16.14, 17, 18, and 19, then checks native ESM, CommonJS, server rendering, and the installed CLI. After a build, run one version with `pnpm run check:package --react 17.0.2`. CI installs from `pnpm-lock.yaml` with `--frozen-lockfile` and checks packed consumers on Node.js 18 and 24.
+
+Versions follow [Semantic Versioning](https://semver.org/). During `0.x`, patches preserve the public API; minor releases may introduce breaking changes, which are called out in the [changelog](./CHANGELOG.md). See [RELEASING.md](./RELEASING.md) for version bumps and publication steps.
+
+## Prior art
+
+[`react-remount`](https://github.com/sag1v/react-remount) and [`react-remount-component`](https://github.com/alexkrolick/react-remount-component) explored declarative component remounting. This library brings together prop-based remount rules, key hooks, state-only resets, and descendant-triggered reset boundaries, with TypeScript and copy-in distribution.
+
+## License
+
+MIT © [Rafael Buzatto de Campos](https://github.com/rbuzatto)

package/RELEASING.md

@@ -0,0 +1,89 @@
+# Releasing
+
+Use Node.js 24 and pnpm 10.27.0, pinned in the `packageManager` field. `package.json`
+is the version source of truth; the CLI reads it and the build includes it in
+template headers. Commit dependency changes to `pnpm-lock.yaml`. Generated
+`dist/` and `templates/` files are not committed.
+
+## Before the first release
+
+1. Confirm that `origin` points to `https://github.com/rbuzatto/react-fresh-key.git`
+   and that `repository`, `homepage`, and `bugs` in `package.json` refer to this
+   repository.
+2. Run `pnpm install --frozen-lockfile`, then `pnpm run check:release`. This includes
+   Biome lint and formatting checks, TypeScript checks, tests, a fresh build,
+   declaration/export checks, and installation of the packed artifact against
+   React 16.14, 17, 18, and 19. The package checks require network access and use
+   temporary consumer projects.
+3. Review `pnpm --config.ignore-scripts=true pack --dry-run`. Confirm the archive contains the
+   builds, declarations, CLI, registry, templates, documentation, and license.
+4. Keep version `0.1.0` for this first publication. Replace `Unreleased` in its
+   changelog heading with the release date, commit the release notes, and make
+   sure `git status --short` is empty.
+5. Create the first tag with `git tag -a v0.1.0 -m "Release 0.1.0"`. Push the
+   commit and tag to the configured remote and wait for CI to pass.
+6. Authenticate to the intended npm account with `pnpm login`, check it with
+   `pnpm whoami`, and run `pnpm publish` with your publish branch at that exact
+   tagged commit. pnpm defaults to publishing from `main` or `master`; configure
+   `publishBranch` in `pnpm-workspace.yaml` if the repository uses another branch.
+
+`pnpm publish` runs the complete release checks through `prepublishOnly`, including
+lint and formatting. CI validates pushes, pull requests, and version tags; it does
+not publish packages.
+
+## Subsequent versions
+
+Use [Semantic Versioning](https://semver.org/): while the package is below `1.0`,
+patch releases preserve the public API, and minor releases may make breaking
+changes. Describe breaking changes and migration steps in `CHANGELOG.md`.
+At `1.0`, use major versions for breaking public API changes.
+
+1. Prepare and commit the changes and a dated changelog entry for the next version.
+2. Start from a clean worktree and run one of:
+
+   ```bash
+   pnpm version patch
+   pnpm version minor
+   ```
+
+   pnpm 10 delegates this command to the npm bundled with Node.js. The `preversion`
+   hook runs the release checks, including lint and formatting, then
+   `package.json` is updated. The `version` hook rebuilds the outputs with the new
+   version before the version commit and tag are created. `pnpm-lock.yaml` does
+   not store this package's root version, so a version-only bump does not change
+   it. A failed hook must be resolved before proceeding; inspect the worktree
+   because a failed build after the bump can leave uncommitted version changes.
+3. Push the version commit and tag to the configured remote, wait for CI, then
+   publish from the tagged commit. `prepublishOnly` checks the new version again.
+
+Do not reuse a version that npm has already published. Do not bypass release
+hooks with `--ignore-scripts` when publishing.
+
+## Individual checks
+
+```bash
+pnpm run lint
+pnpm run format:check
+pnpm run check:style
+pnpm run check
+pnpm run check:package
+pnpm run check:package --react 17.0.2
+```
+
+`lint` and `format:check` report findings without writing files. `check:style`
+runs both through `biome ci --error-on-warnings .`. Before committing, use `pnpm run lint:fix` for
+safe lint fixes and `pnpm run format` to apply formatting; review remaining lint
+findings manually. Biome covers maintained JS/TS/JSX/TSX/JSON files, excluding
+generated outputs, dependency/store directories, `.tmp-vendor/`, and `pnpm-lock.yaml`.
+
+`check` includes `check:style`, TypeScript checks, source/type tests, builds, and
+export checks. The TypeScript checks still validate the public API and React
+compatibility. `check:package` uses the existing build, packs it without lifecycle
+scripts, and verifies the actual installed package. Run `pnpm run build` first
+when invoking it on its own.
+
+CI installs the pinned pnpm version from `packageManager`, caches its store, and
+uses `pnpm install --frozen-lockfile`, then `pnpm run check` for lint, formatting,
+and source validation. The package matrix uses Node.js 18 and 24.
+Build tooling runs on Node.js 24, separately from the Node.js 18 minimum supported
+by consumers.