@forgeax/engine-app 0.1.2

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

@@ -0,0 +1,74 @@
+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,
+      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,
+    });
+    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,76 @@
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import { describe, expect, it, vi } from 'vitest';
+import { commitAttachedWorld, SerializedRebuildQueue } from '../execution/attached-world-swap';
+
+function rendererOwner(): Pick<Renderer, 'attachWorld' | 'detachWorld'> {
+  return {
+    attachWorld: vi.fn(() => ({ ok: true as const, value: undefined })),
+    detachWorld: vi.fn(),
+  };
+}
+
+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 previous = new World();
+    const next = new World();
+
+    await expect(commitAttachedWorld(renderer, previous, next, async () => true)).resolves.toBe(
+      true,
+    );
+    expect(renderer.attachWorld).toHaveBeenCalledWith(next);
+    expect(renderer.detachWorld).toHaveBeenCalledOnce();
+    expect(renderer.detachWorld).toHaveBeenCalledWith(previous);
+  });
+
+  it('detaches a candidate whose bootstrap fails and keeps the previous World', async () => {
+    const renderer = rendererOwner();
+    const previous = new World();
+    const next = new World();
+
+    await expect(commitAttachedWorld(renderer, previous, next, async () => false)).resolves.toBe(
+      false,
+    );
+    expect(renderer.detachWorld).toHaveBeenCalledOnce();
+    expect(renderer.detachWorld).toHaveBeenCalledWith(next);
+    expect(renderer.detachWorld).not.toHaveBeenCalledWith(previous);
+  });
+
+  it('detaches a candidate whose bootstrap throws', async () => {
+    const renderer = rendererOwner();
+    const previous = new World();
+    const next = new World();
+
+    await expect(
+      commitAttachedWorld(renderer, previous, next, async () => {
+        throw new Error('bootstrap failed');
+      }),
+    ).rejects.toThrow('bootstrap failed');
+    expect(renderer.detachWorld).toHaveBeenCalledOnce();
+    expect(renderer.detachWorld).toHaveBeenCalledWith(next);
+  });
+});

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

@@ -0,0 +1,268 @@
+// 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-invalid-canvas-pixel-ratio',
+      '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(14);
+
+    // Each member must be unique.
+    const unique = new Set(allCodes);
+    expect(unique.size).toBe(14);
+  });
+
+  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-invalid-canvas-pixel-ratio':
+          return 'invalid canvas pixel ratio';
+        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(14);
+  });
+
+  it('APP_ERROR_HINTS has one key per AppErrorCode member', () => {
+    const keys = Object.keys(APP_ERROR_HINTS);
+    expect(keys).toHaveLength(14);
+  });
+
+  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,80 @@
+import { createWorldContext, Update, 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(){}};
+        const update=ctx.world.scheduleToken('Update');
+        ctx.world.addSystem(update,system).unwrap();
+        ctx.effect(()=>()=>ctx.world.removeSystem(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(Update)).toBe(1);
+    await context.fiber.dispose();
+    expect(world.inspect().scheduleSystemCount(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');
+    }
+  });
+});

package/src/__tests__/execution-error-detail.test-d.ts

@@ -0,0 +1,13 @@
+import { expectTypeOf, it } from 'vitest';
+import type { AppError } from '../index';
+
+it('narrows execution error detail by code', () => {
+  const error = null as unknown as AppError;
+  if (error.code === 'app-execution-kernel-failed') {
+    expectTypeOf(error.detail.partialWrite).toEqualTypeOf<true>();
+    expectTypeOf(error.detail.retryable).toEqualTypeOf<false>();
+  }
+  if (error.code === 'app-execution-deadline-exceeded') {
+    expectTypeOf(error.detail.phase).toEqualTypeOf<'startup' | 'handshake' | 'frame'>();
+  }
+});

package/src/__tests__/execution-error-detail.unit.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { APP_ERROR_HINTS, APP_EXPECTED, AppError, type AppErrorCode } from '../index';
+
+const EXECUTION_CODES = [
+  'app-execution-tier-unavailable',
+  'app-execution-bootstrap-failed',
+  'app-execution-deadline-exceeded',
+  'app-execution-kernel-failed',
+  'app-execution-stale-world',
+  'app-execution-rebuild-failed',
+] as const satisfies readonly AppErrorCode[];
+
+describe('execution errors', () => {
+  it('has executable expected and hint tables for every execution code', () => {
+    for (const code of EXECUTION_CODES) {
+      expect(APP_EXPECTED[code].length).toBeGreaterThan(0);
+      expect(APP_ERROR_HINTS[code].length).toBeGreaterThan(0);
+    }
+  });
+
+  it('exposes unavailable facts without message parsing', () => {
+    const error = new AppError({
+      code: 'app-execution-tier-unavailable',
+      expected: APP_EXPECTED['app-execution-tier-unavailable'],
+      hint: APP_ERROR_HINTS['app-execution-tier-unavailable'],
+      detail: {
+        requestedTier: 'shared',
+        missingCapabilities: ['sharedArrayBuffer'],
+        sharedEvidencePassed: true,
+      },
+    });
+    expect(error.detail.requestedTier).toBe('shared');
+    expect(error.detail.missingCapabilities).toEqual(['sharedArrayBuffer']);
+  });
+});

package/src/__tests__/execution-frame-order.unit.test.ts

@@ -0,0 +1,38 @@
+import type { InputBackendSample } from '@forgeax/engine-input';
+import { describe, expect, it } from 'vitest';
+import { FrameCreditLedger } from '../execution/protocol';
+
+describe('execution frame ordering', () => {
+  it('samples once and cannot issue the next credit before update, draw and completion', () => {
+    const trace: string[] = [];
+    let samples = 0;
+    const sample = (): InputBackendSample => {
+      samples += 1;
+      trace.push('sample');
+      return {
+        downKeys: new Set(),
+        upKeys: new Set(),
+        buttons: [false, false, false],
+        movementX: 0,
+        movementY: 0,
+        wheelDelta: 0,
+        focused: true,
+        pointerLocked: false,
+      };
+    };
+    const ledger = new FrameCreditLedger('world');
+    const frame = ledger.issue(1 / 60, sample, { width: 320, height: 180 });
+    expect(ledger.issue(1 / 60, sample, { width: 320, height: 180 })).toBeUndefined();
+    trace.push('update', 'draw');
+    ledger.complete({
+      kind: 'frame-complete',
+      worldIdentity: 'world',
+      frameId: frame?.frameId ?? 0,
+      engineUpdateMs: 1,
+      kernelWaitMs: 0,
+    });
+    trace.push('complete');
+    expect(trace).toEqual(['sample', 'update', 'draw', 'complete']);
+    expect(samples).toBe(1);
+  });
+});

package/src/__tests__/execution-frame-protocol.unit.test.ts

@@ -0,0 +1,61 @@
+import type { InputBackendSample } from '@forgeax/engine-input';
+import { describe, expect, it } from 'vitest';
+import { FrameCreditLedger } from '../execution/protocol';
+
+const sample: InputBackendSample = {
+  downKeys: new Set(),
+  upKeys: new Set(),
+  buttons: [false, false, false],
+  movementX: 0,
+  movementY: 0,
+  wheelDelta: 0,
+  focused: true,
+  pointerLocked: false,
+};
+
+describe('frame credit protocol', () => {
+  it('allows one in-flight frame and handles duplicate, late and old identities without writes', () => {
+    const ledger = new FrameCreditLedger('world-1');
+    const first = ledger.issue(0.016, () => sample, { width: 320, height: 180 });
+    expect(first?.frameId).toBe(1);
+    expect(first).toMatchObject({ canvasWidth: 320, canvasHeight: 180 });
+    expect(ledger.issue(0.016, () => sample, { width: 320, height: 180 })).toBeUndefined();
+    expect(
+      ledger.complete({
+        kind: 'frame-complete',
+        worldIdentity: 'old',
+        frameId: 1,
+        engineUpdateMs: 1,
+        kernelWaitMs: 0,
+      }),
+    ).toBe('stale-world');
+    expect(
+      ledger.complete({
+        kind: 'frame-complete',
+        worldIdentity: 'world-1',
+        frameId: 2,
+        engineUpdateMs: 1,
+        kernelWaitMs: 0,
+      }),
+    ).toBe('late');
+    expect(
+      ledger.complete({
+        kind: 'frame-complete',
+        worldIdentity: 'world-1',
+        frameId: 1,
+        engineUpdateMs: 1,
+        kernelWaitMs: 0,
+      }),
+    ).toBe('accepted');
+    expect(
+      ledger.complete({
+        kind: 'frame-complete',
+        worldIdentity: 'world-1',
+        frameId: 1,
+        engineUpdateMs: 1,
+        kernelWaitMs: 0,
+      }),
+    ).toBe('duplicate');
+    expect(ledger.issue(0.016, () => sample, { width: 640, height: 320 })?.frameId).toBe(2);
+  });
+});

package/src/__tests__/execution-input-sample.contract.test.ts

@@ -0,0 +1,23 @@
+import { type InputBackendSample, snapshotFromSample } from '@forgeax/engine-input';
+import { describe, expect, it } from 'vitest';
+
+describe('Host to Engine input boundary', () => {
+  it('reconstructs the existing InputSnapshot from one structured-cloneable sample', () => {
+    const sample: InputBackendSample = {
+      downKeys: new Set(['w']),
+      upKeys: new Set(),
+      buttons: [false, false, false],
+      movementX: 4,
+      movementY: -2,
+      wheelDelta: 1,
+      focused: true,
+      pointerLocked: true,
+    };
+    const clone = structuredClone(sample);
+    const snapshot = snapshotFromSample(clone);
+    expect(snapshot.keyboard.down('w')).toBe(true);
+    expect(snapshot.mouse.movementDelta).toEqual({ x: 4, y: -2 });
+    expect(clone).not.toHaveProperty('window');
+    expect(clone).not.toHaveProperty('document');
+  });
+});