@volter/editor-core 0.5.57

package/src/project-asset-refresh.ts

@@ -0,0 +1,26 @@
+/** Parsed asset caches outlive R3F mounts. Invalidate before asking a document
+ * to reload, so replacing a GLB updates every placement without editing JSX.
+ */
+export async function evictLoaderCaches(paths: readonly string[]): Promise<void> {
+  if (!paths.length) return;
+  const { useGLTF, useTexture } = await import('@react-three/drei');
+  for (const path of paths) {
+    useGLTF.clear(path);
+    useTexture.clear(path);
+  }
+}
+
+export function announceAssetReload(paths: readonly string[]): void {
+  if (
+    typeof window === 'undefined' ||
+    !paths.some((path) => /\.(glb|gltf|png|jpe?g|webp|avif)$/i.test(path))
+  )
+    return;
+  window.dispatchEvent(new CustomEvent('editor:asset-loaders-changed'));
+}
+
+export function onAssetReload(listener: () => void): () => void {
+  if (typeof window === 'undefined') return () => {};
+  window.addEventListener('editor:asset-loaders-changed', listener);
+  return () => window.removeEventListener('editor:asset-loaders-changed', listener);
+}

package/src/project-declaration-refresh.ts

@@ -0,0 +1,31 @@
+import { assignActiveProject, getCurrentProject, type ProjectConfig } from './active-project';
+import { connectProjectDeclarationEvents } from './asset-events';
+import { probeCurrentServerProject } from './editor-api';
+
+/** Refresh declarations in the current session without reopening its project. */
+export function startProjectDeclarationRefresh(): () => void {
+  let revision = 0;
+  const refresh = async (): Promise<void> => {
+    const request = ++revision;
+    const project = getCurrentProject();
+    if (!project) return;
+    try {
+      const probe = await probeCurrentServerProject();
+      // Invalid intermediate saves retain the last valid configuration;
+      // validate-on-save owns their diagnostics.
+      if (probe.status !== 'project' || probe.project.path !== project.rootPath) return;
+      const config: ProjectConfig = probe.project.config as ProjectConfig;
+      if (request !== revision || getCurrentProject() !== project) return;
+      assignActiveProject({ ...project, config });
+    } catch (error) {
+      if (request === revision && getCurrentProject() === project) {
+        console.error('[project] Could not refresh project declarations:', error);
+      }
+    }
+  };
+  const stop = connectProjectDeclarationEvents(() => void refresh());
+  return () => {
+    revision++;
+    stop();
+  };
+}

package/src/project-local-state.ts

@@ -0,0 +1,118 @@
+/**
+ * THE PROJECT-LOCAL SETTINGS LAYER — one in-memory document mirroring
+ * `.vgai/editor-state.json`, the git-ignored file the scaffold already
+ * reserves for "editor autosaved UI state" (ARCHITECTURE-CORE §Editor chrome,
+ * "Settings have four layers with named homes").
+ *
+ * Every piece of per-user, per-checkout state — the workspace layouts, the
+ * active workspace, the open documents, the view state the shell store
+ * autosaves — is a SECTION of this one document, loaded ONCE when a project
+ * becomes active and written back debounced through `saveEditorState`, the
+ * editor server's own route. One document, one writer, so two sections can
+ * never clobber each other through the whole-file route.
+ *
+ * Keyed by the folder itself: a rename, another browser or another checkout
+ * of the same folder finds the same file. Browser storage keyed by an
+ * absolute path was the previous home, and it lost a layout to exactly those
+ * three moves (measured 2026-09-04).
+ */
+
+import { activeProjectKey, getCurrentProject, onProjectChange } from './active-project';
+import { loadEditorState, saveEditorState } from './editor-api';
+import { preloadSettings } from './settings-store';
+
+type Sections = Record<string, unknown>;
+
+const WRITE_DEBOUNCE_MS = 400;
+
+let loadedFor: string | null = null;
+let loading: Promise<void> | null = null;
+let doc: Sections = {};
+let dirty = false;
+let timer: ReturnType<typeof setTimeout> | null = null;
+
+function projectKey(): string {
+  return activeProjectKey();
+}
+
+/**
+ * Load the active project's local document, once per project. Idempotent and
+ * memoized: the second caller for the same project joins the first load, and
+ * a different project starts over. Callers that read synchronously through
+ * {@link projectLocalSection} await this first.
+ */
+export function preloadProjectLocalState(): Promise<void> {
+  const key = projectKey();
+  if (loadedFor === key) return Promise.resolve();
+  // A load in flight for ANOTHER project (the boot's unscoped one, or a
+  // project switched away from mid-load) settles for that project; this
+  // caller's project loads after it, never joins it.
+  if (loading) return loading.then(() => preloadProjectLocalState());
+  loading = Promise.all([loadEditorState(), preloadSettings()])
+    .then(([state]) => {
+      doc = state && typeof state === 'object' ? { ...state } : {};
+      loadedFor = key;
+    })
+    .catch(() => {
+      doc = {};
+      loadedFor = key;
+    })
+    .finally(() => {
+      loading = null;
+    });
+  return loading;
+}
+
+/** True once the active project's document has loaded. */
+export function projectLocalStateReady(): boolean {
+  return loadedFor === projectKey();
+}
+
+/** One section of the loaded document, or `undefined` before load or when
+ *  the project has never written it. Synchronous by design: the boot awaits
+ *  {@link preloadProjectLocalState} before anything reads. */
+export function projectLocalSection<T>(name: string): T | undefined {
+  if (!projectLocalStateReady()) return undefined;
+  return doc[name] as T | undefined;
+}
+
+function flush(): void {
+  if (timer !== null) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  if (!dirty) return;
+  dirty = false;
+  void saveEditorState(doc);
+}
+
+/** Replace one section and schedule the write. A write before the load has
+ *  settled is applied on top of what loads, so a fast first edit is kept. */
+export function writeProjectLocalSection(name: string, value: unknown): void {
+  const apply = () => {
+    doc = { ...doc, [name]: value };
+    dirty = true;
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(flush, WRITE_DEBOUNCE_MS);
+  };
+  if (projectLocalStateReady()) apply();
+  else void preloadProjectLocalState().then(apply);
+}
+
+/** Write what is pending NOW — the page is leaving. */
+export function flushProjectLocalState(): void {
+  flush();
+}
+
+// The layer loads the moment a project becomes active, so the dock that
+// mounts next reads its layout from the folder, not defaults. This module is
+// imported by the shell's boot (`EditorContext`), which is what makes the
+// subscription exist before the first project activates; `active-project.ts`
+// imports nothing of it, so a bounded host's closure stays as it was.
+onProjectChange(() => {
+  if (getCurrentProject()) void preloadProjectLocalState();
+});
+
+if (typeof window !== 'undefined') {
+  window.addEventListener('pagehide', flushProjectLocalState);
+}

package/src/project-manager.ts

@@ -0,0 +1,243 @@
+/**
+ * Project manager — manages the active game project.
+ *
+ * How the editor learns which project is open depends on the surface, and the
+ * split is the whole point:
+ *
+ *  - LOCAL (server-backed) — it ASKS the server. The editor server holds
+ *    "which project is open" as session state, re-rooted live by
+ *    `POST /__editor/open-project` (the project browser, `vgai edit <path>`).
+ *    The URL carries no project identity at all, so a
+ *    refresh or a tab-heal navigation back to the bare origin lands in the
+ *    same project — a VS Code window, not a deep link. A `?project=` on a
+ *    local URL is a loud boot error (`assertNoRemovedBootParams`).
+ *
+ * Sibling deep-link param (the §6 contract):
+ * `?create-from=<templateOrExampleId>` — handled at AppRoot's routing layer,
+ * NOT here. When no explicit project target wins, it opens the
+ * hub's New Project wizard with that template/example preselected and the name
+ * field focused (invalid ids degrade to the default selection plus a
+ * non-blocking notice). An explicit project target always takes precedence.
+ *
+ * Boot precedence (§5/FT-7, unit G5) is decided by `boot-routing.ts`'s pure
+ * `resolveBootTarget` and merely EXECUTED here: explicit target → opted-in
+ * reopen-last → hub. `?hub=1` forces the hub, and a reopen-last project that
+ * fails to open falls back to the hub rather than trapping the user.
+ */
+
+import { assertProjectCompatibility } from '@volter/editor-sdk/session/editor-compatibility';
+import { hasRootOnSurface } from '@volter/editor-project/adapter/manifest-interpreter';
+import { loadGameManifest } from '@volter/editor-project/manifest/load';
+import { type ActiveProject, assignActiveProject, type ProjectConfig } from './active-project';
+import {
+  assertNoRemovedBootParams,
+  decideServerProjectBoot,
+  describeServerProjectFailure,
+  hubRequestedFromSearch,
+  resolveBootTarget,
+  ServerProjectDetectionError,
+} from './boot-routing';
+import {
+  getLauncherSettings,
+  listRecentProjects,
+  probeCurrentServerProject,
+  requireEditorCompatibility,
+} from './editor-api';
+import { parseHierarchyProjection } from './hierarchy-projection';
+
+function describeManifestError(error: unknown): string {
+  const issues =
+    error && typeof error === 'object' && Array.isArray((error as { issues?: unknown }).issues)
+      ? (error as { issues: unknown[] }).issues
+      : null;
+  if (!issues) return error instanceof Error ? error.message : String(error);
+
+  return issues
+    .map((issue) => {
+      if (!issue || typeof issue !== 'object') return String(issue);
+      const candidate = issue as { path?: unknown; message?: unknown };
+      const path = Array.isArray(candidate.path)
+        ? candidate.path.map(String).join('.') || '(root)'
+        : '(root)';
+      const message =
+        typeof candidate.message === 'string' ? candidate.message : 'Invalid manifest value';
+      return `${path}: ${message}`;
+    })
+    .join('\n');
+}
+
+/** Open a project by its root path. Fetches the sole v2 project manifest. */
+export async function openProject(rootPath: string): Promise<ActiveProject> {
+  const compatibility = await requireEditorCompatibility();
+  const res = await fetch('/vgai.project.json');
+  if (!res.ok) {
+    throw new Error(
+      `Could not open project at ${rootPath}.\n` +
+        `Failed to load vgai.project.json: ${res.status} ${res.statusText}`,
+    );
+  }
+  let rawManifest: unknown;
+  try {
+    rawManifest = await res.json();
+  } catch (error) {
+    throw new Error(
+      `Could not open project at ${rootPath}.\n` +
+        `vgai.project.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  assertProjectCompatibility(
+    rawManifest && typeof rawManifest === 'object'
+      ? (rawManifest as {
+          manifestVersion?: unknown;
+          engine?: { version?: unknown };
+          roots?: unknown;
+        })
+      : {},
+    compatibility,
+  );
+  let manifest: ReturnType<typeof loadGameManifest>;
+  try {
+    manifest = loadGameManifest(rawManifest, { configurationKinds: 'defer' });
+  } catch (error) {
+    throw new Error(
+      `Could not open project at ${rootPath}.\n` +
+        `vgai.project.json does not match the current project format:\n${describeManifestError(error)}`,
+    );
+  }
+  const config: ProjectConfig = {
+    manifestVersion: manifest.manifestVersion,
+    name: manifest.name,
+    version: manifest.version,
+    engine: manifest.engine,
+    appId: manifest.appId,
+    resolution: manifest.resolution,
+    authoring: manifest.authoring
+      ? { hierarchy: parseHierarchyProjection(manifest.authoring.hierarchy) }
+      : undefined,
+    hasThreeRoot: hasRootOnSurface(manifest, 'three'),
+    rootCount: manifest.roots.length,
+    configurations: manifest.configurations,
+  };
+  return assignActiveProject({ rootPath, config });
+}
+
+/** How many times boot may re-ask a server that failed to answer at all, and
+ *  how long it waits between tries. Both small: `detectProject` runs inside
+ *  AppRoot's detection timeout, and a failing fetch fails fast. */
+export const SERVER_PROJECT_PROBE_ATTEMPTS = 3;
+export const SERVER_PROJECT_PROBE_RETRY_MS = 300;
+
+/**
+ * Detect and open whatever project the server currently has active.
+ * Used in production where __VGAI_PROJECT_PATH__ isn't available at build time.
+ *
+ * Returns null ONLY when the server said it has no project open — that is the
+ * one answer the launcher is a truthful response to. A server that is serving
+ * a project it cannot describe, or that could not be asked at all, THROWS
+ * (after bounded retries for the transient shape), because rendering the
+ * launcher there tells the user their project does not exist when it does.
+ * The ladder itself is `boot-routing.ts`'s `decideServerProjectBoot`.
+ */
+export async function detectServerProject(): Promise<ActiveProject | null> {
+  const compatibility = await requireEditorCompatibility();
+  for (let attempt = 1; ; attempt++) {
+    const probe = await probeCurrentServerProject();
+    const action = decideServerProjectBoot({
+      status: probe.status,
+      attempt,
+      maxAttempts: SERVER_PROJECT_PROBE_ATTEMPTS,
+    });
+    if (action === 'continue-ladder') return null;
+    if (action === 'open' && probe.status === 'project') {
+      const info = probe.project;
+      assertProjectCompatibility(info.config, compatibility);
+      return assignActiveProject({ rootPath: info.path, config: info.config as ProjectConfig });
+    }
+    if (action === 'retry') {
+      await new Promise((resolve) => setTimeout(resolve, SERVER_PROJECT_PROBE_RETRY_MS));
+      continue;
+    }
+    // 'fail' is only reachable from the two failure shapes, and the surface
+    // that renders this must name the served path and the server's own error
+    // separately — a launcher with a banner is what this fix exists to stop.
+    throw new ServerProjectDetectionError(
+      describeServerProjectFailure(
+        probe.status === 'unreadable'
+          ? { status: 'unreadable', path: probe.path, error: probe.error }
+          : {
+              status: 'unknown',
+              error: probe.status === 'unknown' ? probe.error : 'no answer from the server',
+            },
+      ),
+    );
+  }
+}
+
+/**
+ * Detect which project is open, by ASKING the session. Returns the project if
+ * found, null if the project screen should be shown.
+ */
+export async function detectProject(): Promise<ActiveProject | null> {
+  // One gate before anything is resolved: a removed boot
+  // param errors loudly naming its replacement rather than falling through
+  // (boot-routing.ts) — including `?project=` itself: project identity is
+  // session-held.
+  assertNoRemovedBootParams(window.location.search);
+
+  // 1. ASK THE SESSION. This is the one explicit target —
+  //    `vgai edit <path>`, `VGAI_PROJECT`, and the project browser all reach
+  //    the client the same way, because they all move the SERVER's project
+  //    and the client reads it from there. There is no URL param and no
+  //    boot-time Vite define snapshot in this path: the define is a
+  //    build-time value, and `POST /__editor/open-project` moves the session
+  //    live, so a snapshot could disagree with the server that serves the
+  //    files.
+  const serverProject = await detectServerProject();
+  if (serverProject) return serverProject;
+
+  // 2. Reopen-last (G5). Only reached when the server said it has no project
+  //    open: a live session project outranks the preference.
+  return reopenLastProjectIfEnabled();
+}
+
+/**
+ * The opted-in "Reopen last project on launch" rung of the §5 ladder.
+ *
+ * Returns the reopened project, or null to fall through to the hub — which is
+ * also what a FAILED reopen returns. That fallback is deliberate and is half
+ * the reason the escape hatch exists: a project that was deleted, moved, or
+ * broken since it was last opened must not be able to wedge the launcher in a
+ * boot loop the user cannot click their way out of. Unreal behaves the same
+ * way. The failure is reported to the console rather than thrown, because a
+ * thrown error here would render the startup-failure screen instead of the hub
+ * and hide the recents list the user needs in order to pick something else.
+ */
+async function reopenLastProjectIfEnabled(): Promise<ActiveProject | null> {
+  const [settings, recents] = await Promise.all([getLauncherSettings(), listRecentProjects()]);
+  const target = resolveBootTarget({
+    explicitTarget: null,
+    hubRequested: hubRequestedFromSearch(window.location.search),
+    reopenLastEnabled: settings.reopenLastProject,
+    recents,
+  });
+  if (target.kind !== 'reopen-last') return null;
+  try {
+    return await openProject(target.path);
+  } catch (err) {
+    // biome-ignore lint/suspicious/noConsole: a failed auto-reopen must be visible; the editor console isn't mounted yet at boot.
+    console.warn(
+      `[vgai] "Reopen last project on launch" could not open ${target.path}; showing the project browser instead.`,
+      err,
+    );
+    return null;
+  }
+}
+
+export {
+  type ActiveProject,
+  getCurrentProject,
+  onProjectChange,
+  onProjectSessionEnd,
+  type ProjectConfig,
+  setActiveProject,
+} from './active-project';

package/src/project-module-changes.ts

@@ -0,0 +1,163 @@
+/**
+ * "This project module was saved" — the ONE subscription for editor surfaces
+ * that hold a live, re-executable copy of a project source module.
+ *
+ * WHICH SIGNAL, AND WHY IT IS THE HMR CHANNEL AND NOT SSE
+ * -------------------------------------------------------
+ * The editor has two file-change channels and they answer different
+ * questions. `asset-events.ts` (SSE) reports FILE-SET changes — a tool or
+ * story file appeared/vanished, a `public/` asset changed — and it carries no
+ * event for "an arbitrary `src/**` module's bytes changed". Vite's HMR
+ * channel does, and it carries something the SSE channel cannot: the dev
+ * server has already stamped the changed file HMR-invalid across the
+ * project's own subgraph before it sends (`server/project-script-hmr.ts`'s
+ * `stampHmrInvalidation`, bounded at editor chrome). That stamp is what makes
+ * a cache-busted re-import re-evaluate the module's DEPENDENCIES too; without
+ * it a fresh leaf url re-runs against the browser's cached copies of
+ * everything it imports, which is the exact stale-restart defect that module's
+ * header documents. So the freshness guarantee is the server's, and this
+ * subscription is how a document learns the stamp has landed.
+ *
+ * THE THREE EVENTS are the complete set the server sends for a project source
+ * file (`handleProjectScriptHotUpdate`); a live module document takes all
+ * three because its subject can be any of those classifications:
+ *   - `vgai:restart-required` — a plain `.ts`, or a `.tsx` that is not a Fast
+ *     Refresh boundary. THE COMMON CASE for a model module, whose export is a
+ *     lowercase builder function.
+ *   - `vgai:script-update` — the file is in the editor's lane (`src/contributions/`, `src/tools/`).
+ *   - `vgai:r3f-entry-update` — the file is R3F-dialect.
+ * A `.tsx` that IS a Fast Refresh boundary rides stock Vite HMR instead and
+ * sends none of these, so `vite:afterUpdate` is taken as well: Vite stamped
+ * the graph itself on that path, and the accepted path names the file.
+ *
+ * Nothing here re-imports anything. The subscriber owns what "changed" means
+ * for its own surface.
+ */
+
+/** Project-relative path of the module that changed, e.g. `src/prefabs/probe.ts`. */
+export type ProjectModuleChangeListener = (relativePath: string) => void;
+
+/**
+ * WHY THE TRANSFORM ERROR IS RECORDED SEPARATELY: a dynamic `import()` of a
+ * module the server could not transform rejects with the browser's own opaque
+ * `TypeError: Failed to fetch dynamically imported module: <url>` — the
+ * ACTUAL reason (`Unexpected ";"`, at line:col, with a source frame) never
+ * reaches the importer. Vite sends it on the HMR channel instead, as
+ * `vite:error`, and `editor-console.ts` already prints it. A document showing
+ * a build failure needs the same text: "failed to fetch" is not a modeling
+ * error message.
+ *
+ * Kept as a LAST-ERROR-PER-FILE map rather than a subscription because the
+ * consumer reads it at the moment its import rejects, which is after the
+ * event: the server sends `vite:error` while answering the very request that
+ * is about to reject.
+ */
+interface ViteErrorPayload {
+  readonly err?: {
+    readonly message?: unknown;
+    readonly id?: unknown;
+    readonly frame?: unknown;
+    readonly loc?: { readonly file?: unknown; readonly line?: unknown; readonly column?: unknown };
+  };
+}
+
+/** Keyed by the normalized absolute file path Vite reports. */
+const lastTransformError = new Map<string, string>();
+let transformErrorsWired = false;
+
+function wireTransformErrors(): void {
+  if (transformErrorsWired) return;
+  const hot = import.meta.hot;
+  if (!hot) return;
+  transformErrorsWired = true;
+  hot.on('vite:error', (payload: ViteErrorPayload) => {
+    const err = payload?.err;
+    if (!err || typeof err.message !== 'string') return;
+    const file =
+      typeof err.loc?.file === 'string' ? err.loc.file : typeof err.id === 'string' ? err.id : null;
+    if (file === null) return;
+    const frame = typeof err.frame === 'string' && err.frame !== '' ? `\n${err.frame}` : '';
+    // Vite ids carry the transform query; the record is keyed by the file.
+    lastTransformError.set(normalize(file.split('?')[0] ?? file), `${err.message}${frame}`);
+  });
+}
+
+/**
+ * The server's own reason the module at `relativePath` did not transform, if
+ * it reported one — see {@link ViteErrorPayload}. `null` when the failure was
+ * something else (a throwing top level, a missing dependency at runtime),
+ * which is the caller's cue to report what its own `import()` said.
+ */
+export function projectModuleTransformError(relativePath: string): string | null {
+  for (const [file, message] of lastTransformError) {
+    if (projectModuleChangeMatches(file, relativePath)) return message;
+  }
+  return null;
+}
+
+/** Drop the recorded transform error for a module that has now built. */
+export function clearProjectModuleTransformError(relativePath: string): void {
+  for (const file of [...lastTransformError.keys()]) {
+    if (projectModuleChangeMatches(file, relativePath)) lastTransformError.delete(file);
+  }
+}
+
+/** Server-sent event payloads all carry `{ file }` as an ABSOLUTE path. */
+interface HotFilePayload {
+  readonly file?: unknown;
+}
+
+/** Vite's own `vite:afterUpdate` payload, narrowed to what is read here. */
+interface ViteUpdatePayload {
+  readonly updates?: ReadonlyArray<{ readonly acceptedPath?: unknown; readonly path?: unknown }>;
+}
+
+function normalize(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+/**
+ * Does `changedPath` (absolute, or already project-relative) name
+ * `relativePath` of the open project? Compared by SUFFIX because the two
+ * halves spell the same file differently: the dev server reports the absolute
+ * path it watched, and a document knows only its project-relative one. The
+ * leading separator makes the suffix a whole path segment, so
+ * `src/prefabs/probe.ts` never matches `.../not-src/prefabs/probe.ts`.
+ */
+export function projectModuleChangeMatches(changedPath: string, relativePath: string): boolean {
+  const changed = normalize(changedPath);
+  const relative = normalize(relativePath).replace(/^\.?\//, '');
+  return changed === relative || changed.endsWith(`/${relative}`);
+}
+
+/**
+ * Call `listener` whenever the dev server reports that a project source module
+ * was saved. Returns the unsubscribe. A no-op (and an immediately-returned
+ * unsubscribe) outside a Vite dev client — the packaged host has no HMR
+ * channel, and a surface that needs one says so itself.
+ */
+export function subscribeProjectModuleChange(listener: ProjectModuleChangeListener): () => void {
+  const hot = import.meta.hot;
+  if (!hot) return () => {};
+  wireTransformErrors();
+  const onFileEvent = (payload: HotFilePayload): void => {
+    if (typeof payload?.file === 'string') listener(normalize(payload.file));
+  };
+  const onViteUpdate = (payload: ViteUpdatePayload): void => {
+    for (const update of payload?.updates ?? []) {
+      const path = update.acceptedPath ?? update.path;
+      // Vite's urls carry the transform query (`?t=…`); the path half is the file.
+      if (typeof path === 'string') listener(normalize(path.split('?')[0] ?? path));
+    }
+  };
+  hot.on('vgai:restart-required', onFileEvent);
+  hot.on('vgai:script-update', onFileEvent);
+  hot.on('vgai:r3f-entry-update', onFileEvent);
+  hot.on('vite:afterUpdate', onViteUpdate);
+  return () => {
+    hot.off('vgai:restart-required', onFileEvent);
+    hot.off('vgai:script-update', onFileEvent);
+    hot.off('vgai:r3f-entry-update', onFileEvent);
+    hot.off('vite:afterUpdate', onViteUpdate);
+  };
+}