state-in-url 6.1.3 → 6.2.0

package/README.md

@@ -108,6 +108,7 @@ This library is a good alternative for NUQS.
   - [installation](#installation)
     - [1. Install package](#1-install-package)
     - [2. Edit tsconfig.json](#2-edit-tsconfigjson)
+  - [Using with AI coding agents](#using-with-ai-coding-agents)
   - [useUrlState](#useurlstate)
     - [useUrlState hook for Next.js](#useurlstate-hook-for-nextjs)
       - [Usage examples](#usage-examples)
@@ -159,6 +160,16 @@ 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"`
 
+## 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:
+
+```sh
+npx @tanstack/intent@latest install
+```
+
+This wires your installed agent to discover the skills from `node_modules/state-in-url/skills/`. List available skills with `npx @tanstack/intent@latest list`.
+
 ## useUrlState
 
 Main hook that takes initial state as parameter and returns state object, callback to update url, and callback to update only state.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "6.1.3",
+  "version": "6.2.0",
   "description": "Store state in URL as in object, types and structure are preserved, with TS validation. Same API as React.useState, wthout any hasssle or boilerplate. Next.js@14-15, react-router@6-7, and remix@2.",
   "homepage": "https://state-in-url.dev",
   "repository": {
@@ -26,7 +26,9 @@
     "url": "https://github.com/asmyshlyaev177/state-in-url/issues"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "!skills/_artifacts"
   ],
   "main": "./dist/index.js",
   "module": "dist/index.mjs",
@@ -439,6 +441,7 @@
   },
   "devDependencies": {
     "@babel/core": "^7.28.4",
+    "@tanstack/intent": "latest",
     "@babel/node": "^7.28.0",
     "@babel/preset-env": "^7.28.3",
     "@babel/preset-typescript": "^7.27.1",
@@ -490,7 +493,6 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-router": "^7.15.0",
-    "ringfence": "^0.1.0",
     "rollup": "^4.52.3",
     "rollup-plugin-esbuild": "^6.2.1",
     "rollup-plugin-filesize": "^10.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "6.1.3",
+  "version": "6.2.0",
   "description": "Store state in URL as in object, types and structure are preserved, with TS validation. Same API as React.useState, wthout any hasssle or boilerplate. Next.js@14-15, react-router@6-7, and remix@2.",
   "homepage": "https://state-in-url.dev",
   "repository": {
@@ -26,7 +26,9 @@
     "url": "https://github.com/asmyshlyaev177/state-in-url/issues"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "!skills/_artifacts"
   ],
   "main": "./dist/index.js",
   "module": "dist/index.mjs",
@@ -439,6 +441,7 @@
   },
   "devDependencies": {
     "@babel/core": "^7.28.4",
+    "@tanstack/intent": "latest",
     "@babel/node": "^7.28.0",
     "@babel/preset-env": "^7.28.3",
     "@babel/preset-typescript": "^7.27.1",
@@ -490,7 +493,6 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-router": "^7.15.0",
-    "ringfence": "^0.1.0",
     "rollup": "^4.52.3",
     "rollup-plugin-esbuild": "^6.2.1",
     "rollup-plugin-filesize": "^10.0.0",

package/skills/feature-state-hook/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: feature-state-hook
+description: >
+  Define typed, module-scoped state and wrap useUrlState in a feature-scoped
+  custom hook so unrelated React components share the same URL-synced state.
+  Covers drawer/modal open-state, tab switching, multi-select toggles,
+  reset/defaults semantics, and the object-identity-based sharing model.
+  Load this skill when storing filters, tabs, drawers, selections, paginators,
+  or any UI state that should survive reloads and be shareable by URL.
+type: core
+library: state-in-url
+library_version: '6.1.3'
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/next/useUrlState/useUrlState.ts'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/utils.ts'
+  - 'asmyshlyaev177/state-in-url:README.md'
+---
+
+# state-in-url — Feature state hook
+
+`state-in-url` stores a typed JSON-serializable object in the URL query string. State across components is shared by passing the **same module-scoped default-state object** to `useUrlState`. The library uses object identity, not deep equality, to wire up subscriptions — so the default state must be a static `const`, defined once, outside any component.
+
+## Setup
+
+```typescript
+// features/jobs/jobsState.ts
+export type JobsState = {
+  status: '' | 'active' | 'closed';
+  tab: 'details' | 'qa' | 'applicants';
+  jobId: string;
+};
+
+export const JOBS_STATE: JobsState = {
+  status: '',
+  tab: 'details',
+  jobId: '',
+};
+```
+
+```typescript
+// features/jobs/useJobsState.ts
+'use client';
+import { useSearchParams } from 'next/navigation';
+import { useUrlState } from 'state-in-url/next';
+import { JOBS_STATE } from './jobsState';
+
+export function useJobsState() {
+  const searchParams = useSearchParams();
+  return useUrlState(JOBS_STATE, { searchParams });
+}
+```
+
+```typescript
+// any component
+import { useJobsState } from 'features/jobs/useJobsState';
+
+export function JobsTabs() {
+  const { urlState, setUrl, reset } = useJobsState();
+
+  return (
+    <>
+      <button onClick={() => setUrl({ tab: 'qa' })}>Q&A</button>
+      <button onClick={reset}>Reset</button>
+    </>
+  );
+}
+```
+
+The same `useJobsState()` called in two different components reads and writes the same URL state — no Context, no Provider.
+
+## Core Patterns
+
+### Drawer / modal open-close via URL
+
+Pick an empty-string default for the ID field. Empty = closed (and the URL stays clean); non-empty = open.
+
+```typescript
+type MembersState = { memberId: string; tab: 'profile' | 'activity' };
+const MEMBERS_STATE: MembersState = { memberId: '', tab: 'profile' };
+
+const open  = (id: string) => setUrl({ memberId: id, tab: 'profile' });
+const close = ()           => setUrl({ ...MEMBERS_STATE });
+```
+
+`setUrl({ ...MEMBERS_STATE })` returns every field to default → all related URL params disappear in one call.
+
+### Multi-select toggle (functional update)
+
+```typescript
+const toggle = (id: string) =>
+  setUrl((curr) => ({
+    ...curr,
+    tags: curr.tags.includes(id)
+      ? curr.tags.filter((t) => t !== id)
+      : curr.tags.concat(id),
+  }));
+```
+
+### Reset to defaults
+
+```typescript
+<button onClick={reset}>Reset</button>
+// or, equivalently:
+<button onClick={() => setUrl((_, initial) => initial)}>Reset</button>
+```
+
+### Multiple independent state objects on one page
+
+Different default-state objects → independent stores. Choose non-overlapping top-level field names.
+
+```typescript
+type FiltersState = { search: string; sortBy: 'name' | 'date' };
+type DrawerState  = { open: boolean; view: 'profile' | 'settings' };
+
+const FILTERS_STATE: FiltersState = { search: '', sortBy: 'name' };
+const DRAWER_STATE:  DrawerState  = { open: false, view: 'profile' };
+```
+
+## Common Mistakes
+
+### CRITICAL defaultState defined inside the React component
+
+Wrong:
+
+```typescript
+function MyFeature({ initialTab }: Props) {
+  const defaults = { tab: initialTab, open: false }; // recreated every render
+  const { urlState } = useUrlState(defaults);
+}
+```
+
+Correct:
+
+```typescript
+type FeatureState = { tab: 'a' | 'b'; open: boolean };
+const FEATURE_STATE: FeatureState = { tab: 'a', open: false };
+
+function MyFeature() {
+  const { urlState } = useUrlState(FEATURE_STATE);
+}
+```
+
+The library uses object identity of the default-state argument to wire subscriptions and seed initial state. A new object on every render breaks sharing, breaks SSR hydration, and silently loses URL values on first paint. Maintainer-confirmed on issues #57, #60, #69.
+
+Source: GitHub issues #57, #60, #69 (asmyshlyaev177/state-in-url)
+
+### CRITICAL Using `interface` instead of `type` for the state shape
+
+Wrong:
+
+```typescript
+interface FeatureState { tab: string; open: boolean }
+const initial: FeatureState = { tab: 'a', open: false };
+useUrlState(initial); // TS error on JSONCompatible<T>
+```
+
+Correct:
+
+```typescript
+type FeatureState = { tab: string; open: boolean };
+const initial: FeatureState = { tab: 'a', open: false };
+useUrlState(initial);
+```
+
+The hook's generic constraint `JSONCompatible<T>` accepts `type` aliases but rejects `interface` declarations due to how TypeScript handles index signatures in mapped types. **Always** declare an explicit `type` for the state shape and annotate the default-state const with it (`const FOO_STATE: FooState = { ... }`) — don't rely on inferred types from a plain `const`, since narrowing surprises (`tab: 'a'` inferred as the literal `'a'`, not the union) lead to confusing type errors at every `setUrl` call site.
+
+Source: GitHub issue #21 (asmyshlyaev177/state-in-url)
+
+### CRITICAL `setUrl` inside `useEffect` → infinite update loop
+
+Wrong:
+
+```typescript
+React.useEffect(() => {
+  setUrl({ tab: urlState.tab.toLowerCase() }); // re-fires effect
+}, [urlState, setUrl]);
+```
+
+Correct:
+
+```typescript
+// Derive on read instead
+const tab = urlState.tab.toLowerCase();
+
+// Or, if a sync truly must happen, gate on the actual change
+React.useEffect(() => {
+  const lower = urlState.tab.toLowerCase();
+  if (urlState.tab !== lower) setUrl({ tab: lower });
+}, [urlState.tab, setUrl]);
+```
+
+URL throttling does not break a state→effect→setUrl→state cycle. The state updates first, the effect re-fires, repeat.
+
+Source: Maintainer interview
+
+### HIGH Calling `useUrlState` directly with separate default objects in N components
+
+Wrong:
+
+```typescript
+// ComponentA.tsx
+const DEFAULTS = { tab: 'a' };
+const { urlState } = useUrlState(DEFAULTS);
+
+// ComponentB.tsx  (different file → different identity)
+const DEFAULTS = { tab: 'a' };
+const { urlState } = useUrlState(DEFAULTS); // not sharing with A
+```
+
+Correct:
+
+```typescript
+// hooks/useFeatureState.ts — one source of truth
+export type FeatureState = { tab: 'a' | 'b' };
+export const FEATURE_STATE: FeatureState = { tab: 'a' };
+export const useFeatureState = () => useUrlState(FEATURE_STATE);
+
+// every component imports the hook, never useUrlState directly
+```
+
+Sharing is keyed by default-state object identity. Two components each declaring their own `const DEFAULTS = {...}` produce two independent stores even with identical shape.
+
+Source: Maintainer interview — highest-impact production hazard
+
+### HIGH `setUrl` or `setState` called during render
+
+Wrong:
+
+```typescript
+function Component() {
+  const { urlState, setUrl } = useFeatureState();
+  if (!urlState.initialized) setUrl({ initialized: true });
+  return <div>...</div>;
+}
+```
+
+Correct:
+
+```typescript
+function Component() {
+  const { urlState, setUrl } = useFeatureState();
+  React.useEffect(() => {
+    if (!urlState.initialized) setUrl({ initialized: true });
+  }, [urlState.initialized, setUrl]);
+}
+```
+
+State setters must run in effects or handlers, never during render. React surfaces this with "Cannot update a component while rendering a different component."
+
+Source: Maintainer interview
+
+### HIGH Storing non-JSON-serializable values
+
+Wrong:
+
+```typescript
+const STATE = { onChange: () => {}, items: new Set([1, 2]) };
+```
+
+Correct:
+
+```typescript
+const STATE = { items: [1, 2] as number[], updatedAt: new Date() };
+```
+
+Functions, Symbols, BigInt, Map, Set, ArrayBuffer, and class instances are not JSON-serializable and won't round-trip. Dates **are** supported (the encoder has special-case handling).
+
+Source: packages/urlstate/utils.ts (JSONCompatible type); README Gotchas
+
+### MEDIUM Mutating `urlState` directly
+
+Wrong:
+
+```typescript
+urlState.tab = 'b';  // no-op
+```
+
+Correct:
+
+```typescript
+setUrl({ tab: 'b' });
+```
+
+`urlState` is a reference to internal state; mutating it bypasses subscribers and URL sync.
+
+Source: JSDoc on `useUrlState` return type
+
+### MEDIUM Expecting reset to keep default-valued fields in the URL
+
+Wrong:
+
+```typescript
+// Wanting ?tab=features to persist after a reset
+const STATE = { tab: 'features' };
+reset(); // URL becomes clean — no ?tab= at all
+```
+
+Correct:
+
+```typescript
+// Pick a default that means "no selection". The URL stays clean at default;
+// ?tab=qa appears only when the user selects something non-default.
+const STATE = { tab: 'details' | 'qa' | 'applicants' };
+```
+
+The library only encodes fields whose value differs from the default — this is what keeps URLs short.
+
+Source: README "Best Practices"
+
+### MEDIUM Namespace collision between two features
+
+Wrong:
+
+```typescript
+const JOBS_STATE     = { tab: 'details' };
+const SETTINGS_STATE = { tab: 'profile' };
+// both mounted on same page → fight over ?tab=
+```
+
+Correct:
+
+```typescript
+type JobsState     = { jobs_tab: 'details' | 'qa' | 'applicants' };
+type SettingsState = { settings_tab: 'profile' | 'account' };
+
+const JOBS_STATE:     JobsState     = { jobs_tab: 'details' };
+const SETTINGS_STATE: SettingsState = { settings_tab: 'profile' };
+```
+
+Each `useUrlState` instance reads/writes its keys against the global query string. Two features defining the same field name overwrite each other.
+
+Source: Maintainer interview
+
+## Sensitive data
+
+Entity IDs (`jobId`, `memberId`, `channelId`) referencing public or semi-public DB rows are fine — they already appear in route paths and have no secrecy expectation. Never put **true secrets** in the URL: auth tokens, API keys, passwords, PII (email, SSN, phone).
+
+## Other primitives — when to reach for them
+
+- **`useSharedState`** — cross-component state without URL sync. See `state-in-url/shared-state-no-url`.
+- **`encodeState` / `decodeState`** — server-side or Node.js encoding/decoding of state strings (e.g. inside Next.js Proxy or a layout). Imported from `state-in-url/encodeState`.
+- **`useUrlStateBase`** — build a `useUrlState` for an unsupported router (TanStack Router etc.). Imported from `state-in-url/useUrlStateBase`.
+
+## URL size
+
+Keep total query-string size well under ~12 KB to stay safe across CDNs and Vercel's 14 KB header limit. See [Limits.md](https://github.com/asmyshlyaev177/state-in-url/blob/master/Limits.md).
+
+## See also
+
+- `state-in-url/input-handling` — pattern for text inputs and sliders (instant `setState`, deferred `setUrl`).
+- `state-in-url/nextjs-ssr` — required when using this skill in Next.js to avoid hydration mismatches.
+- `state-in-url/form-library-integration` — when the feature is a `react-hook-form` form.

package/skills/form-library-integration/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: form-library-integration
+description: >
+  Use the URL as a form draft store by pairing useUrlState with
+  react-hook-form (or formik). Share one module-scoped defaults object
+  between both libraries; hydrate useForm.defaultValues from urlState;
+  push form changes back into setUrl via RHF subscribe() (NOT watch()).
+  Load this skill when a form should round-trip its values through the
+  URL — filter forms, search forms, multi-step wizards with shareable
+  draft links.
+type: composition
+library: state-in-url
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:issue#57'
+  - 'asmyshlyaev177/state-in-url:README.md'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — Form library integration (react-hook-form)
+
+The canonical pattern: one module-scoped defaults object owns the form shape, both `useUrlState` and `useForm` consume it, RHF's `subscribe()` callback pushes form changes into `setUrl`. Hydration from URL happens through `defaultValues: urlState`.
+
+## Setup
+
+```typescript
+// features/filters/filtersState.ts
+import { z } from 'zod';
+
+export const filtersSchema = z.object({
+  q: z.string(),
+  sort: z.enum(['name', 'date']),
+  tags: z.array(z.string()),
+});
+export type FiltersState = z.infer<typeof filtersSchema>;
+
+export const FILTERS_STATE: FiltersState = {
+  q: '',
+  sort: 'name',
+  tags: [],
+};
+```
+
+```typescript
+// features/filters/FiltersForm.tsx
+'use client';
+import React from 'react';
+import { useSearchParams } from 'next/navigation';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useUrlState } from 'state-in-url/next';
+import { FILTERS_STATE, filtersSchema, type FiltersState } from './filtersState';
+
+export function FiltersForm() {
+  const searchParams = useSearchParams();
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE, { searchParams });
+
+  const form = useForm<FiltersState>({
+    resolver: zodResolver(filtersSchema),
+    defaultValues: urlState, // hydrate from URL on mount
+  });
+
+  React.useEffect(() => {
+    const sub = form.subscribe({
+      formState: { values: true },
+      callback: ({ values }) => setUrl(values),
+    });
+    return () => sub();
+  }, [form, setUrl]);
+
+  return (
+    <form>
+      <input {...form.register('q')} />
+      <select {...form.register('sort')}>
+        <option value="name">Name</option>
+        <option value="date">Date</option>
+      </select>
+    </form>
+  );
+}
+```
+
+## Core Patterns
+
+### Hydrate `useForm` from `urlState`
+
+`defaultValues: urlState` runs once on mount; the form is initialized with whatever the URL contained (or `FILTERS_STATE` defaults if URL is empty).
+
+### Push form → URL with `subscribe()`
+
+RHF's `subscribe()` is push-based — it fires the callback without re-rendering the host component. Inside, call `setUrl(values)` to coalesce the change into the URL (the library content-diffs internally so no-ops are free).
+
+### Reset
+
+```typescript
+const onReset = () => {
+  form.reset(FILTERS_STATE); // reset form
+  setUrl((_, initial) => initial); // reset URL
+};
+```
+
+## Common Mistakes
+
+### HIGH Building `defaultValues` from `urlState` inline (not the module-scoped shape)
+
+Wrong:
+
+```typescript
+const defaults = { ...formValues, ...overrides }; // new object each render
+const { urlState } = useUrlState(defaults);
+const form = useForm({ defaultValues: defaults });
+```
+
+Correct:
+
+```typescript
+// One module-scoped const, shared by both hooks
+export const FILTERS_STATE: FiltersState = { q: '', sort: 'name', tags: [] };
+
+const { urlState } = useUrlState(FILTERS_STATE, { searchParams });
+const form = useForm({ defaultValues: urlState }); // hydrate from URL
+```
+
+A fresh `defaults` on each render breaks `useUrlState`'s identity-based sharing (same root cause as the cross-skill failure). Use the module-scoped shape for `useUrlState`; pass `urlState` (the live value) to `useForm`.
+
+Source: GitHub issue #57 (asmyshlyaev177/state-in-url, maintainer reply)
+
+### MEDIUM Using `watch()` instead of `subscribe()` to sync RHF → URL
+
+Wrong:
+
+```typescript
+const values = form.watch();
+React.useEffect(() => {
+  setUrl(values);
+}, [values, setUrl]);
+```
+
+Correct:
+
+```typescript
+React.useEffect(() => {
+  const sub = form.subscribe({
+    formState: { values: true },
+    callback: ({ values }) => setUrl(values),
+  });
+  return () => sub();
+}, [form, setUrl]);
+```
+
+`watch()` re-renders the host component on every field change. `subscribe()` is push-based and avoids the rerender, which matters in large forms.
+
+Source: GitHub issue #57 (asmyshlyaev177/state-in-url, maintainer reply)
+
+### CRITICAL `defaultState` defined inside the React component
+
+(Cross-skill failure — also in `feature-state-hook`.)
+
+Wrong:
+
+```typescript
+function FiltersForm({ initialSort }: Props) {
+  const defaults = { q: '', sort: initialSort, tags: [] }; // each render
+  const { urlState } = useUrlState(defaults);
+}
+```
+
+Correct: Move the shape to a module-scoped `const` (`FILTERS_STATE`) and import it.
+
+Source: GitHub issues #57, #60, #69 (asmyshlyaev177/state-in-url)
+
+## formik variant
+
+Same idea: subscribe to `formik.values` and call `setUrl`. With formik, use a `useEffect` on `values` since formik does re-render on changes by design.
+
+```typescript
+const formik = useFormik({ initialValues: urlState, onSubmit: () => {} });
+
+React.useEffect(() => {
+  setUrl(formik.values);
+}, [formik.values, setUrl]);
+```
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern; required reading.
+- `state-in-url/nextjs-ssr` — for SSR hydration of the filter form on Next.js.
+- `state-in-url/input-handling` — for non-form inputs (search box not inside a form).

package/skills/input-handling/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: input-handling
+description: >
+  Reconcile instant local input feedback with URL write throttling. setState
+  updates internal state synchronously (instant re-render); setUrl is throttled
+  and asynchronous (URL catches up on the next tick). Use this skill for text
+  inputs, search boxes, sliders, range pickers, and any control that fires
+  many updates per second where binding setUrl directly to onChange causes
+  perceived lag or wasted URL writes.
+type: core
+library: state-in-url
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/useUrlStateBase/useUrlStateBase.ts'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/utils.ts'
+  - 'asmyshlyaev177/state-in-url:README.md#update-state-only-and-sync-to-url-manually'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — Input handling
+
+`useUrlState` returns three setters with different timing:
+
+| Setter | What updates | When |
+|---|---|---|
+| `setState(value)` | Internal state only | Synchronous |
+| `setUrl(value)` | Internal state + URL | State sync, URL on next tick (throttled) |
+| `setUrl()` | Flush current state to URL | URL on next tick (diff-checked, no-op if equal) |
+
+State updates always render immediately. URL writes are coalesced through an internal global timer (`TIMEOUT` constant in [useUrlStateBase.ts](https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/urlstate/useUrlStateBase/useUrlStateBase.ts)) so a burst of `setUrl` calls produces one URL update.
+
+## Setup
+
+```typescript
+// features/search/searchState.ts
+export type SearchState = { q: string; sort: 'name' | 'date' };
+export const SEARCH_STATE: SearchState = { q: '', sort: 'name' };
+```
+
+```typescript
+// features/search/useSearchState.ts
+'use client';
+import { useSearchParams } from 'next/navigation';
+import { useUrlState } from 'state-in-url/next';
+import { SEARCH_STATE } from './searchState';
+
+export function useSearchState() {
+  const searchParams = useSearchParams();
+  return useUrlState(SEARCH_STATE, { searchParams });
+}
+```
+
+## Core Patterns
+
+### Instant input, deferred URL write (onBlur)
+
+```typescript
+function SearchBox() {
+  const { urlState, setState, setUrl } = useSearchState();
+
+  return (
+    <input
+      value={urlState.q}
+      onChange={(e) => setState({ q: e.target.value })}
+      onBlur={() => setUrl()}
+    />
+  );
+}
+```
+
+`setState` updates state instantly (input feels native). `setUrl()` with no args flushes current state to the URL when the user finishes typing.
+
+### Discrete controls — `setUrl` directly
+
+For click/select/toggle controls that fire at most a few times per second, skip the split. `setUrl` is already throttled.
+
+```typescript
+<button onClick={() => setUrl({ sort: 'date' })}>Sort by date</button>
+```
+
+## Common Mistakes
+
+### CRITICAL `setUrl` inside `useEffect` → infinite update loop
+
+(Cross-skill failure — also in `feature-state-hook`.)
+
+Wrong:
+
+```typescript
+React.useEffect(() => {
+  setUrl({ q: urlState.q.trim() }); // re-fires every URL change
+}, [urlState, setUrl]);
+```
+
+Correct:
+
+```typescript
+React.useEffect(() => {
+  const trimmed = urlState.q.trim();
+  if (urlState.q !== trimmed) setUrl({ q: trimmed });
+}, [urlState.q, setUrl]);
+```
+
+URL throttling does not break a state→effect→setUrl→state cycle.
+
+Source: Maintainer interview
+
+### HIGH Binding `setUrl` directly to onChange of a typing input
+
+Wrong:
+
+```typescript
+<input
+  value={urlState.q}
+  onChange={(e) => setUrl({ q: e.target.value })}
+/>
+```
+
+Correct:
+
+```typescript
+<input
+  value={urlState.q}
+  onChange={(e) => setState({ q: e.target.value })}
+  onBlur={() => setUrl()}
+/>
+```
+
+Every keystroke fires a URL update. The library coalesces them with an internal timer, but the perceived behavior is laggy URL with extra rerenders (one for state, another when URL settles). Issue #78 was filed exactly for this symptom — the throttling is intentional.
+
+Source: GitHub issue #78 (asmyshlyaev177/state-in-url); README "Update state only and sync to URL manually"
+
+### MEDIUM Expecting `window.location.search` to reflect `setUrl` synchronously
+
+Wrong:
+
+```typescript
+setUrl({ tab: 'b' });
+console.log(window.location.search); // still the old value
+```
+
+Correct:
+
+```typescript
+setUrl({ tab: 'b' });
+// `urlState.tab` already equals 'b' synchronously.
+// `window.location.search` catches up after the throttle tick.
+```
+
+`setUrl` is "last-write-wins" — it coalesces a burst of updates into one URL write on the next macrotask. Read `urlState`, not `window.location`.
+
+Source: useUrlStateBase.ts (global `timer`); GitHub issue #78
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern this skill builds on.
+- `state-in-url/nextjs-ssr` — for SSR-safe wiring of the search input on Next.js App Router.

package/skills/nextjs-ssr/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: nextjs-ssr
+description: >
+  SSR-safe useUrlState in Next.js App Router. Forward searchParams from server
+  pages (awaiting the Promise in Next.js 15+), call useSearchParams() in pure
+  client components, decide between useHistory true/false, and use a Proxy
+  (formerly middleware) to expose query params to server layouts. App Router
+  only — Pages Router is not supported. Load this skill for any use of
+  state-in-url/next or anytime URL state must be correct on first paint.
+type: framework
+library: state-in-url
+framework: react
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/next/useUrlState/useUrlState.ts'
+  - 'asmyshlyaev177/state-in-url:packages/example-nextjs16/src/middleware.ts'
+  - 'asmyshlyaev177/state-in-url:README.md#with-server-side-rendering'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — Next.js App Router SSR
+
+Without `searchParams`, the first render of a `useUrlState` component has no URL knowledge. It renders defaults, then a client `useEffect` re-syncs from the URL → visible flash and a React hydration warning. The fix is to feed the URL into the hook on the server (via `searchParams` prop or a Proxy header) so the very first render is correct.
+
+App Router only. Pages Router uses `next/router`, which `state-in-url/next` does not support — there are no plans to add it.
+
+## Setup
+
+### Server page forwarding `searchParams` (recommended)
+
+```typescript
+// app/jobs/page.tsx  (Server Component)
+import { JobsList } from './JobsList';
+
+export default async function Page({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const sp = await searchParams; // Next.js 15+: searchParams is a Promise
+  return <JobsList searchParams={sp} />;
+}
+```
+
+```typescript
+// app/jobs/JobsList.tsx
+'use client';
+import { useUrlState } from 'state-in-url/next';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export function JobsList({ searchParams }: { searchParams: object }) {
+  const { urlState, setUrl } = useUrlState(JOBS_STATE, { searchParams });
+  return <pre>{JSON.stringify(urlState)}</pre>;
+}
+```
+
+### Pure client component using `useSearchParams`
+
+When you can't (or don't want to) thread `searchParams` from a server parent:
+
+```typescript
+'use client';
+import { useSearchParams } from 'next/navigation';
+import { useUrlState } from 'state-in-url/next';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export function useJobsState() {
+  const searchParams = useSearchParams();
+  return useUrlState(JOBS_STATE, { searchParams });
+}
+```
+
+## Core Patterns
+
+### `useHistory` — choosing the URL update mode
+
+| Setting | Mechanism | Effect | Use when |
+|---|---|---|---|
+| `useHistory: true` (default) | `window.history.pushState` / `replaceState` | No `_rsc` round-trip per URL change | URL state is client-only UI (filters, drawers, tabs) |
+| `useHistory: false` | `next/navigation`'s `router.push` / `router.replace` | RSC refetches on every URL change | URL state must refetch server data (e.g. `searchParams` drives a DB query in the page) |
+
+```typescript
+useUrlState(FORM_STATE, { searchParams, useHistory: false });
+```
+
+Default is `true`. Flip to `false` only when the server page needs to re-render with the new query.
+
+### Decoding state on the server for data fetching
+
+```typescript
+// app/jobs/page.tsx
+import { decodeState } from 'state-in-url/encodeState';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+import { fetchJobs } from 'lib/jobs';
+
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  const state = decodeState(new URLSearchParams(sp as Record<string, string>), JOBS_STATE);
+  const jobs = await fetchJobs({ status: state.status });
+  return <JobsList searchParams={sp} jobs={jobs} />;
+}
+```
+
+### Reading URL state in a server layout (Proxy workaround)
+
+Server layouts don't receive `searchParams`. Set up a Proxy (Next.js 16+ — `middleware.ts` still works as a deprecated alias) to surface the query string as a request header, then decode in the layout. With this setup the layout renders correctly on first paint with no extra rerenders.
+
+```typescript
+// proxy.ts  (or middleware.ts, same content)
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+export function proxy(request: NextRequest) {
+  const sp = (request.url.includes('_next') ? '' : request.url).split('?')[1] ?? '';
+  const headers = new Headers(request.headers);
+  headers.set('searchParams', sp);
+  return NextResponse.next({ request: { headers } });
+}
+```
+
+```typescript
+// app/jobs/layout.tsx
+import { headers } from 'next/headers';
+import { decodeState } from 'state-in-url/encodeState';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export default async function Layout({ children }: { children: React.ReactNode }) {
+  const sp = (await headers()).get('searchParams') ?? '';
+  const initial = decodeState(sp, JOBS_STATE);
+
+  return (
+    <>
+      <LayoutHeader initial={initial} />
+      {children}
+    </>
+  );
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Not passing `searchParams` in Next.js App Router
+
+Wrong:
+
+```typescript
+// page.tsx (server)
+export default function Page() { return <Form />; }
+
+// Form.tsx (client)
+const { urlState } = useUrlState(FORM_STATE);  // missing searchParams
+```
+
+Correct:
+
+```typescript
+// page.tsx
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  return <Form searchParams={sp} />;
+}
+
+// Form.tsx
+const { urlState } = useUrlState(FORM_STATE, { searchParams });
+```
+
+`searchParams` makes the **initial** state correct. Without it, the first render uses defaults, then a client `useEffect` re-syncs from the URL on the next tick — causing a visible flash and a hydration warning. URL state still survives refresh either way (URL is the source of truth), but the initial paint is wrong. With a Proxy feeding the layout, no extra rerender happens at all. Most common Next.js issue (#40, #60).
+
+Source: GitHub issues #40, #60 (asmyshlyaev177/state-in-url); maintainer interview
+
+### HIGH Forgetting to await `searchParams` in Next.js 15+
+
+Wrong:
+
+```typescript
+export default function Page({ searchParams }) {
+  return <Form searchParams={searchParams} />; // Promise, not the value
+}
+```
+
+Correct:
+
+```typescript
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  return <Form searchParams={sp} />;
+}
+```
+
+Next.js 15 changed page-level `searchParams` to a Promise. The library silently decodes nothing from an unresolved Promise.
+
+Source: Next.js 15 migration notes
+
+### HIGH Using `state-in-url/next` in a Pages Router project
+
+Wrong:
+
+```typescript
+// pages/index.tsx
+import { useUrlState } from 'state-in-url/next'; // imports next/navigation
+```
+
+Correct:
+
+Use App Router (`app/` directory). The library does not support Pages Router and there are no plans to add support. If you must stay on Pages Router, build a custom hook with `useUrlStateBase` and a `next/router`-backed router object.
+
+Source: README "Gotchas" #3
+
+### MEDIUM Setting `useHistory: false` unnecessarily
+
+Wrong:
+
+```typescript
+useUrlState(FORM_STATE, { searchParams, useHistory: false });
+// every keystroke triggers a Next.js _rsc payload fetch
+```
+
+Correct:
+
+```typescript
+useUrlState(FORM_STATE, { searchParams });
+// useHistory defaults to true → window.history, no server round-trip
+```
+
+`useHistory: false` is only correct when the server page must re-fetch on URL changes. For UI-only state (filters, drawers, tabs) it triples request traffic.
+
+Source: JSDoc on `useUrlState` params; vercel/next.js#59167
+
+### MEDIUM Trying to read `searchParams` in a server layout directly
+
+Wrong:
+
+```typescript
+export default function Layout({ children, searchParams }: any) {
+  // searchParams is always undefined in layouts
+}
+```
+
+Correct:
+
+Use the Proxy + header pattern shown above (`proxy.ts` setting `searchParams` header → layout reads via `headers()` and `decodeState`). With this in place there is no initial lag or extra rerender.
+
+Source: README "Using hook in layout component"; packages/example-nextjs16/src/middleware.ts; maintainer interview
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern; required reading.
+- `state-in-url/input-handling` — for text-input UX with the Next.js hook.

package/skills/react-router-remix-setup/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: react-router-remix-setup
+description: >
+  Set up useUrlState for React Router v7 (state-in-url/react-router), React
+  Router v6 (state-in-url/react-router6 — moved here in 6.0.0), and Remix v2
+  (state-in-url/remix). The hook API is identical across all three; only the
+  import path and per-call NavigateOptions (preventScrollReset, state, replace)
+  differ. Load this skill when wiring useUrlState into any non-Next.js
+  React router or migrating from an older import path.
+type: framework
+library: state-in-url
+framework: react
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/react-router/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/react-router6/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/remix/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:CHANGELOG.md#600-2025-08-05'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — React Router and Remix
+
+The hook signature, return shape, and behavior of `useUrlState` are identical across React Router v6, v7, and Remix v2. Three things differ:
+
+| Aspect | Difference |
+|---|---|
+| Import path | `state-in-url/react-router` (v7), `state-in-url/react-router6` (v6), `state-in-url/remix` (Remix v2) |
+| `setUrl` per-call options | Accepts `NavigateOptions` from `react-router` (e.g. `preventScrollReset`, `state`, `replace`) |
+| SSR | Remix v2 routes can hydrate from loader data; React Router CSR-only by default |
+
+## Setup
+
+### React Router v7
+
+```typescript
+import { useUrlState } from 'state-in-url/react-router';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+### React Router v6 (since state-in-url 6.0.0)
+
+```typescript
+// Note the /react-router6 subpath
+import { useUrlState } from 'state-in-url/react-router6';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+### Remix v2
+
+```typescript
+import { useUrlState } from 'state-in-url/remix';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export default function Route() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+## Core Patterns
+
+### Pass NavigateOptions per call
+
+```typescript
+setUrl({ tab: 'b' }, { replace: false, preventScrollReset: true });
+```
+
+`replace: false` creates a new history entry (push) instead of replacing.
+`preventScrollReset: true` keeps the page scroll position after the navigation — important when URL state controls in-page UI rather than route content.
+
+### `basename` support
+
+Both `useUrlState` hooks for React Router respect the router's `basename`. No extra configuration is needed in the hook.
+
+```typescript
+// router setup
+<BrowserRouter basename="/admin">
+  <App />
+</BrowserRouter>
+// URL state updates happen at /admin?... not /...
+```
+
+### Functional update preserving other fields
+
+```typescript
+setUrl((curr) => ({ ...curr, page: curr.page + 1 }));
+```
+
+## Common Mistakes
+
+### CRITICAL Importing `/react-router` for a React Router v6 project
+
+Wrong:
+
+```typescript
+// react-router v6 project
+import { useUrlState } from 'state-in-url/react-router'; // targets v7 since 6.0.0
+```
+
+Correct:
+
+```typescript
+import { useUrlState } from 'state-in-url/react-router6';
+```
+
+As of state-in-url v6.0.0 (Aug 2025) the v6 implementation moved to its own subpath. `/react-router` now targets React Router v7 only. Agents trained on older code will use the wrong import.
+
+Source: CHANGELOG v6.0.0 BREAKING CHANGES (asmyshlyaev177/state-in-url)
+
+### HIGH Using the deprecated `useUrlState({ allParamsObj })` signature
+
+Wrong:
+
+```typescript
+useUrlState({ defaultState: FORM_STATE, replace: true }); // removed in v5.0.0
+```
+
+Correct:
+
+```typescript
+useUrlState(FORM_STATE, { replace: true });
+```
+
+state-in-url v5.0.0 removed the old object-wrapped call shape. Defaults are now passed positionally; options go in the second argument.
+
+Source: CHANGELOG v5.0.0 BREAKING CHANGES (asmyshlyaev177/state-in-url)
+
+### CRITICAL `defaultState` defined inside the React component
+
+(Cross-skill failure — also in `feature-state-hook`.)
+
+Wrong:
+
+```typescript
+export function Filters() {
+  const defaults = { sort: 'name' };
+  const { urlState } = useUrlState(defaults);
+}
+```
+
+Correct:
+
+```typescript
+type FiltersState = { sort: 'name' | 'date' };
+const FILTERS_STATE: FiltersState = { sort: 'name' };
+
+export function Filters() {
+  const { urlState } = useUrlState(FILTERS_STATE);
+}
+```
+
+Same identity rule as Next.js. A fresh default object each render breaks sharing and initial-state seeding.
+
+Source: GitHub issues #57, #60, #69 (asmyshlyaev177/state-in-url)
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern.
+- `state-in-url/input-handling` — for text-input UX inside a router-driven page.
+- `state-in-url/form-library-integration` — for pairing with `react-hook-form`.

package/skills/shared-state-no-url/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: shared-state-no-url
+description: >
+  Use useSharedState (from state-in-url, NOT a framework subpath) as a
+  framework-agnostic cross-component state primitive when URL sync is
+  explicitly NOT wanted. Same module-scoped default-state-identity rule
+  as useUrlState. A lightweight Context.Provider replacement that works
+  in React, Next.js, Vite, Remix without setup. Load this skill when the
+  user wants shared state but specifies "no URL", or for state that is
+  sensitive, ephemeral, or too large to live in the URL.
+type: core
+library: state-in-url
+library_version: '6.1.3'
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/useSharedState/'
+  - 'asmyshlyaev177/state-in-url:README.md#usesharedstate-hook-for-reactjs'
+---
+
+# state-in-url — Shared state without URL sync
+
+`useSharedState` is `state-in-url`'s lightweight cross-component state primitive — no Context provider, no Redux, no Zustand store. State is shared between any components that pass the **same module-scoped default-state object** (identity, not deep equality). It is framework-agnostic and has no URL involvement.
+
+**Decision:** use `useUrlState` (see `state-in-url/feature-state-hook`) by default. Reach for `useSharedState` only when the user explicitly opts out of URL sync, or when the state is sensitive / ephemeral / too large for a URL.
+
+## Setup
+
+```typescript
+// features/cart/cartState.ts
+export type CartState = {
+  items: { id: string; qty: number }[];
+  isOpen: boolean;
+};
+
+export const CART_STATE: CartState = {
+  items: [],
+  isOpen: false,
+};
+```
+
+```typescript
+// any component
+'use client';
+import { useSharedState } from 'state-in-url'; // NB: top-level subpath
+
+import { CART_STATE } from 'features/cart/cartState';
+
+export function CartButton() {
+  const { state, setState } = useSharedState(CART_STATE);
+
+  return (
+    <button onClick={() => setState((curr) => ({ ...curr, isOpen: !curr.isOpen }))}>
+      Cart ({state.items.length})
+    </button>
+  );
+}
+```
+
+Any other component calling `useSharedState(CART_STATE)` reads and writes the same store.
+
+## Core Patterns
+
+### Functional update
+
+```typescript
+setState((curr) => ({ ...curr, items: curr.items.concat(newItem) }));
+```
+
+### Read-only `getState` (avoid rerender)
+
+```typescript
+const { getState } = useSharedState(CART_STATE);
+
+const onSubmit = () => {
+  const { items } = getState(); // doesn't subscribe to changes
+  api.checkout(items);
+};
+```
+
+### SSR initial state
+
+```typescript
+const { state } = useSharedState(CART_STATE, () => readFromCookie());
+```
+
+The second-argument function runs once for the initial value (useful for cookie-driven SSR hydration).
+
+## Common Mistakes
+
+### MEDIUM Reaching for `useSharedState` when URL sync is wanted
+
+Wrong:
+
+```typescript
+// Filters that the user wants to share via copy/paste link
+const { state, setState } = useSharedState(FILTERS_STATE);
+// Page refresh loses everything. Link sharing impossible.
+```
+
+Correct:
+
+```typescript
+import { useUrlState } from 'state-in-url/next';
+const { urlState, setUrl } = useUrlState(FILTERS_STATE, { searchParams });
+```
+
+`useSharedState` has no URL involvement. Pick `useUrlState` whenever state should survive a refresh or be shareable; pick `useSharedState` only when the user explicitly says "no URL".
+
+Source: Maintainer interview
+
+### HIGH Default state defined inside the React component
+
+Wrong:
+
+```typescript
+function CartButton() {
+  const initial = { items: [], isOpen: false };
+  useSharedState(initial); // different identity in every component → no sharing
+}
+```
+
+Correct:
+
+```typescript
+// cartState.ts (module scope)
+export type CartState = { items: { id: string; qty: number }[]; isOpen: boolean };
+export const CART_STATE: CartState = { items: [], isOpen: false };
+
+function CartButton() {
+  useSharedState(CART_STATE);
+}
+```
+
+Same identity-based sharing rule as `useUrlState`. A non-static default breaks cross-component sharing silently — each call creates an independent store.
+
+Source: Inferred from `useUrlState` pattern (shared internals)
+
+### MEDIUM Storing actual secrets in shared state
+
+Wrong:
+
+```typescript
+const SESSION_STATE = { token: '', userId: '' };
+useSharedState(SESSION_STATE);
+```
+
+Correct:
+
+Use a proper auth store (cookies, secure storage, framework auth helper). `useSharedState` is in-memory and reasonable for app state, but it's not a vault — any component on the page can read it via the shared identity.
+
+## When NOT to use this skill
+
+- The data should be shareable by URL → `state-in-url/feature-state-hook` instead.
+- The data is server cache (lists, paginated queries) → `@tanstack/react-query` or `swr`.
+- The data is persisted user prefs across sessions → `localStorage` or a settings API.
+
+## See also
+
+- `state-in-url/feature-state-hook` — when URL sync IS wanted (the default choice).