fix(core): break ecs/world ↔ in it/world-initializer import cycle

Summary:
After D105972540 introduced a narrow `sideEffects` allowlist in `iwsdk/core`'s `package.json`, the bundler stopped eliding side-effect-only imports and started honoring the full module graph during code emission. That exposed a latent value-level import cycle:

  ecs/world.ts → init/index.js (barrel) → init/world-initializer.ts → ecs/index.js → ecs/world.ts

Because `createSystem({queries: {required: [X]}})` captures the component reference `X` at class-body evaluation time, this cycle let bundlers (Vite/esbuild prebundle and the production Rollup bundle) emit `AudioSystem`'s class body before `AudioSource` was defined. The query then held `[undefined]`, and the failure surfaced later at `QueryManager.registerQuery` with `Cannot read properties of undefined (reading 'bitmask')`.

Three changes break the cycle and prevent regressions:

1. `ecs/world.ts` no longer imports `initializeWorld` statically — it `await import()`s `init/world-initializer.js` from inside `World.create()`. `WorldOptions` is now a `type` import (erased at build time). `launchXR` and `XROptions` come directly from `init/xr.js`, bypassing the `init/index.js` barrel.

2. `audio/audio-system.ts` and `audio/audio.ts` import `Types`, `Entity`, `createSystem`, and `createComponent` directly from `ecs/{component,entity,system}.js` rather than the `ecs/index.js` barrel. Defense-in-depth: even if a future change reintroduces a `world.ts`-side cycle, these modules will no longer participate in it.

3. New `tests/ecs/no-import-cycles.test.ts` asserts that `AudioSystem.queries.audioEntities.required[0]` is `AudioSource` (not `undefined`) at import time. This is a fast TDZ regression guard — if a future bundler change reintroduces the load-order bug, this test fails before any consumer crashes.

Reviewed By: cabanier

Differential Revision: D106196204

fbshipit-source-id: 1e6b227213d5393161f9f4ce9d962353edcefbbd

Author: felixtrz

packages/core/src/asset/asset-manager.ts

@@ -6,7 +6,7 @@
  */
 
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import type { World } from '../ecs/index.js';
+import type { World } from '../ecs/world.js';
 import { LoadingManager, Texture, WebGLRenderer } from '../runtime/index.js';
 import { CacheManager } from './cache-manager.js';
 import { AudioAssetLoader } from './loaders/audio-loader.js';

packages/core/src/audio/audio-system.ts

@@ -7,7 +7,14 @@
 
 import { PositionalAudio, AudioListener, Audio as AmbientAudio } from 'three';
 import { AssetManager } from '../asset/index.js';
-import { Types, Entity, createSystem } from '../ecs/index.js';
+// Import directly from submodules — not the `../ecs/index.js` barrel — to
+// avoid a value-level import cycle: ecs/index.js re-exports ecs/world.js,
+// which (via its transitive deps) loops back to audio/audio-system.js while
+// it is still being evaluated. That would leave the AudioSource reference
+// captured in `audioEntities.required` as `undefined` at class-body eval time.
+import { Types } from '../ecs/component.js';
+import { Entity } from '../ecs/entity.js';
+import { createSystem } from '../ecs/system.js';
 import { AudioInstance, AudioPool } from './audio-pool.js';
 import { AudioSource, InstanceStealPolicy, PlaybackMode } from './audio.js';
 

packages/core/src/audio/audio-utils.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { Entity } from '../ecs/index.js';
-import type { World } from '../ecs/index.js';
+import { Entity } from '../ecs/entity.js';
+import type { World } from '../ecs/world.js';
 import { AudioSource as AudioComponent } from './audio.js';
 
 /** Utility helpers to control {@link AudioSource} without touching Three audio.

packages/core/src/audio/audio.ts

@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { Types, createComponent } from '../ecs/index.js';
+// See audio-system.ts for rationale — import from the subfile, not the
+// `../ecs/index.js` barrel, to keep this module free of the world.js cycle.
+import { Types, createComponent } from '../ecs/component.js';
 
 /**
  * Playback behavior when a new play is requested.

packages/core/src/camera/camera-source.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { Types, createComponent } from '../ecs/index.js';
+import { Types, createComponent } from '../ecs/component.js';
 import { CameraFacing, CameraState } from './types.js';
 
 /**

packages/core/src/camera/camera-system.ts

@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { createSystem, Entity, VisibilityState } from '../ecs/index.js';
+import { createSystem } from '../ecs/system.js';
+import { Entity } from '../ecs/entity.js';
+import { VisibilityState } from '../ecs/world.js';
 import { LinearFilter, VideoTexture } from '../runtime/three.js';
 import { CameraSource } from './camera-source.js';
 import { CameraUtils } from './camera-utils.js';

packages/core/src/camera/camera-utils.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { Entity } from '../ecs/index.js';
+import { Entity } from '../ecs/entity.js';
 import { CameraSource } from './camera-source.js';
 import {
   CameraFacing,

packages/core/src/depth/depth-occludable.ts

@@ -5,8 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { Types, createComponent } from '../ecs/index.js';
-
+import { Types, createComponent } from '../ecs/component.js';
 /** Occlusion shader mode for {@link DepthOccludable}. @category Depth Sensing */
 export const OcclusionShadersMode = {
   /** Soft occlusion with 13-tap blur sampling for smooth edges. */

packages/core/src/depth/depth-sensing-system.ts

@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { createSystem, Entity, Types } from '../ecs/index.js';
+import { createSystem } from '../ecs/system.js';
+import { Entity } from '../ecs/entity.js';
+import { Types } from '../ecs/component.js';
 import { type IUniform, Mesh, Texture, Vector2 } from '../runtime/three.js';
 import { DepthOccludable, OcclusionShadersMode } from './depth-occludable.js';
 import { DepthTextures } from './depth-textures.js';

packages/core/src/ecs/world.ts

@@ -11,14 +11,22 @@ import { Signal, signal } from '@preact/signals-core';
 import { AnyComponent, World as ElicsWorld } from 'elics';
 import { AssetManager } from '../asset/index.js';
 // Environment is driven by components/systems; no world helpers
-import {
-  WorldOptions,
-  initializeWorld,
-  XROptions,
-  launchXR,
-} from '../init/index.js';
+// NOTE: import `launchXR` and types directly from submodules — not the
+// `../init/index.js` barrel — so loading this file does not pull in
+// `init/world-initializer.js`. That would create a value-level cycle with
+// audio-system.ts (and other systems that import the ecs barrel), causing
+// the bundler to emit System classes before their referenced Component
+// constants, producing `undefined.bitmask` crashes at QueryManager.registerQuery.
+// `initializeWorld` is loaded lazily inside `World.create` for the same reason.
+import type { WorldOptions } from '../init/world-initializer.js';
+import { launchXR } from '../init/xr.js';
+import type { XROptions } from '../init/xr.js';
 import type { InputManager } from '../input/index.js';
-import { LevelTag } from '../level/index.js';
+// Import LevelTag from its leaf module — not '../level/index.js' — so that
+// loading ecs/world.ts does not transitively pull in level-system.ts (which
+// would re-enter '../ecs/index.js' and form a cycle, leading to TDZ
+// undefined.bitmask crashes for any component captured in System.queries).
+import { LevelTag } from '../level/level-tag.js';
 import type { MCPRuntime } from '../mcp/index.js';
 import type { Object3DEventMap } from '../runtime/index.js';
 import {
@@ -28,7 +36,10 @@ import {
   Scene,
   WebGLRenderer,
 } from '../runtime/index.js';
-import { Transform } from '../transform/index.js';
+// See note above on LevelTag — import Transform directly from its leaf
+// module to avoid cycling back through '../ecs/index.js' via the transform
+// barrel.
+import { Transform } from '../transform/transform.js';
 import { Entity } from './entity.js';
 
 export enum VisibilityState {
@@ -264,10 +275,11 @@ export class World extends ElicsWorld {
    * - If {@link WorldOptions.level} is provided, the LevelSystem will load it after assets are preloaded.
    * @see /getting-started/01-hello-xr
    */
-  static create(
+  static async create(
     container: HTMLDivElement,
     options?: WorldOptions,
   ): Promise<World> {
+    const { initializeWorld } = await import('../init/world-initializer.js');
     return initializeWorld(container, options);
   }
 }