@vulfram/engine 0.5.8-alpha → 0.17.1-alpha

package/src/engine/world/mount.ts

@@ -0,0 +1,174 @@
+import type {
+  CmdTargetLayerDisposeArgs,
+  CmdTargetLayerUpsertArgs,
+  CmdTargetUpsertArgs,
+  TargetLayerLayout,
+} from '../../types/cmds/target';
+import { engineState } from '../state';
+import {
+  bindWorldToTarget,
+  isWorldReady,
+  unbindWorldFromTarget,
+  upsertTarget,
+} from './entities';
+import type { CommandId, TargetId, WindowId, WorldId } from './types';
+import {
+  asCommandId,
+  asTargetId,
+  asWorldNumber,
+} from './types';
+
+type MountTargetConfig = Omit<CmdTargetUpsertArgs, 'targetId'>;
+
+export type MountWorldArgs = {
+  target: MountTargetConfig;
+  targetId?: TargetId;
+  layout?: TargetLayerLayout;
+  cameraId?: number;
+  environmentId?: number;
+};
+
+export type WaitWorldReadyOptions = {
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+};
+
+/**
+ * Returns whether the world has resolved its internal core realm and can be mounted.
+ */
+export function isWorldMountReady(worldId: WorldId): boolean {
+  return isWorldReady(asWorldNumber(worldId));
+}
+
+/**
+ * Waits until a world reports mount readiness.
+ *
+ * Note: this helper only polls local readiness; callers still must keep
+ * driving `tick(...)` while waiting.
+ *
+ * @returns `true` when ready, or `false` when timeout is reached.
+ */
+export async function waitWorldReady(
+  worldId: WorldId,
+  options: WaitWorldReadyOptions = {},
+): Promise<boolean> {
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const pollIntervalMs = options.pollIntervalMs ?? 16;
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    if (isWorldMountReady(worldId)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+  return isWorldMountReady(worldId);
+}
+
+function allocateTargetId(): TargetId {
+  return asTargetId(engineState.nextGlobalId++);
+}
+
+function defaultLayout(): TargetLayerLayout {
+  return {
+    left: { unit: 'percent', value: 0 },
+    top: { unit: 'percent', value: 0 },
+    width: { unit: 'percent', value: 100 },
+    height: { unit: 'percent', value: 100 },
+    zIndex: 0,
+    blendMode: 0,
+  };
+}
+
+/**
+ * Mounts a world into any target supported by core.
+ *
+ * This function hides realm details from the public API. Internally it:
+ * 1) creates/updates target (`cmd-target-upsert`)
+ * 2) enqueues layer bind (`cmd-target-layer-upsert`) in the same frame
+ *    so command order remains deterministic and avoids duplicate binds.
+ *
+ * @param worldId World to be mounted.
+ * @param args Target configuration and optional layout/camera/environment overrides.
+ * @returns Generated target id and command ids for upsert + bind.
+ */
+export function mountWorld(
+  worldId: WorldId,
+  args: MountWorldArgs,
+): {
+  targetId: TargetId;
+  targetCommandId: CommandId;
+  mountCommandId: CommandId;
+} {
+  const targetId = args.targetId ?? allocateTargetId();
+  const world = asWorldNumber(worldId);
+
+  const targetCommandId = upsertTarget(world, {
+    targetId: targetId as number,
+    ...args.target,
+  });
+
+  const bindArgs = {
+    targetId: targetId as number,
+    layout: args.layout ?? defaultLayout(),
+    cameraId: args.cameraId,
+    environmentId: args.environmentId,
+  };
+  const mountCommandId = bindWorldToTarget(world, bindArgs);
+
+  return {
+    targetId,
+    targetCommandId: asCommandId(targetCommandId),
+    mountCommandId: asCommandId(mountCommandId),
+  };
+}
+
+/**
+ * Convenience wrapper for mounting a world directly into a window target.
+ */
+export function mountWorldToWindow(
+  worldId: WorldId,
+  windowId: WindowId,
+  options: Omit<MountWorldArgs, 'target'> = {},
+): {
+  targetId: TargetId;
+  targetCommandId: CommandId;
+  mountCommandId: CommandId;
+} {
+  return mountWorld(worldId, {
+    ...options,
+    target: {
+      kind: 'window',
+      windowId: windowId as number,
+    },
+  });
+}
+
+/**
+ * Unmounts a world from a target.
+ *
+ * @param worldId Mounted world identifier.
+ * @param targetId Target to unbind.
+ * @returns Command id for unbind request.
+ */
+export function unmountWorld(worldId: WorldId, targetId: TargetId): CommandId {
+  const commandId = unbindWorldFromTarget(asWorldNumber(worldId), {
+    targetId: targetId as number,
+  } as Omit<CmdTargetLayerDisposeArgs, 'realmId'>);
+  return asCommandId(commandId);
+}
+
+/**
+ * Remounts an existing world->target binding with a new layer layout/camera/environment.
+ *
+ * @param worldId Mounted world identifier.
+ * @param args Layer update payload.
+ * @returns Command id for target-layer upsert.
+ */
+export function remountWorld(
+  worldId: WorldId,
+  args: Omit<CmdTargetLayerUpsertArgs, 'realmId'>,
+): CommandId {
+  const commandId = bindWorldToTarget(asWorldNumber(worldId), args);
+  return asCommandId(commandId);
+}

package/src/engine/world/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Generic branded numeric IDs used by the public API to avoid mixing domains.
+ *
+ * Example:
+ * `type WindowId = number & { __WINDOW_ID__: null }`
+ */
+export type WorldId = number & { __WORLD_ID__: null };
+export type World3DId = WorldId & { __WORLD_3D_ID__: null };
+export type WorldUIId = WorldId & { __WORLD_UI_ID__: null };
+export type WindowId = number & { __WINDOW_ID__: null };
+export type TargetId = number & { __TARGET_ID__: null };
+export type EntityId = number & { __ENTITY_ID__: null };
+export type MaterialId = number & { __MATERIAL_ID__: null };
+export type GeometryId = number & { __GEOMETRY_ID__: null };
+export type TextureId = number & { __TEXTURE_ID__: null };
+export type CommandId = number & { __COMMAND_ID__: null };
+
+/** Casts a numeric value to a branded world id. */
+export function asWorldId(value: number): WorldId {
+  return value as WorldId;
+}
+
+/** Casts a numeric value to a branded 3D world id. */
+export function asWorld3DId(value: number): World3DId {
+  return value as World3DId;
+}
+
+/** Casts a numeric value to a branded UI world id. */
+export function asWorldUIId(value: number): WorldUIId {
+  return value as WorldUIId;
+}
+
+/** Casts a numeric value to a branded window id. */
+export function asWindowId(value: number): WindowId {
+  return value as WindowId;
+}
+
+/** Casts a numeric value to a branded target id. */
+export function asTargetId(value: number): TargetId {
+  return value as TargetId;
+}
+
+/** Casts a numeric value to a branded entity id. */
+export function asEntityId(value: number): EntityId {
+  return value as EntityId;
+}
+
+/** Casts a numeric value to a branded material id. */
+export function asMaterialId(value: number): MaterialId {
+  return value as MaterialId;
+}
+
+/** Casts a numeric value to a branded geometry id. */
+export function asGeometryId(value: number): GeometryId {
+  return value as GeometryId;
+}
+
+/** Casts a numeric value to a branded texture id. */
+export function asTextureId(value: number): TextureId {
+  return value as TextureId;
+}
+
+/** Casts a numeric value to a branded command id. */
+export function asCommandId(value: number): CommandId {
+  return value as CommandId;
+}
+
+/** Returns raw numeric world id from branded world id variants. */
+export function asWorldNumber(worldId: WorldId | World3DId | WorldUIId | number): number {
+  return worldId as number;
+}

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

@@ -0,0 +1,266 @@
+import { createWorldUI as createWorldUIRaw } from '../api';
+import type { UiFocusCycleMode } from '../ecs';
+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 { UiEvent } from '../../types/events/ui';
+import { EngineError } from '../errors';
+import { getWorldOrThrow } from '../bridge/guards';
+import {
+  getUiEvents as getUiEventsRaw,
+  uiAccessKitActionRequest as uiAccessKitActionRequestRaw,
+  uiApplyOps as uiApplyOpsRaw,
+  uiClipboardPaste as uiClipboardPasteRaw,
+  uiCreateDocument as uiCreateDocumentRaw,
+  uiCreateImageFromBuffer as uiCreateImageFromBufferRaw,
+  uiDefineTheme as uiDefineThemeRaw,
+  uiDisposeDocument as uiDisposeDocumentRaw,
+  uiDisposeImage as uiDisposeImageRaw,
+  uiDisposeTheme as uiDisposeThemeRaw,
+  uiFieldsetDispose as uiFieldsetDisposeRaw,
+  uiFieldsetUpsert as uiFieldsetUpsertRaw,
+  uiFocusableDispose as uiFocusableDisposeRaw,
+  uiFocusableUpsert as uiFocusableUpsertRaw,
+  uiFocusNext as uiFocusNextRaw,
+  uiFormDispose as uiFormDisposeRaw,
+  uiFormUpsert as uiFormUpsertRaw,
+  uiGetDocumentTree as uiGetDocumentTreeRaw,
+  uiGetFocus as uiGetFocusRaw,
+  uiGetLayoutRects as uiGetLayoutRectsRaw,
+  uiScreenshotReply as uiScreenshotReplyRaw,
+  uiSetDebug as uiSetDebugRaw,
+  uiSetDocumentRect as uiSetDocumentRectRaw,
+  uiSetDocumentTheme as uiSetDocumentThemeRaw,
+  uiSetEventTrace as uiSetEventTraceRaw,
+  uiSetFocus as uiSetFocusRaw,
+} from './entities';
+import type { WorldUIId } from './types';
+import { asWorldNumber, asWorldUIId } from './types';
+
+type CreateUIWorldOptions = {
+  outputSurfaceId?: number;
+  importance?: number;
+  cachePolicy?: number;
+  flags?: number;
+};
+
+type UIFormUpsertArgs = {
+  formId: string;
+  documentId: number;
+  disabled?: boolean;
+  cycleMode?: UiFocusCycleMode;
+  activeFieldsetId?: string;
+};
+
+type UIFocusNextArgs = {
+  backwards?: boolean;
+  formId?: string;
+};
+
+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.`,
+    );
+  }
+
+  if (world.primaryWindowId !== undefined) {
+    return { windowId: world.primaryWindowId, realmId };
+  }
+  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.`,
+  );
+}
+
+/**
+ * Creates a UI world.
+ *
+ * The world is realm-backed internally, but realm details are hidden from this API.
+ * Use `Mount.mountWorld(...)` to present this world in one or more targets.
+ */
+export function createUIWorld(options?: CreateUIWorldOptions): WorldUIId {
+  return asWorldUIId(createWorldUIRaw(options));
+}
+
+/** Defines a theme in a UI world. */
+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 {
+  uiDisposeThemeRaw(asWorldNumber(worldId), args);
+}
+
+/** Creates a document in a UI world. */
+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 {
+  uiDisposeDocumentRaw(asWorldNumber(worldId), args);
+}
+
+/** Sets document rect in a UI world. */
+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 {
+  uiSetDocumentThemeRaw(asWorldNumber(worldId), args);
+}
+
+/** Applies UI ops batch in a UI world. */
+export function applyUIOps(worldId: WorldUIId, args: CmdUiApplyOpsArgs): void {
+  uiApplyOpsRaw(asWorldNumber(worldId), args);
+}
+
+/** Requests UI document tree. */
+export function getUIDocumentTree(worldId: WorldUIId, args: CmdUiDocumentGetTreeArgs): void {
+  uiGetDocumentTreeRaw(asWorldNumber(worldId), args);
+}
+
+/** Requests UI layout rects. */
+export function getUILayoutRects(worldId: WorldUIId, args: CmdUiDocumentGetLayoutRectsArgs): void {
+  uiGetLayoutRectsRaw(asWorldNumber(worldId), args);
+}
+
+/** Configures UI debug flags. */
+export function setUIDebug(worldId: WorldUIId, args: CmdUiDebugSetArgs): void {
+  uiSetDebugRaw(asWorldNumber(worldId), args);
+}
+
+/** Sets focus in a UI world. */
+export function setUIFocus(worldId: WorldUIId, args: CmdUiFocusSetArgs): void {
+  uiSetFocusRaw(asWorldNumber(worldId), args);
+}
+
+/** Requests focus state in a UI world. */
+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 {
+  uiSetEventTraceRaw(asWorldNumber(worldId), args);
+}
+
+/** Creates UI image from a previously uploaded buffer. */
+export function createUIImageFromBuffer(worldId: WorldUIId, args: CmdUiImageCreateFromBufferArgs): void {
+  uiCreateImageFromBufferRaw(asWorldNumber(worldId), args);
+}
+
+/** Disposes UI image resource. */
+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 {
+  uiClipboardPasteRaw(asWorldNumber(worldId), args);
+}
+
+/** Replies to UI screenshot request. */
+export function replyUIScreenshot(worldId: WorldUIId, args: CmdUiScreenshotReplyArgs): void {
+  uiScreenshotReplyRaw(asWorldNumber(worldId), args);
+}
+
+/** Sends AccessKit action request. */
+export function requestUIAccessKitAction(worldId: WorldUIId, args: CmdUiAccessKitActionRequestArgs): void {
+  uiAccessKitActionRequestRaw(asWorldNumber(worldId), args);
+}
+
+/**
+ * Upserts UI form metadata.
+ *
+ * `windowId` and `realmId` are resolved internally from world bindings.
+ */
+export function upsertUIForm(worldId: WorldUIId, form: UIFormUpsertArgs): void {
+  const rawWorldId = asWorldNumber(worldId);
+  const context = resolveWorldUIContext(rawWorldId);
+  uiFormUpsertRaw(rawWorldId, {
+    ...form,
+    windowId: context.windowId,
+    realmId: context.realmId,
+  });
+}
+
+/** Disposes UI form metadata. */
+export function disposeUIForm(worldId: WorldUIId, formId: string): void {
+  uiFormDisposeRaw(asWorldNumber(worldId), formId);
+}
+
+/** Upserts UI fieldset metadata. */
+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 {
+  uiFieldsetDisposeRaw(asWorldNumber(worldId), args.formId, args.fieldsetId);
+}
+
+/** Upserts focusable metadata. */
+export function upsertUIFocusable(worldId: WorldUIId, args: Parameters<typeof uiFocusableUpsertRaw>[1]): void {
+  uiFocusableUpsertRaw(asWorldNumber(worldId), args);
+}
+
+/** Disposes focusable metadata. */
+export function disposeUIFocusable(worldId: WorldUIId, nodeId: number): void {
+  uiFocusableDisposeRaw(asWorldNumber(worldId), nodeId);
+}
+
+/**
+ * Requests moving focus to next/previous focusable.
+ *
+ * `windowId` is resolved internally from world bindings.
+ */
+export function focusUINext(
+  worldId: WorldUIId,
+  args: UIFocusNextArgs = {},
+): void {
+  const rawWorldId = asWorldNumber(worldId);
+  const context = resolveWorldUIContext(rawWorldId);
+  uiFocusNextRaw(rawWorldId, {
+    ...args,
+    windowId: context.windowId,
+  });
+}
+
+/**
+ * Returns UI events mirrored from the latest processed frame.
+ *
+ * This accessor is read-only from the host perspective; events are replaced each tick.
+ */
+export function getUIEvents(worldId: WorldUIId): UiEvent[] {
+  return getUiEventsRaw(asWorldNumber(worldId));
+}