@vulfram/engine 0.19.2-alpha → 0.20.1-alpha

package/src/engine/world/entities.ts

@@ -1,1578 +1,8 @@
-import type { ShadowConfig } from '../../types/cmds/shadow';
-import type { EnvironmentConfig } from '../../types/cmds/environment';
-import type {
-  CmdEnvironmentDisposeArgs,
-} from '../../types/cmds/environment';
-import type {
-  CmdTargetMeasurementArgs,
-  CmdTargetDisposeArgs,
-  CmdTargetLayerDisposeArgs,
-  CmdTargetLayerUpsertArgs,
-  CmdTargetUpsertArgs,
-  TargetLayerLayout,
-} from '../../types/cmds/target';
-import type {
-  CmdAudioListenerCreateArgs,
-  CmdAudioListenerDisposeArgs,
-  CmdAudioListenerUpsertArgs,
-  CmdAudioListenerUpdateArgs,
-  CmdAudioResourceUpsertArgs,
-  CmdAudioResourceDisposeArgs,
-  CmdAudioSourceTransportArgs,
-  CmdAudioSourceCreateArgs,
-  CmdAudioSourceDisposeArgs,
-  CmdAudioSourceUpsertArgs,
-  CmdAudioSourceUpdateArgs,
-  CmdAudioStateGetArgs,
-} from '../../types/cmds/audio';
-import type { CmdPoseUpdateArgs } from '../../types/cmds/model';
-import type {
-  CmdSystemDiagnosticsSetArgs,
-  CmdUploadBufferDiscardAllArgs,
-} from '../../types/cmds/system';
-import type {
-  CmdInputTargetListenerDisposeArgs,
-  CmdInputTargetListenerListArgs,
-  CmdInputTargetListenerUpsertArgs,
-} from '../../types/cmds/input';
-import type { CmdTextureBindTargetArgs } from '../../types/cmds/texture';
-import type {
-  CmdUiAccessKitActionRequestArgs,
-  CmdUiApplyOpsArgs,
-  CmdUiClipboardPasteArgs,
-  CmdUiDebugSetArgs,
-  CmdUiDocumentCreateArgs,
-  CmdUiDocumentDisposeArgs,
-  CmdUiDocumentGetLayoutRectsArgs,
-  CmdUiDocumentGetTreeArgs,
-  CmdUiDocumentSetRectArgs,
-  CmdUiDocumentSetThemeArgs,
-  CmdUiEventTraceSetArgs,
-  CmdUiFocusGetArgs,
-  CmdUiFocusSetArgs,
-  CmdUiImageCreateFromBufferArgs,
-  CmdUiImageDisposeArgs,
-  CmdUiScreenshotReplyArgs,
-  CmdUiThemeDefineArgs,
-  CmdUiThemeDisposeArgs,
-} from '../../types/cmds/ui';
-import type { NotificationLevel } from '../../types/kinds';
-import { EngineError } from '../errors';
-import { getWorldOrThrow, requireInitialized } from '../bridge/guards';
-import {
-  enqueueCommand,
-  enqueueGlobalCommand,
-  markRoutingIndexDirty,
-} from '../bridge/dispatch';
-import type {
-  CameraComponent,
-  CameraProps,
-  GeometryProps,
-  InputStateComponent,
-  Intent,
-  LightProps,
-  MaterialProps,
-  ModelProps,
-  TagProps,
-  TextureProps,
-  TransformComponent,
-  TransformProps,
-  UiFocusCycleMode,
-  WindowStateComponent,
-} from '../ecs';
-import { engineState } from '../state';
-import type { GamepadEvent, SystemEvent, UiEvent } from '../../types/events';
-
-function allocateGlobalId(): number {
-  return engineState.nextGlobalId++;
-}
-
-function recalculateWorldWindowBindings(world: ReturnType<typeof getWorldOrThrow>): void {
-  world.boundWindowIds.clear();
-  for (const windowId of world.targetWindowBindings.values()) {
-    world.boundWindowIds.add(windowId);
-  }
-
-  if (world.boundWindowIds.size === 0) {
-    world.primaryWindowId = undefined;
-    return;
-  }
-
-  let primary = Number.POSITIVE_INFINITY;
-  for (const windowId of world.boundWindowIds) {
-    if (windowId < primary) {
-      primary = windowId;
-    }
-  }
-  world.primaryWindowId = primary;
-}
-
-/**
- * Emits an intent to the specified world.
- * Intents are processed by systems at the beginning of each tick.
- */
-export function emitIntent(worldId: number, intent: Intent): void {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  world.intentStore.enqueue(intent);
-}
-
-/**
- * Returns the core model ID for an entity, if available.
- */
-export function getModelId(worldId: number, entityId: number): number | null {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const store = world.components.get(entityId);
-  if (!store) return null;
-  const model = store.get('Model') as { id: number } | undefined;
-  return model?.id ?? null;
-}
-
-/**
- * Returns the core realm id associated with this world, if already created.
- */
-export function getWorldRealmId(worldId: number): number | null {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  return world.coreRealmId ?? null;
-}
-
-/**
- * Returns true when the world has a resolved core realm id.
- */
-export function isWorldReady(worldId: number): boolean {
-  return getWorldRealmId(worldId) !== null;
-}
-
-/**
- * Upserts a target used to present world output.
- */
-export function upsertTarget(worldId: number, args: CmdTargetUpsertArgs): number {
-  const id = enqueueCommand(worldId, 'cmd-target-upsert', args);
-  const world = getWorldOrThrow(worldId);
-  if (args.kind === 'window' && args.windowId !== undefined) {
-    world.targetWindowBindings.set(args.targetId, args.windowId);
-    recalculateWorldWindowBindings(world);
-    markRoutingIndexDirty();
-  } else {
-    if (world.targetWindowBindings.delete(args.targetId)) {
-      recalculateWorldWindowBindings(world);
-    }
-    markRoutingIndexDirty();
-  }
-  return id;
-}
-
-/**
- * Requests size measurements for a target.
- */
-export function measureTarget(
-  worldId: number,
-  args: CmdTargetMeasurementArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-target-measurement', args);
-}
-
-/**
- * Creates or updates an input listener bound to a routed target.
- */
-export function upsertInputTargetListener(
-  worldId: number,
-  args: CmdInputTargetListenerUpsertArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-input-target-listener-upsert', args);
-}
-
-/**
- * Disposes an input listener bound to routed targets.
- */
-export function disposeInputTargetListener(
-  worldId: number,
-  args: CmdInputTargetListenerDisposeArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-input-target-listener-dispose', args);
-}
-
-/**
- * Lists input listeners (optionally filtered by target id).
- */
-export function listInputTargetListeners(
-  worldId: number,
-  args: CmdInputTargetListenerListArgs = {},
-): number {
-  return enqueueCommand(worldId, 'cmd-input-target-listener-list', args);
-}
-
-/**
- * Disposes a target.
- */
-export function disposeTarget(worldId: number, args: CmdTargetDisposeArgs): number {
-  const world = getWorldOrThrow(worldId);
-  world.targetLayerBindings.delete(args.targetId);
-  if (world.targetWindowBindings.delete(args.targetId)) {
-    recalculateWorldWindowBindings(world);
-  }
-  markRoutingIndexDirty();
-  return enqueueCommand(worldId, 'cmd-target-dispose', args);
-}
-
-/**
- * Binds this world's realm to a target layer.
- */
-export function bindWorldToTarget(
-  worldId: number,
-  args: Omit<CmdTargetLayerUpsertArgs, 'realmId'>,
-): number {
-  const world = getWorldOrThrow(worldId);
-
-  const resolvedCameraId = args.cameraId ?? findPreferredCameraId(worldId);
-
-  world.targetLayerBindings.set(args.targetId, {
-    targetId: args.targetId,
-    layout: args.layout,
-    cameraId: resolvedCameraId,
-    environmentId: args.environmentId,
-  });
-  markRoutingIndexDirty();
-
-  const realmId = getWorldRealmId(worldId);
-  if (realmId === null) {
-    // Realm not ready yet: keep binding cached and let response-decode flush later.
-    return 0;
-  }
-
-  return enqueueCommand(worldId, 'cmd-target-layer-upsert', {
-    realmId,
-    ...args,
-    cameraId: resolvedCameraId,
-  });
-}
-
-/**
- * Unbinds this world's realm from a target layer.
- */
-export function unbindWorldFromTarget(
-  worldId: number,
-  args: Omit<CmdTargetLayerDisposeArgs, 'realmId'>,
-): number {
-  const world = getWorldOrThrow(worldId);
-  world.targetLayerBindings.delete(args.targetId);
-  if (world.targetWindowBindings.delete(args.targetId)) {
-    recalculateWorldWindowBindings(world);
-  }
-  markRoutingIndexDirty();
-
-  const realmId = getWorldRealmId(worldId);
-  if (realmId === null) {
-    // Realm not ready yet: nothing to dispose in core.
-    return 0;
-  }
-
-  return enqueueCommand(worldId, 'cmd-target-layer-dispose', {
-    realmId,
-    ...args,
-  });
-}
-
-function findPreferredCameraId(worldId: number): number | undefined {
-  const world = getWorldOrThrow(worldId);
-  let bestId: number | undefined;
-  let bestOrder = Number.POSITIVE_INFINITY;
-  for (const store of world.components.values()) {
-    const camera = store.get('Camera') as CameraComponent | undefined;
-    if (!camera) continue;
-    if (
-      camera.order < bestOrder ||
-      (camera.order === bestOrder &&
-        (bestId === undefined || camera.id < bestId))
-    ) {
-      bestOrder = camera.order;
-      bestId = camera.id;
-    }
-  }
-  return bestId;
-}
-
-/**
- * Convenience helper: presents this world in a window via target/layer bind.
- */
-export function presentWorldInWindow(
-  worldId: number,
-  args: {
-    windowId: number;
-    targetId?: number;
-    layout?: TargetLayerLayout;
-    cameraId?: number;
-    environmentId?: number;
-  },
-): { targetId: number; upsertCommandId: number; bindCommandId: number } {
-  requireInitialized();
-  const targetId = args.targetId ?? allocateGlobalId();
-  const upsertCommandId = upsertTarget(worldId, {
-    targetId,
-    kind: 'window',
-    windowId: args.windowId,
-  });
-  const bindCommandId = bindWorldToTarget(worldId, {
-    targetId,
-    layout: args.layout ?? {
-      left: { unit: 'percent', value: 0 },
-      top: { unit: 'percent', value: 0 },
-      width: { unit: 'percent', value: 100 },
-      height: { unit: 'percent', value: 100 },
-      zIndex: 0,
-      blendMode: 0,
-    },
-    cameraId: args.cameraId,
-    environmentId: args.environmentId,
-  });
-  return { targetId, upsertCommandId, bindCommandId };
-}
-
-/**
- * Disposes a world and optionally releases its bound realm/targets.
- * This operation is immediate on host state; core-side disposal commands are queued globally.
- */
-export function disposeWorld(
-  worldId: number,
-  opts: {
-    disposeRealm?: boolean;
-    disposeTargets?: boolean;
-    warnOnUndisposedResources?: boolean;
-    strictResourceLifecycle?: boolean;
-  } = {},
-): void {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const disposeRealm = opts.disposeRealm ?? true;
-  const disposeTargets = opts.disposeTargets ?? true;
-  const strictResourceLifecycle = opts.strictResourceLifecycle ?? false;
-  const warnOnUndisposedResources = opts.warnOnUndisposedResources ?? true;
-
-  let retainedCoreObjectCount = 0;
-  for (const store of world.components.values()) {
-    for (const comp of store.values()) {
-      if ('id' in comp && typeof comp.id === 'number') {
-        retainedCoreObjectCount++;
-      }
-    }
-  }
-  const hasRetainedTargets = world.targetLayerBindings.size > 0;
-  const hasPendingWork =
-    world.intentStore.size() > 0 || world.pendingCommands.length > 0;
-
-  if (
-    (!disposeRealm && (retainedCoreObjectCount > 0 || hasPendingWork)) ||
-    (!disposeTargets && hasRetainedTargets)
-  ) {
-    const message =
-      `disposeWorld(${worldId}) called without fully releasing resources. ` +
-      `retainRealm=${!disposeRealm} retainTargets=${!disposeTargets} ` +
-      `trackedCoreObjects=${retainedCoreObjectCount} ` +
-      `targetBindings=${world.targetLayerBindings.size} ` +
-      `pendingIntents=${world.intentStore.size()} ` +
-      `pendingCommands=${world.pendingCommands.length}`;
-    if (strictResourceLifecycle) {
-      throw new EngineError('WorldDisposeLifecycleRisk', message);
-    }
-    if (warnOnUndisposedResources) {
-      console.warn(`[World ${worldId}] ${message}`);
-    }
-  }
-
-  if (disposeTargets) {
-    for (const targetId of world.targetLayerBindings.keys()) {
-      let isShared = false;
-      for (const [otherWorldId, otherWorld] of engineState.worlds) {
-        if (otherWorldId === worldId) continue;
-        if (otherWorld.targetLayerBindings.has(targetId)) {
-          isShared = true;
-          break;
-        }
-      }
-      if (!isShared) {
-        enqueueGlobalCommand('cmd-target-dispose', { targetId });
-      }
-    }
-  }
-
-  if (disposeRealm && world.coreRealmId !== undefined) {
-    enqueueGlobalCommand('cmd-realm-dispose', { realmId: world.coreRealmId });
-  }
-
-  for (const [cmdId, trackedWorldId] of engineState.commandTracker) {
-    if (trackedWorldId === worldId) {
-      engineState.commandTracker.delete(cmdId);
-    }
-  }
-
-  engineState.worlds.delete(worldId);
-  markRoutingIndexDirty();
-}
-
-/**
- * Configures global runtime diagnostics and pointer tracing.
- */
-export function setSystemDiagnostics(
-  args: CmdSystemDiagnosticsSetArgs,
-): number {
-  requireInitialized();
-  return enqueueGlobalCommand('cmd-system-diagnostics-set', args);
-}
-
-/**
- * Requests the core to discard all pending upload buffers.
- */
-export function discardAllUploadBuffers(
-  args: CmdUploadBufferDiscardAllArgs = {},
-): number {
-  requireInitialized();
-  return enqueueGlobalCommand('cmd-upload-buffer-discard-all', args);
-}
-
-/**
- * Sends an audio listener update command.
- */
-export function audioListenerUpdate(
-  worldId: number,
-  args: CmdAudioListenerUpdateArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-listener-upsert', args);
-}
-
-/**
- * Binds a texture id to a texture target output.
- */
-export function bindTextureToTarget(
-  worldId: number,
-  args: CmdTextureBindTargetArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-texture-bind-target', args);
-}
-
-/**
- * Binds the audio listener to a model.
- */
-export function audioListenerCreate(
-  worldId: number,
-  args: CmdAudioListenerCreateArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-listener-upsert', args);
-}
-
-/**
- * Upserts audio listener params or binding.
- */
-export function audioListenerUpsert(
-  worldId: number,
-  args: CmdAudioListenerUpsertArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-listener-upsert', args);
-}
-
-/**
- * Disposes the audio listener binding.
- */
-export function audioListenerDispose(
-  worldId: number,
-  args: CmdAudioListenerDisposeArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-listener-dispose', args);
-}
-
-/**
- * Creates an audio resource from an uploaded buffer.
- */
-export function audioResourceCreate(
-  worldId: number,
-  args: CmdAudioResourceUpsertArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-resource-upsert', args);
-}
-
-/**
- * Pushes a chunk into a streaming audio resource.
- */
-export function audioResourcePush(
-  worldId: number,
-  args: CmdAudioResourceUpsertArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-resource-upsert', args);
-}
-
-/**
- * Disposes an audio resource.
- */
-export function audioResourceDispose(
-  worldId: number,
-  args: CmdAudioResourceDisposeArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-resource-dispose', args);
-}
-
-/**
- * Creates an audio source bound to a model.
- */
-export function audioSourceCreate(
-  worldId: number,
-  args: CmdAudioSourceCreateArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-upsert', args);
-}
-
-/**
- * Updates an audio source.
- */
-export function audioSourceUpdate(
-  worldId: number,
-  args: CmdAudioSourceUpdateArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-upsert', args);
-}
-
-/**
- * Upserts audio source params or binding.
- */
-export function audioSourceUpsert(
-  worldId: number,
-  args: CmdAudioSourceUpsertArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-upsert', args);
-}
-
-/**
- * Starts playback for an audio source.
- */
-export function audioSourcePlay(
-  worldId: number,
-  args: Omit<CmdAudioSourceTransportArgs, 'action'>,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-transport', {
-    ...args,
-    action: 'play',
-  });
-}
-
-/**
- * Pauses playback for an audio source.
- */
-export function audioSourcePause(
-  worldId: number,
-  args: Omit<CmdAudioSourceTransportArgs, 'action'>,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-transport', {
-    ...args,
-    action: 'pause',
-  });
-}
-
-/**
- * Stops playback for an audio source.
- */
-export function audioSourceStop(
-  worldId: number,
-  args: Omit<CmdAudioSourceTransportArgs, 'action'>,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-transport', {
-    ...args,
-    action: 'stop',
-  });
-}
-
-/**
- * Requests a snapshot of audio runtime state.
- */
-export function audioStateGet(
-  worldId: number,
-  args: CmdAudioStateGetArgs = {},
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-state-get', args);
-}
-
-/**
- * Disposes an audio source.
- */
-export function audioSourceDispose(
-  worldId: number,
-  args: CmdAudioSourceDisposeArgs,
-): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-dispose', args);
-}
-
-/**
- * Updates a model pose (skinning) using an uploaded matrices buffer.
- */
-export function poseUpdate(worldId: number, args: CmdPoseUpdateArgs): number {
-  return enqueueCommand(worldId, 'cmd-pose-update', args);
-}
-
-/**
- * Requests a list of resources from the engine for debugging.
- */
-export function requestResourceList(
-  worldId: number,
-  resourceType:
-    | 'model'
-    | 'material'
-    | 'texture'
-    | 'geometry'
-    | 'light'
-    | 'camera',
-): void {
-  emitIntent(worldId, {
-    type: 'request-resource-list',
-    resourceType,
-  });
-}
-
-function resolveWorldWindowId(worldId: number): number {
-  const world = getWorldOrThrow(worldId);
-  if (world.primaryWindowId === undefined) {
-    for (const windowId of world.targetWindowBindings.values()) {
-      return windowId;
-    }
-    throw new EngineError(
-      'WindowNotFound',
-      `World ${worldId} has no window binding available for this command.`,
-    );
-  }
-  return world.primaryWindowId;
-}
-
-/** Requests model list for a world window context. */
-export function listModels(worldId: number): number {
-  return enqueueCommand(worldId, 'cmd-model-list', {
-    windowId: resolveWorldWindowId(worldId),
-  });
-}
-
-/** Requests material list for a world window context. */
-export function listMaterials(worldId: number): number {
-  return enqueueCommand(worldId, 'cmd-material-list', {
-    windowId: resolveWorldWindowId(worldId),
-  });
-}
-
-/** Requests texture list for a world window context. */
-export function listTextures(worldId: number): number {
-  return enqueueCommand(worldId, 'cmd-texture-list', {
-    windowId: resolveWorldWindowId(worldId),
-  });
-}
-
-/** Requests geometry list for a world window context. */
-export function listGeometries(worldId: number): number {
-  return enqueueCommand(worldId, 'cmd-geometry-list', {
-    windowId: resolveWorldWindowId(worldId),
-  });
-}
-
-/** Requests light list for a world window context. */
-export function listLights(worldId: number): number {
-  return enqueueCommand(worldId, 'cmd-light-list', {
-    windowId: resolveWorldWindowId(worldId),
-  });
-}
-
-/** Requests camera list for a world window context. */
-export function listCameras(worldId: number): number {
-  return enqueueCommand(worldId, 'cmd-camera-list', {
-    windowId: resolveWorldWindowId(worldId),
-  });
-}
-
-/**
- * Disposes a material.
- */
-export function disposeMaterial(worldId: number, resourceId: number): void {
-  emitIntent(worldId, { type: 'dispose-material', resourceId });
-}
-
-/**
- * Disposes a texture.
- */
-export function disposeTexture(worldId: number, resourceId: number): void {
-  emitIntent(worldId, { type: 'dispose-texture', resourceId });
-}
-
-/**
- * Disposes a geometry.
- */
-export function disposeGeometry(worldId: number, resourceId: number): void {
-  emitIntent(worldId, { type: 'dispose-geometry', resourceId });
-}
-
-/**
- * Sends a system notification.
- */
-export function sendNotification(
-  worldId: number,
-  props: {
-    level: NotificationLevel;
-    title: string;
-    message: string;
-  },
-): void {
-  emitIntent(worldId, {
-    type: 'send-notification',
-    level: props.level,
-    title: props.title,
-    message: props.message,
-  });
-}
-
-/**
- * Configures shadow settings for the world.
- */
-export function configureShadows(worldId: number, config: ShadowConfig): void {
-  emitIntent(worldId, {
-    type: 'configure-shadows',
-    config,
-  });
-}
-
-/**
- * Configures environment settings for the world.
- */
-export function configureEnvironment(
-  worldId: number,
-  config: EnvironmentConfig,
-): void {
-  emitIntent(worldId, {
-    type: 'configure-environment',
-    config,
-  });
-}
-
-/**
- * Disposes an environment profile.
- * If omitted, defaults to this world id (engine convention).
- */
-export function disposeEnvironment(
-  worldId: number,
-  args: CmdEnvironmentDisposeArgs = { environmentId: worldId },
-): number {
-  return enqueueCommand(worldId, 'cmd-environment-dispose', args);
-}
-
-/**
- * Defines or updates a UI theme.
- */
-export function uiDefineTheme(worldId: number, args: CmdUiThemeDefineArgs): void {
-  emitIntent(worldId, { type: 'ui-theme-define', args });
-}
-
-/**
- * Disposes a UI theme.
- */
-export function uiDisposeTheme(worldId: number, args: CmdUiThemeDisposeArgs): void {
-  emitIntent(worldId, { type: 'ui-theme-dispose', args });
-}
-
-/**
- * Creates a UI document.
- */
-export function uiCreateDocument(worldId: number, args: CmdUiDocumentCreateArgs): void {
-  emitIntent(worldId, { type: 'ui-document-create', args });
-}
-
-/**
- * Disposes a UI document.
- */
-export function uiDisposeDocument(worldId: number, args: CmdUiDocumentDisposeArgs): void {
-  emitIntent(worldId, { type: 'ui-document-dispose', args });
-}
-
-/**
- * Updates document rectangle.
- */
-export function uiSetDocumentRect(worldId: number, args: CmdUiDocumentSetRectArgs): void {
-  emitIntent(worldId, { type: 'ui-document-set-rect', args });
-}
-
-/**
- * Updates document theme.
- */
-export function uiSetDocumentTheme(worldId: number, args: CmdUiDocumentSetThemeArgs): void {
-  emitIntent(worldId, { type: 'ui-document-set-theme', args });
-}
-
-/**
- * Applies document ops.
- */
-export function uiApplyOps(worldId: number, args: CmdUiApplyOpsArgs): void {
-  emitIntent(worldId, { type: 'ui-apply-ops', args });
-}
-
-/**
- * Requests UI document tree for introspection.
- */
-export function uiGetDocumentTree(worldId: number, args: CmdUiDocumentGetTreeArgs): void {
-  emitIntent(worldId, { type: 'ui-document-get-tree', args });
-}
-
-/**
- * Requests UI layout rects for introspection.
- */
-export function uiGetLayoutRects(
-  worldId: number,
-  args: CmdUiDocumentGetLayoutRectsArgs,
-): void {
-  emitIntent(worldId, { type: 'ui-document-get-layout-rects', args });
-}
-
-/**
- * Enables/disables runtime UI debug overlays.
- */
-export function uiSetDebug(worldId: number, args: CmdUiDebugSetArgs): void {
-  emitIntent(worldId, { type: 'ui-debug-set', args });
-}
-
-/**
- * Sets focused UI node.
- */
-export function uiSetFocus(worldId: number, args: CmdUiFocusSetArgs): void {
-  emitIntent(worldId, { type: 'ui-focus-set', args });
-}
-
-/**
- * Requests current UI focus state.
- */
-export function uiGetFocus(worldId: number, args: CmdUiFocusGetArgs = {}): void {
-  emitIntent(worldId, { type: 'ui-focus-get', args });
-}
-
-/**
- * Configures UI event trace level/sampling.
- */
-export function uiSetEventTrace(worldId: number, args: CmdUiEventTraceSetArgs): void {
-  emitIntent(worldId, { type: 'ui-event-trace-set', args });
-}
-
-/**
- * Creates a UI image from uploaded bytes.
- */
-export function uiCreateImageFromBuffer(
-  worldId: number,
-  args: CmdUiImageCreateFromBufferArgs,
-): void {
-  emitIntent(worldId, { type: 'ui-image-create-from-buffer', args });
-}
-
-/**
- * Disposes a UI image.
- */
-export function uiDisposeImage(worldId: number, args: CmdUiImageDisposeArgs): void {
-  emitIntent(worldId, { type: 'ui-image-dispose', args });
-}
-
-/**
- * Delivers host clipboard paste event to UI.
- */
-export function uiClipboardPaste(worldId: number, args: CmdUiClipboardPasteArgs): void {
-  emitIntent(worldId, { type: 'ui-clipboard-paste', args });
-}
-
-/**
- * Delivers screenshot response bytes to UI.
- */
-export function uiScreenshotReply(worldId: number, args: CmdUiScreenshotReplyArgs): void {
-  emitIntent(worldId, { type: 'ui-screenshot-reply', args });
-}
-
-/**
- * Delivers AccessKit action request to UI.
- */
-export function uiAccessKitActionRequest(
-  worldId: number,
-  args: CmdUiAccessKitActionRequestArgs,
-): void {
-  emitIntent(worldId, { type: 'ui-access-kit-action-request', args });
-}
-
-/**
- * Registers or updates a UI form scope used for tab navigation.
- */
-export function uiFormUpsert(
-  worldId: number,
-  form: {
-    formId: string;
-    windowId: number;
-    realmId: number;
-    documentId: number;
-    disabled?: boolean;
-    cycleMode?: UiFocusCycleMode;
-    activeFieldsetId?: string;
-  },
-): void {
-  emitIntent(worldId, { type: 'ui-form-upsert', form });
-}
-
-/**
- * Disposes a registered UI form scope.
- */
-export function uiFormDispose(worldId: number, formId: string): void {
-  emitIntent(worldId, { type: 'ui-form-dispose', formId });
-}
-
-/**
- * Registers or updates fieldset metadata.
- */
-export function uiFieldsetUpsert(
-  worldId: number,
-  fieldset: {
-    formId: string;
-    fieldsetId: string;
-    disabled?: boolean;
-    legendNodeId?: number;
-  },
-): void {
-  emitIntent(worldId, { type: 'ui-fieldset-upsert', fieldset });
-}
-
-/**
- * Disposes fieldset metadata.
- */
-export function uiFieldsetDispose(
-  worldId: number,
-  formId: string,
-  fieldsetId: string,
-): void {
-  emitIntent(worldId, { type: 'ui-fieldset-dispose', formId, fieldsetId });
-}
-
-/**
- * Registers or updates focusable node metadata.
- */
-export function uiFocusableUpsert(
-  worldId: number,
-  focusable: {
-    formId: string;
-    nodeId: number;
-    tabIndex?: number;
-    fieldsetId?: string;
-    disabled?: boolean;
-    orderHint?: number;
-  },
-): void {
-  emitIntent(worldId, { type: 'ui-focusable-upsert', focusable });
-}
-
-/**
- * Disposes focusable node metadata.
- */
-export function uiFocusableDispose(worldId: number, nodeId: number): void {
-  emitIntent(worldId, { type: 'ui-focusable-dispose', nodeId });
-}
-
-/**
- * Advances focus within a form scope using tab ordering.
- */
-export function uiFocusNext(
-  worldId: number,
-  args: { windowId: number; backwards?: boolean; formId?: string },
-): void {
-  emitIntent(worldId, { type: 'ui-focus-next', ...args });
-}
-
-/**
- * Draws a debug gizmo line for one frame.
- */
-export function drawGizmoLine(
-  worldId: number,
-  props: {
-    start: [number, number, number];
-    end: [number, number, number];
-    color?: [number, number, number, number];
-  },
-): void {
-  emitIntent(worldId, {
-    type: 'gizmo-draw-line',
-    start: props.start,
-    end: props.end,
-    color: props.color || [1, 1, 1, 1],
-  });
-}
-
-/**
- * Draws a debug gizmo AABB for one frame.
- */
-export function drawGizmoAabb(
-  worldId: number,
-  props: {
-    min: [number, number, number];
-    max: [number, number, number];
-    color?: [number, number, number, number];
-  },
-): void {
-  emitIntent(worldId, {
-    type: 'gizmo-draw-aabb',
-    min: props.min,
-    max: props.max,
-    color: props.color || [1, 1, 1, 1],
-  });
-}
-
-/**
- * Creates a new entity in the specified world.
- * Returns the entity ID immediately, but the entity is actually created in the next tick.
- */
-export function createEntity(worldId: number): number {
-  requireInitialized();
-  const entityId = engineState.nextEntityId++;
-
-  emitIntent(worldId, {
-    type: 'create-entity',
-    worldId,
-    entityId,
-  });
-
-  return entityId;
-}
-
-/**
- * Removes an entity and all its components in the next tick.
- */
-export function removeEntity(worldId: number, entityId: number): void {
-  emitIntent(worldId, {
-    type: 'remove-entity',
-    entityId,
-  });
-}
-
-/**
- * Attaches a camera component to an entity via Intent.
- */
-export function createCamera(
-  worldId: number,
-  entityId: number,
-  props: CameraProps = {},
-): void {
-  emitIntent(worldId, {
-    type: 'attach-camera',
-    entityId,
-    props,
-  });
-}
-
-/**
- * Attaches a light component to an entity via Intent.
- */
-export function createLight(
-  worldId: number,
-  entityId: number,
-  props: LightProps = {},
-): void {
-  emitIntent(worldId, {
-    type: 'attach-light',
-    entityId,
-    props,
-  });
-}
-
-/**
- * Attaches a model component to an entity via Intent.
- */
-export function createModel(
-  worldId: number,
-  entityId: number,
-  props: ModelProps,
-): void {
-  emitIntent(worldId, {
-    type: 'attach-model',
-    entityId,
-    props,
-  });
-}
-
-/**
- * Updates an entity's transform via Intent.
- */
-export function updateTransform(
-  worldId: number,
-  entityId: number,
-  props: TransformProps,
-): void {
-  // Apply immediately to local ECS snapshot so same-frame queries
-  // (for example gizmo/collision helpers) observe latest transform.
-  // Intent is still emitted to keep the standard system pipeline authoritative.
-  const world = getWorldOrThrow(worldId);
-  const store = world.components.get(entityId);
-  const transform = store?.get('Transform') as TransformComponent | undefined;
-  if (transform) {
-    if (props.position) {
-      transform.position = [
-        props.position[0] ?? transform.position[0],
-        props.position[1] ?? transform.position[1],
-        props.position[2] ?? transform.position[2],
-      ];
-    }
-    if (props.rotation) {
-      transform.rotation = [
-        props.rotation[0] ?? transform.rotation[0],
-        props.rotation[1] ?? transform.rotation[1],
-        props.rotation[2] ?? transform.rotation[2],
-        props.rotation[3] ?? transform.rotation[3],
-      ];
-    }
-    if (props.scale) {
-      transform.scale = [
-        props.scale[0] ?? transform.scale[0],
-        props.scale[1] ?? transform.scale[1],
-        props.scale[2] ?? transform.scale[2],
-      ];
-    }
-    if (props.layerMask !== undefined) {
-      transform.layerMask = props.layerMask;
-    }
-    if (props.visible !== undefined) {
-      transform.visible = props.visible;
-    }
-    world.constraintDirtyEntities.add(entityId);
-  }
-
-  emitIntent(worldId, {
-    type: 'update-transform',
-    entityId,
-    props,
-  });
-}
-
-/**
- * Attaches a tag component to an entity via Intent.
- */
-export function createTag(
-  worldId: number,
-  entityId: number,
-  props: TagProps,
-): void {
-  emitIntent(worldId, {
-    type: 'attach-tag',
-    entityId,
-    props,
-  });
-}
-
-/**
- * Sets the parent of an entity via Intent.
- */
-export function setParent(
-  worldId: number,
-  entityId: number,
-  parentId: number | null,
-): void {
-  if (parentId !== null && parentId === entityId) {
-    throw new EngineError(
-      'InvalidParent',
-      `Entity ${entityId} cannot be parent of itself.`,
-    );
-  }
-  emitIntent(worldId, {
-    type: 'set-parent',
-    entityId,
-    parentId,
-  });
-}
-
-/**
- * Resources (Material, Geometry, Texture)
- */
-
-/**
- * Creates a material resource and returns its ID.
- */
-export function createMaterial(worldId: number, props: MaterialProps): number {
-  requireInitialized();
-  getWorldOrThrow(worldId);
-  const resourceId = allocateGlobalId();
-
-  emitIntent(worldId, {
-    type: 'create-material',
-    resourceId,
-    props,
-  });
-
-  return resourceId;
-}
-
-/**
- * Creates a geometry resource and returns its ID.
- */
-export function createGeometry(worldId: number, props: GeometryProps): number {
-  requireInitialized();
-  getWorldOrThrow(worldId);
-  const resourceId = allocateGlobalId();
-
-  emitIntent(worldId, {
-    type: 'create-geometry',
-    resourceId,
-    props,
-  });
-
-  return resourceId;
-}
-
-/**
- * Creates a texture resource and returns its ID.
- */
-export function createTexture(worldId: number, props: TextureProps): number {
-  requireInitialized();
-  getWorldOrThrow(worldId);
-  const resourceId = allocateGlobalId();
-
-  emitIntent(worldId, {
-    type: 'create-texture',
-    resourceId,
-    props,
-  });
-
-  return resourceId;
-}
-
-/**
- * Input & Window State Queries
- */
-
-const WORLD_ENTITY_ID = 0;
-
-/**
- * Gets the InputState component for a world.
- * Returns undefined if the system hasn't run yet.
- */
-function getInputState(worldId: number): InputStateComponent | undefined {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const worldStore = world.components.get(WORLD_ENTITY_ID);
-  return worldStore?.get('InputState') as InputStateComponent | undefined;
-}
-
-/**
- * Gets the WindowState component for a world.
- * Returns undefined if the system hasn't run yet.
- */
-function getWindowState(worldId: number): WindowStateComponent | undefined {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const worldStore = world.components.get(WORLD_ENTITY_ID);
-  return worldStore?.get('WindowState') as WindowStateComponent | undefined;
-}
-
-/**
- * Checks if a key is currently pressed.
- */
-export function isKeyPressed(worldId: number, keyCode: number): boolean {
-  const state = getInputState(worldId);
-  return state?.keysPressed.has(keyCode) ?? false;
-}
-
-/**
- * Checks if a key was just pressed this frame.
- */
-export function isKeyJustPressed(worldId: number, keyCode: number): boolean {
-  const state = getInputState(worldId);
-  return state?.keysJustPressed.has(keyCode) ?? false;
-}
-
-/**
- * Checks if a key was just released this frame.
- */
-export function isKeyJustReleased(worldId: number, keyCode: number): boolean {
-  const state = getInputState(worldId);
-  return state?.keysJustReleased.has(keyCode) ?? false;
-}
-
-/**
- * Gets the current pointer position in window space.
- */
-export function getPointerPosition(worldId: number): [number, number] {
-  const state = getInputState(worldId);
-  return state?.pointerPosition ?? [0, 0];
-}
-
-/**
- * Gets the real drawn window area associated with the latest pointer event.
- */
-export function getPointerWindowSize(
-  worldId: number,
-): [number, number] | null {
-  const state = getInputState(worldId);
-  return state?.pointerWindowSize ?? null;
-}
-
-/**
- * Gets the pointer movement delta for this frame in window space.
- */
-export function getPointerDelta(worldId: number): [number, number] {
-  const state = getInputState(worldId);
-  return state?.pointerDelta ?? [0, 0];
-}
-
-/**
- * Gets the pointer position relative to the current routed target.
- */
-export function getPointerTargetPosition(
-  worldId: number,
-): [number, number] | null {
-  const state = getInputState(worldId);
-  return state?.pointerPositionTarget ?? null;
-}
-
-/**
- * Gets the real drawn target area associated with the latest pointer event.
- */
-export function getPointerTargetSize(
-  worldId: number,
-): [number, number] | null {
-  const state = getInputState(worldId);
-  return state?.pointerTargetSize ?? null;
-}
-
-/**
- * Gets the pointer movement delta relative to the current routed target.
- */
-export function getPointerTargetDelta(worldId: number): [number, number] | null {
-  const state = getInputState(worldId);
-  return state?.pointerTargetDelta ?? null;
-}
-
-/**
- * Gets the routed target under pointer, when available.
- */
-export function getPointerTargetId(worldId: number): number | null {
-  const state = getInputState(worldId);
-  return state?.pointerTargetId ?? null;
-}
-
-/**
- * Gets pointer UV (0..1) in routed target space, when available.
- */
-export function getPointerTargetUv(worldId: number): [number, number] | null {
-  const state = getInputState(worldId);
-  return state?.pointerTargetUv ?? null;
-}
-
-/**
- * Checks if a pointer button is currently pressed.
- */
-export function isPointerButtonPressed(worldId: number, button: number): boolean {
-  const state = getInputState(worldId);
-  return state?.pointerButtons.has(button) ?? false;
-}
-
-/**
- * Checks if a pointer button was just pressed this frame.
- */
-export function isPointerButtonJustPressed(
-  worldId: number,
-  button: number,
-): boolean {
-  const state = getInputState(worldId);
-  return state?.pointerJustPressed.has(button) ?? false;
-}
-
-/**
- * Gets the scroll delta for this frame.
- */
-export function getScrollDelta(worldId: number): [number, number] {
-  const state = getInputState(worldId);
-  return state?.scrollDelta ?? [0, 0];
-}
-
-/**
- * Returns true while IME composition is active for this world.
- */
-export function isImeEnabled(worldId: number): boolean {
-  const state = getInputState(worldId);
-  return state?.imeEnabled ?? false;
-}
-
-/**
- * Returns current IME preedit text, if any.
- */
-export function getImePreeditText(worldId: number): string | null {
-  const state = getInputState(worldId);
-  return state?.imePreeditText ?? null;
-}
-
-/**
- * Returns current IME cursor range inside preedit text, if available.
- */
-export function getImeCursorRange(worldId: number): [number, number] | null {
-  const state = getInputState(worldId);
-  return state?.imeCursorRange ?? null;
-}
-
-/**
- * Returns last IME committed text for the current frame, if any.
- */
-export function getImeCommitText(worldId: number): string | null {
-  const state = getInputState(worldId);
-  return state?.imeCommitText ?? null;
-}
-
-/**
- * Gets the current window size.
- */
-export function getWindowSize(worldId: number): [number, number] {
-  const state = getWindowState(worldId);
-  return state?.size ?? [800, 600];
-}
-
-/**
- * Gets the current window position.
- */
-export function getWindowPosition(worldId: number): [number, number] {
-  const state = getWindowState(worldId);
-  return state?.position ?? [0, 0];
-}
-
-/**
- * Checks if the window is focused.
- */
-export function isWindowFocused(worldId: number): boolean {
-  const state = getWindowState(worldId);
-  return state?.focused ?? false;
-}
-
-/**
- * Checks if a close was requested this frame.
- */
-export function isWindowCloseRequested(worldId: number): boolean {
-  const state = getWindowState(worldId);
-  return state?.closeRequested ?? false;
-}
-
-/**
- * Checks if the window was resized this frame.
- */
-export function wasWindowResized(worldId: number): boolean {
-  const state = getWindowState(worldId);
-  return state?.resizedThisFrame ?? false;
-}
-
-/**
- * Gets the window scale factor (DPI scaling).
- */
-export function getWindowScaleFactor(worldId: number): number {
-  const state = getWindowState(worldId);
-  return state?.scaleFactor ?? 1.0;
-}
-
-function getGamepadState(worldId: number):
-  | {
-      connected: Map<number, { name: string }>;
-      buttons: Map<number, Map<number, { pressed: boolean; value: number }>>;
-      axes: Map<number, Map<number, number>>;
-      eventsThisFrame: GamepadEvent[];
-    }
-  | undefined {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const worldStore = world.components.get(WORLD_ENTITY_ID);
-  return worldStore?.get('GamepadState') as
-    | {
-        connected: Map<number, { name: string }>;
-        buttons: Map<number, Map<number, { pressed: boolean; value: number }>>;
-        axes: Map<number, Map<number, number>>;
-        eventsThisFrame: GamepadEvent[];
-      }
-    | undefined;
-}
-
-function getSystemEventState(worldId: number):
-  | {
-      eventsThisFrame: SystemEvent[];
-      lastError?: {
-        scope: string;
-        message: string;
-        commandId?: number;
-        commandType?: string;
-      };
-    }
-  | undefined {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const worldStore = world.components.get(WORLD_ENTITY_ID);
-  return worldStore?.get('SystemEventState') as
-    | {
-        eventsThisFrame: SystemEvent[];
-        lastError?: {
-          scope: string;
-          message: string;
-          commandId?: number;
-          commandType?: string;
-        };
-      }
-    | undefined;
-}
-
-function getUiEventState(worldId: number):
-  | { eventsThisFrame: UiEvent[] }
-  | undefined {
-  requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const worldStore = world.components.get(WORLD_ENTITY_ID);
-  return worldStore?.get('UiEventState') as
-    | { eventsThisFrame: UiEvent[] }
-    | undefined;
-}
-
-export function getGamepadEvents(worldId: number): GamepadEvent[] {
-  return getGamepadState(worldId)?.eventsThisFrame ?? [];
-}
-
-/** Lists currently connected gamepads sorted by id. */
-export function getConnectedGamepads(
-  worldId: number,
-): Array<{ gamepadId: number; name: string }> {
-  const connected = getGamepadState(worldId)?.connected;
-  if (!connected) return [];
-  const out: Array<{ gamepadId: number; name: string }> = [];
-  for (const [gamepadId, info] of connected) {
-    out.push({ gamepadId, name: info.name });
-  }
-  out.sort((a, b) => a.gamepadId - b.gamepadId);
-  return out;
-}
-
-/** Returns current value of a gamepad axis or 0 when unavailable. */
-export function getGamepadAxis(
-  worldId: number,
-  gamepadId: number,
-  axis: number,
-): number {
-  return getGamepadState(worldId)?.axes.get(gamepadId)?.get(axis) ?? 0;
-}
-
-/** Returns whether a gamepad button is currently pressed. */
-export function isGamepadButtonPressed(
-  worldId: number,
-  gamepadId: number,
-  button: number,
-): boolean {
-  return (
-    getGamepadState(worldId)?.buttons.get(gamepadId)?.get(button)?.pressed ??
-    false
-  );
-}
-
-/** Returns system events mirrored in the current frame. */
-export function getSystemEvents(worldId: number): SystemEvent[] {
-  return getSystemEventState(worldId)?.eventsThisFrame ?? [];
-}
-
-/** Returns the last system error seen by the world, if any. */
-export function getLastSystemError(worldId: number): {
-  scope: string;
-  message: string;
-  commandId?: number;
-  commandType?: string;
-} | null {
-  return getSystemEventState(worldId)?.lastError ?? null;
-}
-
-/** Returns UI events mirrored in the current frame. */
-export function getUiEvents(worldId: number): UiEvent[] {
-  return getUiEventState(worldId)?.eventsThisFrame ?? [];
-}
+export * from './entities/intents';
+export * from './entities/world-state';
+export * from './entities/targets';
+export * from './entities/audio';
+export * from './entities/resources';
+export * from './entities/ui';
+export * from './entities/scene';
+export * from './entities/state-queries';