@vulfram/engine 0.14.8-alpha → 0.17.1-alpha

package/src/engine/window/manager.ts

@@ -0,0 +1,168 @@
+import type { CmdWindowCloseArgs, CmdWindowCreateArgs } from '../../types/cmds/window';
+import type {
+  CursorGrabMode,
+  CursorIcon,
+  UserAttentionType,
+  WindowState,
+} from '../../types/kinds';
+import { enqueueGlobalCommand } from '../bridge/dispatch';
+import { requireInitialized } from '../bridge/guards';
+import { engineState } from '../state';
+import type { CommandId, WindowId } from '../world/types';
+import { asCommandId, asWindowId } from '../world/types';
+
+export interface WindowProps {
+  title?: string;
+  position?: [number, number];
+  size?: [number, number];
+  state?: WindowState;
+  resizable?: boolean;
+  decorations?: boolean;
+  cursorVisible?: boolean;
+  cursorGrab?: CursorGrabMode;
+  icon?: number;
+  cursorIcon?: CursorIcon;
+}
+
+export interface CreateWindowProps {
+  title: string;
+  size: [number, number];
+  position: [number, number];
+  canvasId?: string;
+  borderless?: boolean;
+  resizable?: boolean;
+  transparent?: boolean;
+  initialState?: WindowState;
+}
+
+function allocateWindowId(): WindowId {
+  while (engineState.usedWindowIds.has(engineState.nextWindowId)) {
+    engineState.nextWindowId++;
+  }
+  const id = engineState.nextWindowId++;
+  engineState.usedWindowIds.add(id);
+  return asWindowId(id);
+}
+
+/**
+ * Creates a window and returns a typed window id plus the command id.
+ *
+ * IDs are auto-generated by default to avoid collisions. You can pass `windowId`
+ * only when integrating with an existing host-level ID contract.
+ */
+export function createWindow(
+  props: CreateWindowProps,
+  windowId?: WindowId,
+): { windowId: WindowId; commandId: CommandId } {
+  requireInitialized();
+  const resolvedWindowId = windowId ?? allocateWindowId();
+  if (windowId !== undefined) {
+    engineState.usedWindowIds.add(windowId as number);
+  }
+  const payload: CmdWindowCreateArgs = {
+    windowId: resolvedWindowId as number,
+    title: props.title,
+    size: props.size,
+    position: props.position,
+    canvasId: props.canvasId,
+    borderless: props.borderless ?? false,
+    resizable: props.resizable ?? true,
+    transparent: props.transparent ?? false,
+    initialState: props.initialState ?? 'windowed',
+  };
+  const commandId = enqueueGlobalCommand('cmd-window-create', payload);
+  engineState.pendingWindowCreateByCommandId.set(
+    commandId,
+    resolvedWindowId as number,
+  );
+  return { windowId: resolvedWindowId, commandId: asCommandId(commandId) };
+}
+
+export function closeWindow(windowId: WindowId): CommandId {
+  requireInitialized();
+  const payload: CmdWindowCloseArgs = { windowId: windowId as number };
+  const commandId = enqueueGlobalCommand('cmd-window-close', payload);
+  engineState.pendingWindowCloseByCommandId.set(commandId, windowId as number);
+  return asCommandId(commandId);
+}
+
+/**
+ * Applies partial window updates.
+ *
+ * Depending on the provided fields, this may enqueue up to three commands
+ * (`measurement`, `state`, `cursor`) and returns all resulting command ids.
+ */
+export function updateWindow(windowId: WindowId, props: WindowProps): CommandId[] {
+  requireInitialized();
+  const commandIds: CommandId[] = [];
+
+  if (props.position !== undefined || props.size !== undefined) {
+    commandIds.push(asCommandId(
+      enqueueGlobalCommand('cmd-window-measurement', {
+        windowId: windowId as number,
+        position: props.position,
+        size: props.size,
+      }),
+    ));
+  }
+  if (
+    props.title !== undefined ||
+    props.state !== undefined ||
+    props.resizable !== undefined ||
+    props.decorations !== undefined ||
+    props.icon !== undefined
+  ) {
+    commandIds.push(asCommandId(
+      enqueueGlobalCommand('cmd-window-state', {
+        windowId: windowId as number,
+        title: props.title,
+        state: props.state,
+        resizable: props.resizable,
+        decorations: props.decorations,
+        iconBufferId: props.icon,
+      }),
+    ));
+  }
+  if (
+    props.cursorVisible !== undefined ||
+    props.cursorGrab !== undefined ||
+    props.cursorIcon !== undefined
+  ) {
+    commandIds.push(asCommandId(
+      enqueueGlobalCommand('cmd-window-cursor', {
+        windowId: windowId as number,
+        visible: props.cursorVisible,
+        mode: props.cursorGrab,
+        icon: props.cursorIcon,
+      }),
+    ));
+  }
+
+  return commandIds;
+}
+
+/**
+ * Requests user attention for a window.
+ *
+ * This does not guarantee foreground focus; behavior depends on host platform policy.
+ */
+export function requestAttention(
+  windowId: WindowId,
+  attentionType?: UserAttentionType,
+): CommandId {
+  requireInitialized();
+  return asCommandId(enqueueGlobalCommand('cmd-window-state', {
+    windowId: windowId as number,
+    action: 'request-attention',
+    attentionType,
+  }));
+}
+
+/** Requests input focus for a window. */
+export function focusWindow(windowId: WindowId): CommandId {
+  requireInitialized();
+  return asCommandId(enqueueGlobalCommand('cmd-window-state', {
+    windowId: windowId as number,
+    action: 'focus',
+  }));
+}