# G — Search, command palette, share & export

Workstream G of the 2026-09-11 upgrade (docs/UPGRADE-PLAN.md). Everything below compiles (pnpm typecheck), lints (eslint on the files listed) and is covered by vitest (tests/unit/search-query.test.ts, tests/unit/export-html.test.ts, tests/integration/search-share.test.ts — the last one runs against the local Postgres when DATABASE_URL is reachable).

# Files

src/lib/export/* is a new directory not claimed by any workstream (used only by the conversations service).

# Query language

free text  "exact phrase"  model:claude  provider:openai  project:research  project:"Q3 Research"
folder:clients  after:2026-08-01  after:2026-08  after:7d  after:today  after:yesterday  after:month
before:2026-09-01  role:user|assistant  is:pinned  is:archived  is:shared

• model: substring of modelKey or of a registry display name (resolved server-side); provider: accepts ids and aliases (google→gemini, claude→anthropic, grok→xai…); project:/folder: match id or name substring; a filter that matches nothing returns an empty result (not "everything").
• after: is inclusive (UTC midnight), before: exclusive; after:2026-08 = whole month; relative Nd|Nw|Nm|Ny.
• role: applies to messages and hides the Conversations group. is:archived is the only way to see archived chats? No — archived conversations are searchable by default; is:archived restricts to them.
• Unknown key:value tokens (URLs, 10:30) and invalid values (role:pirate) are kept as free text.
• Words ≥ 2 chars or any filter make a query searchable. websearch_to_tsquery('simple') handles phrases and -neg; a prefix query ('quot':*) is OR-ed so the last half-typed word matches; if FTS returns nothing on the first page an ILIKE fallback (all words AND-ed) catches fragments inside words (configur → "Reconfiguring").

# API

# GET /api/search?q=&limit=12&cursor=&groups=

Auth: user. Rate limit LIMITS.search. groups = comma list of conversations,messages,models,prompts,projects,presets (default all; secondary groups only on the first page).

interface SearchResponse {
  query: { raw; text; terms: string[]; tokens: FilterToken[]; hasFilters };
  conversations: { id; title; modelKey; provider; projectId; folderId; pinned; archived; shared; messageCount; updatedAt; lastMessageAt }[];
  messages: { id; conversationId; title; role; modelKey; createdAt; snippet }[];   // snippet = plain text, highlight with query.terms
  models: { key; displayName; provider; status }[];
  prompts: { id; name; description; kind: "library" | "legacy" }[];               // library = prompts table (D), legacy = prompt_presets
  projects: { id; name; description; icon; color }[];
  presets: { id; name; description; modelKey }[];
  nextCursor: string | null;   // opaque; pass back as ?cursor= (pages conversations + messages only)
  engine: "fts" | "ilike" | "none";
  tookMs: number;
}

Prompts are read from the prompts table directly (no internal HTTP to /api/prompts), so nothing 404s if D is not wired.

# POST /api/conversations/[id]/actions (existing, extended)

• { action: "share", messageIds?: string[] } → { id, path: "/share/<id>", partial, messageCount, created }. Without messageIds the conversation's single "entire conversation" link is refreshed in place (same URL); with messageIds a new excerpt link is created (active messages only, conversation order).
• { action: "unshare", shareId?: string } → { ok } (all links of the conversation, or one).
• { action: "share-status" } → { share: { id, createdAt, viewCount } | null, shares: ShareLinkItem[] }.
• { action: "list-shares" } → { shares: ShareLinkItem[] } (this conversation).
• { action: "export", format: "json" | "markdown" | "txt" | "html" } → file (kept for the sidebar).

# GET /api/conversations/[id]/export?format=json|markdown|txt|html[&download=1][&print=1]

File download (Content-Disposition: attachment) for everything except html without download=1, which renders inline; print=1 embeds a window.print() on load (used by "PDF (print)"). Cache-Control: private, no-store, X-Robots-Tag: noindex. Rate limit 40/min.

# GET /api/shares → { shares: ShareLinkItem[] } · DELETE /api/shares?id=<shareId> → { ok }

interface ShareLinkItem { id; conversationId; title; createdAt; viewCount; messageCount; partial; path: "/share/<id>" }

# Share snapshot v2

shared_conversations.snapshot now starts with { $meta: true, version: 2, partial, selectedCount, totalCount, generatedAt } followed by the messages. Renderers skip elements without role; readShareMeta(snapshot) reads it. Old snapshots (no meta) keep working. getPublicShare(id, { peek: true }) reads without counting a view (used by generateMetadata).

# Contracts for other workstreams

# A — chat header / composer

• Share button → const share = useShareSheet(); share.open({ conversationId, title, messages }) (from @/components/share/share-sheet). messages (the active PublicMessage[] already in memory) avoids a refetch; messageIds preselects "Selected messages" (use it from the message long-press "Share from here…"). The host is already mounted by CommandPalette — nothing else to mount.
• Export → <ExportMenu conversationId={id} title={title} /> from @/components/share/export-menu (icon button by default; pass your own trigger as children). Programmatic: exportConversation(id, "pdf") from @/components/share/export.
• Events the palette dispatches on window:
  • polyllm:open-attach (CustomEvent, no detail) — "Upload file" command. The composer should open its attachment sheet (phone) or the file picker (desktop). When the user is not on a chat page the palette navigates to /app/chat first and dispatches ~450 ms later.
  • polyllm:switch-model (detail: { modelKey: string }, may be AUTO_MODEL_KEY) — "Switch model" and model search hits. The store's selectedModelKey is already set; the chat view should apply it to the current conversation (changeModel(detail.modelKey)) if one is open.
• Deep links /app/chat/<id>#<messageId>: chat-view.tsx already scrolls to #hash on mount; when the same conversation is open the search UI calls scrollIntoView itself. Keep id={m.id} on message wrappers.

# E — Settings → Data

Mount <ShareLinksList /> from @/components/share/share-sheet in a card titled "Active share links" (it renders its own empty state, copy/revoke actions and a ConfirmDialog). It reads GET /api/shares.

# D — prompts / projects

Search links library prompts to /app/chat?promptId=<id> (your insertion contract) and legacy presets to /app/prompts?edit=<id>; projects to /app/projects/<id>. The palette's "Open project" reads GET /api/projects (tolerates errors) and sets activeProjectId before navigating. Filter chips read project names from the same route.

# Shell (integrator)

"Toggle sidebar" on desktop dispatches a synthetic ⌘B keydown because the collapsed state lives in shell.tsx (// TODO(integration: shell)): exposing toggleSidebarCollapsed in the store would make it explicit. On phones the command opens the drawer (setSidebarOpen(true)). store.searchOpen on ≥ md is consumed by the palette (opens in search mode and resets the flag) so setSearchOpen(true) works from anywhere on any breakpoint.

# Palette behaviour (desktop keyboard-first, phone bottom sheet)

• Root: typing filters commands by label/keywords; ≥ 2 characters also shows live search results under the commands; a leading / is pure search mode. ⌫ on an empty input returns to the root, Esc closes.
• Commands: New chat, New temporary chat (/app/chat?temporary=1), Search conversations, Switch model (AUTO + connected models, labels, favorites first, current ✓), Upload file, Open project, Go to Chat / Arena / Models / Usage / Providers / Projects / Library / Prompts / Model presets / Settings, Toggle theme (light/dark/system ✓), Toggle/Open sidebar, Keyboard shortcuts (sheet). On a chat page: Copy conversation URL, Share conversation, Export conversation (sub-list).
• Recent searches (localStorage polyllm:recent-searches, 8 max) and syntax examples appear in empty search mode.

# Migration notes

• drizzle/0003_search_index.sql is hand-written (expression indexes cannot be declared from schema-search.ts on tables defined in schema.ts); numbering follows E's 0002_endpoints. No snapshot file is needed (the indexes are not part of the drizzle schema, so drizzle-kit generate will neither re-create nor drop them; drizzle-kit push is not used). Index expressions must stay identical to msgTsv/titleTsv in src/lib/search/service.ts.
• Plain CREATE INDEX IF NOT EXISTS (the migrator runs in a transaction; CONCURRENTLY is not possible). On prod the messages table is small; expect sub-second creation via the mld hook.
• Verified with EXPLAIN: Bitmap Index Scan on messages_content_fts_idx for both the websearch and the prefix query.

# Not done / Coming soon

• Nothing is labelled "Coming soon". Desktop filter chips are shown inside the palette's search mode (compact); the pickers are the same sheets as on phones.
• Tags (tag:) are not a filter — conversation_tags has no UI yet.

# QA checklist (integration phase, 375/390/393/430 + 1440)

1. Phone: sidebar search icon → full-screen sheet, keyboard opens, 16 px input, no zoom; chips scroll horizontally; Model/Project/Date/Role/Status pickers open as half sheets and append tokens; token chips remove on ×.
2. Type quotas (or any word from a real chat): grouped results, <mark> highlights, tap a message → chat opens and scrolls to the message; recent search saved; "Load more" appears when > 10 message hits.
3. Desktop ⌘K: ↑↓↵ across commands and results, / search mode, ⌫ back, Esc close; palette sits at 14 % from the top, max 72 vh; footer hints. Hybrid: typing "arena" shows the command and matching chats.
4. Switch model from the palette on an open chat → chat header model changes (needs A's polyllm:switch-model listener). Upload file → composer attach opens (needs A's polyllm:open-attach listener).
5. Share sheet (chat header / palette): warning visible, Entire vs Selected (checkbox list with role + snippet, All/None), Create → link copied + toast, Copy/Open/Share… (native share on phones), Active links list, revoke via ConfirmDialog. Sharing the whole conversation twice keeps the same URL; a selection creates a second link.
6. /share/<id>: renders on 375 px without horizontal overflow, excerpt badge for partial shares, view count increments once per visit, <meta name="robots" content="noindex">, OG title = conversation title; revoked link → 404.
7. Export: Markdown/TXT/JSON/HTML download with the right filename; "PDF (print)" opens a new tab with the print dialog (Safari/Chrome/iOS Safari); blocked pop-up → HTML download + warning toast.
8. Settings → Data: ShareLinksList rows stack correctly on phones, revoke works, empty state text.
9. Old sidebar actions (Copy share link, Export Markdown/JSON) still work through the actions route.