Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

Merge remote-tracking branch 'origin/staging' into t3/reduce-dev-server-build-load

kapishdima42a217cc5f1b
diff --cc .dockerignore
index 730d36d6,037ee719..b9770c2c
--- a/.dockerignore
+++ b/.dockerignore
@@@ -12,4 -12,4 +12,5 @@@ node_module
coverage
.vercel
.source
+public/_previews
+ .search
diff --cc .gitignore
index 8a14807d,5e69bcef..bce005e2
--- a/.gitignore
+++ b/.gitignore
@@@ -43,9 -43,9 +43,12 @@@ next-env.d.t
# fumadocs generated source
.source/
+# preview bundle (scripts/previews/build.mts)
+/public/_previews/
+
+ # semantic search index + embedding model (bun run search:build)
+ .search/
+
.omc
articles
diff --cc CLAUDE.md
index 275cbcce,eff117d6..79151ae7
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -42,24 -41,25 +42,37 @@@ Solo builders и маленькие к�
Доки описывают компоненты и для людей, и для AI-агентов. Скилл `remocn` не хранит свою копию каталога, а читает документацию по URL, поэтому страница компонента — единственное место, где живут его пропсы, пример и сигнал выбора.
- Каждый item из registry обязан иметь страницу с `component: <name>` во frontmatter. Исключения перечислены в `UNDOCUMENTED` в `lib/docs-meta.test.ts` и требуют причины — это либы, внутренние примитивы и sub-item'ы, свёрнутые в страницу контейнера. Иконки документируются галереей, а не страницей на штуку
- - Frontmatter компонента: `component`, `vibe` (одно из семи значений в `lib/docs-schema.ts`), `length`, `useWhen` и `avoidWhen` — списки строк в двойных кавычках. Поля машинные, на странице не рендерятся
+ - Frontmatter компонента: `component`, `vibe` (одно из семи значений в `lib/docs-schema.ts`), `length`, `useWhen`, `avoidWhen` и `askedAs` — списки строк в двойных кавычках. Поля машинные, на странице не рендерятся
+ - `askedAs` — 5–8 формулировок, которыми компонент попросит человек, не видевший каталога: пара коротких запросов в 2–5 слов, пара фраз «хочу…», пара про задачу сцены. Без имени компонента и без слов из `description` там, где есть бытовой синоним («subtitles», а не «captions») — поле ценно именно словарём, которого в описании нет. На английском, до 90 символов, без двойных кавычек внутри. По этим строкам работает поиск, см. «Поиск компонентов»
- `length` — кадры **собственного движения** компонента при 30fps: у перехода это значение для `linearTiming`/`springTiming`, у остальных — момент, когда анимация закончилась. Это нижняя граница `Sequence`, а не длина бита: холд сверху добавляется отдельно. Поэтому `length` намеренно расходится с `durationInFrames` в `config.ts` — там длина демо-композиции вместе с холдом. `"state-driven"` — компонент рендерится из пропа `state` и своей длительности не имеет
- В `avoidWhen` называй компонент-замену в бэктиках. Тест валит сборку, если такого имени нет в registry
+- MDX-страница доков не содержит `import` и `export`. Коллекция `docs` компилируется в рантайме (`dynamic: true` в `source.config.ts`): страница собирается, когда её рендерят — по запросу в dev и во время пререндера в `next build`. Иначе первый запрос доков в dev компилирует все ~900 страниц. Компонент, нужный отдельной странице, регистрируется в `components/docs/mdx-page-components.ts`, общий для всех страниц — в `mdx-components.tsx`. Blog и changelog собираются бандлером, им импорты разрешены
- `bun test lib/docs-meta.test.ts` — блокирующий шаг CI, отдельный от основного прогона тестов (тот пока `continue-on-error`)
- Агентские артефакты генерируются из этого frontmatter: `/llms-components.txt` (роутер по всем компонентам) и `/docs/**.md` (страница как чистый markdown, см. `lib/mdx-to-markdown.ts`)
+## Превью собираются отдельно
+
+`registry/__index__.tsx` перечисляет ~900 превью, у каждого ленивый импорт компонента и конфига. Turbopack компилирует ленивые импорты сразу, поэтому с этим индексом в графе сайта первый запрос любой страницы с превью компилировал все превью. Теперь индекс собирает Bun, а сайт загружает результат по URL.
+
+- `scripts/previews/build.mts` собирает индекс в `public/_previews/` за ~0,3 с: dev-сборка лежит в `dev/`, production — в `prod/`, друг друга они не затирают. Один набор файлов читают и браузер (`/_previews/…`), и сервер (с диска). Все скрипты названы по хешу содержимого. `react` и `remotion` в сборку не входят: превью берут их у страницы, список общих модулей — `lib/previews/shared-modules.ts`
+- Код сайта импортирует `@/lib/previews` и никогда `@/registry/__index__`: экспорты те же. Тест в `lib/docs-meta.test.ts` это проверяет. Скрипты и Remotion Studio по-прежнему импортируют сам индекс
+- `bun dev` (`scripts/dev.mts`) собирает превью, запускает `next dev` и пересобирает превью при сохранении их исходников. Открытая страница получает сборку по WebSocket и подменяет изменённые превью на месте, без перезагрузки (`lib/previews/hot.ts`). Ошибка сборки печатается в терминале `bun dev`, страница остаётся на последней удачной сборке
+- `bun run build` сначала собирает превью (`bun run previews:build`), затем сайт. `next build` без собранных превью падает на пререндере с подсказкой. Пересобрать превью после `next build` и не пересобрать сайт нельзя: страницы ссылаются на прежний входной файл
+- `registry/__names__.ts` — сгенерированный список имён превью, коммитится. Его переписывает любая сборка превью, когда меняются ключи `registry/__index__.tsx`; тест проверяет, что он не отстал
+- Сервер загружает только конфиги. `load()` на сервере отклоняется: плеер с `lazyComponent={load}` монтируется после гидрации
+
+ ## Поиск компонентов
+
+ Один поиск на два входа: `searchCatalog` в `lib/search/components.ts` обслуживает и MCP-тул `search_components`, и `/api/search` (диалог ⌘K в доках). Запрос — описание потребности на любом языке, а не только имя.
+
+ - Ранжирование гибридное (`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`)
+ - Аналитика поиска идёт в 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` — это аналог клика
+ - Текст поискового запроса агента пишется в аналитику (до 200 символов) — политика конфиденциальности (`app/(home)/legal/content.tsx`, «MCP server») это описывает. Брифы `plan_video` и пропсы `preview_component` не пишутся: расширять запись можно только вместе с правкой политики
+ - `bun run search:eval` меряет поиск на `evals/search/golden.json` (топ-1/5/10 для слов и для гибрида). Меняешь ранжирование, модель или правила `askedAs` — сверяйся с ним; новые запросы в эталон приветствуются
+
## Changelog
Любая ветка, которая добавляет или заметно меняет компоненты registry, обязана содержать запись ченджлога — в том же PR, что и сама фича.
diff --cc app/api/search/route.ts
index 49c2151b,9421f14a..950ddbc8
--- a/app/api/search/route.ts
+++ b/app/api/search/route.ts
@@@ -1,7 -1,83 +1,86 @@@
import { createFromSource } from "fumadocs-core/search/server";
+import { docsSearchIndex } from "@/lib/docs-search-index";
+ import { getCatalog } from "@/lib/mcp/catalog";
+ import { searchCatalog } from "@/lib/search/components";
+ import {
+ type ComponentHit,
+ fullTextQuery,
+ mergeDocsResults,
+ } from "@/lib/search/docs-merge";
+ import { trackAgentSearch } from "@/lib/server/analytics";
import { source } from "@/source";
- export const { GET } = createFromSource(source, {
-const docsSearch = createFromSource(source);
++const docsSearch = createFromSource(source, {
+ buildIndex: docsSearchIndex,
+});
+
+ /** How many components lead the results of the docs search dialog. */
+ const COMPONENT_RESULTS = 6;
+
+ let componentUrls: Set<string> | undefined;
+
+ /**
+ * The docs search: full-text matches from fumadocs, with the components that
+ * fit the query by meaning placed among them. The response keeps the fumadocs
+ * shape, so the stock search dialog renders it unchanged.
+ */
+ export async function GET(request: Request) {
+ const url = new URL(request.url);
+ const query = url.searchParams.get("query");
+ if (!query) return Response.json([]);
+
+ const limitParam = Number(url.searchParams.get("limit"));
+ const limit =
+ url.searchParams.has("limit") && Number.isInteger(limitParam)
+ ? limitParam
+ : undefined;
+ const tag = url.searchParams.get("tag")?.split(",");
+
+ const catalog = getCatalog();
+ const started = performance.now();
+ const [docs, { results: components, mode }] = await Promise.all([
+ docsSearch.search(fullTextQuery(query), {
+ tag,
+ locale: url.searchParams.get("locale") ?? undefined,
+ limit,
+ }),
+ // A tag narrows the search to one slice of the docs; the component
+ // ranking knows nothing about tags, so it stays out of a tagged search.
+ tag
+ ? { results: [], mode: undefined }
+ : searchCatalog({ query, limit: COMPONENT_RESULTS }),
+ ]);
+
+ // The search dialog reports its own searches from the browser, where it
+ // knows which ones the visitor settled on and what they opened. Any other
+ // caller is a program using the documented API, and is counted here.
+ if (request.headers.get("sec-fetch-site") !== "same-origin") {
+ trackAgentSearch({
+ surface: "api",
+ userAgent: request.headers.get("user-agent") ?? "",
+ query,
+ results: components.map((record) => record.name),
+ mode,
+ latencyMs: performance.now() - started,
+ });
+ }
+
+ const hits = components.flatMap((record): ComponentHit[] => {
+ const page = catalog.pages.get(record.name);
+ return page
+ ? [
+ {
+ name: record.name,
+ title: record.title,
+ description: record.description,
+ url: page.url,
+ section: record.section,
+ },
+ ]
+ : [];
+ });
+ componentUrls ??= new Set([...catalog.pages.values()].map((p) => p.url));
+
+ const merged = mergeDocsResults(query, docs, hits, componentUrls);
+ return Response.json(limit === undefined ? merged : merged.slice(0, limit));
+ }
diff --cc bun.lock
index 8473720f,9a9d9962..3629ee35
--- a/bun.lock
+++ b/bun.lock
@@@ -9,9 -9,9 +9,10 @@@
"@fontsource/inter": "^5.3.0",
"@fontsource/manrope": "^5.2.8",
"@fontsource/roboto-mono": "^5.3.0",
+ "@fumadocs/mdx-remote": "^1.4.6",
"@hugeicons/core-free-icons": "^4.3.0",
"@hugeicons/react": "^1.1.10",
+ "@huggingface/transformers": "^4.3.2",
"@modelcontextprotocol/server": "^2.3.1",
"@openpanel/nextjs": "^1.0.13",
"@openpanel/sdk": "^1.3.1",
diff --cc package.json
index b8fb97b7,d8999794..c27d6027
--- a/package.json
+++ b/package.json
@@@ -49,9 -50,9 +51,10 @@@
"@fontsource/inter": "^5.3.0",
"@fontsource/manrope": "^5.2.8",
"@fontsource/roboto-mono": "^5.3.0",
+ "@fumadocs/mdx-remote": "^1.4.6",
"@hugeicons/core-free-icons": "^4.3.0",
"@hugeicons/react": "^1.1.10",
+ "@huggingface/transformers": "^4.3.2",
"@modelcontextprotocol/server": "^2.3.1",
"@openpanel/nextjs": "^1.0.13",
"@openpanel/sdk": "^1.3.1",