@vgai/editor 0.2.0

package/src/editor-api.ts

@@ -0,0 +1,700 @@
+/**
+ * Editor server SDK.
+ *
+ * All frontend code should use this module instead of calling fetch()/EventSource
+ * with raw endpoint URLs.
+ *
+ * The project's `public/` file operations (`listAssets`, `saveFile`) are routed
+ * through the backend-agnostic `StorageBackend` (see ./storage): locally that is
+ * `HttpStorage` over the same `/__editor/*` routes (behavior unchanged); in a
+ * server-less browser build it is `OpfsStorage`/`FsaStorage`, so the editor's
+ * file I/O works with no Node server. The remaining endpoints are NOT `public/`
+ * file ops, and split three ways in browser mode (Phase A cleanup — see
+ * `docs/FRONTEND-FIRST-ROADMAP.md` Phase A's "retire the remaining Node-only
+ * `/__editor/*` ops" bullet):
+ *   - `loadEditorState`/`saveEditorState` route through `getStorageBackend()`
+ *     directly (`.vgai/editor-state.json`, project-root-relative — same
+ *     namespace `authoring/world-overlay.ts` already established), because
+ *     remembering view/tool state is genuine authoring-loop parity.
+ *   - Background, non-actionable reads with no independent browser-mode value
+ *     degrade to an honest empty result with NO fetch attempted at all:
+ *     `listRecentProjects`/`listExamples` (browser mode has no server-tracked
+ *     project history), `saveThumbnail` (its only consumer is the Node-only
+ *     recent-projects list), `startLogSession`/`endLogSession`/
+ *     `flushLogEntries` (agent/CLI-tooling introspection — bucketed with the
+ *     CLI control channel, which is already fully dropped in browser mode by
+ *     `command-listener.ts`), and the read-only asset-library lookups.
+ *   - User-triggered actions with no browser equivalent throw a clear, honest
+ *     `Error` instead of doing a doomed fetch: `createProject`, `browseFolder`,
+ *     `openProjectOnServer`, `revealInFinder`, `startExport`,
+ *     `downloadOnlineAsset` — the browser-mode UI either hides the affordance
+ *     (Build/Library tabs, "Show in Finder") or catches the throw into an
+ *     existing error banner (`ProjectScreen.tsx`).
+ */
+
+import { resolveUrl } from '@engine/loader';
+import { getEditorMode } from './editor-mode';
+import { getStorageBackend } from './storage';
+
+const BASE = '/__editor';
+
+/** Browser mode has no Node dev server — every `/__editor/*` op below either
+ *  routes through `getStorageBackend()` or degrades explicitly; this helper
+ *  just names the check so each function reads the same way. */
+function isBrowserMode(): boolean {
+  return getEditorMode() === 'browser';
+}
+
+/**
+ * Read a project text file, storage-backend first, then static HTTP fallback.
+ *
+ * A prefab/asset the user just saved lives in the storage backend (OPFS in the
+ * browser build); a prefab shipped with the project is a static file served over
+ * HTTP. Reading storage-first makes both work — critically, it lets a
+ * just-created prefab be resolved/unpacked in the server-less browser editor,
+ * where a plain `fetch()` of the OPFS path would 404. Returns null if neither has it.
+ */
+export async function readProjectTextFile(path: string): Promise<string | null> {
+  const key = path.replace(/^\//, '');
+  try {
+    const be = getStorageBackend();
+    if (await be.exists(key)) return await be.read(key);
+  } catch {
+    /* fall through to HTTP */
+  }
+  try {
+    const res = await fetch(resolveUrl(path));
+    if (res.ok) return await res.text();
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+export interface AssetEntry {
+  name: string;
+  type: 'file' | 'directory';
+  size: number;
+}
+
+/** List files and folders in a directory under public/. */
+export async function listAssets(root: string, dir: string): Promise<AssetEntry[]> {
+  void root; // backend is project-rooted; `root` kept for signature stability
+  try {
+    const entries = await getStorageBackend().list(dir);
+    return entries.map((e) => ({
+      name: e.name,
+      type: e.type === 'dir' ? 'directory' : 'file',
+      size: e.size ?? 0,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/** Save a file to public/. Returns true on success. */
+export async function saveFile(
+  path: string,
+  content: string,
+  encoding?: 'base64',
+): Promise<boolean> {
+  try {
+    // base64 content → raw bytes; the backend re-encodes per its transport.
+    const data: string | Uint8Array =
+      encoding === 'base64' ? Uint8Array.from(atob(content), (c) => c.charCodeAt(0)) : content;
+    await getStorageBackend().write(path, data);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Start a build/export. Returns the raw Response for SSE streaming. */
+export async function startExport(target: string, signal?: AbortSignal | null): Promise<Response> {
+  if (isBrowserMode()) {
+    throw new Error(
+      'Export is not available in browser mode — building a game requires the Node dev server ' +
+        '(`npm run dev`) or CLI (`vgai edit`).',
+    );
+  }
+  const init: RequestInit = {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ target }),
+  };
+  if (signal) init.signal = signal;
+  return fetch(`${BASE}/export`, init);
+}
+
+/** Build a download URL for a build artifact. */
+export function getDownloadUrl(file: string): string {
+  return `${BASE}/download?file=${encodeURIComponent(file)}`;
+}
+
+/**
+ * The subset of `EventSource`'s surface every caller here actually uses.
+ * `close()` on the object `connectEvents()` returns detaches only the CALLING
+ * consumer (see below) — it is deliberately not a real `EventSource`, so
+ * nothing can reach in and close the shared socket out from under a sibling
+ * consumer.
+ */
+export interface EditorEventSource {
+  addEventListener(type: string, listener: (event: MessageEvent) => void): void;
+  removeEventListener(type: string, listener: (event: MessageEvent) => void): void;
+  close(): void;
+}
+
+let sharedSource: EventSource | null = null;
+let sharedRefCount = 0;
+
+/**
+ * Connect to the editor's SSE event stream.
+ *
+ * SHARED and ref-counted across every caller (W6a field note,
+ * docs/DATA-TOOLS-DESIGN.md §7): this used to hand back a brand-new
+ * `EventSource` per call, and by the time W6a added its 2 new push
+ * channels (tool/data-file add+unlink) this editor had **6** independent
+ * long-lived consumers (asset-moved + scene-changed in
+ * `DefaultEditorLayout`, the CLI command channel, console server-logs, and
+ * the 2 new ones) — landing EXACTLY on Chromium's hard 6-connections-
+ * per-origin cap for HTTP/1.1 and permanently starving every OTHER fetch
+ * to this origin (module chunks, `/__editor/tool-files`, everything) once
+ * all 6 slots were claimed forever. Verified live: with 6 real
+ * `EventSource`s already open, a 7th never left `readyState 0`
+ * (CONNECTING) — nor did ordinary `fetch()` calls issued after it.
+ *
+ * The fix is ONE real connection, reference-counted: `addEventListener`/
+ * `removeEventListener` proxy straight through to it, and `close()` only
+ * removes THIS caller's own listeners and decrements the count — the
+ * underlying socket closes for real only once the last caller releases it.
+ * However many editor features want server push, the origin only ever
+ * pays for one connection.
+ */
+export function connectEvents(): EditorEventSource {
+  if (!sharedSource) {
+    sharedSource = new EventSource(`${BASE}/events`);
+  }
+  const real = sharedSource;
+  sharedRefCount++;
+
+  const ownListeners: Array<{ type: string; listener: EventListener }> = [];
+  let released = false;
+
+  return {
+    addEventListener(type, listener) {
+      const wrapped = listener as EventListener;
+      real.addEventListener(type, wrapped);
+      ownListeners.push({ type, listener: wrapped });
+    },
+    removeEventListener(type, listener) {
+      const wrapped = listener as EventListener;
+      real.removeEventListener(type, wrapped);
+      const idx = ownListeners.findIndex((l) => l.type === type && l.listener === wrapped);
+      if (idx >= 0) ownListeners.splice(idx, 1);
+    },
+    close() {
+      if (released) return;
+      released = true;
+      for (const { type, listener } of ownListeners) real.removeEventListener(type, listener);
+      ownListeners.length = 0;
+      sharedRefCount--;
+      if (sharedRefCount <= 0) {
+        real.close();
+        if (sharedSource === real) sharedSource = null;
+        sharedRefCount = 0;
+      }
+    },
+  };
+}
+
+/** Report the current editor state to the server (called by command-listener). */
+export async function reportEditorState(state: Record<string, unknown>): Promise<void> {
+  try {
+    await fetch(`${BASE}/state`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(state),
+    });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Report a command result back to the server so the SDK/CLI gets the response.
+ *  `data` carries an optional payload for commands that answer with data
+ *  (e.g. `capture-viewport`'s base64 PNG) — passed through verbatim to the
+ *  SDK/CLI caller's response body. */
+export async function reportCommandResult(
+  requestId: string,
+  ok: boolean,
+  error?: string,
+  data?: Record<string, unknown>,
+): Promise<void> {
+  try {
+    await fetch(`${BASE}/command-result`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ _requestId: requestId, ok, error, data }),
+    });
+  } catch {
+    /* best-effort */
+  }
+}
+
+export interface RecentProject {
+  name: string;
+  path: string;
+  lastOpened: string;
+  thumbnail?: string;
+}
+
+/** List recently opened projects. Always empty in browser mode — there is no
+ *  Node-tracked project history there (A1's persisted-root mechanism
+ *  remembers exactly one folder, not a list); an empty result is the honest
+ *  state, not a degraded one. */
+export async function listRecentProjects(): Promise<RecentProject[]> {
+  if (isBrowserMode()) return [];
+  try {
+    const res = await fetch(`${BASE}/recent-projects`);
+    if (!res.ok) return [];
+    const data = (await res.json()) as { projects: RecentProject[] };
+    return data.projects;
+  } catch {
+    return [];
+  }
+}
+
+export interface ExampleInfo {
+  id: string;
+  name: string;
+}
+
+/** List `examples/<id>/` projects available to scaffold from (Track E3, §1.F).
+ *  Always empty in browser mode — this is the on-disk scaffold-a-new-project
+ *  flow; bundled examples are reached in browser mode via the separate
+ *  `?project=<id>` hosted deep-link (`hosted-example.ts`) instead. */
+export async function listExamples(): Promise<ExampleInfo[]> {
+  if (isBrowserMode()) return [];
+  try {
+    const res = await fetch(`${BASE}/examples`);
+    if (!res.ok) return [];
+    const data = (await res.json()) as { examples: ExampleInfo[] };
+    return data.examples;
+  } catch {
+    return [];
+  }
+}
+
+/** Create a new project from a template. */
+export async function createProject(
+  name: string,
+  location: string,
+  template: 'starter' | 'empty' | 'example',
+  exampleId?: string,
+): Promise<{ ok: boolean; path?: string; config?: { name: string }; error?: string }> {
+  if (isBrowserMode()) {
+    throw new Error(
+      'Creating a project on disk from a template needs the Node dev server. In browser mode, ' +
+        'use "Open Folder…" to author a real on-disk project via File System Access, or just start ' +
+        'editing — a Starter project is already seeded in your browser storage.',
+    );
+  }
+  const res = await fetch(`${BASE}/create-project`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name, location, template, ...(exampleId ? { exampleId } : {}) }),
+  });
+  return (await res.json()) as {
+    ok: boolean;
+    path?: string;
+    config?: { name: string };
+    error?: string;
+  };
+}
+
+/** Open a native folder picker dialog. Returns the selected path, or null if cancelled. */
+export async function browseFolder(title?: string): Promise<string | null> {
+  if (isBrowserMode()) {
+    throw new Error(
+      'The native folder picker needs the Node dev server. In browser mode, use "Open Folder…" ' +
+        '(above) instead — it picks a real on-disk folder via File System Access.',
+    );
+  }
+  try {
+    const res = await fetch(`${BASE}/browse-folder`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title }),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { path: string | null };
+    return data.path;
+  } catch {
+    return null;
+  }
+}
+
+/** Reveal a file or folder in the OS file manager. */
+export async function revealInFinder(targetPath: string): Promise<void> {
+  if (isBrowserMode()) {
+    throw new Error(
+      'Revealing a file in the OS file manager needs the Node dev server — a browser-mode project ' +
+        'has no OS path to reveal (File System Access does not expose one).',
+    );
+  }
+  await fetch(`${BASE}/reveal`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path: targetPath }),
+  });
+}
+
+/** Save a viewport thumbnail for the current project. Always a no-op in
+ *  browser mode — its only consumer is the Node-only recent-projects list
+ *  (`listRecentProjects`), which has no browser-mode equivalent to attach a
+ *  thumbnail to; this is background bookkeeping, not a user-facing promise. */
+export async function saveThumbnail(dataUrl: string): Promise<boolean> {
+  if (isBrowserMode()) return false;
+  try {
+    const res = await fetch(`${BASE}/save-thumbnail`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ dataUrl }),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Query the server for the currently active project (if any). */
+export async function getCurrentServerProject(): Promise<{
+  path: string;
+  config: { name: string };
+  /** Whether the project ships src/ui/registry.ts (scene-UI project mode, D9). */
+  hasUiRegistry?: boolean;
+  /** Whether this server is the no-monorepo-checkout packaged runtime
+   *  (`packages/editor/server/packaged.ts`) — see `adapter-resolver.ts`'s
+   *  `isPackagedRuntime` for why a react world's mount needs this. */
+  packaged?: boolean;
+} | null> {
+  // Browser mode has no Node dev server to ask — same honest no-fetch
+  // degrade as the other background reads in this file (Phase A).
+  if (isBrowserMode()) return null;
+  try {
+    const res = await fetch(`${BASE}/project`);
+    if (!res.ok) return null;
+    const data = (await res.json()) as {
+      project: {
+        path: string;
+        config: { name: string };
+        hasUiRegistry?: boolean;
+        packaged?: boolean;
+      } | null;
+    };
+    return data.project;
+  } catch {
+    return null;
+  }
+}
+
+/** Open/switch to a project by its filesystem path. */
+export async function openProjectOnServer(
+  projectPath: string,
+): Promise<{ ok: boolean; config?: { name: string } }> {
+  if (isBrowserMode()) {
+    throw new Error(
+      'Opening a project by filesystem path needs the Node dev server. In browser mode, use ' +
+        '"Open Folder…" instead — it picks a real on-disk folder via File System Access.',
+    );
+  }
+  const res = await fetch(`${BASE}/open-project`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path: projectPath }),
+  });
+  return (await res.json()) as { ok: boolean; config?: { name: string } };
+}
+
+// ---------------------------------------------------------------------------
+// Persistent editor state (.vgai/editor-state.json)
+// ---------------------------------------------------------------------------
+
+/** Project-root-relative path — same `.vgai/` namespace as
+ *  `authoring/world-overlay.ts`'s overlays, and the exact file the server's
+ *  `/__editor/editor-state` route reads/writes via `node:fs`. */
+const EDITOR_STATE_PATH = '.vgai/editor-state.json';
+
+/** Load persisted editor state. Returns {} if none exists. Browser mode goes
+ *  straight through `getStorageBackend()` (OPFS/FSA root at the true project
+ *  folder, no `public/` insertion) instead of the Node-only route — this is
+ *  genuine authoring-loop parity (remembered transform mode/snap/last
+ *  scene/camera), not a background nicety, so it is ROUTED, not dropped. */
+export async function loadEditorState(): Promise<Record<string, unknown>> {
+  try {
+    if (isBrowserMode()) {
+      const backend = getStorageBackend();
+      if (!(await backend.exists(EDITOR_STATE_PATH))) return {};
+      return JSON.parse(await backend.read(EDITOR_STATE_PATH)) as Record<string, unknown>;
+    }
+    const res = await fetch(`${BASE}/editor-state`);
+    if (!res.ok) return {};
+    return (await res.json()) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/** Save editor state (persisted in .vgai/editor-state.json — see
+ *  `loadEditorState`'s doc comment for the browser-mode routing). */
+export async function saveEditorState(state: Record<string, unknown>): Promise<boolean> {
+  try {
+    if (isBrowserMode()) {
+      await getStorageBackend().write(EDITOR_STATE_PATH, JSON.stringify(state, null, 2));
+      return true;
+    }
+    const res = await fetch(`${BASE}/editor-state`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(state),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Play-mode console log persistence
+// ---------------------------------------------------------------------------
+
+export interface LogEntry {
+  t: number;
+  level: string;
+  source?: string;
+  sub?: string;
+  msg: string;
+  meta?: Record<string, unknown>;
+}
+
+/** Start a new log session. Returns the filename, or null on failure. Always
+ *  `null` in browser mode with NO fetch attempted — play-mode console → JSONL
+ *  persistence is `vgai apply-diff`/agent-tooling introspection, bucketed
+ *  with the CLI control channel (already fully dropped in browser mode by
+ *  `command-listener.ts`): no browser-mode consumer reads this file. */
+export async function startLogSession(): Promise<string | null> {
+  if (isBrowserMode()) return null;
+  try {
+    const res = await fetch(`${BASE}/log-session`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'start' }),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { ok: boolean; file: string };
+    return data.file;
+  } catch {
+    return null;
+  }
+}
+
+/** End the current log session. No-op in browser mode (see `startLogSession`). */
+export async function endLogSession(): Promise<void> {
+  if (isBrowserMode()) return;
+  try {
+    await fetch(`${BASE}/log-session`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'end' }),
+    });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Flush a batch of log entries to the server. Returns true on success. No-op
+ *  in browser mode (see `startLogSession`) — critically, this is called on a
+ *  `setInterval` while Play is running, so without this guard it would hammer
+ *  a dead endpoint every 200ms for the whole play session (the same
+ *  retry-loop anti-pattern A2's SSE guards exist to avoid, just via
+ *  `setInterval`+`fetch` instead of `EventSource`). */
+export async function flushLogEntries(entries: LogEntry[]): Promise<boolean> {
+  if (entries.length === 0) return true;
+  if (isBrowserMode()) return true;
+  try {
+    const res = await fetch(`${BASE}/log-entries`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ entries }),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Asset Library (online browsing + download)
+//
+// The whole feature is a Node-only proxy to Poly Haven/ambientcg (CORS +
+// SSRF-allowlist reasons to stay server-side) that writes into
+// `<project>/public/asset-library/...` via raw `node:fs`, not
+// `StorageBackend` — there is no browser-mode equivalent. `BottomPanel.tsx`
+// hides the whole "Library" tab in browser mode; the functions below are a
+// defensive backstop for any other caller: read-only lookups degrade to an
+// honest empty result (no fetch attempted), the one mutating call
+// (`downloadOnlineAsset`) throws instead.
+// ---------------------------------------------------------------------------
+
+export interface OnlineAsset {
+  id: string;
+  source: 'polyhaven' | 'ambientcg' | 'local';
+  name: string;
+  type: 'model' | 'animation' | 'source' | 'hdri' | 'texture' | 'material';
+  thumbnailUrl: string;
+  categories: string[];
+  tags: string[];
+  downloadCount?: number;
+  license?: string;
+  author?: string;
+  sourceUrl?: string;
+  cloudHosted?: boolean;
+}
+
+export interface AssetFileOption {
+  label: string;
+  format: string;
+  url: string;
+  sizeBytes?: number;
+  includes?: { relativePath: string; url: string; size: number }[];
+}
+
+// ---------------------------------------------------------------------------
+// Downloaded-asset cache (client-side, keyed by "source:slug")
+// ---------------------------------------------------------------------------
+
+/** Maps "source:slug" → local serving path (e.g. "/asset-library/polyhaven/arm-chair-01/..."). */
+const downloadedAssetPaths = new Map<string, string>();
+
+/** Listeners notified when the download cache changes. */
+const downloadListeners = new Set<() => void>();
+
+/** Same slug logic as the server's download endpoint. */
+function toSlug(nameOrId: string): string {
+  return nameOrId
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function assetCacheKey(source: string, nameOrId: string): string {
+  return `${source}:${toSlug(nameOrId)}`;
+}
+
+/** Check if an online asset has already been downloaded. Returns local path or null. */
+export function getDownloadedAssetPath(source: string, nameOrId: string): string | null {
+  return downloadedAssetPaths.get(assetCacheKey(source, nameOrId)) ?? null;
+}
+
+/** Subscribe to download cache changes. Returns unsubscribe function. */
+export function onAssetDownloaded(cb: () => void): () => void {
+  downloadListeners.add(cb);
+  return () => downloadListeners.delete(cb);
+}
+
+/** Fetch already-downloaded assets from the server and seed the cache.
+ *  No-op in browser mode — see the Asset Library section header comment. */
+export async function loadDownloadedAssets(): Promise<void> {
+  if (isBrowserMode()) return;
+  try {
+    const res = await fetch(`${BASE}/asset-library/downloaded`);
+    if (!res.ok) return;
+    const data = (await res.json()) as {
+      downloaded: { source: string; slug: string; path: string }[];
+    };
+    for (const entry of data.downloaded) {
+      downloadedAssetPaths.set(`${entry.source}:${entry.slug}`, `/${entry.path}`);
+    }
+    for (const cb of downloadListeners) cb();
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Search for online assets via the editor server proxy. */
+export async function searchOnlineAssets(params: {
+  source: string;
+  type: string;
+  q?: string;
+  category?: string;
+  offset?: number;
+  limit?: number;
+}): Promise<{ assets: OnlineAsset[]; total: number }> {
+  if (isBrowserMode()) return { assets: [], total: 0 };
+  const qs = new URLSearchParams();
+  qs.set('source', params.source);
+  qs.set('type', params.type);
+  if (params.q) qs.set('q', params.q);
+  if (params.category) qs.set('category', params.category);
+  if (params.offset != null) qs.set('offset', String(params.offset));
+  if (params.limit != null) qs.set('limit', String(params.limit));
+
+  const res = await fetch(`${BASE}/asset-library/search?${qs}`);
+  if (!res.ok) return { assets: [], total: 0 };
+  return (await res.json()) as { assets: OnlineAsset[]; total: number };
+}
+
+/** Get available file options (resolutions/formats) for an online asset. */
+export async function getOnlineAssetFiles(source: string, id: string): Promise<AssetFileOption[]> {
+  if (isBrowserMode()) return [];
+  const qs = new URLSearchParams({ source, id });
+  const res = await fetch(`${BASE}/asset-library/files?${qs}`);
+  if (!res.ok) return [];
+  const data = (await res.json()) as { files: AssetFileOption[] };
+  return data.files;
+}
+
+/** Download an online asset into the project's public/asset-library/ folder. */
+export async function downloadOnlineAsset(params: {
+  source: string;
+  id: string;
+  name: string;
+  url: string;
+  format: string;
+  includes?: { relativePath: string; url: string; size: number }[];
+}): Promise<{ ok: boolean; path?: string; alreadyExists?: boolean; error?: string }> {
+  if (isBrowserMode()) {
+    throw new Error(
+      'Downloading online assets needs the Node dev server (Poly Haven/ambientcg access is proxied ' +
+        'server-side). Not available in browser mode.',
+    );
+  }
+  const res = await fetch(`${BASE}/asset-library/download`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(params),
+  });
+  const result = (await res.json()) as {
+    ok: boolean;
+    path?: string;
+    alreadyExists?: boolean;
+    error?: string;
+  };
+  // Cache the local path on success
+  if (result.ok && result.path) {
+    downloadedAssetPaths.set(assetCacheKey(params.source, params.name), `/${result.path}`);
+    for (const cb of downloadListeners) cb();
+  }
+  return result;
+}
+
+/** Get Poly Haven categories for a given asset type. */
+export async function getAssetLibraryCategories(type: string, source?: string): Promise<string[]> {
+  if (isBrowserMode()) return [];
+  const params = new URLSearchParams({ type });
+  if (source) params.set('source', source);
+  const res = await fetch(`${BASE}/asset-library/categories?${params}`);
+  if (!res.ok) return [];
+  const data = (await res.json()) as { categories: string[] };
+  return data.categories;
+}