@forgeax/engine-app 0.1.2

package/schema/execution-report.schema.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgeax.dev/schema/execution-report.schema.json",
+  "title": "ForgeaX ExecutionReport",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "requestedTier",
+    "actualTier",
+    "selectionReason",
+    "sharedEvidencePassed",
+    "capabilities",
+    "engine",
+    "world",
+    "kernelDispatch",
+    "performance",
+    "audio",
+    "fault"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "requestedTier": { "enum": ["auto", "main-serial", "engine-worker", "shared"] },
+    "actualTier": { "enum": [null, "main-serial", "engine-worker", "shared"] },
+    "selectionReason": {
+      "enum": [null, "explicit-request", "auto-shared", "auto-engine-worker", "auto-main-serial"]
+    },
+    "sharedEvidencePassed": { "type": "boolean" },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker",
+        "offscreenCanvas",
+        "workerAnimationFrame",
+        "workerWebGpu",
+        "crossOriginIsolated",
+        "sharedArrayBuffer",
+        "atomicsWait"
+      ],
+      "properties": {
+        "worker": { "$ref": "#/$defs/capability" },
+        "offscreenCanvas": { "$ref": "#/$defs/capability" },
+        "workerAnimationFrame": { "$ref": "#/$defs/capability" },
+        "workerWebGpu": { "$ref": "#/$defs/capability" },
+        "crossOriginIsolated": { "$ref": "#/$defs/capability" },
+        "sharedArrayBuffer": { "$ref": "#/$defs/capability" },
+        "atomicsWait": { "$ref": "#/$defs/capability" }
+      }
+    },
+    "engine": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["realm", "health"],
+      "properties": {
+        "realm": { "enum": ["host", "worker"] },
+        "health": { "enum": ["idle", "starting", "running", "stopped", "faulted"] }
+      }
+    },
+    "world": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["identity", "health", "partialWrite", "retryable"],
+      "properties": {
+        "identity": { "type": ["string", "null"] },
+        "health": { "enum": ["healthy", "poisoned"] },
+        "partialWrite": { "type": "boolean" },
+        "retryable": { "type": "boolean" }
+      }
+    },
+    "kernelDispatch": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["eligible", "usedShared", "reason", "dispatched", "completed"],
+      "properties": {
+        "eligible": { "type": "boolean" },
+        "usedShared": { "type": "boolean" },
+        "reason": {
+          "enum": ["no-eligible-kernel", "zero-work", "small-span", "forced-inline", "shared", "poisoned"]
+        },
+        "dispatched": { "type": "integer", "minimum": 0 },
+        "completed": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "performance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hostFrameMs", "engineUpdateMs", "kernelWaitMs", "hostAudioMs"],
+      "properties": {
+        "hostFrameMs": { "$ref": "#/$defs/nullableMeasurement" },
+        "engineUpdateMs": { "$ref": "#/$defs/nullableMeasurement" },
+        "kernelWaitMs": { "$ref": "#/$defs/nullableMeasurement" },
+        "hostAudioMs": { "$ref": "#/$defs/nullableMeasurement" }
+      }
+    },
+    "audio": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["owner", "contextState", "activeSourceCount", "lastError"],
+      "properties": {
+        "owner": { "const": "host" },
+        "contextState": { "enum": ["running", "suspended", "closed"] },
+        "activeSourceCount": { "type": "integer", "minimum": 0 },
+        "lastError": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["code", "expected", "hint", "detail"],
+              "properties": {
+                "code": { "type": "string", "minLength": 1 },
+                "expected": { "type": "string", "minLength": 1 },
+                "hint": { "type": "string", "minLength": 1 },
+                "detail": {}
+              }
+            }
+          ]
+        }
+      }
+    },
+    "fault": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["source", "code", "expected", "hint", "detail", "partialWrite", "retryable"],
+          "properties": {
+            "source": { "enum": ["bootstrap", "handshake", "runtime", "kernel", "world", "rebuild"] },
+            "code": { "type": "string", "minLength": 1 },
+            "expected": { "type": "string", "minLength": 1 },
+            "hint": { "type": "string", "minLength": 1 },
+            "detail": {},
+            "partialWrite": { "type": "boolean" },
+            "retryable": { "type": "boolean" }
+          }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "capability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["available", "reason"],
+      "properties": {
+        "available": { "type": "boolean" },
+        "reason": { "type": "string" }
+      }
+    },
+    "measurement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["samples", "p50", "p95", "p99", "jitter"],
+      "properties": {
+        "samples": { "type": "integer", "minimum": 1 },
+        "p50": { "type": "number", "minimum": 0 },
+        "p95": { "type": "number", "minimum": 0 },
+        "p99": { "type": "number", "minimum": 0 },
+        "jitter": { "type": "number", "minimum": 0 }
+      }
+    },
+    "nullableMeasurement": {
+      "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/measurement" }]
+    }
+  }
+}

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__/app-rebuild.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { disposeWithOrderedDetail, RebuildLifecycleError } from '../execution/attached-world-swap';
+
+describe('M4 app rebuild lifecycle', () => {
+  it('retains primary failure while recording both cleanup failures in order', async () => {
+    const cleanup: { phase: 'candidate' | 'previous'; cause: unknown }[] = [];
+    const primary = new Error('system throw');
+    await disposeWithOrderedDetail(
+      'candidate',
+      () => {
+        throw new Error('candidate cleanup');
+      },
+      cleanup,
+    );
+    await disposeWithOrderedDetail(
+      'previous',
+      () => {
+        throw new Error('previous cleanup');
+      },
+      cleanup,
+    );
+
+    const failure = new RebuildLifecycleError(primary, cleanup);
+    expect(failure.primary).toBe(primary);
+    expect(failure.cleanup.map((entry) => entry.phase)).toEqual(['candidate', 'previous']);
+    expect(failure.cleanup.map((entry) => (entry.cause as Error).message)).toEqual([
+      'candidate cleanup',
+      'previous cleanup',
+    ]);
+  });
+});

package/src/__tests__/asset-registry-types.test-d.ts

@@ -0,0 +1,16 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { EngineContextServices } from '@forgeax/engine-plugin';
+import type { RenderAssetPort } from '@forgeax/engine-render';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { App, GameHost } from '../index';
+
+describe('app asset ownership types', () => {
+  it('keeps the GameHost loader registry distinct from the App render projection', () => {
+    expectTypeOf<GameHost['assets']>().toEqualTypeOf<AssetRegistry>();
+    expectTypeOf<App['assets']>().toEqualTypeOf<AssetRegistry>();
+  });
+
+  it('augments the engine service with the Renderer-owned port', () => {
+    expectTypeOf<EngineContextServices['assets']>().toEqualTypeOf<RenderAssetPort | undefined>();
+  });
+});

package/src/__tests__/assets-runtime-assembly.integration.test.ts

@@ -0,0 +1,68 @@
+import {
+  createAssetRegistry,
+  createCatalogSource,
+  defineAssetKind,
+} from '@forgeax/engine-assets-runtime';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { assembleAssetRuntime } from '../assets-runtime-assembly';
+
+const kind = defineAssetKind<unknown, 'host-blob'>('host-blob');
+
+describe('App asset runtime assembly', () => {
+  it('installs the one default owner contribution for each durable built-in kind', () => {
+    const registry = createAssetRegistry({ catalog: createCatalogSource({ entries: [] }) });
+    const assembled = assembleAssetRuntime(registry, []);
+
+    expect(assembled.ok).toBe(true);
+    if (!assembled.ok) return;
+    expect(assembled.value.leases.map((lease) => lease.kind)).toEqual([
+      'mesh',
+      'material',
+      'scene',
+      'texture',
+      'equirect',
+      'sampler',
+      'font',
+      'render-pipeline',
+      'tileset',
+      'video',
+      'skeleton',
+      'skin',
+      'animation-clip',
+      'animation-graph',
+      'audio',
+      'particle-effect',
+    ]);
+    assembled.value.dispose();
+    registry.dispose();
+  });
+
+  it('installs one owner lease and releases it idempotently', () => {
+    const registry = createAssetRegistry({ catalog: createCatalogSource({ entries: [] }) });
+    const assembled = assembleAssetRuntime(registry, [
+      { kind, consumer: 'test-owner', decoder: { decode: async () => ok('value') } },
+    ]);
+
+    expect(assembled.ok).toBe(true);
+    if (!assembled.ok) return;
+    expect(assembled.value.leases).toHaveLength(17);
+    expect(assembled.value.leases.at(-1)?.kind).toBe('host-blob');
+    assembled.value.dispose();
+    assembled.value.dispose();
+    registry.dispose();
+  });
+
+  it('returns a closed assembly error for duplicate owner kinds', () => {
+    const registry = createAssetRegistry({ catalog: createCatalogSource({ entries: [] }) });
+    const contribution = {
+      kind,
+      consumer: 'test-owner',
+      decoder: { decode: async () => ok('value') },
+    };
+    const assembled = assembleAssetRuntime(registry, [contribution, contribution]);
+
+    expect(assembled).toMatchObject({ ok: false, error: { code: 'asset-assembly-failed' } });
+    registry.dispose();
+  });
+});

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,32 @@
+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) => {
+  created.ready.then((ready) => {
+    if (!ready.ok) return;
+    void created.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+  });
+});

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,21 @@
+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);
+  });
+});

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

@@ -0,0 +1,40 @@
+import type { RenderFeature } from '@forgeax/engine-render';
+import { describe, expect, it, vi } from 'vitest';
+
+const createRenderer = vi.hoisted(() => vi.fn());
+
+vi.mock('@forgeax/engine-runtime', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@forgeax/engine-runtime')>();
+  return { ...actual, createRenderer };
+});
+
+import { createApp } from '../create-app';
+
+function rendererStub() {
+  return {
+    backend: 'webgpu' as const,
+    ready: Promise.resolve({ ok: true as const, value: undefined }),
+    draw: () => ({ ok: true as const, value: undefined }),
+    onError: () => () => undefined,
+    onLost: () => () => undefined,
+    onHealthChange: () => () => 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;
+    createRenderer.mockResolvedValue(rendererStub());
+
+    const canvas = { tagName: 'canvas', isConnected: true } as HTMLCanvasElement;
+    const result = await createApp(canvas, { features });
+
+    expect(result.ok).toBe(true);
+    expect(createRenderer).toHaveBeenCalledTimes(1);
+    expect(createRenderer.mock.calls[0]?.[1]).toMatchObject({ features });
+    expect(createRenderer.mock.calls[0]?.[1].features).toBe(features);
+  });
+});