@forgeax/engine-app 0.1.2

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

@@ -0,0 +1,82 @@
+// create-app.test-d.ts -- compile-time assertions for w2 acceptanceCheck.
+//
+// Anchors:
+// - createApp(canvas, opts?) returns
+//   Promise<Result<App, AppError | RhiError | EngineEnvironmentError>>
+//   per AC-01 (canvas thin wrapper widens the error union with
+//   EngineEnvironmentError; M2 plugin-system-unify D-7 widens it with
+//   AppError for Cordis activation failures).
+// - createApp({ renderer, world }) returns
+//   Promise<Result<App, AppError | RhiError>>
+//   per AC-02 (assemble form excludes EngineEnvironmentError -- renderer
+//   host-managed).
+// - 'tagName' in arg dispatch lands the right overload at the call site
+//   (HTMLCanvasElement -> canvas form; AppAssembleArgs -> assemble form).
+//
+// charter awareness:
+// - P3 explicit failure: Result envelope shape is type-level (no message strings).
+// - P4 consistent abstraction: both routes return the same App handle.
+
+import type { World } from '@forgeax/engine-ecs';
+import type { Renderer, RendererOptions } from '@forgeax/engine-render';
+import type { RhiError } from '@forgeax/engine-rhi/errors';
+import type { EngineEnvironmentError } from '@forgeax/engine-runtime';
+import type { Result } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { AssetRuntimeAssemblyError } from '../assets-runtime-assembly';
+import { type App, type AppError, createApp } from '../index';
+import type { RhiCaptureHook } from '../types';
+
+describe('createApp double-SSOT entry signatures (w2 acceptanceCheck)', () => {
+  it('canvas form returns the App boundary error union', () => {
+    const canvas = null as unknown as HTMLCanvasElement;
+    const ret = createApp(canvas);
+    expectTypeOf(ret).toEqualTypeOf<
+      Promise<Result<App, AppError | RhiError | AssetRuntimeAssemblyError | EngineEnvironmentError>>
+    >();
+  });
+
+  it('assemble form returns the App boundary error union', () => {
+    const renderer = null as unknown as Renderer;
+    const world = null as unknown as World;
+    const ret = createApp({ renderer, world });
+    expectTypeOf(ret).toEqualTypeOf<
+      Promise<Result<App, AppError | RhiError | AssetRuntimeAssemblyError>>
+    >();
+  });
+
+  it('app.renderer / app.world are reference-equal types at the call site (AC-09)', async () => {
+    const renderer = null as unknown as Renderer;
+    const world = null as unknown as World;
+    const result = await createApp({ renderer, world });
+    if (result.ok) {
+      expectTypeOf(result.value.renderer).toEqualTypeOf<Renderer>();
+      expectTypeOf(result.value.world).toEqualTypeOf<World>();
+    }
+  });
+
+  it('main and Worker execution share the same global capture hook shape', () => {
+    const captureFrame = (globalThis as { __forgeax?: RhiCaptureHook }).__forgeax?.captureFrame;
+    expectTypeOf(captureFrame).toEqualTypeOf<RhiCaptureHook['captureFrame'] | undefined>();
+  });
+});
+
+// feat-20260608-create-app-param-surface-trim / M1 / AC-02 + TASK-006:
+// `RendererOptions.clearColor` was deleted in this feat. AI users that
+// pass `{ clearColor: ... }` to `createRenderer` / `createApp` get a
+// TS2353 excess-property error at compile time (no shim, no
+// deprecation window per AGENTS.md §Change stance).
+describe('RendererOptions.clearColor removal (AC-02 + TASK-006)', () => {
+  it('RendererOptions does not carry a `clearColor` field', () => {
+    // The keyof of RendererOptions must not include 'clearColor'.
+    type Keys = keyof RendererOptions;
+    type HasClearColor = 'clearColor' extends Keys ? true : false;
+    expectTypeOf<HasClearColor>().toEqualTypeOf<false>();
+  });
+
+  it('passing `clearColor` as an object literal is a compile-time error (TS2353)', () => {
+    // @ts-expect-error -- 'clearColor' is not assignable to RendererOptions
+    const opts: RendererOptions = { clearColor: [0, 0, 0, 1] };
+    void opts;
+  });
+});

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

@@ -0,0 +1,346 @@
+// M3 / w15: FORGEAX_ENGINE_RHI_DEBUG guard three-segment dual-source evaluation.
+//
+// The canvas-form guard in create-app.ts reads the flag from two sources with a
+// precise precedence + short-circuit shape (plan-strategy D-4):
+//
+//   (typeof import.meta !== 'undefined' && import.meta.env?.FORGEAX_ENGINE_RHI_DEBUG)
+//     ?? globalThis.process?.env?.FORGEAX_ENGINE_RHI_DEBUG
+//
+// That expression is extracted into the pure `resolveRhiDebugFlag` helper so the
+// three deployment scenarios can be exercised without a real bundler / runtime:
+//   (a) browser: import.meta.env replaced by the vite define -> '1' wins
+//   (b) dawn-node: import.meta absent (modelled as undefined env) -> falls
+//       through to globalThis.process.env
+//   (c) unset: neither source carries '1' -> undefined -> guard does not fire
+//
+// C5 (plan-strategy): the `typeof import.meta !== 'undefined'` prefix must
+// short-circuit before any `.env` access, because under dawn-node `import.meta`
+// itself can be undefined; passing `undefined` for the import.meta.env arg is
+// the unit-level model of that prefix evaluating to false.
+//
+// OOS-1/2: only the DevTools-trigger path is in scope; this test does not
+// exercise external HTTP triggers or in-page buttons.
+
+import { World } from '@forgeax/engine-ecs';
+import { Camera, orthographic, perspective } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+import { createApp, syncCameraAspect, syncCanvasDrawingBuffer } from '../create-app';
+import { AppError } from '../errors';
+import { resolveRhiDebugFlag } from '../internal/rhi-debug-flag';
+
+describe('create-app.test.ts', () => {
+  describe('resolveRhiDebugFlag three-segment dual-source (w15 / D-4)', () => {
+    it('(a) browser: import.meta.env.FORGEAX_ENGINE_RHI_DEBUG === "1" wins', () => {
+      const flag = resolveRhiDebugFlag(
+        { FORGEAX_ENGINE_RHI_DEBUG: '1' },
+        { FORGEAX_ENGINE_RHI_DEBUG: undefined },
+      );
+      expect(flag).toBe('1');
+    });
+
+    it('(b) dawn-node: import.meta absent -> falls through to process.env', () => {
+      // `undefined` models `typeof import.meta === 'undefined'` short-circuiting
+      // the first operand to a falsy value, so the `??` chain consults process.env.
+      const flag = resolveRhiDebugFlag(undefined, { FORGEAX_ENGINE_RHI_DEBUG: '1' });
+      expect(flag).toBe('1');
+    });
+
+    it('(b2) import.meta.env present but flag unset -> still falls through to process.env', () => {
+      // `import.meta.env` exists (vite always injects it) but the key is absent;
+      // the first operand is `undefined`, so `??` consults process.env.
+      const flag = resolveRhiDebugFlag({}, { FORGEAX_ENGINE_RHI_DEBUG: '1' });
+      expect(flag).toBe('1');
+    });
+
+    it('(c) unset: neither source carries the flag -> undefined (guard does not fire)', () => {
+      expect(resolveRhiDebugFlag(undefined, undefined)).toBeUndefined();
+      expect(resolveRhiDebugFlag({}, {})).toBeUndefined();
+      expect(
+        resolveRhiDebugFlag(
+          { FORGEAX_ENGINE_RHI_DEBUG: undefined },
+          { FORGEAX_ENGINE_RHI_DEBUG: undefined },
+        ),
+      ).toBeUndefined();
+    });
+
+    it('import.meta.env wins over process.env when both set (precedence)', () => {
+      // Browser path takes precedence: the `??` only consults process.env when
+      // the first operand is null/undefined, and '1' is neither.
+      const flag = resolveRhiDebugFlag(
+        { FORGEAX_ENGINE_RHI_DEBUG: '1' },
+        { FORGEAX_ENGINE_RHI_DEBUG: '0' },
+      );
+      expect(flag).toBe('1');
+    });
+
+    it('a non-"1" value is returned verbatim (guard compares === "1" at call site)', () => {
+      // resolveRhiDebugFlag returns the raw flag; the create-app guard does the
+      // `=== '1'` comparison. A '0' value must therefore not be coerced to fire.
+      expect(resolveRhiDebugFlag({ FORGEAX_ENGINE_RHI_DEBUG: '0' }, undefined)).toBe('0');
+    });
+  });
+
+  describe('zero-injection when flag unset (c) (w15 / F-3)', () => {
+    it('globalThis.__forgeax is undefined before any flagged createApp runs', () => {
+      // With the flag unset (the default unit-test environment: no vite define,
+      // no process.env override), the canvas form never touches globalThis, so
+      // the capture entry point does not exist. A DevTools caller invoking it
+      // would hit a TypeError -- the explicit-failure contract (charter P3).
+      const g = globalThis as { __forgeax?: { captureFrame?: unknown } };
+      expect(g.__forgeax).toBeUndefined();
+      expect(() => {
+        // Reading .captureFrame off an undefined __forgeax throws synchronously.
+        (g.__forgeax as { captureFrame: (n: number) => unknown }).captureFrame(1);
+      }).toThrow(TypeError);
+    });
+  });
+
+  describe('syncCanvasDrawingBuffer host boundary', () => {
+    it('matches the physical drawing buffer to CSS size at the device pixel ratio', () => {
+      const canvas = {
+        clientWidth: 800,
+        clientHeight: 400,
+        width: 300,
+        height: 150,
+        style: { width: '800px', height: '400px' },
+      };
+      const before = globalThis.devicePixelRatio;
+      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
+      try {
+        syncCanvasDrawingBuffer(canvas);
+        expect(canvas.width).toBe(1600);
+        expect(canvas.height).toBe(800);
+      } finally {
+        Object.defineProperty(globalThis, 'devicePixelRatio', {
+          configurable: true,
+          value: before,
+        });
+      }
+    });
+
+    it('applies a Host pixel-ratio cap without changing the default path', () => {
+      const canvas = {
+        clientWidth: 800,
+        clientHeight: 400,
+        width: 300,
+        height: 150,
+        style: { width: '800px', height: '400px' },
+      };
+      const before = globalThis.devicePixelRatio;
+      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
+      try {
+        syncCanvasDrawingBuffer(canvas, 1.5);
+        expect(canvas.width).toBe(1200);
+        expect(canvas.height).toBe(600);
+      } finally {
+        Object.defineProperty(globalThis, 'devicePixelRatio', {
+          configurable: true,
+          value: before,
+        });
+      }
+    });
+
+    it('allows the Host to downsample a GPU-bound canvas below CSS pixel density', () => {
+      const canvas = {
+        clientWidth: 800,
+        clientHeight: 400,
+        width: 300,
+        height: 150,
+        style: { width: '800px', height: '400px' },
+      };
+      const before = globalThis.devicePixelRatio;
+      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
+      try {
+        syncCanvasDrawingBuffer(canvas, 0.875);
+        expect(canvas.width).toBe(700);
+        expect(canvas.height).toBe(350);
+      } finally {
+        Object.defineProperty(globalThis, 'devicePixelRatio', {
+          configurable: true,
+          value: before,
+        });
+      }
+    });
+
+    it('rejects an invalid Host pixel-ratio cap before touching a detached canvas', async () => {
+      const result = await createApp(
+        { tagName: 'CANVAS', isConnected: false } as unknown as HTMLCanvasElement,
+        { maxCanvasPixelRatio: 0 },
+      );
+      expect(result.ok).toBe(false);
+      if (!result.ok && result.error instanceof AppError) {
+        expect(result.error.code).toBe('app-invalid-canvas-pixel-ratio');
+        if (result.error.code === 'app-invalid-canvas-pixel-ratio') {
+          expect(result.error.detail.value).toBe(0);
+        }
+      }
+    });
+
+    it('leaves a zero-sized host untouched', () => {
+      const canvas = { clientWidth: 0, clientHeight: 400, width: 300, height: 150 };
+      syncCanvasDrawingBuffer(canvas);
+      expect(canvas.width).toBe(300);
+      expect(canvas.height).toBe(150);
+    });
+
+    it('leaves a headless canvas without CSS dimensions untouched', () => {
+      const canvas = { width: 320, height: 180 } as HTMLCanvasElement;
+      syncCanvasDrawingBuffer(canvas);
+      expect(canvas.width).toBe(320);
+      expect(canvas.height).toBe(180);
+    });
+
+    it('preserves an intrinsic canvas drawing buffer without CSS dimensions', () => {
+      let width = 256;
+      let height = 256;
+      const canvas = {
+        get clientWidth() {
+          return width;
+        },
+        get clientHeight() {
+          return height;
+        },
+        get width() {
+          return width;
+        },
+        set width(value: number) {
+          width = value;
+        },
+        get height() {
+          return height;
+        },
+        set height(value: number) {
+          height = value;
+        },
+      };
+      const before = globalThis.devicePixelRatio;
+      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
+      try {
+        syncCanvasDrawingBuffer(canvas);
+        syncCanvasDrawingBuffer(canvas);
+        expect(width).toBe(256);
+        expect(height).toBe(256);
+      } finally {
+        Object.defineProperty(globalThis, 'devicePixelRatio', {
+          configurable: true,
+          value: before,
+        });
+      }
+    });
+
+    it('does not repeatedly scale a CSS-sized canvas when layout follows width writes', () => {
+      let width = 256;
+      let height = 256;
+      const canvas = {
+        clientWidth: 256,
+        clientHeight: 256,
+        style: { width: '256px', height: '256px' },
+        get width() {
+          return width;
+        },
+        set width(value: number) {
+          width = value;
+          canvas.clientWidth = value;
+        },
+        get height() {
+          return height;
+        },
+        set height(value: number) {
+          height = value;
+          canvas.clientHeight = value;
+        },
+      };
+      const before = globalThis.devicePixelRatio;
+      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
+      try {
+        syncCanvasDrawingBuffer(canvas);
+        syncCanvasDrawingBuffer(canvas);
+        expect(width).toBe(512);
+        expect(height).toBe(512);
+      } finally {
+        Object.defineProperty(globalThis, 'devicePixelRatio', {
+          configurable: true,
+          value: before,
+        });
+      }
+    });
+  });
+
+  // feat-20260617 M3 / w10: aspect-sync sidecar (createApp path only).
+  // syncCameraAspect is the canvas-form per-frame Update system body
+  // closure calls with the live canvas width/height. It walks Camera entities via
+  // world.get (NOT the query bundle: a bool column read off the bundle returns a
+  // raw 0/1 number, so `!== 0` is always true -- the
+  // bool-field-compared-with-not-equal-zero-always-true trap; D-5/Finding 2). It
+  // writes canvas.width/height into Camera.aspect for perspective + autoAspect=true
+  // cameras only.
+  describe('syncCameraAspect sidecar (w10 / AC-07)', () => {
+    it('canvas resize -> perspective autoAspect=true camera aspect becomes w/h', () => {
+      const world = new World();
+      const cam = world
+        .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1 }) })
+        .unwrap();
+
+      syncCameraAspect(world, 800, 400);
+
+      const r = world.get(cam, Camera);
+      expect(r.ok).toBe(true);
+      if (!r.ok) return;
+      expect(r.value.aspect).toBeCloseTo(2, 5);
+    });
+
+    it('autoAspect=false camera is left untouched', () => {
+      const world = new World();
+      const cam = world
+        .spawn({
+          component: Camera,
+          data: perspective({ fov: 1, aspect: 1.234, autoAspect: false }),
+        })
+        .unwrap();
+
+      syncCameraAspect(world, 800, 400);
+
+      const r = world.get(cam, Camera);
+      expect(r.ok).toBe(true);
+      if (!r.ok) return;
+      expect(r.value.aspect).toBeCloseTo(1.234, 5);
+    });
+
+    it('canvas size 0 is skipped (no NaN / 0 written into aspect)', () => {
+      const world = new World();
+      const cam = world
+        .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1.5 }) })
+        .unwrap();
+
+      syncCameraAspect(world, 0, 0);
+
+      const r = world.get(cam, Camera);
+      expect(r.ok).toBe(true);
+      if (!r.ok) return;
+      expect(r.value.aspect).toBeCloseTo(1.5, 5);
+      expect(Number.isNaN(r.value.aspect)).toBe(false);
+    });
+
+    it('orthographic camera is left untouched', () => {
+      const world = new World();
+      const cam = world
+        .spawn({
+          component: Camera,
+          data: orthographic({ left: -1, right: 1, bottom: -1, top: 1 }),
+        })
+        .unwrap();
+      const before = world.get(cam, Camera);
+      expect(before.ok).toBe(true);
+      if (!before.ok) return;
+      const aspectBefore = before.value.aspect;
+
+      syncCameraAspect(world, 800, 400);
+
+      const r = world.get(cam, Camera);
+      expect(r.ok).toBe(true);
+      if (!r.ok) return;
+      expect(r.value.aspect).toBeCloseTo(aspectBefore, 5);
+    });
+  });
+});

package/src/__tests__/create-renderer-error.integration.test.ts

@@ -0,0 +1,24 @@
+import { createRenderer, EngineEnvironmentError } from '@forgeax/engine-runtime';
+import { describe, expect, it } from 'vitest';
+import { createApp } from '../create-app';
+
+describe('app renderer construction boundary', () => {
+  it('keeps construction failures catchable', async () => {
+    await expect(createRenderer(null as never)).rejects.toBeDefined();
+  });
+
+  it('returns EngineEnvironmentError through the canvas Result path', async () => {
+    const canvas = {
+      tagName: 'CANVAS',
+      isConnected: true,
+      width: 16,
+      height: 16,
+      getContext: () => null,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    } as unknown as HTMLCanvasElement;
+    const result = await createApp(canvas, { rhi: undefined });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toBeInstanceOf(EngineEnvironmentError);
+  });
+});

package/src/__tests__/create-renderer-lifecycle.integration.test.ts

@@ -0,0 +1,19 @@
+import type { Renderer } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+describe('app-facing renderer lifecycle', () => {
+  it('consumes the three lifecycle Result boundaries without casts', async () => {
+    const events: string[] = [];
+    const renderer = {
+      ready: Promise.resolve({ ok: true as const, value: undefined }),
+      draw: () => ({ ok: true as const, value: undefined }),
+      dispose: () => events.push('dispose'),
+    } as unknown as Renderer;
+    const ready = await renderer.ready;
+    expect(ready.ok).toBe(true);
+    expect(renderer.draw([], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    renderer.dispose();
+    renderer.dispose();
+    expect(events).toEqual(['dispose', 'dispose']);
+  });
+});

package/src/__tests__/docs-gate-green.unit.test.ts

@@ -0,0 +1,61 @@
+// @perf-budget-skip: intentional documentation subprocess gate.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const repoRoot = resolve(fileURLToPath(new URL('../../../..', import.meta.url)));
+const docsGate = resolve(repoRoot, 'scripts/forgeax/check-token-first-docs.mjs');
+
+function runDocsGate(): { readonly status: number; readonly output: string } {
+  try {
+    const output = execFileSync(process.execPath, [docsGate], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { status: 0, output };
+  } catch (error: unknown) {
+    const result = error as {
+      readonly status?: number;
+      readonly stdout?: string;
+      readonly stderr?: string;
+    };
+    return {
+      status: result.status ?? 1,
+      output: `${result.stdout ?? ''}${result.stderr ?? ''}`,
+    };
+  }
+}
+
+describe('M5 active-documentation token-first gate', () => {
+  it('keeps the engine-owned active documentation surface present', () => {
+    for (const path of [
+      'packages/ecs/README.md',
+      'packages/app/README.md',
+      'packages/audio-webaudio/README.md',
+      'packages/input/README.md',
+      'packages/runtime/README.md',
+      'packages/state/README.md',
+      'skills/forgeax-engine-ecs/SKILL.md',
+      'skills/forgeax-engine-app/SKILL.md',
+      'skills/forgeax-engine-audio/SKILL.md',
+      'skills/forgeax-engine-state/SKILL.md',
+      'apps/hello/sprite-atlas/README.md',
+      'apps/learn-render/1.getting-started/5.transformations/README.md',
+      'apps/learn-render/1.getting-started/7.camera/README.md',
+      'apps/learn-render/2.lighting/3.materials/README.md',
+      'packages/ecs/CHANGELOG.md',
+    ]) {
+      expect(existsSync(resolve(repoRoot, path)), path).toBe(true);
+    }
+  });
+
+  it('accepts only token-first registration and explicit-delta update examples', () => {
+    const result = runDocsGate();
+    expect(result.status, result.output).toBe(0);
+    expect(result.output).toContain('Active-documentation token-first gate passed');
+  });
+});