@volter/editor-core 0.5.57

package/server/project-dependency-invalidation.ts

@@ -0,0 +1,114 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ProjectModuleLoader } from './project-tools';
+
+/**
+ * Makes a live editor session see dependencies installed UNDER it.
+ *
+ * The problem, measured: `vgai add mesh` copies `src/lib/mesh/**` in and runs
+ * `npm install three-bvh-csg …`, but a session that is already running keeps
+ * failing every Node module-lane call with
+ * `Cannot find module 'three-bvh-csg' imported from …/src/lib/mesh/modifiers.ts`
+ * — while `require.resolve` from the very same project directory succeeds.
+ *
+ * The mechanism is a cached FAILURE, not a cached resolution. Vite's SSR
+ * module runner memoises a module's load promise on its module-graph node and
+ * never clears it when that promise REJECTS
+ * (`vite/dist/node/module-runner.js`, `cachedRequest`: `mod.promise = promise`
+ * inside a `try`/`finally` that only flips `evaluated`). So the first load of
+ * `modifiers.ts` attempted before the package existed poisons that module for
+ * the life of the process, and every later call replays the identical
+ * rejection — including calls from brand-new files that merely import it. The
+ * poison is per-module, not per-package: a fresh module importing
+ * `three-bvh-csg` DIRECTLY resolves it fine at the same moment.
+ *
+ * That also explains the two things the symptom report noted. Editing the
+ * importing file "fixes" it, because an HMR invalidation drops the module
+ * node together with its rejected promise. And `vgai restart` does not, because
+ * it re-issues `play` to the browser and never touches this Node process.
+ *
+ * The fix is to perform that same invalidation when the project's dependency
+ * set moves. This is checked ON USE rather than from a file watcher on
+ * purpose: `vgai add` installs and returns, and the next thing a caller does
+ * is run the tool. A debounced watcher races that window; a fingerprint read
+ * at load time cannot.
+ */
+
+/**
+ * Files whose contents define which packages a project has. `package.json`
+ * alone is not enough — a bare `npm install` that only writes the lockfile
+ * still changes what is resolvable — and the lockfile alone is not enough
+ * either, since `vgai add` merges dependencies into `package.json` first.
+ */
+export const DEPENDENCY_MANIFEST_FILES = [
+  'package.json',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'bun.lock',
+  'bun.lockb',
+] as const;
+
+/**
+ * Cheap stat-based fingerprint of a project's dependency manifests. Size is
+ * carried alongside mtime because an install that lands inside one filesystem
+ * timestamp tick still changes the file's length.
+ */
+export function dependencyManifestFingerprint(projectRoot: string): string {
+  return DEPENDENCY_MANIFEST_FILES.map((name) => {
+    try {
+      const stats = statSync(join(projectRoot, name));
+      return `${name}:${stats.mtimeMs}:${stats.size}`;
+    } catch {
+      return `${name}:-`;
+    }
+  }).join('|');
+}
+
+export interface DependencyChangeInvalidationDeps {
+  /** Read live — the open project changes at runtime. */
+  getProjectRoot: () => string;
+  /**
+   * Drop everything the Node module lane has cached for this project. The
+   * owning dev server implements it as
+   * `vite.environments.ssr.moduleGraph.invalidateAll()`; a host without a
+   * bundler (the static production server) has nothing to invalidate and
+   * omits it, leaving the loader a plain pass-through.
+   */
+  invalidateModules?: (() => void) | undefined;
+}
+
+/**
+ * Wraps a project-module loader so a dependency change invalidates the cached
+ * module graph before the next load. Returns `undefined` for an absent loader
+ * so hosts that never load project modules stay unchanged.
+ */
+export function withDependencyChangeInvalidation(
+  load: ProjectModuleLoader | undefined,
+  deps: DependencyChangeInvalidationDeps,
+): ProjectModuleLoader | undefined {
+  if (!load) return undefined;
+  const { getProjectRoot, invalidateModules } = deps;
+  if (!invalidateModules) return load;
+
+  let lastProjectRoot: string | null = null;
+  let lastFingerprint: string | null = null;
+
+  return async (absoluteModuleId: string): Promise<unknown> => {
+    const projectRoot = getProjectRoot();
+    const fingerprint = dependencyManifestFingerprint(projectRoot);
+    // A different project is a fresh baseline, never an invalidation: opening
+    // a project already rebuilds what the graph holds for it.
+    if (
+      lastProjectRoot === projectRoot &&
+      lastFingerprint !== null &&
+      lastFingerprint !== fingerprint
+    ) {
+      invalidateModules();
+    }
+    lastProjectRoot = projectRoot;
+    lastFingerprint = fingerprint;
+    return load(absoluteModuleId);
+  };
+}

package/server/project-file-scan.ts

@@ -0,0 +1,235 @@
+/**
+ * Reading a project's files as FACTS: install its dependencies, hash a tree,
+ * snapshot it for collaboration, and name a file's content type.
+ *
+ * None of this holds session state — every function takes the paths it works
+ * on. The collaboration snapshot in particular is a pure read: it is what a
+ * joining participant is told the project currently contains.
+ */
+
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { type Dirent, readFileSync } from 'node:fs';
+import { readdir, readFile, stat, unlink } from 'node:fs/promises';
+import type { IncomingMessage } from 'node:http';
+import { join, relative, sep } from 'node:path';
+import { isContainedRelativePath } from '@volter/editor-sdk/session/relative-path-guard';
+
+export async function installProjectDependencies(projectPath: string): Promise<void> {
+  await new Promise<void>((resolveInstall, rejectInstall) => {
+    const child = spawn(
+      'npm',
+      ['install', '--prefer-offline', '--no-audit', '--no-fund', '--loglevel=error'],
+      {
+        cwd: projectPath,
+        stdio: 'ignore',
+        shell: true,
+      },
+    );
+    child.once('error', rejectInstall);
+    child.once('close', (code) => {
+      if (code === 0) resolveInstall();
+      else rejectInstall(new Error(`npm install exited with code ${code ?? 'unknown'}`));
+    });
+  });
+}
+
+export function readRunningEngineVersion(engineRoot: string): string | null {
+  const candidates = [
+    join(engineRoot, 'packages', 'editor-core', 'package.json'),
+    join(engineRoot, 'node_modules', '@volter', 'editor-core', 'package.json'),
+  ];
+  for (const path of candidates) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { version?: unknown };
+      if (typeof parsed.version === 'string') return parsed.version;
+    } catch {
+      // Try the next supported checkout/installed-package layout.
+    }
+  }
+  // Packaged mode passes the installed `@vgai/editor` package as engineRoot.
+  // npm/pnpm may hoist its runtime-package dependencies to the PROJECT's
+  // node_modules, outside both candidates above; reading that project copy
+  // would merely echo the manifest pin and make every mismatch look healthy.
+  // Release-train package versions are synchronized, so the installed
+  // editor's own version is the authoritative identity in this layout. Keep
+  // the name check strict: the monorepo root has its own unrelated package
+  // version and must never masquerade as the engine version.
+  try {
+    const parsed = JSON.parse(readFileSync(join(engineRoot, 'package.json'), 'utf-8')) as {
+      name?: unknown;
+      version?: unknown;
+    };
+    if (parsed.name === '@volter/editor-core' && typeof parsed.version === 'string') {
+      return parsed.version;
+    }
+  } catch {
+    // No packaged-editor identity at this root.
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// File hashing — partial hash for large files (first 64KB + size)
+// ---------------------------------------------------------------------------
+
+const PARTIAL_HASH_THRESHOLD = 10 * 1024 * 1024; // 10MB
+
+export async function hashAndSize(absPath: string): Promise<{ hash: string; size: number }> {
+  const data = await readFile(absPath);
+  const hash = createHash('sha256');
+  if (data.length > PARTIAL_HASH_THRESHOLD) {
+    hash.update(data.subarray(0, 65536));
+    hash.update(`\0size:${data.length}`);
+  } else {
+    hash.update(data);
+  }
+  return { hash: hash.digest('hex').slice(0, 16), size: data.length };
+}
+
+export async function unlinkIfPresent(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+}
+
+export async function scanDirForHashes(
+  dir: string,
+  hashCache: Map<string, string>,
+  sizeCache: Map<string, number>,
+): Promise<void> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await scanDirForHashes(full, hashCache, sizeCache);
+    } else if (entry.isFile()) {
+      try {
+        const { hash, size } = await hashAndSize(full);
+        hashCache.set(full, hash);
+        sizeCache.set(full, size);
+      } catch {
+        /* skip unreadable files */
+      }
+    }
+  }
+}
+
+const COLLABORATION_IGNORED_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'coverage',
+  'logs',
+  '.git',
+  '.vgai',
+]);
+
+/** The project-owned estate: every file under the project root except the
+ *  installed, generated and private directories above, and every dotfile.
+ *  The same set `collaborationSourceSnapshot` publishes to a joining
+ *  participant — one line, not a second weaker one. */
+export function isProjectOwnedRelativePath(path: string): boolean {
+  if (!isContainedRelativePath(path)) return false;
+  return !path
+    .split('/')
+    .some((segment) => segment.startsWith('.') || COLLABORATION_IGNORED_DIRS.has(segment));
+}
+
+/** The project's own files with size and mtime — a listing, not a read, so
+ *  asking what is there does not cost what is in it. */
+export async function projectFileIndex(
+  projectRoot: string,
+): Promise<Array<{ path: string; size: number; mtime: number }>> {
+  const files: Array<{ path: string; size: number; mtime: number }> = [];
+  const visit = async (dir: string): Promise<void> => {
+    let entries: Dirent[];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || COLLABORATION_IGNORED_DIRS.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      try {
+        const info = await stat(full);
+        files.push({
+          path: relative(projectRoot, full).split(sep).join('/'),
+          size: info.size,
+          mtime: info.mtimeMs,
+        });
+      } catch {
+        /* vanished between readdir and stat: it is not in the project now */
+      }
+    }
+  };
+  await visit(projectRoot);
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export async function collaborationSourceSnapshot(
+  projectRoot: string,
+): Promise<Array<{ path: string; sha: string }>> {
+  const resources: Array<{ path: string; sha: string }> = [];
+  const visit = async (dir: string): Promise<void> => {
+    let entries: Dirent[];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || COLLABORATION_IGNORED_DIRS.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const { hash } = await hashAndSize(full);
+      resources.push({
+        path: relative(projectRoot, full).split(sep).join('/'),
+        sha: hash,
+      });
+    }
+  };
+  await visit(projectRoot);
+  return resources.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+// ---------------------------------------------------------------------------
+// MIME type detection
+export const mimeTypes: Record<string, string> = {
+  json: 'application/json',
+  glb: 'model/gltf-binary',
+  gltf: 'model/gltf+json',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  wav: 'audio/wav',
+  mp3: 'audio/mpeg',
+  ogg: 'audio/ogg',
+  gif: 'image/gif',
+};
+
+/** One raw request header as a single string (Node hands back `string[]` for
+ *  the repeatable ones). The share-claim headers are all single-valued. */
+export function headerValue(request: IncomingMessage, name: string): string | undefined {
+  const value = request.headers[name.toLowerCase()];
+  return Array.isArray(value) ? value[0] : value;
+}

package/server/project-hmr-files.ts

@@ -0,0 +1,215 @@
+import path from 'node:path';
+import { isEditorLanePath } from '@volter/editor-sdk/session/tool-contribution-convention';
+import ts from 'typescript';
+import type { ImportersOf } from './project-root-surface';
+import { resolveOidSurface } from './project-root-surface';
+
+export type ProjectHotUpdateKind =
+  | 'outside'
+  | 'stock-data'
+  | 'react'
+  | 'r3f-refresh'
+  | 'r3f-entry'
+  | 'tool'
+  | 'restart'
+  | 'ignore';
+
+/** Only locally proven component exports earn stock Fast Refresh. A wrong
+ * positive can reload the whole editor. Parse all declarations (including
+ * inline/indented exports), and never infer a component from an uppercase
+ * value, an arbitrary factory call, or an uninspected re-export.
+ */
+export function reactRefreshBoundaryExports(source: string): readonly string[] | null {
+  const file = ts.createSourceFile(
+    'boundary.tsx',
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  const bindings = new Map<string, ts.Node>();
+  const reactWrappers = new Set<string>();
+  const reactNamespaces = new Set<string>();
+  for (const statement of file.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.name)
+      bindings.set(statement.name.text, statement);
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name) && declaration.initializer)
+          bindings.set(declaration.name.text, declaration.initializer);
+      }
+    }
+    if (
+      ts.isImportDeclaration(statement) &&
+      ts.isStringLiteral(statement.moduleSpecifier) &&
+      statement.moduleSpecifier.text === 'react'
+    ) {
+      const clause = statement.importClause;
+      if (clause?.name) reactNamespaces.add(clause.name.text);
+      if (clause?.namedBindings && ts.isNamespaceImport(clause.namedBindings))
+        reactNamespaces.add(clause.namedBindings.name.text);
+      if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+        for (const binding of clause.namedBindings.elements) {
+          if (['memo', 'forwardRef'].includes((binding.propertyName ?? binding.name).text))
+            reactWrappers.add(binding.name.text);
+        }
+      }
+    }
+  }
+  const component = (node: ts.Node, seen = new Set<string>()): boolean => {
+    if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node))
+      return !node.name || /^[A-Z]/.test(node.name.text);
+    if (ts.isArrowFunction(node)) return true;
+    if (
+      ts.isParenthesizedExpression(node) ||
+      ts.isAsExpression(node) ||
+      ts.isSatisfiesExpression(node)
+    )
+      return component(node.expression, seen);
+    if (ts.isIdentifier(node)) {
+      if (seen.has(node.text) || !/^[A-Z]/.test(node.text)) return false;
+      const binding = bindings.get(node.text);
+      seen.add(node.text);
+      return binding !== undefined && component(binding, seen);
+    }
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      const wrapper = ts.isIdentifier(callee)
+        ? reactWrappers.has(callee.text)
+        : ts.isPropertyAccessExpression(callee) &&
+          ts.isIdentifier(callee.expression) &&
+          reactNamespaces.has(callee.expression.text) &&
+          ['memo', 'forwardRef'].includes(callee.name.text);
+      return wrapper && node.arguments[0] !== undefined && component(node.arguments[0], seen);
+    }
+    return false;
+  };
+  const exports: string[] = [];
+  for (const statement of file.statements) {
+    if (ts.isExportAssignment(statement)) {
+      if (
+        statement.isExportEquals ||
+        ts.isArrowFunction(statement.expression) ||
+        !component(statement.expression)
+      )
+        return null;
+      exports.push('default');
+      continue;
+    }
+    if (ts.isExportDeclaration(statement)) {
+      if (statement.isTypeOnly) continue;
+      if (
+        statement.moduleSpecifier ||
+        !statement.exportClause ||
+        !ts.isNamedExports(statement.exportClause)
+      )
+        return null;
+      for (const spec of statement.exportClause.elements) {
+        if (spec.isTypeOnly) continue;
+        if (spec.name.text !== 'default' && !/^[A-Z]/.test(spec.name.text)) return null;
+        if (!component(spec.propertyName ?? spec.name)) return null;
+        exports.push(spec.name.text);
+      }
+      continue;
+    }
+    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+    if (!modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
+    if (ts.isFunctionDeclaration(statement)) {
+      if (!statement.name || !/^[A-Z]/.test(statement.name.text)) return null;
+      exports.push(
+        modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
+          ? 'default'
+          : statement.name.text,
+      );
+    } else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (
+          !ts.isIdentifier(declaration.name) ||
+          !/^[A-Z]/.test(declaration.name.text) ||
+          !declaration.initializer ||
+          !component(declaration.initializer)
+        )
+          return null;
+        exports.push(declaration.name.text);
+      }
+    } else return null;
+  }
+  return exports.length ? exports.sort() : null;
+}
+
+export function isReactRefreshBoundary(source: string): boolean {
+  return reactRefreshBoundaryExports(source) !== null;
+}
+
+/**
+ * Classify a Vite watcher update for the editor's project-script HMR seam.
+ *
+ * Only modules below the project's `src/` directory are game code. Build
+ * output, tests, one-off scripts, and dependency caches may also contain
+ * JavaScript, but importing them into the live game is both surprising and
+ * unsafe (a project build used to make the editor import `dist/assets/*`).
+ */
+export function classifyProjectHotUpdate(
+  file: string,
+  projectRoot: string,
+  source = '',
+  importersOf?: ImportersOf,
+): ProjectHotUpdateKind {
+  const normalizedFile = file.replaceAll('\\', '/');
+  const normalizedRoot = projectRoot.replaceAll('\\', '/').replace(/\/$/, '');
+  const relative = path.posix.relative(normalizedRoot, normalizedFile);
+
+  if (relative === '' || relative === '..' || relative.startsWith('../')) {
+    // A repo-vendored game's source (`vendor/games/<id>/…`) is the OPEN
+    // GAME's own code even though it lives outside the project folder — the
+    // project's ingest root maps to it. Classifying it `outside` handed it to
+    // STOCK Vite HMR, whose unbounded propagation re-stamped ~33 editor
+    // modules per creation-site write (the write route writes these files),
+    // fanned an HMR update at the tab, and split editor singletons
+    // (`play-mode.ts`'s game container) so every ▶ after a write refused —
+    // measured on bubbo-bubbo, 2026-08-21. `restart` is the honest kind: the
+    // ingest world re-derives from source on its next mount, and the
+    // swallowed-HMR path stamps the module graph with the editor-chrome
+    // boundary instead of letting stock HMR walk into the editor.
+    if (normalizedFile.includes('/vendor/games/') && /\.(ts|tsx|js|jsx)$/.test(normalizedFile)) {
+      return 'restart';
+    }
+    return 'outside';
+  }
+  if (relative === 'vgai.project.json') return 'restart';
+  if (!relative.startsWith('src/')) return 'ignore';
+  if (/\.data\.json$/.test(relative)) return 'stock-data';
+  if (!/\.(ts|tsx|js|jsx)$/.test(relative)) return 'ignore';
+  // Project-tool definitions, surfaces, documents, and their local helpers
+  // are editor tooling. They remount through the tool contribution store's
+  // own cache-busted import, never through game restart or React Refresh.
+  if (isEditorLanePath(relative)) return 'tool';
+  // R3F is a React renderer: a component-only module can refresh without
+  // replacing its scene. Mixed component/data exports still need the editor's
+  // remount boundary, because React Refresh cannot safely accept them.
+  //
+  // `resolveOidSurface` — the SAME single decision `vite-plugin-ui-oid.ts`'s
+  // OID-stamping transform stamps with, not a separate copy kept in lockstep
+  // by hand. It decides from the manifest when this exact file is a root's
+  // `entry`, from the live import graph when it's reachable from exactly one
+  // root's `entry` (`importersOf`, when the caller has one — see
+  // `dev.ts`/`packaged.ts`'s `handleHotUpdate`), and otherwise from the file's
+  // own dialect evidence (a direct `@react-three/fiber` /
+  // `@vgai/game-runtime/world3d-react` import, OR an R3F-only intrinsic tag like
+  // `<mesh>`). Reading its ATTRIBUTE rather than its surface is what keeps the
+  // two halves identical by construction: a file stamped `userData-oid` is, by
+  // definition, an R3F module. Its export shape decides whether the renderer
+  // can refresh or needs the design-session remount.
+  if (/\.(tsx|jsx)$/.test(relative)) {
+    if (resolveOidSurface(file, source, importersOf).attribute === 'userData-oid')
+      return isReactRefreshBoundary(source) ? 'r3f-refresh' : 'r3f-entry';
+    // Stock Fast Refresh ONLY when the module provably is a Fast Refresh
+    // boundary. Anything else the editor owns (swallow + stamp the module
+    // graph + `vgai:restart-required`), because letting Vite propagate a
+    // project module that is not a boundary full-reloads the editor page and
+    // silently destroys the running game — see `isReactRefreshBoundary`.
+    return isReactRefreshBoundary(source) ? 'react' : 'restart';
+  }
+  return 'restart';
+}