# URL State Management

## Current Status

URL state management is implemented in the current frontend.

The quiz now supports:
- Shareable URLs for in-progress quiz state
- Direct links to product detail views
- Browser refresh without losing the current route context
- Browser back/forward support
- Share buttons on results and product-detail views

## Current URL Parameters

- `b` - accumulated bitwise state for the user selections
- `q` - current question key or `results`
- `p` - product code for direct product-detail views

Examples:

```text
/quiz/?b=16401&q=results
/quiz/?p=404&b=16401
/quiz/product/404
```

## What Is Implemented

### Core State Handling
- `accumulatedBitValue` is tracked in the frontend
- `BIT_DEFINITIONS` constants are present in `script.js`
- `product_bitwise.json` is loaded during startup
- `updateBitValue()` updates the accumulated bitmask from answer filters
- `updateURL()` writes `b` and `q` params without reloading the page
- `initFromURL()` restores the app from query params or direct product routes
- `restoreStateFromBitValue()` rebuilds the key quiz selections from the bitmask
- `startOver()` clears the URL state

### Product Deep Linking
- Product cards open detail views through `showProductByCode()`
- Product detail views push the selected product code into the URL
- Direct query-string product links are supported with `?p=<code>`
- Direct Flask routes are supported with `/quiz/product/<product_code>`

### Share and Navigation Support
- `shareCurrentPage()` copies the current URL to the clipboard when supported
- A notification helper is shown after successful copy
- Share buttons exist on results and product detail screens
- A `popstate` listener handles browser back/forward navigation

## Implementation Notes

The current implementation restores the primary quiz state used by filtering:
- base type
- subtype
- material
- color

That is enough to reopen result sets and product-detail pages consistently.

Dimension data is still primarily driven by the current session flow rather than fully
reconstructed from the URL alone.

## Validation Checklist

- [x] Bitwise data loads at startup
- [x] URLs update as quiz answers are selected
- [x] Results pages can be shared with `b` and `q`
- [x] Product pages can be shared with `p`
- [x] Browser refresh restores route context
- [x] Browser back button is handled in code
- [x] Browser forward button is handled in code
- [ ] Full manual regression testing across all quiz paths

## Known Limits

- URL restoration is designed around the current bitwise filter model, not a complete
    replay of every form interaction.
- Conditional question metadata exists in the navigation data, but the frontend does
    not yet use a fully generic conditional-resolution engine.

## Related Files

- `app/static/js/script.js`
- `app/data/product_bitwise.json`
- `information/BITWISE_USAGE_GUIDE.md`
- `information/REQUIRED_CODE_CHANGES.md`

## Recommended Next Steps

1. Manually test refresh and back/forward behavior on all major quiz branches.
2. Extend restoration if dimension-specific deep linking becomes a requirement.
3. Finish generic conditional navigation so URL restoration and question skipping use the same rules.