@vulfram/engine 0.14.8-alpha → 0.17.1-alpha

package/src/engine/systems/ui-bridge.ts

@@ -0,0 +1,360 @@
+import { KeyCode } from '../../types/events/keyboard';
+import { enqueueCommand } from '../bridge/dispatch';
+import type {
+  InputStateComponent,
+  Intent,
+  System,
+  UiFieldsetScope,
+  UiFocusableNode,
+  UiFormScope,
+  UiStateComponent,
+} from '../ecs';
+
+const WORLD_ENTITY_ID = 0;
+
+function ensureUiState(world: Parameters<System>[0]): UiStateComponent {
+  let worldStore = world.components.get(WORLD_ENTITY_ID);
+  if (!worldStore) {
+    worldStore = new Map();
+    world.components.set(WORLD_ENTITY_ID, worldStore);
+    world.entities.add(WORLD_ENTITY_ID);
+  }
+
+  let uiState = worldStore.get('UiState') as UiStateComponent | undefined;
+  if (!uiState) {
+    uiState = {
+      type: 'UiState',
+      forms: new Map(),
+      fieldsets: new Map(),
+      nodes: new Map(),
+      focusByWindow: new Map(),
+    };
+    worldStore.set('UiState', uiState);
+  }
+
+  return uiState;
+}
+
+function getInputState(world: Parameters<System>[0]): InputStateComponent | undefined {
+  const worldStore = world.components.get(WORLD_ENTITY_ID);
+  return worldStore?.get('InputState') as InputStateComponent | undefined;
+}
+
+function fieldsetKey(formId: string, fieldsetId: string): string {
+  return `${formId}::${fieldsetId}`;
+}
+
+function canFocusNode(
+  form: UiFormScope,
+  node: UiFocusableNode,
+  fieldsets: Map<string, UiFieldsetScope>,
+): boolean {
+  if (form.disabled || node.disabled || node.tabIndex < 0) {
+    return false;
+  }
+
+  if (form.activeFieldsetId && node.fieldsetId !== form.activeFieldsetId) {
+    return false;
+  }
+
+  if (node.fieldsetId) {
+    const fieldset = fieldsets.get(fieldsetKey(form.formId, node.fieldsetId));
+    if (fieldset?.disabled && fieldset.legendNodeId !== node.nodeId) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function sortFocusables(a: UiFocusableNode, b: UiFocusableNode): number {
+  const aPositive = a.tabIndex > 0;
+  const bPositive = b.tabIndex > 0;
+  if (aPositive !== bPositive) return aPositive ? -1 : 1;
+
+  if (aPositive && bPositive && a.tabIndex !== b.tabIndex) {
+    return a.tabIndex - b.tabIndex;
+  }
+
+  if (a.orderHint !== b.orderHint) {
+    return a.orderHint - b.orderHint;
+  }
+
+  return a.nodeId - b.nodeId;
+}
+
+function resolveTargetForm(
+  uiState: UiStateComponent,
+  windowId: number,
+  formId?: string,
+): UiFormScope | undefined {
+  if (formId) {
+    const form = uiState.forms.get(formId);
+    if (form && form.windowId === windowId && !form.disabled) {
+      return form;
+    }
+  }
+
+  const focused = uiState.focusByWindow.get(windowId);
+  if (focused) {
+    const form = uiState.forms.get(focused.formId);
+    if (form && !form.disabled) {
+      return form;
+    }
+  }
+
+  const forms = Array.from(uiState.forms.values())
+    .filter((f) => f.windowId === windowId && !f.disabled)
+    .sort((a, b) => a.formId.localeCompare(b.formId));
+
+  return forms[0];
+}
+
+function resolveNextNode(
+  uiState: UiStateComponent,
+  windowId: number,
+  backwards: boolean,
+  formId?: string,
+): { form: UiFormScope; nodeId: number } | null {
+  const form = resolveTargetForm(uiState, windowId, formId);
+  if (!form) return null;
+
+  const candidates = Array.from(uiState.nodes.values())
+    .filter((node) => node.formId === form.formId)
+    .filter((node) => canFocusNode(form, node, uiState.fieldsets))
+    .sort(sortFocusables);
+
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  const focused = uiState.focusByWindow.get(windowId);
+  const activeNodeId =
+    focused?.formId === form.formId ? focused.nodeId : form.activeNodeId;
+  const currentIndex = candidates.findIndex((node) => node.nodeId === activeNodeId);
+
+  let nextIndex = currentIndex;
+  if (currentIndex < 0) {
+    nextIndex = backwards ? candidates.length - 1 : 0;
+  } else {
+    nextIndex = backwards ? currentIndex - 1 : currentIndex + 1;
+  }
+
+  const cycleMode = form.cycleMode;
+  if (nextIndex < 0 || nextIndex >= candidates.length) {
+    if (cycleMode === 'clamp') {
+      return null;
+    }
+    nextIndex = nextIndex < 0 ? candidates.length - 1 : 0;
+  }
+
+  const target = candidates[nextIndex];
+  if (!target) return null;
+  return { form, nodeId: target.nodeId };
+}
+
+function applyFocus(uiState: UiStateComponent, windowId: number, formId: string, nodeId: number): void {
+  uiState.focusByWindow.set(windowId, { formId, nodeId });
+  const form = uiState.forms.get(formId);
+  if (form) {
+    form.activeNodeId = nodeId;
+  }
+}
+
+function processUiIntent(
+  worldId: number,
+  uiState: UiStateComponent,
+  intent: Intent,
+): boolean {
+  switch (intent.type) {
+    case 'ui-theme-define':
+      enqueueCommand(worldId, 'cmd-ui-theme-define', intent.args);
+      return true;
+    case 'ui-theme-dispose':
+      enqueueCommand(worldId, 'cmd-ui-theme-dispose', intent.args);
+      return true;
+    case 'ui-document-create':
+      enqueueCommand(worldId, 'cmd-ui-document-create', intent.args);
+      return true;
+    case 'ui-document-dispose':
+      enqueueCommand(worldId, 'cmd-ui-document-dispose', intent.args);
+      return true;
+    case 'ui-document-set-rect':
+      enqueueCommand(worldId, 'cmd-ui-document-set-rect', intent.args);
+      return true;
+    case 'ui-document-set-theme':
+      enqueueCommand(worldId, 'cmd-ui-document-set-theme', intent.args);
+      return true;
+    case 'ui-document-get-tree':
+      enqueueCommand(worldId, 'cmd-ui-document-get-tree', intent.args);
+      return true;
+    case 'ui-document-get-layout-rects':
+      enqueueCommand(worldId, 'cmd-ui-document-get-layout-rects', intent.args);
+      return true;
+    case 'ui-apply-ops':
+      enqueueCommand(worldId, 'cmd-ui-apply-ops', intent.args);
+      return true;
+    case 'ui-debug-set':
+      enqueueCommand(worldId, 'cmd-ui-debug-set', intent.args);
+      return true;
+    case 'ui-focus-set': {
+      enqueueCommand(worldId, 'cmd-ui-focus-set', intent.args);
+      const form = resolveTargetForm(uiState, intent.args.windowId);
+      if (form && form.realmId === intent.args.realmId && form.documentId === intent.args.documentId) {
+        applyFocus(uiState, intent.args.windowId, form.formId, intent.args.nodeId ?? 0);
+      }
+      return true;
+    }
+    case 'ui-focus-get':
+      enqueueCommand(worldId, 'cmd-ui-focus-get', intent.args);
+      return true;
+    case 'ui-event-trace-set':
+      enqueueCommand(worldId, 'cmd-ui-event-trace-set', intent.args);
+      return true;
+    case 'ui-image-create-from-buffer':
+      enqueueCommand(worldId, 'cmd-ui-image-create-from-buffer', intent.args);
+      return true;
+    case 'ui-image-dispose':
+      enqueueCommand(worldId, 'cmd-ui-image-dispose', intent.args);
+      return true;
+    case 'ui-clipboard-paste':
+      enqueueCommand(worldId, 'cmd-ui-clipboard-paste', intent.args);
+      return true;
+    case 'ui-screenshot-reply':
+      enqueueCommand(worldId, 'cmd-ui-screenshot-reply', intent.args);
+      return true;
+    case 'ui-access-kit-action-request':
+      enqueueCommand(worldId, 'cmd-ui-access-kit-action-request', intent.args);
+      return true;
+    case 'ui-form-upsert': {
+      const existing = uiState.forms.get(intent.form.formId);
+      uiState.forms.set(intent.form.formId, {
+        formId: intent.form.formId,
+        windowId: intent.form.windowId,
+        realmId: intent.form.realmId,
+        documentId: intent.form.documentId,
+        disabled: intent.form.disabled ?? false,
+        cycleMode: intent.form.cycleMode ?? 'wrap',
+        activeFieldsetId: intent.form.activeFieldsetId,
+        activeNodeId: existing?.activeNodeId,
+      });
+      return true;
+    }
+    case 'ui-form-dispose': {
+      uiState.forms.delete(intent.formId);
+      for (const [key, fieldset] of uiState.fieldsets) {
+        if (fieldset.formId === intent.formId) {
+          uiState.fieldsets.delete(key);
+        }
+      }
+      for (const [nodeId, node] of uiState.nodes) {
+        if (node.formId === intent.formId) {
+          uiState.nodes.delete(nodeId);
+        }
+      }
+      for (const [windowId, focus] of uiState.focusByWindow) {
+        if (focus.formId === intent.formId) {
+          uiState.focusByWindow.delete(windowId);
+        }
+      }
+      return true;
+    }
+    case 'ui-fieldset-upsert': {
+      uiState.fieldsets.set(fieldsetKey(intent.fieldset.formId, intent.fieldset.fieldsetId), {
+        formId: intent.fieldset.formId,
+        fieldsetId: intent.fieldset.fieldsetId,
+        disabled: intent.fieldset.disabled ?? false,
+        legendNodeId: intent.fieldset.legendNodeId,
+      });
+      return true;
+    }
+    case 'ui-fieldset-dispose':
+      uiState.fieldsets.delete(fieldsetKey(intent.formId, intent.fieldsetId));
+      return true;
+    case 'ui-focusable-upsert':
+      uiState.nodes.set(intent.focusable.nodeId, {
+        formId: intent.focusable.formId,
+        nodeId: intent.focusable.nodeId,
+        tabIndex: intent.focusable.tabIndex ?? 0,
+        fieldsetId: intent.focusable.fieldsetId,
+        disabled: intent.focusable.disabled ?? false,
+        orderHint: intent.focusable.orderHint ?? intent.focusable.nodeId,
+      });
+      return true;
+    case 'ui-focusable-dispose':
+      uiState.nodes.delete(intent.nodeId);
+      return true;
+    case 'ui-focus-next': {
+      const next = resolveNextNode(
+        uiState,
+        intent.windowId,
+        intent.backwards ?? false,
+        intent.formId,
+      );
+      if (!next) return true;
+
+      enqueueCommand(worldId, 'cmd-ui-focus-set', {
+        windowId: next.form.windowId,
+        realmId: next.form.realmId,
+        documentId: next.form.documentId,
+        nodeId: next.nodeId,
+      });
+      applyFocus(uiState, next.form.windowId, next.form.formId, next.nodeId);
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * Bridges UI-oriented intents into core UI commands and maintains focus state.
+ *
+ * It also provides default keyboard Tab navigation when explicit
+ * `ui-focus-next` intents are not emitted by the application.
+ */
+export const UiBridgeSystem: System = (world, context) => {
+  const uiState = ensureUiState(world);
+  const intentsToRemove: number[] = [];
+  let explicitFocusNavigation = false;
+
+  for (let i = 0; i < world.pendingIntents.length; i++) {
+    const intent = world.pendingIntents[i];
+    if (!intent) continue;
+
+    if (intent.type === 'ui-focus-next') {
+      explicitFocusNavigation = true;
+    }
+
+    if (processUiIntent(context.worldId, uiState, intent)) {
+      intentsToRemove.push(i);
+    }
+  }
+
+  if (!explicitFocusNavigation) {
+    const inputState = getInputState(world);
+    if (inputState?.keysJustPressed.has(KeyCode.Tab)) {
+      const backwards =
+        inputState.keysPressed.has(KeyCode.ShiftLeft) ||
+        inputState.keysPressed.has(KeyCode.ShiftRight);
+      const focusWindowId = world.primaryWindowId;
+      if (focusWindowId !== undefined) {
+        const next = resolveNextNode(uiState, focusWindowId, backwards);
+        if (next) {
+          enqueueCommand(context.worldId, 'cmd-ui-focus-set', {
+            windowId: next.form.windowId,
+            realmId: next.form.realmId,
+            documentId: next.form.documentId,
+            nodeId: next.nodeId,
+          });
+          applyFocus(uiState, next.form.windowId, next.form.formId, next.nodeId);
+        }
+      }
+    }
+  }
+
+  for (let i = intentsToRemove.length - 1; i >= 0; i--) {
+    const idx = intentsToRemove[i];
+    if (idx !== undefined) world.pendingIntents.splice(idx, 1);
+  }
+};

package/src/engine/systems/utils.ts

@@ -9,6 +9,7 @@ import type {
 import type { TransformComponent } from '../ecs';
 import type { WorldState } from '../state';
 
+/** Converts array-like numeric values into a fixed-length tuple buffer. */
 export function toTuple(value: ArrayLike<number>, length: number): number[] {
   const result = new Array<number>(length);
   for (let i = 0; i < length; i++) {
@@ -17,16 +18,19 @@ export function toTuple(value: ArrayLike<number>, length: number): number[] {
   return result;
 }
 
+/** Normalizes arbitrary 2D vector input to a strict tuple. */
 export function toVec2(value: ArrayLike<number>): [number, number] {
   const result = toTuple(value, 2);
   return [result[0] ?? 0, result[1] ?? 0];
 }
 
+/** Normalizes arbitrary 3D vector input to a strict tuple. */
 export function toVec3(value: ArrayLike<number>): [number, number, number] {
   const result = toTuple(value, 3);
   return [result[0] ?? 0, result[1] ?? 0, result[2] ?? 0];
 }
 
+/** Normalizes arbitrary 4D vector input to a strict tuple. */
 export function toVec4(value: ArrayLike<number>): [number, number, number, number] {
   const result = toTuple(value, 4);
   return [
@@ -37,10 +41,12 @@ export function toVec4(value: ArrayLike<number>): [number, number, number, numbe
   ];
 }
 
+/** Normalizes arbitrary quaternion-like input to a strict `[x, y, z, w]` tuple. */
 export function toQuat(value: ArrayLike<number>): [number, number, number, number] {
   return toVec4(value);
 }
 
+/** Normalizes standard-material option payload for command serialization. */
 export function normalizeStandardOptions(options: StandardOptions): StandardOptions {
   const normalized: StandardOptions = {
     ...options,
@@ -56,6 +62,7 @@ export function normalizeStandardOptions(options: StandardOptions): StandardOpti
   return normalized;
 }
 
+/** Normalizes PBR-material option payload for command serialization. */
 export function normalizePbrOptions(options: PbrOptions): PbrOptions {
   return {
     ...options,
@@ -64,6 +71,7 @@ export function normalizePbrOptions(options: PbrOptions): PbrOptions {
   };
 }
 
+/** Normalizes polymorphic material options into strict tuple-backed values. */
 export function normalizeMaterialOptions(
   options: MaterialOptions | undefined,
 ): MaterialOptions | undefined {
@@ -80,6 +88,7 @@ export function normalizeMaterialOptions(
   };
 }
 
+/** Normalizes primitive options that contain vector payloads. */
 export function normalizePrimitiveOptions(options: PrimitiveOptions): PrimitiveOptions {
   if (options.type === 'cube') {
     const content = options.content as CubeOptions;
@@ -114,7 +123,11 @@ export function normalizePrimitiveOptions(options: PrimitiveOptions): PrimitiveO
   return options;
 }
 
-export function getEntityTransformMatrix(
+/**
+ * Resolves the local transform matrix for an entity, without applying constraints
+ * (for example parent hierarchy composition).
+ */
+export function getEntityLocalTransformMatrix(
   world: WorldState,
   entityId: number,
 ): mat4 {
@@ -145,3 +158,32 @@ export function getEntityTransformMatrix(
   }
   return m;
 }
+
+/**
+ * Returns the latest constraint-resolved world matrix for an entity.
+ * Falls back to local transform when no resolved matrix is cached yet.
+ */
+export function getResolvedEntityTransformMatrix(
+  world: WorldState,
+  entityId: number,
+): mat4 {
+  const resolved = world.resolvedEntityTransforms.get(entityId);
+  if (!resolved) {
+    return getEntityLocalTransformMatrix(world, entityId);
+  }
+  return mat4.clone(resolved);
+}
+
+/** Compares 4x4 matrices using an absolute epsilon per component. */
+export function mat4EqualsApprox(
+  a: ArrayLike<number>,
+  b: ArrayLike<number>,
+  epsilon = 1e-6,
+): boolean {
+  for (let i = 0; i < 16; i++) {
+    if (Math.abs((a[i] ?? 0) - (b[i] ?? 0)) > epsilon) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/engine/systems/world-lifecycle.ts

@@ -1,10 +1,17 @@
 import type { EnvironmentConfig } from '../../types/cmds/environment';
 import type { ShadowConfig } from '../../types/cmds/shadow';
-import type { WindowState } from '../../types/kinds';
 import { enqueueCommand } from '../bridge/dispatch';
 import type { System } from '../ecs';
-import { toVec2, toVec3 } from './utils';
+import { toVec3, toVec4 } from './utils';
 
+/**
+ * Applies world-scoped lifecycle/configuration intents.
+ *
+ * Covered intents:
+ * - environment configuration
+ * - shadow configuration
+ * - notification dispatch
+ */
 export const WorldLifecycleSystem: System = (world, context) => {
   const intentsToRemove: number[] = [];
 
@@ -12,103 +19,7 @@ export const WorldLifecycleSystem: System = (world, context) => {
     const intent = world.pendingIntents[i];
     if (!intent) continue;
 
-    if (intent.type === 'create-window') {
-      const cmd = {
-        windowId: context.worldId,
-        title: intent.props.title,
-        size: toVec2(intent.props.size),
-        position: toVec2(intent.props.position),
-        borderless: intent.props.borderless ?? false,
-        resizable: intent.props.resizable ?? true,
-        transparent: intent.props.transparent ?? false,
-        initialState: intent.props.initialState ?? ('windowed' as WindowState),
-      } as const;
-      const payload: typeof cmd & { canvasId?: string } = { ...cmd };
-      if (intent.props.canvasId !== undefined) {
-        payload.canvasId = intent.props.canvasId;
-      }
-      enqueueCommand(context.worldId, 'cmd-window-create', payload);
-      intentsToRemove.push(i);
-    } else if (intent.type === 'close-window') {
-      enqueueCommand(context.worldId, 'cmd-window-close', {
-        windowId: context.worldId,
-      });
-      intentsToRemove.push(i);
-    } else if (intent.type === 'update-window') {
-      const p = intent.props;
-      if (p.title !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-title', {
-          windowId: context.worldId,
-          title: p.title,
-        });
-      }
-      if (p.position !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-position', {
-          windowId: context.worldId,
-          position: p.position,
-        });
-      }
-      if (p.size !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-size', {
-          windowId: context.worldId,
-          size: p.size,
-        });
-      }
-      if (p.state !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-state', {
-          windowId: context.worldId,
-          state: p.state,
-        });
-      }
-      if (p.resizable !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-resizable', {
-          windowId: context.worldId,
-          resizable: p.resizable,
-        });
-      }
-      if (p.decorations !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-decorations', {
-          windowId: context.worldId,
-          decorations: p.decorations,
-        });
-      }
-      if (p.cursorVisible !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-cursor-visible', {
-          windowId: context.worldId,
-          visible: p.cursorVisible,
-        });
-      }
-      if (p.cursorGrab !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-cursor-grab', {
-          windowId: context.worldId,
-          mode: p.cursorGrab,
-        });
-      }
-      if (p.icon !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-icon', {
-          windowId: context.worldId,
-          bufferId: p.icon,
-        });
-      }
-      if (p.cursorIcon !== undefined) {
-        enqueueCommand(context.worldId, 'cmd-window-set-cursor-icon', {
-          windowId: context.worldId,
-          icon: p.cursorIcon,
-        });
-      }
-      intentsToRemove.push(i);
-    } else if (intent.type === 'request-attention') {
-      enqueueCommand(context.worldId, 'cmd-window-request-attention', {
-        windowId: context.worldId,
-        attentionType: intent.attentionType,
-      });
-      intentsToRemove.push(i);
-    } else if (intent.type === 'focus-window') {
-      enqueueCommand(context.worldId, 'cmd-window-focus', {
-        windowId: context.worldId,
-      });
-      intentsToRemove.push(i);
-    } else if (intent.type === 'configure-environment') {
+    if (intent.type === 'configure-environment') {
       const config = intent.config as EnvironmentConfig;
       const payload: EnvironmentConfig = {
         msaa: {
@@ -124,6 +35,7 @@ export const WorldLifecycleSystem: System = (world, context) => {
           skyColor: toVec3(config.skybox.skyColor),
           cubemapTextureId: config.skybox.cubemapTextureId ?? null,
         },
+        clearColor: toVec4(config.clearColor ?? [0, 0, 0, 0]),
         post: {
           filterEnabled: config.post.filterEnabled,
           filterExposure: config.post.filterExposure,
@@ -157,12 +69,35 @@ export const WorldLifecycleSystem: System = (world, context) => {
           bloomScatter: config.post.bloomScatter,
         },
       };
-      enqueueCommand(context.worldId, 'cmd-environment-update', {
-        windowId: context.worldId,
+      enqueueCommand(context.worldId, 'cmd-environment-upsert', {
+        environmentId: context.worldId,
         config: payload,
       });
+      // Keep current realm->target bindings synchronized with this environment.
+      for (const binding of world.targetLayerBindings.values()) {
+        binding.environmentId = context.worldId;
+        if (world.coreRealmId === undefined) continue;
+        enqueueCommand(context.worldId, 'cmd-target-layer-upsert', {
+          realmId: world.coreRealmId,
+          targetId: binding.targetId,
+          layout: binding.layout,
+          cameraId: binding.cameraId,
+          environmentId: context.worldId,
+        });
+      }
       intentsToRemove.push(i);
     } else if (intent.type === 'configure-shadows') {
+      let windowId = world.primaryWindowId;
+      if (windowId === undefined) {
+        for (const boundWindowId of world.targetWindowBindings.values()) {
+          windowId = boundWindowId;
+          break;
+        }
+      }
+      if (windowId === undefined) {
+        windowId = world.realmCreateArgs.hostWindowId;
+      }
+      if (windowId === undefined) continue;
       const c = intent.config || {};
       const config: ShadowConfig = {
         tileResolution: c.tileResolution ?? 1024,
@@ -174,7 +109,7 @@ export const WorldLifecycleSystem: System = (world, context) => {
         normalBias: c.normalBias ?? 0.01,
       };
       enqueueCommand(context.worldId, 'cmd-shadow-configure', {
-        windowId: context.worldId,
+        windowId,
         config,
       });
       intentsToRemove.push(i);