{"owner":"47ng","repo":"nuqs","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS GUIDE\n\nOperational instructions for autonomous coding / AI agents contributing to the nuqs repository.\n\n**nuqs** is a library for type-safe URL query string ↔ React state synchronization with minimal bundle size and zero dependencies.\n\nRefer to: [README.md](README.md) & [CONTRIBUTING.md](CONTRIBUTING.md) for authoritative detail.\n\n---\n\n## Essential Context\n\n### Repository Structure (Monorepo)\n\n- **Library source:** `packages/nuqs`\n- **Documentation app** (Next.js + Fumadocs): `packages/docs`\n  - MDX content: `packages/docs/content`\n- **End-to-end test benches:** `packages/e2e`\n  - Framework targets: Next.js app/pages, React SPA, Remix, TanStack Router, React Router v6/v7/v8\n- **Examples:** `packages/examples/*`\n\n### Core Concepts (nuqs)\n\n- **Goal:** Type-safe URL query string ↔ React state sync.\n- **Main Hooks:**\n  - `useQueryState(key, parserOrConfig)`\n  - `useQueryStates(configObject, options)`\n- **Parsers:** Provide `parse` & `serialize`; enhanced with `.withDefault()` & `.withOptions()`\n- **Batching & Throttling:** Multiple state updates in one tick are merged; URL updates throttled (≥50ms)\n- **Key Principles:**\n  1. URL = single source of truth\n  2. Serialization must be lossless & pure\n  3. Defaults are internal (not written to URL)\n  4. Invalid parse → return `null`\n\n### Configuration\n\n- **Package manager:** `pnpm`\n- **New worktrees:** With Git 2.54+, run `node --run setup:hooks` once per trusted clone to auto-install dependencies after `git worktree add`. If the hook skips (branch manifests differ from `origin/HEAD`), review the branch and run `node --run setup:worktree` in the worktree.\n- **Build:** `pnpm build`\n- **Test suite:** `pnpm test` (5-10 minutes; includes build + unit + typing + e2e)\n- **Focused tests:** Use the root Turbo command, for example `pnpm run test --filter nuqs` or `pnpm run test --filter e2e-next`. Do not invoke package test scripts directly.\n- **Development:** `pnpm dev --filter <package-name>...` (triple dots start dependencies' dev script too)\n\n---\n\n## Development Guidelines\n\nFor detailed development guidelines organized by task, see:\n\n- **[Adapter Development](.agents/docs/adapter-development.md)** — Adding framework adapters\n- **[Parser Implementation](.agents/docs/parser-implementation.md)** — Creating custom parsers\n- **[API Design & Architecture](.agents/docs/api-design.md)** — Design principles, extensibility, type safety\n- **[Testing Patterns](.agents/docs/testing.md)** — Unit, type-level, and e2e testing strategies\n- **[Release & Git Workflow](.agents/docs/git-workflow.md)** — Conventional commits, semantic versioning, PR standards\n- **[Quality Standards](.agents/docs/quality-standards.md)** — Checklists, performance, security, anti-patterns\n\n---\n\n## Quick Reference: Common Tasks\n\n| Task                    | Guide                                                                             |\n| ----------------------- | --------------------------------------------------------------------------------- |\n| Fix a bug               | See [Testing Patterns](.agents/docs/testing.md) → Regression                      |\n| Add a new parser        | See [Parser Implementation](.agents/docs/parser-implementation.md)                |\n| Add a framework adapter | See [Adapter Development](.agents/docs/adapter-development.md)                    |\n| Improve performance     | See [API Design](.agents/docs/api-design.md) → Performance & Reliability          |\n| Update documentation    | See [Release & Git Workflow](.agents/docs/git-workflow.md) → Documentation        |\n| Prepare a pull request  | See [Release & Git Workflow](.agents/docs/git-workflow.md) → PR Quality Checklist |\n\n---\n\n## Debugging\n\nImport the opt-in debug bundle once in each runtime where logs are needed:\n\n```ts\nimport 'nuqs/debug'\n```\n\nThen enable debug logs in the browser console and reload the page:\n\n```js\nlocalStorage.setItem('debug', 'nuqs')\n```\n\nIn server or Node environments (e.g. when using `nuqs/server`), set the `DEBUG` environment variable so it contains `nuqs`:\n\n```bash\nDEBUG=nuqs pnpm dev\n```\n\nHook-level logs are prefixed with `[nuq+ …]`; internal subsystems use `[nuqs <subsystem>]` (see `packages/nuqs/src/lib/debug-messages.ts` for the catalog).\n\nEncourage debug logs in issue reports and include them in reproduction scripts.\n\n---\n\n## Exit Conditions for Agent Tasks\n\nA task is **DONE** when:\n\n- All checklist items satisfied\n- Tests pass locally (`pnpm test`)\n- Docs consistent with behavior\n- No unresolved TODOs introduced\n- No stray console logs (except controlled debug support)\n"},"files":{"AGENTS.md":"# AGENTS GUIDE\n\nOperational instructions for autonomous coding / AI agents contributing to the nuqs repository.\n\n**nuqs** is a library for type-safe URL query string ↔ React state synchronization with minimal bundle size and zero dependencies.\n\nRefer to: [README.md](README.md) & [CONTRIBUTING.md](CONTRIBUTING.md) for authoritative detail.\n\n---\n\n## Essential Context\n\n### Repository Structure (Monorepo)\n\n- **Library source:** `packages/nuqs`\n- **Documentation app** (Next.js + Fumadocs): `packages/docs`\n  - MDX content: `packages/docs/content`\n- **End-to-end test benches:** `packages/e2e`\n  - Framework targets: Next.js app/pages, React SPA, Remix, TanStack Router, React Router v6/v7/v8\n- **Examples:** `packages/examples/*`\n\n### Core Concepts (nuqs)\n\n- **Goal:** Type-safe URL query string ↔ React state sync.\n- **Main Hooks:**\n  - `useQueryState(key, parserOrConfig)`\n  - `useQueryStates(configObject, options)`\n- **Parsers:** Provide `parse` & `serialize`; enhanced with `.withDefault()` & `.withOptions()`\n- **Batching & Throttling:** Multiple state updates in one tick are merged; URL updates throttled (≥50ms)\n- **Key Principles:**\n  1. URL = single source of truth\n  2. Serialization must be lossless & pure\n  3. Defaults are internal (not written to URL)\n  4. Invalid parse → return `null`\n\n### Configuration\n\n- **Package manager:** `pnpm`\n- **New worktrees:** With Git 2.54+, run `node --run setup:hooks` once per trusted clone to auto-install dependencies after `git worktree add`. If the hook skips (branch manifests differ from `origin/HEAD`), review the branch and run `node --run setup:worktree` in the worktree.\n- **Build:** `pnpm build`\n- **Test suite:** `pnpm test` (5-10 minutes; includes build + unit + typing + e2e)\n- **Focused tests:** Use the root Turbo command, for example `pnpm run test --filter nuqs` or `pnpm run test --filter e2e-next`. Do not invoke package test scripts directly.\n- **Development:** `pnpm dev --filter <package-name>...` (triple dots start dependencies' dev script too)\n\n---\n\n## Development Guidelines\n\nFor detailed development guidelines organized by task, see:\n\n- **[Adapter Development](.agents/docs/adapter-development.md)** — Adding framework adapters\n- **[Parser Implementation](.agents/docs/parser-implementation.md)** — Creating custom parsers\n- **[API Design & Architecture](.agents/docs/api-design.md)** — Design principles, extensibility, type safety\n- **[Testing Patterns](.agents/docs/testing.md)** — Unit, type-level, and e2e testing strategies\n- **[Release & Git Workflow](.agents/docs/git-workflow.md)** — Conventional commits, semantic versioning, PR standards\n- **[Quality Standards](.agents/docs/quality-standards.md)** — Checklists, performance, security, anti-patterns\n\n---\n\n## Quick Reference: Common Tasks\n\n| Task                    | Guide                                                                             |\n| ----------------------- | --------------------------------------------------------------------------------- |\n| Fix a bug               | See [Testing Patterns](.agents/docs/testing.md) → Regression                      |\n| Add a new parser        | See [Parser Implementation](.agents/docs/parser-implementation.md)                |\n| Add a framework adapter | See [Adapter Development](.agents/docs/adapter-development.md)                    |\n| Improve performance     | See [API Design](.agents/docs/api-design.md) → Performance & Reliability          |\n| Update documentation    | See [Release & Git Workflow](.agents/docs/git-workflow.md) → Documentation        |\n| Prepare a pull request  | See [Release & Git Workflow](.agents/docs/git-workflow.md) → PR Quality Checklist |\n\n---\n\n## Debugging\n\nImport the opt-in debug bundle once in each runtime where logs are needed:\n\n```ts\nimport 'nuqs/debug'\n```\n\nThen enable debug logs in the browser console and reload the page:\n\n```js\nlocalStorage.setItem('debug', 'nuqs')\n```\n\nIn server or Node environments (e.g. when using `nuqs/server`), set the `DEBUG` environment variable so it contains `nuqs`:\n\n```bash\nDEBUG=nuqs pnpm dev\n```\n\nHook-level logs are prefixed with `[nuq+ …]`; internal subsystems use `[nuqs <subsystem>]` (see `packages/nuqs/src/lib/debug-messages.ts` for the catalog).\n\nEncourage debug logs in issue reports and include them in reproduction scripts.\n\n---\n\n## Exit Conditions for Agent Tasks\n\nA task is **DONE** when:\n\n- All checklist items satisfied\n- Tests pass locally (`pnpm test`)\n- Docs consistent with behavior\n- No unresolved TODOs introduced\n- No stray console logs (except controlled debug support)\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS GUIDE\n\nOperational instructions for autonomous coding / AI agents contributing to the nuqs repository.\n\n**nuqs** is a library for type-safe URL query string ↔ React state synchronization with minimal bundle size and zero dependencies.\n\nRefer to: [README.md](README.md) & [CONTRIBUTING.md](CONTRIBUTING.md) for authoritative detail.\n\n---\n\n## Essential Context\n\n### Repository Structure (Monorepo)\n\n- **Library source:** `packages/nuqs`\n- **Documentation app** (Next.js + Fumadocs): `packages/docs`\n  - MDX content: `packages/docs/content`\n- **End-to-end test benches:** `packages/e2e`\n  - Framework targets: Next.js app/pages, React SPA, Remix, TanStack Router, React Router v6/v7/v8\n- **Examples:** `packages/examples/*`\n\n### Core Concepts (nuqs)\n\n- **Goal:** Type-safe URL query string ↔ React state sync.\n- **Main Hooks:**\n  - `useQueryState(key, parserOrConfig)`\n  - `useQueryStates(configObject, options)`\n- **Parsers:** Provide `parse` & `serialize`; enhanced with `.withDefault()` & `.withOptions()`\n- **Batching & Throttling:** Multiple state updates in one tick are merged; URL updates throttled (≥50ms)\n- **Key Principles:**\n  1. URL = single source of truth\n  2. Serialization must be lossless & pure\n  3. Defaults are internal (not written to URL)\n  4. Invalid parse → return `null`\n\n### Configuration\n\n- **Package manager:** `pnpm`\n- **New worktrees:** With Git 2.54+, run `node --run setup:hooks` once per trusted clone to auto-install dependencies after `git worktree add`. If the hook skips (branch manifests differ from `origin/HEAD`), review the branch and run `node --run setup:worktree` in the worktree.\n- **Build:** `pnpm build`\n- **Test suite:** `pnpm test` (5-10 minutes; includes build + unit + typing + e2e)\n- **Focused tests:** Use the root Turbo command, for example `pnpm run test --filter nuqs` or `pnpm run test --filter e2e-next`. Do not invoke package test scripts directly.\n- **Development:** `pnpm dev --filter <package-name>...` (triple dots start dependencies' dev script too)\n\n---\n\n## Development Guidelines\n\nFor detailed development guidelines organized by task, see:\n\n- **[Adapter Development](.agents/docs/adapter-development.md)** — Adding framework adapters\n- **[Parser Implementation](.agents/docs/parser-implementation.md)** — Creating custom parsers\n- **[API Design & Architecture](.agents/docs/api-design.md)** — Design principles, extensibility, type safety\n- **[Testing Patterns](.agents/docs/testing.md)** — Unit, type-level, and e2e testing strategies\n- **[Release & Git Workflow](.agents/docs/git-workflow.md)** — Conventional commits, semantic versioning, PR standards\n- **[Quality Standards](.agents/docs/quality-standards.md)** — Checklists, performance, security, anti-patterns\n\n---\n\n## Quick Reference: Common Tasks\n\n| Task                    | Guide                                                                             |\n| ----------------------- | --------------------------------------------------------------------------------- |\n| Fix a bug               | See [Testing Patterns](.agents/docs/testing.md) → Regression                      |\n| Add a new parser        | See [Parser Implementation](.agents/docs/parser-implementation.md)                |\n| Add a framework adapter | See [Adapter Development](.agents/docs/adapter-development.md)                    |\n| Improve performance     | See [API Design](.agents/docs/api-design.md) → Performance & Reliability          |\n| Update documentation    | See [Release & Git Workflow](.agents/docs/git-workflow.md) → Documentation        |\n| Prepare a pull request  | See [Release & Git Workflow](.agents/docs/git-workflow.md) → PR Quality Checklist |\n\n---\n\n## Debugging\n\nImport the opt-in debug bundle once in each runtime where logs are needed:\n\n```ts\nimport 'nuqs/debug'\n```\n\nThen enable debug logs in the browser console and reload the page:\n\n```js\nlocalStorage.setItem('debug', 'nuqs')\n```\n\nIn server or Node environments (e.g. when using `nuqs/server`), set the `DEBUG` environment variable so it contains `nuqs`:\n\n```bash\nDEBUG=nuqs pnpm dev\n```\n\nHook-level logs are prefixed with `[nuq+ …]`; internal subsystems use `[nuqs <subsystem>]` (see `packages/nuqs/src/lib/debug-messages.ts` for the catalog).\n\nEncourage debug logs in issue reports and include them in reproduction scripts.\n\n---\n\n## Exit Conditions for Agent Tasks\n\nA task is **DONE** when:\n\n- All checklist items satisfied\n- Tests pass locally (`pnpm test`)\n- Docs consistent with behavior\n- No unresolved TODOs introduced\n- No stray console logs (except controlled debug support)\n","category":"root","tokens":1144}]}