@volter/editor-core 0.5.57

package/server/model-import-conversion.ts

@@ -0,0 +1,345 @@
+/// <reference lib="dom" />
+
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, extname } from 'node:path';
+import * as THREE from 'three';
+import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';
+import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
+import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+import { TDSLoader } from 'three/addons/loaders/TDSLoader.js';
+import { mergeVertices } from 'three/addons/utils/BufferGeometryUtils.js';
+import {
+  type AssetImportSettings,
+  assetImportSettingsSchema,
+} from '../src/asset-workflow/import-contract';
+
+export const SERVER_CONVERTIBLE_MODEL_FORMATS = new Set(['fbx', 'obj', 'dae', 'stl', 'ply', '3ds']);
+
+/** Convert a staged source model to a runtime GLB without requiring Blender. */
+export async function convertStagedModelToGlb(
+  primaryPath: string,
+  format: string,
+  rawSettings: Partial<AssetImportSettings> | number = {},
+): Promise<Uint8Array> {
+  const settings = assetImportSettingsSchema.parse(
+    typeof rawSettings === 'number' ? { scale: rawSettings } : rawSettings,
+  );
+  installNodeDom();
+  const bytes = new Uint8Array(await readFile(primaryPath));
+  const object = await parseSourceModel(primaryPath, format.toLowerCase(), bytes);
+  discardUnloadedTextures(object);
+  applyModelImportSettings(object, settings);
+  installNodeFileReader();
+  try {
+    const result = await new Promise<ArrayBuffer>((resolve, reject) => {
+      new GLTFExporter().parse(
+        object,
+        (output) =>
+          output instanceof ArrayBuffer
+            ? resolve(output)
+            : reject(new Error('Model conversion produced JSON instead of binary GLB.')),
+        reject,
+        { binary: true, animations: object.animations, onlyVisible: false },
+      );
+    });
+    const output = new Uint8Array(result);
+    await validateConvertedGlb(output);
+    return output;
+  } finally {
+    disposeObject(object);
+  }
+}
+
+const materialTextureSlots = [
+  'map',
+  'alphaMap',
+  'aoMap',
+  'bumpMap',
+  'displacementMap',
+  'emissiveMap',
+  'envMap',
+  'lightMap',
+  'metalnessMap',
+  'normalMap',
+  'roughnessMap',
+  'specularMap',
+] as const;
+
+/** Apply the persisted conversion settings before the runtime GLB is exported. */
+export function applyModelImportSettings(
+  object: THREE.Object3D,
+  settings: AssetImportSettings,
+): void {
+  object.scale.multiplyScalar(settings.scale * sourceUnitScale(settings.sourceUnits));
+  object.quaternion.premultiply(importAxisRotation(settings.upAxis, settings.forwardAxis));
+
+  const discardedTextures = new Set<THREE.Texture>();
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one traversal deliberately applies the persisted mesh, material, texture, normal, tangent, and optimization settings to each converted renderable.
+  object.traverse((node) => {
+    const mesh = node as THREE.Mesh;
+    if (!mesh.geometry) return;
+    let geometry = mesh.geometry;
+    if (settings.meshOptimization !== 'none') {
+      const optimized = mergeVertices(
+        geometry,
+        settings.meshOptimization === 'aggressive' ? 1e-3 : 1e-6,
+      );
+      if (optimized !== geometry) {
+        mesh.geometry = optimized;
+        geometry.dispose();
+        geometry = optimized;
+      }
+    }
+    if (settings.normals !== 'preserve') {
+      geometry.deleteAttribute('normal');
+      geometry.computeVertexNormals();
+    }
+    if (settings.tangents === 'discard') geometry.deleteAttribute('tangent');
+    if (
+      settings.tangents === 'generate' &&
+      geometry.index &&
+      geometry.hasAttribute('position') &&
+      geometry.hasAttribute('normal') &&
+      geometry.hasAttribute('uv')
+    ) {
+      geometry.computeTangents();
+    }
+    geometry.computeBoundingBox();
+    geometry.computeBoundingSphere();
+
+    const priorMaterials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+    if (settings.materials === 'discard') {
+      mesh.material = Array.isArray(mesh.material)
+        ? priorMaterials.map(() => new THREE.MeshStandardMaterial())
+        : new THREE.MeshStandardMaterial();
+      for (const material of priorMaterials) material.dispose();
+      return;
+    }
+    if (settings.textures !== 'discard') return;
+    for (const material of priorMaterials) {
+      const textured = material as THREE.Material & Record<string, unknown>;
+      for (const slot of materialTextureSlots) {
+        const texture = textured[slot];
+        if (texture instanceof THREE.Texture) discardedTextures.add(texture);
+        textured[slot] = null;
+      }
+      material.needsUpdate = true;
+    }
+  });
+  for (const texture of discardedTextures) texture.dispose();
+
+  if (settings.animations.length > 0) {
+    const requested = new Set(settings.animations);
+    const selected = object.animations.filter((clip) => requested.has(clip.name));
+    const missing = settings.animations.filter(
+      (name) => !selected.some((clip) => clip.name === name),
+    );
+    if (missing.length > 0) throw new Error(`Animation clips not found: ${missing.join(', ')}.`);
+    object.animations = selected;
+  }
+  object.updateWorldMatrix(true, true);
+}
+
+function sourceUnitScale(units: AssetImportSettings['sourceUnits']): number {
+  return { auto: 1, mm: 0.001, cm: 0.01, m: 1, in: 0.0254, ft: 0.3048 }[units];
+}
+
+function importAxisRotation(
+  upAxis: AssetImportSettings['upAxis'],
+  forwardAxis: AssetImportSettings['forwardAxis'],
+): THREE.Quaternion {
+  const up = upAxis === 'auto' ? null : axisVector(upAxis);
+  const forward = forwardAxis === 'auto' ? null : axisVector(forwardAxis);
+  if (up && forward) {
+    if (Math.abs(up.dot(forward)) > 0.001)
+      throw new Error('Import up and forward axes must be perpendicular.');
+    const right = new THREE.Vector3().crossVectors(forward, up).normalize();
+    const correctedForward = new THREE.Vector3().crossVectors(up, right).normalize();
+    const sourceBasis = new THREE.Matrix4().makeBasis(right, up, correctedForward.clone().negate());
+    return new THREE.Quaternion().setFromRotationMatrix(sourceBasis.invert());
+  }
+  if (up) return new THREE.Quaternion().setFromUnitVectors(up, new THREE.Vector3(0, 1, 0));
+  if (forward)
+    return new THREE.Quaternion().setFromUnitVectors(forward, new THREE.Vector3(0, 0, -1));
+  return new THREE.Quaternion();
+}
+
+function axisVector(axis: Exclude<AssetImportSettings['forwardAxis'], 'auto'> | 'x' | 'y' | 'z') {
+  const sign = axis.startsWith('-') ? -1 : 1;
+  const name = axis.replace('-', '');
+  return new THREE.Vector3(
+    name === 'x' ? sign : 0,
+    name === 'y' ? sign : 0,
+    name === 'z' ? sign : 0,
+  );
+}
+
+async function parseSourceModel(
+  primaryPath: string,
+  format: string,
+  bytes: Uint8Array,
+): Promise<THREE.Object3D> {
+  const resourcePath = `${dirname(primaryPath)}/`;
+  switch (format) {
+    case 'fbx':
+      return new FBXLoader().parse(bytes.buffer as ArrayBuffer, resourcePath);
+    case 'obj': {
+      const loader = new OBJLoader();
+      const materialPath = primaryPath.replace(/\.obj$/i, '.mtl');
+      try {
+        const materials = new MTLLoader().parse(await readFile(materialPath, 'utf8'), resourcePath);
+        materials.preload();
+        loader.setMaterials(materials);
+      } catch {
+        // Geometry-only OBJ conversion remains valid when no MTL is present.
+      }
+      return loader.parse(new TextDecoder().decode(bytes));
+    }
+    case 'dae': {
+      return new ColladaLoader().parse(new TextDecoder().decode(bytes), resourcePath).scene;
+    }
+    case 'stl': {
+      const geometry = new STLLoader().parse(bytes.buffer as ArrayBuffer);
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({ color: 0x8fb5da, roughness: 0.75 }),
+      );
+    }
+    case 'ply': {
+      const geometry = new PLYLoader().parse(bytes.buffer as ArrayBuffer);
+      if (!geometry.hasAttribute('normal')) geometry.computeVertexNormals();
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({
+          color: geometry.hasAttribute('color') ? 0xffffff : 0xb8d09b,
+          vertexColors: geometry.hasAttribute('color'),
+          roughness: 0.8,
+          side: THREE.DoubleSide,
+        }),
+      );
+    }
+    case '3ds':
+      return new TDSLoader().parse(bytes.buffer as ArrayBuffer, resourcePath);
+    default:
+      throw new Error(`Built-in conversion does not support ${format || extname(primaryPath)}.`);
+  }
+}
+
+/** Three's source loaders construct browser image elements even when the
+ * conversion runs in Node. JSDOM supplies that parser boundary; unresolved
+ * asynchronous images are removed below rather than passed to GLTFExporter
+ * as invalid zero-sized image objects. */
+function installNodeDom(): void {
+  if (typeof document !== 'undefined' && typeof DOMParser !== 'undefined') return;
+  const { JSDOM } = createRequire(import.meta.url)('jsdom') as {
+    JSDOM: new () => {
+      window: {
+        document: Document;
+        DOMParser: typeof DOMParser;
+        HTMLImageElement: typeof HTMLImageElement;
+        HTMLCanvasElement: typeof HTMLCanvasElement;
+        Image: typeof Image;
+      };
+    };
+  };
+  const window = new JSDOM().window;
+  Object.assign(globalThis, {
+    document: window.document,
+    DOMParser: window.DOMParser,
+    HTMLImageElement: window.HTMLImageElement,
+    HTMLCanvasElement: window.HTMLCanvasElement,
+    Image: window.Image,
+  });
+}
+
+function discardUnloadedTextures(root: THREE.Object3D): void {
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one bounded traversal removes only unresolved image slots across every supported material shape.
+  root.traverse((object) => {
+    const mesh = object as THREE.Mesh;
+    const materials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+    for (const material of materials) {
+      const textured = material as THREE.Material & Record<string, unknown>;
+      for (const slot of materialTextureSlots) {
+        const value = textured[slot];
+        if (!(value instanceof THREE.Texture)) continue;
+        const image = value.image as { width?: number; height?: number } | null;
+        if (image && (image.width ?? 0) > 0 && (image.height ?? 0) > 0) continue;
+        textured[slot] = null;
+        value.dispose();
+      }
+      material.needsUpdate = true;
+    }
+  });
+}
+
+async function validateConvertedGlb(bytes: Uint8Array): Promise<void> {
+  const parsed = await new GLTFLoader().parseAsync(Uint8Array.from(bytes).buffer, '');
+  let renderable = false;
+  parsed.scene.traverse((object) => {
+    renderable ||= Boolean((object as THREE.Mesh).isMesh || (object as THREE.Points).isPoints);
+  });
+  disposeObject(parsed.scene);
+  if (!renderable && parsed.animations.length === 0) {
+    throw new Error('Converted GLB contains neither renderable geometry nor animation clips.');
+  }
+}
+
+function installNodeFileReader(): void {
+  if (typeof FileReader !== 'undefined') return;
+  class NodeFileReader {
+    result: string | ArrayBuffer | null = null;
+    error: Error | null = null;
+    onloadend: ((event: ProgressEvent<FileReader>) => void) | null = null;
+    onerror: ((event: ProgressEvent<FileReader>) => void) | null = null;
+    readAsArrayBuffer(blob: Blob): void {
+      void blob.arrayBuffer().then(
+        (result) => {
+          this.result = result;
+          this.onloadend?.({ target: this } as unknown as ProgressEvent<FileReader>);
+        },
+        (error) => {
+          this.error = error instanceof Error ? error : new Error(String(error));
+          this.onerror?.({ target: this } as unknown as ProgressEvent<FileReader>);
+        },
+      );
+    }
+    readAsDataURL(blob: Blob): void {
+      void blob.arrayBuffer().then((result) => {
+        this.result = `data:${blob.type || 'application/octet-stream'};base64,${Buffer.from(result).toString('base64')}`;
+        this.onloadend?.({ target: this } as unknown as ProgressEvent<FileReader>);
+      });
+    }
+  }
+  Object.assign(globalThis, { FileReader: NodeFileReader });
+}
+
+function disposeObject(root: THREE.Object3D): void {
+  root.traverse((object) => {
+    const renderable = object as THREE.Mesh;
+    renderable.geometry?.dispose();
+    const materials = Array.isArray(renderable.material)
+      ? renderable.material
+      : renderable.material
+        ? [renderable.material]
+        : [];
+    for (const material of materials) {
+      for (const value of Object.values(material))
+        if (value instanceof THREE.Texture) value.dispose();
+      material.dispose();
+    }
+  });
+}

package/server/native-credential-store.ts

@@ -0,0 +1,162 @@
+export type CredentialPersistence = 'system' | 'session';
+
+export interface NativeCredentialStore {
+  persistence(): Promise<CredentialPersistence>;
+  read(account: string): Promise<string | null>;
+  write(account: string, value: string): Promise<void>;
+  delete(account: string): Promise<void>;
+}
+
+/**
+ * Normalized per-credential handle over `@napi-rs/keyring`'s `AsyncEntry` /
+ * `Entry` classes. Restores keytar's calmer contract: a missing credential is
+ * `null` / `false`, never an error.
+ */
+interface KeyringEntry {
+  getPassword(): Promise<string | null>;
+  setPassword(value: string): Promise<void>;
+  deletePassword(): Promise<boolean>;
+}
+
+type KeyringEntryFactory = (service: string, account: string) => KeyringEntry;
+
+type KeyringLoader = () => Promise<unknown>;
+
+interface RawKeyringEntry {
+  getPassword(): unknown;
+  setPassword(value: string): unknown;
+  deleteCredential?(): unknown;
+  deletePassword?(): unknown;
+}
+
+type RawEntryConstructor = new (service: string, account: string) => RawKeyringEntry;
+
+/**
+ * `keyring-rs` reports an absent credential as a NoEntry error. Message text
+ * varies by binding/version: keyring-rs v2/v3 says "No matching entry found
+ * in secure storage", while the actually-shipped `@napi-rs/keyring@^1.3.0`
+ * native binary says "No matching credential found" (confirmed via `strings`
+ * on the installed binary). keytar returned `null`/`false` for the same
+ * situation; treat NoEntry as "not found", not as a broken credential manager,
+ * regardless of which wording the binding uses.
+ */
+function isNoEntryError(error: unknown): boolean {
+  return error instanceof Error && /no matching (entry|credential)/i.test(error.message);
+}
+
+function keyringApi(module: unknown): KeyringEntryFactory | null {
+  if (!module || typeof module !== 'object') return null;
+  const imported = module as Record<string, unknown>;
+  const candidate =
+    imported['default'] && typeof imported['default'] === 'object'
+      ? (imported['default'] as Record<string, unknown>)
+      : imported;
+  // Prefer AsyncEntry (does not block the event loop); accept sync Entry too.
+  const EntryConstructor = [candidate['AsyncEntry'], candidate['Entry']].find(
+    (value): value is RawEntryConstructor =>
+      typeof value === 'function' &&
+      typeof (value as { prototype?: Record<string, unknown> }).prototype?.['getPassword'] ===
+        'function' &&
+      typeof (value as { prototype?: Record<string, unknown> }).prototype?.['setPassword'] ===
+        'function',
+  );
+  if (!EntryConstructor) return null;
+  return (service, account) => {
+    const entry = new EntryConstructor(service, account);
+    return {
+      async getPassword() {
+        try {
+          const value = await entry.getPassword();
+          return typeof value === 'string' ? value : null;
+        } catch (error) {
+          if (isNoEntryError(error)) return null;
+          throw error;
+        }
+      },
+      async setPassword(value) {
+        await entry.setPassword(value);
+      },
+      async deletePassword() {
+        try {
+          const deleted =
+            typeof entry.deleteCredential === 'function'
+              ? await entry.deleteCredential()
+              : await entry.deletePassword?.();
+          return deleted !== false;
+        } catch (error) {
+          if (isNoEntryError(error)) return false;
+          throw error;
+        }
+      },
+    };
+  };
+}
+
+/**
+ * One editor-global secret boundary. Native builds use macOS Keychain,
+ * Windows Credential Manager, or Linux Secret Service through
+ * `@napi-rs/keyring`, the maintained native credential-store binding. A host
+ * without that optional dependency is deliberately session-only: it never
+ * turns a missing credential manager into a plaintext file.
+ */
+export function createNativeCredentialStore(
+  service = 'ai.vgai.editor',
+  loadKeyring: KeyringLoader = () => import('@napi-rs/keyring'),
+): NativeCredentialStore {
+  const memory = new Map<string, string>();
+  let modulePromise: Promise<KeyringEntryFactory | null> | undefined;
+  let degraded = false;
+  const keyring = () => {
+    modulePromise ??= loadKeyring()
+      .then(keyringApi)
+      .catch(() => null);
+    return modulePromise;
+  };
+
+  return {
+    async persistence() {
+      return (await keyring()) && !degraded ? 'system' : 'session';
+    },
+    async read(account) {
+      const native = await keyring();
+      if (native && !degraded) {
+        try {
+          const value = await native(service, account).getPassword();
+          if (value === null) memory.delete(account);
+          else memory.set(account, value);
+          return value;
+        } catch {
+          degraded = true;
+        }
+      }
+      return memory.get(account) ?? null;
+    },
+    async write(account, value) {
+      const native = await keyring();
+      if (native && !degraded) {
+        try {
+          await native(service, account).setPassword(value);
+          memory.set(account, value);
+          return;
+        } catch {
+          degraded = true;
+        }
+      }
+      memory.set(account, value);
+    },
+    async delete(account) {
+      const native = await keyring();
+      if (native) {
+        try {
+          await native(service, account).deletePassword();
+        } catch {
+          degraded = true;
+          throw new Error(
+            'The native credential manager could not confirm that the credential was deleted.',
+          );
+        }
+      }
+      memory.delete(account);
+    },
+  };
+}

package/server/open-browser.ts

@@ -0,0 +1,118 @@
+/**
+ * THE platform browser hand-off — the one open ladder (darwin / win32 / WSL
+ * explorer.exe→powershell.exe / xdg-open), owned here because the editor
+ * server must keep maintaining its tab (tab-bijection self-heal,
+ * ensure-driven opens) long after any launching CLI process has exited. The
+ * CLI imports this module; it does not carry its own copy — the old
+ * "no editor-package dependency" premise stopped being true when the CLI
+ * grew six editor-server imports and an `@vgai/editor` dependency, and the
+ * two ladders had already drifted (`-g` background support on one side
+ * only).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnOpener } from './spawn-opener';
+
+function isWSL(): boolean {
+  if (process.platform !== 'linux') return false;
+  try {
+    return readFileSync('/proc/version', 'utf8').toLowerCase().includes('microsoft');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The path segment that identifies a session rooted in an AGENT's git
+ * worktree. Agents take one of these before they write code
+ * (docs/LOCAL-DEV.md), so it is the one honest, always-present signal that a
+ * tab belongs to a background builder rather than to the person at the
+ * keyboard.
+ */
+const AGENT_WORKTREE_MARKER = '/.claude/worktrees/';
+
+/** Env override for the placement decision (`1` background, `0` foreground). */
+export const TAB_BACKGROUND_ENV = 'VGAI_TAB_BACKGROUND';
+
+export interface TabOpenPlacementInput {
+  /**
+   * The session's project root, ALREADY symlink-resolved
+   * (`canonicalProjectRoot`) — the marker check is on the real path, because
+   * a worktree reached through a symlinked parent would otherwise read as a
+   * human checkout.
+   */
+  readonly projectRoot: string | null | undefined;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * Decide whether this session's ONE tab should open behind the human's
+ * current window instead of stealing focus.
+ *
+ * Measured (owner, three times in one day): every builder/reviewer `vgai edit`
+ * auto-opened a FOREGROUND tab on the one display, so the owner kept ending up
+ * looking at an agent's session instead of their own. A session rooted in an
+ * agent worktree therefore opens in the BACKGROUND; the human flow — a normal
+ * checkout, or a scaffolded game anywhere else — keeps foreground, because for
+ * a person the whole point of `vgai edit` is that the editor comes up in front
+ * of them.
+ *
+ * `VGAI_TAB_BACKGROUND` overrides in BOTH directions: `1` backgrounds a tab
+ * that would have been foreground, `0` foregrounds one inside a worktree (an
+ * agent deliberately showing the owner something).
+ *
+ * Pure: the caller supplies the resolved root and the environment.
+ */
+export function shouldOpenTabInBackground(input: TabOpenPlacementInput): boolean {
+  const override = input.env[TAB_BACKGROUND_ENV];
+  if (override !== undefined && override !== '') {
+    return override !== '0' && override.toLowerCase() !== 'false';
+  }
+  const root = input.projectRoot;
+  if (root === null || root === undefined || root === '') return false;
+  return root.replaceAll('\\', '/').includes(AGENT_WORKTREE_MARKER);
+}
+
+export interface OpenBrowserUrlOptions {
+  /**
+   * Open behind the frontmost window instead of activating the browser.
+   * Honored on macOS only (`open -g`) — Windows `start` and `xdg-open` have no
+   * portable equivalent, so every other platform keeps its existing
+   * focus-stealing behavior rather than getting a half-kept promise.
+   */
+  readonly background?: boolean;
+}
+
+/** Best-effort open of `browserUrl` in the platform default browser. */
+export function openBrowserUrl(browserUrl: string, options?: OpenBrowserUrlOptions): void {
+  if (process.platform === 'darwin') {
+    // `-g` = do not bring the opened application to the foreground. The tab
+    // still opens, still loads, and still registers with the bijection — it
+    // just does not seize the display.
+    spawnOpener('open', options?.background === true ? ['-g', browserUrl] : [browserUrl]);
+  } else if (process.platform === 'win32') {
+    // `start` is a cmd builtin, not an executable — it needs cmd itself.
+    spawnOpener('cmd', ['/c', 'start', '', browserUrl]);
+  } else if (isWSL()) {
+    // WSL has no display of its own; hand the URL to the Windows side. A dead
+    // interop socket (stale background session) means no Windows .exe can
+    // launch — name it instead of failing silently.
+    const interop = process.env['WSL_INTEROP'];
+    if (interop && !existsSync(interop)) {
+      console.error(
+        `[vgai-editor] cannot open a browser from this shell — the WSL interop socket ` +
+          `(${interop}) is gone, so Windows executables cannot launch. Open ${browserUrl} ` +
+          'from any regular terminal or browser instead.',
+      );
+      return;
+    }
+    // Explorer is the direct Windows shell-association path. Start-Process
+    // can exit zero even when a transient browser process fails to forward
+    // the URL to the existing browser, so PowerShell is the fallback.
+    spawnOpener('explorer.exe', [browserUrl], () =>
+      spawnOpener('powershell.exe', ['-NoProfile', '-Command', `Start-Process '${browserUrl}'`]),
+    );
+  } else {
+    spawnOpener('xdg-open', [browserUrl]);
+  }
+}