@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/doctor/report.ts

@@ -36,7 +36,7 @@ import type { DataDoctorFinding } from './data-checks';
 /** One declared world from the manifest — enough identity to label a verdict row. */
 export interface DoctorDeclaredWorld {
   readonly worldId: string;
-  /** `ResolvedWorldEntry.kind` (e.g. `'threejs'`/`'pixijs'`/`'react'`). */
+  /** `ResolvedAdapterRoot.kind` (e.g. `'threejs'`/`'pixijs'`/`'react'`). */
   readonly kind: string;
   /** `ResolvedAdapter['identity']` (e.g. `'ingest-three'`/`'module'`/`'default-three'`). */
   readonly identity: string;
@@ -108,6 +108,17 @@ export interface DoctorSiblingEvidence {
   readonly authoringPersist: boolean;
 }
 
+/**
+ * Evidence from the editor's real Play composer. The world id is published
+ * only after `mountManifestWorlds` has returned and play-mode has installed
+ * the composite authoring surface, so presence proves both runtime mount and
+ * editor adoption without inventing kind-specific capture data.
+ */
+export interface DoctorRuntimeEvidence {
+  readonly runtimeMounted: true;
+  readonly authoringPresent: true;
+}
+
 /**
  * Every raw datum the browser-phase runner scraped off the live page —
  * data-in for {@link assembleDoctorReport}. Maps/sets are keyed by worldId so
@@ -128,6 +139,7 @@ export interface DoctorRawSignals {
    * byte-stable — an absent map reads exactly like an empty one.
    */
   readonly siblingEvidence?: ReadonlyMap<string, DoctorSiblingEvidence>;
+  readonly runtimeEvidence?: ReadonlyMap<string, DoctorRuntimeEvidence>;
   /**
    * Per-worldId react-ingest DOM evidence (D-L2, wave 10 Slice B,
    * docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md) — checked in
@@ -150,6 +162,7 @@ export interface DoctorMountedVerdict extends DoctorVerdictBase {
     | DoctorIngestEvidence
     | DoctorModuleEvidence
     | DoctorSiblingEvidence
+    | DoctorRuntimeEvidence
     | DoctorReactIngestEvidence;
 }
 
@@ -165,7 +178,7 @@ export interface DoctorUnverifiableVerdict extends DoctorVerdictBase {
 
 export type DoctorVerdict = DoctorMountedVerdict | DoctorFailedVerdict | DoctorUnverifiableVerdict;
 
-/** True iff an ingest-capture evidence bundle proves a real, live, editable mount (D-A4's MOUNTED bar for ingest worlds). */
+/** True iff an ingest-capture evidence bundle proves a real, live, editable mount (D-A4's MOUNTED bar for ingest roots). */
 function clearsIngestMountedBar(ev: DoctorIngestEvidence): boolean {
   const reflectedOk = ev.reflectedCount !== null && ev.reflectedCount > 0;
   const drawOk = ev.drawCountClimbed === true;
@@ -183,7 +196,7 @@ function ingestShortfallReason(worldId: string, ev: DoctorIngestEvidence): strin
   );
 }
 
-/** True iff react-ingest DOM evidence proves a real, live, editable mount (D-L3's MOUNTED bar for react-ingest worlds) — ALL four legs, never partial credit. */
+/** True iff react-ingest DOM evidence proves a real, live, editable mount (D-L3's MOUNTED bar for react-ingest roots) — ALL four legs, never partial credit. */
 function clearsReactIngestMountedBar(ev: DoctorReactIngestEvidence): boolean {
   return (
     ev.elementCount > 0 && ev.hierarchyNodeCount > 0 && ev.reactRootPresent && ev.setPausedPresent
@@ -292,6 +305,11 @@ export function assembleDoctorReport(
       };
     }
 
+    const runtimeEv = raw.runtimeEvidence?.get(worldId);
+    if (runtimeEv) {
+      return { worldId, kind, identity, verdict: 'MOUNTED', evidence: runtimeEv };
+    }
+
     // D-H2 (docs/WAVE9-SIBLING-PERSISTENCE-DOCTOR-DESIGN.md Slice B): checked
     // LAST among the "some evidence exists" branches, after ingest/module
     // evidence and react presence — so a world whose ingest evidence exists
@@ -311,10 +329,16 @@ export function assembleDoctorReport(
       kind,
       identity,
       verdict: 'UNVERIFIABLE',
+      // Dry-run finding (docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md Wave 6 ledger —
+      // "Doctor's UNVERIFIABLE world verdict reads oddly next to 'clean'"):
+      // agents reading a healthy world's report couldn't tell from the old
+      // wording alone whether UNVERIFIABLE counted as a problem. State the
+      // verdict semantics inline, up front, before the per-world detail.
       reason:
-        `no headless health signal was observed for world "${worldId}" (kind "${kind}", identity ` +
-        `"${identity}"), and no mount-failure entry named it either — either this identity has no ` +
-        'headless signal wired in doctor this slice, or the mount never ran at all.',
+        'no headless health signal exists for this world kind yet; NOT a failure (doctor treats ' +
+        `it as non-blocking) — nothing was observed for world "${worldId}" (kind "${kind}", ` +
+        `identity "${identity}"), and no mount-failure entry named it either — either this ` +
+        'identity has no headless signal wired in doctor this slice, or the mount never ran at all.',
     };
   });
 }
@@ -342,30 +366,50 @@ export interface DoctorStaticSummary {
  * 3 -> 4 (docs/DATA-TOOLS-DESIGN.md §6.6, W5 enforcement): the envelope
  * gained the optional top-level `data` section (data-asset findings), and an
  * ERROR-severity data finding now flips the exit code (see
- * {@link doctorExitCode}).
+ * {@link doctorExitCode}). Bumped 4 -> 5: ordinary manifest roots now gain
+ * the {@link DoctorRuntimeEvidence} variant after a real editor Play mount.
  */
-export const DOCTOR_VERSION = 4 as const;
+export const DOCTOR_VERSION = 5 as const;
+
+/**
+ * The acceptance-suite line item (docs/ACCEPTANCE-DRIVER-SPEC.md §2.4, Task
+ * 4.3): how many `tests/acceptance/*.spec.ts` files the project has, plus —
+ * iff that count is zero — the advisory message (`run-probe.ts`'s
+ * `ZERO_SPECS_MESSAGE`, the exact line `vgai probe` itself prints for an
+ * empty suite). ADVISORY ONLY: it never flips the exit code
+ * ({@link doctorExitCode} does not read it), so it is a purely additive
+ * optional envelope field — no {@link DOCTOR_VERSION} bump, the same
+ * shape-evolution pattern the optional `data` section established.
+ */
+export interface DoctorAcceptanceSummary {
+  readonly specCount: number;
+  readonly advisory?: string;
+}
 
 export interface DoctorJsonReport {
   readonly doctorVersion: typeof DOCTOR_VERSION;
   readonly static: DoctorStaticSummary;
-  readonly worlds: readonly DoctorVerdict[];
+  readonly roots: readonly DoctorVerdict[];
   /** Data-asset check findings (docs/DATA-TOOLS-DESIGN.md §6.6) — present iff the caller ran the data scan (run-doctor.ts always does; older/other callers may not). */
   readonly data?: { readonly findings: readonly DataDoctorFinding[] };
+  /** Acceptance-suite summary ({@link DoctorAcceptanceSummary}) — present iff the caller scanned `tests/acceptance/` (run-doctor.ts always does; older/other callers may not). Advisory only — never affects the exit code. */
+  readonly acceptance?: DoctorAcceptanceSummary;
 }
 
-/** Build the stable `--json` envelope (D-A5: "stable shape, top-level `doctorVersion`, static-phase result included"; the version literal itself is {@link DOCTOR_VERSION}, currently `4`). The `data` section is included only when findings were actually scanned — never fabricated as an empty pass. */
+/** Build the stable `--json` envelope (D-A5: "stable shape, top-level `doctorVersion`, static-phase result included"; the version literal itself is {@link DOCTOR_VERSION}, currently `5`). The `data` and `acceptance` sections are included only when their scans actually ran — never fabricated as an empty pass. */
 export function buildDoctorJsonReport(
   staticSummary: DoctorStaticSummary,
   worldVerdicts: readonly DoctorVerdict[],
   dataFindings?: readonly DataDoctorFinding[],
+  acceptance?: DoctorAcceptanceSummary,
 ): DoctorJsonReport {
   const base: DoctorJsonReport = {
     doctorVersion: DOCTOR_VERSION,
     static: staticSummary,
-    worlds: worldVerdicts,
+    roots: worldVerdicts,
   };
-  return dataFindings ? { ...base, data: { findings: dataFindings } } : base;
+  const withData = dataFindings ? { ...base, data: { findings: dataFindings } } : base;
+  return acceptance ? { ...withData, acceptance } : withData;
 }
 
 /**
@@ -373,7 +417,7 @@ export function buildDoctorJsonReport(
  * UNVERIFIABLE does not flip the exit code." Extended by W5 enforcement
  * (docs/DATA-TOOLS-DESIGN.md §6.6): an ERROR-severity data-asset finding
  * (schema failure, dangling ref) also exits 1 — warn/info findings never do,
- * mirroring how UNVERIFIABLE worlds never do.
+ * mirroring how UNVERIFIABLE roots never do.
  */
 export function doctorExitCode(
   staticSummary: DoctorStaticSummary,

package/src/editor-api.ts

@@ -33,10 +33,22 @@
  */
 
 import { resolveUrl } from '@engine/loader';
+import {
+  assertEditorCompatibility,
+  assertProjectCompatibility,
+  type EditorServerCompatibility,
+  editorServerUnavailableError,
+  isStartupRecovery,
+  missingCompatibilityError,
+  ProjectCompatibilityError,
+} from './editor-compatibility';
 import { getEditorMode } from './editor-mode';
+import type { HarnessChatAction, HarnessChatSnapshot } from './harness-chat-types';
+import { parseHarnessChatSnapshot, unavailableHarnessChatSnapshot } from './harness-chat-types';
 import { getStorageBackend } from './storage';
 
 const BASE = '/__editor';
+const EDITOR_CLIENT_ID = globalThis.crypto?.randomUUID?.() ?? `editor-${Date.now()}`;
 
 /** Browser mode has no Node dev server — every `/__editor/*` op below either
  *  routes through `getStorageBackend()` or degrades explicitly; this helper
@@ -45,6 +57,55 @@ function isBrowserMode(): boolean {
   return getEditorMode() === 'browser';
 }
 
+function parseEditorCompatibility(value: unknown): EditorServerCompatibility | null {
+  if (!value || typeof value !== 'object') return null;
+  const candidate = value as Partial<EditorServerCompatibility>;
+  if (
+    candidate.apiVersion !== 1 ||
+    (typeof candidate.engineVersion !== 'string' && candidate.engineVersion !== null) ||
+    typeof candidate.manifestVersion !== 'number' ||
+    typeof candidate.startedAt !== 'string' ||
+    !candidate.source ||
+    (candidate.source.state !== 'current' && candidate.source.state !== 'restart-required')
+  ) {
+    return null;
+  }
+  if (
+    candidate.source.state === 'restart-required' &&
+    (typeof candidate.source.changedPath !== 'string' ||
+      typeof candidate.source.changedAt !== 'string')
+  ) {
+    return null;
+  }
+  return candidate as EditorServerCompatibility;
+}
+
+/** Read the immutable identity of the local Node process serving this editor. */
+export async function getEditorCompatibility(): Promise<EditorServerCompatibility | null> {
+  if (isBrowserMode()) return null;
+  let res: Response;
+  try {
+    res = await fetch(`${BASE}/compatibility`, { cache: 'no-store' });
+  } catch (error) {
+    throw editorServerUnavailableError(error instanceof Error ? error.message : String(error));
+  }
+  if (res.status >= 500) throw editorServerUnavailableError(`HTTP ${res.status}`);
+  if (!res.ok || !res.headers.get('content-type')?.includes('application/json')) return null;
+  try {
+    return parseEditorCompatibility(await res.json());
+  } catch {
+    return null;
+  }
+}
+
+/** Require a current handshake before any operation that activates a project. */
+export async function requireEditorCompatibility(): Promise<EditorServerCompatibility> {
+  const identity = await getEditorCompatibility();
+  if (!identity) throw missingCompatibilityError();
+  assertEditorCompatibility(identity);
+  return identity;
+}
+
 /**
  * Read a project text file, storage-backend first, then static HTTP fallback.
  *
@@ -71,6 +132,45 @@ export async function readProjectTextFile(path: string): Promise<string | null>
   return null;
 }
 
+/**
+ * Check whether a project file exists WITHOUT reading its content.
+ *
+ * Storage-backend-first (`StorageBackend.exists`, already cheap on every
+ * backend: `HttpStorage.exists` stats via the parent directory LISTING
+ * (`/__editor/assets?dir=`), never a body fetch; OPFS/FSA resolve a handle),
+ * then an HTTP HEAD fallback against the static serving path for anything the
+ * storage layer doesn't know about. Prefer this over
+ * `readProjectTextFile(...) !== null` when only existence is needed — e.g. a
+ * restore-time verification probe — since that reads and discards the whole
+ * body.
+ *
+ * HEAD-support caveat (verified live with `curl -I` against the Vite dev
+ * server): real project files answer HEAD with a genuine Content-Type/
+ * Content-Length, so the fallback IS worth using. However the dev server's
+ * SPA fallback also answers a HEAD/GET for a MISSING path with 200 (it serves
+ * `index.html` rather than 404), so `res.ok` alone cannot fully distinguish
+ * "exists" from "missing" through this fallback path. This is not a new gap —
+ * the prior full-GET-based check had the identical blind spot — and it's only
+ * reached when the storage backend itself doesn't have the file (e.g. a
+ * static-shipped asset not yet materialized in OPFS/FSA); a false positive
+ * here just means a subsequent real open attempt fails through its own error
+ * path instead of at this cheap pre-check.
+ */
+export async function projectFileExists(path: string): Promise<boolean> {
+  const key = path.replace(/^\//, '');
+  try {
+    if (await getStorageBackend().exists(key)) return true;
+  } catch {
+    /* fall through to HTTP */
+  }
+  try {
+    const res = await fetch(resolveUrl(path), { method: 'HEAD' });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
 export interface AssetEntry {
   name: string;
   type: 'file' | 'directory';
@@ -172,7 +272,9 @@ let sharedRefCount = 0;
  */
 export function connectEvents(): EditorEventSource {
   if (!sharedSource) {
-    sharedSource = new EventSource(`${BASE}/events`);
+    sharedSource = new EventSource(
+      `${BASE}/events?clientId=${encodeURIComponent(EDITOR_CLIENT_ID)}`,
+    );
   }
   const real = sharedSource;
   sharedRefCount++;
@@ -207,13 +309,91 @@ export function connectEvents(): EditorEventSource {
   };
 }
 
+/** Fetch the complete project-scoped coding-harness Chat state. The static
+ * hosted editor cannot inspect local processes, so browser mode degrades
+ * honestly while keeping the permanent Chat surface understandable. */
+export async function getHarnessChatSnapshot(): Promise<HarnessChatSnapshot> {
+  if (isBrowserMode()) {
+    return unavailableHarnessChatSnapshot(
+      'Local coding sessions are available when this project is opened with `vgai edit`.',
+    );
+  }
+  try {
+    const res = await fetch(`${BASE}/harness-chat`);
+    if (!res.ok) {
+      const body = (await res.json().catch(() => null)) as { error?: string } | null;
+      return unavailableHarnessChatSnapshot(body?.error ?? 'Harness Chat is unavailable.');
+    }
+    return parseHarnessChatSnapshot(await res.json());
+  } catch (error) {
+    return unavailableHarnessChatSnapshot(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/** Perform one explicit Chat mutation. Collapsing the panel deliberately
+ * does not call this API: presentation cannot attach, detach, or hand off
+ * session control. */
+export async function performHarnessChatAction(
+  action: HarnessChatAction,
+): Promise<HarnessChatSnapshot> {
+  if (isBrowserMode()) {
+    throw new Error('Local coding sessions require the Node editor opened by `vgai edit`.');
+  }
+  const res = await fetch(`${BASE}/harness-chat/action`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(action),
+  });
+  const body = (await res.json()) as {
+    error?: string;
+    snapshot?: HarnessChatSnapshot;
+  } & Partial<HarnessChatSnapshot>;
+  if (!res.ok) {
+    throw new HarnessChatRequestError(
+      body.error ?? 'Harness Chat action failed.',
+      body.snapshot ?? null,
+    );
+  }
+  return parseHarnessChatSnapshot(body);
+}
+
+export class HarnessChatRequestError extends Error {
+  constructor(
+    message: string,
+    readonly snapshot: HarnessChatSnapshot | null,
+  ) {
+    super(message);
+    this.name = 'HarnessChatRequestError';
+  }
+}
+
+/** Subscribe through the editor's one shared EventSource. */
+export function connectHarnessChatEvents(
+  onSnapshot: (snapshot: HarnessChatSnapshot) => void,
+): () => void {
+  if (isBrowserMode()) return () => {};
+  const events = connectEvents();
+  const listener = (event: MessageEvent) => {
+    try {
+      onSnapshot(parseHarnessChatSnapshot(JSON.parse(event.data as string)));
+    } catch {
+      /* A malformed optional update cannot break the rest of the editor. */
+    }
+  };
+  events.addEventListener('harness-chat', listener);
+  return () => {
+    events.removeEventListener('harness-chat', listener);
+    events.close();
+  };
+}
+
 /** 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),
+      body: JSON.stringify({ ...state, _clientId: EDITOR_CLIENT_ID }),
     });
   } catch {
     /* best-effort */
@@ -222,8 +402,10 @@ export async function reportEditorState(state: Record<string, unknown>): Promise
 
 /** 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. */
+ *  (e.g. `capture-viewport`'s base64 PNG, the Wave 5 debug-seam reads) —
+ *  forwarded verbatim through `/__editor/command-result` →
+ *  `commandResponseFor` → the SDK transports, on the failure path too (where
+ *  it carries structured `{ code: ... }` markers). */
 export async function reportCommandResult(
   requestId: string,
   ok: boolean,
@@ -289,7 +471,7 @@ export async function listExamples(): Promise<ExampleInfo[]> {
 export async function createProject(
   name: string,
   location: string,
-  template: 'starter' | 'empty' | 'example',
+  template: 'default' | '2d' | 'react' | 'example',
   exampleId?: string,
 ): Promise<{ ok: boolean; path?: string; config?: { name: string }; error?: string }> {
   if (isBrowserMode()) {
@@ -370,7 +552,13 @@ export async function saveThumbnail(dataUrl: string): Promise<boolean> {
 /** Query the server for the currently active project (if any). */
 export async function getCurrentServerProject(): Promise<{
   path: string;
-  config: { name: string };
+  config: {
+    manifestVersion: 2;
+    name: string;
+    version: string;
+    engine: { version: string };
+    [key: string]: unknown;
+  };
   /** 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
@@ -387,7 +575,13 @@ export async function getCurrentServerProject(): Promise<{
     const data = (await res.json()) as {
       project: {
         path: string;
-        config: { name: string };
+        config: {
+          manifestVersion: 2;
+          name: string;
+          version: string;
+          engine: { version: string };
+          [key: string]: unknown;
+        };
         hasUiRegistry?: boolean;
         packaged?: boolean;
       } | null;
@@ -399,21 +593,56 @@ export async function getCurrentServerProject(): Promise<{
 }
 
 /** Open/switch to a project by its filesystem path. */
-export async function openProjectOnServer(
-  projectPath: string,
-): Promise<{ ok: boolean; config?: { name: string } }> {
+export async function openProjectOnServer(projectPath: string): Promise<{
+  ok: boolean;
+  config?: {
+    manifestVersion: 2;
+    name: string;
+    version: string;
+    engine: { version: string };
+    [key: string]: unknown;
+  };
+}> {
   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 compatibility = await requireEditorCompatibility();
   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 } };
+  let payload: unknown;
+  try {
+    payload = await res.json();
+  } catch {
+    throw editorServerUnavailableError(`HTTP ${res.status} returned an invalid response`);
+  }
+  if (!res.ok) {
+    if (payload && typeof payload === 'object') {
+      const failure = payload as Record<string, unknown>;
+      if (typeof failure['error'] === 'string' && isStartupRecovery(failure['recovery'])) {
+        throw new ProjectCompatibilityError(failure['error'], failure['recovery']);
+      }
+      if (typeof failure['error'] === 'string') throw new Error(failure['error']);
+    }
+    throw new Error(`Could not open project at ${projectPath}: HTTP ${res.status}`);
+  }
+  const result = payload as {
+    ok: boolean;
+    config?: {
+      manifestVersion: 2;
+      name: string;
+      version: string;
+      engine: { version: string };
+      [key: string]: unknown;
+    };
+  };
+  if (result.config) assertProjectCompatibility(result.config, compatibility);
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -475,6 +704,12 @@ export interface LogEntry {
   sub?: string;
   msg: string;
   meta?: Record<string, unknown>;
+  /** Engine fixed-step counter at write time (SYNTHETIC-PLAYER-SPEC §3.3) —
+   *  present only while a live play session's debug seam can be read, so
+   *  entries correlate frame-exactly with `ctx.debug.emit` events. */
+  tick?: number;
+  /** Accumulated sim-seconds at write time — same source as `tick`. */
+  simT?: number;
 }
 
 /** Start a new log session. Returns the filename, or null on failure. Always
@@ -539,8 +774,8 @@ export async function flushLogEntries(entries: LogEntry[]): Promise<boolean> {
 // 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
+// `StorageBackend` — there is no browser-mode equivalent. The server-only
+// Asset Library navigator is unavailable 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.
@@ -559,6 +794,20 @@ export interface OnlineAsset {
   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 {
@@ -569,31 +818,31 @@ export interface AssetFileOption {
   includes?: { relativePath: string; url: string; size: number }[];
 }
 
+export interface OnlineAssetPreview {
+  path: string;
+  format: string;
+  label: string;
+  sourceAssetId: string;
+  materialPath?: string;
+}
+
 // ---------------------------------------------------------------------------
-// Downloaded-asset cache (client-side, keyed by "source:slug")
+// Downloaded-asset cache (client-side, keyed by exact provider identity)
 // ---------------------------------------------------------------------------
 
-/** Maps "source:slug" → local serving path (e.g. "/asset-library/polyhaven/arm-chair-01/..."). */
+/** 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>();
 
-/** 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)}`;
+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, nameOrId: string): string | null {
-  return downloadedAssetPaths.get(assetCacheKey(source, nameOrId)) ?? 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. */
@@ -610,10 +859,10 @@ export async function loadDownloadedAssets(): Promise<void> {
     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 }[];
+      downloaded: { source: string; id: string; path: string }[];
     };
     for (const entry of data.downloaded) {
-      downloadedAssetPaths.set(`${entry.source}:${entry.slug}`, `/${entry.path}`);
+      downloadedAssetPaths.set(assetCacheKey(entry.source, entry.id), `/${entry.path}`);
     }
     for (const cb of downloadListeners) cb();
   } catch {
@@ -649,11 +898,26 @@ export async function getOnlineAssetFiles(source: string, id: string): Promise<A
   if (isBrowserMode()) return [];
   const qs = new URLSearchParams({ source, id });
   const res = await fetch(`${BASE}/asset-library/files?${qs}`);
-  if (!res.ok) return [];
+  if (!res.ok) {
+    const body = (await res.json().catch(() => null)) as { error?: string } | null;
+    throw new Error(body?.error ?? `Asset delivery lookup failed (${res.status}).`);
+  }
   const data = (await res.json()) as { files: AssetFileOption[] };
   return data.files;
 }
 
+/** Resolve a read-only Asset Lab model from the editor's catalog cache. */
+export async function getOnlineAssetPreview(
+  source: string,
+  id: string,
+): Promise<OnlineAssetPreview | null> {
+  if (isBrowserMode()) return null;
+  const qs = new URLSearchParams({ source, id });
+  const res = await fetch(`${BASE}/asset-library/preview?${qs}`);
+  if (!res.ok) return null;
+  return (await res.json()) as OnlineAssetPreview;
+}
+
 /** Download an online asset into the project's public/asset-library/ folder. */
 export async function downloadOnlineAsset(params: {
   source: string;
@@ -682,7 +946,7 @@ export async function downloadOnlineAsset(params: {
   };
   // Cache the local path on success
   if (result.ok && result.path) {
-    downloadedAssetPaths.set(assetCacheKey(params.source, params.name), `/${result.path}`);
+    downloadedAssetPaths.set(assetCacheKey(params.source, params.id), `/${result.path}`);
     for (const cb of downloadListeners) cb();
   }
   return result;