# URL State Hook

## Objective

Put shareable view state in the URL through one consistent, validated accessor.

A single typed accessor for the filters, tabs, panel positions, and selections the app keeps in its query string.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Identify every screen where a colleague pasting the current URL should see the same thing — filtered lists, selected tabs, opened detail panels, date ranges, search terms — and route all of them through one accessor instead of the several ad hoc parsers already in the codebase.
2. Declare a type and a default for each parameter, and parse defensively: an unknown sort key, a negative page, or a date that does not exist must fall back to the default rather than reaching the query layer.
3. Read and write parameters non-destructively, merging into what is already in the URL so unrelated parameters set by another component, a campaign tag, or a deep link survive untouched.
4. Decide per parameter whether a change pushes a history entry or replaces the current one, and write the decision down. A filter the user deliberately chose deserves a back button; a search box updating as they type does not.
5. Which of the user's arrangements live in the URL and which live in their account is settled by Persistent View Preferences. Anything worth sharing in a link belongs here; anything personal and durable, such as column widths, belongs there. Do not store the same choice in both.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Malformed or hostile values arrive constantly from stale bookmarks, truncated chat links, and hand-edited URLs. Every parameter must be validated and coerced to a safe default rather than passed through to a fetch or a query.
- Writing a parameter must preserve the ones this component knows nothing about — referral tags, an unrelated open panel, a scroll anchor — because clobbering them turns a shared link into a broken one.
- Pushing a history entry for every keystroke buries the previous page under fifty back presses, while replacing a deliberate filter change makes the back button skip it. The choice has to be per parameter and intentional.
- On a server-rendered page the URL is known before the browser is, so the first client render must derive its state from the same parsed URL rather than from a default that then swaps — that swap is a hydration mismatch and a visible flash.
- Two components writing different parameters in the same tick must not overwrite each other; reads must be against the live URL rather than a captured value.
- URLs have practical length limits in browsers, logs, and chat clients, so a long multi-select filter needs a compact encoding or a saved-view identifier instead of a hundred repeated keys.
- Parameters that carry a record identifier the current user may no longer access must degrade to that view's own empty or forbidden state, not a blank screen.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] All shareable view state is read and written through one accessor with declared types and defaults.
- [ ] Invalid, unknown, or out-of-range values fall back to defaults and never reach a query.
- [ ] Writing one parameter leaves every other parameter in the URL intact.
- [ ] Each parameter documents whether it pushes or replaces a history entry, and behaves accordingly.
- [ ] A pasted URL reproduces the same view for another permitted user.
- [ ] The first client render matches the server render for every URL-derived value.
- [ ] URL state and stored view preferences do not both own the same choice.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.