feat(browse): highlight search matches and disable infinite scroll while searching (Closes #24)

Wire the FTS5 snippet from /api/search into the browse feed so matched
terms render with <mark> highlighting, and suspend the scroll-triggered
auto-load while a search query is active.

- Preserve the FTS5 snippet through the API client (drop only rank) and
  add it to BrowseItem
- Render highlighted snippets in ContentCard, falling back to the plain
  preview when there is no snippet
- Consolidate the XSS-safe snippet parser into src/lib/snippet.ts, shared
  by the browse card and the command palette; segments render as React
  text children so no dangerouslySetInnerHTML ever touches untrusted
  content (single source of truth for the safety property)
- Add an infiniteScroll prop to ContentFeed; browse-page passes !filters.q
  so scrolling no longer auto-loads mid-search (a manual Load more still
  paginates)
- Style <mark> with the --primary-muted design token
- Bump 0.10.0 -> 0.11.0 + README badge

Closes #24

Author: mikkisguy

README.md

@@ -5,7 +5,7 @@
 
 # ShadowBrain
 
-[![Version](https://img.shields.io/badge/version-0.10.0-yellow)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.11.0-yellow)](CHANGELOG.md)
 
 </div>
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadowbrain",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "scripts": {
     "dev": "next dev",

src/app/browse/api.test.ts

@@ -252,15 +252,45 @@ describe("fetchBrowseItems", () => {
     const call = calls[0];
     expect(call.url).toMatch(/^\/api\/search\?/);
     expect(call.url).toMatch(/q=docker/);
-    // The search-only fields (rank, snippet) must not leak into the
-    // Browse response shape.
+    // `rank` (BM25 score) is search-only and must not leak into the
+    // Browse response shape, but `snippet` is preserved so the card
+    // can render highlighted matches (issue #24).
     expect(result.items).toHaveLength(1);
     const item = result.items[0];
     expect(item).not.toHaveProperty("rank");
-    expect(item).not.toHaveProperty("snippet");
+    expect(item.snippet).toBe("docker <mark>networking</mark>");
     expect(item.id).toBe("x");
   });
 
+  it("preserves the snippet as null when the search row omits it", async () => {
+    nextResponse = () =>
+      new Response(
+        JSON.stringify({
+          query: "docker",
+          results: [
+            {
+              id: "x",
+              type: "note",
+              title: null,
+              content: "docker networking",
+              source: "manual",
+              source_url: null,
+              created_at: "2026-06-21T00:00:00.000Z",
+              updated_at: "2026-06-21T00:00:00.000Z",
+              rank: 1.23,
+            },
+          ],
+          total: 1,
+          page: 1,
+          limit: 20,
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      );
+
+    const result = await fetchBrowseItems({ q: "docker" });
+    expect(result.items[0].snippet).toBeNull();
+  });
+
   it("drops empty filter values from the query string", async () => {
     nextResponse = () =>
       new Response(

src/app/browse/api.ts

@@ -70,8 +70,9 @@ function endpointFor(filters: BrowseFilters): {
     return {
       url: "/api/search",
       // The search endpoint returns `results` (with a `rank` and a
-      // FTS5 `snippet`); we strip those to the canonical BrowseItem
-      // shape so the feed component never has to branch.
+      // FTS5 `snippet`); we keep the `snippet` (the card renders it
+      // with highlighted matches) but drop `rank` to the canonical
+      // BrowseItem shape so the feed component never branches on it.
       mapResults: (body) =>
         Array.isArray(body.results)
           ? (body.results as Record<string, unknown>[]).map(stripSearchOnly)
@@ -127,12 +128,12 @@ function coerceTags(raw: unknown): string[] {
 }
 
 /** The search endpoint carries a `rank` and a `snippet` per row;
- *  the items endpoint does not. Both are valid for the Browse feed,
- *  but the type only declares the shared columns. This normaliser
- *  maps a raw DB row to the canonical `BrowseItem` shape — it
- *  prefixes the `image_path` with `/api/images/`, picks up the
- *  batched `tags`, and drops any search-only fields (`rank`,
- *  `snippet`). */
+ *  the items endpoint does not. This normaliser maps a raw DB row to
+ *  the canonical `BrowseItem` shape — it prefixes the `image_path`
+ *  with `/api/images/`, picks up the batched `tags`, and omits the
+ *  search-only fields. `stripSearchOnly` layers the `snippet` back on
+ *  for search results (it renders as highlighted matches in the card);
+ *  `rank` (BM25 score) is never surfaced to the client. */
 function normaliseItem(row: Record<string, unknown>): BrowseItem {
   return {
     id: String(row.id),
@@ -149,11 +150,18 @@ function normaliseItem(row: Record<string, unknown>): BrowseItem {
   };
 }
 
-/** The search endpoint returns `results` (with a `rank` and a
- *  FTS5 `snippet`); we strip those to the canonical BrowseItem
- *  shape so the feed component never has to branch. */
+/** The search endpoint carries a `rank` (BM25 score) and a `snippet`
+ *  (FTS5 highlight) per row. We keep the `snippet` — the card renders
+ *  it with highlighted matches — but drop `rank` so the canonical
+ *  `BrowseItem` shape stays free of search-only scoring metadata. */
 function stripSearchOnly(row: Record<string, unknown>): BrowseItem {
-  return normaliseItem(row);
+  return { ...normaliseItem(row), snippet: asStringOrNull(row.snippet) };
+}
+
+/** Coerce an unknown value to `string | null` for snippet passthrough.
+ *  Defensive: a missing / non-string `snippet` collapses to `null`. */
+function asStringOrNull(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
 }
 
 export async function fetchBrowseItems(

src/app/browse/browse-page.tsx

@@ -158,6 +158,11 @@ export function BrowsePage() {
         hasMore={hasMore}
         onLoadMore={loadMore}
         cardVariant={cardVariant}
+        // Issue #24: while a search query is active, the feed shows
+        // search results as a finite set — the scroll-triggered
+        // auto-load is suspended (a manual "Load more" still
+        // paginates). Clearing `q` re-enables infinite scroll.
+        infiniteScroll={!filters.q}
         // Clicking a card's tag pill narrows the feed to that tag.
         // `setFilters({ tag })` updates the URL (`?tag=…`) and resets
         // to page 1, exactly like picking the tag from the advanced

src/app/browse/content-card.test.tsx

@@ -258,6 +258,53 @@ describe("ContentCard", () => {
       screen.queryByTestId("content-card-metadata-summary")
     ).not.toBeInTheDocument();
   });
+
+  it("renders the FTS5 snippet with <mark> highlighting matched terms", () => {
+    const item: BrowseItem = {
+      ...baseItem,
+      snippet: "…bridge <mark>networks</mark> are the default…",
+    };
+    render(<ContentCard item={item} />);
+    const snippet = screen.getByTestId("content-card-snippet");
+    const mark = snippet.querySelector("mark");
+    expect(mark).not.toBeNull();
+    expect(mark).toHaveTextContent("networks");
+  });
+
+  it("keeps the line-clamped styling on the snippet paragraph", () => {
+    const item: BrowseItem = { ...baseItem, snippet: "a <mark>b</mark> c" };
+    render(<ContentCard item={item} />);
+    expect(screen.getByTestId("content-card-snippet").className).toMatch(
+      /line-clamp-3/
+    );
+  });
+
+  it("falls back to the plain content preview when there is no snippet", () => {
+    render(<ContentCard item={baseItem} />);
+    // No snippet test id, and the plain preview text is shown.
+    expect(
+      screen.queryByTestId("content-card-snippet")
+    ).not.toBeInTheDocument();
+    expect(screen.getByText(/Bridge networks/)).toBeInTheDocument();
+  });
+
+  it("treats markup inside the snippet as inert text (XSS-safe)", () => {
+    // FTS5's snippet() does not escape source content, so a note
+    // containing a <script> tag would surface in the snippet. We
+    // render segments as React text children, which escape markup —
+    // so no executable element is ever created.
+    const item: BrowseItem = {
+      ...baseItem,
+      snippet: "…<mark>docker</mark><script>alert(1)</script>…",
+    };
+    const { container } = render(<ContentCard item={item} />);
+    expect(container.querySelector("script")).toBeNull();
+    // The matched term still highlights.
+    const mark = screen
+      .getByTestId("content-card-snippet")
+      .querySelector("mark");
+    expect(mark).toHaveTextContent("docker");
+  });
 });
 
 describe("metadataSummary", () => {

src/app/browse/content-card.tsx

@@ -44,6 +44,7 @@ import Link from "next/link";
 import { useMemo, useState } from "react";
 
 import { cn } from "@/lib/utils";
+import { parseSnippet } from "@/lib/snippet";
 import {
   Tooltip,
   TooltipContent,
@@ -222,6 +223,10 @@ export function ContentCard({
     [item.created_at]
   );
   const summary = metadataSummary(item.type, item.metadata);
+  // Parse the FTS5 snippet (search results only) into highlighted
+  // segments. `null` when there is no snippet (the regular list view)
+  // so the card falls back to the plain content preview.
+  const snippetParts = item.snippet ? parseSnippet(item.snippet) : null;
   // When the image 404s, show a text placeholder instead of the
   // browser's default broken-image glyph. The file may genuinely
   // not exist (the image capture pipeline hasn't created it yet),
@@ -325,9 +330,28 @@ export function ContentCard({
           </h3>
         ) : null}
 
-        <p className="text-muted-foreground line-clamp-3 font-sans text-sm leading-relaxed break-words">
-          {previewText(item.content)}
-        </p>
+        {snippetParts ? (
+          // Search result: render the FTS5 snippet with `<mark>`
+          // highlighting the matched terms. Segments are React text
+          // children (auto-escaped), so markup in the source content
+          // is neutralised — see `parseSnippet`.
+          <p
+            data-testid="content-card-snippet"
+            className="text-muted-foreground line-clamp-3 font-sans text-sm leading-relaxed break-words"
+          >
+            {snippetParts.map((part, i) =>
+              part.highlight ? (
+                <mark key={i}>{part.text}</mark>
+              ) : (
+                <span key={i}>{part.text}</span>
+              )
+            )}
+          </p>
+        ) : (
+          <p className="text-muted-foreground line-clamp-3 font-sans text-sm leading-relaxed break-words">
+            {previewText(item.content)}
+          </p>
+        )}
 
         {summary ? (
           <p

src/app/browse/content-feed.test.tsx

@@ -234,6 +234,98 @@ describe("ContentFeed", () => {
     expect(onLoadMore).toHaveBeenCalledOnce();
   });
 
+  it("attaches the scroll observer by default (infinite scroll on)", () => {
+    const observeSpy = vi.spyOn(IntersectionObserver.prototype, "observe");
+    render(
+      <ContentFeed
+        items={[item]}
+        status="success"
+        error={null}
+        onRetry={() => undefined}
+        hasActiveFilters={false}
+        {...defaultProps}
+        hasMore
+      />
+    );
+    expect(observeSpy).toHaveBeenCalled();
+  });
+
+  it("does not attach the scroll observer during an active search (infiniteScroll off)", () => {
+    // Issue #24: while searching, the feed shows results as a finite
+    // set — the IntersectionObserver sentinel must not auto-load.
+    const observeSpy = vi.spyOn(IntersectionObserver.prototype, "observe");
+    render(
+      <ContentFeed
+        items={[item]}
+        status="success"
+        error={null}
+        onRetry={() => undefined}
+        hasActiveFilters={false}
+        {...defaultProps}
+        hasMore
+        infiniteScroll={false}
+      />
+    );
+    expect(observeSpy).not.toHaveBeenCalled();
+    // The sentinel element is still rendered (it doubles as a layout
+    // spacer), but it has no observer attached.
+    expect(screen.getByTestId("feed-sentinel")).toBeInTheDocument();
+  });
+
+  it("detaches the observer when infiniteScroll flips from on to off (typing a query)", () => {
+    // The real user flow: browse (infinite scroll on) → type a query
+    // (infinite scroll off). The effect cleanup must disconnect the
+    // observer so scrolling no longer auto-loads mid-search.
+    const disconnectSpy = vi.spyOn(
+      IntersectionObserver.prototype,
+      "disconnect"
+    );
+    const { rerender } = render(
+      <ContentFeed
+        items={[item]}
+        status="success"
+        error={null}
+        onRetry={() => undefined}
+        hasActiveFilters={false}
+        {...defaultProps}
+        hasMore
+        infiniteScroll
+      />
+    );
+    expect(disconnectSpy).not.toHaveBeenCalled();
+    rerender(
+      <ContentFeed
+        items={[item]}
+        status="success"
+        error={null}
+        onRetry={() => undefined}
+        hasActiveFilters={false}
+        {...defaultProps}
+        hasMore
+        infiniteScroll={false}
+      />
+    );
+    expect(disconnectSpy).toHaveBeenCalled();
+  });
+
+  it("still shows the manual Load more button during search when hasMore", () => {
+    // Infinite scroll is off, but manual pagination stays available so
+    // search results are never cut off.
+    render(
+      <ContentFeed
+        items={[item]}
+        status="success"
+        error={null}
+        onRetry={() => undefined}
+        hasActiveFilters={false}
+        {...defaultProps}
+        hasMore
+        infiniteScroll={false}
+      />
+    );
+    expect(screen.getByTestId("feed-load-more-button")).toBeInTheDocument();
+  });
+
   it("threads onTagClick through to each card's tag pill", async () => {
     const onTagClick = vi.fn();
     const user = userEvent.setup();

src/app/browse/content-feed.tsx

@@ -60,6 +60,12 @@ export interface ContentFeedProps {
    *  to `setFilters({ tag })` so a click narrows the feed and the
    *  URL picks up `?tag=…`. */
   onTagClick?: (tag: string) => void;
+  /** Whether the scroll-triggered auto-load (the IntersectionObserver
+   *  on the sentinel) is active. Disabled during an active search so
+   *  results appear as a finite set "replacing infinite scroll" (issue
+   *  #24); a manual "Load more" button still paginates if `hasMore`.
+   *  Defaults to `true` (the normal browse feed). */
+  infiniteScroll?: boolean;
 }
 
 const SKELETON_CARD_COUNT = 6;
@@ -96,6 +102,7 @@ export function ContentFeed({
   onLoadMore,
   cardVariant = "larger-dot",
   onTagClick,
+  infiniteScroll = true,
 }: ContentFeedProps) {
   // ---- Column-count derivation for the masonry grid -----------
   // We watch the container width (via ResizeObserver) and derive
@@ -125,8 +132,14 @@ export function ContentFeed({
   }, [items, view, gridColumnCount]);
 
   // ---- Infinite-scroll sentinel -------------------------------
+  // Disabled during an active search (`infiniteScroll === false`):
+  // the observer is not attached, so scrolling to the bottom does
+  // not auto-fetch the next page. A manual "Load more" button below
+  // still paginates, so search results are never cut off — only the
+  // scroll-triggered auto-load (the "infinite scroll") is suspended.
   const sentinelRef = useRef<HTMLDivElement | null>(null);
   useEffect(() => {
+    if (!infiniteScroll) return;
     const node = sentinelRef.current;
     if (!node) return;
     if (typeof IntersectionObserver === "undefined") return;
@@ -140,7 +153,7 @@ export function ContentFeed({
     );
     observer.observe(node);
     return () => observer.disconnect();
-  }, [onLoadMore]);
+  }, [onLoadMore, infiniteScroll]);
 
   if (status === "error") {
     return (

src/app/browse/types.ts

@@ -44,6 +44,17 @@ export interface BrowseItem {
    *  when the item has no tags. Surfaced by the list / search API
    *  routes via a batched `content_tags` lookup. */
   tags: string[];
+  /** FTS5-generated snippet from `/api/search`, with matched terms
+   *  wrapped in `<mark>…</mark>` and `…` as the ellipsis. Present
+   *  only for search results; `null` / `undefined` for the regular
+   *  `/api/items` list. The card renders this in place of the
+   *  plain content preview so the match is visually highlighted.
+   *  The snippet is parsed into plain / highlight segments by
+   *  `parseSnippet` (src/lib/snippet.ts) and rendered as React text
+   *  children, which auto-escape any markup the source content
+   *  contained — there is no `dangerouslySetInnerHTML` anywhere in
+   *  the path. */
+  snippet?: string | null;
   created_at: string;
   updated_at: string;
 }