searchsocket 0.4.0 → 0.5.0

package/README.md

@@ -14,9 +14,9 @@ Semantic site search and MCP retrieval for SvelteKit content projects.
 - **SvelteKit Integrations**:
   - `searchsocketHandle()` for `POST /api/search` endpoint
   - `searchsocketVitePlugin()` for build-triggered indexing
-- **Client Library**: `createSearchClient()` for browser-side search
+- **Client Library**: `createSearchClient()` for browser-side search, `buildResultUrl()` for scroll-to-section links
+- **Scroll-to-Text**: `searchsocketScrollToText()` auto-scrolls to matching sections on navigation
 - **MCP Server**: Model Context Protocol tools for search and page retrieval
-- **Git-Tracked Markdown Mirror**: Commit-safe deterministic markdown outputs
 
 ## Install
 
@@ -291,6 +291,53 @@ for (const result of response.results) {
 }
 ```
 
+## Scroll-to-Text Navigation
+
+When a visitor clicks a search result, SearchSocket can automatically scroll them to the relevant section on the destination page. This uses two utilities:
+
+### `buildResultUrl(result)`
+
+Builds a URL from a search result that includes:
+- A `_ssk` query parameter for SvelteKit client-side navigation (read by `searchsocketScrollToText`)
+- A [Text Fragment](https://developer.mozilla.org/en-US/docs/Web/URI/Fragment/Text_fragments) (`#:~:text=`) for native browser scroll-to-text on full page loads (Chrome 80+, Safari 16.1+, Firefox 131+)
+
+Import from `searchsocket/client`:
+
+```ts
+import { createSearchClient, buildResultUrl } from "searchsocket/client";
+
+const client = createSearchClient();
+const { results } = await client.search({ q: "installation" });
+
+// Use in your search UI
+for (const result of results) {
+  const href = buildResultUrl(result);
+  // "/docs/getting-started?_ssk=Installation#:~:text=Installation"
+}
+```
+
+If the result has no `sectionTitle`, the original URL is returned unchanged.
+
+### `searchsocketScrollToText`
+
+A SvelteKit `afterNavigate` hook that reads the `_ssk` parameter and scrolls the matching heading into view. Add it to your root layout:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { afterNavigate } from '$app/navigation';
+  import { searchsocketScrollToText } from 'searchsocket/sveltekit';
+
+  afterNavigate(searchsocketScrollToText);
+</script>
+```
+
+The hook:
+- Matches headings (h1–h6) case-insensitively with whitespace normalization
+- Falls back to a broader text node search if no heading matches
+- Scrolls smoothly to the first match
+- Is a silent no-op when `_ssk` is absent or no match is found
+
 ## Vector Backend: Turso/libSQL
 
 SearchSocket uses **Turso** (libSQL) as its single vector backend, providing a unified experience across development and production.
@@ -399,7 +446,6 @@ The built-in `InMemoryRateLimiter` auto-disables on serverless platforms (it res
 
 The following features are only used during `searchsocket index` (CLI), not the search handler:
 - `ensureStateDirs` — creates `.searchsocket/` state directories
-- Markdown mirror — writes `.searchsocket/mirror/` files
 - Local SQLite fallback — only needed when `TURSO_DATABASE_URL` is not set
 
 ### Adapter Guidance
@@ -537,34 +583,6 @@ SEARCHSOCKET_AUTO_INDEX=1 pnpm build
 SEARCHSOCKET_DISABLE_AUTO_INDEX=1 pnpm build
 ```
 
-## Git-Tracked Markdown Mirror
-
-Indexing writes a **deterministic markdown mirror**:
-
-```
-.searchsocket/pages/<scope>/<path>.md
-```
-
-Example:
-```
-.searchsocket/pages/main/docs/intro.md
-```
-
-Each file contains:
-- Frontmatter: URL, title, scope, route file, metadata
-- Markdown: Extracted content
-
-**Why commit it?**
-- Content workflows (edit markdown, regenerate embeddings)
-- Version control for indexed content
-- Debugging (see exactly what was indexed)
-- Offline search (grep the mirror)
-
-Add to `.gitignore` if you don't need it:
-```
-.searchsocket/pages/
-```
-
 ## Commands
 
 ### `searchsocket init`