Production-ready animations, transitions, backgrounds, and scenes for Remotion
TypeScript ai-agentsclaude-codedemo-videomcpmcp-servermodel-context-protocolmotion-designproduct-demoreactremotionshadcnvideo
fix: components first for described needs; record agent search queries (#336)
KapishDima959fb5f29493
diff --git a/CLAUDE.md b/CLAUDE.mdindex b2c7696b..eff117d6 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -55,9 +55,9 @@ Solo builders и маленькие команды (1-2 чел), фронтен- Ранжирование гибридное (`lib/search/hybrid.ts`): лексический скор по `name`/`title`/`description`/`useWhen`/`askedAs` и семантика, слитые через reciprocal rank fusion. Слова держат точные имена, смысл — запросы, у которых с каталогом нет общих слов- Семантика — локальная модель `multilingual-e5-small` в процессе сервера (`@huggingface/transformers`), без API-ключей и платы за запрос. Модель и размерность зашиты в `lib/search/model.ts`- `bun run search:build` считает векторы (описание + каждая строка `askedAs`) в `.search/` и туда же кладёт модель. Каталог в git не попадает; Dockerfile собирает его перед `next build`. Нет индекса или модель не загрузилась — поиск молча работает по словам, поэтому в dev запускать сборку индекса не обязательно-- `/api/search` отдаёт результат в формате fumadocs: сначала гайды с совпадением в заголовке, потом компоненты, потом остальные полнотекстовые совпадения (`lib/search/docs-merge.ts`)+- `/api/search` отдаёт результат в формате fumadocs: сначала гайды, которые запрос называет целиком (и только пара их строк), потом компоненты, потом остальные полнотекстовые совпадения (`lib/search/docs-merge.ts`)- Аналитика поиска идёт в OpenPanel одним событием `search_performed` для всех, со свойствами `actor` (`human` / `agent`) и `surface` (`docs_dialog` / `mcp` / `api`). Человек: диалог (`components/docs/search-dialog.tsx`) шлёт события из браузера — запрос считается, когда на нём остановились (правила в `lib/search/dialog-session.ts`), плюс `search_result_selected` и `search_abandoned`. Агент: сервер шлёт `search_performed` из MCP-тула и из `/api/search` (всё, что пришло не из диалога) и `component_fetched` на `get_component` / `preview_component` — это аналог клика-- Текст запроса агента в аналитику не пишется: политика конфиденциальности (`app/(home)/legal/content.tsx`) обещает, что присланное MCP-серверу не хранится. Пишутся только длина, письменность и вернувшиеся компоненты. Флаг `LOG_AGENT_QUERY_TEXT` в `lib/server/analytics.ts` включать только вместе с правкой политики+- Текст поискового запроса агента пишется в аналитику (до 200 символов) — политика конфиденциальности (`app/(home)/legal/content.tsx`, «MCP server») это описывает. Брифы `plan_video` и пропсы `preview_component` не пишутся: расширять запись можно только вместе с правкой политики- `bun run search:eval` меряет поиск на `evals/search/golden.json` (топ-1/5/10 для слов и для гибрида). Меняешь ранжирование, модель или правила `askedAs` — сверяйся с ним; новые запросы в эталон приветствуются## Changelogdiff --git a/app/(home)/legal/content.tsx b/app/(home)/legal/content.tsxindex c314c7a7..adb922e4 100644--- a/app/(home)/legal/content.tsx+++ b/app/(home)/legal/content.tsx@@ -107,14 +107,14 @@ export const LEGAL_PARTS: LegalPart[] = [body: (<>The Remocn plugin for Claude Code and Codex and the MCP server at{" "}- <code>remocn.dev/mcp</code> need no account and collect no personal+ <code>remocn.dev/mcp</code> need no account and ask for no personaldata.</>),items: [{title: "MCP server.",- body: "The server is stateless. It answers each request from the public component catalog and does not store or log what you send it: search queries, video briefs and component props are used to build the answer and then discarded. We do count tool calls, to see whether the search works: which tool ran, which client called it, how long a query was and which catalog components came back. Those counts hold none of the text you sent. The standard access logs described above apply, as for the rest of the site.",+ body: "The server is stateless and has no accounts. Search queries sent to the search tool are recorded, cut to 200 characters, so we can see what agents look for and whether the search finds it. A recorded query is not tied to an account or an IP address; it is stored with the name of the calling client, the catalog components that came back and how long the answer took. Keep confidential details out of search queries. Video briefs and component props are used to build the answer and then discarded. We also count calls to the other tools: which tool ran and which component it asked for. The standard access logs described above apply, as for the rest of the site.",},{title: "Previews in chat.",diff --git a/app/api/search/route.ts b/app/api/search/route.tsindex 0be72da9..9421f14a 100644--- a/app/api/search/route.ts+++ b/app/api/search/route.ts@@ -1,7 +1,11 @@import { createFromSource } from "fumadocs-core/search/server";import { getCatalog } from "@/lib/mcp/catalog";import { searchCatalog } from "@/lib/search/components";-import { type ComponentHit, mergeDocsResults } from "@/lib/search/docs-merge";+import {+ type ComponentHit,+ fullTextQuery,+ mergeDocsResults,+} from "@/lib/search/docs-merge";import { trackAgentSearch } from "@/lib/server/analytics";import { source } from "@/source";@@ -32,7 +36,7 @@ export async function GET(request: Request) {const catalog = getCatalog();const started = performance.now();const [docs, { results: components, mode }] = await Promise.all([- docsSearch.search(query, {+ docsSearch.search(fullTextQuery(query), {tag,locale: url.searchParams.get("locale") ?? undefined,limit,diff --git a/evals/search/golden.json b/evals/search/golden.jsonindex b9845ae2..120120a0 100644--- a/evals/search/golden.json+++ b/evals/search/golden.json@@ -1,4 +1,8 @@[+ {+ "query": "i need show my contribution",+ "expect": ["contribution-heatmap"]+ },{"query": "show someone asking OpenAI's assistant a question","expect": ["chat-gpt"]diff --git a/lib/search/docs-merge.test.ts b/lib/search/docs-merge.test.tsindex 0ac06ad2..f3ae4f8a 100644--- a/lib/search/docs-merge.test.ts+++ b/lib/search/docs-merge.test.ts@@ -1,6 +1,10 @@import { describe, expect, it } from "bun:test";import type { SortedResult } from "fumadocs-core/search";-import { type ComponentHit, mergeDocsResults } from "./docs-merge";+import {+ type ComponentHit,+ fullTextQuery,+ mergeDocsResults,+} from "./docs-merge";const clock: ComponentHit = {name: "clock-sweep",@@ -105,4 +109,71 @@ describe("mergeDocsResults", () => {expect(merged[0].id).toBe("component:clock-sweep");expect(merged.at(-1)?.url).toBe("/docs/guides/setup");});++ it("does not promote a guide through one word of a described need", () => {+ const docs = [+ page("/docs/guides/showcase-reel", "<mark>Show</mark>case reel"),+ text("/docs/guides/showcase-reel#reel", "The reel"),+ ];++ const merged = mergeDocsResults(+ "i need show my contribution",+ docs,+ [clock],+ COMPONENT_URLS,+ );++ expect(merged[0].id).toBe("component:clock-sweep");+ });++ it("promotes a guide asked for in a sentence", () => {+ const docs = [+ page("/docs/getting-started/installation", "<mark>Install</mark>ation"),+ ];++ const merged = mergeDocsResults(+ "how to install",+ docs,+ [clock],+ COMPONENT_URLS,+ );++ expect(merged[0].url).toBe("/docs/getting-started/installation");+ });++ it("shows only a few lines of a leading guide", () => {+ const url = "/docs/getting-started/installation";+ const docs = [+ page(url, "<mark>Installation</mark>"),+ ...Array.from({ length: 9 }, (_, n) => text(`${url}#s${n}`, `line ${n}`)),+ ];++ const merged = mergeDocsResults(+ "installation",+ docs,+ [clock],+ COMPONENT_URLS,+ );++ expect(merged.findIndex((r) => r.id === "component:clock-sweep")).toBe(3);+ });+});++describe("fullTextQuery", () => {+ it("drops function words and stray letters", () => {+ expect(fullTextQuery("i need show my contribution")).toBe(+ "show contribution",+ );+ });++ it("keeps a query that names something", () => {+ expect(fullTextQuery("blur transition")).toBe("blur transition");+ expect(fullTextQuery("показать рост выручки")).toBe(+ "показать рост выручки",+ );+ });++ it("passes through a query made only of function words", () => {+ expect(fullTextQuery("how do i")).toBe("how do i");+ });});diff --git a/lib/search/docs-merge.ts b/lib/search/docs-merge.tsindex bda24836..f3370ef3 100644--- a/lib/search/docs-merge.ts+++ b/lib/search/docs-merge.ts@@ -33,26 +33,85 @@ function groupByPage(results: SortedResult[]): Map<string, SortedResult[]> {return groups;}+/**+ * Words that carry a sentence but name nothing. People now describe what they+ * need ("i need to show my contribution"), and the full-text search would+ * otherwise match the letter "i" on every page.+ */+const FUNCTION_WORDS = new Set([+ "a",+ "an",+ "and",+ "are",+ "can",+ "do",+ "does",+ "for",+ "how",+ "i",+ "in",+ "is",+ "it",+ "me",+ "my",+ "need",+ "of",+ "on",+ "or",+ "our",+ "some",+ "something",+ "that",+ "the",+ "this",+ "to",+ "want",+ "we",+ "what",+ "with",+ "you",+ "your",+]);++/**+ * The query the full-text search should run: the same words without the+ * function words and stray single letters. A query made only of those is+ * passed through as typed.+ */+export function fullTextQuery(query: string): string {+ const kept = query+ .trim()+ .split(/\s+/)+ .filter((word) => {+ const bare = word.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");+ return !FUNCTION_WORDS.has(bare) && !/^[a-z0-9]?$/.test(bare);+ });+ return kept.length > 0 ? kept.join(" ") : query;+}+function wordsOverlap(a: string, b: string): boolean {return a === b || (a.length >= 4 && b.startsWith(a)) || a.startsWith(b);}/**- * Whether the visitor is asking for this page by its title: at least half of- * the query's words appear in it. One shared word out of seven ("show that- * setup only takes five minutes" against the Setup guide) is a description- * that happens to touch the title, not a request for the guide.+ * Whether the visitor is asking for this page by its title: every word of the+ * query, function words aside, appears in it ("installation", "how to+ * install", "mcp server"). One shared word is not enough: "i need show my+ * contribution" touches "Showcase reel" through "show", and is a described+ * need, not a request for that guide.*/function namesTitle(group: SortedResult[], queryWords: string[]): boolean {const title = group.find((r) => r.type === "page")?.content;if (!title || queryWords.length === 0) return false;const titleWords = tokenize(title.replace(/<\/?mark>/g, ""));- const shared = queryWords.filter((word) =>+ return queryWords.every((word) =>titleWords.some((titleWord) => wordsOverlap(word, titleWord)),);- return shared.length * 2 >= queryWords.length;}+/** Matched lines shown under a guide that leads the results. */+const GUIDE_LINES = 2;+function sectionLabel(slug: string): string {return slug.replace(/(^|-)([a-z])/g, (_, sep: string, c: string) =>(sep ? " " : "").concat(c.toUpperCase()),@@ -76,16 +135,24 @@ export function mergeDocsResults(componentUrls: ReadonlySet<string>,): SortedResult[] {const groups = groupByPage(docs);- const queryWords = tokenize(query);+ const queryWords = tokenize(query).filter(+ (word) => !FUNCTION_WORDS.has(word),+ );const shown = new Set(components.map((c) => c.url));const guides: SortedResult[] = [];const rest: SortedResult[] = [];for (const [url, group] of groups) {if (shown.has(url)) continue;- if (!componentUrls.has(url) && namesTitle(group, queryWords))- guides.push(...group);- else rest.push(...group);+ if (!componentUrls.has(url) && namesTitle(group, queryWords)) {+ // A long guide matches on dozens of lines; all of them above the+ // components would push every component off the first screen.+ const lines = group.filter((r) => r.type !== "page");+ guides.push(+ ...group.filter((r) => r.type === "page"),+ ...lines.slice(0, GUIDE_LINES),+ );+ } else rest.push(...group);}const componentRows = components.flatMap((component): SortedResult[] => {diff --git a/lib/server/analytics.ts b/lib/server/analytics.tsindex 79ab41ce..f8135e2c 100644--- a/lib/server/analytics.ts+++ b/lib/server/analytics.ts@@ -51,15 +51,6 @@ export async function trackRegistryInstall(}}-/**- * Whether agent searches are recorded with their text. Off: the privacy policy- * (`app/(home)/legal/content.tsx`, "MCP server") promises that what an agent- * sends is discarded, so an agent search is described by its shape (length,- * script) and by the components it returned, never quoted. Turning this on- * means rewriting that promise first.- */-const LOG_AGENT_QUERY_TEXT = false;-function send(event: string, properties: Record<string, unknown>): void {// Never awaited: analytics must not add to a response time, and a metrics// outage must never reach the caller.@@ -85,6 +76,11 @@ export interface AgentSearch {* A search made by a program: an MCP `search_components` call or a direct* call to `/api/search`. Same event name as the dialog's, told apart by* `actor` and `surface`.+ *+ * The query text is recorded, cut to `MAX_LOGGED_QUERY`. The privacy policy+ * (`app/(home)/legal/content.tsx`, "MCP server") says so and names the limit:+ * search queries only. Video briefs and component props stay out of+ * analytics, and widening this needs that paragraph changed first.*/export function trackAgentSearch(search: AgentSearch): void {if (isCrawler(search.userAgent)) return;@@ -93,7 +89,7 @@ export function trackAgentSearch(search: AgentSearch): void {surface: search.surface,client: classifyAgentClient(search.userAgent),user_agent: search.userAgent.slice(0, 200),- ...(LOG_AGENT_QUERY_TEXT ? { query: loggedQuery(search.query) } : {}),+ query: loggedQuery(search.query),...describeQuery(search.query),result_count: search.results.length,component_count: search.results.length,