@vulfram/engine 0.14.8-alpha → 0.17.1-alpha

package/src/engine/ecs/index.ts

@@ -4,17 +4,35 @@ import type { MaterialOptions } from '../../types/cmds/material';
 import type { ShadowConfig } from '../../types/cmds/shadow';
 import type { ForwardAtlasOptions } from '../../types/cmds/texture';
 import type { EnvironmentConfig } from '../../types/cmds/environment';
+import type { GamepadEvent, SystemEvent, UiEvent } from '../../types/events';
+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 {
   CameraKind,
   LightKind,
   MaterialKind,
   TextureCreateMode,
   NotificationLevel,
-  WindowState,
-  CursorGrabMode,
-  CursorIcon,
-  UserAttentionType,
 } from '../../types/kinds';
+import type { JsonObject, JsonValue } from '../../types/json';
 import type { WorldState } from '../state';
 
 /**
@@ -179,6 +197,91 @@ export interface WindowStateComponent {
   focusChangedThisFrame: boolean;
 }
 
+/**
+ * Gamepad state mirrored from core gamepad events.
+ */
+export interface GamepadStateComponent {
+  type: 'GamepadState';
+  connected: Map<number, { name: string }>;
+  buttons: Map<number, Map<number, { pressed: boolean; value: number }>>;
+  axes: Map<number, Map<number, number>>;
+  eventsThisFrame: GamepadEvent[];
+}
+
+/**
+ * System events mirrored for host-level integrations.
+ */
+export interface SystemEventStateComponent {
+  type: 'SystemEventState';
+  eventsThisFrame: SystemEvent[];
+  lastError?: {
+    scope: string;
+    message: string;
+    commandId?: number;
+    commandType?: string;
+  };
+}
+
+/**
+ * UI events mirrored from core UI event channel.
+ */
+export interface UiEventStateComponent {
+  type: 'UiEventState';
+  eventsThisFrame: UiEvent[];
+}
+
+/**
+ * Focus traversal behavior when reaching first/last input.
+ */
+export type UiFocusCycleMode = 'wrap' | 'clamp';
+
+/**
+ * Form scope state used to control focus traversal.
+ */
+export interface UiFormScope {
+  formId: string;
+  windowId: number;
+  realmId: number;
+  documentId: number;
+  disabled: boolean;
+  cycleMode: UiFocusCycleMode;
+  activeFieldsetId?: string;
+  activeNodeId?: number;
+}
+
+/**
+ * Fieldset scope metadata.
+ */
+export interface UiFieldsetScope {
+  formId: string;
+  fieldsetId: string;
+  disabled: boolean;
+  legendNodeId?: number;
+}
+
+/**
+ * Focusable node metadata for tab ordering.
+ */
+export interface UiFocusableNode {
+  formId: string;
+  nodeId: number;
+  tabIndex: number;
+  fieldsetId?: string;
+  disabled: boolean;
+  orderHint: number;
+}
+
+/**
+ * UI runtime state mirrored in the ECS world.
+ */
+export interface UiStateComponent {
+  type: 'UiState';
+  forms: Map<string, UiFormScope>;
+  fieldsets: Map<string, UiFieldsetScope>;
+  nodes: Map<number, UiFocusableNode>;
+  focusByWindow: Map<number, { formId: string; nodeId: number }>;
+}
+
 /**
  * Resource Properties
  */
@@ -228,6 +331,8 @@ export interface SphereOptions {
 export interface CylinderOptions {
   radius?: number;
   height?: number;
+  sectors?: number;
+  /** @deprecated use `sectors` */
   segments?: number;
 }
 
@@ -237,7 +342,11 @@ export interface CylinderOptions {
 export interface TorusOptions {
   majorRadius?: number;
   minorRadius?: number;
+  majorSegments?: number;
+  minorSegments?: number;
+  /** @deprecated use `majorSegments` */
   radialSegments?: number;
+  /** @deprecated use `minorSegments` */
   tubularSegments?: number;
 }
 
@@ -292,6 +401,10 @@ export type Component =
   | TagComponent
   | InputStateComponent
   | WindowStateComponent
+  | GamepadStateComponent
+  | SystemEventStateComponent
+  | UiEventStateComponent
+  | UiStateComponent
   | CustomComponent;
 
 /**
@@ -302,7 +415,7 @@ export type Component =
  */
 export interface CustomComponent {
   type: string;
-  data: Record<string, unknown>;
+  data: JsonObject;
 }
 
 /**
@@ -335,7 +448,7 @@ export type PropertyType =
  */
 export interface SchemaProperty {
   type: PropertyType;
-  default?: unknown;
+  default?: JsonValue;
   optional?: boolean;
 }
 
@@ -346,36 +459,6 @@ export interface ComponentSchema {
   [key: string]: SchemaProperty;
 }
 
-/**
- * Window update properties.
- */
-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;
-}
-
-/**
- * Window creation properties.
- */
-export interface CreateWindowProps {
-  title: string;
-  size: [number, number];
-  position: [number, number];
-  canvasId?: string;
-  borderless?: boolean;
-  resizable?: boolean;
-  transparent?: boolean;
-  initialState?: WindowState;
-}
-
 /**
  * Intents:
  * Requests to change the state of the World.
@@ -383,11 +466,6 @@ export interface CreateWindowProps {
  */
 
 export type Intent =
-  | { type: 'create-window'; props: CreateWindowProps }
-  | { type: 'close-window' }
-  | { type: 'update-window'; props: WindowProps }
-  | { type: 'request-attention'; attentionType?: UserAttentionType }
-  | { type: 'focus-window' }
   | { type: 'configure-environment'; config: EnvironmentConfig }
   | {
       type: 'request-resource-list';
@@ -453,10 +531,75 @@ export type Intent =
       max: [number, number, number];
       color: [number, number, number, number];
     }
+  | { type: 'ui-theme-define'; args: CmdUiThemeDefineArgs }
+  | { type: 'ui-theme-dispose'; args: CmdUiThemeDisposeArgs }
+  | { type: 'ui-document-create'; args: CmdUiDocumentCreateArgs }
+  | { type: 'ui-document-dispose'; args: CmdUiDocumentDisposeArgs }
+  | { type: 'ui-document-set-rect'; args: CmdUiDocumentSetRectArgs }
+  | { type: 'ui-document-set-theme'; args: CmdUiDocumentSetThemeArgs }
+  | { type: 'ui-document-get-tree'; args: CmdUiDocumentGetTreeArgs }
+  | {
+      type: 'ui-document-get-layout-rects';
+      args: CmdUiDocumentGetLayoutRectsArgs;
+    }
+  | { type: 'ui-apply-ops'; args: CmdUiApplyOpsArgs }
+  | { type: 'ui-debug-set'; args: CmdUiDebugSetArgs }
+  | { type: 'ui-focus-set'; args: CmdUiFocusSetArgs }
+  | { type: 'ui-focus-get'; args: CmdUiFocusGetArgs }
+  | { type: 'ui-event-trace-set'; args: CmdUiEventTraceSetArgs }
+  | { type: 'ui-image-create-from-buffer'; args: CmdUiImageCreateFromBufferArgs }
+  | { type: 'ui-image-dispose'; args: CmdUiImageDisposeArgs }
+  | { type: 'ui-clipboard-paste'; args: CmdUiClipboardPasteArgs }
+  | { type: 'ui-screenshot-reply'; args: CmdUiScreenshotReplyArgs }
+  | {
+      type: 'ui-access-kit-action-request';
+      args: CmdUiAccessKitActionRequestArgs;
+    }
+  | {
+      type: 'ui-form-upsert';
+      form: {
+        formId: string;
+        windowId: number;
+        realmId: number;
+        documentId: number;
+        disabled?: boolean;
+        cycleMode?: UiFocusCycleMode;
+        activeFieldsetId?: string;
+      };
+    }
+  | { type: 'ui-form-dispose'; formId: string }
+  | {
+      type: 'ui-fieldset-upsert';
+      fieldset: {
+        formId: string;
+        fieldsetId: string;
+        disabled?: boolean;
+        legendNodeId?: number;
+      };
+    }
+  | { type: 'ui-fieldset-dispose'; formId: string; fieldsetId: string }
+  | {
+      type: 'ui-focusable-upsert';
+      focusable: {
+        formId: string;
+        nodeId: number;
+        tabIndex?: number;
+        fieldsetId?: string;
+        disabled?: boolean;
+        orderHint?: number;
+      };
+    }
+  | { type: 'ui-focusable-dispose'; nodeId: number }
+  | {
+      type: 'ui-focus-next';
+      windowId: number;
+      backwards?: boolean;
+      formId?: string;
+    }
   | {
       type: 'custom';
       name: string;
-      data: Record<string, unknown>;
+      data: JsonObject;
     };
 
 /**

package/src/engine/state.ts

@@ -1,6 +1,7 @@
 import type { EngineTransport } from '@vulfram/transport-types';
 import type { CommandResponseEnvelope, EngineCmdEnvelope } from '../types/cmds';
 import type { EngineEvent } from '../types/events';
+import type { CmdRealmCreateArgs, RealmKind } from '../types/cmds/realm';
 import type {
   Component,
   ComponentType,
@@ -28,8 +29,78 @@ type ResourceIdCounters = {
   texture: number;
 };
 
+export type RoutingIndex = {
+  dirty: boolean;
+  byWindowId: Map<number, number[]>;
+  byRealmId: Map<number, number[]>;
+  byTargetId: Map<number, number[]>;
+};
+
 export type WorldState = {
-  windowId: number;
+  worldId: number;
+  /**
+   * Realm kind for this world.
+   * `three-d` realms are used by World3D APIs and `two-d` realms by WorldUI APIs.
+   */
+  realmKind: RealmKind;
+  primaryWindowId?: number;
+  boundWindowIds: Set<number>;
+  /**
+   * Latest target-layer binding args keyed by targetId.
+   * Used to keep realm->target binds coherent when cameras are created later.
+   */
+  targetLayerBindings: Map<
+    number,
+    {
+      targetId: number;
+      layout: import('../types/cmds/target').TargetLayerLayout;
+      cameraId?: number;
+      environmentId?: number;
+    }
+  >;
+  /**
+   * Window target ownership keyed by targetId.
+   * Tracks which window a target is currently presenting into for routing purposes.
+   */
+  targetWindowBindings: Map<number, number>;
+  coreRealmId?: number;
+  realmCreateRetryCount: number;
+  nextRealmCreateRetryAtMs: number;
+  realmCreateArgs: CmdRealmCreateArgs;
+  coreSurfaceId?: number;
+  corePresentId?: number;
+  /**
+   * Constraint-solved world matrices keyed by entity id.
+   */
+  resolvedEntityTransforms: Map<number, Float32Array>;
+  /**
+   * Entities explicitly marked as dirty for constraint recomputation.
+   */
+  constraintDirtyEntities: Set<number>;
+  /**
+   * Scratch cache for per-tick constraint solve graph resolution.
+   */
+  constraintScratchResolved: Map<number, Float32Array>;
+  /**
+   * Scratch set used while resolving hierarchy recursion (cycle detection).
+   */
+  constraintScratchVisiting: Set<number>;
+  /**
+   * Entities with resolved matrix changes in the current tick.
+   */
+  constraintChangedEntities: Set<number>;
+  /**
+   * Parent -> children relationship index for hierarchy propagation.
+   */
+  constraintChildrenByParent: Map<number, Set<number>>;
+  /**
+   * Child -> parent relationship index for fast reparent operations.
+   */
+  constraintParentByChild: Map<number, number>;
+  /**
+   * Reusable scratch arrays used when syncing matrices to core.
+   */
+  sceneSyncMatrixScratch: Map<number, number[]>;
   entities: Set<number>;
   /**
    * Components stored by entityId -> componentType -> ComponentData
@@ -50,6 +121,7 @@ export type WorldState = {
    * Will be moved to the engine's global batch during the tick.
    */
   pendingCommands: EngineCmdEnvelope[];
+  pendingCommandsHead: number;
   /**
    * Events routed to this world in the current frame.
    */
@@ -64,17 +136,57 @@ export type EngineState = {
   status: EngineStatus;
   transport: EngineTransport | null;
   worlds: Map<number, WorldState>;
+  nextWorldId: number;
+  nextWindowId: number;
   nextEntityId: number;
   nextCommandId: number;
+  /**
+   * Global ID allocator for core-global resources/objects.
+   * Use for IDs that are not realm-scoped (material/geometry/texture/target/...).
+   */
+  nextGlobalId: number;
   /**
    * Global command batch for the current frame.
    */
   commandBatch: EngineCmdEnvelope[];
+  /**
+   * Tracks reserved window IDs to avoid logical ID collisions for host windows.
+   */
+  usedWindowIds: Set<number>;
+  /**
+   * Pending global commands not scoped to any specific world.
+   */
+  globalPendingCommands: EngineCmdEnvelope[];
+  globalPendingCommandsHead: number;
+  /**
+   * Window IDs confirmed by core `window-create` responses.
+   */
+  confirmedWindowIds: Set<number>;
+  /**
+   * Maps pending window-create command ids to requested window ids.
+   */
+  pendingWindowCreateByCommandId: Map<number, number>;
+  /**
+   * Maps pending window-close command ids to target window ids.
+   */
+  pendingWindowCloseByCommandId: Map<number, number>;
   /**
    * Maps command IDs to the world ID that created them.
    * This is used to route responses back to the correct world.
    */
   commandTracker: Map<number, number>;
+  /**
+   * Tracks global commands (not world-scoped) so their responses are not lost.
+   */
+  globalCommandTracker: Set<number>;
+  /**
+   * Buffered responses for global commands.
+   */
+  globalInboundResponses: CommandResponseEnvelope[];
+  /**
+   * Cached world routing index for event fanout.
+   */
+  routingIndex: RoutingIndex;
   /**
    * Registry for custom components and systems.
    */
@@ -99,8 +211,10 @@ export type EngineState = {
 export const REQUIRED_SYSTEMS = [
   'InputMirrorSystem',
   'CommandIntentSystem',
+  'UiBridgeSystem',
   'ResourceUploadSystem',
-  'CoreCommandBuilderSystem',
+  'ConstraintSolveSystem',
+  'SceneSyncSystem',
   'ResponseDecodeSystem',
   'WorldLifecycleSystem',
   'DiagnosticsSystem',
@@ -110,10 +224,27 @@ export const engineState: EngineState = {
   status: 'uninitialized',
   transport: null,
   worlds: new Map(),
+  nextWorldId: 1,
+  nextWindowId: 1,
   nextEntityId: 1,
   nextCommandId: 1,
+  nextGlobalId: 100,
   commandBatch: [],
+  usedWindowIds: new Set(),
+  globalPendingCommands: [],
+  globalPendingCommandsHead: 0,
+  confirmedWindowIds: new Set(),
+  pendingWindowCreateByCommandId: new Map(),
+  pendingWindowCloseByCommandId: new Map(),
   commandTracker: new Map(),
+  globalCommandTracker: new Set(),
+  globalInboundResponses: [],
+  routingIndex: {
+    dirty: true,
+    byWindowId: new Map(),
+    byRealmId: new Map(),
+    byTargetId: new Map(),
+  },
   registry: {
     components: new Map(),
     systems: {

package/src/engine/systems/command-intent.ts

@@ -5,10 +5,42 @@ import type {
   LightComponent,
   ModelComponent,
   System,
+  TransformComponent,
 } from '../ecs';
+import { toQuat, toVec3 } from './utils';
 
+function wouldCreateParentCycle(
+  world: Parameters<System>[0],
+  childEntityId: number,
+  parentEntityId: number,
+): boolean {
+  let cursor: number | null = parentEntityId;
+  const visited = new Set<number>();
+
+  while (cursor !== null) {
+    if (cursor === childEntityId) {
+      return true;
+    }
+    if (visited.has(cursor)) {
+      return true;
+    }
+    visited.add(cursor);
+
+    const store = world.components.get(cursor);
+    const parent = store?.get('Parent') as { parentId: number } | undefined;
+    cursor = parent?.parentId ?? null;
+  }
+
+  return false;
+}
+
+/**
+ * Applies structural ECS intents that must mutate local world state before
+ * render-time command synthesis (entity lifecycle, tags, parent links, transforms).
+ */
 export const CommandIntentSystem: System = (world, context) => {
   const intentsToRemove: number[] = [];
+  const realmId = world.coreRealmId;
 
   for (let i = 0; i < world.pendingIntents.length; i++) {
     const intent = world.pendingIntents[i];
@@ -32,8 +64,123 @@ export const CommandIntentSystem: System = (world, context) => {
           visible: true,
         });
       }
+      world.constraintDirtyEntities.add(intent.entityId);
+      intentsToRemove.push(i);
+    } else if (intent.type === 'attach-tag') {
+      let store = world.components.get(intent.entityId);
+      if (!store) {
+        store = new Map();
+        world.components.set(intent.entityId, store);
+      }
+      store.set('Tag', {
+        type: 'Tag',
+        name: intent.props.name ?? '',
+        labels: new Set(intent.props.labels ?? []),
+      });
+      intentsToRemove.push(i);
+    } else if (intent.type === 'set-parent') {
+      let store = world.components.get(intent.entityId);
+      if (!store) {
+        store = new Map();
+        world.components.set(intent.entityId, store);
+      }
+      if (intent.parentId === null) {
+        const oldParentId = world.constraintParentByChild.get(intent.entityId);
+        if (oldParentId !== undefined) {
+          const siblings = world.constraintChildrenByParent.get(oldParentId);
+          siblings?.delete(intent.entityId);
+          if (siblings && siblings.size === 0) {
+            world.constraintChildrenByParent.delete(oldParentId);
+          }
+          world.constraintParentByChild.delete(intent.entityId);
+        }
+        store.delete('Parent');
+      } else {
+        if (intent.parentId === intent.entityId) {
+          console.error(
+            `[World ${context.worldId}] Invalid parent constraint: entity ${intent.entityId} cannot parent itself.`,
+          );
+          intentsToRemove.push(i);
+          continue;
+        }
+        if (wouldCreateParentCycle(world, intent.entityId, intent.parentId)) {
+          console.error(
+            `[World ${context.worldId}] Invalid parent constraint: cycle detected for child ${intent.entityId} and parent ${intent.parentId}.`,
+          );
+          intentsToRemove.push(i);
+          continue;
+        }
+        store.set('Parent', {
+          type: 'Parent',
+          parentId: intent.parentId,
+        });
+
+        const oldParentId = world.constraintParentByChild.get(intent.entityId);
+        if (oldParentId !== undefined && oldParentId !== intent.parentId) {
+          const siblings = world.constraintChildrenByParent.get(oldParentId);
+          siblings?.delete(intent.entityId);
+          if (siblings && siblings.size === 0) {
+            world.constraintChildrenByParent.delete(oldParentId);
+          }
+        }
+        world.constraintParentByChild.set(intent.entityId, intent.parentId);
+        let children = world.constraintChildrenByParent.get(intent.parentId);
+        if (!children) {
+          children = new Set();
+          world.constraintChildrenByParent.set(intent.parentId, children);
+        }
+        children.add(intent.entityId);
+      }
+      world.constraintDirtyEntities.add(intent.entityId);
+      intentsToRemove.push(i);
+    } else if (intent.type === 'update-transform') {
+      const store = world.components.get(intent.entityId);
+      if (!store) {
+        continue;
+      }
+      const transform = store.get('Transform') as TransformComponent | undefined;
+      if (!transform) {
+        continue;
+      }
+
+      const nextProps = { ...intent.props };
+      if (nextProps.position) {
+        nextProps.position = toVec3(nextProps.position);
+      }
+      if (nextProps.rotation) {
+        nextProps.rotation = toQuat(nextProps.rotation);
+      }
+      if (nextProps.scale) {
+        nextProps.scale = toVec3(nextProps.scale);
+      }
+      Object.assign(transform, nextProps);
+      world.constraintDirtyEntities.add(intent.entityId);
       intentsToRemove.push(i);
     } else if (intent.type === 'remove-entity') {
+      if (realmId === undefined) continue;
+
+      // Detach all children linked to this entity to keep hierarchy state coherent.
+      const children = world.constraintChildrenByParent.get(intent.entityId);
+      if (children) {
+        for (const childId of children) {
+          const childStore = world.components.get(childId);
+          childStore?.delete('Parent');
+          world.constraintParentByChild.delete(childId);
+          world.constraintDirtyEntities.add(childId);
+        }
+        world.constraintChildrenByParent.delete(intent.entityId);
+      }
+
+      const parentId = world.constraintParentByChild.get(intent.entityId);
+      if (parentId !== undefined) {
+        const siblings = world.constraintChildrenByParent.get(parentId);
+        siblings?.delete(intent.entityId);
+        if (siblings && siblings.size === 0) {
+          world.constraintChildrenByParent.delete(parentId);
+        }
+        world.constraintParentByChild.delete(intent.entityId);
+      }
+
       const store = world.components.get(intent.entityId);
       if (store) {
         // Emit disposal commands for all components with IDs
@@ -42,19 +189,19 @@ export const CommandIntentSystem: System = (world, context) => {
             if (type === 'Model') {
               const modelComp = comp as ModelComponent;
               enqueueCommand(context.worldId, 'cmd-model-dispose', {
-                windowId: context.worldId,
+                realmId,
                 modelId: modelComp.id,
               });
             } else if (type === 'Camera') {
               const cameraComp = comp as CameraComponent;
               enqueueCommand(context.worldId, 'cmd-camera-dispose', {
-                windowId: context.worldId,
+                realmId,
                 cameraId: cameraComp.id,
               });
             } else if (type === 'Light') {
               const lightComp = comp as LightComponent;
               enqueueCommand(context.worldId, 'cmd-light-dispose', {
-                windowId: context.worldId,
+                realmId,
                 lightId: lightComp.id,
               });
             }
@@ -63,6 +210,9 @@ export const CommandIntentSystem: System = (world, context) => {
         world.components.delete(intent.entityId);
       }
       world.entities.delete(intent.entityId);
+      world.resolvedEntityTransforms.delete(intent.entityId);
+      world.sceneSyncMatrixScratch.delete(intent.entityId);
+      world.constraintDirtyEntities.add(intent.entityId);
       intentsToRemove.push(i);
     }
   }