state-in-url 6.5.0 → 8.0.0

package/README.es.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · Español · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=es source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=es source=README.md source-blob=8b11ee8f8c8b83c207a940455766e24376508130 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -138,6 +138,7 @@ La comparación completa — la misma feature en ambas, otras alternativas (TanS
   - [Instalación](#instalación)
     - [1. Instalar el paquete](#1-instalar-el-paquete)
     - [2. Editar tsconfig.json](#2-editar-tsconfigjson)
+    - [3. Nota: este paquete se resuelve solo como ESM](#3-nota-este-paquete-se-resuelve-solo-como-esm)
   - [Uso con agentes de codificación con IA](#uso-con-agentes-de-codificación-con-ia)
   - [useUrlState](#useurlstate)
     - [Hook useUrlState para Next.js](#hook-useurlstate-para-nextjs)
@@ -150,14 +151,16 @@ La comparación completa — la misma feature en ambas, otras alternativas (TanS
       - [Ejemplo](#ejemplo)
     - [Hook useUrlState para React-Router](#hook-useurlstate-para-react-router)
       - [Ejemplo](#ejemplo-1)
-    - [Hook useUrlState para Astro](#hook-useurlstate-para-astro)
+    - [Hook useUrlState para React (sin router)](#hook-useurlstate-para-react-sin-router)
       - [Ejemplo](#ejemplo-2)
+    - [Hook useUrlState para Astro](#hook-useurlstate-para-astro)
+      - [Ejemplo](#ejemplo-3)
   - [Recetas](#recetas)
         - [Hook personalizado para trabajar cómodamente con una porción del estado](#hook-personalizado-para-trabajar-cómodamente-con-una-porción-del-estado)
         - [Con una forma de estado compleja](#con-una-forma-de-estado-compleja)
         - [Actualizar solo el estado y sincronizarlo manualmente con la URL](#actualizar-solo-el-estado-y-sincronizarlo-manualmente-con-la-url)
   - [Otros hooks y helpers](#otros-hooks-y-helpers)
-    - [Hook `useUrlStateBase` para otros routers](#hook-useurlstatebase-para-otros-routers)
+    - [Hook `useUrlStateBase` para otro router](#hook-useurlstatebase-para-otro-router)
     - [Hook `useSharedState` para React.js](#hook-usesharedstate-para-reactjs)
     - [Hook `useLinkProps` para React.js](#hook-uselinkprops-para-reactjs)
     - [Hook `useUrlEncode` para React.js](#hook-useurlencode-para-reactjs)
@@ -195,6 +198,20 @@ pnpm add state-in-url
 En `tsconfig.json`, en `compilerOptions`, establece `"moduleResolution": "Bundler"`, o `"moduleResolution": "Node16"`, o `"moduleResolution": "NodeNext"`.
 Posiblemente necesites establecer `"module": "ES2022"`, o `"module": "ESNext"`
 
+### 3. Nota: este paquete se resuelve solo como ESM
+
+Next.js, Vite, Astro y Remix lo empaquetan sin ninguna configuración, y
+`require()` desde Node puro funciona en Node `^20.19` o `>=22.12`, donde
+`require(esm)` no necesita flag.
+
+En `dist/` también se publica una compilación CommonJS con extensión `.cjs`, pero
+el mapa `exports` no apunta a ella, así que ninguna resolución llega allí por
+accidente. Está para los casos límite — Node antiguo, o Jest sin flag — y solo se
+alcanza mediante una ruta explícita.
+
+**En cualquiera de los dos casos Jest necesita una línea de configuración** —
+consulta el punto 5 de [Trampas](#trampas).
+
 ## Uso con agentes de codificación con IA
 
 `state-in-url` incluye archivos de habilidades (skills) para [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview), de modo que los agentes de IA (Claude Code, Cursor, Copilot, Codex, etc.) carguen los patrones correctos y eviten errores comunes al usar la biblioteca. Tras instalar `state-in-url`, ejecuta una vez en tu proyecto:
@@ -540,6 +557,39 @@ const tags = [
 
 [Ejemplo de código](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState para React (sin router)
+
+Para una aplicación React sin router: Vite, Create React App, o un widget que se monta en una página que no controlas. El hook escribe la URL con `window.history` y la vuelve a leer al navegar atrás y adelante y ante cualquier otro `pushState`/`replaceState`. Todos los componentes que usan el mismo objeto de estado lo comparten, sin nada que envolver y sin nada que pasar por props.
+
+[Documentación de la API](packages/urlstate/react/useUrlState)
+
+#### Ejemplo
+
+```typescript
+// useFilters.ts
+import { useUrlState } from 'state-in-url/react';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  return useUrlState(FILTERS_STATE);
+}
+```
+
+```typescript
+// FiltersBar.tsx
+import { useFilters } from './useFilters';
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useFilters();
+
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Page {urlState.page}</button>;
+}
+```
+
+`state-in-url/astro` es este mismo hook; se documenta aparte más abajo porque las islands además reciben `searchParams` como prop.
+
 ### Hook useUrlState para Astro
 
 Para islas de React. Astro no tiene router del lado del cliente por defecto, así que el hook escribe la URL con `window.history` y la vuelve a leer al navegar atrás/adelante y en cualquier otro `pushState`/`replaceState`, incluido el propio `<ClientRouter />` de Astro. Las islas de una página comparten el estado, sin nada que las envuelva.
@@ -818,9 +868,39 @@ Sincronizar el estado en `onBlur` estará más alineado con el uso en el mundo r
 
 ## Otros hooks y helpers
 
-### Hook `useUrlStateBase` para otros routers
+### Hook `useUrlStateBase` para otro router
+
+Úsalo para construir tu propio `useUrlState` para un router del que este paquete no publica un punto de entrada, por ejemplo TanStack Router. Pasa cualquier objeto memoizado con `push(url)` y `replace(url)`.
+
+Si **no hay router alguno** no lo necesitas: usa [`state-in-url/react`](#hook-useurlstate-para-react-sin-router), que es este mismo hook ya conectado a `window.history`.
+
+```typescript
+import { useUrlStateBase } from 'state-in-url/useUrlStateBase';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  const router = useYourRouter();
+  const nav = React.useMemo(
+    () => ({
+      push: (url: string) => router.navigate(url),
+      replace: (url: string) => router.navigate(url, { replace: true }),
+    }),
+    [router],
+  );
+
+  return useUrlStateBase(FILTERS_STATE, nav, ({ parse }) => parse(window.location.search));
+}
+```
+
+Dos diferencias respecto a `useUrlState`:
+
+- Devuelve `state`, `updateUrl` y `updateState`, no `urlState`, `setUrl` ni `setState`; además `updateUrl` hace push por defecto, mientras que `setUrl` hace replace.
+- El tercer argumento define el state inicial. Si lo omites, el hook ignora la cadena de consulta con la que se cargó la página, así que un enlace compartido se abre con los valores por defecto.
 
-Hooks para crear tus propios hooks `useUrlState` con otros routers, p. ej. react-router o tanstack router.
+> [!NOTE]
+> `useUrlState` ya no se exporta desde la raíz del paquete: cada uno está atado a un framework, así que cada uno vive en su propio punto de entrada (`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`). La raíz solo conserva lo que es independiente del framework: `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode` y `encodeState`/`decodeState`.
 
 [Documentación de la API](packages/urlstate/useUrlStateBase)
 
@@ -917,6 +997,41 @@ export const useUserState = () => {
 2. Los servidores de Vercel limitan el tamaño de las cabeceras (la cadena de consulta y demás) a **14KB**, así que mantén el estado de tu URL por debajo de ~5000 palabras. <https://vercel.com/docs/errors/URL_TOO_LONG>
 3. Probado con `next.js` 14/15/16 con app router; no hay planes de soportar pages.
 
+4. **Vitest + react-router 7**: si una prueba que renderiza un componente dentro de `<BrowserRouter>` lanza `useNavigate() may be used only in the context of a <Router> component` con el provider justo ahí, actualiza a `react-router@8` o incorpora este paquete en línea:
+
+   ```ts
+   // vitest.config.ts
+   test: { server: { deps: { inline: ['state-in-url'] } } }
+   ```
+
+   Vitest externaliza `node_modules`, así que Node carga `state-in-url` mientras Vite carga tu archivo de prueba. En `react-router@7` la condición de exportación `node` apunta `module`/`module-sync` a `index.mjs` y `default` a `index.js`, y los dos resolutores eligen distinto: react-router se carga dos veces, su contexto de React existe por duplicado y el provider escribe en la copia que el hook no lee. Incorporarlo en línea pone ambos lados en el resolutor de Vite.
+
+   `react-router@8` apunta `default` y `module-sync` al mismo archivo, de modo que ningún resolutor puede discrepar y no hace falta nada. El error nunca menciona `state-in-url`, por eso esto está aquí.
+
+5. **Jest**: este paquete se resuelve solo como ESM y Jest ejecuta las pruebas como CommonJS por defecto, así que un `require()` simple falla con `Must use import to load ES Module`. Jest no hereda el `require(esm)` sin flag de Node — usa su propia API síncrona `vm` —, así que en **Node 24.9+** pásale el flag:
+
+   ```json
+   // package.json
+   "scripts": { "test": "NODE_OPTIONS=--experimental-vm-modules jest" }
+   ```
+
+   Si prefieres no pasar un flag, `dist/` también incluye una compilación CommonJS. Está deliberadamente fuera del mapa `exports`, así que nada se resuelve a ella por accidente: apunta Jest a ella de forma explícita:
+
+   ```js
+   // jest.config.js
+   moduleNameMapper: {
+     '^state-in-url$': '<rootDir>/node_modules/state-in-url/dist/index.cjs',
+     '^state-in-url/utils$': '<rootDir>/node_modules/state-in-url/dist/utils.cjs',
+     '^state-in-url/(.*)$': '<rootDir>/node_modules/state-in-url/dist/$1/index.cjs',
+   },
+   ```
+
+   Eso sustituye la compilación por la de CJS en todo el proceso de pruebas, y es seguro. No mezcles las dos en un mismo proceso: este paquete guarda su almacén de estado compartido en el ámbito del módulo, así que dos copias significan dos almacenes y `useSharedState` deja de compartir sin avisar.
+
+   Una diferencia más: `jest.mock()` no se aplica a los módulos ES. Usa `jest.unstable_mockModule()` si haces mock de este paquete.
+
+   Vitest, Next.js, Vite, Astro y Remix no necesitan nada de esta configuración de Jest. El único paso adicional de Vitest es el `server.deps.inline` de arriba, y solo con `react-router@7`.
+
 ## Otros
 
 ### Contribuir y/o ejecutar localmente

package/README.fr.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md) · [Português (BR)](./README.pt-BR.md) · Français · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=fr source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=fr source=README.md source-blob=8b11ee8f8c8b83c207a940455766e24376508130 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -138,6 +138,7 @@ La comparaison complète — la même fonctionnalité dans les deux, d’autres
   - [Installation](#installation)
     - [1. Installer le paquet](#1-installer-le-paquet)
     - [2. Modifier tsconfig.json](#2-modifier-tsconfigjson)
+    - [3. Remarque : ce paquet ne se résout qu'en ESM](#3-remarque--ce-paquet-ne-se-résout-quen-esm)
   - [Utilisation avec des agents de codage IA](#utilisation-avec-des-agents-de-codage-ia)
   - [useUrlState](#useurlstate)
     - [Hook useUrlState pour Next.js](#hook-useurlstate-pour-nextjs)
@@ -150,14 +151,16 @@ La comparaison complète — la même fonctionnalité dans les deux, d’autres
       - [Exemple](#exemple)
     - [Hook useUrlState pour React-Router](#hook-useurlstate-pour-react-router)
       - [Exemple](#exemple-1)
-    - [Hook useUrlState pour Astro](#hook-useurlstate-pour-astro)
+    - [Hook useUrlState pour React (sans routeur)](#hook-useurlstate-pour-react-sans-routeur)
       - [Exemple](#exemple-2)
+    - [Hook useUrlState pour Astro](#hook-useurlstate-pour-astro)
+      - [Exemple](#exemple-3)
   - [Recettes](#recettes)
         - [Hook personnalisé pour travailler confortablement avec une tranche d'état](#hook-personnalisé-pour-travailler-confortablement-avec-une-tranche-détat)
         - [Avec une forme d'état complexe](#avec-une-forme-détat-complexe)
         - [Mettre à jour l'état seul et le synchroniser manuellement avec l'URL](#mettre-à-jour-létat-seul-et-le-synchroniser-manuellement-avec-lurl)
   - [Autres hooks et helpers](#autres-hooks-et-helpers)
-    - [Hook `useUrlStateBase` pour d'autres routeurs](#hook-useurlstatebase-pour-dautres-routeurs)
+    - [Hook `useUrlStateBase` pour un autre routeur](#hook-useurlstatebase-pour-un-autre-routeur)
     - [Hook `useSharedState` pour React.js](#hook-usesharedstate-pour-reactjs)
     - [Hook `useLinkProps` pour React.js](#hook-uselinkprops-pour-reactjs)
     - [Hook `useUrlEncode` pour React.js](#hook-useurlencode-pour-reactjs)
@@ -195,6 +198,20 @@ pnpm add state-in-url
 Dans `tsconfig.json`, dans `compilerOptions`, définissez `"moduleResolution": "Bundler"`, ou `"moduleResolution": "Node16"`, ou `"moduleResolution": "NodeNext"`.
 Il peut être nécessaire de définir `"module": "ES2022"`, ou `"module": "ESNext"`
 
+### 3. Remarque : ce paquet ne se résout qu'en ESM
+
+Next.js, Vite, Astro et Remix l'empaquettent sans aucune configuration, et
+`require()` depuis Node seul fonctionne sur Node `^20.19` ou `>=22.12`, où
+`require(esm)` ne demande pas de drapeau.
+
+Une build CommonJS est également publiée dans `dist/` avec l'extension `.cjs`,
+mais la table `exports` ne pointe pas dessus : aucune résolution n'y aboutit par
+accident. Elle existe pour les cas limites — un Node ancien, ou Jest sans
+drapeau — et on ne l'atteint que par un chemin explicite.
+
+**Dans les deux cas, Jest demande une ligne de configuration** — voir le point 5
+des [Pièges](#pièges).
+
 ## Utilisation avec des agents de codage IA
 
 `state-in-url` fournit des fichiers de compétences (skills) pour [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview), afin que les agents IA (Claude Code, Cursor, Copilot, Codex, etc.) chargent les bons modèles et évitent les erreurs courantes lors de l'utilisation de la bibliothèque. Après avoir installé `state-in-url`, exécutez une fois dans votre projet :
@@ -540,6 +557,39 @@ const tags = [
 
 [Exemple de code](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState pour React (sans routeur)
+
+Pour une application React sans routeur : Vite, Create React App, ou un widget monté dans une page que vous ne contrôlez pas. Le hook écrit l'URL via `window.history` et la relit lors des retours et avances dans l'historique ainsi qu'à chaque autre `pushState`/`replaceState`. Tous les composants qui utilisent le même objet d'état le partagent, sans rien à englober ni rien à faire transiter par les props.
+
+[Documentation de l'API](packages/urlstate/react/useUrlState)
+
+#### Exemple
+
+```typescript
+// useFilters.ts
+import { useUrlState } from 'state-in-url/react';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  return useUrlState(FILTERS_STATE);
+}
+```
+
+```typescript
+// FiltersBar.tsx
+import { useFilters } from './useFilters';
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useFilters();
+
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Page {urlState.page}</button>;
+}
+```
+
+`state-in-url/astro` est ce même hook ; il est documenté séparément plus bas parce que les îlots reçoivent en plus `searchParams` sous forme de prop.
+
 ### Hook useUrlState pour Astro
 
 Pour les îlots React. Astro n'a pas de routeur côté client par défaut, donc le hook écrit l'URL avec `window.history` et la relit lors des navigations précédent/suivant et lors de tout autre `pushState`/`replaceState`, y compris le `<ClientRouter />` d'Astro. Les îlots d'une page partagent l'état, sans avoir à les envelopper dans quoi que ce soit.
@@ -818,9 +868,39 @@ Synchroniser l'état sur `onBlur` sera plus conforme à l'usage réel.
 
 ## Autres hooks et helpers
 
-### Hook `useUrlStateBase` pour d'autres routeurs
+### Hook `useUrlStateBase` pour un autre routeur
+
+Utilisez-le pour construire votre propre `useUrlState` destiné à un routeur pour lequel ce paquet ne publie pas de point d'entrée, par exemple TanStack Router. Passez n'importe quel objet mémoïsé possédant `push(url)` et `replace(url)`.
+
+S'il n'y a **aucun routeur**, vous n'en avez pas besoin : utilisez [`state-in-url/react`](#hook-useurlstate-pour-react-sans-routeur), qui est ce même hook déjà relié à `window.history`.
+
+```typescript
+import { useUrlStateBase } from 'state-in-url/useUrlStateBase';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  const router = useYourRouter();
+  const nav = React.useMemo(
+    () => ({
+      push: (url: string) => router.navigate(url),
+      replace: (url: string) => router.navigate(url, { replace: true }),
+    }),
+    [router],
+  );
+
+  return useUrlStateBase(FILTERS_STATE, nav, ({ parse }) => parse(window.location.search));
+}
+```
+
+Deux différences avec `useUrlState` :
+
+- Il renvoie `state`, `updateUrl`, `updateState`, et non `urlState`, `setUrl`, `setState` ; de plus `updateUrl` fait un push par défaut, là où `setUrl` fait un replace.
+- Le troisième argument fournit le state initial. Si vous l'omettez, le hook ignore la chaîne de requête avec laquelle la page a été chargée, et un lien partagé s'ouvre donc sur les valeurs par défaut.
 
-Hooks pour créer vos propres hooks `useUrlState` avec d'autres routeurs, par exemple react-router ou tanstack router.
+> [!NOTE]
+> `useUrlState` n'est plus exporté depuis la racine du paquet : chacun est lié à un framework, et chacun vit donc derrière son propre point d'entrée (`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`). La racine ne conserve que ce qui est indépendant du framework : `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode` et `encodeState`/`decodeState`.
 
 [Documentation de l'API](packages/urlstate/useUrlStateBase)
 
@@ -917,6 +997,41 @@ export const useUserState = () => {
 2. Les serveurs Vercel limitent la taille des en-têtes (chaîne de requête et autres) à **14KB**, gardez donc l'état de votre URL sous ~5000 mots. <https://vercel.com/docs/errors/URL_TOO_LONG>
 3. Testé avec `next.js` 14/15/16 avec app router ; pas de plan pour prendre en charge pages.
 
+4. **Vitest + react-router 7** : si un test qui rend un composant à l'intérieur de `<BrowserRouter>` lève `useNavigate() may be used only in the context of a <Router> component` alors que le provider est juste là, passez à `react-router@8` ou intégrez ce paquet en ligne :
+
+   ```ts
+   // vitest.config.ts
+   test: { server: { deps: { inline: ['state-in-url'] } } }
+   ```
+
+   Vitest externalise `node_modules`, donc Node charge `state-in-url` tandis que Vite charge votre fichier de test. Dans `react-router@7`, la condition d'export `node` pointe `module`/`module-sync` vers `index.mjs` et `default` vers `index.js`, et les deux résolveurs n'en choisissent pas le même : react-router est chargé deux fois, son contexte React existe en double, et le provider écrit dans la copie que le hook ne lit pas. L'intégration en ligne place les deux côtés sur le résolveur de Vite.
+
+   `react-router@8` pointe `default` et `module-sync` vers le même fichier : aucun résolveur ne peut diverger et rien n'est nécessaire. L'erreur ne nomme jamais `state-in-url`, d'où la présence de ce point ici.
+
+5. **Jest** : ce paquet ne se résout qu'en ESM, et Jest exécute les tests en CommonJS par défaut ; un simple `require()` échoue donc avec `Must use import to load ES Module`. Jest n'hérite pas du `require(esm)` sans drapeau de Node — il utilise sa propre API synchrone `vm` — donc sur **Node 24.9+**, passez-lui le drapeau :
+
+   ```json
+   // package.json
+   "scripts": { "test": "NODE_OPTIONS=--experimental-vm-modules jest" }
+   ```
+
+   Si vous préférez éviter le drapeau, `dist/` contient aussi une build CommonJS. Elle est délibérément absente de la table `exports`, si bien que rien ne s'y résout par accident : pointez Jest dessus explicitement :
+
+   ```js
+   // jest.config.js
+   moduleNameMapper: {
+     '^state-in-url$': '<rootDir>/node_modules/state-in-url/dist/index.cjs',
+     '^state-in-url/utils$': '<rootDir>/node_modules/state-in-url/dist/utils.cjs',
+     '^state-in-url/(.*)$': '<rootDir>/node_modules/state-in-url/dist/$1/index.cjs',
+   },
+   ```
+
+   Cela substitue la build CJS pour tout le processus de test, et c'est sans danger. Ne mélangez pas les deux dans un même processus : ce paquet garde son magasin d'état partagé dans la portée du module, donc deux copies signifient deux magasins et `useSharedState` cesse de partager sans rien signaler.
+
+   Autre différence : `jest.mock()` ne s'applique pas aux modules ES. Utilisez `jest.unstable_mockModule()` si vous mockez ce paquet.
+
+   Vitest, Next.js, Vite, Astro et Remix n'ont besoin de rien de cette configuration Jest. La seule étape supplémentaire pour Vitest est le `server.deps.inline` ci-dessus, et uniquement avec `react-router@7`.
+
 ## Autres
 
 ### Contribuer et/ou exécuter localement

package/README.ja.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · 日本語 · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md) · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=ja source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=ja source=README.md source-blob=8b11ee8f8c8b83c207a940455766e24376508130 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -138,6 +138,7 @@ nuqs も優れたライブラリです。値ごとに読みやすいクエリパ
   - [インストール](#インストール)
     - [1. パッケージのインストール](#1-パッケージのインストール)
     - [2. tsconfig.json の編集](#2-tsconfigjson-の編集)
+    - [3. 補足: このパッケージは ESM としてのみ解決されます](#3-補足-このパッケージは-esm-としてのみ解決されます)
   - [AI コーディングエージェントと使う](#ai-コーディングエージェントと使う)
   - [useUrlState](#useurlstate)
     - [Next.js 向け useUrlState フック](#nextjs-向け-useurlstate-フック)
@@ -150,8 +151,10 @@ nuqs も優れたライブラリです。値ごとに読みやすいクエリパ
       - [例](#例)
     - [React-Router 向け useUrlState フック](#react-router-向け-useurlstate-フック)
       - [例](#例-1)
-    - [Astro 向け useUrlState フック](#astro-向け-useurlstate-フック)
+    - [React 向け useUrlState フック（ルーターなし）](#react-向け-useurlstate-フックルーターなし)
       - [例](#例-2)
+    - [Astro 向け useUrlState フック](#astro-向け-useurlstate-フック)
+      - [例](#例-3)
   - [レシピ](#レシピ)
         - [状態の一部を便利に扱うカスタムフック](#状態の一部を便利に扱うカスタムフック)
         - [複雑な状態の形を使用](#複雑な状態の形を使用)
@@ -195,6 +198,19 @@ pnpm add state-in-url
 `tsconfig.json` の `compilerOptions` に `"moduleResolution": "Bundler"`、または `"moduleResolution": "Node16"`、または `"moduleResolution": "NodeNext"` を設定します。
 `"module": "ES2022"` または `"module": "ESNext"` の設定が必要になる場合があります。
 
+### 3. 補足: このパッケージは ESM としてのみ解決されます
+
+Next.js、Vite、Astro、Remix は設定なしでバンドルできます。また `require(esm)` が
+フラグなしで使える Node `^20.19` または `>=22.12` であれば、素の Node からの
+`require()` も動作します。
+
+`dist/` には `.cjs` という拡張子で CommonJS ビルドも同梱されていますが、`exports`
+マップはそれを指していないため、解決が偶然そちらへ向かうことはありません。これは
+例外的なケース——古い Node、あるいはフラグなしの Jest——のためのもので、明示的な
+パスでのみ参照できます。
+
+**どちらの場合も Jest には 1 行の設定が必要です**——[注意点](#注意点)の 5 番を参照してください。
+
 ## AI コーディングエージェントと使う
 
 `state-in-url` は [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview) 向けのスキルファイルを同梱しています。AI エージェント(Claude Code、Cursor、Copilot、Codex など)がライブラリ使用時の正しいパターンを読み込み、よくあるミスを避けられます。`state-in-url` をインストールした後、プロジェクトで一度実行してください:
@@ -540,6 +556,39 @@ const tags = [
 
 [サンプルコード](packages/example-react-router6/src/Form-for-test.tsx)
 
+### React 向け useUrlState フック（ルーターなし）
+
+ルーターを持たない React アプリ向けです。Vite、Create React App、あるいは自分では管理できないページに埋め込むウィジェットなどが対象です。このフックは `window.history` で URL を書き込み、戻る/進むや他の `pushState`/`replaceState` のたびに読み戻します。同じ state オブジェクトを使うコンポーネントはすべて状態を共有するため、ラップするものも props で渡すものもありません。
+
+[API ドキュメント](packages/urlstate/react/useUrlState)
+
+#### 例
+
+```typescript
+// useFilters.ts
+import { useUrlState } from 'state-in-url/react';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  return useUrlState(FILTERS_STATE);
+}
+```
+
+```typescript
+// FiltersBar.tsx
+import { useFilters } from './useFilters';
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useFilters();
+
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Page {urlState.page}</button>;
+}
+```
+
+`state-in-url/astro` は同じフックです。islands では `searchParams` を prop として受け取るため、下で別に説明しています。
+
 ### Astro 向け useUrlState フック
 
 React アイランド向けです。Astro にはデフォルトでクライアントサイドルーターがないため、このフックは `window.history` で URL を書き込み、戻る/進む操作時およびその他あらゆる `pushState`/`replaceState` の際（Astro 自身の `<ClientRouter />` を含む）に URL を読み戻します。ページ上のアイランドは状態を共有し、それらをラップするものは何も必要ありません。
@@ -820,7 +869,37 @@ const tags = [
 
 ### 他のルーター向け `useUrlStateBase` フック
 
-react-router や tanstack router など、他のルーターで独自の `useUrlState` フックを作成するためのフックです。
+本パッケージがエントリーポイントを用意していないルーター（例: TanStack Router）向けに、自前の `useUrlState` を作るために使います。`push(url)` と `replace(url)` を持つメモ化されたオブジェクトを渡してください。
+
+ルーターが**まったくない**場合は不要です。[`state-in-url/react`](#react-向け-useurlstate-フックルーターなし) を使ってください。こちらは同じフックを `window.history` に接続済みのものです。
+
+```typescript
+import { useUrlStateBase } from 'state-in-url/useUrlStateBase';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  const router = useYourRouter();
+  const nav = React.useMemo(
+    () => ({
+      push: (url: string) => router.navigate(url),
+      replace: (url: string) => router.navigate(url, { replace: true }),
+    }),
+    [router],
+  );
+
+  return useUrlStateBase(FILTERS_STATE, nav, ({ parse }) => parse(window.location.search));
+}
+```
+
+`useUrlState` との違いは 2 点です:
+
+- 返すのは `urlState`、`setUrl`、`setState` ではなく `state`、`updateUrl`、`updateState` です。また `updateUrl` の既定は push で、`setUrl` の既定は replace です。
+- 第 3 引数が初期 state を決めます。省略するとフックは読み込み時のクエリ文字列を無視するため、共有されたリンクを開いても既定値が表示されます。
+
+> [!NOTE]
+> `useUrlState` はパッケージのルートからはエクスポートされません。どの `useUrlState` もフレームワークに結び付いているため、それぞれ専用のエントリーポイント（`state-in-url/next`、`/react`、`/react-router`、`/react-router6`、`/remix`、`/astro`）にあります。ルートエントリーにはフレームワークに依存しないものだけが残ります: `useSharedState`、`useUrlEncode`、`useUrlStateBase`、`useLinkProps`、`encode`/`decode`、`encodeState`/`decodeState`。
 
 [API ドキュメント](packages/urlstate/useUrlStateBase)
 
@@ -917,6 +996,41 @@ export const useUserState = () => {
 2. Vercel サーバーはヘッダー(クエリ文字列など)のサイズを **14KB** に制限しているため、URL の状態は約 5000 語未満に保ってください。<https://vercel.com/docs/errors/URL_TOO_LONG>
 3. app router 付きの `next.js` 14/15/16 でテスト済みです。pages をサポートする予定はありません。
 
+4. **Vitest + react-router 7**: provider がすぐそこにあるのに、`<BrowserRouter>` の内側でコンポーネントを描画するテストが `useNavigate() may be used only in the context of a <Router> component` を投げる場合は、`react-router@8` に上げるか、このパッケージをインライン化してください:
+
+   ```ts
+   // vitest.config.ts
+   test: { server: { deps: { inline: ['state-in-url'] } } }
+   ```
+
+   Vitest は `node_modules` を外部化するため、`state-in-url` は Node が、テストファイルは Vite が読み込みます。`react-router@7` では `node` エクスポート条件が `module`/`module-sync` を `index.mjs` に、`default` を `index.js` に向けており、2 つのリゾルバがそれぞれ別のものを選びます。その結果 react-router が二重に読み込まれ、React context も二つ存在し、provider が書き込むのは hook が読まない方のコピーになります。インライン化すると双方が Vite のリゾルバに揃います。
+
+   `react-router@8` は `default` と `module-sync` を同じファイルに向けているので、どのリゾルバも食い違いようがなく、何も必要ありません。エラーメッセージに `state-in-url` の名前は出てこないため、ここに書いてあります。
+
+5. **Jest**: このパッケージは ESM としてのみ解決されますが、Jest は既定でテストを CommonJS として実行するため、素の `require()` は `Must use import to load ES Module` で失敗します。Jest は Node のフラグ不要な `require(esm)` を引き継がず、独自の同期 `vm` API を使うので、**Node 24.9+** ではフラグを渡してください:
+
+   ```json
+   // package.json
+   "scripts": { "test": "NODE_OPTIONS=--experimental-vm-modules jest" }
+   ```
+
+   フラグを渡したくない場合、`dist/` には CommonJS ビルドも同梱されています。`exports` マップからは意図的に外してあるため偶然解決されることはありません——Jest を明示的にそこへ向けてください:
+
+   ```js
+   // jest.config.js
+   moduleNameMapper: {
+     '^state-in-url$': '<rootDir>/node_modules/state-in-url/dist/index.cjs',
+     '^state-in-url/utils$': '<rootDir>/node_modules/state-in-url/dist/utils.cjs',
+     '^state-in-url/(.*)$': '<rootDir>/node_modules/state-in-url/dist/$1/index.cjs',
+   },
+   ```
+
+   これはテストプロセス全体を CJS ビルドに差し替えるもので、安全です。一つのプロセス内で両方を混在させないでください——このパッケージは共有ステートのストアをモジュールスコープに置いているため、コピーが二つあればストアも二つになり、`useSharedState` は何も告げずに共有をやめます。
+
+   もう一つの違いとして、`jest.mock()` は ES モジュールには効きません。このパッケージをモックするなら `jest.unstable_mockModule()` を使ってください。
+
+   Vitest、Next.js、Vite、Astro、Remix はいずれもこの Jest 向けの設定を必要としません。Vitest で追加が必要なのは上記の `server.deps.inline` だけで、しかも `react-router@7` の場合のみです。
+
 ## その他
 
 ### 貢献、またはローカルでの実行