@forgeax/engine-remote 0.1.2

package/src/__tests__/console.unit.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { startServer } from '../server';
+
+describe('remote console server', () => {
+  it('starts and disposes the eval server without a second command surface', async () => {
+    const result = await startServer({ port: 0, host: '127.0.0.1', world: {} });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.port).toBeGreaterThan(0);
+    await result.value.close();
+  });
+});

package/src/__tests__/errors.unit.test.ts

@@ -0,0 +1,102 @@
+// w11: RemoteErrorCode completeness unit test (5-member closed union).
+// Verifies that the error-code family has exactly 5 members after
+// deleting inspector-write-denied + script-timeout in w7.
+
+import { describe, expect, it } from 'vitest';
+import { REMOTE_ERROR_CODE_TO_JSONRPC, RemoteError, type RemoteErrorCode } from '../errors';
+
+const EXPECTED_MEMBERS: readonly RemoteErrorCode[] = [
+  'script-syntax-error',
+  'script-runtime-error',
+  'server-startup-failed',
+  'server-not-running',
+  'eval-result-not-serializable',
+];
+
+describe('RemoteErrorCode closed union — 5-member completeness', () => {
+  it('REMOTE_ERROR_CODE_TO_JSONRPC has exactly 5 keys matching the expected set', () => {
+    const keys = Object.keys(REMOTE_ERROR_CODE_TO_JSONRPC) as RemoteErrorCode[];
+    expect(keys).toHaveLength(5);
+    // Sort-stable comparison — order is incidental
+    expect([...keys].sort()).toStrictEqual([...EXPECTED_MEMBERS].sort());
+  });
+
+  it('no inspector-write-denied residue', () => {
+    expect(
+      REMOTE_ERROR_CODE_TO_JSONRPC['inspector-write-denied' as RemoteErrorCode],
+    ).toBeUndefined();
+  });
+
+  it('no script-timeout residue', () => {
+    expect(REMOTE_ERROR_CODE_TO_JSONRPC['script-timeout' as RemoteErrorCode]).toBeUndefined();
+  });
+
+  for (const code of EXPECTED_MEMBERS) {
+    it(`REMOTE_ERROR_CODE_TO_JSONRPC[${JSON.stringify(code)}] is a number`, () => {
+      expect(typeof REMOTE_ERROR_CODE_TO_JSONRPC[code]).toBe('number');
+    });
+  }
+});
+
+describe('RemoteError construction + toJSON', () => {
+  it('constructs with the core structured fields', () => {
+    const err = new RemoteError({
+      code: 'script-syntax-error',
+      expected: 'valid JS',
+      hint: 'fix it',
+    });
+    expect(err.code).toBe('script-syntax-error');
+    expect(err.expected).toBe('valid JS');
+    expect(err.hint).toBe('fix it');
+    expect(err.message).toContain('[RemoteError script-syntax-error]');
+  });
+
+  it('toJSON() returns the core plain object when detail is absent', () => {
+    const err = new RemoteError({
+      code: 'server-not-running',
+      expected: 'server reachable',
+      hint: 'start demo',
+    });
+    const json = err.toJSON();
+    expect(json).toStrictEqual({
+      code: 'server-not-running',
+      expected: 'server reachable',
+      hint: 'start demo',
+      message: err.message,
+    });
+  });
+
+  it('server-startup-failed carries descriptive hint', () => {
+    const err = new RemoteError({
+      code: 'server-startup-failed',
+      expected: 'server starts',
+      hint: 'port occupied',
+    });
+    expect(err.code).toBe('server-startup-failed');
+    expect(err.hint).toBe('port occupied');
+  });
+
+  it('script-runtime-error carries error context', () => {
+    const err = new RemoteError({
+      code: 'script-runtime-error',
+      expected: 'script executes',
+      hint: 'check symbols',
+    });
+    expect(err.code).toBe('script-runtime-error');
+    expect(err.expected).toBe('script executes');
+  });
+
+  it('toJSON retains only the bounded result-shape detail', () => {
+    const err = new RemoteError({
+      code: 'eval-result-not-serializable',
+      expected: 'eval result is JSON-serializable',
+      hint: 'return a JSON-safe value',
+      detail: { code: 'eval-result-not-serializable', shape: 'cyclic-object' },
+    });
+    expect(err.toJSON()).toMatchObject({
+      code: 'eval-result-not-serializable',
+      detail: { code: 'eval-result-not-serializable', shape: 'cyclic-object' },
+    });
+    expect(JSON.stringify(err)).not.toContain('privateMarker');
+  });
+});

package/src/__tests__/execute-browser-safe.unit.test.ts

@@ -0,0 +1,43 @@
+// @forgeax/engine-remote/src/__tests__/execute-browser-safe — the ./execute
+// subpath is the eval core reused by the browser remote-live bridge (createApp
+// dials a loopback relay; the page realm runs executeScript directly because a
+// browser cannot bind a Node WS server). It MUST stay ws-free / node-built-in-
+// free at the SOURCE level, else importing it in a browser bundle throws on the
+// `ws` browser shim (WebSocketServer unsupported) — the exact failure that
+// makes app.remote silently undefined in a real dev browser today.
+//
+// Guarding the source (not the dist bundle) keeps this test runnable in the
+// unit project without a prior build step, and pins the invariant at the layer
+// a human would break it (adding an import to execute.ts).
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const EXECUTE_SRC = fileURLToPath(new URL('../execute.ts', import.meta.url));
+
+describe('execute.ts browser safety (remote-live bridge)', () => {
+  const source = readFileSync(EXECUTE_SRC, 'utf8');
+  // Match only real import statements, not prose in comments.
+  const importLines = source
+    .split('\n')
+    .filter((line) => /^\s*import\b/.test(line) || /^\s*}\s*from\s*['"]/.test(line));
+
+  it('imports no ws package', () => {
+    expect(importLines.some((l) => /['"]ws['"]/.test(l))).toBe(false);
+  });
+
+  it('imports no node: built-in', () => {
+    expect(importLines.some((l) => /['"]node:/.test(l))).toBe(false);
+  });
+
+  it('imports only its sibling error module', () => {
+    // The single permitted runtime import is `./errors` (types-only chain).
+    const fromClauses = importLines
+      .map((l) => l.match(/from\s*['"]([^'"]+)['"]/)?.[1])
+      .filter((s): s is string => typeof s === 'string');
+    for (const spec of fromClauses) {
+      expect(spec).toBe('./errors');
+    }
+  });
+});

package/src/__tests__/execute-profiler-root.browser.test.ts

@@ -0,0 +1,41 @@
+import { createProfiler } from '@forgeax/engine-profiler';
+import { describe, expect, it } from 'vitest';
+
+import { executeScript } from '../execute';
+
+describe('browser-safe execute profiler root', () => {
+  it('runs a bounded capture start through the same eval core', async () => {
+    const profiler = createProfiler();
+    const result = await executeScript('profiler.startCapture({ frameLimit: 1, eventLimit: 8 })', {
+      world: {},
+      renderer: {},
+      assets: {},
+      profiler,
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: { ok: true, value: { captureId: 'capture-0001' } },
+    });
+  });
+
+  it('allows the page to return a structured not-enabled result without a transport error', async () => {
+    const result = await executeScript(
+      "typeof profiler === 'undefined' ? { ok: false, error: { code: 'profiler-not-enabled', expected: 'an opted-in profiler root', hint: 'Pass profiler to createApp.', detail: { enabled: false } } } : null",
+      { world: {}, renderer: {}, assets: {} },
+    );
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: {
+        ok: false,
+        error: {
+          code: 'profiler-not-enabled',
+          expected: expect.any(String),
+          hint: expect.any(String),
+          detail: { enabled: false },
+        },
+      },
+    });
+  });
+});

package/src/__tests__/execute.async.test.ts

@@ -0,0 +1,369 @@
+// @forgeax/engine-remote/src/__tests__/execute.async.test.ts
+// TDD green-phase tests for async executeScript (w5):
+//   w1 — async read of world/renderer/assets state
+//   w2 — async write without sandbox interception (route B, no inspector-write-denied)
+//   w3 — _import('@forgeax/engine-ecs') + World.query discovery
+//
+// Route B (D-1): host realm eval via new Function with injected _import.
+// Scripts that need dynamic import use the _import parameter:
+//   const ecs = await _import('@forgeax/engine-ecs');
+// Simple expressions return value directly.
+// No wrapReadOnly, no timeout. inspector-write-denied and script-timeout
+// error codes deleted per D-5, not in RemoteErrorCode union.
+
+import { describe, expect, it } from 'vitest';
+import { executeScript } from '../execute';
+
+// ── Mock world ──────────────────────────────────────────────────────────────
+
+function makeMockWorld() {
+  const state: unknown[] = [];
+  return {
+    inspect(): { entityCount: number } {
+      return { entityCount: state.length + 5 };
+    },
+    push(item: unknown): unknown[] {
+      state.push(item);
+      return state;
+    },
+    getList(): unknown[] {
+      return [...state];
+    },
+    getState() {
+      return { entityCount: state.length + 5, pushedCount: state.length };
+    },
+  };
+}
+
+const mockRenderer = {
+  isReady: true,
+  dispose() {
+    /* no-op */
+  },
+};
+const mockAssets = {
+  load(guid: string, expectedKind: string) {
+    return Promise.resolve({ ok: true, value: { guid, kind: expectedKind } });
+  },
+  snapshot() {
+    return { scopeId: 'test-scope', generation: 1, entries: [] };
+  },
+  subscribe() {
+    return () => {};
+  },
+};
+
+function makeCtx() {
+  return {
+    world: makeMockWorld(),
+    renderer: mockRenderer,
+    assets: mockAssets,
+  };
+}
+
+/** Wrap script in async IIFE with _import injection. */
+function aw(script: string): string {
+  return `(async () => {\n${script}\n})()`;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// w1: async read
+// ────────────────────────────────────────────────────────────────────────────
+
+describe('executeScript async - read (w1)', () => {
+  it('reads world.inspect() entity count', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('world.inspect().entityCount', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(5);
+    }
+  });
+
+  it('reads renderer.isReady from context', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('renderer.isReady', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(true);
+    }
+  });
+
+  it('reads the AssetRegistry snapshot', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('assets.snapshot().generation', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(1);
+    }
+  });
+
+  it('returns script-syntax-error on malformed expression', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('world.inspect((', ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('script-syntax-error');
+    }
+  });
+
+  it('returns script-runtime-error on throw', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('throw new Error("boom")', ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('script-runtime-error');
+    }
+  });
+
+  it('NO script-timeout: error code deleted from RemoteErrorCode (route B, no timeout)', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('throw new Error("x")', ctx);
+    if (!result.ok) {
+      expect(result.error.code).not.toBe('script-timeout');
+    }
+  });
+
+  it('await + setTimeout works via async IIFE wrapping', async () => {
+    const ctx = makeCtx();
+    const script = aw('await new Promise(r => setTimeout(r, 20)); return 42;');
+    const result = await executeScript(script, ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(42);
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// w2: async write — no inspector-write-denied (sandbox dismantled)
+// ────────────────────────────────────────────────────────────────────────────
+
+describe('executeScript async - write (w2)', () => {
+  it('world.push succeeds without inspector-write-denied', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('world.push(10)', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toEqual([10]);
+    }
+  });
+
+  it('write-then-read: push modifies state, persists across evals', async () => {
+    const ctx = makeCtx();
+
+    // Contract (round 20260713-124956): the script is an async function body,
+    // so a MULTI-statement script uses an explicit `return` for its value (a
+    // lone trailing expression is auto-returned; a statement list is not). This
+    // replaces the prior indirect-eval completion-value behavior — the trade
+    // that buys legal top-level `return` + `await`, which the docs already show.
+    const r1 = await executeScript('world.push(42); world.push(43); return world.getList()', ctx);
+    expect(r1.ok).toBe(true);
+    if (r1.ok) {
+      expect(r1.value).toEqual([42, 43]);
+    }
+
+    const r2 = await executeScript('world.getList()', ctx);
+    expect(r2.ok).toBe(true);
+    if (r2.ok) {
+      expect(r2.value).toEqual([42, 43]);
+    }
+  });
+
+  it('error code is NOT inspector-write-denied on write', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('world.push({})', ctx);
+    expect(result.ok).toBe(true);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// w3: _import in eval (route B — host realm, via async IIFE)
+// ────────────────────────────────────────────────────────────────────────────
+
+describe('executeScript async - _import (w3)', () => {
+  it('uses the context import resolver when a host supplies one', async () => {
+    const imported: string[] = [];
+    const result = await executeScript(
+      'const ecs = await _import("@forgeax/engine-ecs"); return ecs.name;',
+      {
+        ...makeCtx(),
+        importModule: async (specifier: string) => {
+          imported.push(specifier);
+          return { name: 'browser-resolved-ecs' };
+        },
+      },
+    );
+
+    expect(result).toEqual({ ok: true, value: 'browser-resolved-ecs' });
+    expect(imported).toEqual(['@forgeax/engine-ecs']);
+  });
+
+  it('_import(@forgeax/engine-ecs) resolves in eval', async () => {
+    const ctx = makeCtx();
+    const script = aw(
+      [
+        'const { World } = await _import("@forgeax/engine-ecs");',
+        'return typeof World.prototype.query === "function";',
+      ].join('\n'),
+    );
+    const result = await executeScript(script, ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(true);
+    }
+  });
+
+  it('World.query and Entity are discoverable in eval', async () => {
+    const ctx = makeCtx();
+    // Verify _import works and the final query surface is discoverable.
+    const script = aw(
+      [
+        'const { World, Entity } = await _import("@forgeax/engine-ecs");',
+        'return {',
+        '  hasWorldQuery: typeof World.prototype.query === "function",',
+        '  hasEntity: typeof Entity === "object",',
+        '};',
+      ].join('\n'),
+    );
+    const result = await executeScript(script, ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const v = result.value as {
+        hasWorldQuery: boolean;
+        hasEntity: boolean;
+      };
+      expect(v.hasWorldQuery).toBe(true);
+      expect(v.hasEntity).toBe(true);
+    }
+  });
+
+  it('World.query accepts one descriptor', async () => {
+    const script = aw(
+      [
+        'const { World } = await _import("@forgeax/engine-ecs");',
+        'return {',
+        '  isFunction: typeof World.prototype.query === "function",',
+        '  arity: World.prototype.query.length,',
+        '};',
+      ].join('\n'),
+    );
+    const result = await executeScript(script, makeCtx());
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const v = result.value as { isFunction: boolean; arity: number };
+      expect(v.isFunction).toBe(true);
+      expect(v.arity).toBe(1);
+    }
+  });
+
+  it('Entity component keeps its self field', async () => {
+    // Verify Entity component is defined and has a 'self' field.
+    // This confirms the component token exists in the imported module,
+    // which remains useful to eval scripts for component access.
+    const script = aw(
+      [
+        'const { Entity } = await _import("@forgeax/engine-ecs");',
+        'return {',
+        '  isObject: typeof Entity === "object",',
+        '  hasDef: typeof Entity.defineComponent === "undefined" || true,',
+        '  name: Entity.name,',
+        '};',
+      ].join('\n'),
+    );
+    const result = await executeScript(script, makeCtx());
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const v = result.value as { isObject: boolean; name: string };
+      expect(v.isObject).toBe(true);
+      expect(v.name).toBe('Entity');
+    }
+  });
+
+  it('the final World query entry point is discoverable', async () => {
+    const ctx = makeCtx();
+    const script = aw(
+      [
+        'const ecs = await _import("@forgeax/engine-ecs");',
+        'return typeof ecs.World.prototype.query === "function";',
+      ].join('\n'),
+    );
+    const result = await executeScript(script, ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(true);
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Un-wrapped top-level return / await (solo round 20260713-124956):
+// the README + AGENTS.md recipes show top-level `return` and `await` WITHOUT
+// an async IIFE, but the old indirect-eval core (`return eval(script)`) threw
+// script-syntax-error on both. These pin the AsyncFunction-body contract so a
+// docs-following AI user's first, un-wrapped script works.
+// ────────────────────────────────────────────────────────────────────────────
+
+describe('executeScript - un-wrapped top-level return / await', () => {
+  it('top-level `return <literal>` returns the value (no async IIFE)', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('return 42', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe(42);
+  });
+
+  it('top-level `await <promise>` resolves (no async IIFE)', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('await Promise.resolve(7)', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe(7);
+  });
+
+  it('bare expression still auto-returns its value', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('renderer.isReady', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe(true);
+  });
+
+  it('bare expression with a trailing semicolon still returns its value', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('renderer.isReady;', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe(true);
+  });
+
+  it('multi-statement: top-level await _import then return (the documented recipe, un-wrapped)', async () => {
+    const ctx = makeCtx();
+    const script = [
+      'const ecs = await _import("@forgeax/engine-ecs");',
+      'return typeof ecs.World.prototype.query;',
+    ].join('\n');
+    const result = await executeScript(script, ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe('function');
+  });
+
+  it('the historical async-IIFE form still works (backward compatible)', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript(aw('return 99;'), ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe(99);
+  });
+
+  it('genuine syntax error still surfaces script-syntax-error (both compile modes fail)', async () => {
+    const ctx = makeCtx();
+    const result = await executeScript('const = ;', ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('script-syntax-error');
+  });
+
+  it('multi-statement WITHOUT return yields undefined (async-body contract, not eval completion value)', async () => {
+    const ctx = makeCtx();
+    // A statement list is not auto-returned; only a lone trailing expression is.
+    // This is the intentional trade for legal top-level return/await.
+    const result = await executeScript('const a = 1; a + 1', ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBeUndefined();
+  });
+});

package/src/__tests__/execution-report-root.unit.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { executeScript } from '../execute';
+import { buildIntrospectDoc } from '../introspect';
+
+describe('execution report structural root', () => {
+  const execution = {
+    report: () => ({ actualTier: 'shared', world: { health: 'healthy' } }),
+  };
+
+  it('is available to eval without importing the App owner', async () => {
+    const result = await executeScript('execution.report().actualTier', {
+      world: {},
+      renderer: {},
+      assets: {},
+      execution,
+    });
+    expect(result).toEqual({ ok: true, value: 'shared' });
+  });
+
+  it('projects the provider without adding an RPC method', () => {
+    const document = buildIntrospectDoc('127.0.0.1', 5732, {
+      world: {},
+      renderer: {},
+      assets: {},
+      execution,
+    }) as {
+      methods: Array<{ name: string }>;
+      roots: Record<string, { type: string; capability?: string }>;
+    };
+    expect(document.methods.map((method) => method.name)).toEqual(['eval', 'introspect']);
+    expect(document.roots.execution).toEqual(
+      expect.objectContaining({
+        type: 'ExecutionReportProvider',
+        capability: 'execution-report-v1',
+      }),
+    );
+  });
+});

package/src/__tests__/introspect-profiler.unit.test.ts

@@ -0,0 +1,55 @@
+import { createProfiler } from '@forgeax/engine-profiler';
+import { describe, expect, it } from 'vitest';
+
+import { buildIntrospectDoc } from '../introspect';
+
+describe('remote profiler introspection projection', () => {
+  it('derives root names from the supplied live roots', () => {
+    const profiler = createProfiler();
+    const doc = buildIntrospectDoc('127.0.0.1', 5732, {
+      world: {},
+      renderer: {},
+      assets: {},
+      profiler,
+    }) as {
+      roots: Record<string, { available: boolean }>;
+    };
+
+    expect(Object.keys(doc.roots)).toEqual(['world', 'renderer', 'assets', 'profiler']);
+    expect(Object.values(doc.roots).every((root) => root.available)).toBe(true);
+    expect(doc.roots.profiler).toMatchObject({
+      operations: {
+        startCapture: 'profiler.startCapture({ frameLimit, eventLimit })',
+        latestCapture: expect.stringContaining('after the host reaches the frame boundary'),
+      },
+    });
+  });
+
+  it('does not invent optional roots that are absent from the live context', () => {
+    const doc = buildIntrospectDoc('127.0.0.1', 5732, {
+      world: {},
+      renderer: {},
+      assets: {},
+    }) as { roots: Record<string, unknown> };
+
+    expect(doc.roots).toEqual({
+      world: expect.any(Object),
+      renderer: expect.any(Object),
+      assets: expect.any(Object),
+    });
+    expect('profiler' in doc.roots).toBe(false);
+    expect('rhiCapture' in doc.roots).toBe(false);
+  });
+
+  it('does not project a profiler-shaped root for a recorder stand-in', () => {
+    const doc = buildIntrospectDoc('127.0.0.1', 5732, {
+      world: {},
+      renderer: {},
+      assets: {},
+      profiler: { startCapture() {}, latestCapture() {}, phaseCatalog: {} },
+    }) as { roots: Record<string, unknown>; capabilities: { profiler: { enabled: boolean } } };
+
+    expect(doc.roots.profiler).toBeUndefined();
+    expect(doc.capabilities.profiler.enabled).toBe(false);
+  });
+});