state-in-url 6.1.3 → 6.2.1

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.1",
   "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",
@@ -480,7 +483,7 @@
     "happy-dom": "^20.0.2",
     "husky": "^9.1.7",
     "lint-staged": "^15.5.2",
-    "next": "^15.5.18",
+    "next": "^15.5.19",
     "nyc": "^17.1.0",
     "only-allow": "^1.2.1",
     "pin-github-action": "^1.9.1",
@@ -489,8 +492,7 @@
     "prettier-plugin-tailwindcss": "^0.6.14",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "react-router": "^7.15.0",
-    "ringfence": "^0.1.0",
+    "react-router": "^7.17.0",
     "rollup": "^4.52.3",
     "rollup-plugin-esbuild": "^6.2.1",
     "rollup-plugin-filesize": "^10.0.0",
@@ -557,7 +559,8 @@
     "search",
     "encode url",
     "decode url",
-    "fast"
+    "fast",
+    "tanstack-intent"
   ],
   "packageManager": "pnpm@10.26.0",
   "pnpm": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "6.1.3",
+  "version": "6.2.1",
   "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",
@@ -480,7 +483,7 @@
     "happy-dom": "^20.0.2",
     "husky": "^9.1.7",
     "lint-staged": "^15.5.2",
-    "next": "^15.5.18",
+    "next": "^15.5.19",
     "nyc": "^17.1.0",
     "only-allow": "^1.2.1",
     "pin-github-action": "^1.9.1",
@@ -489,8 +492,7 @@
     "prettier-plugin-tailwindcss": "^0.6.14",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "react-router": "^7.15.0",
-    "ringfence": "^0.1.0",
+    "react-router": "^7.17.0",
     "rollup": "^4.52.3",
     "rollup-plugin-esbuild": "^6.2.1",
     "rollup-plugin-filesize": "^10.0.0",
@@ -557,7 +559,8 @@
     "search",
     "encode url",
     "decode url",
-    "fast"
+    "fast",
+    "tanstack-intent"
   ],
   "packageManager": "pnpm@10.26.0",
   "pnpm": {

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).