react-fresh-key 0.1.0

package/templates/ts/useRemountKey.ts

@@ -0,0 +1,115 @@
+// react-fresh-key v0.1.0 — vendored copy (TypeScript).
+// This file is yours now: edit it freely. Docs: https://www.npmjs.com/package/react-fresh-key
+/*!
+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.
+*/
+import { useState } from 'react'
+import { areDepsEqual, isEqualDep, type DepsList } from './utils'
+
+/**
+ * Returns a numeric key that changes whenever any value in `deps` changes.
+ * Values are compared with `Object.is` — like React's own dependency
+ * comparison — except that plain objects and ordinary arrays are compared
+ * one level deep. Distinct objects with equal content preserve the key;
+ * `[{ id }]` written inline therefore converges instead of looping.
+ *
+ * A hook cannot remount the component it runs in, so apply the key to an
+ * inner subtree:
+ *
+ * ```tsx
+ * function Profile({ userId }: { userId: string }) {
+ *   const key = useRemountKey([userId])
+ *   return <ProfileForm key={key} userId={userId} />
+ * }
+ * ```
+ *
+ * The key is derived purely during render (the setState-in-render
+ * "derived state" pattern), so it is SSR-deterministic and StrictMode-safe.
+ * In the render where deps change, the *new* key is returned immediately.
+ *
+ * **Stability contract** — put primitives, references you already hold
+ * (props, state, memoized values), or flat plain objects/arrays in `deps`.
+ * A value that is a *new, non-equal* reference on every render — a nested
+ * object literal, `new Map()`, `new Date()`, a class instance built inline —
+ * can never compare equal and will trip React's re-render limit. Hold such
+ * values in state or `useMemo` first.
+ *
+ * @param deps Watched values, compared using {@link DepsList} rules. Treat the
+ * list and its values as immutable; changing their contents in place is not
+ * detected reliably. An empty list keeps the initial key.
+ * @returns A key local to this hook instance, starting at `0` and increasing
+ * when dependencies change. Apply it to a descendant element's `key` prop.
+ */
+export function useRemountKey(deps: DepsList): number {
+  const [state, setState] = useState<{ deps: DepsList; key: number }>({
+    deps,
+    key: 0,
+  })
+  if (!areDepsEqual(state.deps, deps)) {
+    // Documented React pattern: setting state during render restarts the
+    // render immediately with the new state, before touching the DOM.
+    const key = state.key + 1
+    setState({ deps, key })
+    return key
+  }
+  return state.key
+}
+
+/**
+ * Predicate flavor of {@link useRemountKey}: tracks an arbitrary `value` and
+ * bumps the key when `when(prev, next)` returns `true` for a changed value.
+ *
+ * `prev` is the last recorded value. Whenever a changed value is observed,
+ * the snapshot advances even if the predicate returns `false`. Equal values
+ * retain the existing snapshot and skip the predicate. Equality uses
+ * `Object.is`, or a one-level shallow comparison for plain objects and ordinary
+ * arrays, so a flat inline object (`useRemountKeyWhen({ id, tab }, …)`) converges.
+ *
+ * ```tsx
+ * const key = useRemountKeyWhen(user, (prev, next) => prev.id !== next.id)
+ * ```
+ *
+ * **Stability contract**: the same as {@link useRemountKey} — a value that is
+ * a new, non-equal reference on every render (nested literals, Map, Date,
+ * class instances built inline) cannot converge; hold it in state or `useMemo`.
+ *
+ * @param value The immutable value to track. Replace changed objects instead
+ * of mutating them in place.
+ * @param when A pure render-time predicate comparing the last recorded value
+ * with the new value. It is skipped on initial render and for equal values;
+ * changing only the predicate does not trigger a comparison.
+ * @returns A key starting at `0`, increased when a changed value satisfies
+ * `when`. Apply it to a descendant element; it cannot remount this hook's owner.
+ */
+export function useRemountKeyWhen<T>(value: T, when: (prev: T, next: T) => boolean): number {
+  const [state, setState] = useState<{ value: T; key: number }>({
+    value,
+    key: 0,
+  })
+  if (!isEqualDep(state.value, value)) {
+    const key = when(state.value, value) ? state.key + 1 : state.key
+    setState({ value, key })
+    return key
+  }
+  return state.key
+}

package/templates/ts/useResettableState.ts

@@ -0,0 +1,93 @@
+// react-fresh-key v0.1.0 — vendored copy (TypeScript).
+// This file is yours now: edit it freely. Docs: https://www.npmjs.com/package/react-fresh-key
+/*!
+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.
+*/
+import { useCallback, useState, type Dispatch, type SetStateAction } from 'react'
+import { areDepsEqual, type DepsList } from './utils'
+
+function resolveInitial<T>(initial: T | (() => T)): T {
+  return typeof initial === 'function' ? (initial as () => T)() : initial
+}
+
+/**
+ * Like `useState`, but the state snaps back to `initial` whenever any value
+ * in `deps` changes.
+ *
+ * This is the cheap alternative to a full remount: only this piece of state
+ * resets — DOM state (focus, scroll, uncontrolled inputs), refs, and effects
+ * are untouched. Reach for this first; remount only when you need everything
+ * gone.
+ *
+ * ```tsx
+ * function Comment({ postId }: { postId: string }) {
+ *   const [draft, setDraft] = useResettableState('', [postId])
+ *   // draft clears when the user navigates to another post
+ * }
+ * ```
+ *
+ * Reset happens purely during render (no effect, no flash of stale state),
+ * and the render in which deps change already sees the fresh value — so
+ * code after the hook never observes state that belongs to the old deps.
+ *
+ * `deps` follow {@link DepsList} comparison rules: `Object.is`, with plain
+ * objects and ordinary arrays compared one level deep. Dependencies must be
+ * able to compare equal across rerenders: nested literals or new class
+ * instances created on every render can cause a re-render loop. Keep those
+ * values in state or memoize them, and replace changed values rather than
+ * mutating them in place.
+ *
+ * @param initial The value, or a pure lazy initializer, used on mount and on
+ * each dependency change. Resets use the current render's `initial`; changing
+ * only this argument does not reset existing state. Wrap a function-valued
+ * initial state in an initializer, as with React's `useState`.
+ * @param deps Immutable watched values that determine when to reset. An empty
+ * list disables dependency-driven resets.
+ * @returns The current state and a stable setter accepting either the next
+ * value or a pure updater function. A dependency change returns fresh state
+ * in the same render, without remounting the component.
+ */
+export function useResettableState<T>(
+  initial: T | (() => T),
+  deps: DepsList
+): [T, Dispatch<SetStateAction<T>>] {
+  const [state, setState] = useState<{ deps: DepsList; value: T }>(() => ({
+    deps,
+    value: resolveInitial(initial),
+  }))
+
+  const setValue = useCallback<Dispatch<SetStateAction<T>>>((action) => {
+    setState((s) => ({
+      deps: s.deps,
+      value: typeof action === 'function' ? (action as (prev: T) => T)(s.value) : action,
+    }))
+  }, [])
+
+  if (!areDepsEqual(state.deps, deps)) {
+    const value = resolveInitial(initial)
+    setState({ deps, value })
+    return [value, setValue]
+  }
+
+  return [state.value, setValue]
+}

package/templates/ts/utils.ts

@@ -0,0 +1,109 @@
+// react-fresh-key v0.1.0 — vendored copy (TypeScript).
+// This file is yours now: edit it freely. Docs: https://www.npmjs.com/package/react-fresh-key
+/*!
+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.
+*/
+/**
+ * Watched values used by remount and state-reset APIs.
+ *
+ * List length and corresponding entries are compared. Entries use `Object.is`,
+ * except that plain objects and ordinary arrays compare one level deep using
+ * their own enumerable string and symbol properties; arrays also compare
+ * length. Equal content preserves state even when object identities differ.
+ * Nested objects, functions, Maps, Sets, Dates, and class instances (including
+ * array subclasses) compare by identity.
+ *
+ * Treat the list and its values as immutable. A new list is fine when its
+ * entries compare equal; values created anew on every render that cannot
+ * compare equal can cause hooks to hit React's re-render limit.
+ */
+export type DepsList = readonly unknown[]
+
+function isPlainObject(value: unknown): value is Record<PropertyKey, unknown> {
+  if (value === null || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+/** An `Array` proper — not a subclass, which is treated as a class instance. */
+function isOrdinaryArray(value: unknown): value is unknown[] {
+  return Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype
+}
+
+/** Own enumerable keys, including symbol keys (which `Object.keys` omits). */
+function ownEnumerableKeys(value: object): PropertyKey[] {
+  const keys: PropertyKey[] = Object.keys(value)
+  for (const sym of Object.getOwnPropertySymbols(value)) {
+    if (Object.prototype.propertyIsEnumerable.call(value, sym)) keys.push(sym)
+  }
+  return keys
+}
+
+/** Shallow-compare two objects: same own enumerable keys, `Object.is` per value. */
+export function shallowEqual(a: object, b: object): boolean {
+  if (Object.is(a, b)) return true
+  const keysA = ownEnumerableKeys(a)
+  const keysB = ownEnumerableKeys(b)
+  if (keysA.length !== keysB.length) return false
+  for (const key of keysA) {
+    if (
+      !Object.prototype.propertyIsEnumerable.call(b, key) ||
+      !Object.is((a as Record<PropertyKey, unknown>)[key], (b as Record<PropertyKey, unknown>)[key])
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Equality for a single watched value: `Object.is`, except that two *plain*
+ * objects (`{}` / `Object.create(null)`) or two ordinary arrays are compared
+ * one level deep — every own enumerable property, symbol keys included, plus
+ * array length. This lets the common inline-literal shapes converge —
+ * `useRemountKey([{ id }])`, `useRemountKeyWhen({ id, tab }, …)` — without
+ * hiding real changes. Anything else (class instances, including `Array`
+ * subclasses; Map/Set; Date; functions; nested objects' inner values) is
+ * compared by identity.
+ */
+export function isEqualDep(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (isOrdinaryArray(a) && isOrdinaryArray(b)) return a.length === b.length && shallowEqual(a, b)
+  if (isPlainObject(a) && isPlainObject(b)) return shallowEqual(a, b)
+  return false
+}
+
+/** Compare two dependency lists element-wise with {@link isEqualDep}. */
+export function areDepsEqual(a: DepsList, b: DepsList): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (!isEqualDep(a[i], b[i])) return false
+  }
+  return true
+}
+
+/** Normalize a selector result into a deps list. */
+export function toDeps(value: unknown): DepsList {
+  return Array.isArray(value) ? value : [value]
+}

package/templates/ts/withRemount.tsx

@@ -0,0 +1,281 @@
+// react-fresh-key v0.1.0 — vendored copy (TypeScript).
+// This file is yours now: edit it freely. Docs: https://www.npmjs.com/package/react-fresh-key
+/*!
+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.
+*/
+import {
+  forwardRef,
+  useState,
+  type ComponentProps,
+  type ComponentPropsWithRef,
+  type ComponentType,
+  type ForwardRefExoticComponent,
+  type JSX,
+  type LazyExoticComponent,
+  type MemoExoticComponent,
+} from 'react'
+import { areDepsEqual, shallowEqual, toDeps, type DepsList } from './utils'
+
+/**
+ * What to watch for remounting:
+ *
+ * - `['userId', 'mode']` — prop names; remount when any of them changes.
+ * - `(props) => props.user.id` — selector; remount when the returned value
+ *   (or any element, if it returns an array) changes. Same as `{ select }`.
+ * - `{ select: (props) => value | deps[] }` — explicit selector form.
+ * - `{ when: (prev, next) => boolean }` — predicate over previous/next props;
+ *   remount when it returns `true`.
+ *
+ * Predicates are always explicit (`{ when }`). A bare function is always a
+ * selector — there is no arity-based guessing.
+ *
+ * Selected values use `Object.is`, except plain objects and ordinary arrays
+ * are compared one level deep. Selectors and predicates run during render:
+ * keep them pure, because React may evaluate them more than once.
+ *
+ * Declared `defaultProps` are applied before callbacks, including through
+ * `memo`. Inner defaults behind `lazy` and JavaScript parameter defaults
+ * cannot be resolved by the wrapper; handle any optional props accordingly.
+ */
+export type WatchSpec<P extends object> =
+  | ReadonlyArray<keyof P>
+  | ((props: P) => unknown)
+  | {
+      /**
+       * Pure selector of the incoming props. Return one watched value or an
+       * array of dependencies; remount when any selected dependency changes.
+       *
+       * @param props Incoming props with available `defaultProps` applied.
+       */
+      select: (props: P) => unknown
+    }
+  | {
+      /**
+       * Pure predicate called when props differ shallowly (`Object.is` per
+       * prop). Return `true` to remount. The snapshot advances on a detected
+       * change even when this returns `false`.
+       *
+       * @param prev Previous tracked props, not necessarily those at the last remount.
+       * @param next Incoming props. Available `defaultProps` are applied to both arguments.
+       */
+      when: (prev: P, next: P) => boolean
+    }
+
+/**
+ * `true` when `C` is a `lazy` component, possibly wrapped in any number of
+ * `memo` layers. Mirrors the runtime `unwrapMemo`, which also looks through
+ * every memo layer and then stops at a lazy object it cannot open.
+ */
+type ContainsLazy<C> =
+  C extends LazyExoticComponent<infer _Component>
+    ? true
+    : C extends MemoExoticComponent<infer T>
+      ? ContainsLazy<T>
+      : false
+
+/**
+ * The props the wrapper accepts: whatever React's JSX checker would accept
+ * for the original component (so props covered by `defaultProps` stay
+ * optional — through `memo` too), with the ref type inferred from the
+ * original.
+ *
+ * `lazy` is the one exception, at any depth of `memo` nesting: its inner
+ * component's defaults are unknowable until the module loads, so the wrapper
+ * requires those props as declared. That keeps the types truthful about what
+ * selectors and predicates receive.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: This component constraint accepts required props; the concrete C preserves their types.
+export type RemountedProps<C extends ComponentType<any>> =
+  ContainsLazy<C> extends true
+    ? ComponentPropsWithRef<C>
+    : JSX.LibraryManagedAttributes<C, ComponentPropsWithRef<C>>
+
+type NormalizedWatch<P extends object> =
+  | { mode: 'select'; select: (props: P) => DepsList }
+  | { mode: 'when'; when: (prev: P, next: P) => boolean }
+
+function normalizeWatch<P extends object>(watch: WatchSpec<P>): NormalizedWatch<P> {
+  if (Array.isArray(watch)) {
+    const names = watch as ReadonlyArray<keyof P>
+    return { mode: 'select', select: (props) => names.map((n) => props[n]) }
+  }
+  if (typeof watch === 'function') {
+    if (watch.length >= 2) {
+      throw new Error(
+        'react-fresh-key: a bare function passed to withRemount is a selector `(props) => value`. ' +
+          'For a predicate `(prev, next) => boolean`, pass `{ when: fn }` instead.'
+      )
+    }
+    const select = watch as (props: P) => unknown
+    return { mode: 'select', select: (props) => toDeps(select(props)) }
+  }
+  if (watch && typeof watch === 'object') {
+    if ('select' in watch && typeof watch.select === 'function') {
+      const select = watch.select
+      return { mode: 'select', select: (props) => toDeps(select(props)) }
+    }
+    if ('when' in watch && typeof watch.when === 'function') {
+      return { mode: 'when', when: watch.when }
+    }
+  }
+  throw new Error(
+    'react-fresh-key: invalid watch spec. Expected a prop-name array, a selector function, { select }, or { when }.'
+  )
+}
+
+const REACT_MEMO_TYPE = Symbol.for('react.memo')
+
+/**
+ * `memo(C)` is an object `{ $$typeof, type: C }`; React applies the *inner*
+ * component's `defaultProps` when it renders, and `JSX.LibraryManagedAttributes`
+ * unwraps `memo` the same way. Mirror both so types and runtime agree.
+ * (`lazy` cannot be unwrapped before it loads; see {@link RemountedProps}.)
+ */
+function unwrapMemo(Component: unknown): unknown {
+  let current = Component
+  while (
+    current !== null &&
+    typeof current === 'object' &&
+    (current as { $$typeof?: unknown }).$$typeof === REACT_MEMO_TYPE
+  ) {
+    current = (current as { type: unknown }).type
+  }
+  return current
+}
+
+/**
+ * Apply `defaultProps` the way React does (a default fills in only when the
+ * prop is `undefined`). Returns the same object when nothing needs filling.
+ */
+function makeDefaultsResolver<P extends object>(Component: unknown): (props: P) => P {
+  const defaults = (unwrapMemo(Component) as { defaultProps?: Record<string, unknown> } | null)
+    ?.defaultProps
+  if (!defaults) return (props) => props
+  const keys = Object.keys(defaults)
+  return (props) => {
+    let resolved: Record<string, unknown> | null = null
+    for (const key of keys) {
+      if ((props as Record<string, unknown>)[key] === undefined) {
+        resolved ??= { ...(props as Record<string, unknown>) }
+        resolved[key] = defaults[key]
+      }
+    }
+    return (resolved ?? props) as P
+  }
+}
+
+interface WatchState<P> {
+  /** The raw props object the current snapshot was taken from (the anchor). */
+  props: P
+  /** Selected deps (select mode only). */
+  deps: DepsList | null
+  key: number
+}
+
+/**
+ * Single-useState implementation so the hook order is identical for both
+ * modes, with the raw `props` object as the convergence anchor: after a
+ * render-phase setState, React re-invokes the component with the *same*
+ * props object, so the comparison branch is skipped on that second pass.
+ * That makes the derivation converge even when a selector returns a fresh
+ * object on every call (it remounts once per props change instead of looping).
+ */
+function useWatchKey<P extends object>(
+  props: P,
+  spec: NormalizedWatch<P>,
+  resolve: (props: P) => P
+): number {
+  const [state, setState] = useState<WatchState<P>>(() => ({
+    props,
+    deps: spec.mode === 'select' ? spec.select(resolve(props)) : null,
+    key: 0,
+  }))
+
+  if (state.props !== props) {
+    if (spec.mode === 'select') {
+      const deps = spec.select(resolve(props))
+      if (!areDepsEqual(state.deps as DepsList, deps)) {
+        const key = state.key + 1
+        setState({ props, deps, key })
+        return key
+      }
+      // Unchanged: leave the snapshot alone (no extra render pass).
+    } else if (!shallowEqual(state.props, props)) {
+      // Only consult the predicate when props actually changed (shallow),
+      // so parent re-renders with identical props stay single-pass.
+      const key = spec.when(resolve(state.props), resolve(props)) ? state.key + 1 : state.key
+      setState({ props, deps: null, key })
+      return key
+    }
+  }
+
+  return state.key
+}
+
+/**
+ * Wrap a component with a remount policy declared *at the definition site*,
+ * so call sites don't need to know which props warrant a fresh mount:
+ *
+ * ```tsx
+ * // Profile.tsx
+ * function Profile({ userId }: ProfileProps) { ... }
+ * export default withRemount(Profile, ['userId'])
+ *
+ * // Anywhere else — no key juggling required:
+ * <Profile userId={id} />
+ * ```
+ *
+ * Parents can still override identity the normal way with their own `key`.
+ * Refs are forwarded, and the ref type is inferred from the wrapped
+ * component (a `forwardRef<HTMLInputElement, …>` component yields a wrapper
+ * that accepts `Ref<HTMLInputElement>` and nothing else). Props covered by
+ * `defaultProps` stay optional, except behind `lazy`; see {@link RemountedProps}.
+ *
+ * Call this once outside rendering. Creating a wrapper during render creates
+ * a new component type each time and discards its state. Selectors and
+ * predicates must be pure; they run during render and may be evaluated again.
+ *
+ * @param Component Component whose entire subtree remounts when the rule matches.
+ * @param watch Prop names, a selector, `{ select }`, or `{ when }`; see {@link WatchSpec}.
+ * @returns A component accepting the original props and supported ref type.
+ * @throws If the watch specification is invalid; pass predicates as `{ when }`.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: This component constraint accepts required props; the concrete C preserves their types.
+export function withRemount<C extends ComponentType<any>>(
+  Component: C,
+  watch: WatchSpec<ComponentProps<C>>
+): ForwardRefExoticComponent<RemountedProps<C>> {
+  const spec = normalizeWatch(watch)
+  const resolve = makeDefaultsResolver<ComponentProps<C>>(Component)
+  const Inner = Component as ComponentType<ComponentProps<C>>
+
+  const Wrapped = forwardRef<unknown, ComponentProps<C>>((props, ref) => {
+    const key = useWatchKey(props as ComponentProps<C>, spec, resolve)
+    return <Inner key={key} ref={ref} {...(props as ComponentProps<C>)} />
+  })
+
+  const name = Component.displayName ?? Component.name ?? 'Component'
+  Wrapped.displayName = `withRemount(${name})`
+
+  return Wrapped as unknown as ForwardRefExoticComponent<RemountedProps<C>>
+}