searchsocket 0.3.3 → 0.5.0

package/README.md

@@ -6,17 +6,17 @@ Semantic site search and MCP retrieval for SvelteKit content projects.
 
 ## Features
 
-- **Embeddings**: Jina AI `jina-embeddings-v3` with task-specific LoRA adapters (configurable)
+- **Embeddings**: Jina AI `jina-embeddings-v5-text-small` with task-specific LoRA adapters (configurable)
 - **Vector Backend**: Turso/libSQL with vector search (local file DB for development, remote for production)
-- **Rerank**: Optional Jina reranker — same API key, one boolean to enable
+- **Rerank**: Jina `jina-reranker-v3` enabled by default — same API key
 - **Page Aggregation**: Group results by page with score-weighted chunk decay
 - **Meta Extraction**: Automatically extracts `<meta name="description">` and `<meta name="keywords">` for improved relevance
 - **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
 
@@ -163,7 +163,7 @@ pnpm searchsocket search --q "getting started" --top-k 5 --path-prefix /docs
   "meta": {
     "timingsMs": { "embed": 120, "vector": 15, "rerank": 0, "total": 135 },
     "usedRerank": false,
-    "modelId": "jina-embeddings-v3"
+    "modelId": "jina-embeddings-v5-text-small"
   }
 }
 ```
@@ -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
@@ -416,9 +462,9 @@ SearchSocket uses **Jina AI's embedding models** to convert text into semantic v
 
 ### Default Model
 
-- **Model**: `jina-embeddings-v3`
+- **Model**: `jina-embeddings-v5-text-small`
 - **Dimensions**: 1024 (default)
-- **Cost**: ~$0.00002 per 1K tokens (generous 10M token free tier)
+- **Cost**: ~$0.00005 per 1K tokens
 - **Task adapters**: Uses `retrieval.passage` for indexing, `retrieval.query` for search queries (LoRA task-specific adapters for better retrieval quality)
 
 ### How It Works
@@ -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`
@@ -612,7 +630,7 @@ pnpm searchsocket status
 # Output:
 # project: my-site
 # resolved scope: main
-# embedding model: jina-embeddings-v3
+# embedding model: jina-embeddings-v5-text-small
 # vector backend: turso/libsql (local (.searchsocket/vectors.db))
 # vector health: ok
 # last indexed (main): 2025-02-23T10:30:00Z
@@ -865,7 +883,7 @@ export default {
 
   embeddings: {
     provider: "jina",
-    model: "jina-embeddings-v3",
+    model: "jina-embeddings-v5-text-small",
     apiKey: "jina_...",          // direct API key (or use apiKeyEnv)
     apiKeyEnv: "JINA_API_KEY",
     batchSize: 64,
@@ -886,7 +904,7 @@ export default {
   rerank: {
     enabled: true,
     topN: 20,
-    model: "jina-reranker-v2-base-multilingual"
+    model: "jina-reranker-v3"
   },
 
   ranking: {