@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/assetlib/loadImported.js

@@ -0,0 +1,143 @@
+// Three.js side of asset import: turn a saved import recipe (or a freshly
+// resolved download) into a live object/material. The style pass stays the
+// caller's job — the lab and worlds run applyEnvironmentShader (or
+// applyToonShader for characters) over the result, exactly like procedural
+// assets, so imports always render in the active style set.
+
+import * as THREE from 'three';
+import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+
+import { readZipEntries } from './zip.js';
+
+/**
+ * Load a (possibly multi-file) glTF whose companion files live at arbitrary
+ * CDN URLs. `resources` maps the glTF's internal relative URIs to real URLs
+ * (Poly Haven serves textures/bin outside the glTF's own directory); a
+ * LoadingManager URL modifier rewrites each request by suffix match, which
+ * also covers URL-encoded variants.
+ */
+export async function loadImportedModel({ url, resources = {}, dracoDecoderPath = '/draco/gltf/' }) {
+  const manager = new THREE.LoadingManager();
+  const byPath = Object.entries(resources);
+  manager.setURLModifier((requested) => {
+    for (const [relativePath, remoteUrl] of byPath) {
+      if (requested.endsWith(relativePath) || requested.endsWith(encodeURI(relativePath))) {
+        return remoteUrl;
+      }
+    }
+    return requested;
+  });
+  const loader = new GLTFLoader(manager);
+  const dracoLoader = new DRACOLoader(manager);
+  dracoLoader.setDecoderPath(dracoDecoderPath);
+  loader.setDRACOLoader(dracoLoader);
+  let gltf;
+  try {
+    gltf = await loader.loadAsync(url);
+  } finally {
+    dracoLoader.dispose();
+  }
+  const object = gltf.scene ?? gltf.scenes?.[0];
+  if (!object) throw new Error('loadImportedModel: glTF contained no scene.');
+  object.traverse((child) => {
+    if (child.isMesh) {
+      child.castShadow = true;
+      child.receiveShadow = true;
+    }
+  });
+  return object;
+}
+
+/**
+ * PBR texture-set maps → a tiling MeshStandardMaterial. Prefers the packed
+ * `arm` map (occlusion-R / roughness-G / metalness-B — the glTF ORM layout
+ * three samples those slots from); falls back to individual AO/Rough maps.
+ */
+export async function loadImportedTextureMaterial({ maps }, { repeat = 1 } = {}) {
+  const loader = new THREE.TextureLoader();
+  loader.setCrossOrigin('anonymous');
+  const load = async (slot, { srgb = false } = {}) => {
+    if (!maps?.[slot]?.url) return null;
+    const texture = await loader.loadAsync(maps[slot].url);
+    texture.colorSpace = srgb ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+    texture.wrapS = THREE.RepeatWrapping;
+    texture.wrapT = THREE.RepeatWrapping;
+    texture.repeat.set(repeat, repeat);
+    return texture;
+  };
+  const [diffuse, normal, arm, roughness, ao] = await Promise.all([
+    load('diffuse', { srgb: true }),
+    load('normal'),
+    load('arm'),
+    maps?.arm ? null : load('roughness'),
+    maps?.arm ? null : load('ao'),
+  ]);
+  if (!diffuse) throw new Error('loadImportedTextureMaterial: texture set has no diffuse map.');
+  const material = new THREE.MeshStandardMaterial({
+    aoMap: arm ?? ao ?? null,
+    map: diffuse,
+    metalness: arm ? 1 : 0,
+    metalnessMap: arm ?? null,
+    normalMap: normal ?? null,
+    roughness: 1,
+    roughnessMap: arm ?? roughness ?? null,
+  });
+  return material;
+}
+
+// ambientCG archive entry names → material slots (Bricks097_1K-JPG_Color.jpg …)
+const AMBIENTCG_MAP_PATTERNS = Object.freeze({
+  ao: /_AmbientOcclusion\.(jpg|png)$/i,
+  diffuse: /_Color\.(jpg|png)$/i,
+  displacement: /_Displacement\.(jpg|png)$/i,
+  normal: /_NormalGL\.(jpg|png)$/i,
+  roughness: /_Roughness\.(jpg|png)$/i,
+});
+
+/**
+ * An ambientCG ZIP download → tiling MeshStandardMaterial: fetch the archive
+ * (through the backend/dev proxy in browsers — pass rewriteUrl), extract the
+ * PBR maps in memory, and feed them to loadImportedTextureMaterial as
+ * object-URLs (revoked once the textures are on the GPU).
+ */
+export async function loadAmbientcgTextureMaterial({ url }, { repeat = 1, rewriteUrl = (value) => value } = {}) {
+  const response = await fetch(rewriteUrl(url));
+  if (!response.ok) throw new Error(`loadAmbientcgTextureMaterial: ${response.status} for ${url}`);
+  const entries = await readZipEntries(await response.arrayBuffer());
+  const maps = {};
+  const objectUrls = [];
+  for (const [slot, pattern] of Object.entries(AMBIENTCG_MAP_PATTERNS)) {
+    const entry = entries.find((candidate) => pattern.test(candidate.name));
+    if (!entry) continue;
+    const type = entry.name.toLowerCase().endsWith('.png') ? 'image/png' : 'image/jpeg';
+    const objectUrl = URL.createObjectURL(new Blob([entry.data], { type }));
+    objectUrls.push(objectUrl);
+    maps[slot] = { url: objectUrl };
+  }
+  try {
+    return await loadImportedTextureMaterial({ maps }, { repeat });
+  } finally {
+    for (const objectUrl of objectUrls) URL.revokeObjectURL(objectUrl);
+  }
+}
+
+/**
+ * The spawn snippet entry point: a saved import recipe → live content.
+ *   model   → { kind: 'model', object3D }
+ *   texture → { kind: 'texture', material }
+ * Recipes store portable origin urls; browsers pass `rewriteUrl`
+ * (e.g. rewriteAmbientcgDownloadUrl) to route zip fetches through the proxy.
+ */
+export async function loadImportedAsset(recipe, { repeat = 1, rewriteUrl = (value) => value } = {}) {
+  if (recipe?.kind === 'model' && recipe.download) {
+    return { kind: 'model', object3D: await loadImportedModel(recipe.download) };
+  }
+  if (recipe?.kind === 'texture' && recipe.textureSet) {
+    return { kind: 'texture', material: await loadImportedTextureMaterial(recipe.textureSet, { repeat }) };
+  }
+  if (recipe?.kind === 'texture' && recipe.download?.url) {
+    return { kind: 'texture', material: await loadAmbientcgTextureMaterial(recipe.download, { repeat, rewriteUrl }) };
+  }
+  throw new Error(`loadImportedAsset: unsupported recipe kind "${recipe?.kind}".`);
+}

package/src/assetlib/opensource3d.js

@@ -0,0 +1,113 @@
+// CC0 asset source: Open Source 3D Assets (opensource3dassets.com) — a
+// keyless curated registry (github.com/ToxSam/open-source-3D-assets) built
+// FOR asset browsers: static JSON with direct GLB urls, thumbnails, tags,
+// and per-collection license metadata. ~991 models today, all from the
+// Polygonal Mind CC0 collections (park/museum/sci-fi/vaporwave/medieval
+// environment sets + creatures). The registry metadata itself is CC0 too.
+//
+// Everything is served from raw.githubusercontent.com (CORS `*`), so this
+// client runs in the browser with no proxy and in Node unchanged.
+//
+// LICENSING: collections declare their license in projects.json; today all
+// are CC0 but the registry accepts CC-BY submissions, so we filter to
+// license === 'CC0' exactly — never assume.
+
+export const OS3D_DATA_URL = 'https://raw.githubusercontent.com/ToxSam/open-source-3d-assets/main/data';
+
+export const OS3D_SOURCE = Object.freeze({
+  sourceLabel: 'Open Source 3D Assets',
+  sourceUrl: 'https://opensource3dassets.com',
+});
+
+/**
+ * Raw projects.json → CC0-only collection descriptors:
+ *   { id, name, creator, description, license, assetDataFile, pageUrl }
+ */
+export function normalizeOs3dProjects(raw) {
+  const projects = [];
+  for (const project of raw ?? []) {
+    if (!project?.id || !project.asset_data_file) continue;
+    if (project.is_public === false) continue;
+    if (project.license !== 'CC0') continue; // exact — future collections may be CC-BY
+    projects.push({
+      assetDataFile: project.asset_data_file,
+      creator: project.creator_id ?? null,
+      description: project.description ?? '',
+      id: project.id,
+      license: project.license,
+      name: project.name ?? project.id,
+      pageUrl: project.github_url ?? OS3D_SOURCE.sourceUrl,
+    });
+  }
+  return projects;
+}
+
+/** metadata.attributes trait list → lowercase tag values. */
+function attributeValues(asset) {
+  return (asset?.metadata?.attributes ?? [])
+    .map((attribute) => String(attribute?.value ?? '').toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * One collection's assets/*.json + its project descriptor → normalized refs
+ * (kind is always 'model'; download embedded like Poly Pizza's). Drafts,
+ * non-public rows, and non-glTF formats are dropped.
+ */
+export function normalizeOs3dAssets(raw, project) {
+  const refs = [];
+  for (const asset of raw ?? []) {
+    if (!asset?.id || !asset.model_file_url) continue;
+    if (asset.is_public === false || asset.is_draft === true) continue;
+    const format = String(asset.format ?? 'GLB').toLowerCase();
+    if (format !== 'glb' && format !== 'gltf') continue;
+    refs.push({
+      attribution: { license: project.license, ...OS3D_SOURCE },
+      authors: project.creator ? [project.creator] : [],
+      categories: [String(project.name ?? project.id).toLowerCase()],
+      download: {
+        format,
+        resources: {},
+        sizeBytes: asset.metadata?.file_size ?? 0,
+        url: asset.model_file_url,
+      },
+      id: asset.id,
+      kind: 'model',
+      name: asset.name ?? asset.id,
+      pageUrl: project.pageUrl,
+      source: 'opensource3d',
+      tags: attributeValues(asset),
+      thumbnailUrl: asset.thumbnail_url ?? null,
+    });
+  }
+  return refs;
+}
+
+let indexCache = null;
+
+/**
+ * Full CC0 index (projects.json + every CC0 collection's asset file, fetched
+ * in parallel), normalized and cached per session. A collection that fails
+ * to fetch is skipped rather than blanking the browser; the projects.json
+ * fetch itself failing throws.
+ */
+export function fetchOs3dIndex({ dataUrl = OS3D_DATA_URL, fetchImpl = fetch } = {}) {
+  if (!indexCache) {
+    indexCache = (async () => {
+      const response = await fetchImpl(`${dataUrl}/projects.json`);
+      if (!response.ok) throw new Error(`Open Source 3D Assets projects.json: ${response.status}`);
+      const projects = normalizeOs3dProjects(await response.json());
+      const settled = await Promise.allSettled(projects.map(async (project) => {
+        const assetsResponse = await fetchImpl(`${dataUrl}/${project.assetDataFile}`);
+        if (!assetsResponse.ok) throw new Error(`Open Source 3D Assets ${project.assetDataFile}: ${assetsResponse.status}`);
+        return normalizeOs3dAssets(await assetsResponse.json(), project);
+      }));
+      return settled
+        .flatMap((result) => (result.status === 'fulfilled' ? result.value : []))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    })();
+    // a failed fetch must not poison the session cache
+    indexCache.catch(() => { indexCache = null; });
+  }
+  return indexCache;
+}

package/src/assetlib/polyhaven.js

@@ -0,0 +1,182 @@
+// CC0 asset source: Poly Haven (polyhaven.com) — photoscanned models, PBR
+// texture sets, and HDRIs, all CC0. The current API page says the live API is
+// free for any use and requires visible credit plus a unique application UA:
+//   https://polyhaven.com/our-api
+// Browsers cannot override User-Agent, so browser calls use the identifying
+// /api/polyhaven dev/host proxy. Node calls add ASSETLIB_USER_AGENT here.
+//
+// Donation-vault ("early access") assets never appear in the public /assets
+// dump today; the date_published guard below keeps them out if that changes.
+
+import { ASSETLIB_USER_AGENT, ASSET_REF_KINDS, pickResolution } from './assetRef.js';
+
+export const POLYHAVEN_API_URL = 'https://api.polyhaven.com';
+export const POLYHAVEN_BROWSER_API_URL = '/api/polyhaven';
+export const POLYHAVEN_THUMB_URL = 'https://cdn.polyhaven.com/asset_img/thumbs';
+
+export const POLYHAVEN_ATTRIBUTION = Object.freeze({
+  license: 'CC0',
+  sourceLabel: 'Poly Haven',
+  sourceUrl: 'https://polyhaven.com',
+});
+
+/** API `type` param values, in the order the lab offers them. */
+export const POLYHAVEN_ASSET_TYPES = Object.freeze(['models', 'textures', 'hdris']);
+
+const KIND_BY_TYPE = { hdris: 'hdri', models: 'model', textures: 'texture' };
+
+// files-doc keys for texture-set maps → the material slots we care about.
+// `arm` is a packed occlusion(R)/roughness(G)/metalness(B) map — exactly the
+// glTF ORM layout three.js samples aoMap/roughnessMap/metalnessMap from.
+const TEXTURE_MAP_KEYS = Object.freeze({
+  ao: 'AO',
+  arm: 'arm',
+  diffuse: 'Diffuse',
+  displacement: 'Displacement',
+  normal: 'nor_gl',
+  roughness: 'Rough',
+});
+
+export function polyhavenThumbnailUrl(id, { width = 256, height = 256 } = {}) {
+  return `${POLYHAVEN_THUMB_URL}/${encodeURIComponent(id)}.png?width=${width}&height=${height}`;
+}
+
+export function polyhavenAssetPageUrl(id) {
+  return `https://polyhaven.com/a/${encodeURIComponent(id)}`;
+}
+
+/**
+ * Raw `GET /assets?type=…` payload (`{ id: info }`) → sorted array of
+ * normalized asset refs. `now` is epoch seconds; assets published in the
+ * future (donation vault) are dropped.
+ */
+export function normalizePolyhavenIndex(raw, { type = 'models', now = Date.now() / 1000 } = {}) {
+  const kind = KIND_BY_TYPE[type];
+  if (!kind || !ASSET_REF_KINDS.includes(kind)) {
+    throw new Error(`normalizePolyhavenIndex: unknown type "${type}".`);
+  }
+  const refs = [];
+  for (const [id, info] of Object.entries(raw ?? {})) {
+    if (!info || typeof info !== 'object') continue;
+    if ((info.date_published ?? 0) > now) continue;
+    refs.push({
+      attribution: POLYHAVEN_ATTRIBUTION,
+      authors: Object.keys(info.authors ?? {}),
+      categories: (info.categories ?? []).map((value) => String(value).toLowerCase()),
+      datePublished: info.date_published ?? 0,
+      dimensions: info.dimensions ?? null,
+      id,
+      kind,
+      maxResolution: info.max_resolution ?? null,
+      name: info.name ?? id,
+      pageUrl: polyhavenAssetPageUrl(id),
+      polycount: info.polycount ?? null,
+      source: 'polyhaven',
+      tags: (info.tags ?? []).map((value) => String(value).toLowerCase()),
+      thumbnailUrl: info.thumbnail_url ?? polyhavenThumbnailUrl(id),
+    });
+  }
+  return refs.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const indexCache = new Map();
+
+function defaultPolyhavenApiUrl() {
+  return typeof window === 'undefined' ? POLYHAVEN_API_URL : POLYHAVEN_BROWSER_API_URL;
+}
+
+function polyhavenRequestOptions(headers) {
+  const merged = new Headers(headers);
+  if (typeof window === 'undefined' && !merged.has('user-agent')) {
+    merged.set('user-agent', ASSETLIB_USER_AGENT);
+  }
+  return { headers: merged };
+}
+
+/** Full asset index for one type, normalized; cached per type per session.
+ * Browser hosts must implement `/api/polyhaven` as an identifying proxy;
+ * Node defaults to the upstream API and supplies ASSETLIB_USER_AGENT. */
+export function fetchPolyhavenIndex({
+  type = 'models',
+  fetchImpl = fetch,
+  headers = {},
+  apiUrl = defaultPolyhavenApiUrl(),
+  now = Date.now() / 1000,
+} = {}) {
+  const cacheKey = `${apiUrl}\n${type}`;
+  if (!indexCache.has(cacheKey)) {
+    const promise = (async () => {
+      const response = await fetchImpl(
+        `${apiUrl.replace(/\/$/, '')}/assets?type=${type}`,
+        polyhavenRequestOptions(headers),
+      );
+      if (!response.ok) throw new Error(`Poly Haven /assets?type=${type}: ${response.status}`);
+      return normalizePolyhavenIndex(await response.json(), { now, type });
+    })();
+    // a failed fetch must not poison the session cache
+    promise.catch(() => indexCache.delete(cacheKey));
+    indexCache.set(cacheKey, promise);
+  }
+  return indexCache.get(cacheKey);
+}
+
+/** Raw `GET /files/{id}` document, using the same browser/Node routing. */
+export async function fetchPolyhavenFiles(id, {
+  fetchImpl = fetch,
+  headers = {},
+  apiUrl = defaultPolyhavenApiUrl(),
+} = {}) {
+  const response = await fetchImpl(
+    `${apiUrl.replace(/\/$/, '')}/files/${encodeURIComponent(id)}`,
+    polyhavenRequestOptions(headers),
+  );
+  if (!response.ok) throw new Error(`Poly Haven /files/${id}: ${response.status}`);
+  return response.json();
+}
+
+/**
+ * files doc → one loadable glTF download:
+ *   { format: 'gltf', resolution, url, sizeBytes,
+ *     resources: { 'textures/…_diff_1k.jpg': 'https://…', '….bin': '…' } }
+ * `resources` maps the glTF's internal relative URIs to their real CDN URLs
+ * (Poly Haven hosts them outside the glTF's directory) — feed it to
+ * loadImportedModel, which resolves them via a LoadingManager URL modifier.
+ */
+export function resolvePolyhavenModelDownload(filesDoc, { resolution = '1k' } = {}) {
+  const byResolution = filesDoc?.gltf;
+  const picked = pickResolution(byResolution, resolution);
+  if (!picked) throw new Error('resolvePolyhavenModelDownload: no glTF files in document.');
+  const entry = byResolution[picked]?.gltf;
+  if (!entry?.url) throw new Error(`resolvePolyhavenModelDownload: no glTF url at ${picked}.`);
+  const resources = {};
+  let sizeBytes = entry.size ?? 0;
+  for (const [relativePath, file] of Object.entries(entry.include ?? {})) {
+    resources[relativePath] = file.url;
+    sizeBytes += file.size ?? 0;
+  }
+  return { format: 'gltf', resolution: picked, resources, sizeBytes, url: entry.url };
+}
+
+/**
+ * files doc → PBR map urls for a texture set:
+ *   { resolution, format, maps: { diffuse: {url,sizeBytes}, normal, arm, … } }
+ * Prefers `arm` (packed ORM) plus diffuse/normal; individual AO/Rough are
+ * still included when present so callers can choose.
+ */
+export function resolvePolyhavenTextureDownload(filesDoc, { resolution = '1k', format = 'jpg' } = {}) {
+  const maps = {};
+  let picked = null;
+  for (const [slot, key] of Object.entries(TEXTURE_MAP_KEYS)) {
+    const byResolution = filesDoc?.[key];
+    if (!byResolution) continue;
+    const mapResolution = pickResolution(byResolution, resolution);
+    if (!mapResolution) continue;
+    const byFormat = byResolution[mapResolution];
+    const file = byFormat?.[format] ?? byFormat?.jpg ?? byFormat?.png;
+    if (!file?.url) continue;
+    picked = picked ?? mapResolution;
+    maps[slot] = { sizeBytes: file.size ?? 0, url: file.url };
+  }
+  if (!maps.diffuse) throw new Error('resolvePolyhavenTextureDownload: no diffuse map found.');
+  return { format, maps, resolution: picked };
+}

package/src/assetlib/polypizza.js

@@ -0,0 +1,115 @@
+// Asset source: Poly Pizza (poly.pizza) — low-poly stylized models (the
+// Quaternius catalog, Google Poly CC0/CC-BY survivors, and more). The best
+// STYLE fit for a toon renderer of all our sources: authored low-poly takes
+// cel shading and outlines far better than photoscans.
+//
+// BYO API KEY (free: https://poly.pizza/settings/api; their terms: hobby use
+// free, commercial pay-as-you-go — a commercial toonlab-pro deployment needs
+// its own arrangement). The API sends no CORS headers AND wants the key in a
+// header, so browsers go through a backend route that injects it server-side
+// (Vite dev proxy: /api/polypizza with TOONLAB_POLYPIZZA_KEY from env; the
+// key never reaches the client). Node callers pass `apiKey` directly.
+//
+// LICENSING: unlike Poly Haven/ambientCG this corpus is NOT all-CC0 — models
+// carry Licence 'CC0' or 'CC-BY' (ready-made credit string in Attribution).
+// Callers default to CC0-only; CC-BY may be surfaced with its license badge
+// and attribution shown, but must never be bundled/redistributed by us.
+
+export const POLYPIZZA_API_URL = 'https://api.poly.pizza/v1.1';
+export const POLYPIZZA_STATIC_URL = 'https://static.poly.pizza';
+
+/** Backend/dev-proxy routes the browser uses instead of poly.pizza hosts. */
+export const POLYPIZZA_PROXY_API = '/api/polypizza';
+export const POLYPIZZA_PROXY_STATIC = '/api/polypizza-static';
+
+export const POLYPIZZA_SOURCE = Object.freeze({
+  sourceLabel: 'Poly Pizza',
+  sourceUrl: 'https://poly.pizza',
+});
+
+/** Absolute static.poly.pizza url → same request through the proxy route. */
+export function rewritePolyPizzaDownloadUrl(url, base = POLYPIZZA_PROXY_STATIC) {
+  return String(url ?? '').replace(POLYPIZZA_STATIC_URL, base);
+}
+
+function normalizeLicence(licence) {
+  const value = String(licence ?? '').toUpperCase().replace(/\s+/g, '-');
+  return value.includes('CC0') ? 'CC0' : value || 'unknown';
+}
+
+/** One API model object → normalized ref (kind is always 'model'). */
+export function normalizePolyPizzaModel(model) {
+  if (!model?.ID) return null;
+  return {
+    animated: Boolean(model.Animated),
+    attribution: {
+      license: normalizeLicence(model.Licence),
+      // Poly Pizza ships the exact credit line CC-BY requires — keep it.
+      text: model.Attribution ?? null,
+      ...POLYPIZZA_SOURCE,
+    },
+    authors: model.Creator?.Username ? [model.Creator.Username] : [],
+    categories: model.Category ? [String(model.Category).toLowerCase()] : [],
+    download: { format: 'glb', url: model.Download },
+    id: model.ID,
+    kind: 'model',
+    name: model.Title ?? model.ID,
+    pageUrl: `https://poly.pizza/m/${encodeURIComponent(model.ID)}`,
+    polycount: model['Tri Count'] ?? null,
+    source: 'polypizza',
+    tags: (model.Tags ?? []).map((value) => String(value).toLowerCase()),
+    thumbnailUrl: model.Thumbnail ?? null,
+  };
+}
+
+function keyHeaders(apiKey) {
+  return apiKey ? { 'x-auth-token': apiKey } : {};
+}
+
+async function requireOk(response, what) {
+  if (response.status === 401) {
+    throw new Error(`Poly Pizza ${what}: 401 — API key missing or invalid. Get a free key at poly.pizza/settings/api, then paste it in the sidebar (or set TOONLAB_POLYPIZZA_KEY for the dev server / MCP).`);
+  }
+  if (!response.ok) throw new Error(`Poly Pizza ${what}: ${response.status}`);
+  return response;
+}
+
+/**
+ * Keyword search. The endpoint requires a search term; callers with an empty
+ * query should supply a starter word. `cc0Only` (default true) drops CC-BY
+ * results — flip it off only where the license badge + attribution show.
+ */
+export async function searchPolyPizza({
+  query,
+  limit = 32,
+  page = 0,
+  cc0Only = true,
+  apiUrl = POLYPIZZA_API_URL,
+  apiKey = null,
+  fetchImpl = fetch,
+} = {}) {
+  const keyword = String(query ?? '').trim() || 'low poly';
+  const params = new URLSearchParams({ Limit: String(limit), Page: String(page) });
+  const response = await fetchImpl(
+    `${apiUrl}/search/${encodeURIComponent(keyword)}?${params}`,
+    { headers: keyHeaders(apiKey) },
+  );
+  await requireOk(response, 'search');
+  const payload = await response.json();
+  const refs = (payload?.results ?? []).map(normalizePolyPizzaModel).filter(Boolean);
+  return cc0Only ? refs.filter((ref) => ref.attribution.license === 'CC0') : refs;
+}
+
+/** Exact lookup by model id (headless boot, MCP get/import). */
+export async function fetchPolyPizzaModel(id, {
+  apiUrl = POLYPIZZA_API_URL,
+  apiKey = null,
+  fetchImpl = fetch,
+} = {}) {
+  const response = await fetchImpl(
+    `${apiUrl}/model/${encodeURIComponent(id)}`,
+    { headers: keyHeaders(apiKey) },
+  );
+  await requireOk(response, `model/${id}`);
+  return normalizePolyPizzaModel(await response.json());
+}