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

package/src/__tests__/animation-asset-lookup.unit.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { createAnimationPayloadLookup } from '../animation-asset-lookup';
+
+describe('createAnimationPayloadLookup', () => {
+  it('projects the renderer catalogue lookup into the animation callback', () => {
+    const clip = { kind: 'animation-clip' as const, duration: 2, channels: [] };
+    const lookup = createAnimationPayloadLookup({
+      lookup<T>(guid: string): T | undefined {
+        return (guid === 'clip-guid' ? clip : undefined) as T | undefined;
+      },
+    });
+
+    expect(lookup('clip-guid')).toBe(clip);
+    expect(lookup('missing')).toBeUndefined();
+  });
+
+  it('fails closed before a renderer catalogue exists', () => {
+    expect(createAnimationPayloadLookup(undefined)('clip-guid')).toBeUndefined();
+  });
+});

package/src/__tests__/callback-deletion.unit.test.ts

@@ -0,0 +1,14 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { GameHost } from '../game-context';
+import type { App, AppAssembleArgs, CreateAppOptions } from '../types';
+
+describe('app callback and phantom surface deletion', () => {
+  it('omits callbacks and phantom scheduling fields from public app contracts', () => {
+    expectTypeOf<App>().not.toHaveProperty('registerUpdate');
+    expectTypeOf<GameHost>().not.toHaveProperty('registerUpdate');
+    expectTypeOf<AppAssembleArgs>().not.toHaveProperty('schedule');
+    expectTypeOf<AppAssembleArgs>().not.toHaveProperty('maxDt');
+    expectTypeOf<CreateAppOptions>().not.toHaveProperty('schedule');
+    expectTypeOf<CreateAppOptions>().not.toHaveProperty('maxDt');
+  });
+});

package/src/__tests__/callback-inference.test-d.ts

@@ -0,0 +1,36 @@
+import { animationPlugin } from '@forgeax/engine-animation';
+import { World } from '@forgeax/engine-ecs';
+import type { Plugin } from '@forgeax/engine-plugin';
+import { Camera, perspective, type Renderer } from '@forgeax/engine-render';
+import { createRenderer } from '@forgeax/engine-runtime';
+import { createApp } from '../create-app';
+
+const plugin: Plugin = animationPlugin();
+void plugin;
+
+declare const canvas: HTMLCanvasElement;
+declare const renderer: Renderer;
+
+const world = new World();
+const cameraEntity = world
+  .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1 }) })
+  .unwrap();
+const camera = world.get(cameraEntity, Camera).unwrap();
+camera.projection;
+const appResult = createApp({ renderer, world, plugins: [plugin] });
+appResult.then((result) => {
+  if (result.ok) {
+    result.value.start();
+  }
+});
+
+createRenderer(canvas).then((created) => {
+  if (!created.ok) return;
+  const attached = created.value.attach(world);
+  if (!attached.ok) return;
+  void created.value.draw({
+    leases: [attached.value],
+    camera: { lease: attached.value },
+    environment: { lease: attached.value },
+  });
+});

package/src/__tests__/component-introspection.unit.test.ts

@@ -0,0 +1,56 @@
+import { componentDefinition, defineComponent, World } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { Visibility } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+import { projectComponentIntrospection } from '../internal/component-introspection';
+
+const Probe = defineComponent(
+  'ComponentIntrospectionProbe',
+  {
+    mode: {
+      type: 'enum',
+      default: 0,
+      labels: { first: 0, second: 1 },
+    },
+    name: {
+      type: 'string',
+      meta: { purpose: 'reflection-test' },
+    },
+  },
+  { meta: { owner: 'app-test' } },
+);
+
+describe('component introspection projection', () => {
+  it('derives Visibility schema, labels, and metadata from the registered token', () => {
+    const world = new World();
+    world.components.register(Visibility).unwrap();
+    const descriptors = projectComponentIntrospection(world.components.entries());
+    const descriptor = descriptors.find((entry) => entry.name === Visibility.name);
+
+    expect(descriptor).toBeDefined();
+    expect(descriptor?.schema).toEqual(componentSchema(Visibility));
+    expect(descriptor?.fields.state?.labels).toEqual(Visibility.fields.state?.labels);
+    expect(descriptor?.fields.state?.type).toBe('enum');
+  });
+
+  it('projects field and component metadata without leaking component tokens', () => {
+    const world = new World();
+    world.components.register(Probe).unwrap();
+    const descriptors = projectComponentIntrospection(world.components.entries());
+    const descriptor = descriptors.find((entry) => entry.name === Probe.name);
+
+    expect(descriptor).toMatchObject({
+      name: Probe.name,
+      schema: componentSchema(Probe),
+      fields: {
+        mode: { type: 'enum', labels: Probe.fields.mode?.labels },
+        name: { type: 'string' },
+      },
+      meta: componentDefinition(Probe).policy.meta,
+    });
+    expect(descriptor).not.toHaveProperty('id');
+    expect(descriptor).not.toHaveProperty('validate');
+    expect(descriptor).not.toHaveProperty('toSchemaJSON');
+    expect(JSON.parse(JSON.stringify(descriptor))).toEqual(descriptor);
+  });
+});

package/src/__tests__/consumer-migration.unit.test.ts

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Time, Update, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+
+describe('callback consumer migration', () => {
+  it('registers character-style per-frame work as an Update system reading Time', () => {
+    const world = new World();
+    let observed = 0;
+    world
+      .addSystem(Update, {
+        name: 'character-drive',
+        queries: [],
+        fn: () => {
+          observed = world.getResource(Time).delta;
+        },
+      })
+      .unwrap();
+
+    world.update(1 / 60).unwrap();
+    expect(observed).toBeCloseTo(1 / 60);
+  });
+
+  it('uses the receipt-bound renderer host contract', () => {
+    const source = [
+      readFileSync(resolve(process.cwd(), 'packages/app/src/create-app.ts'), 'utf8'),
+      readFileSync(resolve(process.cwd(), 'packages/app/src/internal/frame-loop.ts'), 'utf8'),
+    ].join('\n');
+    expect(source).toContain('renderer.attach(');
+    expect(source).toContain('renderer.draw({');
+    expect(source).not.toContain('renderer.ready');
+    expect(source).not.toContain('renderer.device');
+  });
+});

package/src/__tests__/create-app-error-retention.integration.test.ts

@@ -0,0 +1,125 @@
+import { Update, World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import { RhiError } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import { createApp } from '../create-app';
+import type { AppDispatchError } from '../types';
+
+function makeRenderer(): {
+  readonly renderer: Renderer;
+  readonly draw: ReturnType<typeof vi.fn>;
+  readonly emit: (error: RhiError) => void;
+} {
+  const draw = vi.fn(() => ({ ok: true as const, value: undefined }));
+  let listener: ((event: { readonly kind: 'error'; readonly error: RhiError }) => void) | undefined;
+  const renderer = {
+    backend: 'webgpu' as const,
+    ready: Promise.resolve({ ok: true as const, value: undefined }),
+    draw,
+    attach: () => ({ ok: true as const, value: { dispose: () => undefined } }),
+    attachWorld: () => ({ ok: true as const, value: undefined }),
+    detachWorld: () => undefined,
+    subscribe: (next: (event: { readonly kind: 'error'; readonly error: RhiError }) => void) => {
+      listener = next;
+      return () => {
+        if (listener === next) listener = undefined;
+      };
+    },
+    onLost: () => () => undefined,
+    dispose: () => undefined,
+  } as unknown as Renderer;
+  return { renderer, draw, emit: (error) => listener?.({ kind: 'error', error }) };
+}
+
+function installFaultingSystem(world: World, cause: Error): void {
+  world
+    .addSystem(Update, {
+      name: 'retention-faulting-update',
+      queries: [],
+      fn: () => {
+        throw cause;
+      },
+    })
+    .unwrap();
+}
+
+async function createPausedApp(world: World, renderer: Renderer, silenceUnhandledErrors = true) {
+  const result = await createApp({ renderer, world, silenceUnhandledErrors });
+  expect(result.ok).toBe(true);
+  if (!result.ok) throw result.error;
+  result.value.start().unwrap();
+  result.value.pause().unwrap();
+  return result.value;
+}
+
+describe('createApp error retention', () => {
+  it('retains a real frame/update system failure through the main dispatch owner', async () => {
+    const cause = new Error('boom');
+    const world = new World();
+    installFaultingSystem(world, cause);
+    const { renderer, draw } = makeRenderer();
+    const app = await createPausedApp(world, renderer);
+    let observed: AppDispatchError | undefined;
+    app.onError((error) => {
+      observed = error;
+    });
+
+    const frame = app.stepFrame(1 / 60);
+
+    expect(frame.ok).toBe(false);
+    if (frame.ok) return;
+    expect(frame.error.code).toBe('app-system-update-failed');
+    if (frame.error.code !== 'app-system-update-failed') return;
+    const updateError = frame.error.detail.cause as {
+      readonly code?: string;
+      readonly detail?: { readonly cause?: unknown };
+    };
+    expect(updateError.code).toBe('system-failed');
+    expect(updateError.detail?.cause).toBe(cause);
+    expect(observed).toBe(frame.error);
+    expect(app.lastError).toBe(frame.error);
+    expect(world.execution.health).toBe('poisoned');
+    expect(world.inspect().systems.map((system) => system.name)).toContain(
+      'retention-faulting-update',
+    );
+    expect(draw).not.toHaveBeenCalled();
+  });
+
+  it('retains the same structured failure when console fallback is the only observer', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const world = new World();
+    installFaultingSystem(world, new Error('unobserved boom'));
+    const { renderer } = makeRenderer();
+    const app = await createPausedApp(world, renderer, false);
+
+    const frame = app.stepFrame(1 / 60);
+
+    expect(frame.ok).toBe(false);
+    if (!frame.ok) {
+      expect(consoleError).toHaveBeenCalledTimes(1);
+      expect(consoleError).toHaveBeenCalledWith(frame.error);
+      expect(app.lastError).toBe(frame.error);
+    }
+    consoleError.mockRestore();
+  });
+
+  it('preserves renderer device-loss identity and retention', async () => {
+    const world = new World();
+    const { renderer, emit } = makeRenderer();
+    const app = await createPausedApp(world, renderer);
+    let observed: AppDispatchError | undefined;
+    app.onError((error) => {
+      observed = error;
+    });
+    const deviceLoss = new RhiError({
+      code: 'device-lost',
+      expected: 'the test device remains available',
+      hint: 'rebuild the renderer after device recovery',
+    });
+
+    emit(deviceLoss);
+
+    expect(observed).toBe(deviceLoss);
+    expect(app.lastError).toBe(deviceLoss);
+  });
+});

package/src/__tests__/create-app-features.test.ts

@@ -0,0 +1,51 @@
+import type { RenderFeature } from '@forgeax/engine-render';
+import { describe, expect, it, vi } from 'vitest';
+
+const constructRuntimeRendererHost = vi.hoisted(() => vi.fn());
+
+vi.mock('@forgeax/engine-runtime', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@forgeax/engine-runtime')>();
+  return actual;
+});
+
+vi.mock('@forgeax/engine-runtime/internal/renderer-host', () => ({
+  constructRuntimeRendererHost,
+  loadRhiPack: vi.fn(),
+}));
+
+import { createApp } from '../create-app';
+
+function rendererStub() {
+  const lease = {};
+  return {
+    attach: () => ({ ok: true as const, value: lease }),
+    draw: () => ({ ok: true as const, value: {} }),
+    observe: async () => ({ ok: true as const, value: {} }),
+    releaseSurface: () => ({ ok: true as const, value: undefined }),
+    restoreSurface: () => ({ ok: true as const, value: undefined }),
+    recover: async () => ({ ok: true as const, value: undefined }),
+    onError: () => () => undefined,
+    onLost: () => () => undefined,
+    dispose: () => undefined,
+  };
+}
+
+describe('createApp features passthrough', () => {
+  it('forwards the same ordered feature array to createRenderer', async () => {
+    const first = { identity: 'test.first' } as unknown as RenderFeature<unknown>;
+    const second = { identity: 'test.second' } as unknown as RenderFeature<unknown>;
+    const features = [first, second] as const;
+    constructRuntimeRendererHost.mockResolvedValue({
+      ok: true,
+      value: { renderer: rendererStub(), assets: undefined },
+    });
+
+    const canvas = { tagName: 'canvas', isConnected: true } as HTMLCanvasElement;
+    const result = await createApp(canvas, { features });
+
+    expect(result.ok).toBe(true);
+    expect(constructRuntimeRendererHost).toHaveBeenCalledTimes(1);
+    expect(constructRuntimeRendererHost.mock.calls[0]?.[1]).toMatchObject({ features });
+    expect(constructRuntimeRendererHost.mock.calls[0]?.[1].features).toBe(features);
+  });
+});