@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/manifest-project.ts

@@ -0,0 +1,107 @@
+/**
+ * Manifest-backed project detection for the play path — T3.3 slice 2 part C.
+ *
+ * The dev server serves the project's RAW `volter.project.json` at `/volter.project.json`
+ * (editor-server.ts's project-file-serving middleware, mirroring how it
+ * with no view synthesis — the browser parses it itself through the PURE half
+ * of the manifest loader (`loadGameManifest`,
+ * `@volter/project/manifest/load`), never `load-file.ts` (that needs `node:fs`, which
+ * has no place in a browser bundle).
+ */
+
+import { MANIFEST_FILENAME } from '@volter/project/manifest/filename';
+import { loadGameManifest, type ResolvedGameManifest } from '@volter/project/manifest/load';
+import { servedUrl } from '@volter/sdk/kit/served-url';
+
+/**
+ * "This project has no manifest" — a DIFFERENT answer from "this project's
+ * manifest could not be read", and the reason {@link fetchGameManifest} needs
+ * two rejections rather than one.
+ *
+ * A caller that cannot tell them apart has only one safe move: swallow both.
+ * `ingest/mount-ingest-root.ts`'s three manifest routes did exactly that
+ * (`.catch(() => null)` each), so a project declaring a perfectly good
+ * `{ ingest }` root in a manifest the strict loader REJECTED — one
+ * unrecognized key is enough, the schema is `.strict()` — was declined by
+ * every route and mounted NOTHING, with not one line anywhere saying why.
+ *
+ * Recognized by `name`, not `instanceof`: this classification must survive a
+ * caller holding a different module instance of this file, and a wrong answer
+ * there is a silent mount, not a loud one.
+ */
+export const MANIFEST_ABSENT_ERROR_NAME = 'ManifestAbsentError';
+
+/** True for the rejection {@link fetchGameManifest} uses to say "no manifest
+ *  here" — see {@link MANIFEST_ABSENT_ERROR_NAME}. */
+export function isManifestAbsence(error: unknown): boolean {
+  return error instanceof Error && error.name === MANIFEST_ABSENT_ERROR_NAME;
+}
+
+function manifestAbsent(where: string): Error {
+  const error = new Error(`${where} declares no ${MANIFEST_FILENAME}`);
+  error.name = MANIFEST_ABSENT_ERROR_NAME;
+  return error;
+}
+
+/**
+ * Fetch + parse the current project's sole v2 config from the session that
+ * serves it. Both failures are loud; ABSENCE is the one that is also
+ * classifiable ({@link isManifestAbsence}).
+ */
+export async function fetchGameManifest(): Promise<ResolvedGameManifest> {
+  const url = servedUrl('/volter.project.json');
+  const res = await fetch(url);
+  if (res.status === 404) throw manifestAbsent(url);
+  if (!res.ok) throw new Error(`Failed to load ${url}: ${res.status} ${res.statusText}`);
+  // A 404 is not the only way this route says "no manifest": a dev server with
+  // an SPA fallback answers an unknown path with index.html and a 200, which
+  // `res.json()` reports as `Unexpected token '<'` — an unreadable manifest,
+  // when the truth is that there is none. `fetchRawGameManifest` below has
+  // made the same distinction the same way since it was written.
+  const body = await res.text();
+  if (/^\s*</.test(body)) throw manifestAbsent(url);
+  try {
+    return loadGameManifest(JSON.parse(body), { configurationKinds: 'defer' });
+  } catch (error) {
+    throw new Error(
+      `Failed to load ${url}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/**
+ * A1 (edit mode, defect 2): fetch the RAW, UN-validated `volter.project.json` JSON
+ * — or `null` when the project genuinely has none (the route 404s). Unlike
+ * {@link fetchGameManifest}, this NEVER throws on a schema violation: edit mode
+ * must tolerate a manifest with ONE bad world (e.g. an unknown `kind`) by
+ * surfacing that world as an error node (#18) while the VALID roots declared
+ * alongside it still open — strict `loadGameManifest` would reject the whole
+ * file and make every declared world vanish. The caller (`edit-mode-authoring
+ * .ts`) reads `roots[]` leniently; a genuinely absent manifest (this returns
+ * `null`) is the only case that synthesizes a single-world game.
+ */
+export async function fetchRawGameManifest(): Promise<unknown | null> {
+  const url = servedUrl('/volter.project.json');
+  const res = await fetch(url);
+  if (!res.ok) return null;
+  // A 404 is not the only way this route says "no manifest". A dev server with
+  // an SPA fallback answers an unknown path with index.html and a **200**, so
+  // `res.ok` passes and `res.json()` throws `Unexpected token '<', "<!DOCTYPE
+  // "... is not valid JSON` — from a function whose whole contract is to return
+  // `null` when there is no manifest. That throw escapes into callers that
+  // only ever guarded against `null`: it aborted `tryManifestIngestRoute2D`
+  // before it could look at the roots at all, so a perfectly well-formed
+  // `{ ingest }` world silently fell through to the default-pixi path and
+  // failed to mount, reporting the JSON error as the mount's cause with no
+  // hint of which fetch produced it.
+  const body = await res.text();
+  if (/^\s*</.test(body)) return null; // HTML fallback === no manifest here
+  try {
+    return JSON.parse(body) as unknown;
+  } catch (error) {
+    // A genuinely malformed manifest is NOT absence — say so, and say where.
+    throw new Error(
+      `${url} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/kit/module-fetch-diagnosis.ts

@@ -0,0 +1,192 @@
+/**
+ * WHICH MODULE A FAILED DYNAMIC IMPORT COULD NOT LOAD. The browser reports any
+ * failure anywhere in an imported module's graph as the top module alone
+ * ("Failed to fetch dynamically imported module: <entry>"), so a world whose
+ * entry serves fine but whose graph holds one refused file reads as a broken
+ * entry. This walks the entry's STATIC import graph with the page's own `fetch`
+ * and names the first module that does not answer 200 with a script type.
+ *
+ * When every file answers, the failure is the loader's memory: a module that
+ * failed once stays failed for the document, whatever the network says now. The
+ * walk then imports the graph in dependency order (a module only after all it
+ * imports) and stops at the first refusal, which is therefore the module that
+ * failed itself rather than one that inherited a dependency's failure; that
+ * module's own network attempts are reported with their bytes over the wire (0
+ * means the browser answered from its cache without asking). The probe only runs
+ * after a failure and imports only the static graph the failed import was
+ * already evaluating; `import()` edges are not followed.
+ *
+ * Walks running together share one request per URL and at most
+ * {@link MAX_DIAGNOSES} run at once, so a shared dependency failing under many
+ * stories costs one walk's requests. Nothing is kept once the walks finish: a
+ * later failure of the same entry is walked afresh.
+ */
+
+const FAILED_IMPORT = [
+  /Failed to fetch dynamically imported module: (\S+)/, // Chromium
+  /error loading dynamically imported module: (\S+)/, // Firefox
+];
+/** Static edges only: `import … from`, `import "…"`, `export … from`. */
+const SPECIFIER =
+  /(?:\bimport\s*(?:[\w*{}\s,$]+\s*from\s*)?|\bexport\s*[\w*{}\s,$]+\s*from\s*)["']((?:\/|\.\.?\/)[^"']+)["']/g;
+const LIMIT = 400;
+const MAX_DIAGNOSES = 5;
+
+// The browser keeps 250 resource timings by default and a project boot issues more requests than
+// that, so the first attempt at a module (the one the loader remembers) would already be dropped
+// by the time a failure asks for it.
+if (typeof performance !== 'undefined' && typeof performance.setResourceTimingBufferSize === 'function') {
+  performance.setResourceTimingBufferSize(5_000);
+}
+
+export interface ModuleFetchDiagnosis {
+  readonly entry: string;
+  readonly fetched: number;
+  /** The first module that did not load, or `null` when every one loads now. */
+  readonly failed: {
+    readonly url: string;
+    /** The network's answer; `null` when the network answered and the loader refused. */
+    readonly status: number | null;
+    readonly detail: string;
+  } | null;
+}
+
+/** The entry named by a failed dynamic import's message, or `null` for any other error. */
+export function failedImportEntry(message: string): string | null {
+  for (const pattern of FAILED_IMPORT) {
+    const entry = pattern.exec(message)?.[1];
+    if (entry) return entry;
+  }
+  return null;
+}
+
+interface FetchedModule {
+  readonly status: number;
+  readonly type: string;
+  readonly imports: readonly string[];
+}
+
+/** Requests shared by the walks in flight; cleared when the last one settles. */
+const fetchedModules = new Map<string, Promise<FetchedModule>>();
+/** The walks in flight, by entry. */
+const diagnoses = new Map<string, Promise<ModuleFetchDiagnosis>>();
+
+function fetchModule(url: string): Promise<FetchedModule> {
+  let pending = fetchedModules.get(url);
+  if (!pending) {
+    pending = (async () => {
+      const response = await fetch(url, { cache: 'no-store' });
+      const type = response.headers.get('content-type') ?? '';
+      if (!response.ok || !/javascript|ecmascript/.test(type)) return { status: response.status, type, imports: [] };
+      const body = await response.text();
+      const imports = new Set<string>();
+      for (const match of body.matchAll(SPECIFIER)) {
+        const specifier = match[1]!;
+        // A served import carries an extension, a query or Vite's `/@` prefix (`/@id/…` virtual
+        // modules); a bare relative name is text in a string or comment, not an edge.
+        if (!/\.[a-z]+(?:[?#]|$)|\?|^\/@/i.test(specifier)) continue;
+        imports.add(new URL(specifier, url).href);
+      }
+      return { status: response.status, type, imports: [...imports] };
+    })();
+    fetchedModules.set(url, pending);
+  }
+  return pending;
+}
+
+/** Diagnose a failed import of `entry`; never rejects. */
+export function diagnoseModuleFetch(entry: string): Promise<ModuleFetchDiagnosis> {
+  const existing = diagnoses.get(entry);
+  if (existing) return existing;
+  if (diagnoses.size >= MAX_DIAGNOSES) {
+    return Promise.resolve({
+      entry,
+      fetched: 0,
+      failed: { url: entry, status: null, detail: `not walked: ${MAX_DIAGNOSES} other failed imports are being walked` },
+    });
+  }
+  const pending = walk(entry)
+    .catch(
+      (err): ModuleFetchDiagnosis => ({
+        entry,
+        fetched: 0,
+        failed: { url: entry, status: null, detail: `walk failed: ${String(err)}` },
+      }),
+    )
+    .finally(() => {
+      diagnoses.delete(entry);
+      if (diagnoses.size === 0) fetchedModules.clear();
+    });
+  diagnoses.set(entry, pending);
+  return pending;
+}
+
+async function walk(entry: string): Promise<ModuleFetchDiagnosis> {
+  const root = new URL(entry, location.href).href;
+  const edges = new Map<string, readonly string[]>();
+  const queue = [root];
+  while (queue.length > 0 && edges.size < LIMIT) {
+    const url = queue.shift()!;
+    if (edges.has(url)) continue;
+    let fetched: FetchedModule;
+    try {
+      fetched = await fetchModule(url);
+    } catch (err) {
+      return { entry, fetched: edges.size + 1, failed: { url, status: 0, detail: String(err) } };
+    }
+    if (fetched.status !== 200 || !/javascript|ecmascript/.test(fetched.type)) {
+      return {
+        entry,
+        fetched: edges.size + 1,
+        failed: { url, status: fetched.status, detail: fetched.type || '(no content type)' },
+      };
+    }
+    edges.set(url, fetched.imports);
+    for (const next of fetched.imports) if (!edges.has(next)) queue.push(next);
+  }
+
+  // Dependency order: a module after everything it imports (post-order from the entry).
+  const order: string[] = [];
+  const visited = new Set<string>();
+  const visit = (url: string): void => {
+    if (visited.has(url) || !edges.has(url)) return;
+    visited.add(url);
+    for (const next of edges.get(url)!) visit(next);
+    order.push(url);
+  };
+  visit(root);
+
+  for (const url of order) {
+    try {
+      await import(/* @vite-ignore */ url);
+    } catch (err) {
+      const attempts = performance
+        .getEntriesByType('resource')
+        .filter((timing): timing is PerformanceResourceTiming => timing.name === url)
+        .map(
+          (timing) =>
+            `${'responseStatus' in timing ? timing.responseStatus : '?'} ` +
+            `(${timing.transferSize}B over the wire, ${timing.initiatorType}) at ${Math.round(timing.startTime)}ms`,
+        );
+      return {
+        entry,
+        fetched: edges.size,
+        failed: {
+          url,
+          status: null,
+          detail:
+            `every module it imports loads and the network serves it, but the loader refused it (${String(err)}); ` +
+            `its attempts on this page: ${attempts.join(' | ') || 'none kept'}`,
+        },
+      };
+    }
+  }
+  return { entry, fetched: edges.size, failed: null };
+}
+
+export function describeModuleFetch(diagnosis: ModuleFetchDiagnosis): string {
+  const { failed } = diagnosis;
+  if (!failed) return `all ${diagnosis.fetched} modules from ${diagnosis.entry} fetch and import from the page now`;
+  const answer = failed.status === null ? '' : ` answered ${failed.status}`;
+  return `module ${failed.url}${answer}: ${failed.detail} (walking ${diagnosis.fetched} modules from ${diagnosis.entry})`;
+}

package/src/kit/mount-failure-report.ts

@@ -0,0 +1,154 @@
+/**
+ * Mount-failure report — D-W3: every manifest world's auto-launch route
+ * degrades to exactly one `editorConsole.error` line today (§0.4 — ground
+ * truth: the default Untitled scene is already showing by the time a manifest
+ * route fails, so a broken world mounts to what LOOKS like a normal empty
+ * project). This module is the structured half of the fix: a global mount-
+ * failure slot every manifest-route catch block populates.
+ *
+ * WHERE IT SHOWS — there is ONE error home, the editor's bottom surface, and
+ * this slot rides it rather than owning a surface of its own:
+ *
+ *   1. the `editorConsole.error` line each route already writes (the full
+ *      trace lives there, and the status bar's `console-counts` counts it);
+ *   2. the status bar's `mount-failure` contribution
+ *      (`../components/status-contributions.tsx`) — a sticky, danger-toned
+ *      "N worlds failed to mount" item that names each world in its title and
+ *      opens the Console on click. Sticky is the point: a dead world stays
+ *      dead until it is fixed, so unlike a transient hint this item persists
+ *      until the slot clears;
+ *   3. the Console utility is REVEALED on the empty→failing edge
+ *      (`../workspace-utility-commands.ts`'s auto-open policy, the same one a
+ *      failed build uses) — that reveal is what makes a mount failure loud
+ *      without a second surface, and it is why the Console not being the
+ *      default bottom tab is no longer an argument for one.
+ *
+ * A separate top-of-shell banner used to render this slot. It was a SECOND
+ * error home — users had to learn two places to look — and it is gone.
+ *
+ * D-V5 (composite): a composite manifest (one ingest world + siblings,
+ * `ingest-siblings.ts`) can fail SEVERAL roots independently in one mount
+ * attempt (a `default-three` sibling, a throwing `default-react` sibling, …)
+ * — a single-slot "last failure wins" model would silently drop every failure
+ * but the latest, the exact F9 anti-pattern this module exists to close. The
+ * slot is an ORDERED LIST: `addMountFailureReport` (deduped by `worldId` — a
+ * re-attempt for the SAME world replaces that world's entry in place, keeping
+ * list order stable), `getMountFailureReports()`,
+ * `clearMountFailureReports()`.
+ *
+ * The slot owns its own `subscribe` (same shape as
+ * `../asset-workflow/asset-materialization-report.ts`) rather than
+ * piggybacking on `EditorShellStore.subscribe`: the readers are no longer
+ * mounted inside a store-subscribed panel, and the per-world clears
+ * (`clearMountFailureReport`) run from root-level lifecycles that do not all
+ * broadcast a store notification. `getMountFailureReports()` returns a frozen
+ * snapshot whose identity changes only when the list does, so it is a valid
+ * `useSyncExternalStore` getSnapshot.
+ */
+
+/** One manifest world's mount failure — the exact fields the status item shows. */
+export interface MountFailureReport {
+  /** The failing world's manifest id (`ResolvedAdapterRoot.id`), or the
+   *  vendored/fixture route's discovered game/folder id. */
+  readonly worldId: string;
+  /** The world's render substrate kind (`ResolvedAdapterRoot.kind`, e.g.
+   *  `'three'`/`'canvas'`/`'react'`) — or, for the URL-fallback route
+   *  (which has no `ResolvedAdapterRoot` to read a kind from), the same
+   *  vocabulary inferred from which fixture glob resolved the id. */
+  readonly kind: string;
+  /** The resolved adapter identity (`ResolvedAdapter['identity']` — e.g.
+   *  `'ingest-three'`/`'ingest-pixi'`/`'ingest-react'`/`'module'`). */
+  readonly identity: string;
+  /** The caught error's message — never the raw `Error` object (never
+   *  fabricated; empty only if the thrown value truly stringifies empty). */
+  readonly message: string;
+}
+
+/** D-V5: an ORDERED list now backs the slot (insertion order — the order
+ *  roots actually failed in, which for a composite's sibling loop is
+ *  manifest order). Every accessor below is a thin view over this same
+ *  array — never a second, parallel source of truth. Replaced wholesale
+ *  rather than mutated so the snapshot identity is a real change signal. */
+let _reports: readonly MountFailureReport[] = [];
+const _listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const listener of _listeners) listener();
+}
+
+/** `useSyncExternalStore`-compatible subscribe for the status contribution
+ *  and the Console auto-open policy. */
+export function subscribeToMountFailures(callback: () => void): () => void {
+  _listeners.add(callback);
+  return () => {
+    _listeners.delete(callback);
+  };
+}
+
+/**
+ * D-V5: append one world's failure, deduped by `worldId` — a re-attempt for
+ * a world that already has an entry REPLACES it in place (keeps list order
+ * stable: retrying world B in `[A, B]` yields `[A, B']`, never `[A, B]` moved
+ * to the end).
+ */
+export function addMountFailureReport(report: MountFailureReport): void {
+  const index = _reports.findIndex((r) => r.worldId === report.worldId);
+  if (index === -1) {
+    _reports = [..._reports, report];
+  } else {
+    const next = [..._reports];
+    next[index] = report;
+    _reports = next;
+  }
+  notify();
+}
+
+/** D-V5: every mount failure from the current attempt, oldest first. */
+export function getMountFailureReports(): readonly MountFailureReport[] {
+  return _reports;
+}
+
+/** Drop every recorded failure — what a successful mount (or a torn-down
+ *  session, which has nothing left to report) calls. */
+export function clearMountFailureReports(): void {
+  if (_reports.length === 0) return;
+  _reports = [];
+  notify();
+}
+
+/**
+ * PD-1: drop ONE world's recorded failure — what a route that mounts a single
+ * world calls after that world mounts successfully.
+ *
+ * `clearMountFailureReports()` above is the whole-attempt reset an ingest/
+ * module route can afford because it owns the entire mount. The R3F design
+ * session and the design-time layer loop do NOT: they mount roots
+ * independently, so a blanket clear on one root's success would erase a
+ * SIBLING root's still-true failure — the exact D-V5 drop the ordered list
+ * exists to prevent. Keyed by the same `worldId` `addMountFailureReport`
+ * dedupes on, and a no-op when that world has no entry.
+ *
+ * Not clearing at all is what PD-1 measured: an R3F world that failed to mount
+ * once kept reporting that failure through the editor's `status` command's "MOUNT FAILED —
+ * THIS WORLD IS NOT RUNNING" line (and the in-editor surface) for the rest of
+ * the page's life, including while the very same world was mounted and
+ * PLAYING. A diagnostic that cannot go back to healthy is worse than none.
+ */
+export function clearMountFailureReport(worldId: string): void {
+  const index = _reports.findIndex((r) => r.worldId === worldId);
+  if (index === -1) return;
+  _reports = _reports.filter((_, i) => i !== index);
+  notify();
+}
+
+/**
+ * Build a `MountFailureReport['message']` from a caught value the same way
+ * every route's existing `editorConsole.error` line already stringifies it
+ * (`` `...failed: ${err}` `` — kept byte-for-byte at each call site so the
+ * console's full trace is unchanged) — an `Error`'s own `.message` reads
+ * better in a one-line summary than its `String(err)` form (`"Error: <msg>"`),
+ * so the report uses this instead of the console's template-literal form.
+ */
+export function formatMountFailureMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}