Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
perf(animations): serve one clip, and exact counts, without the whole manifest
nirholas3bf8d1c83601
diff --git a/api/animations/library.js b/api/animations/library.jsindex 9b3f61be2..eef8274cb 100644--- a/api/animations/library.js+++ b/api/animations/library.js@@ -15,9 +15,26 @@// array, so a caller can page it with ?limit= (1..1000) and ?offset= to keep any// single response bounded as the catalog grows past thousands of clips. With no// ?limit the full array is returned exactly as before, so existing consumers-// (embed viewer, pose deep-link lookup, the older gallery build) are unchanged.-// Paged responses add `offset` + `next_offset` (null on the last page); `total`-// is always the full catalog size regardless of paging.+// (the older gallery build) are unchanged. Paged responses add `offset` ++// `next_offset` (null on the last page); `total` is always the full catalog size+// regardless of paging.+//+// Facets: ?facets=1 returns the catalog's size and its per-category counts and+// no clips at all. The /animations gallery needs exact totals for its hero line+// and its filter chips, and deriving them client-side means holding the whole+// catalog in the browser, which is the reason the gallery downloaded every page+// on load. The classifier that produces a category is shared with the gallery+// (src/animation-categories.js), so a count here and a chip there can never+// disagree.+//+// Name lookup: ?name=<clip> (repeatable, or comma-separated) returns only the+// entries with those exact names. Paging cannot serve that caller, because a+// deep-link resolves ONE clip by name and has no idea which page holds it, so+// its only alternative is the whole manifest. That is what the pose deep-link+// (src/animation-library.js) and the embed viewer (src/avatar-embed.js) used to+// do, and at 1.1 MB per lookup for a single 3 KB entry it is the response that+// grows worst as the catalog does. Names are capped at MAX_NAMES per request so+// the lookup stays bounded too; unknown names are simply absent from `clips`.//// TWO MANIFESTS, ONE CATALOG. The Mixamo bake and the generative text-to-motion// seeder each own their own manifest object and never write the other's:@@ -37,10 +54,36 @@import { cors, json, method, wrap } from '../_lib/http.js';import { getPublicObjectBuffer } from '../_lib/r2.js';+import { GALLERY_CATEGORIES, galleryCategoryOf } from '../../src/animation-categories.js';const MANIFEST_KEY = 'animations/library/manifest.json';const GENERATED_MANIFEST_KEY = 'animations/library/generated/manifest.json';const MAX_PAGE = 1000;+// Ceiling on ?name= entries per request. A deep-link resolves one clip and an+// avatar with a full animation set resolves a handful, so this is generous for+// every real caller while keeping the response bounded.+const MAX_NAMES = 50;++/**+ * Parse ?name= into a deduped, bounded list of exact clip names. Accepts the+ * param repeated (?name=a&name=b) and comma-separated (?name=a,b), because both+ * spellings are natural to write and neither is ambiguous: a clip name never+ * contains a comma.+ *+ * @param {URLSearchParams} params+ * @returns {string[]}+ */+function parseNames(params) {+ const seen = new Set();+ for (const raw of params.getAll('name')) {+ for (const part of String(raw).split(',')) {+ const name = part.trim();+ if (name) seen.add(name);+ if (seen.size >= MAX_NAMES) return [...seen];+ }+ }+ return [...seen];+}/*** Read one manifest object. A missing object is the expected state for the@@ -92,6 +135,27 @@ export default wrap(async (req, res) => {res.setHeader('Cache-Control', 'public, s-maxage=300, stale-while-revalidate=3600');const url = new URL(req.url, 'http://x');++ if (url.searchParams.get('facets') === '1') {+ const counts = new Map(GALLERY_CATEGORIES.map((c) => [c.key, 0]));+ for (const clip of clips) {+ const key = galleryCategoryOf(clip?.name || '', clip?.label || '');+ counts.set(key, (counts.get(key) || 0) + 1);+ }+ return json(res, 200, {+ total,+ categories: [...counts].map(([key, count]) => ({ key, count })),+ generated_at: generatedAt,+ });+ }++ const names = parseNames(url.searchParams);+ if (names.length) {+ const wanted = new Set(names);+ const matched = clips.filter((c) => c?.name && wanted.has(c.name));+ return json(res, 200, { clips: matched, total, generated_at: generatedAt });+ }+const rawLimit = url.searchParams.get('limit');if (rawLimit == null) {// Legacy full-catalog response — unchanged contract.diff --git a/docs/animation-seeding.md b/docs/animation-seeding.mdindex 8cd7dda87..3997b7f61 100644--- a/docs/animation-seeding.md+++ b/docs/animation-seeding.md@@ -294,32 +294,79 @@ batch, so a later batch cannot hand out a second set of free clips.Measured 2026-09-02 against the live site, with 2,874 clips in the library and58,544 avatars in the catalog.-`GET /api/animations/library` already supports paging (`?limit=`, `?offset=`), and a-paged response is small: 24.6 KB for `?limit=60`. **With no `?limit` it returns the-entire manifest**, which is 1.12 MB uncompressed today (about 100 KB on the wire,+`GET /api/animations/library` pages with `?limit=` and `?offset=`, and a paged+response is small: 24.6 KB for `?limit=60`. With no `?limit` it returns the entire+manifest, which is 1.14 MB uncompressed at 3,007 clips (about 100 KB on the wire,since the CDN serves it brotli-compressed). That un-paged form is the documented-backward-compatible contract, and three consumers still use it:--- `src/animations-gallery.js` (the `/animations` gallery)-- `src/animation-library.js` (pose deep-link lookup by clip name)-- `src/avatar-embed.js` (the embed viewer)+backward-compatible contract and it stays, but **nothing three.ws ships asks for it+any more.** Two more query shapes landed on 2026-09-09 so no consumer has to:++| Query | Returns | Size at 3,007 clips | Size at 30,070 |+|---|---|---|---|+| `?name=<clip>` | just the named clips (up to 50 per request) | 365 B | 480 B |+| `?facets=1` | catalog total plus per-category counts, no clips | 541 B | 558 B |+| `?limit=1000&offset=0` | one bounded page | 388 KB | 397 KB |+| (no params) | the whole manifest | 1.14 MB | 11.5 MB |++Both are flat in the catalog size, which is the point.++### What each consumer does now++- `src/animation-library.js` (pose deep-link) and `src/avatar-embed.js` (embed+ viewer) each resolve ONE clip by name. Paging cannot serve them, because neither+ knows which page holds the name, so both used to download the whole manifest for+ a single 3 KB entry: on every embed load carrying `?animation=`. They now ask+ `?name=`, measured in a real browser at 365 B and 474 B against the live catalog,+ a 3,190x smaller response for the same answer.+- `src/animations-gallery.js` (the `/animations` gallery) loads **one page** plus+ `?facets=1` and stops. Further pages are fetched when a reader actually reaches+ the end of the grid. It used to fetch every page on load: 3 requests at 3,007+ clips, 30 at ten times that, paid by every visitor who reads the first screen and+ leaves.+- `packages/vscode-3d/src/animations.js` pages already and is unchanged.++The gallery's totals do not wait for the catalog. `?facets=1` counts it server-side+with the same classifier the gallery uses (`src/animation-categories.js`), so the+hero line and every filter chip read true at first paint and never count upward as+pages arrive.++Searching, filtering by category or re-sorting DOES need every clip, because all+three run client-side over the whole gallery, and a count like "63 of 3,119" has to+mean every match rather than every match among the pages that happen to be loaded.+Those actions drain the remaining pages in the background and the grid refreshes as+they land. Idle browsing, which is the common case, never pays for it. A URL that+arrives already narrowed (`?cat=`, `?q=`, `?sort=`) drains for the same reason, and+so does a `?clip=` deep link whose clip has not been loaded yet: a shared link must+open the clip it names.++### Measured at ten times the catalog++Verified in Chromium against a synthetic 30,070-clip catalog served through the real+endpoint:++| | Before | After |+|---|---|---|+| `/animations` first paint | 30 requests, 11.5 MB | 2 requests, 389 KB |+| Hero and chip counts at first paint | partial, counting up as pages land | exact |+| Scrolling to the end of the grid | already loaded | one 397 KB page per screenful |+| A search across the whole catalog | already loaded | 3.1 s to drain, results stream in |+| Embed resolving one clip by name | 11.5 MB | 480 B |-At 5 to 10 times the current library those three each parse 6 to 11 MB of JSON on-load. The gallery is the one to fix first, because it only ever renders a page at a-time and has no reason to hold the whole manifest; the other two look a clip up by-name, so they need either a name-indexed endpoint or a cached shard rather than-simple paging. None of this is urgent at 2,874 clips and all of it bites well before-30,000.+The remaining trade is deliberate: a deliberate search at 30,000 clips reads the+catalog once, cached by the CDN and the browser, instead of every visitor reading it+once.The other list surfaces are already scale-safe and need no change. Measured at-58,544 avatars, each returns a bounded first page even with **no** `?limit` given:+68,971 avatars (2026-09-09), each returns a bounded first page even with **no**+`?limit` given:| Endpoint | No limit | `?limit=24` ||---|---|---|-| `/api/marketplace` | 22.8 KB | 22.8 KB |-| `/api/avatars/public` | 38.3 KB | 38.3 KB |-| `/api/marketplace/animations` | cursor-paged, `limit` ceiling 60 |-| `/api/animations/library` | **1.12 MB, the whole manifest** | 24.6 KB |--So the clip library is the single unbounded response on the platform, and the fix is-the three consumers above rather than the endpoint, which already pages.+| `/api/marketplace` | 22 KB | 22 KB |+| `/api/avatars/public` | 39 KB | 39 KB |+| `/api/marketplace/animations` | cursor-paged, `limit` ceiling 60 | |+| `/api/animations/library` | 1.14 MB, the whole manifest, no first-party caller | 24.6 KB |++`/gallery` pages at `?limit=24` with lazy thumbnails, and `/dashboard/avatars` is+cursor-paged with an IntersectionObserver, both verified live at that catalog size+with no console errors.diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 5de837434..be0510312 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -5767,6 +5767,8 @@ Each entry's `url` is an absolute CDN URL to the baked clip JSON (`THREE.Animati| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- || `limit` | Page size, `1`–`1000`. When set, the response is a bounded page instead of the whole catalog — use this to keep a single response small as the library grows. || `offset` | Zero-based start index into the ordered catalog. Default `0`. |+| `name` | Exact clip name. Repeat it (`?name=a&name=b`) or comma-separate (`?name=a,b`) for up to 50 names; the response holds only those clips. Unknown names are simply absent. |+| `facets` | `1` returns the catalog's size and its per-category counts, and no clips at all. |The manifest is a stable ordered array, so paging is offset-based. A paged response adds `offset` and `next_offset` (`null` on the last page); `total` is always the full catalog size. Page until `next_offset` is `null`:@@ -5777,6 +5779,28 @@ GET /api/animations/library?limit=1000&offset=1000 # next 1000 → next_offset:Omitting `limit` returns the full array exactly as before (no `offset`/`next_offset` fields) — the legacy contract is unchanged.+**Resolving one clip by name.** Paging cannot serve a caller that knows a clip's name and nothing else, because it has no idea which page holds it. `?name=` answers that in a few hundred bytes instead of the whole manifest, which is what a pose deep-link and the embed viewer used to download for a single entry:++```+GET /api/animations/library?name=mx-hip-hop-dancing # 365 B, not 1.1 MB+GET /api/animations/library?name=mx-walking,mx-running # up to 50 names+```++**Counting the catalog.** `?facets=1` returns the total and the per-category breakdown with no clips attached, so a browse UI can render exact totals and filter counts without holding the catalog:++```json+{+ "total": 3007,+ "categories": [+ { "key": "idle", "count": 184 },+ { "key": "locomotion", "count": 693 }+ ],+ "generated_at": "2026-07-05T11:01:51.610Z"+}+```++Categories come from the same classifier the `/animations` gallery uses (`src/animation-categories.js`), so a count here and a filter chip there always agree. Every category is listed, including the empty ones, so a UI built from this response keeps a stable set of controls. The response is about half a kilobyte whatever the catalog size.+**Response**```jsondiff --git a/src/animation-library.js b/src/animation-library.jsindex 67497d1a1..221efd9fa 100644--- a/src/animation-library.js+++ b/src/animation-library.js@@ -154,11 +154,16 @@ export class AnimationLibrary {* manifest; their defs carry an absolute CDN url that preview()/_loadClip()* fetch like any other. Returns null when the library doesn't know the* name either (including before the library has been uploaded).+ *+ * Asks the endpoint for the single name rather than downloading the whole+ * manifest to find one entry in it: the catalog is thousands of clips and+ * growing with every seeding batch, so the unfiltered response is over a+ * megabyte of JSON to resolve about three kilobytes of it.* @param {string} name*/async _lookupFullLibrary(name) {try {- const res = await fetch('/api/animations/library');+ const res = await fetch(`/api/animations/library?name=${encodeURIComponent(name)}`);if (!res.ok) return null;const data = await res.json();return (data.clips || []).find((d) => d.name === name) || null;diff --git a/src/animations-gallery.js b/src/animations-gallery.jsindex 18d1dced3..d290b4f3b 100644--- a/src/animations-gallery.js+++ b/src/animations-gallery.js@@ -11,9 +11,24 @@// All are normalized to one card shape — poster thumbnail, derived category// (src/animation-categories.js), duration, loop mode — then filtered (search +// category + loop/once), sorted, and paginated client-side (PAGE_SIZE at a time,-// infinite-scroll, lazy thumbnails). The full catalog is fetched from the CDN in-// bounded pages (LIBRARY_PAGE_SIZE) rather than one large response, so a library-// that grows past thousands of clips never lands as a single unbounded payload.+// infinite-scroll, lazy thumbnails).+//+// THE CATALOG IS LOADED ON DEMAND, one bounded page at a time, because it is the+// only source here with no ceiling on its size. A first load costs exactly one+// page plus the tiny ?facets=1 response, at any catalog size; further pages are+// fetched when the reader actually reaches the end of the grid. Loading every+// page up front was 3 requests at 3,007 clips and would be 30 at ten times that,+// paid by every visitor who looks at the first screen and leaves.+//+// Exact totals do NOT wait for that. ?facets=1 returns the catalog's size and+// its per-category counts in about half a kilobyte, computed with the same+// classifier this file uses, so the hero line and the filter chips read true+// from the first paint and never count up as pages arrive.+//+// Searching, filtering or re-sorting DOES need the whole catalog, because those+// run client-side over every clip, so those three actions drain the remaining+// pages in the background and the grid refreshes as they land. That is the+// trade: a deliberate narrowing pays for the catalog, idle browsing does not.//// Previews run through ONE shared WebGL engine (src/animations-live-preview.js):// hovering a card (or opening the detail modal) moves the singleton canvas into@@ -103,6 +118,21 @@ const state = {shown: 0,loaded: false,modalIndex: -1, // index into state.filtered while the modal is open+ // Names the curated manifest already surfaces, so the same clip never lands+ // twice when the catalog page carrying it arrives.+ curatedNames: new Set(),+ shuffleSeed: (Math.random() * 0xffffffff) >>> 0,+ catalog: {+ offset: 0, // next page to request+ loaded: 0, // rows merged into state.all so far+ total: 0, // full catalog size, known from ?facets=1 before any page lands+ byCategory: new Map(), // merged rows per category, to net off the facets+ facets: null, // Map<categoryKey, count> over the WHOLE catalog+ pending: null, // in-flight page, so overlapping triggers coalesce+ draining: false,+ done: false,+ failed: false,+ },};const live = getLivePreview();@@ -153,36 +183,111 @@ async function fetchCommunity() {}/**- * Page through the full CDN catalog with the endpoint's opt-in ?limit/?offset so- * each response is bounded and individually CDN-cacheable. `next_offset: null`- * marks the last page; the page ceiling is a runaway guard.+ * Catalog size and per-category counts, without a single clip attached. The+ * counts come from the same classifier this file uses, so a chip and the+ * endpoint can never disagree, and they are exact from the first paint however+ * many pages are still unfetched.+ */+async function fetchCatalogFacets() {+ const res = await fetch(`${LIBRARY_API}?facets=1`, { cache: 'force-cache' });+ if (!res.ok) throw new Error(`HTTP ${res.status}`);+ const data = await res.json();+ const cat = state.catalog;+ cat.total = Number(data.total) || 0;+ cat.facets = new Map(+ (Array.isArray(data.categories) ? data.categories : []).map((c) => [c.key, Number(c.count) || 0]),+ );+}++/**+ * Fetch ONE bounded page of the catalog and merge it into the grid. Overlapping+ * callers (the scroll sentinel and a drain running together) share the one+ * in-flight request rather than racing two pages at the same offset.*- * Each page is handed to `onPage` as soon as it lands rather than being held- * back until the whole catalog is in hand. The grid used to wait for every page- * before painting a single card, so time-to-first-card was the size of the- * entire library: 1.1 MB at 2,874 clips, and growing with every seeding batch.- * Streaming makes first paint cost one page no matter how large the catalog- * gets, which is the whole reason the endpoint pages at all.+ * Resolves to false once the catalog is exhausted or has failed, which is what+ * lets drainCatalog() terminate.*- * @param {(clips: object[]) => void} [onPage]+ * @returns {Promise<boolean>} whether a page was merged*/-async function fetchFullLibrary(onPage) {- const out = [];- let offset = 0;- for (let i = 0; i < LIBRARY_MAX_PAGES; i++) {- const res = await fetch(`${LIBRARY_API}?limit=${LIBRARY_PAGE_SIZE}&offset=${offset}`, {- cache: 'force-cache',- });+function loadCatalogPage() {+ const cat = state.catalog;+ if (cat.pending) return cat.pending;+ if (cat.done || cat.failed) return Promise.resolve(false);+ if (cat.offset >= LIBRARY_PAGE_SIZE * LIBRARY_MAX_PAGES) {+ cat.done = true;+ return Promise.resolve(false);+ }++ cat.pending = (async () => {+ const url = `${LIBRARY_API}?limit=${LIBRARY_PAGE_SIZE}&offset=${cat.offset}`;+ const res = await fetch(url, { cache: 'force-cache' });if (!res.ok) throw new Error(`HTTP ${res.status}`);const data = await res.json();- const clips = Array.isArray(data.clips) ? data.clips : [];- const normalized = clips.map(normalizeFullLibraryClip);- out.push(...normalized);- if (onPage && normalized.length) onPage(normalized);- if (data.next_offset == null || clips.length === 0) break;- offset = data.next_offset;+ const rows = Array.isArray(data.clips) ? data.clips : [];+ if (!cat.total) cat.total = Number(data.total) || 0;++ const fresh = rows+ .map(normalizeFullLibraryClip)+ .filter((c) => !state.curatedNames.has(c.id));+ for (const clip of fresh) {+ cat.byCategory.set(clip.category, (cat.byCategory.get(clip.category) || 0) + 1);+ }+ cat.loaded += fresh.length;+ if (fresh.length) state.all = state.all.concat(fresh);+ if (data.next_offset == null || rows.length === 0) cat.done = true;+ else cat.offset = Number(data.next_offset);+ return fresh.length > 0;+ })()+ .catch((err) => {+ // One bad page must not strand the grid the reader is already using,+ // and must not spin the sentinel: mark the catalog failed so the+ // counts stop promising rows that will never arrive.+ cat.failed = true;+ cat.done = true;+ throw err;+ })+ .finally(() => {+ cat.pending = null;+ });++ return cat.pending;+}++/**+ * Load every remaining page. Search, category and sort all run client-side over+ * the whole set, so narrowing the view is the moment the rest of the catalog has+ * to exist. The grid repaints as each page lands, keeping what is already on+ * screen in place.+ */+async function drainCatalog() {+ const cat = state.catalog;+ if (cat.draining) return;+ cat.draining = true;+ try {+ await drainLoop(cat);+ } finally {+ cat.draining = false;+ }+}++/** @param {typeof state.catalog} cat */+async function drainLoop(cat) {+ while (!cat.done && !cat.failed) {+ let merged = false;+ try {+ merged = await loadCatalogPage();+ } catch {+ break;+ }+ if (merged && state.loaded) refreshAfterCatalogPage();}- return out;+}++/** Repaint the counts and the grid around a page that just landed. */+function refreshAfterCatalogPage() {+ renderHeroStats();+ renderChips();+ applyFilters({ preserveShown: true });}function normalizeLibraryClip(clip) {@@ -240,46 +345,46 @@ function normalizeCommunityClip(clip) {async function loadAll() {showState('loading');+ // Retry restarts every source, so the catalog cursor restarts with them.+ state.catalog = {+ offset: 0,+ loaded: 0,+ total: 0,+ byCategory: new Map(),+ facets: null,+ pending: null,+ draining: false,+ done: false,+ failed: false,+ };// The curated manifest and the community feed are both small and bounded, so- // they are awaited together. The full CDN catalog is the unbounded one and is- // streamed in behind them: the first page paints, the rest merge in as they- // land. A user is looking at cards after one page instead of after the whole- // library, which is what keeps first paint flat as seeding grows the catalog.+ // they are awaited together. The catalog is the unbounded one, and exactly+ // one page of it is loaded here: the rest arrives when a reader scrolls to+ // the end of the grid or narrows it. First paint costs the same whether the+ // catalog holds three thousand clips or thirty.const [libRes, comRes] = await Promise.allSettled([fetchLibrary(), fetchCommunity()]);const library = libRes.status === 'fulfilled' ? libRes.value : [];const community = comRes.status === 'fulfilled' ? comRes.value : [];// Community clips lead (fresh, human-authored); the curated library follows;- // the full catalog trails, minus anything the curated set already surfaces.- const curatedNames = new Set(library.map((c) => c.id));+ // the catalog trails, minus anything the curated set already surfaces.+ state.curatedNames = new Set(library.map((c) => c.id));state.all = [...community, ...library];- let painted = false;- const paint = () => {- state.loaded = true;- renderHeroStats();- renderChips();- applyFilters();- painted = true;- };-- let fullFailed = false;- try {- await fetchFullLibrary((clips) => {- const fresh = clips.filter((c) => !curatedNames.has(c.id));- if (!fresh.length) return;- state.all = state.all.concat(fresh);- // The first page is what ends the loading state; later pages refresh a- // grid the user is already reading, so they only re-render what the- // counts and filters depend on.- paint();- });- } catch {- fullFailed = true;- }+ // The counts and the first page are independent requests, so they fly+ // together: the hero line and the chips are exact the moment the grid paints+ // rather than one page behind it.+ const [facetRes, pageRes] = await Promise.allSettled([fetchCatalogFacets(), loadCatalogPage()]);+ const fullFailed = pageRes.status === 'rejected';const results = [libRes, comRes, { status: fullFailed ? 'rejected' : 'fulfilled' }];state.loaded = true;+ if (facetRes.status === 'rejected') {+ // Without facets the totals fall back to what is actually loaded, which+ // is only right once everything is: drain rather than show a count that+ // contradicts the grid.+ drainCatalog();+ }// Nothing to show AND at least one source errored is a failure, not an empty// library: "be the first to publish" would be a lie, and Retry is the action@@ -290,42 +395,95 @@ async function loadAll() {return;}- if (!painted) paint();- else {- renderHeroStats();- renderChips();- applyFilters();- }+ renderHeroStats();+ renderChips();+ applyFilters();// ?clip= deep link → open the modal once data exists.const wanted = new URLSearchParams(location.search).get('clip');- if (wanted) {+ if (wanted) await openDeepLink(wanted);+}++/**+ * Open ?clip=<id>. The clip may live on a catalog page nobody has asked for+ * yet, so a miss loads the rest of the catalog before it gives up: a shared+ * link has to open the clip it names whatever the reader's scroll position is.+ *+ * @param {string} wanted+ */+async function openDeepLink(wanted) {+ for (;;) {const idx = state.filtered.findIndex((c) => c.id === wanted);- if (idx >= 0) openModal(idx);- else {- const item = state.all.find((c) => c.id === wanted);- if (item) {- // Visible under different filters, so clear them for the link.- state.query = '';- state.category = '';- state.filter = '';- els.search.value = '';- syncTypeFilter();- renderChips();- applyFilters();- openModal(state.filtered.findIndex((c) => c.id === wanted));- }+ if (idx >= 0) {+ openModal(idx);+ return;}+ const item = state.all.find((c) => c.id === wanted);+ if (item) {+ // Visible under different filters, so clear them for the link.+ state.query = '';+ state.category = '';+ state.filter = '';+ els.search.value = '';+ syncTypeFilter();+ renderChips();+ applyFilters();+ openModal(state.filtered.findIndex((c) => c.id === wanted));+ return;+ }+ if (state.catalog.done || state.catalog.failed) return;+ try {+ await loadCatalogPage();+ } catch {+ return;+ }+ refreshAfterCatalogPage();}}// ── Hero stats + chips ───────────────────────────────────────────────────────+/**+ * Catalog rows that exist but have not been fetched yet. Counting them keeps+ * every total on the page equal to what the library actually holds, so nothing+ * ticks upward as the reader scrolls.+ */+function catalogPending() {+ const cat = state.catalog;+ if (!cat.total || cat.failed) return 0;+ return Math.max(0, cat.total - cat.loaded);+}++/** Every clip the gallery can show, loaded or not. */+function totalClips() {+ return state.all.length + catalogPending();+}++/**+ * Per-category counts over the whole gallery: what is loaded, plus the catalog+ * rows still unfetched, taken from the facets and netted against the rows of+ * that category already merged so nothing is counted twice.+ *+ * @returns {Map<string, number>}+ */+function categoryCounts() {+ const counts = new Map();+ for (const item of state.all) counts.set(item.category, (counts.get(item.category) || 0) + 1);+ const cat = state.catalog;+ if (cat.facets && !cat.failed) {+ for (const [key, total] of cat.facets) {+ const pending = Math.max(0, total - (cat.byCategory.get(key) || 0));+ if (pending) counts.set(key, (counts.get(key) || 0) + pending);+ }+ }+ return counts;+}+function renderHeroStats() {if (!els.heroStats) return;- const total = state.all.length;+ const total = totalClips();const community = state.all.filter((c) => c.source === 'community').length;- const cats = new Set(state.all.map((c) => c.category)).size;+ const cats = [...categoryCounts().values()].filter(Boolean).length;els.heroStats.textContent = `${total.toLocaleString()} clips · ${cats} categories${community ? ` · ${community} community-authored` : ''}`;@@ -333,8 +491,7 @@ function renderHeroStats() {function renderChips() {if (!els.chips) return;- const counts = new Map();- for (const item of state.all) counts.set(item.category, (counts.get(item.category) || 0) + 1);+ const counts = categoryCounts();els.chips.innerHTML = '';const mk = (key, label, icon, count) => {const btn = document.createElement('button');@@ -347,7 +504,7 @@ function renderChips() {}`;els.chips.appendChild(btn);};- mk('', 'All', '', state.all.length);+ mk('', 'All', '', totalClips());for (const cat of GALLERY_CATEGORIES) {const n = counts.get(cat.key);if (n) mk(cat.key, cat.label, cat.icon, n);@@ -371,7 +528,19 @@ function syncTypeFilter() {// ── Filter + sort + render ───────────────────────────────────────────────────-function applyFilters() {+/**+ * Recompute the filtered set and repaint.+ *+ * `preserveShown` keeps the reader where they are when a catalog page lands+ * under them: the grid is rebuilt, but out to the same number of cards it held+ * a moment ago instead of collapsing back to the first screen.+ *+ * @param {{ preserveShown?: boolean }} [opts]+ */+function applyFilters({ preserveShown = false } = {}) {+ const keep = preserveShown ? state.shown : 0;+ // A user action re-deals the shuffle; a page arriving underneath one does not.+ if (!preserveShown) state.shuffleSeed = (Math.random() * 0xffffffff) >>> 0;const q = state.query.toLowerCase();state.filtered = state.all.filter((item) => {if (state.filter === 'loop' && !item.loop) return false;@@ -387,6 +556,30 @@ function applyFilters() {state.shown = 0;renderCount();renderGrid();+ while (state.shown < keep && state.shown < state.filtered.length) renderGrid();++ // A narrowed view has to be complete to be honest: "63 of 3,119" must mean+ // every clip that matches, not every clip that matches among the pages that+ // happen to be loaded. Sorting is the same argument: every order but the+ // source order ranks the whole gallery. Browsing unnarrowed is the only case+ // that can be served a page at a time, and it is the common one.+ const narrowed = Boolean(state.query || state.category || state.filter) || state.sort !== 'featured';+ if (narrowed && !state.catalog.done && !state.catalog.failed) drainCatalog();+}++/**+ * Stable pseudo-random ordering key for the shuffle sort: the same clip keeps+ * the same place for as long as the seed does.+ *+ * @param {string} id+ */+function shuffleKey(id) {+ let h = state.shuffleSeed >>> 0;+ for (let i = 0; i < id.length; i++) {+ h = Math.imul(h ^ id.charCodeAt(i), 3432918353);+ h = (h << 13) | (h >>> 19);+ }+ return h >>> 0;}function sortFiltered() {@@ -404,15 +597,16 @@ function sortFiltered() {case 'longest':arr.sort((a, b) => (b.duration_ms ?? -1) - (a.duration_ms ?? -1));break;- case 'shuffle': {- // Reshuffled on every filter pass, so changing a chip or the search- // while shuffled deals a fresh hand rather than the same order.- for (let i = arr.length - 1; i > 0; i--) {- const j = Math.floor(Math.random() * (i + 1));- [arr[i], arr[j]] = [arr[j], arr[i]];- }+ case 'shuffle':+ // Ordered by a hash of the clip id against the current seed rather than+ // by swapping in place. The hand is still random, and still re-dealt+ // whenever the reader changes a chip or the search (applyFilters reseeds+ // on a user action), but it no longer depends on the order clips+ // arrived in: a catalog page landing mid-scroll slots its cards into+ // the existing order instead of dealing everything again under the+ // reader's cursor.+ arr.sort((a, b) => shuffleKey(a.id) - shuffleKey(b.id));break;- }default:// 'featured' — the assembled source order (community → curated → catalog).break;@@ -426,13 +620,22 @@ function renderCount() {return;}const n = state.filtered.length;- els.count.textContent = n === state.all.length+ const total = totalClips();+ els.count.textContent = n === total? `${n.toLocaleString()} animations`- : `${n.toLocaleString()} of ${state.all.length.toLocaleString()}`;+ : `${n.toLocaleString()} of ${total.toLocaleString()}`;}function renderGrid() {if (state.filtered.length === 0) {+ // Nothing matches YET is not the same as nothing matches: a narrow filter+ // can exclude every clip loaded so far while the page holding its matches+ // is still unfetched. Keep the loading state and pull the rest in.+ if (!state.catalog.done && !state.catalog.failed) {+ showState('loading');+ drainCatalog();+ return;+ }if (state.all.length === 0) {showState('empty');} else {@@ -463,6 +666,18 @@ function renderGrid() {state.shown = end;els.loadMore.hidden = state.shown >= state.filtered.length;++ // Every loaded clip is on screen and the catalog has more: fetch the next+ // page. This covers both ways a reader reaches the end: scrolling a long+ // grid, and landing on a view whose matches all fit without scrolling at+ // all, which no scroll sentinel would ever fire for.+ if (els.loadMore.hidden && !state.catalog.done && !state.catalog.failed) {+ loadCatalogPage()+ .then((merged) => {+ if (merged) refreshAfterCatalogPage();+ })+ .catch(() => {});+ }}function showMore() {diff --git a/src/avatar-embed.js b/src/avatar-embed.jsindex 83b8f7f55..96422f58f 100644--- a/src/avatar-embed.js+++ b/src/avatar-embed.js@@ -185,9 +185,13 @@ async function main() {} else {// Not in the curated manifest — resolve from the full motion library// and register just the requested def (its url points at the R2 CDN).+ // The ?name= lookup keeps that one embed request small: the whole+ // manifest is over a megabyte and only one entry of it is wanted.(async () => {try {- const res = await fetch('/api/animations/library');+ const res = await fetch(+ `/api/animations/library?name=${encodeURIComponent(startAnim)}`,+ );if (res.ok) {const data = await res.json();const def = (data.clips || []).find((d) => d.name === startAnim);diff --git a/tests/animations-library-endpoint.test.js b/tests/animations-library-endpoint.test.jsindex 0ee3c99e6..95f77677f 100644--- a/tests/animations-library-endpoint.test.js+++ b/tests/animations-library-endpoint.test.js@@ -139,4 +139,105 @@ describe('GET /api/animations/library', () => {expect(body).toEqual({ clips: CLIPS, total: 5, generated_at: null });expect('next_offset' in body).toBe(false);});++ // ── Name lookup (?name=) ────────────────────────────────────────────────+ // A pose deep-link and the embed viewer resolve ONE clip by name and cannot+ // use paging to do it: they do not know which page holds the name. Without+ // this they download the whole manifest per lookup, which is the response+ // that grows worst as the catalog does.++ it('returns only the named clip, with the full catalog total', async () => {+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));+ const res = fakeRes();+ await handler(fakeReq('GET', '/api/animations/library?name=mx-clip-3'), res);+ const body = JSON.parse(res.body);+ expect(body.clips.map((c) => c.name)).toEqual(['mx-clip-3']);+ expect(body.total).toBe(5);+ });++ it('accepts several names, repeated and comma-separated', async () => {+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));+ const res = fakeRes();+ await handler(+ fakeReq('GET', '/api/animations/library?name=mx-clip-0,mx-clip-2&name=mx-clip-4'),+ res,+ );+ const body = JSON.parse(res.body);+ expect(body.clips.map((c) => c.name)).toEqual(['mx-clip-0', 'mx-clip-2', 'mx-clip-4']);+ });++ it('returns an empty list for a name the library does not have', async () => {+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));+ const res = fakeRes();+ await handler(fakeReq('GET', '/api/animations/library?name=mx-nope'), res);+ const body = JSON.parse(res.body);+ expect(body.clips).toEqual([]);+ expect(body.total).toBe(5);+ });++ it('matches names exactly rather than by prefix or substring', async () => {+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));+ const res = fakeRes();+ await handler(fakeReq('GET', '/api/animations/library?name=mx-clip'), res);+ expect(JSON.parse(res.body).clips).toEqual([]);+ });++ it('caps how many names one request can ask for', async () => {+ const many = Array.from({ length: 80 }, (_, i) => ({ ...CLIP, name: `mx-many-${i}` }));+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: many })));+ const res = fakeRes();+ const query = many.map((c) => `name=${c.name}`).join('&');+ await handler(fakeReq('GET', `/api/animations/library?${query}`), res);+ const body = JSON.parse(res.body);+ expect(body.clips.length).toBe(50);+ expect(body.total).toBe(80);+ });++ // ── Facets (?facets=1) ──────────────────────────────────────────────────+ // The gallery needs exact totals to render its hero line and chips. Deriving+ // them client-side means holding the whole catalog in the browser, which is+ // the reason it used to download every page on load.++ it('counts the catalog by category and returns no clips', async () => {+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({+ clips: [+ { ...CLIP, name: 'mx-walking', label: 'Walking' },+ { ...CLIP, name: 'mx-running', label: 'Running' },+ { ...CLIP, name: 'mx-hip-hop-dancing', label: 'Hip Hop Dancing' },+ ],+ })));+ const res = fakeRes();+ await handler(fakeReq('GET', '/api/animations/library?facets=1'), res);+ const body = JSON.parse(res.body);+ expect(body.clips).toBeUndefined();+ expect(body.total).toBe(3);+ const counts = Object.fromEntries(body.categories.map((c) => [c.key, c.count]));+ expect(counts.locomotion).toBe(2);+ expect(counts.dance).toBe(1);+ });++ it('sums the facet counts to the catalog total', async () => {+ const clips = Array.from({ length: 40 }, (_, i) => ({ ...CLIP, name: `mx-clip-${i}`, label: `Clip ${i}` }));+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips })));+ const res = fakeRes();+ await handler(fakeReq('GET', '/api/animations/library?facets=1'), res);+ const body = JSON.parse(res.body);+ expect(body.categories.reduce((n, c) => n + c.count, 0)).toBe(body.total);+ });++ it('reports every category, including the empty ones, so chips stay stable', async () => {+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: [CLIP] })));+ const res = fakeRes();+ await handler(fakeReq('GET', '/api/animations/library?facets=1'), res);+ const body = JSON.parse(res.body);+ expect(body.categories.length).toBeGreaterThan(5);+ expect(body.categories.some((c) => c.count === 0)).toBe(true);+ });++ it('ignores an empty ?name= and falls through to the legacy full response', async () => {+ readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ clips: CLIPS })));+ const res = fakeRes();+ await handler(fakeReq('GET', '/api/animations/library?name='), res);+ expect(JSON.parse(res.body).clips.length).toBe(5);+ });});diff --git a/tests/e2e/animations-gallery.spec.js b/tests/e2e/animations-gallery.spec.jsindex f869e814b..b3ad28e5c 100644--- a/tests/e2e/animations-gallery.spec.js+++ b/tests/e2e/animations-gallery.spec.js@@ -50,9 +50,22 @@ const PIXEL = Buffer.from('base64',);+// The gallery asks for its totals separately (?facets=1) so it never has to hold+// the whole catalogue to count it. Registered after the catalogue route because+// Playwright matches the most recently added route first.+const FACETS = {+ total: LIBRARY.clips.length,+ categories: [+ { key: 'locomotion', count: 2 },+ { key: 'dance', count: 0 },+ ],+ generated_at: null,+};+async function stubCatalogue(page) {await page.route('**/animations/manifest.json', (r) => r.fulfill({ json: CURATED }));await page.route('**/api/animations/library**', (r) => r.fulfill({ json: LIBRARY }));+ await page.route('**/api/animations/library?facets=1', (r) => r.fulfill({ json: FACETS }));await page.route('**/api/animations/clips**', (r) => r.fulfill({ json: { items: [], next_cursor: null } }));await page.route('https://cdn.example.invalid/**/thumbs/**', (r) =>r.fulfill({ contentType: 'image/png', body: PIXEL }),