Skip to content

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.

perf(animations): serve one clip, and exact counts, without the whole manifest

nirholas3bf8d1c83601
diff --git a/api/animations/library.js b/api/animations/library.js
index 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.md
index 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 and
58,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.md
index 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**
```json
diff --git a/src/animation-library.js b/src/animation-library.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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 }),