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

package/src/__tests__/plugin-profiles.unit.test.ts

@@ -0,0 +1,190 @@
+import type { AudioBackend } from '@forgeax/engine-audio';
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { type InputBackend, ownedInputBackendPlugin } from '@forgeax/engine-input';
+import { Context, type Plugin } from '@forgeax/engine-plugin';
+import type { Renderer } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+import { assembledEngineProfile } from '../internal/assembled-engine-profile';
+import { mainEngineProfile } from '../internal/main-engine-profile';
+import { remoteServerPlugin } from '../internal/remote-server-plugin';
+import { workerEngineProfile } from '../internal/worker-engine-profile';
+import { ownedRendererPlugin } from '../renderer-plugin';
+
+interface PluginMetadata {
+  readonly name?: string;
+  readonly inject?: readonly string[] | Readonly<Record<string, unknown>>;
+  readonly provide?: string | readonly string[];
+}
+
+function metadata(plugin: Plugin): PluginMetadata {
+  return plugin as PluginMetadata;
+}
+
+function names(value: string | readonly string[] | undefined): readonly string[] {
+  if (value === undefined) return [];
+  return typeof value === 'string' ? [value] : value;
+}
+
+function injects(value: PluginMetadata['inject']): readonly string[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : Object.keys(value);
+}
+
+function expectDag(profile: readonly Plugin[], roots: readonly string[]): void {
+  const providers = new Map<string, number>();
+  for (const root of roots) providers.set(root, -1);
+  for (const [index, plugin] of profile.entries()) {
+    for (const service of names(metadata(plugin).provide)) {
+      expect(providers.has(service), `duplicate provider for ${service}`).toBe(false);
+      providers.set(service, index);
+    }
+  }
+
+  const outgoing = profile.map(() => new Set<number>());
+  const indegree = profile.map(() => 0);
+  for (const [consumer, plugin] of profile.entries()) {
+    for (const service of injects(metadata(plugin).inject)) {
+      const provider = providers.get(service);
+      expect(
+        provider,
+        `${metadata(plugin).name ?? consumer} requires ${service}`,
+      ).not.toBeUndefined();
+      expect(
+        provider === consumer,
+        `${metadata(plugin).name ?? consumer} provides and requires ${service}`,
+      ).toBe(false);
+      if (provider === undefined || provider < 0) continue;
+      if (outgoing[provider]?.has(consumer)) continue;
+      outgoing[provider]?.add(consumer);
+      indegree[consumer] = (indegree[consumer] ?? 0) + 1;
+    }
+  }
+
+  const ready = indegree.flatMap((degree, index) => (degree === 0 ? [index] : []));
+  let visited = 0;
+  while (ready.length > 0) {
+    const current = ready.shift();
+    if (current === undefined) break;
+    visited += 1;
+    for (const consumer of outgoing[current] ?? []) {
+      indegree[consumer] = (indegree[consumer] ?? 0) - 1;
+      if (indegree[consumer] === 0) ready.push(consumer);
+    }
+  }
+  expect(visited, 'built-in profile dependency cycle').toBe(profile.length);
+}
+
+const renderer = { assets: {} } as unknown as Renderer;
+const input = { sample: () => ({}) } as InputBackend;
+const audio = {} as AudioBackend;
+describe('Engine built-in plugin profiles', () => {
+  it('keeps browser-main capabilities in one acyclic declared graph', () => {
+    const profile = mainEngineProfile({
+      renderer,
+      input,
+      inputMap: [],
+      animationPayloads: () => undefined,
+    });
+    expect(profile.map((plugin) => metadata(plugin).name)).toEqual([
+      'renderer',
+      'render-components',
+      'renderer-assets',
+      'assets-world',
+      'input-backend',
+      'scene',
+      'animation-payloads',
+      'animation',
+      'state',
+      'input',
+      'input-map',
+    ]);
+    expectDag(profile, ['world']);
+  });
+
+  it('keeps Worker and assembled selections acyclic without copying App wiring', () => {
+    expectDag(
+      workerEngineProfile({
+        renderer,
+        input,
+        audio,
+        animationPayloads: () => undefined,
+      }),
+      ['world'],
+    );
+    expectDag(assembledEngineProfile({ renderer }), ['world']);
+  });
+
+  it('closes an App-owned remote server with its Fiber', async () => {
+    let closeCount = 0;
+    const context = new Context();
+    await context.plugin(
+      remoteServerPlugin({
+        port: 5732,
+        async close() {
+          closeCount += 1;
+        },
+      }),
+    );
+    await context.fiber.dispose();
+    expect(closeCount).toBe(1);
+  });
+
+  it('releases an owned Renderer through its dependent Fiber', async () => {
+    const disposalOrder: string[] = [];
+    const ownedRenderer = {
+      dispose() {
+        disposalOrder.push('renderer');
+      },
+    } as Renderer;
+    const context = new Context();
+    await context.plugin(ownedRendererPlugin(ownedRenderer));
+    await context.plugin({
+      name: 'renderer-consumer',
+      inject: ['renderer'],
+      apply(ctx) {
+        ctx.effect(
+          () => () => {
+            disposalOrder.push('consumer');
+          },
+          'test/renderer-consumer',
+        );
+      },
+    });
+    await context.fiber.dispose();
+    expect(disposalOrder).toEqual(['consumer', 'renderer']);
+  });
+
+  it('releases an App-acquired input backend through its provider Fiber', async () => {
+    let disposeCount = 0;
+    const context = new Context();
+    await context.plugin(
+      ownedInputBackendPlugin(input, () => {
+        disposeCount += 1;
+      }),
+    );
+    await context.fiber.dispose();
+    expect(disposeCount).toBe(1);
+  });
+
+  it('releases an owned Renderer once when later activation rolls back', async () => {
+    let disposeCount = 0;
+    const ownedRenderer = {
+      dispose() {
+        disposeCount += 1;
+      },
+    } as Renderer;
+
+    await expect(
+      createWorldContext(new World(), [
+        ownedRendererPlugin(ownedRenderer),
+        {
+          name: 'activation-failure',
+          apply() {
+            throw new Error('activation failed');
+          },
+        },
+      ]),
+    ).rejects.toThrow('activation failed');
+    expect(disposeCount).toBe(1);
+  });
+});

package/src/__tests__/profiler-default-off.test.ts

@@ -0,0 +1,53 @@
+import { World } from '@forgeax/engine-ecs';
+import { createProfiler } from '@forgeax/engine-profiler';
+import type { Renderer } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+import { createFrameLoop } from '../internal/frame-loop';
+
+function makeRenderer(): Renderer {
+  return {
+    backend: 'webgpu',
+    ready: Promise.resolve({ ok: true, value: undefined }),
+    attach: () => ({ ok: true, value: undefined }),
+    detachWorld: () => {},
+    draw: () => ({ ok: true, value: undefined }),
+    onError: () => () => {},
+    onLost: () => () => {},
+    dispose: () => {},
+  } as unknown as Renderer;
+}
+
+describe('App profiler default-off allocation boundary', () => {
+  it('reports zero profiler-owned event objects and no artifact on the full loop', () => {
+    const allocationReport = { profilerEventObjectAllocations: 0 };
+    const profiler = createProfiler({ enabled: false, allocationReport });
+    const scheduler = {
+      callback: undefined as ((timestamp: number) => void) | undefined,
+      raf(callback: (timestamp: number) => void): number {
+        this.callback = callback;
+        return 1;
+      },
+      caf(): void {
+        this.callback = undefined;
+      },
+    };
+    const loop = createFrameLoop({
+      world: new World(),
+      renderer: makeRenderer(),
+      now: () => 1000,
+      raf: scheduler.raf.bind(scheduler),
+      caf: scheduler.caf.bind(scheduler),
+      profiler,
+    });
+
+    loop.start().unwrap();
+    scheduler.callback?.(1000);
+    loop.stop().unwrap();
+
+    expect({
+      profilerEventObjectAllocations: allocationReport.profilerEventObjectAllocations,
+      artifact: profiler.latestCapture(),
+    }).toEqual({ profilerEventObjectAllocations: 0, artifact: undefined });
+  });
+});

package/src/__tests__/profiler-frame-token.test.ts

@@ -0,0 +1,235 @@
+import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import { createProfiler, type ProfileCapture } from '@forgeax/engine-profiler';
+import type { Renderer, RenderFrameInput } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+import { createFrameLoop } from '../internal/frame-loop';
+import { APP_PHASE_CATALOG } from '../types';
+
+const FRAME_LOOP_PHASES = [
+  'frame-total',
+  'draw-source',
+  'world-update-primary',
+  'world-update-injected',
+  'renderer-draw',
+] as const;
+
+function makeScheduler() {
+  let callback: ((timestamp: number) => void) | undefined;
+  return {
+    raf(next: (timestamp: number) => void): number {
+      callback = next;
+      return 1;
+    },
+    caf(): void {
+      callback = undefined;
+    },
+    tick(timestamp: number): void {
+      const next = callback;
+      callback = undefined;
+      next?.(timestamp);
+    },
+  };
+}
+
+function makeRenderer(onDraw: (profileFrame: unknown) => void = () => {}): Renderer {
+  return {
+    attach: (world: World) => ({ ok: true, value: createRenderReadLease(world) }),
+    draw: (request: RenderFrameInput) => {
+      onDraw(request.profileFrame);
+      return { ok: true, value: undefined };
+    },
+    subscribe: () => () => {},
+    dispose: () => {},
+  } as unknown as Renderer;
+}
+
+function startSession(
+  profiler: ReturnType<typeof createProfiler>,
+  frameLimit = 2,
+  eventLimit = 64,
+) {
+  const result = profiler.startCapture({ frameLimit, eventLimit });
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+function finish(profiler: ReturnType<typeof createProfiler>): ProfileCapture {
+  const session = profiler.activeSession();
+  if (session === undefined) {
+    const latest = profiler.latestCapture();
+    expect(latest).toBeDefined();
+    if (latest === undefined) throw new Error('capture did not publish');
+    return latest;
+  }
+  const result = session?.finish();
+  expect(result?.ok).toBe(true);
+  if (result === undefined || !result.ok) throw new Error('capture did not finish');
+  return result.value;
+}
+
+describe('App profiler frame token', () => {
+  it('records the local frame phases with one token per logical frame', () => {
+    const profiler = createProfiler();
+    expect(startSession(profiler).captureId).toBe('capture-0001');
+    const scheduler = makeScheduler();
+    const drawOptions: unknown[] = [];
+    const loop = createFrameLoop({
+      world: new World(),
+      renderer: makeRenderer((options) => drawOptions.push(options)),
+      now: (() => {
+        const values = [1000, 1016, 1032];
+        return () => values.shift() ?? 1032;
+      })(),
+      raf: scheduler.raf,
+      caf: scheduler.caf,
+      profiler,
+    });
+
+    loop.start().unwrap();
+    scheduler.tick(1016);
+    scheduler.tick(1032);
+    loop.stop().unwrap();
+
+    const capture = finish(profiler);
+    expect(capture.phaseCatalog.app).toEqual(APP_PHASE_CATALOG);
+    expect(capture.captureId).toBe('capture-0001');
+    expect(capture.records.filter((record) => record.source === 'app')).toHaveLength(10);
+    expect(
+      capture.records
+        .filter((record) => record.source === 'app' && record.kind === 'phase')
+        .map((record) => record.phase),
+    ).toEqual(expect.arrayContaining([...FRAME_LOOP_PHASES]));
+    expect(
+      new Set(
+        capture.records
+          .filter((record) => record.source === 'app' && record.kind === 'phase')
+          .map((record) => record.phase),
+      ),
+    ).toEqual(new Set(FRAME_LOOP_PHASES));
+    expect(
+      new Set(
+        capture.records.filter((record) => record.source === 'app').map((record) => record.frameId),
+      ),
+    ).toEqual(new Set([1, 2]));
+    expect(drawOptions).toHaveLength(2);
+    expect(drawOptions[0]).toMatchObject({
+      captureId: 'capture-0001',
+      frameId: 1,
+    });
+    expect(drawOptions[1]).toMatchObject({
+      captureId: 'capture-0001',
+      frameId: 2,
+    });
+  });
+
+  it('does not reuse capture identity and isolates observer and sink failures', () => {
+    const profiler = createProfiler({
+      sink: {
+        write: () => {
+          throw new Error('sink failure');
+        },
+      },
+    });
+    const session = startSession(profiler, 1);
+    const scheduler = makeScheduler();
+    let draws = 0;
+    const loop = createFrameLoop({
+      world: new World(),
+      renderer: makeRenderer(() => {
+        draws += 1;
+      }),
+      now: () => 1000,
+      raf: scheduler.raf,
+      caf: scheduler.caf,
+      profiler,
+    });
+
+    loop.start().unwrap();
+    scheduler.tick(1000);
+    loop.stop().unwrap();
+    expect(draws).toBe(1);
+    expect(session.finish().ok).toBe(false);
+
+    const secondSession = startSession(profiler, 1);
+    expect(secondSession.captureId).not.toBe(session.captureId);
+  });
+
+  it('recaptures complete data after an overflow without stale capture state', () => {
+    const profiler = createProfiler();
+    const scheduler = makeScheduler();
+    const loop = createFrameLoop({
+      world: new World(),
+      renderer: makeRenderer(),
+      now: () => 1000,
+      raf: scheduler.raf,
+      caf: scheduler.caf,
+      profiler,
+    });
+
+    const overflowSession = startSession(profiler, 1, 1);
+    loop.start().unwrap();
+    scheduler.tick(1000);
+
+    const overflow = profiler.latestCapture();
+    expect(overflow?.captureId).toBe(overflowSession.captureId);
+    expect(overflow?.completeness.status).toBe('overflow');
+    expect(overflow?.completeness.droppedEventCount).toBeGreaterThan(0);
+
+    const completeSession = startSession(profiler, 1, 64);
+    scheduler.tick(1016);
+    loop.stop().unwrap();
+
+    const complete = profiler.latestCapture();
+    expect(complete?.captureId).toBe(completeSession.captureId);
+    expect(complete?.captureId).not.toBe(overflow?.captureId);
+    expect(complete?.completeness).toMatchObject({ status: 'complete', droppedEventCount: 0 });
+    expect(overflow?.completeness.status).toBe('overflow');
+    expect(profiler.activeCaptureId()).toBeUndefined();
+  });
+
+  it('publishes a partial artifact when the host stops before its frame boundary', () => {
+    const profiler = createProfiler();
+    startSession(profiler, 2);
+    const scheduler = makeScheduler();
+    const loop = createFrameLoop({
+      world: new World(),
+      renderer: makeRenderer(),
+      now: () => 1000,
+      raf: scheduler.raf,
+      caf: scheduler.caf,
+      profiler,
+    });
+
+    loop.start().unwrap();
+    scheduler.tick(1000);
+    loop.stop().unwrap();
+
+    expect(profiler.latestCapture()?.completeness).toMatchObject({
+      status: 'partial',
+      incompleteReason: 'stopped-before-frame',
+    });
+    expect(profiler.activeCaptureId()).toBeUndefined();
+  });
+
+  it('keeps the default-off path free of profiler records', () => {
+    const scheduler = makeScheduler();
+    let draws = 0;
+    const loop = createFrameLoop({
+      world: new World(),
+      renderer: makeRenderer(() => {
+        draws += 1;
+      }),
+      now: () => 1000,
+      raf: scheduler.raf,
+      caf: scheduler.caf,
+    });
+
+    loop.start().unwrap();
+    scheduler.tick(1000);
+    loop.stop().unwrap();
+
+    expect(draws).toBe(1);
+  });
+});

package/src/__tests__/profiler-phase-catalog.test.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs';
+import { createProfiler } from '@forgeax/engine-profiler';
+import { describe, expect, it } from 'vitest';
+
+import { APP_PHASE_CATALOG } from '../types';
+
+describe('App profiler phase catalog ownership', () => {
+  it('matches the profiler receiver set by definition and has five unique phases', () => {
+    const profiler = createProfiler();
+    expect(profiler.registerPhaseCatalog('app', APP_PHASE_CATALOG).ok).toBe(true);
+    expect(APP_PHASE_CATALOG).toHaveLength(9);
+    expect(new Set(APP_PHASE_CATALOG).size).toBe(APP_PHASE_CATALOG.length);
+    expect(new Set(APP_PHASE_CATALOG)).toEqual(new Set(profiler.phaseCatalog.app));
+  });
+
+  it('rejects a second App catalog definition', () => {
+    const profiler = createProfiler();
+    expect(profiler.registerPhaseCatalog('app', APP_PHASE_CATALOG).ok).toBe(true);
+    const duplicate = profiler.registerPhaseCatalog('app', APP_PHASE_CATALOG);
+    expect(duplicate.ok).toBe(false);
+    if (!duplicate.ok) expect(duplicate.error.code).toBe('phase-catalog-conflict');
+  });
+
+  it('keeps the phase declaration in the App owner module', () => {
+    const source = readFileSync(new URL('../types.ts', import.meta.url), 'utf8');
+    expect(source.match(/'frame-total'/g)).toHaveLength(1);
+    expect(source).not.toContain('FramePhaseObserver');
+    expect(source).not.toContain('frameSeq');
+  });
+});

package/src/__tests__/profiler-phase-integration.test.ts

@@ -0,0 +1,117 @@
+import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import { createProfiler } from '@forgeax/engine-profiler';
+import type { Renderer, RenderFrameInput } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+import { createFrameLoop } from '../internal/frame-loop';
+import { APP_PHASE_CATALOG } from '../types';
+
+function makeScheduler() {
+  let callback: ((timestamp: number) => void) | undefined;
+  return {
+    raf(next: (timestamp: number) => void): number {
+      callback = next;
+      return 1;
+    },
+    caf(): void {
+      callback = undefined;
+    },
+    tick(timestamp: number): void {
+      const next = callback;
+      callback = undefined;
+      next?.(timestamp);
+    },
+  };
+}
+
+function makeRenderer(draw: (profileFrame: unknown) => void): Renderer {
+  return {
+    attach: (world: World) => ({ ok: true, value: createRenderReadLease(world) }),
+    draw: (request: RenderFrameInput) => {
+      draw(request.profileFrame);
+      return { ok: true, value: undefined };
+    },
+    subscribe: () => () => {},
+    dispose: () => {},
+  } as unknown as Renderer;
+}
+
+function start(profiler: ReturnType<typeof createProfiler>) {
+  const result = profiler.startCapture({ frameLimit: 2, eventLimit: 64 });
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+function finish(profiler: ReturnType<typeof createProfiler>) {
+  const session = profiler.activeSession();
+  if (session === undefined) {
+    const latest = profiler.latestCapture();
+    if (latest === undefined) throw new Error('capture did not publish');
+    return latest;
+  }
+  const result = session.finish();
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+describe('App and Render profiler integration', () => {
+  it('keeps normal and App-only frames on one capture identity', () => {
+    const profiler = createProfiler();
+    start(profiler);
+    const scheduler = makeScheduler();
+    const drawOptions: unknown[] = [];
+    const loop = createFrameLoop({
+      world: new World(),
+      renderer: makeRenderer((options) => drawOptions.push(options)),
+      now: () => 1000,
+      raf: scheduler.raf,
+      caf: scheduler.caf,
+      profiler,
+    });
+
+    loop.start().unwrap();
+    scheduler.tick(1000);
+    loop.stop().unwrap();
+
+    const capture = finish(profiler);
+    expect(capture.records.filter((record) => record.source === 'app')).toHaveLength(5);
+    expect(capture.records.every((record) => record.frameId === 1)).toBe(true);
+    expect(drawOptions[0]).toMatchObject({
+      captureId: capture.captureId,
+      frameId: 1,
+    });
+    expect(capture.phaseCatalog.app).toEqual(APP_PHASE_CATALOG);
+    expect(profiler.phaseCatalog.app).toEqual([]);
+  });
+
+  it('isolates a renderer failure while the host frame loop continues', () => {
+    const profiler = createProfiler();
+    start(profiler);
+    const scheduler = makeScheduler();
+    let draws = 0;
+    const errors: unknown[] = [];
+    const loop = createFrameLoop({
+      world: new World(),
+      renderer: makeRenderer(() => {
+        draws += 1;
+        throw new Error('render failure');
+      }),
+      now: () => 1000,
+      raf: scheduler.raf,
+      caf: scheduler.caf,
+      onError: (error) => errors.push(error),
+      profiler,
+    });
+
+    loop.start().unwrap();
+    scheduler.tick(1000);
+    scheduler.tick(1000);
+    loop.stop().unwrap();
+
+    const capture = finish(profiler);
+    expect(draws).toBe(2);
+    expect(errors).toHaveLength(2);
+    expect(capture.records.filter((record) => record.source === 'app')).toHaveLength(10);
+  });
+});

package/src/__tests__/profiler-remote-bridge.test.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const BRIDGE_SOURCE = fileURLToPath(
+  new URL('../internal/browser-remote-bridge.ts', import.meta.url),
+);
+const CREATE_APP_SOURCE = fileURLToPath(new URL('../create-app.ts', import.meta.url));
+
+describe('browser remote profiler bridge', () => {
+  const bridge = readFileSync(BRIDGE_SOURCE, 'utf8');
+  const createApp = readFileSync(CREATE_APP_SOURCE, 'utf8');
+
+  it('propagates the explicit profiler root through the existing bridge context', () => {
+    expect(bridge).toContain('readonly profiler?: unknown');
+    expect(bridge).toContain('profiler,');
+    expect(bridge).toContain('profiler: profiler');
+  });
+
+  it('keeps the bridge opt-in and free of a static remote dependency', () => {
+    expect(createApp).toContain('VITE_FORGEAX_ENGINE_BRIDGE');
+    expect(createApp).toContain("import('./internal/browser-remote-bridge')");
+    expect(bridge).not.toMatch(/^import .*@forgeax\/engine-remote/m);
+  });
+
+  it('keeps profiler failures in the JSON-safe eval envelope', () => {
+    expect(bridge).toContain("code: typeof e.code === 'string' ? e.code : 'script-runtime-error'");
+    expect(bridge).toContain('detail');
+    expect(bridge).toContain('JSON.stringify(envelope)');
+  });
+});