@forgeax/engine-app 0.0.0-dev.8d955ade1c79

package/src/__tests__/draw-source-single-world-regression.test.ts

@@ -0,0 +1,184 @@
+// feat-20260709-editor-world-partition-editorworld-super-composite / M2 / w8
+// (RED — impl lands in w12). Contract test: the drawSource injection seam MUST
+// degrade to the existing single-world path byte-identically when the host does
+// not opt in.
+//
+// Two non-opt-in shapes must both reproduce the legacy call
+// `renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })` (feat-20260708 M3 / AC-03 wrapping):
+//
+//   1. `drawSource` absent entirely — the createApp/frame-loop caller passes no
+//      drawSource (the single-world AI-user default).
+//   2. `drawSource` present but returning `undefined` on the frame — a host
+//      that wired the seam but, this frame, has nothing multi-world to inject
+//      (e.g. editor with no partitioned viewport active).
+//
+// Both cases MUST call `renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })` with the loop's
+// own single world and owner 0. This pins the AC-03 regression guarantee across
+// the new seam: adding drawSource never perturbs the single-world path.
+//
+// This test drives createFrameLoop directly (injected now / raf / caf seams)
+// with a spy renderer, mirroring frame-loop-world-array.test.ts. The drawSource
+// option is reached through a typed alias so the intent reads clearly before w12
+// widens the real FrameLoopOptions type (test-first RED window).
+//
+// Anchors:
+//   plan-strategy §2 D-3 (drawSource pull callback; absent / undefined -> single
+//     world path byte-identical to draw([world], { cameraOwner: 0, resourceOwner: 0 }))
+//   research F1 (frame-loop hardcodes renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }) — the
+//     seam insertion point)
+
+import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import type { Renderer, RenderFrameInput } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+import { createFrameLoop, type FrameLoopOptions } from '../internal/frame-loop';
+
+interface DrawCall {
+  readonly request: RenderFrameInput;
+}
+
+function makeSpyRenderer(): { renderer: Renderer; calls: DrawCall[] } {
+  const calls: DrawCall[] = [];
+  const renderer = {
+    attach: (world: World) => ({ ok: true, value: createRenderReadLease(world) }),
+    draw(request: RenderFrameInput): { ok: true; value: undefined } {
+      calls.push({ request });
+      return { ok: true, value: undefined };
+    },
+    onError(): () => void {
+      return () => {
+        // no-op unsubscribe
+      };
+    },
+    dispose(): void {
+      // no-op
+    },
+  } as unknown as Renderer;
+  return { renderer, calls };
+}
+
+/**
+ * Synchronous rAF driver: fire the scheduled tick exactly `frames` times.
+ * Mirrors frame-loop-world-array.test.ts so both single-world contract tests
+ * step the loop identically.
+ */
+function makeSyncScheduler() {
+  let pending: ((t: number) => void) | null = null;
+  let clock = 0;
+  const raf = (cb: (t: number) => void): number => {
+    pending = cb;
+    return 1;
+  };
+  const caf = (): void => {
+    pending = null;
+  };
+  const now = (): number => {
+    clock += 16;
+    return clock;
+  };
+  const pump = (frames: number): void => {
+    for (let i = 0; i < frames; i++) {
+      const cb = pending;
+      pending = null;
+      if (cb === null) break;
+      cb(clock);
+    }
+  };
+  return { raf, caf, now, pump };
+}
+
+// The drawSource pull callback shape w11/w12 will introduce on FrameLoopOptions.
+// Declared locally so this test states the contract independent of the (not-yet
+// widened) source type. `undefined` return = "no multi-world injection this
+// frame" (degrade to single world).
+type DrawSourceCallback = () =>
+  | { worlds: readonly World[]; cameraOwner: number; resourceOwner: number }
+  | undefined;
+
+type FrameLoopOptionsWithDrawSource = FrameLoopOptions & {
+  drawSource?: DrawSourceCallback;
+};
+
+const createFrameLoopWithDrawSource = createFrameLoop as unknown as (
+  opts: FrameLoopOptionsWithDrawSource,
+) => ReturnType<typeof createFrameLoop>;
+
+describe('drawSource seam degrades to single-world path (w8, AC-03 regression)', () => {
+  it('no drawSource: draws the primary World with explicit camera and resource owners', () => {
+    const world = new World();
+    const { renderer, calls } = makeSpyRenderer();
+    const { raf, caf, now, pump } = makeSyncScheduler();
+
+    // No drawSource field at all — the single-world AI-user default.
+    const loop = createFrameLoop({ world, renderer, now, raf, caf });
+    expect(loop.start().ok).toBe(true);
+    pump(3);
+
+    expect(calls.length).toBeGreaterThanOrEqual(3);
+    for (const call of calls) {
+      expect(call.request.leases).toHaveLength(1);
+      expect(call.request.leases[0]?.worldIdentity).toBe(world.identity);
+      expect(call.request.camera.lease).toBe(call.request.leases[0]);
+      expect(call.request.environment.lease).toBe(call.request.leases[0]);
+    }
+
+    loop.stop();
+  });
+
+  it('drawSource returns undefined: still draws [world] with { cameraOwner: 0, resourceOwner: 0 } (no-inject frame)', () => {
+    const world = new World();
+    const { renderer, calls } = makeSpyRenderer();
+    const { raf, caf, now, pump } = makeSyncScheduler();
+
+    let pulls = 0;
+    const drawSource: DrawSourceCallback = () => {
+      pulls++;
+      // Host wired the seam but has nothing multi-world to inject this frame.
+      return undefined;
+    };
+
+    const loop = createFrameLoopWithDrawSource({ world, renderer, now, raf, caf, drawSource });
+    expect(loop.start().ok).toBe(true);
+    pump(3);
+
+    // The seam was consulted (pull callback fired) but the resulting draw is
+    // identical to the primary-World call.
+    expect(pulls).toBeGreaterThanOrEqual(3);
+    expect(calls.length).toBeGreaterThanOrEqual(3);
+    for (const call of calls) {
+      expect(call.request.leases).toHaveLength(1);
+      expect(call.request.leases[0]?.worldIdentity).toBe(world.identity);
+      expect(call.request.camera.lease).toBe(call.request.leases[0]);
+      expect(call.request.environment.lease).toBe(call.request.leases[0]);
+    }
+
+    loop.stop();
+  });
+
+  it('setDrawSource switches routing without creating a second frame loop', () => {
+    const world = new World();
+    const overlay = new World();
+    const { renderer, calls } = makeSpyRenderer();
+    const { raf, caf, now, pump } = makeSyncScheduler();
+    const loop = createFrameLoop({ world, renderer, now, raf, caf });
+
+    expect(loop.start().ok).toBe(true);
+    pump(1);
+    loop.setDrawSource(() => ({ worlds: [world, overlay], cameraOwner: 0, resourceOwner: 0 }));
+    pump(1);
+    loop.setDrawSource(undefined);
+    pump(1);
+
+    expect(calls).toHaveLength(3);
+    expect(calls[0]?.request.leases).toHaveLength(1);
+    expect(calls[0]?.request.leases[0]?.worldIdentity).toBe(world.identity);
+    expect(calls[1]?.request.leases).toHaveLength(2);
+    expect(calls[1]?.request.leases[0]?.worldIdentity).toBe(world.identity);
+    expect(calls[1]?.request.leases[1]?.worldIdentity).toBe(overlay.identity);
+    expect(calls[1]?.request.camera.lease).toBe(calls[1]?.request.leases[0]);
+    expect(calls[1]?.request.environment.lease).toBe(calls[1]?.request.leases[0]);
+    expect(calls[2]?.request.leases).toHaveLength(1);
+    expect(calls[2]?.request.leases[0]?.worldIdentity).toBe(world.identity);
+    loop.stop();
+  });
+});

package/src/__tests__/engine-worker-bootstrap-channel.unit.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from 'vitest';
+import { startEngineWorker } from '../execution/engine-worker';
+import type { EngineToHostMessage, HostToEngineMessage } from '../execution/protocol';
+
+class FakeWorker {
+  onmessage: ((event: MessageEvent<EngineToHostMessage>) => void) | null = null;
+  onerror: ((event: ErrorEvent) => void) | null = null;
+  readonly posts: Array<{
+    readonly message: HostToEngineMessage;
+    readonly transfer: readonly Transferable[];
+  }> = [];
+  readonly terminate = vi.fn();
+
+  postMessage(message: HostToEngineMessage, transfer: Transferable[] = []): void {
+    this.posts.push({ message, transfer });
+    if (message.kind !== 'init') return;
+    queueMicrotask(() => {
+      this.onmessage?.({
+        data: {
+          kind: 'ready',
+          worldIdentity: 'world-test',
+          realm: 'worker',
+          workerWebGpu: true,
+        },
+      } as MessageEvent<EngineToHostMessage>);
+    });
+  }
+}
+
+describe('Engine Worker thick bootstrap channel', () => {
+  it('transfers bootstrap data and the realm MessagePort with the canvas', async () => {
+    const worker = new FakeWorker();
+    const offscreen = {} as OffscreenCanvas;
+    const transferControlToOffscreen = vi.fn(() => offscreen);
+    const channel = new MessageChannel();
+    const started = await startEngineWorker({
+      canvas: { transferControlToOffscreen } as unknown as HTMLCanvasElement,
+      bootstrapUrl: 'https://example.test/bootstrap.js',
+      bootstrapData: { gameId: 'sample' },
+      bootstrapPort: channel.port2,
+      assetCatalog: {
+        url: '/__pack/scopes/sample/7/catalog.json',
+        expectedScope: { scopeId: 'sample', generation: 7 },
+      },
+      timeoutMs: 100,
+      tier: 'engine-worker',
+      workerFactory: () => worker as unknown as Worker,
+    });
+
+    expect(started.ok).toBe(true);
+    expect(transferControlToOffscreen).toHaveBeenCalledOnce();
+    expect(worker.posts[0]?.message).toMatchObject({
+      kind: 'init',
+      bootstrapData: { gameId: 'sample' },
+      bootstrapPort: channel.port2,
+      assetCatalog: {
+        url: '/__pack/scopes/sample/7/catalog.json',
+        expectedScope: { scopeId: 'sample', generation: 7 },
+      },
+    });
+    expect(worker.posts[0]?.transfer).toEqual([offscreen, channel.port2]);
+    started.ok && started.value.dispose();
+    channel.port1.close();
+  });
+
+  it('rejects non-cloneable data before Worker creation or canvas transfer', async () => {
+    const workerFactory = vi.fn();
+    const transferControlToOffscreen = vi.fn();
+    const started = await startEngineWorker({
+      canvas: { transferControlToOffscreen } as unknown as HTMLCanvasElement,
+      bootstrapUrl: 'https://example.test/bootstrap.js',
+      bootstrapData: { callback: (() => {}) as never },
+      timeoutMs: 100,
+      tier: 'engine-worker',
+      workerFactory,
+    });
+
+    expect(started.ok).toBe(false);
+    expect(workerFactory).not.toHaveBeenCalled();
+    expect(transferControlToOffscreen).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/engine-worker-world-swap.unit.test.ts

@@ -0,0 +1,69 @@
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer, RenderWorldLease } from '@forgeax/engine-render';
+import { describe, expect, it, vi } from 'vitest';
+import { commitAttachedWorld, SerializedRebuildQueue } from '../execution/attached-world-swap';
+
+function rendererOwner(): Pick<Renderer, 'attach'> {
+  const lease = {
+    worldIdentity: {},
+    generation: 0,
+    readChanges: vi.fn(),
+    querySpans: vi.fn(),
+    inspectCursor: vi.fn(),
+    dispose: vi.fn(),
+  } as unknown as RenderWorldLease;
+  return {
+    attach: vi.fn(() => ({ ok: true as const, value: lease })),
+  };
+}
+
+describe('worker attached World swap', () => {
+  it('serializes concurrent rebuild requests', async () => {
+    const queue = new SerializedRebuildQueue();
+    const trace: string[] = [];
+    let releaseFirst: (() => void) | undefined;
+    const first = queue.enqueue(async () => {
+      trace.push('first:start');
+      await new Promise<void>((resolve) => {
+        releaseFirst = resolve;
+      });
+      trace.push('first:end');
+    });
+    const second = queue.enqueue(async () => {
+      trace.push('second:start');
+      trace.push('second:end');
+    });
+
+    await Promise.resolve();
+    expect(trace).toEqual(['first:start']);
+    releaseFirst?.();
+    await Promise.all([first, second]);
+    expect(trace).toEqual(['first:start', 'first:end', 'second:start', 'second:end']);
+  });
+
+  it('publishes the candidate before detaching the previous World', async () => {
+    const renderer = rendererOwner();
+    const next = new World();
+
+    await expect(commitAttachedWorld(renderer, next, async () => true)).resolves.toBe(true);
+    expect(renderer.attach).toHaveBeenCalledWith(next);
+  });
+
+  it('detaches a candidate whose bootstrap fails and keeps the previous World', async () => {
+    const renderer = rendererOwner();
+    const next = new World();
+
+    await expect(commitAttachedWorld(renderer, next, async () => false)).resolves.toBe(false);
+  });
+
+  it('detaches a candidate whose bootstrap throws', async () => {
+    const renderer = rendererOwner();
+    const next = new World();
+
+    await expect(
+      commitAttachedWorld(renderer, next, async () => {
+        throw new Error('bootstrap failed');
+      }),
+    ).rejects.toThrow('bootstrap failed');
+  });
+});

package/src/__tests__/errors-pointer-lock-failed.test.ts

@@ -0,0 +1,265 @@
+// errors-pointer-lock-failed.test.ts -- M2 w10: AppErrorCode closed union
+// (6 members) + 'app-pointer-lock-failed' detail shape + exhaustive switch
+// + APP_EXPECTED / APP_ERROR_HINTS bidirectional symmetry.
+//
+// TDD red phase: this test is written BEFORE the 'app-pointer-lock-failed'
+// member lands in errors.ts (w12). It will fail typecheck / assertions until
+// w12 expands the union and adds the detail variant.
+//
+// charter awareness:
+//   P3 explicit failure -- every assertion produces a clear diagnostic
+//   P4 closed-union exhaustive switch -- zero default branch, tsc guards completeness
+
+import { describe, expect, it } from 'vitest';
+import {
+  APP_ERROR_HINTS,
+  APP_EXPECTED,
+  AppError,
+  type AppErrorCode,
+  type AppErrorDetail,
+  type AppErrorDetailFor,
+  isAppError,
+} from '../errors';
+
+// ---------------------------------------------------------------------------
+// 1. AppErrorCode closed union
+// ---------------------------------------------------------------------------
+
+describe('AppErrorCode closed union', () => {
+  it('has every source-owned member', () => {
+    // Verify the full set of members. When 'app-pointer-lock-failed' is added
+    // in w12, this set will be complete and the exhaustive-switch check below
+    // will pass tsc with no default branch.
+    const allCodes: AppErrorCode[] = [
+      'app-not-started',
+      'app-already-running',
+      'app-canvas-detached',
+      'app-frame-step-invalid',
+      'app-system-update-failed',
+      'app-pointer-lock-failed',
+      'app-plugin-activation-failed',
+      'app-execution-tier-unavailable',
+      'app-execution-bootstrap-failed',
+      'app-execution-deadline-exceeded',
+      'app-execution-kernel-failed',
+      'app-execution-stale-world',
+      'app-execution-rebuild-failed',
+    ];
+
+    expect(allCodes).toHaveLength(13);
+
+    // Each member must be unique.
+    const unique = new Set(allCodes);
+    expect(unique.size).toBe(13);
+  });
+
+  it('exhaustive switch over AppErrorCode has zero default branch', () => {
+    // This function MUST compile with no default. If a member is missing from
+    // the union, tsc will flag the switch as non-exhaustive. If a member is
+    // removed from the union but left here, tsc will flag the dead case.
+    // The test assertion itself is trivially true -- the test is the
+    // compile-time guarantee.
+    function exhaust(code: AppErrorCode): string {
+      switch (code) {
+        case 'app-not-started':
+          return 'not started';
+        case 'app-already-running':
+          return 'already running';
+        case 'app-canvas-detached':
+          return 'canvas detached';
+        case 'app-frame-step-invalid':
+          return 'frame step invalid';
+        case 'app-system-update-failed':
+          return 'system update failed';
+        case 'app-pointer-lock-failed':
+          return 'pointer lock failed';
+        case 'app-plugin-activation-failed':
+          return 'plugin activation failed';
+        case 'app-execution-tier-unavailable':
+        case 'app-execution-bootstrap-failed':
+        case 'app-execution-deadline-exceeded':
+        case 'app-execution-kernel-failed':
+        case 'app-execution-stale-world':
+        case 'app-execution-rebuild-failed':
+          return 'execution';
+      }
+    }
+
+    // Verify the function is callable for representative codes.
+    expect(exhaust('app-not-started')).toBe('not started');
+    expect(exhaust('app-already-running')).toBe('already running');
+    expect(exhaust('app-canvas-detached')).toBe('canvas detached');
+    expect(exhaust('app-system-update-failed')).toBe('system update failed');
+    expect(exhaust('app-pointer-lock-failed')).toBe('pointer lock failed');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. 'app-pointer-lock-failed' detail shape
+// ---------------------------------------------------------------------------
+
+describe("'app-pointer-lock-failed' detail shape", () => {
+  it('has .code === "app-pointer-lock-failed"', () => {
+    const err = new AppError({
+      code: 'app-pointer-lock-failed',
+      expected: 'pointer-lock request to succeed',
+      hint: 'remain in unlocked state; next trusted click will retry',
+      detail: { path: 'w3c', cause: new Error('test') },
+    });
+    expect(err.code).toBe('app-pointer-lock-failed');
+  });
+
+  it('detail.path narrows to "w3c" | "provider"', () => {
+    const w3cErr = new AppError({
+      code: 'app-pointer-lock-failed',
+      expected: 'pointer-lock request to succeed',
+      hint: 'remain in unlocked state; next trusted click will retry',
+      detail: { path: 'w3c', cause: new DOMException('test', 'NotAllowedError') },
+    });
+    expect(w3cErr.detail.path).toBe('w3c');
+
+    const provErr = new AppError({
+      code: 'app-pointer-lock-failed',
+      expected: 'pointer-lock request to succeed',
+      hint: 'remain in unlocked state; next trusted click will retry',
+      detail: { path: 'provider', cause: new Error('provider reject') },
+    });
+    expect(provErr.detail.path).toBe('provider');
+  });
+
+  it('detail.cause carries the original rejection value verbatim', () => {
+    const cause = new Error('W3C lock rejected');
+    const err = new AppError({
+      code: 'app-pointer-lock-failed',
+      expected: 'pointer-lock request to succeed',
+      hint: 'remain in unlocked state; next trusted click will retry',
+      detail: { path: 'w3c', cause },
+    });
+    expect(err.detail.cause).toBe(cause);
+  });
+
+  it('isAppError returns true for pointer-lock-failed errors', () => {
+    const err = new AppError({
+      code: 'app-pointer-lock-failed',
+      expected: 'pointer-lock request to succeed',
+      hint: 'remain in unlocked state; next trusted click will retry',
+      detail: { path: 'w3c', cause: new Error('test') },
+    });
+    expect(isAppError(err)).toBe(true);
+  });
+
+  it('message carries path and cause summary', () => {
+    const err = new AppError({
+      code: 'app-pointer-lock-failed',
+      expected: 'pointer-lock request to succeed',
+      hint: 'remain in unlocked state; next trusted click will retry',
+      detail: { path: 'w3c', cause: new Error('NotAllowedError') },
+    });
+    expect(err.message).toContain('app-pointer-lock-failed');
+    expect(err.message).toContain('NotAllowedError');
+  });
+
+  it('narrows via discriminated union: if (err.code === "app-pointer-lock-failed")', () => {
+    const err = new AppError({
+      code: 'app-pointer-lock-failed',
+      expected: 'pointer-lock request to succeed',
+      hint: 'remain in unlocked state; next trusted click will retry',
+      detail: { path: 'w3c', cause: new Error('test') },
+    }) as AppError;
+
+    if (err.code === 'app-pointer-lock-failed') {
+      // detail should narrow to { path: 'w3c' | 'provider'; cause: unknown }
+      const { path, cause } = err.detail;
+      expect(path).toBe('w3c');
+      expect(cause).toBeInstanceOf(Error);
+    } else {
+      // Should not reach here for this test.
+      expect.unreachable('expected code to be app-pointer-lock-failed');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. APP_EXPECTED / APP_ERROR_HINTS bidirectional symmetry (6 keys)
+// ---------------------------------------------------------------------------
+
+describe('APP_EXPECTED / APP_ERROR_HINTS bidirectional symmetry', () => {
+  it('APP_EXPECTED has one key per AppErrorCode member', () => {
+    const keys = Object.keys(APP_EXPECTED);
+    expect(keys).toHaveLength(13);
+  });
+
+  it('APP_ERROR_HINTS has one key per AppErrorCode member', () => {
+    const keys = Object.keys(APP_ERROR_HINTS);
+    expect(keys).toHaveLength(13);
+  });
+
+  it('APP_EXPECTED and APP_ERROR_HINTS have the same key set', () => {
+    const expectedKeys = Object.keys(APP_EXPECTED).sort();
+    const hintKeys = Object.keys(APP_ERROR_HINTS).sort();
+    expect(expectedKeys).toEqual(hintKeys);
+  });
+
+  it('every APP_EXPECTED entry is non-empty', () => {
+    for (const [key, value] of Object.entries(APP_EXPECTED)) {
+      expect(value, `APP_EXPECTED[${key}] must be non-empty`).toBeTruthy();
+      expect(value.length, `APP_EXPECTED[${key}] must be non-empty`).toBeGreaterThan(0);
+    }
+  });
+
+  it('every APP_ERROR_HINTS entry is non-empty', () => {
+    for (const [key, value] of Object.entries(APP_ERROR_HINTS)) {
+      expect(value, `APP_ERROR_HINTS[${key}] must be non-empty`).toBeTruthy();
+      expect(value.length, `APP_ERROR_HINTS[${key}] must be non-empty`).toBeGreaterThan(0);
+    }
+  });
+
+  it('app-pointer-lock-failed has expected and hint entries', () => {
+    expect(APP_EXPECTED).toHaveProperty('app-pointer-lock-failed');
+    expect(APP_ERROR_HINTS).toHaveProperty('app-pointer-lock-failed');
+    expect(APP_EXPECTED['app-pointer-lock-failed'].length).toBeGreaterThan(0);
+    expect(APP_ERROR_HINTS['app-pointer-lock-failed'].length).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. AppErrorDetail union includes the new variant
+// ---------------------------------------------------------------------------
+
+describe('AppErrorDetail union', () => {
+  it('accepts the pointer-lock-failed detail variant', () => {
+    const detail: AppErrorDetail = {
+      path: 'w3c',
+      cause: new Error('test'),
+    };
+    expect(detail.path).toBe('w3c');
+    expect(detail.cause).toBeInstanceOf(Error);
+  });
+
+  it('accepts the provider path variant', () => {
+    const detail: AppErrorDetail = {
+      path: 'provider',
+      cause: 'provider string rejection',
+    };
+    // cause is unknown, so string is valid.
+    expect(detail.path).toBe('provider');
+    expect(typeof detail.cause).toBe('string');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. AppErrorDetailFor conditional type narrows correctly
+// ---------------------------------------------------------------------------
+
+describe('AppErrorDetailFor conditional type', () => {
+  it('narrows "app-pointer-lock-failed" to { path, cause }', () => {
+    // This is a compile-time assertion: if AppErrorDetailFor<'app-pointer-lock-failed'>
+    // does not resolve to { path: 'w3c' | 'provider'; cause: unknown }, tsc will fail.
+    const detail: AppErrorDetailFor<'app-pointer-lock-failed'> = {
+      path: 'w3c',
+      cause: new Error('test'),
+    };
+    expect(detail.path).toBe('w3c');
+    expect(detail.cause).toBeInstanceOf(Error);
+  });
+});

package/src/__tests__/execution-bootstrap-isolation.unit.test.ts

@@ -0,0 +1,79 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  executionBootstrapHostPlugin,
+  loadBootstrapEntry,
+  prepareBootstrapEntry,
+  validateExecutionBootstrapData,
+} from '../execution';
+
+function moduleUrl(source: string): string {
+  return `data:text/javascript,${encodeURIComponent(source)}`;
+}
+
+describe('execution bootstrap isolation', () => {
+  it('activates realm-local bootstrap plugins and disposes their effects', async () => {
+    const url = moduleUrl(`export default function(data){return {plugins:[{
+      name:'test-bootstrap',inject:['world','executionBootstrapHost'],apply(ctx){
+        ctx.world.insertResource('bootstrapped',data.value);
+        ctx.effect(()=>()=>ctx.world.insertResource('cleaned',true),'test/cleanup');
+        ctx.executionBootstrapHost.setPointerLockAllowed(false);
+      }
+    }]}}`);
+    const prepared = await prepareBootstrapEntry(url, { value: true });
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const world = new World();
+    const pointerLock = vi.fn();
+    const close = vi.fn();
+    const context = await createWorldContext(world, [
+      executionBootstrapHostPlugin({
+        port: { close } as unknown as MessagePort,
+        setPointerLockAllowed: pointerLock,
+      }),
+      ...(prepared.value.plugins ?? []),
+    ]);
+    expect(world.getResource('bootstrapped')).toBe(true);
+    expect(pointerLock).toHaveBeenCalledWith(false);
+    await context.fiber.dispose();
+    expect(world.getResource('cleaned')).toBe(true);
+    expect(close).toHaveBeenCalledOnce();
+  });
+
+  it('keeps schedule identity in the realm-local World', async () => {
+    const url = moduleUrl(`export default function(){return {plugins:[{
+      name:'module-system',inject:['world'],apply(ctx){
+        const system={name:'module-system',queries:[],fn(){}};
+        ctx.world.addSystem(ctx.world.scheduleToken('Update'),system).unwrap();
+        ctx.effect(()=>()=>ctx.world.removeSystem(ctx.world.scheduleToken('Update'),system.name),'test/system');
+      }
+    }]}}`);
+    const prepared = await prepareBootstrapEntry(url, undefined);
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const world = new World();
+    const context = await createWorldContext(world, prepared.value.plugins ?? []);
+    expect(world.inspect().scheduleSystemCount(world.scheduleToken('Update'))).toBe(1);
+    await context.fiber.dispose();
+    expect(world.inspect().scheduleSystemCount(world.scheduleToken('Update'))).toBe(0);
+  });
+
+  it('rejects a missing default export structurally', async () => {
+    const result = await loadBootstrapEntry('data:text/javascript,export const value=1');
+    expect(result.ok).toBe(false);
+    if (!result.ok && result.error.code === 'app-execution-bootstrap-failed') {
+      expect(result.error.detail.phase).toBe('export');
+    }
+  });
+
+  it('rejects non-cloneable bootstrap data before canvas transfer', () => {
+    const result = validateExecutionBootstrapData(
+      { callback: (() => {}) as never },
+      'https://example.test/bootstrap.js',
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok && result.error.code === 'app-execution-bootstrap-failed') {
+      expect(result.error.detail.phase).toBe('data');
+    }
+  });
+});