@vulfram/engine 0.17.1-alpha → 0.19.3-alpha

package/src/engine/world/entities.ts

@@ -4,6 +4,7 @@ import type {
   CmdEnvironmentDisposeArgs,
 } from '../../types/cmds/environment';
 import type {
+  CmdTargetMeasurementArgs,
   CmdTargetDisposeArgs,
   CmdTargetLayerDisposeArgs,
   CmdTargetLayerUpsertArgs,
@@ -29,6 +30,11 @@ 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,
@@ -69,6 +75,7 @@ import type {
   ModelProps,
   TagProps,
   TextureProps,
+  TransformComponent,
   TransformProps,
   UiFocusCycleMode,
   WindowStateComponent,
@@ -107,7 +114,7 @@ function recalculateWorldWindowBindings(world: ReturnType<typeof getWorldOrThrow
 export function emitIntent(worldId: number, intent: Intent): void {
   requireInitialized();
   const world = getWorldOrThrow(worldId);
-  world.pendingIntents.push(intent);
+  world.intentStore.enqueue(intent);
 }
 
 /**
@@ -157,6 +164,46 @@ export function upsertTarget(worldId: number, args: CmdTargetUpsertArgs): number
   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.
  */
@@ -178,19 +225,8 @@ export function bindWorldToTarget(
   args: Omit<CmdTargetLayerUpsertArgs, 'realmId'>,
 ): number {
   const world = getWorldOrThrow(worldId);
-  const realmId = getWorldRealmId(worldId);
-  if (realmId === null) {
-    throw new EngineError(
-      'WorldNotReady',
-      `World ${worldId} realm is not ready. Call tick() and wait for realm-create response.`,
-    );
-  }
 
   const resolvedCameraId = args.cameraId ?? findPreferredCameraId(worldId);
-  const resolvedArgs: Omit<CmdTargetLayerUpsertArgs, 'realmId'> = {
-    ...args,
-    cameraId: resolvedCameraId,
-  };
 
   world.targetLayerBindings.set(args.targetId, {
     targetId: args.targetId,
@@ -200,9 +236,16 @@ export function bindWorldToTarget(
   });
   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,
-    ...resolvedArgs,
+    ...args,
+    cameraId: resolvedCameraId,
   });
 }
 
@@ -214,18 +257,18 @@ export function unbindWorldFromTarget(
   args: Omit<CmdTargetLayerDisposeArgs, 'realmId'>,
 ): number {
   const world = getWorldOrThrow(worldId);
-  const realmId = getWorldRealmId(worldId);
-  if (realmId === null) {
-    throw new EngineError(
-      'WorldNotReady',
-      `World ${worldId} realm is not ready. Call tick() and wait for realm-create response.`,
-    );
-  }
   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,
@@ -317,7 +360,7 @@ export function disposeWorld(
   }
   const hasRetainedTargets = world.targetLayerBindings.size > 0;
   const hasPendingWork =
-    world.pendingIntents.length > 0 || world.pendingCommands.length > 0;
+    world.intentStore.size() > 0 || world.pendingCommands.length > 0;
 
   if (
     (!disposeRealm && (retainedCoreObjectCount > 0 || hasPendingWork)) ||
@@ -328,7 +371,7 @@ export function disposeWorld(
       `retainRealm=${!disposeRealm} retainTargets=${!disposeTargets} ` +
       `trackedCoreObjects=${retainedCoreObjectCount} ` +
       `targetBindings=${world.targetLayerBindings.size} ` +
-      `pendingIntents=${world.pendingIntents.length} ` +
+      `pendingIntents=${world.intentStore.size()} ` +
       `pendingCommands=${world.pendingCommands.length}`;
     if (strictResourceLifecycle) {
       throw new EngineError('WorldDisposeLifecycleRisk', message);
@@ -589,9 +632,6 @@ function resolveWorldWindowId(worldId: number): number {
     for (const windowId of world.targetWindowBindings.values()) {
       return windowId;
     }
-    if (world.realmCreateArgs.hostWindowId !== undefined) {
-      return world.realmCreateArgs.hostWindowId;
-    }
     throw new EngineError(
       'WindowNotFound',
       `World ${worldId} has no window binding available for this command.`,
@@ -1054,6 +1094,44 @@ export function updateTransform(
   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,
@@ -1205,38 +1283,92 @@ export function isKeyJustReleased(worldId: number, keyCode: number): boolean {
 }
 
 /**
- * Gets the current mouse position.
+ * 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 getMousePosition(worldId: number): [number, number] {
+export function getPointerWindowSize(
+  worldId: number,
+): [number, number] | null {
   const state = getInputState(worldId);
-  return state?.mousePosition ?? [0, 0];
+  return state?.pointerWindowSize ?? null;
 }
 
 /**
- * Gets the mouse movement delta for this frame.
+ * Gets the pointer movement delta for this frame in window space.
  */
-export function getMouseDelta(worldId: number): [number, number] {
+export function getPointerDelta(worldId: number): [number, number] {
   const state = getInputState(worldId);
-  return state?.mouseDelta ?? [0, 0];
+  return state?.pointerDelta ?? [0, 0];
 }
 
 /**
- * Checks if a mouse button is currently pressed.
+ * Gets the pointer position relative to the current routed target.
  */
-export function isMouseButtonPressed(worldId: number, button: number): boolean {
+export function getPointerTargetPosition(
+  worldId: number,
+): [number, number] | null {
   const state = getInputState(worldId);
-  return state?.mouseButtons.has(button) ?? false;
+  return state?.pointerPositionTarget ?? null;
 }
 
 /**
- * Checks if a mouse button was just pressed this frame.
+ * Gets the real drawn target area associated with the latest pointer event.
  */
-export function isMouseButtonJustPressed(
+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?.mouseJustPressed.has(button) ?? false;
+  return state?.pointerJustPressed.has(button) ?? false;
 }
 
 /**
@@ -1247,6 +1379,38 @@ export function getScrollDelta(worldId: number): [number, number] {
   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.
  */

package/src/engine/world/mount.ts

@@ -1,4 +1,5 @@
 import type {
+  CmdTargetMeasurementArgs,
   CmdTargetLayerDisposeArgs,
   CmdTargetLayerUpsertArgs,
   CmdTargetUpsertArgs,
@@ -8,6 +9,7 @@ import { engineState } from '../state';
 import {
   bindWorldToTarget,
   isWorldReady,
+  measureTarget,
   unbindWorldFromTarget,
   upsertTarget,
 } from './entities';
@@ -31,6 +33,7 @@ export type MountWorldArgs = {
 export type WaitWorldReadyOptions = {
   timeoutMs?: number;
   pollIntervalMs?: number;
+  onPoll?: (() => void | Promise<void>) | undefined;
 };
 
 /**
@@ -54,15 +57,22 @@ export async function waitWorldReady(
 ): Promise<boolean> {
   const timeoutMs = options.timeoutMs ?? 5_000;
   const pollIntervalMs = options.pollIntervalMs ?? 16;
-  const start = Date.now();
+  const deadline = Date.now() + timeoutMs;
 
-  while (Date.now() - start < timeoutMs) {
-    if (isWorldMountReady(worldId)) {
-      return true;
+  const poll = async (): Promise<boolean> => {
+    if (isWorldMountReady(worldId)) return true;
+    if (Date.now() >= deadline) return isWorldMountReady(worldId);
+
+    if (options.onPoll) {
+      await options.onPoll();
+      if (isWorldMountReady(worldId)) return true;
     }
+
     await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-  }
-  return isWorldMountReady(worldId);
+    return poll();
+  };
+
+  return poll();
 }
 
 function allocateTargetId(): TargetId {
@@ -172,3 +182,14 @@ export function remountWorld(
   const commandId = bindWorldToTarget(asWorldNumber(worldId), args);
   return asCommandId(commandId);
 }
+
+/**
+ * Requests measurement for a mounted target.
+ */
+export function measureMountedTarget(
+  worldId: WorldId,
+  args: CmdTargetMeasurementArgs,
+): CommandId {
+  const commandId = measureTarget(asWorldNumber(worldId), args);
+  return asCommandId(commandId);
+}

package/src/engine/world/world-ui.ts

@@ -55,7 +55,6 @@ import type { WorldUIId } from './types';
 import { asWorldNumber, asWorldUIId } from './types';
 
 type CreateUIWorldOptions = {
-  outputSurfaceId?: number;
   importance?: number;
   cachePolicy?: number;
   flags?: number;
@@ -74,15 +73,12 @@ type UIFocusNextArgs = {
   formId?: string;
 };
 
-function resolveWorldUIContext(worldId: number): { windowId: number; realmId: number } {
+function resolveWorldUIContext(worldId: number): {
+  windowId: number;
+  realmId: number;
+} {
   const world = getWorldOrThrow(worldId);
-  const realmId = world.coreRealmId;
-  if (realmId === undefined) {
-    throw new EngineError(
-      'WorldNotReady',
-      `World ${worldId} has no core realm available yet.`,
-    );
-  }
+  const realmId = world.coreRealmId ?? world.worldId;
 
   if (world.primaryWindowId !== undefined) {
     return { windowId: world.primaryWindowId, realmId };
@@ -90,9 +86,6 @@ function resolveWorldUIContext(worldId: number): { windowId: number; realmId: nu
   for (const windowId of world.targetWindowBindings.values()) {
     return { windowId, realmId };
   }
-  if (world.realmCreateArgs.hostWindowId !== undefined) {
-    return { windowId: world.realmCreateArgs.hostWindowId, realmId };
-  }
   throw new EngineError(
     'WindowNotFound',
     `World ${worldId} has no window binding available for UI operation.`,
@@ -110,32 +103,50 @@ export function createUIWorld(options?: CreateUIWorldOptions): WorldUIId {
 }
 
 /** Defines a theme in a UI world. */
-export function defineUITheme(worldId: WorldUIId, args: CmdUiThemeDefineArgs): void {
+export function defineUITheme(
+  worldId: WorldUIId,
+  args: CmdUiThemeDefineArgs,
+): void {
   uiDefineThemeRaw(asWorldNumber(worldId), args);
 }
 
 /** Disposes a theme in a UI world. */
-export function disposeUITheme(worldId: WorldUIId, args: CmdUiThemeDisposeArgs): void {
+export function disposeUITheme(
+  worldId: WorldUIId,
+  args: CmdUiThemeDisposeArgs,
+): void {
   uiDisposeThemeRaw(asWorldNumber(worldId), args);
 }
 
 /** Creates a document in a UI world. */
-export function createUIDocument(worldId: WorldUIId, args: CmdUiDocumentCreateArgs): void {
+export function createUIDocument(
+  worldId: WorldUIId,
+  args: CmdUiDocumentCreateArgs,
+): void {
   uiCreateDocumentRaw(asWorldNumber(worldId), args);
 }
 
 /** Disposes a document in a UI world. */
-export function disposeUIDocument(worldId: WorldUIId, args: CmdUiDocumentDisposeArgs): void {
+export function disposeUIDocument(
+  worldId: WorldUIId,
+  args: CmdUiDocumentDisposeArgs,
+): void {
   uiDisposeDocumentRaw(asWorldNumber(worldId), args);
 }
 
 /** Sets document rect in a UI world. */
-export function setUIDocumentRect(worldId: WorldUIId, args: CmdUiDocumentSetRectArgs): void {
+export function setUIDocumentRect(
+  worldId: WorldUIId,
+  args: CmdUiDocumentSetRectArgs,
+): void {
   uiSetDocumentRectRaw(asWorldNumber(worldId), args);
 }
 
 /** Sets document theme in a UI world. */
-export function setUIDocumentTheme(worldId: WorldUIId, args: CmdUiDocumentSetThemeArgs): void {
+export function setUIDocumentTheme(
+  worldId: WorldUIId,
+  args: CmdUiDocumentSetThemeArgs,
+): void {
   uiSetDocumentThemeRaw(asWorldNumber(worldId), args);
 }
 
@@ -145,12 +156,18 @@ export function applyUIOps(worldId: WorldUIId, args: CmdUiApplyOpsArgs): void {
 }
 
 /** Requests UI document tree. */
-export function getUIDocumentTree(worldId: WorldUIId, args: CmdUiDocumentGetTreeArgs): void {
+export function getUIDocumentTree(
+  worldId: WorldUIId,
+  args: CmdUiDocumentGetTreeArgs,
+): void {
   uiGetDocumentTreeRaw(asWorldNumber(worldId), args);
 }
 
 /** Requests UI layout rects. */
-export function getUILayoutRects(worldId: WorldUIId, args: CmdUiDocumentGetLayoutRectsArgs): void {
+export function getUILayoutRects(
+  worldId: WorldUIId,
+  args: CmdUiDocumentGetLayoutRectsArgs,
+): void {
   uiGetLayoutRectsRaw(asWorldNumber(worldId), args);
 }
 
@@ -165,37 +182,58 @@ export function setUIFocus(worldId: WorldUIId, args: CmdUiFocusSetArgs): void {
 }
 
 /** Requests focus state in a UI world. */
-export function getUIFocus(worldId: WorldUIId, args: CmdUiFocusGetArgs = {}): void {
+export function getUIFocus(
+  worldId: WorldUIId,
+  args: CmdUiFocusGetArgs = {},
+): void {
   uiGetFocusRaw(asWorldNumber(worldId), args);
 }
 
 /** Configures UI event trace in a UI world. */
-export function setUIEventTrace(worldId: WorldUIId, args: CmdUiEventTraceSetArgs): void {
+export function setUIEventTrace(
+  worldId: WorldUIId,
+  args: CmdUiEventTraceSetArgs,
+): void {
   uiSetEventTraceRaw(asWorldNumber(worldId), args);
 }
 
 /** Creates UI image from a previously uploaded buffer. */
-export function createUIImageFromBuffer(worldId: WorldUIId, args: CmdUiImageCreateFromBufferArgs): void {
+export function createUIImageFromBuffer(
+  worldId: WorldUIId,
+  args: CmdUiImageCreateFromBufferArgs,
+): void {
   uiCreateImageFromBufferRaw(asWorldNumber(worldId), args);
 }
 
 /** Disposes UI image resource. */
-export function disposeUIImage(worldId: WorldUIId, args: CmdUiImageDisposeArgs): void {
+export function disposeUIImage(
+  worldId: WorldUIId,
+  args: CmdUiImageDisposeArgs,
+): void {
   uiDisposeImageRaw(asWorldNumber(worldId), args);
 }
 
 /** Sends clipboard paste payload to UI world. */
-export function pasteUIClipboard(worldId: WorldUIId, args: CmdUiClipboardPasteArgs): void {
+export function pasteUIClipboard(
+  worldId: WorldUIId,
+  args: CmdUiClipboardPasteArgs,
+): void {
   uiClipboardPasteRaw(asWorldNumber(worldId), args);
 }
 
 /** Replies to UI screenshot request. */
-export function replyUIScreenshot(worldId: WorldUIId, args: CmdUiScreenshotReplyArgs): void {
+export function replyUIScreenshot(
+  worldId: WorldUIId,
+  args: CmdUiScreenshotReplyArgs,
+): void {
   uiScreenshotReplyRaw(asWorldNumber(worldId), args);
 }
 
 /** Sends AccessKit action request. */
-export function requestUIAccessKitAction(worldId: WorldUIId, args: CmdUiAccessKitActionRequestArgs): void {
+export function requestUIAccessKitAction(
+  worldId: WorldUIId,
+  args: CmdUiAccessKitActionRequestArgs,
+): void {
   uiAccessKitActionRequestRaw(asWorldNumber(worldId), args);
 }
 
@@ -220,17 +258,26 @@ export function disposeUIForm(worldId: WorldUIId, formId: string): void {
 }
 
 /** Upserts UI fieldset metadata. */
-export function upsertUIFieldset(worldId: WorldUIId, args: Parameters<typeof uiFieldsetUpsertRaw>[1]): void {
+export function upsertUIFieldset(
+  worldId: WorldUIId,
+  args: Parameters<typeof uiFieldsetUpsertRaw>[1],
+): void {
   uiFieldsetUpsertRaw(asWorldNumber(worldId), args);
 }
 
 /** Disposes UI fieldset metadata. */
-export function disposeUIFieldset(worldId: WorldUIId, args: { formId: string; fieldsetId: string }): void {
+export function disposeUIFieldset(
+  worldId: WorldUIId,
+  args: { formId: string; fieldsetId: string },
+): void {
   uiFieldsetDisposeRaw(asWorldNumber(worldId), args.formId, args.fieldsetId);
 }
 
 /** Upserts focusable metadata. */
-export function upsertUIFocusable(worldId: WorldUIId, args: Parameters<typeof uiFocusableUpsertRaw>[1]): void {
+export function upsertUIFocusable(
+  worldId: WorldUIId,
+  args: Parameters<typeof uiFocusableUpsertRaw>[1],
+): void {
   uiFocusableUpsertRaw(asWorldNumber(worldId), args);
 }