@volter/editor-core 0.5.57

package/src/animation/three-clips-subject.ts

@@ -0,0 +1,172 @@
+/**
+ * WHAT A THREE WORLD CAN SHOW AT A TIME — the stage transport's subjects for
+ * an ordinary three/R3F stage (WORK.md §The stage transport and the animation
+ * door, Step 3).
+ *
+ * TWO DISCOVERIES, because a three world carries clips in two different
+ * places and only one of them is the obvious one:
+ *
+ *  1. `object.animations` — what a GLTF's own `AnimationClip[]` lands in when
+ *     something assigns it. A subject here owns a NEW `AnimationMixer` on that
+ *     object, because nothing else is playing it.
+ *  2. `getUserData(object, '_animationRuntime')` — the inspection a world's
+ *     own binding attached (`bindXStateAnimation` →
+ *     `attachAnimationRuntimeInspection`). A subject here drives THAT
+ *     inspection's existing mixer; minting a second mixer over the same object
+ *     would give one skeleton two writers.
+ *
+ * DISCOVERY 2 IS NOT OPTIONAL, and this is the measurement that says so:
+ * three's `GLTFLoader` never assigns `scene.animations`, so an R3F character
+ * loaded with `useGLTF` has an EMPTY `animations` array on its Object3D. A
+ * scan that looked only at `animations` would find nothing on exactly the
+ * worlds a person most wants to scrub.
+ *
+ * THE MIXER IS THREE'S OWN and every call here is three's own API — this is a
+ * subject over `AnimationMixer`, never a wrapper around it. `setTime` is the
+ * one write; the transport owns the position.
+ */
+import { getUserData } from '@volter/editor-threejs/ecs/user-data';
+import * as THREE from 'three';
+import type { StageTransport } from './stage-transport';
+
+/** The display rate a three clip is shown at. Three clips carry a duration in
+ *  SECONDS and no rate of their own, so the transport needs one to convert a
+ *  frame for a look that asks in frames. 30 is three's own editor convention
+ *  (`AnimationClip.CreateFromMorphTargetSequence` defaults to it). */
+const THREE_DISPLAY_FPS = 30;
+
+function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value;
+}
+
+/**
+ * A subject over an object's OWN clips, on a mixer this subject mints and
+ * owns. `setClip` swaps which clip is showing: the chosen action is played
+ * PAUSED (so it poses the skeleton without advancing itself) and every other
+ * action is stopped, because the transport — not the action — is what moves.
+ */
+function attachOwnClips(object: THREE.Object3D, transport: StageTransport): (() => void) | null {
+  const clips = object.animations;
+  if (clips.length === 0) return null;
+  const mixer = new THREE.AnimationMixer(object);
+  let current = clips[0];
+  if (!current) return null;
+
+  const show = (clip: THREE.AnimationClip): void => {
+    mixer.stopAllAction();
+    const action = mixer.clipAction(clip);
+    action.paused = true;
+    action.play();
+    current = clip;
+  };
+  show(current);
+
+  const detach = transport.attach({
+    id: object.uuid,
+    label: object.name || current.name || 'Clip',
+    range: () => ({ start: 0, end: current?.duration ?? 0, fps: THREE_DISPLAY_FPS }),
+    seek: (seconds) => {
+      mixer.setTime(clamp(seconds, 0, current?.duration ?? 0));
+    },
+    clips: () => clips.map((clip) => ({ id: clip.name, label: clip.name })),
+    setClip: (id) => {
+      const next = clips.find((clip) => clip.name === id);
+      if (next) show(next);
+    },
+  });
+
+  return () => {
+    detach();
+    mixer.stopAllAction();
+    mixer.uncacheRoot(object);
+  };
+}
+
+/**
+ * A subject over an inspection a world's own binding already owns. It drives
+ * that mixer and never mints one; `clips` come from the inspection's map.
+ */
+function attachInspected(object: THREE.Object3D, transport: StageTransport): (() => void) | null {
+  const inspection = getUserData(object, '_animationRuntime');
+  if (!inspection) return null;
+  const entries = [...inspection.clips.entries()];
+  let current = entries[0]?.[1];
+  if (!current) return null;
+
+  const show = (clip: THREE.AnimationClip): void => {
+    inspection.mixer.stopAllAction();
+    const action = inspection.mixer.clipAction(clip);
+    action.paused = true;
+    action.play();
+    current = clip;
+  };
+
+  const detach = transport.attach({
+    id: object.uuid,
+    label: object.name || current.name || 'Animation',
+    range: () => ({ start: 0, end: current?.duration ?? 0, fps: THREE_DISPLAY_FPS }),
+    seek: (seconds) => {
+      inspection.mixer.setTime(clamp(seconds, 0, current?.duration ?? 0));
+    },
+    clips: () => entries.map(([name, clip]) => ({ id: name, label: clip.name || name })),
+    setClip: (id) => {
+      const next = inspection.clips.get(id);
+      if (next) show(next);
+    },
+  });
+
+  // Deliberately NOT stopping the inspection's actions on detach: this subject
+  // borrowed a mixer the world owns, and a borrower does not decide what the
+  // owner is playing when it leaves.
+  return detach;
+}
+
+/**
+ * One scan of a mounted root, and the handle that keeps it current.
+ *
+ * `refresh()` DIFFS by object uuid rather than re-attaching: a rescan of an
+ * unchanged tree must not detach and re-attach every subject, because that
+ * would reset which clip each one is showing under a person's hands. The
+ * caller decides when to rescan (the stage host throttles it and skips it
+ * while the world is driving time).
+ */
+export interface ClipSubjectScan {
+  refresh(): void;
+  dispose(): void;
+}
+
+export function scanClipSubjects(root: THREE.Object3D, transport: StageTransport): ClipSubjectScan {
+  const attached = new Map<string, () => void>();
+
+  const refresh = (): void => {
+    const seen = new Set<string>();
+    root.traverse((object) => {
+      if (attached.has(object.uuid)) {
+        seen.add(object.uuid);
+        return;
+      }
+      // The inspection wins when an object has both: it means a world binding
+      // is already driving that skeleton, and a second mixer over it would
+      // give one object two writers.
+      const detach = attachInspected(object, transport) ?? attachOwnClips(object, transport);
+      if (!detach) return;
+      attached.set(object.uuid, detach);
+      seen.add(object.uuid);
+    });
+    for (const [uuid, detach] of [...attached]) {
+      if (seen.has(uuid)) continue;
+      detach();
+      attached.delete(uuid);
+    }
+  };
+
+  refresh();
+
+  return {
+    refresh,
+    dispose: () => {
+      for (const detach of attached.values()) detach();
+      attached.clear();
+    },
+  };
+}

package/src/api/asset-library-wire.ts

@@ -0,0 +1,45 @@
+/**
+ * The asset-library wire — the shapes `/__editor/assets/*` answers with,
+ * declared ONCE in a leaf module both sides import (the browser client in
+ * `./assets.ts`, the producing routes in `../../server/asset-library-routes.ts`).
+ * Deliberately import-free so the server's tsconfig can reach it without
+ * dragging the client's whole module graph along.
+ */
+
+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;
+  variantId?: string;
+  variantCount?: number;
+  sizeBytes?: number;
+  animationCount?: number;
+  deliveryKinds?: ('local-ssd' | 'cloud' | 'remote')[];
+  addedAt?: string;
+  capabilities?: {
+    previewable: boolean;
+    importable: boolean;
+    runtimeReady: boolean;
+    animated: boolean;
+    deliveryAvailable: boolean;
+    health: 'healthy' | 'source-only' | 'unsupported';
+  };
+}
+
+export interface AssetFileOption {
+  label: string;
+  format: string;
+  url: string;
+  sizeBytes?: number;
+  /** Additional files that must be downloaded alongside the main URL (GLTF includes). */
+  includes?: { relativePath: string; url: string; size: number }[];
+}

package/src/api/assets.ts

@@ -0,0 +1,365 @@
+/**
+ * Listing project assets, and the online asset library. Both are the session's
+ * own routes: it owns the project folder, so it is the one thing that can list
+ * `public/` or write a downloaded asset into it.
+ */
+
+import type { ProjectComponentEntry } from '../asset-workflow/project-content';
+
+import { assertEditorServerAnswered, editorServerJson } from '../editor-server-response';
+import { getStorageBackend } from '../storage';
+import { BASE } from './base';
+export interface AssetEntry {
+  name: string;
+  type: 'file' | 'directory';
+  /** Bytes, when the backend reports it. ABSENT means unmeasured — not zero. */
+  size?: number;
+  /** Epoch ms, when the backend reports it. ABSENT means unmeasured — not 1970. */
+  modifiedAt?: number;
+}
+
+/**
+ * A listing that either HAPPENED or FAILED.
+ *
+ * `{ ok: true, entries: [] }` is a real measurement — the directory is empty,
+ * the project defines no components. A failure is a DIFFERENT FACT and carries
+ * its reason, because rendering "this folder is empty" over a permissions
+ * error, an offline dev server or a 500 tells the author their work is gone.
+ * Both listings used to `catch { return [] }`, so the two were the same bytes.
+ */
+export type Listing<T> =
+  | { readonly ok: true; readonly entries: T[] }
+  | { readonly ok: false; readonly reason: string };
+
+function listingFailure(error: unknown): { readonly ok: false; readonly reason: string } {
+  return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+}
+
+/** One named asset root, listed by the editor server's own route. The entry
+ *  shape is the route's; an ABSENT root answers the empty listing (the route's
+ *  own S-8 rule), and a real failure still reports its reason. */
+async function listAssetRootFromServer(root: string, dir: string): Promise<Listing<AssetEntry>> {
+  try {
+    const query = new URLSearchParams({ root, dir });
+    const response = await fetch(`${BASE}/assets?${query}`, { cache: 'no-store' });
+    const body = await editorServerJson<{ entries?: AssetEntry[] }>(
+      response,
+      `Could not list ${root}/${dir} from ${BASE}/assets`,
+    );
+    return { ok: true, entries: body.entries ?? [] };
+  } catch (error) {
+    return listingFailure(error);
+  }
+}
+
+/**
+ * List files and folders in a directory under one of the project's asset roots
+ * (`public`, or `references` — see `asset-workflow/project-asset-roots.ts`).
+ * `dir` is root-relative in both tiers; only the way the root is reached
+ * differs, and that difference is the two branches below.
+ */
+export async function listAssets(root: string, dir: string): Promise<Listing<AssetEntry>> {
+  // The tier's backend is rooted AT `public/`, so a second root cannot be
+  // spelled through it at all — it is named to the server's own listing route
+  // instead, which resolves it from the open project.
+  if (root !== 'public') return listAssetRootFromServer(root, dir);
+  try {
+    const entries = await getStorageBackend().list(dir);
+    return {
+      ok: true,
+      entries: entries.map((e) => ({
+        name: e.name,
+        type: e.type === 'dir' ? ('directory' as const) : ('file' as const),
+        // OMITTED, never zeroed: a backend that does not report a size has not
+        // told us the file is 0 bytes, and a browser listing genuinely cannot
+        // for some handles. `0`/`0` sorted an unmeasured file to the bottom of
+        // "largest first" and to 1970 in "most recent", both as if measured.
+        ...(e.size === undefined ? {} : { size: e.size }),
+        ...(e.mtime === undefined ? {} : { modifiedAt: e.mtime }),
+      })),
+    };
+  } catch (error) {
+    return listingFailure(error);
+  }
+}
+
+/** List source-defined visual components for the semantic component board. */
+export async function listProjectComponents(): Promise<Listing<ProjectComponentEntry>> {
+  try {
+    const response = await fetch(`${BASE}/project-components`, { cache: 'no-store' });
+    const body = await editorServerJson<{ components?: ProjectComponentEntry[] }>(
+      response,
+      `Could not list project components from ${BASE}/project-components`,
+    );
+    return { ok: true, entries: body.components ?? [] };
+  } catch (error) {
+    return listingFailure(error);
+  }
+}
+
+/** Build a download URL for a build artifact. */
+export function getDownloadUrl(file: string): string {
+  return `${BASE}/download?file=${encodeURIComponent(file)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Asset Library (online browsing + download)
+//
+// The session is a Node-only proxy to Poly Haven/ambientcg (CORS +
+// SSRF-allowlist reasons to stay server-side) plus the 34,412-asset local SSD
+// catalog, writing into `<project>/public/asset-library/...` via raw
+// `node:fs`. A browser cannot do either: it is refused by CORS and has no
+// local disk to read.
+// ---------------------------------------------------------------------------
+
+import type { AssetFileOption, OnlineAsset } from './asset-library-wire';
+
+export type { AssetFileOption, OnlineAsset } from './asset-library-wire';
+
+export type AssetDeliveryIssueCode =
+  | 'offline'
+  | 'quota-limited'
+  | 'license-blocked'
+  | 'unavailable'
+  | 'provider-error';
+
+export class AssetDeliveryError extends Error {
+  constructor(
+    readonly code: AssetDeliveryIssueCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'AssetDeliveryError';
+  }
+}
+
+export function assetDeliveryIssueMessage(code: AssetDeliveryIssueCode): string {
+  return {
+    offline: 'Network delivery is offline. SSD assets remain available.',
+    'quota-limited': 'The remote provider quota is exhausted. Retry after the provider resets it.',
+    'license-blocked': 'This delivery is blocked because its license terms are not accepted.',
+    unavailable: 'No healthy SSD, cloud, or remote delivery is available for this variant.',
+    'provider-error': 'The remote provider could not return delivery metadata. Retry the request.',
+  }[code];
+}
+
+export interface OnlineAssetPreview {
+  path: string;
+  format: string;
+  label: string;
+  sourceAssetId: string;
+  materialPath?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Downloaded-asset cache (client-side, keyed by exact provider identity)
+// ---------------------------------------------------------------------------
+
+/** Maps "source:asset-id" → local serving path. Display names are never identity. */
+const downloadedAssetPaths = new Map<string, string>();
+
+/** Listeners notified when the download cache changes. */
+const downloadListeners = new Set<() => void>();
+
+function assetCacheKey(source: string, assetId: string): string {
+  return `${source}:${assetId}`;
+}
+
+/** Check if an online asset has already been downloaded. Returns local path or null. */
+export function getDownloadedAssetPath(source: string, assetId: string): string | null {
+  return downloadedAssetPaths.get(assetCacheKey(source, assetId)) ?? 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. */
+export async function loadDownloadedAssets(): Promise<void> {
+  try {
+    const res = await fetch(`${BASE}/asset-library/downloaded`);
+    const data = await editorServerJson<{
+      downloaded: { source: string; id: string; path: string }[];
+    }>(res, 'Could not read the downloaded-asset list');
+    downloadedAssetPaths.clear();
+    for (const entry of data.downloaded) {
+      downloadedAssetPaths.set(assetCacheKey(entry.source, entry.id), `/${entry.path}`);
+    }
+    for (const cb of downloadListeners) cb();
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Search for online assets via the editor server's proxy. */
+export async function searchOnlineAssets(params: {
+  source: string;
+  type: string;
+  q?: string;
+  category?: string;
+  offset?: number;
+  limit?: number;
+}): Promise<{ assets: OnlineAsset[]; total: number }> {
+  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}`);
+  assertEditorServerAnswered(res, 'Asset Library search failed');
+  if (!res.ok) {
+    const body = (await res.json().catch(() => null)) as { error?: string } | null;
+    throw new Error(body?.error ?? `Asset Library search failed (${res.status}).`);
+  }
+  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[]> {
+  return fetchOnlineAssetFilesFromServer(source, id);
+}
+
+async function fetchOnlineAssetFilesFromServer(
+  source: string,
+  id: string,
+): Promise<AssetFileOption[]> {
+  const qs = new URLSearchParams({ source, id });
+  let res: Response;
+  try {
+    res = await fetch(`${BASE}/asset-library/files?${qs}`);
+  } catch (error) {
+    throw new AssetDeliveryError(
+      'offline',
+      error instanceof Error ? error.message : assetDeliveryIssueMessage('offline'),
+    );
+  }
+  // A page fallback here is not a provider problem — it is nobody serving the
+  // route — so it reports itself rather than being graded into a delivery code.
+  assertEditorServerAnswered(res, 'Asset Library file lookup failed');
+  if (!res.ok) {
+    const body = (await res.json().catch(() => null)) as { error?: string } | null;
+    const code: AssetDeliveryIssueCode =
+      res.status === 403
+        ? 'license-blocked'
+        : res.status === 429
+          ? 'quota-limited'
+          : res.status === 404
+            ? 'unavailable'
+            : 'provider-error';
+    throw new AssetDeliveryError(code, body?.error ?? assetDeliveryIssueMessage(code));
+  }
+  const data = (await res.json()) as { files: AssetFileOption[] };
+  return data.files;
+}
+
+/** Resolve a read-only interactive model preview from the editor's catalog cache. */
+export async function getOnlineAssetPreview(
+  source: string,
+  id: string,
+): Promise<OnlineAssetPreview | null> {
+  const qs = new URLSearchParams({ source, id });
+  const res = await fetch(`${BASE}/asset-library/preview?${qs}`);
+  // `null` stays the answer for a route that says "no preview" (404); it is NOT
+  // the answer for an origin where the route does not exist at all.
+  assertEditorServerAnswered(res, 'Could not resolve an asset preview');
+  if (!res.ok) return null;
+  return (await res.json()) as OnlineAssetPreview;
+}
+
+export interface AppliedAssetImportHistory {
+  assetPath: string;
+  beforeToken: string;
+  afterToken: string;
+}
+
+export interface DownloadOnlineAssetResult {
+  ok: boolean;
+  path?: string;
+  alreadyExists?: boolean;
+  provenanceOperationId?: string;
+  history?: AppliedAssetImportHistory;
+  error?: string;
+  /** The import SUCCEEDED but `.vgai/assets.json` could not be updated (D-AP3).
+   *  Loud, non-fatal degradation: the bytes are in the project, the provenance
+   *  record is not. */
+  ledgerError?: string;
+}
+
+/** 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;
+  jobId?: string;
+  includes?: { relativePath: string; url: string; size: number }[];
+  /** License as the library's own search result reported it. Recorded in the
+   *  provenance ledger for sources the server cannot resolve a license for
+   *  (the polyhaven/ambientcg proxy) — see D-AP3. */
+  license?: string;
+  signal?: AbortSignal;
+}): Promise<DownloadOnlineAssetResult> {
+  const res = await fetch(`${BASE}/asset-library/download`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ ...params, signal: undefined }),
+    ...(params.signal ? { signal: params.signal } : {}),
+  });
+  assertEditorServerAnswered(res, 'Could not download the asset');
+  const result = (await res.json()) as DownloadOnlineAssetResult;
+  // Cache the local path on success
+  if (result.ok && result.path) {
+    downloadedAssetPaths.set(assetCacheKey(params.source, params.id), `/${result.path}`);
+    for (const cb of downloadListeners) cb();
+  }
+  return result;
+}
+
+/** Capture a content-addressed server snapshot for one imported asset directory. */
+export async function captureProjectAssetHistory(assetPath: string): Promise<string> {
+  const response = await fetch(`${BASE}/asset-library/history/capture`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ assetPath }),
+  });
+  assertEditorServerAnswered(response, 'Asset history capture failed');
+  const result = (await response.json()) as { ok?: boolean; token?: string; error?: string };
+  if (!response.ok || !result.token) {
+    throw new Error(result.error ?? `Asset history capture failed (${response.status}).`);
+  }
+  return result.token;
+}
+
+/** Restore an exact imported-directory + provenance snapshot during undo/redo. */
+export async function restoreProjectAssetHistory(assetPath: string, token: string): Promise<void> {
+  const response = await fetch(`${BASE}/asset-library/history/restore`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ assetPath, token }),
+  });
+  // This function REPORTS BY RETURNING: a page fallback is `ok`, so an undo
+  // that restored nothing used to complete silently.
+  assertEditorServerAnswered(response, 'Asset history restore failed');
+  if (!response.ok) {
+    const result = (await response.json().catch(() => null)) as { error?: string } | null;
+    throw new Error(result?.error ?? `Asset history restore failed (${response.status}).`);
+  }
+}
+
+/** Get categories for a given asset type (Poly Haven, or the cloud-hosted
+ *  "local" catalog). */
+export async function getAssetLibraryCategories(type: string, source?: string): Promise<string[]> {
+  const params = new URLSearchParams({ type });
+  if (source) params.set('source', source);
+  const res = await fetch(`${BASE}/asset-library/categories?${params}`);
+  assertEditorServerAnswered(res, 'Could not read Asset Library categories');
+  if (!res.ok) return [];
+  const data = (await res.json()) as { categories: string[] };
+  return data.categories;
+}

package/src/api/base.ts

@@ -0,0 +1,10 @@
+/**
+ * What every `api/<family>.ts` module shares: the route prefix every
+ * `/__editor/*` op is written against.
+ *
+ * The session serves the editor and answers these routes (ARCHITECTURE-CORE
+ * §The target shape rule 5), so a family module asks no question before
+ * touching the network.
+ */
+
+export const BASE = '/__editor';

package/src/api/build.ts

@@ -0,0 +1,99 @@
+/**
+ * Producing a build, and the two catalogues the New Project screen starts one
+ * from: `/__editor/export`, `/__editor/examples`, `/__editor/templates`.
+ */
+
+import { editorServerJson } from '../editor-server-response';
+import { BASE } from './base';
+/** Start a build/export. Returns the raw Response for SSE streaming.
+ *
+ *  Deliberately NOT read through `editor-server-response.ts`: that reader's
+ *  rule is "the editor server answers JSON", and a successful export answers
+ *  `text/event-stream`, which it would reject. The stream's own consumer owns
+ *  the question here. */
+
+/** FT-5 learner-facing metadata — mirrors the manifest's `learn` block
+ *  (`LearnMetadataSchema`, @volter/editor-project/manifest/schema); served merged into `GET
+ *  /__editor/examples`. */
+export interface ExampleLearnInfo {
+  kind: 'starter' | 'feature' | 'sample-game' | 'lesson-companion';
+  title: string;
+  summary: string;
+  difficulty: 'beginner' | 'intermediate' | 'advanced';
+  features: string[];
+  thumbnail?: string;
+  preview?: string;
+  lesson?: string;
+}
+
+export interface ExampleInfo {
+  id: string;
+  name: string;
+  /** The example's FT-5 `learn` block. REQUIRED: every shipped example
+   *  carries one and the server omits any example that doesn't (editor and
+   *  server ship from one repo, so there is no older server to be compatible
+   *  with). */
+  learn: ExampleLearnInfo;
+}
+
+/** List `examples/<id>/` projects (Track E3, §1.F). Server mode reads the
+ *  scaffold registry. Browser mode derives the list from what THIS build
+ *  actually stages: the runtime bundle's per-root dispatch keys name every
+ *  bundled example, and each one's manifest (with its FT-5 `learn` block) is
+ *  served at `/examples/<id>/vgai.project.json` — so the gallery lists
+ *  exactly the projects `?project=<id>` can open, never a curated id that
+ *  drifted from the build (the dead `editor-tutorial` link, measured on
+ *  production 2026-08-27, was exactly that drift). */
+export async function listExamples(): Promise<ExampleInfo[]> {
+  try {
+    const res = await fetch(`${BASE}/examples`);
+    const data = await editorServerJson<{ examples: ExampleInfo[] }>(
+      res,
+      `GET ${BASE}/examples failed`,
+    );
+    return data.examples;
+  } catch {
+    return [];
+  }
+}
+
+/** One template-registry entry (G1, FT-3): mirrors `TemplateRegistryEntry` in
+ *  create-vgai-project/templates, served by `GET /__editor/templates` from the
+ *  same `templates.json` the CLI reads. */
+export interface TemplateInfo {
+  id: string;
+  title: string;
+  description: string;
+  /** `template:<compositionId>` or `example:<exampleId>`. */
+  source: string;
+  thumbnail?: string;
+  /** Curated preview bullets for composition templates. Promoted examples
+   * derive their facts from the owning example's learn metadata. */
+  whatsInside?: string[];
+  /** A post-copy PRESENTATION of `source`'s tree. The gallery's
+   * "Blank" card carries `'blank'` beside the SAME `template:default` source
+   * the starter card uses — two cards, one template. */
+  presentation?: string;
+}
+
+/** Map an engine-repo-relative registry/learn thumbnail path to its server
+ * route without baking template or example directories into the client. */
+export function learnThumbnailUrl(repoRelativePath: string): string {
+  // Browser-mode example thumbnails are already staged ABSOLUTE paths
+  // (`/examples/<id>/learn/…`) — there is no server route to proxy them.
+  if (repoRelativePath.startsWith('/')) return repoRelativePath;
+  return `${BASE}/learn-thumbnail?file=${encodeURIComponent(repoRelativePath)}`;
+}
+
+/** List the template registry. */
+export async function listTemplates(): Promise<TemplateInfo[]> {
+  // No silent empty-list fallback and no hardcoded fallback entry in the
+  // wizard: editor and server ship from ONE repo, so an unreachable or
+  // failing `/templates` is a real defect, not version skew. Surface it.
+  const res = await fetch(`${BASE}/templates`);
+  const data = await editorServerJson<{ templates: TemplateInfo[] }>(
+    res,
+    `GET ${BASE}/templates failed`,
+  );
+  return data.templates;
+}