@vulfram/engine 0.19.2-alpha → 0.20.1-alpha

package/src/engine/world/entities/targets.ts

@@ -0,0 +1,203 @@
+import type {
+  CmdTargetMeasurementArgs,
+  CmdTargetDisposeArgs,
+  CmdTargetLayerDisposeArgs,
+  CmdTargetLayerUpsertArgs,
+  CmdTargetUpsertArgs,
+  TargetLayerLayout,
+} from '../../../types/cmds/target';
+import type {
+  CmdInputTargetListenerDisposeArgs,
+  CmdInputTargetListenerListArgs,
+  CmdInputTargetListenerUpsertArgs,
+} from '../../../types/cmds/input';
+import { enqueueCommand, markRoutingIndexDirty } from '../../bridge/dispatch';
+import { getWorldOrThrow, requireInitialized } from '../../bridge/guards';
+import type { CameraComponent } from '../../ecs';
+import { allocateGlobalId, recalculateWorldWindowBindings } from './common';
+import { getWorldRealmId } from './world-state';
+
+/**
+ * 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);
+}
+
+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;
+}
+
+/**
+ * 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,
+  });
+}
+
+/**
+ * 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 };
+}

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

@@ -0,0 +1,192 @@
+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 { UiFocusCycleMode } from '../../ecs';
+import { emitIntent } from './intents';
+
+/** 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 });
+}

package/src/engine/world/entities/world-state.ts

@@ -0,0 +1,140 @@
+import type {
+  CmdSystemDiagnosticsSetArgs,
+  CmdUploadBufferDiscardAllArgs,
+} from '../../../types/cmds/system';
+import { EngineError } from '../../errors';
+import {
+  enqueueGlobalCommand,
+  markRoutingIndexDirty,
+} from '../../bridge/dispatch';
+import { getWorldOrThrow, requireInitialized } from '../../bridge/guards';
+import { engineState } from '../../state';
+
+/**
+ * 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;
+}
+
+/**
+ * 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);
+}