Deep-link Search By mode via URL hash

[nfvelten]

Closes #1228.

Search By mode (General/Author/Title/Series/Manual), content type and the search query now live in the URL as a hash fragment, updated live as you search, not just parsed once on load. A shared/bookmarked link like #search_by=manual&q=foundation reopens in that exact mode with the query filled in.

Following the direction from the issue thread:

• Hash fragment instead of query string, so it stays browser side only.
• Live updates via history.replaceState, no history spam per keystroke.
• Default Search By persisted in a client side cookie as fallback when there's no hash, no user accounts needed.

Tested manually against a local build (search-by switching, hash live update, deep link reload, cookie fallback when there's no hash, and hash overriding a stale cookie).

[calibrain]

Hey, thank you so much for the contribution !
I took a look, and had claude summarize some of my thoughts and issues, could you take a look ?

1. Existing query-string deep links break, and the docs still document them

useUrlSearch now reads only window.location.hash (hooks/useUrlSearch.ts:51), and useSearchParams is gone. But docs/url-search-parameters.md (linked from docs/index.md) documents /?q=harry+potter, /?q=dune&content_type=audiobook, and friends — those, plus any bookmarks users already made, now load a blank app with no indication why.

The hash was the right call for the new live-reflected state, but I don't think we want to drop what already shipped. Could we parse the query string as a fallback when the hash is empty — ideally rewriting ?… → #… once on load so the two don't drift — and update the doc either way?

2. Non-general Search By targets don't round-trip: the hash the app writes reopens as a blank or general search

This is the headline use case, and I think it's broken for every target except general:

• Direct mode, author/title/isbn target. The typed value lives in searchInput, not advancedFilters.author — buildCurrentSearchRequest only maps it onto author= at search time (App.tsx:2308). So buildUrlSearchHash writes #search_by=author&q=herbert with no author=. On reload, UrlSearchBootstrapMount.tsx:157 blanks searchInput (because the target isn't general) and then reads advancedFilters.author, which is empty — so it runs a filters-only search while the input shows "herbert" and the selector says Author.
• Universal mode, provider-field target (series, hardcover_list). The bootstrap never passes fieldValues the way the normal dispatch path does, so #search_by=series&q=dune executes a plain general query while the selector reads Series.
• #search_by=manual&q=foundation — the example in the PR description — runs a normal universal search rather than handleManualSearch's release flow.

I think this needs fixing on both sides: have buildUrlSearchHash emit the value under the target's own param for direct fields, and have the bootstrap route q through the active target (fieldValues for provider fields, the direct filter for direct fields, and no auto-search for manual).

3. The cookie is written from the derived fallback, not the user's choice

App.tsx:1965 persists effectiveActiveQueryTarget, which is the re-validated value, not what the user picked. Three ways that destroys the preference it's meant to protect:

• On a cold load, before the metadata search_fields fetch resolves, queryTargets is just [general], so effectiveActiveQueryTarget collapses to general and immediately overwrites a stored author/series cookie. It self-heals once the fields arrive — but not if the tab is closed first, or the fetch fails.
• Clicking the logo (App.tsx:2429) and logging out (App.tsx:668) both set general, wiping the stored default. That's exactly the "bookmark that lands in Manual mode" case from the issue.
• view_series browse sets the target programmatically (App.tsx:2249), so series silently becomes a sticky default the user never chose.

Persisting only on an explicit selector change (onQueryTargetChange, App.tsx:2452 / :2519) would avoid all three.

4. replaceState fires on every keystroke

searchInput updates per character (App.tsx:2086) → memo → effect → history.replaceState (useUrlSearch.ts:93). Safari throws SecurityError past roughly 100 replaceState calls per 30 seconds, and there's no try/catch, so it surfaces as an uncaught error inside a React effect. (The "no history spam" note in the description covers pushState vs replaceState, but not call volume.) A ~300ms debounce plus a try/catch around the call should cover it.

Worth a look

5. Pasting a shared link into an already-open tab does nothing. A hash-only change doesn't reload the document and there's no hashchange listener, so nothing reacts — and then the sync effect rewrites the URL back to the current state on the next change, making the link look broken. Either listen for hashchange and re-bootstrap, or call the limitation out in the docs.

6. The queryTargets race fixes the selector but not the search. The retry effect at App.tsx:1950 re-applies search_by once targets load, but by then the bootstrap search has already run against the wrong target, and the sync effect has rewritten the hash without search_by — so a deep link whose target hasn't loaded yet quietly mutates the URL that was shared. The comment acknowledges the race; the remedy stops one step short.

Nits

• parseUrlSearchParams lowercases search_by, but the builder writes the raw target key. Every built-in provider field key is lowercase today, so this is fine now — but a custom provider (per shelfmark/metadata_providers/README.md) with a camelCase field key would silently never match.
• The @example block in parseUrlSearchParams.ts still shows /?q=harry+potter style URLs, which are now hash-only.
• A cookie is sent on every HTTP request; localStorage is a better fit for a purely client-side UI preference. Not a blocker — just flagging since "cookie" in the issue thread was probably shorthand for "client-side".

[calibrain]

thank you so much !

[nfvelten]

@calibrain happy to help, I use Shelfmark pretty much daily so this one was for me too. Thanks for the quick merge.

One thing I noticed while testing that wasn't in your review: the hash picks up the default filters, so a plain author search ends up as #q=herbert&search_by=author&sort=relevance&lang=default&format=epub&format=mobi&format=azw3&format=fb2&format=djvu&format=cbz&format=cbr. Shared links get long fast, and my own comment in the builder claims a default-state URL carries no hash at all, which isn't true. Want a small follow up that omits filters still sitting at their defaults?

[calibrain]

sure, no use keeping empty / default values in the url !