@escalay/kit 0.0.0-stage → 1.8.0

package/src/boards/tools.ts

@@ -0,0 +1,76 @@
+/** The board routes as MCP tools, so an agent can keep what it finds for the owner. */
+import { z } from '@hono/zod-openapi'
+import { mcpTool, type McpTool } from '../mcp/index.js'
+
+type BoardJson = { id: string; name: string; items: number; description?: string | null; _embedded?: { items: { ref: string; note: string | null; item: unknown }[] } }
+
+/**
+ * The MCP tools for the same routes, so an agent can keep what it finds for the owner: list, make, open, save to and
+ * take off boards (and suggestions, when the app has them).
+ *
+ * @example
+ * boardTools({ noun: 'recipes', label: (recipe) => `${recipe.title} (${recipe.year})`, suggestions: true })
+ */
+export const boardTools = ({ path = '/api/boards', noun, label, suggestions = false }: { path?: string; noun: string; label: (item: any) => string; suggestions?: boolean }): McpTool[] => {
+  const line = (board: BoardJson) => `${board.name} · ${board.items} ${noun} · id ${board.id}`
+  const tools: McpTool[] = [
+    mcpTool({
+      name: 'list_boards',
+      title: 'The owner’s boards',
+      description: `Every board (a named collection of ${noun} for a project) with how much is on it; give \`item\` to see which boards hold one.`,
+      input: z.object({ item: z.string().optional().describe('Only boards holding this ref.') }),
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      call: ({ item }) => ({ path, query: item ? { item } : {} }),
+      summarize: (json: { _embedded: { boards: BoardJson[] } }) => json._embedded.boards.map(line).join('\n') || 'No boards yet. create_board makes one.',
+    }),
+    mcpTool({
+      name: 'create_board',
+      title: 'Make a board',
+      description: `A new, empty board to collect ${noun} for a project. Returns its id.`,
+      input: z.object({ name: z.string().min(1).describe('A short name.'), description: z.string().optional().describe('What it is for.') }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+      call: (body) => ({ method: 'POST', path, body }),
+      summarize: (json: BoardJson) => `Made ${line(json)}`,
+    }),
+    mcpTool({
+      name: 'get_board',
+      title: 'Open a board',
+      description: `A board and the ${noun} on it, newest first, with their notes.`,
+      input: z.object({ id: z.string().describe('The board’s id.') }),
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      call: ({ id }) => ({ path: `${path}/${encodeURIComponent(id)}` }),
+      summarize: (json: BoardJson) => [line(json), ...(json._embedded?.items ?? []).map((entry) => `- ${entry.item ? label(entry.item) : `${entry.ref} (no longer in the catalog)`}${entry.note ? ` — ${entry.note}` : ''}`)].join('\n'),
+    }),
+    mcpTool({
+      name: 'save_to_board',
+      title: 'Save to a board',
+      description: `Puts one of the ${noun} on a board, with an optional note on why; saving it again only changes the note.`,
+      input: z.object({ id: z.string().describe('The board’s id.'), ref: z.string().describe('The item’s ref, from a search result (e.g. its id).'), note: z.string().optional().describe('Why it belongs here.') }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+      call: ({ id, ref, note }) => ({ method: 'PUT', path: `${path}/${encodeURIComponent(id)}/items/${encodeURIComponent(ref)}`, body: note ? { note } : {} }),
+      summarize: (json: BoardJson) => `Saved. ${line(json)}`,
+    }),
+    mcpTool({
+      name: 'remove_from_board',
+      title: 'Take off a board',
+      description: `Takes one of the ${noun} off a board.`,
+      input: z.object({ id: z.string().describe('The board’s id.'), ref: z.string().describe('The item’s ref.') }),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+      call: ({ id, ref }) => ({ method: 'DELETE', path: `${path}/${encodeURIComponent(id)}/items/${encodeURIComponent(ref)}` }),
+      summarize: () => 'Removed.',
+    }),
+  ]
+  if (suggestions)
+    tools.push(
+      mcpTool({
+        name: 'board_suggestions',
+        title: 'More like a board',
+        description: `${noun[0]!.toUpperCase()}${noun.slice(1)} like the ones on a board, best first, leaving out what is already on it.`,
+        input: z.object({ id: z.string().describe('The board’s id.'), limit: z.number().int().min(1).max(100).optional() }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        call: ({ id, limit }) => ({ path: `${path}/${encodeURIComponent(id)}/suggestions`, query: limit ? { limit } : {} }),
+        summarize: (json: { _embedded: { items: unknown[] } }) => json._embedded.items.map((item) => `- ${label(item)}`).join('\n') || 'Nothing yet: add a few items first.',
+      }),
+    )
+  return tools
+}

package/src/browser/README.md

@@ -0,0 +1,31 @@
+# browser
+
+The browser side, for the app's frontend (not the API): typed clients for the search and board routes, headless
+React hooks over them, and an optional shadcn search block. Logic only; each app draws its own UI.
+
+| Part | Files | What |
+|---|---|---|
+| `search-client` | `search-client.ts` | `createSearchClient`, `createSearchController` (debounce, cancel, picture paste and drop) |
+| `search-react` | `search-react.ts` | `useVectorSearch`, `usePictureInput`, `useSimilar` |
+| `vector-search-ui` | `vector-search-block.tsx` | an optional search block (shadcn `button` + `input`) |
+| `boards-client` | `boards-client.ts` + `../boards/refs.ts` | `createBoardsClient`: list, create, save, unsave, suggestions; `BoardsError` carries the problem |
+| `boards-react` | `boards-react.ts` | `useBoards`, `useItemBoards` |
+
+```bash
+# into the frontend, tracked by the API's kit.json
+npx @escalay/kit add boards-react --dir apps/api/src/kit --web-dir ../../web/src/kit
+# or one part with the shadcn CLI, into src/kit
+npx shadcn add escalay/api-kit/boards-react
+```
+
+```ts
+const boards = createBoardsClient<RecipeCard>()
+const saved = (await boards.list()).find((b) => b.name === 'Saved') ?? (await boards.create('Saved'))
+await boards.save(saved.id, boardRef('recipe', slug), 'the sun')
+```
+
+## Rules
+
+- The clients use the page's own sign-in (same-origin cookies); a failure is a typed error with the API's `detail`.
+- Typechecked with bundler resolution (`tsconfig.web.json`).
+- Standard: `docs/STANDARD.md` §16.

package/src/browser/boards-client.ts

@@ -0,0 +1,74 @@
+/**
+ * The browser side of `boards`, without a framework: a typed client for the board routes, run with the page's own
+ * sign-in. A plain viewer uses it directly; React apps use `boards-react.ts`. A failed call is a `BoardsError` carrying
+ * the API's problem (`code`, `detail`), so an app can show what to do.
+ *
+ * @example
+ * const boards = createBoardsClient<RecipeCard>()
+ * const saved = (await boards.list()).find((board) => board.name === 'Saved') ?? (await boards.create('Saved'))
+ * await boards.save(saved.id, 'recipe:soup', 'the sun')
+ */
+
+export { BOARD_REF, boardRef, parseBoardRef } from '../boards/refs.js'
+
+export type BoardEntry<Item> = { ref: string; note: string | null; addedAt: string; item: Item | null }
+export type Board<Item> = { id: string; name: string; description: string | null; items: number; createdAt: string; updatedAt: string; entries?: BoardEntry<Item>[] }
+
+/** A failed board call, as the API's problem+json described it. */
+export class BoardsError extends Error {
+  readonly status: number
+  readonly code: string
+  readonly detail: string
+
+  constructor(status: number, code: string, detail: string) {
+    super(detail)
+    this.status = status
+    this.code = code
+    this.detail = detail
+  }
+}
+
+type BoardJson<Item> = Omit<Board<Item>, 'entries'> & { _embedded?: { items: BoardEntry<Item>[] } }
+const boardOf = <Item>({ _embedded, ...board }: BoardJson<Item>): Board<Item> => ({ ...board, ...(_embedded ? { entries: _embedded.items } : {}) })
+
+export type BoardsClient<Item> = {
+  /** Every board, newest change first; with `ref`, only the boards holding it. */
+  list: (ref?: string) => Promise<Board<Item>[]>
+  create: (name: string, description?: string) => Promise<Board<Item>>
+  /** A board with its entries. */
+  get: (id: string) => Promise<Board<Item>>
+  rename: (id: string, change: { name?: string; description?: string }) => Promise<Board<Item>>
+  remove: (id: string) => Promise<void>
+  /** Puts an item on a board (or changes its note); harmless to repeat. */
+  save: (id: string, ref: string, note?: string) => Promise<Board<Item>>
+  unsave: (id: string, ref: string) => Promise<void>
+  suggestions: (id: string, limit?: number) => Promise<Item[]>
+}
+
+/**
+ * A client for the routes `registerBoards` serves. `fetchImpl` and `headers` are for tests and scripts; a page needs
+ * neither.
+ *
+ * @example
+ * const boards = createBoardsClient<RecipeCard>({ path: '/api/boards' })
+ * const holding = await boards.list('recipe:soup') // where it is saved
+ */
+export const createBoardsClient = <Item>({ path = '/api/boards', fetchImpl = (...args) => fetch(...args), headers = {} }: { path?: string; fetchImpl?: typeof fetch; headers?: Record<string, string> } = {}): BoardsClient<Item> => {
+  const call = async (url: string, init: RequestInit = {}) => {
+    const response = await fetchImpl(url, { credentials: 'same-origin', ...init, headers: { accept: 'application/json', ...(init.body ? { 'content-type': 'application/json' } : {}), ...headers } })
+    const body = response.status === 204 ? null : await response.json().catch(() => null)
+    if (!response.ok) throw new BoardsError(response.status, body?.code ?? 'error', body?.detail ?? body?.title ?? `The board call failed (${response.status}).`)
+    return body
+  }
+  const at = (id: string) => `${path}/${encodeURIComponent(id)}`
+  return {
+    list: async (ref) => ((await call(ref ? `${path}?item=${encodeURIComponent(ref)}` : path))._embedded.boards as BoardJson<Item>[]).map(boardOf),
+    create: async (name, description) => boardOf(await call(path, { method: 'POST', body: JSON.stringify({ name, ...(description ? { description } : {}) }) })),
+    get: async (id) => boardOf(await call(at(id))),
+    rename: async (id, change) => boardOf(await call(at(id), { method: 'PATCH', body: JSON.stringify(change) })),
+    remove: async (id) => void (await call(at(id), { method: 'DELETE' })),
+    save: async (id, ref, note) => boardOf(await call(`${at(id)}/items/${encodeURIComponent(ref)}`, { method: 'PUT', body: JSON.stringify(note ? { note } : {}) })),
+    unsave: async (id, ref) => void (await call(`${at(id)}/items/${encodeURIComponent(ref)}`, { method: 'DELETE' })),
+    suggestions: async (id, limit) => (await call(`${at(id)}/suggestions${limit ? `?limit=${limit}` : ''}`))._embedded.items as Item[],
+  }
+}

package/src/browser/boards-react.ts

@@ -0,0 +1,73 @@
+/**
+ * React hooks over `boards-client.ts`: the owner's boards and where one item is saved, with no markup. Each app draws
+ * its own lists, menus and save buttons.
+ *
+ *   useBoards       every board, and making, renaming and deleting them
+ *   useItemBoards   the boards holding one item, and saving it to or taking it off a board
+ *
+ * @example
+ * const boards = useMemo(() => createBoardsClient<RecipeCard>(), [])
+ * const { boards: all, create } = useBoards(boards)
+ * const { holding, toggle } = useItemBoards(boards, `recipe:${recipe.slug}`)
+ * all.map((board) => <label key={board.id}><input type="checkbox" checked={holding.has(board.id)} onChange={() => toggle(board.id)} />{board.name}</label>)
+ */
+import { useCallback, useEffect, useState } from 'react'
+import type { Board, BoardsClient, BoardsError } from './boards-client'
+
+type Status = 'loading' | 'ready' | 'error'
+
+/**
+ * Every board, newest change first, reloaded after each change made through it.
+ *
+ * @example
+ * const { boards, status, create, rename, remove } = useBoards(client)
+ */
+export const useBoards = <Item>(client: BoardsClient<Item>) => {
+  const [boards, setBoards] = useState<Board<Item>[]>([])
+  const [status, setStatus] = useState<Status>('loading')
+  const [error, setError] = useState<BoardsError | null>(null)
+  const reload = useCallback(async () => {
+    try {
+      setBoards(await client.list())
+      setStatus('ready')
+      setError(null)
+    } catch (caught) {
+      setStatus('error')
+      setError(caught as BoardsError)
+    }
+  }, [client])
+  useEffect(() => void reload(), [reload])
+  const after =
+    <Args extends unknown[], Result>(change: (...args: Args) => Promise<Result>) =>
+    async (...args: Args) => {
+      const result = await change(...args)
+      await reload()
+      return result
+    }
+  return { boards, status, error, reload, create: after(client.create), rename: after(client.rename), remove: after(client.remove) }
+}
+
+/**
+ * Where one item is saved: the ids of the boards holding it, and saving it to or taking it off one. Stays idle without
+ * a ref.
+ *
+ * @example
+ * const { holding, toggle, save } = useItemBoards(client, `recipe:${slug}`)
+ */
+export const useItemBoards = <Item>(client: BoardsClient<Item>, ref: string | null | undefined) => {
+  const [holding, setHolding] = useState<Set<string>>(new Set())
+  const reload = useCallback(async () => setHolding(ref ? new Set((await client.list(ref)).map((board) => board.id)) : new Set()), [client, ref])
+  useEffect(() => void reload().catch(() => setHolding(new Set())), [reload])
+  const save = async (boardId: string, note?: string) => {
+    if (!ref) return
+    await client.save(boardId, ref, note)
+    await reload()
+  }
+  const toggle = async (boardId: string) => {
+    if (!ref) return
+    if (holding.has(boardId)) await client.unsave(boardId, ref)
+    else await client.save(boardId, ref)
+    await reload()
+  }
+  return { holding, save, toggle, reload }
+}

package/src/browser/search-client.ts

@@ -0,0 +1,258 @@
+/**
+ * The browser side of `vector-search`, without a framework: a typed client for its three routes, a controller that
+ * holds one search's state (words debounced, a picture at once, every new search cancelling the last), and the
+ * helpers that turn a paste or a drop into a picture. A plain viewer uses these directly; React apps use
+ * `search-react.ts`, which wraps the same controller. Nothing here draws anything: each app renders its own results.
+ *
+ * Requests run with the page's own sign-in (same-origin cookies), so the browser never holds an API key. A failed
+ * call is a `SearchError` carrying the API's problem: `code`, `detail`, and `retryAfter` for a 429 or 503.
+ *
+ * @example
+ * const client = createSearchClient<RecipeCard>({ path: '/api/search', similarPath: '/api/recipes/{id}/similar' })
+ * const search = createSearchController(client)
+ * search.subscribe(() => render(search.getState()))
+ * input.addEventListener('input', () => search.setWords(input.value))
+ * listenForPictures(window, (picture) => search.setPicture(picture))
+ */
+
+export type SearchBy = 'look' | 'meaning' | 'both'
+export type SearchResult<Item> = { score: number; z: number | null; space: 'look' | 'meaning'; item: Item }
+/** `closest`: only when nothing cleared the bar, the nearest few below it (not matches; show them as such). */
+export type SearchAnswer<Item> = { query: string | null; by: SearchBy; results: SearchResult<Item>[]; closest: SearchResult<Item>[] }
+export type SearchFilters = Record<string, string | number | boolean | undefined>
+export type SearchOptions = { by?: SearchBy; limit?: number; filters?: SearchFilters; signal?: AbortSignal }
+
+/** A failed search, as the API's problem+json described it. */
+export class SearchError extends Error {
+  readonly status: number
+  readonly code: string
+  readonly detail: string
+  readonly retryAfter: number | null
+
+  constructor(status: number, code: string, detail: string, retryAfter: number | null = null) {
+    super(detail)
+    this.status = status
+    this.code = code
+    this.detail = detail
+    this.retryAfter = retryAfter
+  }
+}
+
+export type SearchClient<Item> = {
+  /** Items that match words. */
+  byWords: (text: string, options?: SearchOptions) => Promise<SearchAnswer<Item>>
+  /** Items that look like a picture: a file or blob, or a data URL. */
+  byPicture: (picture: Blob | string, options?: SearchOptions) => Promise<SearchAnswer<Item>>
+  /** Items like one, by its id. */
+  similar: (id: string, options?: SearchOptions) => Promise<SearchAnswer<Item>>
+}
+
+const queryOf = ({ by, limit, filters = {} }: SearchOptions) => {
+  const params = new URLSearchParams()
+  if (by) params.set('by', by)
+  if (limit) params.set('limit', String(limit))
+  for (const [name, value] of Object.entries(filters)) if (value !== undefined && value !== '') params.set(name, String(value))
+  return params
+}
+
+/**
+ * A client for the routes `registerVectorSearch` serves. `fetchImpl` and `headers` are for tests and for callers
+ * outside the page (a key in a script); a page needs neither.
+ *
+ * @example
+ * const client = createSearchClient<RecipeCard>({ path: '/api/search', similarPath: '/api/recipes/{slug}/similar' })
+ * const { results } = await client.byWords('a fox made of triangles', { by: 'look', filters: { decade: '1970s' } })
+ */
+export const createSearchClient = <Item>({ path, similarPath, fetchImpl = (...args) => fetch(...args), headers = {} }: { path: string; similarPath?: string; fetchImpl?: typeof fetch; headers?: Record<string, string> }): SearchClient<Item> => {
+  const call = async (url: string, init: RequestInit = {}): Promise<SearchAnswer<Item>> => {
+    const response = await fetchImpl(url, { credentials: 'same-origin', ...init, headers: { accept: 'application/json', ...headers, ...(init.headers as Record<string, string>) } })
+    const body = (await response.json().catch(() => null)) as { query?: string | null; by?: SearchBy; _embedded?: { results?: SearchResult<Item>[]; closest?: SearchResult<Item>[] }; code?: string; detail?: string; title?: string } | null
+    if (!response.ok) {
+      const retry = Number(response.headers.get('retry-after'))
+      throw new SearchError(response.status, body?.code ?? 'error', body?.detail ?? body?.title ?? `The search failed (${response.status}).`, Number.isFinite(retry) && retry > 0 ? retry : null)
+    }
+    return { query: body?.query ?? null, by: body?.by ?? 'both', results: body?._embedded?.results ?? [], closest: body?._embedded?.closest ?? [] }
+  }
+  return {
+    byWords: (text, options = {}) => {
+      const params = queryOf(options)
+      params.set('q', text)
+      return call(`${path}?${params}`, { signal: options.signal })
+    },
+    byPicture: (picture, options = {}) => {
+      const params = queryOf(options)
+      const suffix = params.size ? `?${params}` : ''
+      if (typeof picture === 'string') return call(`${path}${suffix}`, { method: 'POST', body: JSON.stringify({ image: picture }), headers: { 'content-type': 'application/json' }, signal: options.signal })
+      const form = new FormData()
+      form.append('image', picture)
+      return call(`${path}${suffix}`, { method: 'POST', body: form, signal: options.signal })
+    },
+    similar: (id, options = {}) => {
+      if (!similarPath) return Promise.reject(new SearchError(404, 'not_found', 'This client has no similarPath.'))
+      const params = queryOf(options)
+      return call(`${similarPath.replace(/\{\w+\}/, encodeURIComponent(id))}${params.size ? `?${params}` : ''}`, { signal: options.signal })
+    },
+  }
+}
+
+/** What is being searched for: nothing yet, words, a picture (with an object URL to show it), or one item's likeness. */
+export type SearchInput = { kind: 'idle' } | { kind: 'words'; text: string } | { kind: 'picture'; picture: Blob; preview: string } | { kind: 'similar'; id: string }
+
+export type SearchState<Item> = {
+  input: SearchInput
+  by: SearchBy
+  filters: SearchFilters
+  status: 'idle' | 'loading' | 'done' | 'error'
+  results: SearchResult<Item>[]
+  /** The nearest below the bar when `results` is empty. */
+  closest: SearchResult<Item>[]
+  error: SearchError | null
+}
+
+export type SearchController<Item> = {
+  getState: () => SearchState<Item>
+  /** Calls `listener` after every change; returns the unsubscribe. */
+  subscribe: (listener: () => void) => () => void
+  /** Words, debounced; fewer than `minLength` characters clears the results. */
+  setWords: (text: string) => void
+  setPicture: (picture: Blob) => void
+  similarTo: (id: string) => void
+  /** Reruns the current search with the new setting. */
+  setBy: (by: SearchBy) => void
+  setFilters: (filters: SearchFilters) => void
+  retry: () => void
+  clear: () => void
+  /** Cancels what is running and frees the picture preview. */
+  dispose: () => void
+}
+
+/**
+ * One search's state over a client: words wait `debounceMs` after the last keystroke, a picture or a likeness runs at
+ * once, and a newer search aborts an older one, so results never arrive out of order. `by` defaults to `both` for
+ * words and `look` for pictures and likeness, until set.
+ *
+ * @example
+ * const search = createSearchController(client, { limit: 48 })
+ * search.subscribe(() => paint(search.getState()))
+ * search.setWords('bauhaus lettermark')
+ */
+export const createSearchController = <Item>(client: SearchClient<Item>, { debounceMs = 250, minLength = 2, limit, by: fixedBy, filters: initialFilters = {} }: { debounceMs?: number; minLength?: number; limit?: number; by?: SearchBy; filters?: SearchFilters } = {}): SearchController<Item> => {
+  let state: SearchState<Item> = { input: { kind: 'idle' }, by: fixedBy ?? 'both', filters: initialFilters, status: 'idle', results: [], closest: [], error: null }
+  let chosenBy = fixedBy
+  const listeners = new Set<() => void>()
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let running: AbortController | undefined
+
+  const set = (next: Partial<SearchState<Item>>) => {
+    state = { ...state, ...next }
+    listeners.forEach((listener) => listener())
+  }
+  const freePreview = (input: SearchInput) => {
+    if (input.kind === 'picture') URL.revokeObjectURL(input.preview)
+  }
+  const byFor = (input: SearchInput): SearchBy => chosenBy ?? (input.kind === 'words' ? 'both' : 'look')
+
+  const run = () => {
+    clearTimeout(timer)
+    running?.abort()
+    const { input } = state
+    if (input.kind === 'idle') return set({ status: 'idle', results: [], closest: [], error: null })
+    const controller = new AbortController()
+    running = controller
+    const by = byFor(input)
+    const options = { by: input.kind === 'similar' && by === 'both' ? 'look' : by, limit, filters: state.filters, signal: controller.signal } as const
+    set({ status: 'loading', by, error: null })
+    const answer = input.kind === 'words' ? client.byWords(input.text, options) : input.kind === 'picture' ? client.byPicture(input.picture, options) : client.similar(input.id, options)
+    answer.then(
+      ({ results, closest }) => controller === running && set({ status: 'done', results, closest }),
+      (error: unknown) => {
+        if (controller !== running || controller.signal.aborted) return
+        set({ status: 'error', error: error instanceof SearchError ? error : new SearchError(0, 'network', 'The search could not reach the server. Check the connection and retry.') })
+      },
+    )
+  }
+  const start = (input: SearchInput, wait = 0) => {
+    freePreview(state.input)
+    clearTimeout(timer)
+    set({ input })
+    if (wait) timer = setTimeout(run, wait)
+    else run()
+  }
+
+  return {
+    getState: () => state,
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    setWords: (text) => (text.trim().length < minLength ? start({ kind: 'idle' }) : start({ kind: 'words', text: text.trim() }, debounceMs)),
+    setPicture: (picture) => start({ kind: 'picture', picture, preview: URL.createObjectURL(picture) }),
+    similarTo: (id) => start({ kind: 'similar', id }),
+    setBy: (by) => {
+      chosenBy = by
+      set({ by })
+      run()
+    },
+    setFilters: (filters) => {
+      set({ filters })
+      run()
+    },
+    retry: run,
+    clear: () => start({ kind: 'idle' }),
+    dispose: () => {
+      clearTimeout(timer)
+      running?.abort()
+      freePreview(state.input)
+    },
+  }
+}
+
+const IMAGE = /^image\/(png|jpeg|webp|gif)$/
+
+/**
+ * The first picture in a paste, a drop or a file list, or null.
+ *
+ * @example
+ * window.addEventListener('paste', (event) => { const picture = pictureFrom(event.clipboardData) })
+ */
+export const pictureFrom = (source: DataTransfer | FileList | null | undefined): File | null => {
+  if (!source) return null
+  const files = 'items' in source ? Array.from(source.items, (item) => (item.kind === 'file' ? item.getAsFile() : null)) : Array.from(source)
+  return files.find((file): file is File => !!file && IMAGE.test(file.type)) ?? null
+}
+
+/**
+ * Listens on `target` (the window, or a drop zone) for a pasted (⌘V) or dropped picture. A paste without a picture,
+ * or one another handler already took, is left alone, so typing and pasting text keep working. Returns the cleanup.
+ *
+ * @example
+ * const stop = listenForPictures(window, (picture) => search.setPicture(picture))
+ */
+export const listenForPictures = (target: EventTarget, onPicture: (picture: File) => void, { paste = true, drop = true }: { paste?: boolean; drop?: boolean } = {}) => {
+  const onPaste = (event: Event) => {
+    const clipboard = (event as ClipboardEvent).clipboardData
+    const picture = event.defaultPrevented ? null : pictureFrom(clipboard)
+    if (!picture) return
+    event.preventDefault()
+    onPicture(picture)
+  }
+  const onDragOver = (event: Event) => {
+    if ((event as DragEvent).dataTransfer?.types.includes('Files')) event.preventDefault()
+  }
+  const onDrop = (event: Event) => {
+    const picture = pictureFrom((event as DragEvent).dataTransfer?.files)
+    if (!picture) return
+    event.preventDefault()
+    onPicture(picture)
+  }
+  if (paste) target.addEventListener('paste', onPaste)
+  if (drop) {
+    target.addEventListener('dragover', onDragOver)
+    target.addEventListener('drop', onDrop)
+  }
+  return () => {
+    target.removeEventListener('paste', onPaste)
+    target.removeEventListener('dragover', onDragOver)
+    target.removeEventListener('drop', onDrop)
+  }
+}

package/src/browser/search-react.ts

@@ -0,0 +1,116 @@
+/**
+ * React hooks over `search-client.ts`: the state and actions of a search, with no markup. Each app draws its own search
+ * box, picture chip and results; `vector-search.tsx` is one suggested way to, which an app can copy, restyle or skip.
+ *
+ *   useVectorSearch   one search (words, a picture, or one item's likeness) and what to do with it
+ *   usePictureInput   paste (⌘V), drop and a file picker that hand over a picture
+ *   useSimilar        items like one, reloaded when the id changes
+ *
+ * @example
+ * const client = useMemo(() => createSearchClient<RecipeCard>({ path: '/api/search', similarPath: '/api/recipes/{slug}/similar' }), [])
+ * const search = useVectorSearch(client, { limit: 48 })
+ * const picture = usePictureInput({ onPicture: search.setPicture })
+ * <input value={text} onChange={(event) => { setText(event.target.value); search.setWords(event.target.value) }} />
+ * <div {...picture.dropProps}>{search.results.map((result) => <Card key={result.item.id} {...result.item} />)}</div>
+ */
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore, type ChangeEvent, type DragEvent } from 'react'
+import { createSearchController, listenForPictures, pictureFrom, type SearchBy, type SearchClient, type SearchController, type SearchFilters, type SearchState } from './search-client'
+
+type ControllerOptions = Parameters<typeof createSearchController>[1]
+
+/**
+ * One search's state and actions. The controller lives as long as the component; a new client starts a new one.
+ *
+ * @example
+ * const { status, results, error, input, setWords, setPicture, setBy, clear } = useVectorSearch(client)
+ */
+export const useVectorSearch = <Item>(client: SearchClient<Item>, options: ControllerOptions = {}): SearchState<Item> & Omit<SearchController<Item>, 'getState' | 'subscribe' | 'dispose'> => {
+  const [controller, setController] = useState(() => createSearchController(client, options))
+  const made = useRef(client)
+  useEffect(() => {
+    if (made.current === client) return
+    made.current = client
+    setController(createSearchController(client, options))
+    // Options are read once per client, like a store's initial state
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client])
+  useEffect(() => () => controller.dispose(), [controller])
+  const state = useSyncExternalStore(controller.subscribe, controller.getState, controller.getState)
+  const { setWords, setPicture, similarTo, setBy, setFilters, retry, clear } = controller
+  return { ...state, setWords, setPicture, similarTo, setBy, setFilters, retry, clear }
+}
+
+const ACCEPT = 'image/png,image/jpeg,image/webp,image/gif'
+
+/**
+ * Paste, drop and pick a picture. Pastes are heard on the whole window by default (`paste: 'window'`), or only while
+ * focus is inside `scope`; `dropProps` go on whatever should take a drop, `inputProps` on a hidden file input.
+ *
+ * @example
+ * const picture = usePictureInput({ onPicture: search.setPicture })
+ * <div {...picture.dropProps} data-dragging={picture.dragging}>…<button onClick={picture.openPicker}>Choose a picture</button><input {...picture.inputProps} /></div>
+ */
+export const usePictureInput = ({ onPicture, paste = 'window', scope }: { onPicture: (picture: File) => void; paste?: 'window' | 'scope' | false; scope?: { current: HTMLElement | null } }) => {
+  const [dragging, setDragging] = useState(false)
+  const input = useRef<HTMLInputElement>(null)
+  const latest = useRef(onPicture)
+  latest.current = onPicture
+  useEffect(() => {
+    const target = paste === 'window' ? window : paste === 'scope' ? scope?.current : null
+    return target ? listenForPictures(target, (picture) => latest.current(picture), { drop: false }) : undefined
+  }, [paste, scope])
+  const take = useCallback((picture: File | null) => picture && latest.current(picture), [])
+  return {
+    dragging,
+    openPicker: () => input.current?.click(),
+    dropProps: {
+      onDragOver: (event: DragEvent) => {
+        if (!event.dataTransfer.types.includes('Files')) return
+        event.preventDefault()
+        setDragging(true)
+      },
+      onDragLeave: () => setDragging(false),
+      onDrop: (event: DragEvent) => {
+        setDragging(false)
+        const picture = pictureFrom(event.dataTransfer.files)
+        if (!picture) return
+        event.preventDefault()
+        take(picture)
+      },
+    },
+    inputProps: {
+      ref: input,
+      type: 'file' as const,
+      accept: ACCEPT,
+      hidden: true,
+      onChange: (event: ChangeEvent<HTMLInputElement>) => {
+        take(pictureFrom(event.target.files))
+        event.target.value = ''
+      },
+    },
+  }
+}
+
+/**
+ * Items like one, by look (default) or meaning; reloads when the id, `by` or the filters change, and stays idle
+ * without an id.
+ *
+ * @example
+ * const { status, results } = useSimilar(client, recipe.slug, { by: 'look', limit: 12 })
+ */
+export const useSimilar = <Item>(client: SearchClient<Item>, id: string | null | undefined, { by = 'look', limit, filters }: { by?: Exclude<SearchBy, 'both'>; limit?: number; filters?: SearchFilters } = {}) => {
+  const search = useVectorSearch(client, { by, limit, filters })
+  const filterKey = JSON.stringify(filters ?? {})
+  useEffect(() => {
+    if (!id) return search.clear()
+    search.similarTo(id)
+    // The controller's actions are stable; the inputs are the id and settings
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [id])
+  useEffect(() => {
+    if (search.by !== by) search.setBy(by)
+    if (JSON.stringify(search.filters) !== filterKey) search.setFilters(filters ?? {})
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [by, filterKey])
+  return { status: search.status, results: search.results, error: search.error, retry: search.retry }
+}