state-in-url 7.0.0 → 8.0.1

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=ad78fdbbee096115a953813ed9a462e3393c5736 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)
@@ -197,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:
@@ -982,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=ad78fdbbee096115a953813ed9a462e3393c5736 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)
@@ -197,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 :
@@ -982,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=ad78fdbbee096115a953813ed9a462e3393c5736 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-フック)
@@ -197,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` をインストールした後、プロジェクトで一度実行してください:
@@ -982,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` の場合のみです。
+
 ## その他
 
 ### 貢献、またはローカルでの実行

package/README.ko.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.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=ko source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
+<!-- i18n:meta locale=ko source=README.md source-blob=8b11ee8f8c8b83c207a940455766e24376508130 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -95,7 +95,7 @@ Next.js, react-router, Remix, Astro용 `useUrlState` 훅과 그 외 JS 환경을
 - **호환성**: 서드파티 쿼리 매개변수를 그대로 유지
 - **유연성**: 동일한 페이지에서 1개 이상의 상태 객체 사용 가능, 다른 키만 사용하면 됨
 - **빠름**: 최소한의 리렌더링, 큰 객체 인코딩 및 디코딩에 약 [1ms](https://github.com/asmyshlyaev177/state-in-url/blob/87c8c7c995c5cd7d9e7aa039c30bfe64b24abe4b/packages/urlstate/encoder/encoder.test.ts#L185) 소요
-- **서버 사이드 렌더링**: 서버 컴포넌트에서 사용 가능, Next.js 14 및 15 지원
+- **서버 사이드 렌더링**: 서버 컴포넌트에서 사용 가능, Next.js 14, 15 및 16 지원
 - **경량**: 의존성 없음, 라이브러리 크기 2KB 미만
 - **개발자 경험**: 좋은 개발자 경험, 문서, JSDoc 주석 및 예제
 - **프레임워크 유연성**: `Next.js`, `react-router`, `Remix`, `Astro`용 훅, 다른 프레임워크나 순수 JS와 함께 사용할 수 있는 헬퍼
@@ -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-훅)
@@ -197,6 +198,18 @@ 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에는 설정 한 줄이 필요합니다**——[주의사항](#주의사항) 5번을 참고하세요.
+
 ## AI 코딩 에이전트와 함께 사용
 
 `state-in-url`은 [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview)용 스킬 파일을 함께 제공합니다. AI 에이전트(Claude Code, Cursor, Copilot, Codex 등)가 라이브러리를 사용할 때 올바른 패턴을 불러오고 흔한 실수를 피할 수 있습니다. `state-in-url`을 설치한 후 프로젝트에서 한 번 실행하세요:
@@ -975,7 +988,42 @@ export const useUserState = () => {
 
 1. 직렬화 가능한 값만 전달할 수 있습니다. `Function`, `BigInt` 또는 `Symbol`은 작동하지 않으며, `ArrayBuffer`와 같은 것도 마찬가지일 것입니다. JSON으로 직렬화할 수 있는 모든 것은 작동합니다.
 2. Vercel 서버는 헤더(쿼리 문자열 및 기타 항목) 크기를 **14KB**로 제한하므로 URL 상태를 약 5000단어 미만으로 유지하세요. <https://vercel.com/docs/errors/URL_TOO_LONG>
-3. app router를 사용하는 `next.js` 14/15로 테스트되었으며, pages를 지원할 계획은 없습니다.
+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`로 가리키고 두 리졸버가 서로 다른 것을 고릅니다——그래서 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`에서만 필요합니다.
 
 ## 기타
 

package/README.md

@@ -137,6 +137,7 @@ The full comparison — the same feature built in both, other alternatives (TanS
   - [installation](#installation)
     - [1. Install package](#1-install-package)
     - [2. Edit tsconfig.json](#2-edit-tsconfigjson)
+    - [3. Note: this package resolves as ESM only](#3-note-this-package-resolves-as-esm-only)
   - [Using with AI coding agents](#using-with-ai-coding-agents)
   - [useUrlState](#useurlstate)
     - [useUrlState hook for Next.js](#useurlstate-hook-for-nextjs)
@@ -196,6 +197,18 @@ pnpm add state-in-url
 In `tsconfig.json` in `compilerOptions` set `"moduleResolution": "Bundler"`, or`"moduleResolution": "Node16"`, or `"moduleResolution": "NodeNext"`.
 Possibly need to set `"module": "ES2022"`, or `"module": "ESNext"`
 
+### 3. Note: this package resolves as ESM only
+
+Next.js, Vite, Astro and Remix bundle it with no configuration, and `require()`
+from plain Node works on Node `^20.19` or `>=22.12`, where `require(esm)` is
+unflagged.
+
+A CommonJS build ships in `dist/` as `.cjs`, but the `exports` map does not point
+at it, so nothing resolves to it by accident. It is there for the edge cases —
+older Node, or Jest without a flag — and you reach it by explicit path.
+
+**Jest needs one line of config either way** — see [Gotchas](#gotchas) item 5.
+
 ## Using with AI coding agents
 
 `state-in-url` ships skill files for [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview), so AI agents (Claude Code, Cursor, Copilot, Codex, etc.) load the right patterns and avoid common mistakes when using the library. After installing `state-in-url`, run once in your project:
@@ -980,6 +993,40 @@ export const useUserState = () => {
 1. Can pass only serializable values, `Function`, `BigInt` or `Symbol` won't work, probably things like `ArrayBuffer` neither. Everything that can be serialized to JSON will work.
 2. Vercel servers limit size of headers (query string and other stuff) to **14KB**, so keep your URL state under ~5000 words. <https://vercel.com/docs/errors/URL_TOO_LONG>
 3. Tested with `next.js` 14/15/16  with app router, no plans to support pages.
+4. **Vitest + react-router 7**: if a test rendering a component inside `<BrowserRouter>` throws `useNavigate() may be used only in the context of a <Router> component` with the provider right there, either upgrade to `react-router@8` or inline this package:
+
+   ```ts
+   // vitest.config.ts
+   test: { server: { deps: { inline: ['state-in-url'] } } }
+   ```
+
+   Vitest externalizes `node_modules`, so Node loads `state-in-url` while Vite loads your test file. In `react-router@7` the `node` export condition points `module`/`module-sync` at `index.mjs` and `default` at `index.js`, and the two resolvers pick different ones — so react-router loads twice, its React context exists twice, and the provider writes to the copy the hook does not read. Inlining puts both sides on Vite's resolver.
+
+   `react-router@8` points `default` and `module-sync` at the same file, so no resolver can disagree and nothing is needed. The error never names `state-in-url`, which is why this is here.
+
+5. **Jest**: this package resolves as ESM only, and Jest runs tests as CommonJS by default, so a bare `require()` fails with `Must use import to load ES Module`. Jest does not inherit Node's unflagged `require(esm)` — it uses its own synchronous `vm` API — so on **Node 24.9+** give it the flag:
+
+   ```json
+   // package.json
+   "scripts": { "test": "NODE_OPTIONS=--experimental-vm-modules jest" }
+   ```
+
+   If you would rather not pass a flag, `dist/` also ships a CommonJS build. It is deliberately absent from the `exports` map, so nothing resolves to it by accident — point Jest at it explicitly:
+
+   ```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',
+   },
+   ```
+
+   That substitutes the CJS build for the whole test process, which is safe. Do not mix the two in one process — this package keeps its shared-state store in module scope, so two copies means two stores and `useSharedState` quietly stops sharing.
+
+   One more difference: `jest.mock()` does not apply to ES modules. Use `jest.unstable_mockModule()` if you mock this package.
+
+   Vitest, Next.js, Vite, Astro and Remix all need none of this Jest setup. Vitest's one extra step is the `server.deps.inline` above, and only with `react-router@7`.
 
 ## Other
 

package/README.pt-BR.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) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=pt-BR source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
+<!-- i18n:meta locale=pt-BR source=README.md source-blob=8b11ee8f8c8b83c207a940455766e24376508130 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -138,6 +138,7 @@ A comparação completa — a mesma feature nas duas, outras alternativas (TanSt
   - [Instalação](#instalação)
     - [1. Instalar o pacote](#1-instalar-o-pacote)
     - [2. Editar o tsconfig.json](#2-editar-o-tsconfigjson)
+    - [3. Observação: este pacote resolve apenas como ESM](#3-observação-este-pacote-resolve-apenas-como-esm)
   - [Uso com agentes de codificação de IA](#uso-com-agentes-de-codificação-de-ia)
   - [useUrlState](#useurlstate)
     - [Hook useUrlState para Next.js](#hook-useurlstate-para-nextjs)
@@ -197,6 +198,20 @@ pnpm add state-in-url
 No `tsconfig.json`, em `compilerOptions`, defina `"moduleResolution": "Bundler"`, ou `"moduleResolution": "Node16"`, ou `"moduleResolution": "NodeNext"`.
 Possivelmente será necessário definir `"module": "ES2022"`, ou `"module": "ESNext"`
 
+### 3. Observação: este pacote resolve apenas como ESM
+
+Next.js, Vite, Astro e Remix o empacotam sem nenhuma configuração, e o
+`require()` do Node puro funciona no Node `^20.19` ou `>=22.12`, onde
+`require(esm)` dispensa flag.
+
+Em `dist/` também é publicada uma build CommonJS com extensão `.cjs`, mas o mapa
+`exports` não aponta para ela, então nenhuma resolução chega lá por acidente. Ela
+existe para os casos extremos — Node antigo, ou Jest sem flag — e só é alcançada
+por um caminho explícito.
+
+**Em qualquer um dos casos o Jest precisa de uma linha de configuração** — veja o
+item 5 em [Pegadinhas](#pegadinhas).
+
 ## Uso com agentes de codificação de IA
 
 O `state-in-url` inclui arquivos de habilidades (skills) para o [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview), para que os agentes de IA (Claude Code, Cursor, Copilot, Codex, etc.) carreguem os padrões corretos e evitem erros comuns ao usar a biblioteca. Após instalar o `state-in-url`, execute uma vez no seu projeto:
@@ -982,6 +997,41 @@ export const useUserState = () => {
 2. Os servidores da Vercel limitam o tamanho dos cabeçalhos (string de consulta e outras coisas) a **14KB**, então mantenha o estado da sua URL abaixo de ~5000 palavras. <https://vercel.com/docs/errors/URL_TOO_LONG>
 3. Testado com `next.js` 14/15/16 com app router; sem planos de suportar pages.
 
+4. **Vitest + react-router 7**: se um teste que renderiza um componente dentro de `<BrowserRouter>` lança `useNavigate() may be used only in the context of a <Router> component` com o provider bem ali, atualize para `react-router@8` ou inclua este pacote inline:
+
+   ```ts
+   // vitest.config.ts
+   test: { server: { deps: { inline: ['state-in-url'] } } }
+   ```
+
+   O Vitest externaliza `node_modules`, então o Node carrega `state-in-url` enquanto o Vite carrega o seu arquivo de teste. No `react-router@7` a condição de exportação `node` aponta `module`/`module-sync` para `index.mjs` e `default` para `index.js`, e os dois resolvedores escolhem coisas diferentes: o react-router é carregado duas vezes, o React context dele existe em duplicata e o provider escreve na cópia que o hook não lê. Incluir inline coloca os dois lados no resolvedor do Vite.
+
+   O `react-router@8` aponta `default` e `module-sync` para o mesmo arquivo, então nenhum resolvedor pode divergir e nada é necessário. O erro nunca cita `state-in-url`, e é por isso que este item está aqui.
+
+5. **Jest**: este pacote resolve apenas como ESM e o Jest executa os testes como CommonJS por padrão, então um `require()` simples falha com `Must use import to load ES Module`. O Jest não herda o `require(esm)` sem flag do Node — ele usa a própria API síncrona `vm` —, então no **Node 24.9+** passe a flag:
+
+   ```json
+   // package.json
+   "scripts": { "test": "NODE_OPTIONS=--experimental-vm-modules jest" }
+   ```
+
+   Se preferir não passar flag, `dist/` também traz uma build CommonJS. Ela está deliberadamente fora do mapa `exports`, então nada resolve para ela por acidente: aponte o Jest para ela explicitamente:
+
+   ```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',
+   },
+   ```
+
+   Isso substitui pela build CJS em todo o processo de teste, e é seguro. Não misture as duas em um mesmo processo: este pacote guarda o armazenamento de estado compartilhado no escopo do módulo, então duas cópias significam dois armazenamentos e o `useSharedState` para de compartilhar sem avisar.
+
+   Mais uma diferença: `jest.mock()` não se aplica a módulos ES. Use `jest.unstable_mockModule()` se você fizer mock deste pacote.
+
+   Vitest, Next.js, Vite, Astro e Remix não precisam de nada dessa configuração do Jest. O único passo adicional do Vitest é o `server.deps.inline` acima, e apenas com `react-router@7`.
+
 ## Outros
 
 ### Contribuir e/ou executar localmente

package/README.ru.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.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=ru source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
+<!-- i18n:meta locale=ru 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)
     - [Hook useUrlState для Next.js](#hook-useurlstate-для-nextjs)
@@ -197,6 +198,20 @@ 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()`
+из обычного Node работает на Node `^20.19` или `>=22.12`, где `require(esm)`
+доступен без флага.
+
+В `dist/` также поставляется сборка CommonJS с расширением `.cjs`, но карта
+`exports` на неё не указывает, поэтому разрешение не попадёт на неё случайно.
+Она существует для пограничных случаев — старый Node или Jest без флага — и
+обратиться к ней можно только по явному пути.
+
+**В обоих случаях Jest требует одной строки настройки** — см. пункт 5 в разделе
+[Подводные камни](#подводные-камни).
+
 ## Использование с AI-агентами для кодинга
 
 `state-in-url` поставляется с файлами навыков (skills) для [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview), поэтому AI-агенты (Claude Code, Cursor, Copilot, Codex и т. д.) загружают правильные паттерны и избегают типичных ошибок при работе с библиотекой. После установки `state-in-url` выполните один раз в своём проекте:
@@ -982,6 +997,41 @@ export const useUserState = () => {
 2. Серверы Vercel ограничивают размер заголовков (строка запроса и прочее) **14KB**, поэтому держите состояние в URL в пределах ~5000 слов. <https://vercel.com/docs/errors/URL_TOO_LONG>
 3. Протестировано с `next.js` 14/15/16 с app router; поддержка pages не планируется.
 
+4. **Vitest + react-router 7**: если тест, рендерящий компонент внутри `<BrowserRouter>`, выбрасывает `useNavigate() may be used only in the context of a <Router> component`, хотя provider стоит прямо там, — либо обновитесь до `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`, и два резолвера выбирают разное: react-router загружается дважды, его React context существует в двух экземплярах, и provider пишет в ту копию, которую хук не читает. Инлайн переводит обе стороны на резолвер 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)`, работающий без флага, — он использует собственный синхронный API `vm`, — поэтому на **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`.
+
 ## Прочее
 
 ### Участие и/или локальный запуск