@forgeax/engine-app 0.1.2

package/src/__tests__/draw-source-headless-full-chain.test.ts

@@ -0,0 +1,226 @@
+// feat-20260709-editor-world-partition-editorworld-super-composite / M2 / w10
+// (RED — impl lands in w12). Full-chain consumer test on the rhi-null headless
+// backend: the drawSource seam drives a REAL Renderer (createRenderer +
+// RhiNull) end-to-end — update -> extract -> record — with no GPU.
+//
+// Unlike w8 (spy renderer, call-shape) and w9 (spy renderer, stale-matrix), this
+// test exercises the actual runtime render pipeline through the seam. The camera
+// + light + visible mesh live ONLY in the injected world; the frame-loop's own
+// world is empty. So a non-zero draw count proves three things at once:
+//   1. drawSource is consumed (else the empty loop world is drawn -> 0 draws),
+//   2. the injected world was world.update(1 / 60).unwrap()'d (propagate ran; extract finds the
+//      camera + resolved Transform.world),
+//   3. the full URP record path fired headlessly (bookkeeper counts draws).
+//
+// rhi-null needs no GPU: navigator.gpu is stubbed undefined so createRenderer
+// selects the injected RhiNull instance, and the RhiNullDevice bookkeeper counts
+// draw / bind-group / pipeline records. File suffix `.test.ts` runs in the node
+// vitest project (no dawn / no browser).
+//
+// The frame-loop is driven directly (createFrameLoop + injected now/raf/caf)
+// rather than through createApp, because createApp's assemble form does not (yet
+// — that is w11) forward drawSource; w12 threads it into the loop. Driving the
+// loop directly keeps this test focused on the seam's runtime contract. The
+// drawSource option is reached through a typed alias before w12 widens the type.
+//
+// Anchors:
+//   plan-strategy §2 D-3 (drawSource pull -> update injected worlds -> draw)
+//   research F1 (frame-loop is the update -> draw driver; the seam insertion pt)
+//   feat-20260623 rhi-null-command-flow.unit.test.ts (headless full-chain
+//     precedent: createRenderer + RhiNull + bookkeeper counters)
+
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import {
+  Camera,
+  DirectionalLight,
+  MeshFilter,
+  MeshRenderer,
+  type Renderer,
+} from '@forgeax/engine-render';
+import type { RhiNullDevice } from '@forgeax/engine-rhi-null';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { createRenderer } from '@forgeax/engine-runtime';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createFrameLoop, type FrameLoopOptions } from '../internal/frame-loop';
+
+function makeStubCanvas(w = 800, h = 600): HTMLCanvasElement {
+  return {
+    width: w,
+    height: h,
+    getContext(_kind: string): unknown {
+      return null;
+    },
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+  } as unknown as HTMLCanvasElement;
+}
+
+function buildManifestDataUrl(): string {
+  const manifest = {
+    schemaVersion: '1.0.0',
+    entries: [
+      { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+      {
+        hash: 'tonemap0',
+        wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
+        glsl: '',
+        bindings: '',
+      },
+    ],
+  };
+  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+}
+
+function identityTransform(
+  overrides: Partial<Record<string, number[]>> = {},
+): Record<string, number[]> {
+  return {
+    pos: [0, 0, 0],
+    quat: [0, 0, 0, 1],
+    scale: [1, 1, 1],
+    ...overrides,
+  };
+}
+
+// The injected world carries the FULL renderable set (camera + light + visible
+// mesh). It also registers propagateTransforms so the frame-loop's world.update
+// resolves Transform.world before extract reads it.
+function makeInjectedWorld(): World {
+  const world = new World();
+  const cube = createPrimitiveMesh('cube').unwrap();
+  const cubeHandle = world.internSharedRef('MeshAsset', cube);
+  registerPropagateTransforms(world);
+  world.spawn(
+    { component: Transform, data: identityTransform({ pos: [0, 0, 5] }) },
+    { component: Camera, data: { fov: 60, near: 0.1, far: 1000, tonemap: 4 } },
+  );
+  world.spawn(
+    { component: Transform, data: identityTransform() },
+    {
+      component: DirectionalLight,
+      data: { direction: [0.5, -1, -0.5], castShadow: true, intensity: 1 },
+    },
+  );
+  world.spawn(
+    { component: Transform, data: identityTransform() },
+    { component: MeshFilter, data: { assetHandle: cubeHandle } },
+    { component: MeshRenderer, data: {} },
+  );
+  return world;
+}
+
+function makeSyncScheduler() {
+  let pending: ((t: number) => void) | null = null;
+  let clock = 0;
+  const raf = (cb: (t: number) => void): number => {
+    pending = cb;
+    return 1;
+  };
+  const caf = (): void => {
+    pending = null;
+  };
+  const now = (): number => {
+    clock += 16;
+    return clock;
+  };
+  const pump = (frames: number): void => {
+    for (let i = 0; i < frames; i++) {
+      const cb = pending;
+      pending = null;
+      if (cb === null) break;
+      cb(clock);
+    }
+  };
+  return { raf, caf, now, pump };
+}
+
+type DrawSourceCallback = () =>
+  | { worlds: readonly World[]; cameraOwner: number; resourceOwner: number }
+  | undefined;
+
+type FrameLoopOptionsWithDrawSource = FrameLoopOptions & {
+  drawSource?: DrawSourceCallback;
+};
+
+const createFrameLoopWithDrawSource = createFrameLoop as unknown as (
+  opts: FrameLoopOptionsWithDrawSource,
+) => ReturnType<typeof createFrameLoop>;
+
+// The RhiNull instance is a structural stand-in for a real RhiInstance in this
+// headless test; cast the options bag to RendererOptions so the direct
+// createRenderer import (strict RendererOptions) accepts the injected backend.
+const rhiOptions = {
+  rhi: rhi as unknown as import('@forgeax/engine-render').RendererOptions['rhi'],
+} as import('@forgeax/engine-render').RendererOptions;
+
+let renderer: Renderer | null = null;
+
+beforeEach(() => {
+  vi.stubGlobal('navigator', { gpu: undefined });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  if (renderer) {
+    try {
+      renderer.dispose();
+    } catch {
+      // ignore
+    }
+    renderer = null;
+  }
+});
+
+describe('drawSource full chain on rhi-null headless (w10)', () => {
+  it('drives update -> extract -> record for an injected world with no GPU', async () => {
+    const canvas = makeStubCanvas();
+    renderer = await createRenderer(canvas, rhiOptions, {
+      shaderManifestUrl: buildManifestDataUrl(),
+    });
+    await renderer.ready;
+
+    const rhiNullDevice = renderer.device as unknown as RhiNullDevice;
+
+    // The frame-loop's own world is EMPTY — it has no camera / mesh, so it
+    // records zero draws on its own. Only the injected world is renderable.
+    const loopWorld = new World();
+    const injectedWorld = makeInjectedWorld();
+
+    const drawSource: DrawSourceCallback = () => ({
+      worlds: [injectedWorld],
+      cameraOwner: 0,
+      resourceOwner: 0,
+    });
+
+    const { raf, caf, now, pump } = makeSyncScheduler();
+    const loop = createFrameLoopWithDrawSource({
+      world: loopWorld,
+      renderer: renderer as Renderer,
+      now,
+      raf,
+      caf,
+      drawSource,
+    });
+
+    // Reset per-frame counters immediately before the observed frame.
+    rhiNullDevice.totalDrawCount = 0;
+    rhiNullDevice.totalBindGroupCount = 0;
+    rhiNullDevice.framePassNames = [];
+
+    expect(loop.start().ok).toBe(true);
+    pump(1);
+    loop.stop();
+
+    // The full URP record path fired for the INJECTED world: a non-zero draw
+    // count is only reachable if drawSource was consumed AND the injected world
+    // was updated (camera + resolved Transform.world present for extract).
+    expect(rhiNullDevice.totalDrawCount).toBeGreaterThanOrEqual(1);
+    expect(rhiNullDevice.totalBindGroupCount).toBeGreaterThanOrEqual(1);
+    expect(renderer.perFramePassNames.length).toBeGreaterThan(0);
+    expect(renderer.perFramePassNames).toContain('main');
+  });
+});

package/src/__tests__/draw-source-injected-world-update-visibility.test.ts

@@ -0,0 +1,182 @@
+// feat-20260709-editor-world-partition-editorworld-super-composite / M2 / w9
+// (RED — impl lands in w12). Contract test: a world injected through drawSource
+// MUST be world.update(1 / 60).unwrap()'d by the frame-loop in the SAME frame it is drawn, so
+// the renderer reads a freshly-propagated Transform.world mat4 — never a stale
+// one.
+//
+// Why this matters (Strategist D-3, not covered by research): the renderer's
+// extract stage reads the DERIVED `Transform.world` column, whose sole writer is
+// the propagateTransforms system (plugin-factories.ts / systems/propagate-
+// transforms.ts). That writer only runs inside `world.update(1 / 60).unwrap()`. If drawSource
+// merely fed injected worlds into `renderer.draw(worlds, ...)` WITHOUT the
+// frame-loop running `world.update(1 / 60).unwrap()` on them first, the renderer would read the
+// injected world's Transform.world at its previous (or default identity) value —
+// a stale-matrix bug that renders the injected world one frame behind (or at the
+// origin on the first frame).
+//
+// This test spawns an entity in the injected world with a DISTINGUISHING
+// non-identity translation and never calls world.update(1 / 60).unwrap() on that world itself.
+// The spy renderer reads `Transform.world` at draw time. A frame-loop that
+// updates injected worlds surfaces the translation in the mat4's column-major
+// [12]/[13]/[14] slots; a draw-only frame-loop surfaces the identity default
+// (0/0/0), which fails the assertion. So the test has genuine discriminating
+// power over the stale-matrix regression.
+//
+// Driven through createFrameLoop directly with injected now / raf / caf seams,
+// mirroring frame-loop-world-array.test.ts. The drawSource option is reached
+// through a typed alias before w12 widens the real FrameLoopOptions type.
+//
+// Anchors:
+//   plan-strategy §2 D-3 (frame-loop MUST update injected worlds — transform
+//     propagation — before draw; not draw-only)
+//   research F1 (frame-loop is the world.update -> renderer.draw driver)
+//   AGENTS.md invariant 6 (Transform.world is the round-trip fidelity seam)
+
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { createFrameLoop, type FrameLoopOptions } from '../internal/frame-loop';
+
+// Distinguishing translation for the injected world's entity. Column-major mat4
+// carries translation at indices [12] (x), [13] (y), [14] (z).
+const INJECTED_TX = 5;
+const INJECTED_TY = -3;
+const INJECTED_TZ = 7;
+
+function makeSyncScheduler() {
+  let pending: ((t: number) => void) | null = null;
+  let clock = 0;
+  const raf = (cb: (t: number) => void): number => {
+    pending = cb;
+    return 1;
+  };
+  const caf = (): void => {
+    pending = null;
+  };
+  const now = (): number => {
+    clock += 16;
+    return clock;
+  };
+  const pump = (frames: number): void => {
+    for (let i = 0; i < frames; i++) {
+      const cb = pending;
+      pending = null;
+      if (cb === null) break;
+      cb(clock);
+    }
+  };
+  return { raf, caf, now, pump };
+}
+
+type DrawSourceCallback = () =>
+  | { worlds: readonly World[]; cameraOwner: number; resourceOwner: number }
+  | undefined;
+
+type FrameLoopOptionsWithDrawSource = FrameLoopOptions & {
+  drawSource?: DrawSourceCallback;
+};
+
+const createFrameLoopWithDrawSource = createFrameLoop as unknown as (
+  opts: FrameLoopOptionsWithDrawSource,
+) => ReturnType<typeof createFrameLoop>;
+
+describe('drawSource injected worlds are updated same-frame (w9, stale-matrix regression)', () => {
+  it('renderer reads a freshly-propagated Transform.world for the injected world at draw time', () => {
+    // The loop's OWN world — the single-world identity path. Never carries the
+    // injected entity, so it cannot mask a stale read on the injected world.
+    const loopWorld = new World();
+
+    // The injected world: register propagateTransforms (the sole Transform.world
+    // writer) and spawn an entity with a distinguishing non-identity translation.
+    // We deliberately do NOT call injectedWorld.update() here — the frame-loop
+    // must run it for the translation to reach Transform.world.
+    const injectedWorld = new World();
+    registerPropagateTransforms(injectedWorld);
+    const spawned = injectedWorld
+      .spawn({
+        component: Transform,
+        data: {
+          pos: [INJECTED_TX, INJECTED_TY, INJECTED_TZ],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      })
+      .unwrap();
+    const entity = spawned as unknown as EntityHandle;
+
+    // Sanity: BEFORE any frame, Transform.world is still the identity default
+    // (translation columns are 0). This proves the assertion below measures the
+    // frame-loop's update, not a pre-propagated value.
+    const before = injectedWorld.get(entity, Transform);
+    expect(before.ok).toBe(true);
+    if (before.ok) {
+      const w = before.value.world as unknown as ArrayLike<number>;
+      expect(w[12]).toBe(0);
+      expect(w[13]).toBe(0);
+      expect(w[14]).toBe(0);
+    }
+
+    // Spy renderer: at draw time, read the injected world's Transform.world and
+    // record the translation columns. This is the exact read the real extract
+    // stage performs (Transform.world is the extract SSOT).
+    const observed: Array<[number, number, number]> = [];
+    const renderer = {
+      backend: 'webgpu' as const,
+      ready: Promise.resolve({ ok: true, value: undefined }),
+      attachWorld: () => ({ ok: true, value: undefined }),
+      detachWorld: () => {},
+      draw(worlds: readonly World[]): { ok: true; value: undefined } {
+        // worlds is what drawSource returned; find the injected world in it.
+        const iw = worlds.find((w) => w === injectedWorld);
+        if (iw !== undefined) {
+          const r = iw.get(entity, Transform);
+          if (r.ok) {
+            const m = r.value.world as unknown as ArrayLike<number>;
+            observed.push([m[12] as number, m[13] as number, m[14] as number]);
+          }
+        }
+        return { ok: true, value: undefined };
+      },
+      onError(): () => void {
+        return () => {
+          // no-op
+        };
+      },
+      dispose(): void {
+        // no-op
+      },
+    } as unknown as Renderer;
+
+    const drawSource: DrawSourceCallback = () => ({
+      worlds: [injectedWorld],
+      cameraOwner: 0,
+      resourceOwner: 0,
+    });
+
+    const { raf, caf, now, pump } = makeSyncScheduler();
+    const loop = createFrameLoopWithDrawSource({
+      world: loopWorld,
+      renderer,
+      now,
+      raf,
+      caf,
+      drawSource,
+    });
+
+    expect(loop.start().ok).toBe(true);
+    pump(2);
+    loop.stop();
+
+    // At least one frame observed the injected world, and every observation saw
+    // the FRESH translation — the frame-loop ran injectedWorld.update() before
+    // draw. A draw-only frame-loop would observe [0, 0, 0] (identity) and fail.
+    expect(observed.length).toBeGreaterThanOrEqual(1);
+    for (const [x, y, z] of observed) {
+      expect(x).toBeCloseTo(INJECTED_TX);
+      expect(y).toBeCloseTo(INJECTED_TY);
+      expect(z).toBeCloseTo(INJECTED_TZ);
+    }
+  });
+});

package/src/__tests__/draw-source-single-world-regression.test.ts

@@ -0,0 +1,185 @@
+// feat-20260709-editor-world-partition-editorworld-super-composite / M2 / w8
+// (RED — impl lands in w12). Contract test: the drawSource injection seam MUST
+// degrade to the existing single-world path byte-identically when the host does
+// not opt in.
+//
+// Two non-opt-in shapes must both reproduce the legacy call
+// `renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })` (feat-20260708 M3 / AC-03 wrapping):
+//
+//   1. `drawSource` absent entirely — the createApp/frame-loop caller passes no
+//      drawSource (the single-world AI-user default).
+//   2. `drawSource` present but returning `undefined` on the frame — a host
+//      that wired the seam but, this frame, has nothing multi-world to inject
+//      (e.g. editor with no partitioned viewport active).
+//
+// Both cases MUST call `renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })` with the loop's
+// own single world and owner 0. This pins the AC-03 regression guarantee across
+// the new seam: adding drawSource never perturbs the single-world path.
+//
+// This test drives createFrameLoop directly (injected now / raf / caf seams)
+// with a spy renderer, mirroring frame-loop-world-array.test.ts. The drawSource
+// option is reached through a typed alias so the intent reads clearly before w12
+// widens the real FrameLoopOptions type (test-first RED window).
+//
+// Anchors:
+//   plan-strategy §2 D-3 (drawSource pull callback; absent / undefined -> single
+//     world path byte-identical to draw([world], { cameraOwner: 0, resourceOwner: 0 }))
+//   research F1 (frame-loop hardcodes renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }) — the
+//     seam insertion point)
+
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+import { createFrameLoop, type FrameLoopOptions } from '../internal/frame-loop';
+
+interface DrawCall {
+  readonly worlds: unknown;
+  readonly options: unknown;
+}
+
+function makeSpyRenderer(): { renderer: Renderer; calls: DrawCall[] } {
+  const calls: DrawCall[] = [];
+  const renderer = {
+    backend: 'webgpu' as const,
+    ready: Promise.resolve({ ok: true, value: undefined }),
+    attachWorld: () => ({ ok: true, value: undefined }),
+    detachWorld: () => {},
+    draw(worlds: unknown, options: unknown): { ok: true; value: undefined } {
+      calls.push({ worlds, options });
+      return { ok: true, value: undefined };
+    },
+    onError(): () => void {
+      return () => {
+        // no-op unsubscribe
+      };
+    },
+    dispose(): void {
+      // no-op
+    },
+  } as unknown as Renderer;
+  return { renderer, calls };
+}
+
+/**
+ * Synchronous rAF driver: fire the scheduled tick exactly `frames` times.
+ * Mirrors frame-loop-world-array.test.ts so both single-world contract tests
+ * step the loop identically.
+ */
+function makeSyncScheduler() {
+  let pending: ((t: number) => void) | null = null;
+  let clock = 0;
+  const raf = (cb: (t: number) => void): number => {
+    pending = cb;
+    return 1;
+  };
+  const caf = (): void => {
+    pending = null;
+  };
+  const now = (): number => {
+    clock += 16;
+    return clock;
+  };
+  const pump = (frames: number): void => {
+    for (let i = 0; i < frames; i++) {
+      const cb = pending;
+      pending = null;
+      if (cb === null) break;
+      cb(clock);
+    }
+  };
+  return { raf, caf, now, pump };
+}
+
+// The drawSource pull callback shape w11/w12 will introduce on FrameLoopOptions.
+// Declared locally so this test states the contract independent of the (not-yet
+// widened) source type. `undefined` return = "no multi-world injection this
+// frame" (degrade to single world).
+type DrawSourceCallback = () =>
+  | { worlds: readonly World[]; cameraOwner: number; resourceOwner: number }
+  | undefined;
+
+type FrameLoopOptionsWithDrawSource = FrameLoopOptions & {
+  drawSource?: DrawSourceCallback;
+};
+
+const createFrameLoopWithDrawSource = createFrameLoop as unknown as (
+  opts: FrameLoopOptionsWithDrawSource,
+) => ReturnType<typeof createFrameLoop>;
+
+describe('drawSource seam degrades to single-world path (w8, AC-03 regression)', () => {
+  it('no drawSource: draws the primary World with explicit camera and resource owners', () => {
+    const world = new World();
+    const { renderer, calls } = makeSpyRenderer();
+    const { raf, caf, now, pump } = makeSyncScheduler();
+
+    // No drawSource field at all — the single-world AI-user default.
+    const loop = createFrameLoop({ world, renderer, now, raf, caf });
+    expect(loop.start().ok).toBe(true);
+    pump(3);
+
+    expect(calls.length).toBeGreaterThanOrEqual(3);
+    for (const call of calls) {
+      expect(Array.isArray(call.worlds)).toBe(true);
+      const arr = call.worlds as unknown[];
+      expect(arr.length).toBe(1);
+      expect(arr[0]).toBe(world);
+      expect(call.options).toEqual({ cameraOwner: 0, resourceOwner: 0 });
+    }
+
+    loop.stop();
+  });
+
+  it('drawSource returns undefined: still draws [world] with { cameraOwner: 0, resourceOwner: 0 } (no-inject frame)', () => {
+    const world = new World();
+    const { renderer, calls } = makeSpyRenderer();
+    const { raf, caf, now, pump } = makeSyncScheduler();
+
+    let pulls = 0;
+    const drawSource: DrawSourceCallback = () => {
+      pulls++;
+      // Host wired the seam but has nothing multi-world to inject this frame.
+      return undefined;
+    };
+
+    const loop = createFrameLoopWithDrawSource({ world, renderer, now, raf, caf, drawSource });
+    expect(loop.start().ok).toBe(true);
+    pump(3);
+
+    // The seam was consulted (pull callback fired) but the resulting draw is
+    // identical to the primary-World call.
+    expect(pulls).toBeGreaterThanOrEqual(3);
+    expect(calls.length).toBeGreaterThanOrEqual(3);
+    for (const call of calls) {
+      expect(Array.isArray(call.worlds)).toBe(true);
+      const arr = call.worlds as unknown[];
+      expect(arr.length).toBe(1);
+      expect(arr[0]).toBe(world);
+      expect(call.options).toEqual({ cameraOwner: 0, resourceOwner: 0 });
+    }
+
+    loop.stop();
+  });
+
+  it('setDrawSource switches routing without creating a second frame loop', () => {
+    const world = new World();
+    const overlay = new World();
+    const { renderer, calls } = makeSpyRenderer();
+    const { raf, caf, now, pump } = makeSyncScheduler();
+    const loop = createFrameLoop({ world, renderer, now, raf, caf });
+
+    expect(loop.start().ok).toBe(true);
+    pump(1);
+    loop.setDrawSource(() => ({ worlds: [world, overlay], cameraOwner: 0, resourceOwner: 0 }));
+    pump(1);
+    loop.setDrawSource(undefined);
+    pump(1);
+
+    expect(calls).toHaveLength(3);
+    expect(calls[0]?.options).toEqual({ cameraOwner: 0, resourceOwner: 0 });
+    expect(calls[1]?.worlds).toEqual([world, overlay]);
+    expect(calls[1]?.options).toEqual({ cameraOwner: 0, resourceOwner: 0 });
+    expect(calls[2]?.worlds).toEqual([world]);
+    expect(calls[2]?.options).toEqual({ cameraOwner: 0, resourceOwner: 0 });
+    loop.stop();
+  });
+});

package/src/__tests__/ecs-import.unit.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createEcsImportModule,
+  ECS_PUBLIC_SYMBOLS,
+  projectEcsPublicModule,
+} from '../internal/ecs-import';
+
+describe('host-owned ECS import projection', () => {
+  it('keeps the explicit six-symbol surface and drops implementation exports', () => {
+    expect(ECS_PUBLIC_SYMBOLS).toEqual([
+      'World',
+      'Entity',
+      'Update',
+      'FixedUpdate',
+      'Time',
+      'FixedTime',
+    ]);
+    expect(
+      projectEcsPublicModule({
+        World: 'World',
+        Entity: 'Entity',
+        defineComponent: 'implementation-only',
+      }),
+    ).toEqual({ World: 'World', Entity: 'Entity' });
+  });
+
+  it('projects only the ECS specifier and preserves other host modules', async () => {
+    const calls: string[] = [];
+    const importModule = createEcsImportModule(async (specifier) => {
+      calls.push(specifier);
+      return specifier === '@forgeax/engine-ecs'
+        ? { World: 'World', defineComponent: 'implementation-only' }
+        : { value: 'other-module' };
+    });
+
+    await expect(importModule('@forgeax/engine-ecs')).resolves.toEqual({ World: 'World' });
+    await expect(importModule('virtual:host-module')).resolves.toEqual({ value: 'other-module' });
+    expect(calls).toEqual(['@forgeax/engine-ecs', 'virtual:host-module']);
+  });
+});