research-agent-ui 0.1.219 → 0.1.221

package/README.md

@@ -20,259 +20,285 @@
 </p>
 <!-- template-git-repo:badges:end -->
 
-# research-agent-ui
-
-
-The QwkSearch app UI: conversation window, article reader, search config,
-file uploads, chat history — plus the app shell (providers, app dock, cookie
-banner, the research/docs view switch) that assembles them into a whole app.
-Includes the shadcn primitives and icons the components depend on, so it can be
-dropped into a Next.js app with a single dependency.
-
-![img1](https://i.imgur.com/UxNJOKy.png)
-
-## Two entry points: with and without the editor
-
-The package ships the same app twice, and the only difference is whether the
-REASON document editor and its file sidebar come along:
-
-| Import from | You get | Extra dependencies |
-| --- | --- | --- |
-| `research-agent-ui` | Chat, search, article reader, app shell | none |
-| `research-agent-ui/workspace` | All of the above **plus** the REASON editor, document tree, and file sidebar | `react-reason-editor`, `react-reason-editor-sidebar` |
-
-`research-agent-ui/workspace` re-exports everything the root entry does, so a
-host that wants documents imports from that one path rather than mixing the
-two. Going the other way, the root entry's import graph never reaches
-`react-reason-editor` — the editor's (large) dependency tree stays out of a
-chat-only consumer's bundle entirely. `test/entryBoundaries.test.ts` enforces
-that in both directions.
-
-The two editor packages are declared as **optional** peer dependencies:
-installing `research-agent-ui` on its own is enough for the chat-only build,
-and package managers will not warn about the missing peers.
-
-## Usage
-
-### The whole app in one component
-
-```tsx
-// Chat only — no editor, no sidebar.
-import { QwkSearchApp } from 'research-agent-ui';
-
-export default function Page() {
-  return (
-    <QwkSearchApp
-      authClient={myAuthClient}
-      config={{ appName: 'MyApp', footerLinks: myLinks }}
-    />
-  );
-}
-```
-
-```tsx
-// The same app, with documents.
-import { QwkSearchWorkspaceApp } from 'research-agent-ui/workspace';
-
-export default function Page() {
-  return (
-    <QwkSearchWorkspaceApp
-      authClient={myAuthClient}
-      config={{ appName: 'MyApp', footerLinks: myLinks }}
-    />
-  );
-}
-```
-
-`QwkSearchProviders` is the same shell without a page inside it, for hosts that
-render their own routes within the app chrome. It accepts a `ChromeProvider` to
-mount app-owned context (a settings modal, say) inside the stack, and
-`showDock` / `showCookieConsent` / `showToaster` to opt out of individual
-pieces.
-
-### Composing the pieces yourself
-
-```tsx
-import {
-  ChatProvider,
-  SessionProvider,
-  ExtractPanelProvider,
-  ChatWindow,
-  configureResearchAgentUI,
-} from 'research-agent-ui';
-
-configureResearchAgentUI({
-  appName: 'MyApp',
-  getAutoMediaSearch: () => true,
-  // ...see ResearchAgentUIConfig for the full list of overridable values
-});
-
-function App() {
-  return (
-    <SessionProvider authClient={myAuthClient}>
-      <ExtractPanelProvider>
-        <ChatProvider>
-          <ChatWindow />
-        </ChatProvider>
-      </ExtractPanelProvider>
-    </SessionProvider>
-  );
-}
-```
-
-## Storybook
-
-Individual UI pieces can be browsed in isolation with [Storybook](https://storybook.js.org/).
-Stories render against **mock data only** (see `src/stories/mocks.ts`) — no API,
-auth session, or chat backend is required, so you can develop and review the
-chat components (message header with timestamp/copy/edit actions, search
-progress, follow-up suggestions, file & pasted-content cards) on their own.
-
-```bash
-# from packages/research-agent-ui
-bun run storybook        # dev server on http://localhost:6006
-bun run build-storybook  # static build → storybook-static/
-```
-
-A light/dark toggle in the toolbar switches between the two token palettes
-(mirrored from the host app's `globals.css` in `.storybook/preview.css`). Add
-new stories next to their component as `*.stories.tsx`.
-
-## API Routes (`research-agent-ui/api`)
-
-All 25 Next.js route handlers are exported from the `research-agent-ui/api`
-subpath as factory functions. Each factory accepts a **deps** object that
-injects your app's database, auth helpers, and other services, so the same
-handler logic works in any Next.js project without hard-coding any imports.
-
-### How it works
-
-The route logic lives in `packages/research-agent-ui/src/api/handlers/`.
-Your app's `app/api/agent/*/route.ts` files become thin wrappers that call
-the factory and re-export the HTTP method handlers.
-
-### Step 1 — install / workspace link
-
-If you are in this monorepo, `research-agent-ui` is already linked via the
-`workspace:*` protocol. For an external project, install the published
-package:
-
-```bash
-npm install research-agent-ui
-# or
-bun add research-agent-ui
-```
-
-### Step 2 — create your route files
-
-For each API path, create a `route.ts` that calls the matching factory and
-passes in your app's dependencies. Every factory is named
-`create<RouteName>Handler` and is exported from `research-agent-ui/api`.
-
-#### Example: `app/api/agent/chats/route.ts`
-
-```ts
-import { createChatsHandler } from "research-agent-ui/api";
-import { getDB } from "@/lib/database";
-import { chats, messages } from "@/lib/database/schema";
-import { requireUserId } from "@/lib/auth/session";
-
-const handler = createChatsHandler({
-  getDB,
-  requireUserId,
-  schema: { chats, messages },
-});
-export const { GET, DELETE } = handler;
-```
-
-#### Example: `app/api/agent/article-followups/route.ts`
-
-```ts
-import { createArticleFollowupsHandler } from "research-agent-ui/api";
-import { getUserId } from "@/lib/auth/session";
-import { getDB } from "@/lib/database";
-import { user as userSchema } from "@/lib/database/schema";
-import { getEnv } from "@/lib/env";
-
-export const POST = createArticleFollowupsHandler({
-  getUserId,
-  requireUserId: async () => {
-    const id = await getUserId();
-    if (!id) throw new Error("Unauthorized");
-    return id;
-  },
-  getDB,
-  userSchema,
-  getEnv,
-});
-```
-
-### All available factories and their dep shapes
-
-| Factory | File | Required deps |
-|---|---|---|
-| `createArticleFollowupsHandler` | `article-followups` | `getUserId`, `requireUserId`, `getDB`, `userSchema`, `getEnv` |
-| `createArticleQAHandler` | `article-qa` | `getUserId`, `requireUserId`, `getDB`, `userSchema`, `getEnv` |
-| `createChatsHandler` | `chats` | `getDB`, `requireUserId`, `schema.chats`, `schema.messages` |
-| `createChatByIdHandler` | `chats/[id]` | `getDB`, `requireUserId`, `schema.chats`, `schema.messages` |
-| `createChatsSearchHandler` | `chats/search` | `getDB`, `requireUserId`, `schema.chats`, `schema.messages` |
-| `createChatsShareHandler` | `chats/share` | `getDB`, `requireUserId`, `schema.chats`, `schema.messages` |
-| `createMessagesHandler` | `messages` | `getDB`, `requireUserId`, `messagesSchema` |
-| `createProvidersHandler` | `providers` | `getSession` |
-| `createProviderByIdHandler` | `providers/[id]` | _(none)_ |
-| `createProviderModelsHandler` | `providers/[id]/models` | _(none)_ |
-| `createMCPServersHandler` | `mcpservers` | `configManager`, `getConfiguredMCPServers` |
-| `createMCPServerByIdHandler` | `mcpservers/[id]` | `configManager`, `getConfiguredMCPServers` |
-| `createMCPServerToggleHandler` | `mcpservers/[id]/toggle` | `configManager`, `getConfiguredMCPServers` |
-| `createSearchHandler` | `search` | `searxngDomain?` (default: `https://search.qwksearch.com`) |
-| `createDiscoverHandler` | `discover` | _(none)_ |
-| `createAutocompleteHandler` | `autocomplete` | _(none)_ |
-| `createSuggestionsHandler` | `suggestions` | _(none)_ |
-| `createAgentsHandler` | `agents` | `getUserId`, `requireUserId`, `getDB`, `userSchema`, `getEnv` |
-| `createRewriteHandler` | `rewrite` | `getEnv`, `generateText`, `createGroq` |
-| `createVoiceHandler` | `voice` | `getUserId`, `checkTTSRateLimit`, `generateSpeech` |
-| `createTranscriptHandler` | `transcript` | `getCloudflareContext` |
-| `createTestModelsHandler` | `test-models` | _(none)_ |
-| `createValidateOpenRouterHandler` | `validate-openrouter` | `validateOpenRouterModels` |
-
-### Dep type definitions
-
-All dep interfaces are exported from `research-agent-ui/api`:
-
-```ts
-import type {
-  ArticleDeps,
-  ChatsDeps,
-  MessagesDeps,
-  ProvidersDeps,
-  MCPServersDeps,
-  SearchDeps,
-  VoiceDeps,
-  TranscriptDeps,
-  RewriteDeps,
-  ValidateOpenRouterDeps,
-  AgentsDeps,
-} from "research-agent-ui/api";
-```
-
-### The chat route
-
-`POST /api/agent/chat` is not migrated into this package because it delegates
-to a full `handleChatRequest` orchestrator that is app-specific (streaming,
-search integration, database writes). Keep it directly in your app:
-
-```ts
-// app/api/agent/chat/route.ts
-import { handleChatRequest } from "@/lib/chat";
-
-export const runtime = "nodejs";
-export const dynamic = "force-dynamic";
-export const POST = handleChatRequest;
-```
-
-## Configuration
-
-`configureResearchAgentUI` overrides app-specific values (branding strings,
-the Google API key used by the Drive picker, and the auto-media-search
-toggle) that would otherwise couple this package to a specific app. See
-`ResearchAgentUIConfig` in `src/config.ts` for the full list.
+# research-agent-ui
+
+
+The QwkSearch app UI: conversation window, article reader, search config,
+file uploads, chat history — plus the app shell (providers, app dock, cookie
+banner, the research/docs view switch) that assembles them into a whole app.
+Includes the shadcn primitives and icons the components depend on, so it can be
+dropped into a Next.js app with a single dependency.
+
+![img1](https://i.imgur.com/UxNJOKy.png)
+
+## Two entry points: with and without the editor
+
+The package ships the same app twice, and the only difference is whether the
+REASON document editor and its file sidebar come along:
+
+| Import from | You get | Extra dependencies |
+| --- | --- | --- |
+| `research-agent-ui` | Chat, search, article reader, app shell | none |
+| `research-agent-ui/workspace` | All of the above **plus** the REASON editor, document tree, and file sidebar | `react-reason-editor`, `react-reason-editor-sidebar` |
+
+`research-agent-ui/workspace` re-exports everything the root entry does, so a
+host that wants documents imports from that one path rather than mixing the
+two. Going the other way, the root entry's import graph never reaches
+`react-reason-editor` — the editor's (large) dependency tree stays out of a
+chat-only consumer's bundle entirely. `test/entryBoundaries.test.ts` enforces
+that in both directions.
+
+The two editor packages are declared as **optional** peer dependencies:
+installing `research-agent-ui` on its own is enough for the chat-only build,
+and package managers will not warn about the missing peers.
+
+## Spotlight search
+
+`QwkSearchProviders` mounts a macOS-Spotlight-style command palette over the
+whole app. <kbd>Ctrl</kbd> <kbd>Space</kbd> opens it (Cmd-Space belongs to
+macOS), or call `openSpotlight()` from your own chrome. Typing searches past
+chats, app pages, settings sections and actions at once, with "ask the research
+agent this" pinned to the top; a leading letter scopes the search to one source
+— `c ` chats, `t ` pages, `s ` settings, `a ` actions, `w ` ask — and
+<kbd>Tab</kbd> cycles between them.
+
+```tsx
+import { QwkSearchProviders, openSpotlight } from 'research-agent-ui';
+
+<QwkSearchProviders authClient={authClient} showSpotlight>   {/* the default */}
+  <YourApp />
+</QwkSearchProviders>;
+
+// …and from a button somewhere in your own chrome:
+<button onClick={() => openSpotlight()}>Search everything</button>;
+```
+
+Rows that open a chat or a settings section go through `onOpenChat` /
+`onOpenSettings` first, so a host rendering chats inline handles them without
+navigating; returning anything but `true` falls back to `/c/<id>` and
+`/settings/<section>`.
+
+## Usage
+
+### The whole app in one component
+
+```tsx
+// Chat only — no editor, no sidebar.
+import { QwkSearchApp } from 'research-agent-ui';
+
+export default function Page() {
+  return (
+    <QwkSearchApp
+      authClient={myAuthClient}
+      config={{ appName: 'MyApp', footerLinks: myLinks }}
+    />
+  );
+}
+```
+
+```tsx
+// The same app, with documents.
+import { QwkSearchWorkspaceApp } from 'research-agent-ui/workspace';
+
+export default function Page() {
+  return (
+    <QwkSearchWorkspaceApp
+      authClient={myAuthClient}
+      config={{ appName: 'MyApp', footerLinks: myLinks }}
+    />
+  );
+}
+```
+
+`QwkSearchProviders` is the same shell without a page inside it, for hosts that
+render their own routes within the app chrome. It accepts a `ChromeProvider` to
+mount app-owned context (a settings modal, say) inside the stack, and
+`showDock` / `showCookieConsent` / `showToaster` to opt out of individual
+pieces.
+
+### Composing the pieces yourself
+
+```tsx
+import {
+  ChatProvider,
+  SessionProvider,
+  ExtractPanelProvider,
+  ChatWindow,
+  configureResearchAgentUI,
+} from 'research-agent-ui';
+
+configureResearchAgentUI({
+  appName: 'MyApp',
+  getAutoMediaSearch: () => true,
+  // ...see ResearchAgentUIConfig for the full list of overridable values
+});
+
+function App() {
+  return (
+    <SessionProvider authClient={myAuthClient}>
+      <ExtractPanelProvider>
+        <ChatProvider>
+          <ChatWindow />
+        </ChatProvider>
+      </ExtractPanelProvider>
+    </SessionProvider>
+  );
+}
+```
+
+## Storybook
+
+Individual UI pieces can be browsed in isolation with [Storybook](https://storybook.js.org/).
+Stories render against **mock data only** (see `src/stories/mocks.ts`) — no API,
+auth session, or chat backend is required, so you can develop and review the
+chat components (message header with timestamp/copy/edit actions, search
+progress, follow-up suggestions, file & pasted-content cards) on their own.
+
+```bash
+# from packages/research-agent-ui
+bun run storybook        # dev server on http://localhost:6006
+bun run build-storybook  # static build → storybook-static/
+```
+
+A light/dark toggle in the toolbar switches between the two token palettes
+(mirrored from the host app's `globals.css` in `.storybook/preview.css`). Add
+new stories next to their component as `*.stories.tsx`.
+
+## API Routes (`research-agent-ui/api`)
+
+All 25 Next.js route handlers are exported from the `research-agent-ui/api`
+subpath as factory functions. Each factory accepts a **deps** object that
+injects your app's database, auth helpers, and other services, so the same
+handler logic works in any Next.js project without hard-coding any imports.
+
+### How it works
+
+The route logic lives in `packages/research-agent-ui/src/api/handlers/`.
+Your app's `app/api/agent/*/route.ts` files become thin wrappers that call
+the factory and re-export the HTTP method handlers.
+
+### Step 1 — install / workspace link
+
+If you are in this monorepo, `research-agent-ui` is already linked via the
+`workspace:*` protocol. For an external project, install the published
+package:
+
+```bash
+npm install research-agent-ui
+# or
+bun add research-agent-ui
+```
+
+### Step 2 — create your route files
+
+For each API path, create a `route.ts` that calls the matching factory and
+passes in your app's dependencies. Every factory is named
+`create<RouteName>Handler` and is exported from `research-agent-ui/api`.
+
+#### Example: `app/api/agent/chats/route.ts`
+
+```ts
+import { createChatsHandler } from "research-agent-ui/api";
+import { getDB } from "@/lib/database";
+import { chats, messages } from "@/lib/database/schema";
+import { requireUserId } from "@/lib/auth/session";
+
+const handler = createChatsHandler({
+  getDB,
+  requireUserId,
+  schema: { chats, messages },
+});
+export const { GET, DELETE } = handler;
+```
+
+#### Example: `app/api/agent/article-followups/route.ts`
+
+```ts
+import { createArticleFollowupsHandler } from "research-agent-ui/api";
+import { getUserId } from "@/lib/auth/session";
+import { getDB } from "@/lib/database";
+import { user as userSchema } from "@/lib/database/schema";
+import { getEnv } from "@/lib/env";
+
+export const POST = createArticleFollowupsHandler({
+  getUserId,
+  requireUserId: async () => {
+    const id = await getUserId();
+    if (!id) throw new Error("Unauthorized");
+    return id;
+  },
+  getDB,
+  userSchema,
+  getEnv,
+});
+```
+
+### All available factories and their dep shapes
+
+| Factory | File | Required deps |
+|---|---|---|
+| `createArticleFollowupsHandler` | `article-followups` | `getUserId`, `requireUserId`, `getDB`, `userSchema`, `getEnv` |
+| `createArticleQAHandler` | `article-qa` | `getUserId`, `requireUserId`, `getDB`, `userSchema`, `getEnv` |
+| `createChatsHandler` | `chats` | `getDB`, `requireUserId`, `schema.chats`, `schema.messages` |
+| `createChatByIdHandler` | `chats/[id]` | `getDB`, `requireUserId`, `schema.chats`, `schema.messages` |
+| `createChatsSearchHandler` | `chats/search` | `getDB`, `requireUserId`, `schema.chats`, `schema.messages` |
+| `createChatsShareHandler` | `chats/share` | `getDB`, `requireUserId`, `schema.chats`, `schema.messages` |
+| `createMessagesHandler` | `messages` | `getDB`, `requireUserId`, `messagesSchema` |
+| `createProvidersHandler` | `providers` | `getSession` |
+| `createProviderByIdHandler` | `providers/[id]` | _(none)_ |
+| `createProviderModelsHandler` | `providers/[id]/models` | _(none)_ |
+| `createMCPServersHandler` | `mcpservers` | `configManager`, `getConfiguredMCPServers` |
+| `createMCPServerByIdHandler` | `mcpservers/[id]` | `configManager`, `getConfiguredMCPServers` |
+| `createMCPServerToggleHandler` | `mcpservers/[id]/toggle` | `configManager`, `getConfiguredMCPServers` |
+| `createSearchHandler` | `search` | `searxngDomain?` (default: `https://search.qwksearch.com`) |
+| `createDiscoverHandler` | `discover` | _(none)_ |
+| `createAutocompleteHandler` | `autocomplete` | _(none)_ |
+| `createSuggestionsHandler` | `suggestions` | _(none)_ |
+| `createAgentsHandler` | `agents` | `getUserId`, `requireUserId`, `getDB`, `userSchema`, `getEnv` |
+| `createRewriteHandler` | `rewrite` | `getEnv`, `generateText`, `createGroq` |
+| `createVoiceHandler` | `voice` | `getUserId`, `checkTTSRateLimit`, `generateSpeech` |
+| `createTranscriptHandler` | `transcript` | `getCloudflareContext` |
+| `createTestModelsHandler` | `test-models` | _(none)_ |
+| `createValidateOpenRouterHandler` | `validate-openrouter` | `validateOpenRouterModels` |
+
+### Dep type definitions
+
+All dep interfaces are exported from `research-agent-ui/api`:
+
+```ts
+import type {
+  ArticleDeps,
+  ChatsDeps,
+  MessagesDeps,
+  ProvidersDeps,
+  MCPServersDeps,
+  SearchDeps,
+  VoiceDeps,
+  TranscriptDeps,
+  RewriteDeps,
+  ValidateOpenRouterDeps,
+  AgentsDeps,
+} from "research-agent-ui/api";
+```
+
+### The chat route
+
+`POST /api/agent/chat` is not migrated into this package because it delegates
+to a full `handleChatRequest` orchestrator that is app-specific (streaming,
+search integration, database writes). Keep it directly in your app:
+
+```ts
+// app/api/agent/chat/route.ts
+import { handleChatRequest } from "@/lib/chat";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const POST = handleChatRequest;
+```
+
+## Configuration
+
+`configureResearchAgentUI` overrides app-specific values (branding strings,
+the Google API key used by the Drive picker, and the auto-media-search
+toggle) that would otherwise couple this package to a specific app. See
+`ResearchAgentUIConfig` in `src/config.ts` for the full list.

package/dist/app/QwkSearchProviders.d.ts

@@ -45,5 +45,11 @@ export interface QwkSearchProvidersProps {
     showCookieConsent?: boolean;
     /** Render the `sonner` toaster. Default true. */
     showToaster?: boolean;
+    /**
+     * Mount the Ctrl-Space spotlight palette. Default true. Turn it off in a
+     * shell that already binds that chord (a VS Code webview, say, where the
+     * host may want the keystroke for itself).
+     */
+    showSpotlight?: boolean;
 }
-export declare function QwkSearchProviders({ children, authClient, config, googleOneTap, docsEnabled, ChromeProvider, showDock, showCookieConsent, showToaster, }: QwkSearchProvidersProps): import("react").JSX.Element;
+export declare function QwkSearchProviders({ children, authClient, config, googleOneTap, docsEnabled, ChromeProvider, showDock, showCookieConsent, showToaster, showSpotlight, }: QwkSearchProvidersProps): import("react").JSX.Element;

package/dist/components/SearchConfig/focusModes.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+export interface FocusMode {
+    /** The value stored in chat state and sent with a search request. */
+    key: string;
+    title: string;
+    description: string;
+    icon: ReactNode;
+}
+export declare const focusModes: FocusMode[];

package/dist/components/SpotlightPalette/SpotlightPalette.d.ts

@@ -0,0 +1,5 @@
+/** Opens the spotlight palette from anywhere in the tree, without threading
+ *  state through props. A no-op if the palette is not mounted. */
+export declare function openSpotlight(): void;
+export declare function SpotlightPalette(): import("react").JSX.Element;
+export default SpotlightPalette;

package/dist/components/SpotlightPalette/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview The Ctrl-Space spotlight palette — a single bar that searches
+ * chats, pages, settings and actions, and asks the research agent anything
+ * that matches none of them.
+ */
+export { SpotlightPalette, openSpotlight } from './SpotlightPalette';
+export { buildActionItems, buildChatItems, buildPageItems, buildSearchItem, buildSettingItems, } from './spotlightItems';
+export type { SpotlightContext, SpotlightIcon, SpotlightItem, } from './spotlightItems';
+export { matchSpotlight, parsePrefix, prefixForSource, SPOTLIGHT_PREFIXES, } from './spotlightMatch';
+export type { SpotlightMatch, SpotlightMatchable, SpotlightPrefix, SpotlightSource, } from './spotlightMatch';
+export { SPOTLIGHT_LINKS, type SpotlightLink } from './spotlightLinks';