@vgai/editor 0.2.0

package/server/editor-sse.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared SSE (Server-Sent Events) broadcast for editor plugins.
+ *
+ * Both the asset browser and Colyseus plugins use this to push
+ * real-time events to the editor client via /__editor/events.
+ */
+
+import type { ServerResponse } from 'node:http';
+
+const sseClients = new Set<ServerResponse>();
+
+const KEEPALIVE_MS = 15_000;
+let keepaliveTimer: ReturnType<typeof setInterval> | null = null;
+
+/** Write to a client, removing it from the pool if the socket is dead. */
+function writeOrDrop(client: ServerResponse, msg: string): void {
+  try {
+    // `writableEnded` guards against writing to a closed stream.
+    if (client.writableEnded) {
+      sseClients.delete(client);
+      return;
+    }
+    client.write(msg);
+  } catch {
+    // SC3: one dead client must not abort the broadcast loop.
+    sseClients.delete(client);
+  }
+}
+
+/** Start the keepalive ticker once at least one client is connected. */
+function ensureKeepalive(): void {
+  if (keepaliveTimer || sseClients.size === 0) return;
+  keepaliveTimer = setInterval(() => {
+    if (sseClients.size === 0) {
+      stopKeepalive();
+      return;
+    }
+    for (const client of sseClients) writeOrDrop(client, ':keepalive\n\n');
+  }, KEEPALIVE_MS);
+  // Don't keep the process alive solely for the heartbeat.
+  keepaliveTimer.unref?.();
+}
+
+function stopKeepalive(): void {
+  if (keepaliveTimer) {
+    clearInterval(keepaliveTimer);
+    keepaliveTimer = null;
+  }
+}
+
+/** Send an SSE event to all connected editor clients. */
+export function broadcast(event: string, data: unknown): void {
+  const msg = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+  // Snapshot so deletions during iteration are safe.
+  for (const client of [...sseClients]) writeOrDrop(client, msg);
+}
+
+/** Add an SSE client connection. Call from the /__editor/events handler. */
+export function addClient(res: ServerResponse): void {
+  sseClients.add(res);
+  ensureKeepalive();
+}
+
+/** Remove an SSE client connection. Call on request close. */
+export function removeClient(res: ServerResponse): void {
+  sseClients.delete(res);
+  if (sseClients.size === 0) stopKeepalive();
+}
+
+/** Number of currently-connected clients (exposed for tests). */
+export function clientCount(): number {
+  return sseClients.size;
+}

package/server/game-globals-shadow.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure predicate for the `vgai-game-globals` Vite plugin in `dev.ts` — split
+ * out into its own side-effect-free module so it's unit-testable without
+ * booting Vite/Express (`dev.ts`'s module top-level calls `main()`, which
+ * starts real servers — importing it directly in a test would do that).
+ *
+ * R2c (docs/MASTER-ARCHITECTURE-REVIEW.md §7.1 item 10): the prelude used to
+ * be scoped to `projectRoots` alone (an opened project's own `/src/`), which
+ * covers first-party project code and play-mode's game examples but NOT the
+ * in-tree ingest fixtures' same-realm `shared`/`deduped`-strategy entry
+ * modules — those live under this EDITOR PACKAGE's own
+ * `packages/editor/src/ingest/games/**` (three.js) and
+ * `packages/editor/src/ingest/games-2d/**` (PixiJS) trees, which
+ * `ingest/discovery.ts`/`discovery2d.ts` pull into the SAME Vite module graph
+ * via `import.meta.glob` (they are ordinary `/src/` modules Vite already
+ * knows about statically — not an external project folder), so they were
+ * served UNSHADOWED: a vendored game's raw `window`/`document` input
+ * listeners ran for its entire mount regardless of editor focus. The
+ * `iframe-reachable`/`opaque-embed` ingest tiers are NOT in scope here — they
+ * run in a separate browsing context (a real iframe) and never resolve to
+ * this shadow at all, shadowed or not.
+ */
+import path from 'node:path';
+
+/**
+ * The two same-realm ingest-fixture roots, given this editor package's own
+ * `src/` directory. Fixed (not runtime-discovered) — these folders are part
+ * of THIS package's source tree, not a project a user opens.
+ */
+export function ingestGameShadowRoots(editorSrcRoot: string): string[] {
+  return [
+    path.resolve(editorSrcRoot, 'ingest/games'),
+    path.resolve(editorSrcRoot, 'ingest/games-2d'),
+  ];
+}
+
+/**
+ * True if `file` is a `/src/` TS/JS module — the shape the prelude assumes
+ * (a lexically-scoped `const window=…,document=…;` prepended to the top of
+ * the module body; see `gated-globals.ts`'s doc comment for why that's safe
+ * even ahead of the module's own `import` statements).
+ */
+export function isShadowableModulePath(file: string): boolean {
+  return /\.(ts|tsx|js|jsx)$/.test(file) && file.includes('/src/');
+}
+
+/**
+ * True if `file` should get the `GAME_GLOBALS_PRELUDE` shadow prepended:
+ * a shadowable module path under any of `roots` (an opened project's root,
+ * or one of {@link ingestGameShadowRoots}).
+ */
+export function shouldShadowGameGlobals(file: string, roots: Iterable<string>): boolean {
+  if (!isShadowableModulePath(file)) return false;
+  for (const root of roots) {
+    if (file.startsWith(root)) return true;
+  }
+  return false;
+}

package/server/local-asset-catalog.ts

@@ -0,0 +1,163 @@
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isPathInside } from './server-utils';
+
+export const DEFAULT_LOCAL_ASSET_LIBRARY_ROOT = '/Volumes/PeakSSD/vgai-asset-library';
+export const REPOSITORY_ASSET_CATALOG_PATH = fileURLToPath(
+  new URL('../../../catalog/asset-library/catalog.json', import.meta.url),
+);
+
+export type LocalAssetType = 'model' | 'animation' | 'source';
+
+export interface LocalAssetFile {
+  label: string;
+  path: string;
+  format: string;
+  sizeBytes: number;
+  dependencies?: string[];
+}
+
+export interface LocalCatalogAsset {
+  id: string;
+  source: string;
+  name: string;
+  type: LocalAssetType;
+  categories: string[];
+  tags: string[];
+  license: string;
+  author: string;
+  sourceUrl: string;
+  thumbnail?: string;
+  files: LocalAssetFile[];
+  animationCount?: number;
+  clipNames?: string[];
+}
+
+export interface LocalAssetCatalog {
+  version: 1;
+  generatedAt: string;
+  assets: LocalCatalogAsset[];
+}
+
+export function getLocalAssetLibraryRoot(): string {
+  return resolve(process.env['VGAI_ASSET_LIBRARY_ROOT'] ?? DEFAULT_LOCAL_ASSET_LIBRARY_ROOT);
+}
+
+export function getLocalCatalogPath(root = getLocalAssetLibraryRoot()): string {
+  return resolve(root, 'catalog', 'catalog.json');
+}
+
+export async function resolveLocalCatalogPath(
+  root = getLocalAssetLibraryRoot(),
+): Promise<string> {
+  const externalPath = getLocalCatalogPath(root);
+  try {
+    await stat(externalPath);
+    return externalPath;
+  } catch {
+    return REPOSITORY_ASSET_CATALOG_PATH;
+  }
+}
+
+let cachedCatalog: LocalAssetCatalog | null = null;
+let cachedPath = '';
+let cachedMtimeMs = -1;
+
+export async function loadLocalAssetCatalog(
+  root = getLocalAssetLibraryRoot(),
+): Promise<LocalAssetCatalog> {
+  const catalogPath = await resolveLocalCatalogPath(root);
+  const catalogStat = await stat(catalogPath);
+  if (cachedCatalog && cachedPath === catalogPath && cachedMtimeMs === catalogStat.mtimeMs) {
+    return cachedCatalog;
+  }
+
+  const parsed = JSON.parse(await readFile(catalogPath, 'utf8')) as LocalAssetCatalog;
+  if (parsed.version !== 1 || !Array.isArray(parsed.assets)) {
+    throw new Error(`Unsupported local asset catalog at ${catalogPath}`);
+  }
+  cachedCatalog = parsed;
+  cachedPath = catalogPath;
+  cachedMtimeMs = catalogStat.mtimeMs;
+  return parsed;
+}
+
+export async function findLocalAsset(
+  id: string,
+  root = getLocalAssetLibraryRoot(),
+): Promise<LocalCatalogAsset | null> {
+  const catalog = await loadLocalAssetCatalog(root);
+  return catalog.assets.find((asset) => asset.id === id) ?? null;
+}
+
+export function localAssetMatchesType(asset: LocalCatalogAsset, type?: string): boolean {
+  const normalizedType = type === 'all' ? undefined : type?.replace(/s$/, '');
+  if (!normalizedType) return true;
+  if (normalizedType === 'animation') {
+    return (
+      asset.type === 'animation' ||
+      asset.tags.includes('animation') ||
+      asset.tags.includes('animated')
+    );
+  }
+  return asset.type === normalizedType;
+}
+
+export function resolveCatalogFile(root: string, relativePath: string): string {
+  const absolutePath = resolve(root, relativePath);
+  if (!isPathInside(root, absolutePath)) {
+    throw new Error(`Catalog path escapes the asset library: ${relativePath}`);
+  }
+  return absolutePath;
+}
+
+export function searchLocalCatalog(
+  catalog: LocalAssetCatalog,
+  options: { q?: string; type?: string; category?: string; offset?: number; limit?: number },
+): { assets: LocalCatalogAsset[]; total: number } {
+  const queryTokens = (options.q ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+  const category = options.category?.toLowerCase();
+  const type = options.type === 'all' ? undefined : options.type;
+
+  const matches = catalog.assets.filter((asset) => {
+    if (!localAssetMatchesType(asset, type)) return false;
+    if (category && !asset.categories.some((value) => value.toLowerCase() === category)) {
+      return false;
+    }
+    if (queryTokens.length === 0) return true;
+    const haystack = [
+      asset.name,
+      asset.source,
+      asset.author,
+      asset.license,
+      ...asset.categories,
+      ...asset.tags,
+      ...(asset.clipNames ?? []),
+    ]
+      .join(' ')
+      .toLowerCase();
+    return queryTokens.every((token) => haystack.includes(token));
+  });
+
+  const offset = Math.max(0, options.offset ?? 0);
+  const limit = Math.min(200, Math.max(1, options.limit ?? 48));
+  return { assets: matches.slice(offset, offset + limit), total: matches.length };
+}
+
+export function localAssetSlug(asset: LocalCatalogAsset): string {
+  const base = asset.name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  return `${base || 'asset'}-${asset.id.slice(0, 8)}`;
+}
+
+export function makeLocalAssetId(source: string, key: string): string {
+  return createHash('sha256').update(`${source}\0${key}`).digest('hex').slice(0, 24);
+}
+
+export function catalogFormat(path: string): string {
+  return extname(path).slice(1).toLowerCase() || 'bin';
+}