@vulfram/engine 0.14.8-alpha → 0.17.1-alpha

package/src/engine/bridge/dispatch.ts

@@ -1,5 +1,6 @@
 import type { CommandResponseEnvelope, EngineCmd } from '../../types/cmds';
 import type { EngineEvent } from '../../types/events';
+import { EngineError } from '../errors';
 import { engineState } from '../state';
 import { getWorldOrThrow, requireInitialized } from './guards';
 
@@ -7,6 +8,60 @@ import { getWorldOrThrow, requireInitialized } from './guards';
  * Limits for Backpressure management.
  */
 const MAX_BATCH_COMMANDS = 2048;
+const MAX_BATCH_ESTIMATED_BYTES = 60 * 1024;
+
+function estimateSerializedBytes(value: unknown): number {
+  if (value === null || value === undefined) return 1;
+  const valueType = typeof value;
+  if (valueType === 'boolean') return 1;
+  if (valueType === 'number') return 8;
+  if (valueType === 'string') return 2 + (value as string).length * 2;
+  if (ArrayBuffer.isView(value)) return (value as ArrayBufferView).byteLength + 8;
+  if (value instanceof ArrayBuffer) return value.byteLength + 8;
+
+  if (Array.isArray(value)) {
+    let total = 8;
+    for (let i = 0; i < value.length; i++) {
+      total += estimateSerializedBytes(value[i]);
+    }
+    return total;
+  }
+
+  if (valueType === 'object') {
+    const record = value as Record<string, unknown>;
+    let total = 8;
+    for (const [key, nested] of Object.entries(record)) {
+      if (nested === undefined) continue;
+      total += 2 + key.length * 2;
+      total += estimateSerializedBytes(nested);
+    }
+    return total;
+  }
+
+  return 4;
+}
+
+function estimateEnvelopeBytes(envelope: { id: number; type: string; content: unknown }): number {
+  return 24 + envelope.type.length * 2 + estimateSerializedBytes(envelope.content);
+}
+
+function maybeCompactQueue<T>(queue: T[], head: number): number {
+  if (head <= 0) return head;
+  if (head === queue.length) {
+    queue.length = 0;
+    return 0;
+  }
+  if (head >= 1024 && head * 2 >= queue.length) {
+    queue.copyWithin(0, head);
+    queue.length -= head;
+    return 0;
+  }
+  return head;
+}
+
+export function markRoutingIndexDirty(): void {
+  engineState.routingIndex.dirty = true;
+}
 
 /**
  * Enqueues a command to be sent to the core in the next tick.
@@ -21,13 +76,49 @@ export function enqueueCommand<T extends EngineCmd['type']>(
   const world = getWorldOrThrow(worldId);
   const id = engineState.nextCommandId++;
 
-  // Contract: windowId must match worldId (windowId) if present in content
-  const typedContent = content as Record<string, unknown>;
-  if ('windowId' in typedContent) {
-    typedContent.windowId = world.windowId;
+  // Contract: realmId resolves from world core realm; windowId may default to primary binding.
+  const typedContent = {
+    ...(content as Record<string, unknown>),
+  } as Record<string, unknown>;
+  if (
+    'windowId' in typedContent &&
+    typedContent.windowId == null &&
+    world.primaryWindowId !== undefined
+  ) {
+    typedContent.windowId = world.primaryWindowId;
+  }
+  if ('realmId' in typedContent && typedContent.realmId == null) {
+    if (world.coreRealmId === undefined) {
+      throw new EngineError(
+        'WorldNotReady',
+        `World ${worldId} realm is not ready yet. Wait for at least one tick after createWorld.`,
+      );
+    }
+    typedContent.realmId = world.coreRealmId;
   }
 
-  world.pendingCommands.push({ id, type, content });
+  world.pendingCommands.push({
+    id,
+    type,
+    content: typedContent as unknown as Extract<
+      EngineCmd,
+      { type: T }
+    >['content'],
+  });
+  return id;
+}
+
+/**
+ * Enqueues a command not scoped to a specific world (window management, etc).
+ */
+export function enqueueGlobalCommand<T extends EngineCmd['type']>(
+  type: T,
+  content: Extract<EngineCmd, { type: T }>['content'],
+): number {
+  requireInitialized();
+  const id = engineState.nextCommandId++;
+  engineState.globalCommandTracker.add(id);
+  engineState.globalPendingCommands.push({ id, type, content });
   return id;
 }
 
@@ -37,63 +128,192 @@ export function enqueueCommand<T extends EngineCmd['type']>(
  */
 export function collectCommands(): void {
   let collectedCount = 0;
+  let collectedBytes = 0;
+
+  const globalAvailable =
+    engineState.globalPendingCommands.length - engineState.globalPendingCommandsHead;
+  if (globalAvailable > 0) {
+    const start = engineState.globalPendingCommandsHead;
+    let end = start;
+    while (
+      end < engineState.globalPendingCommands.length &&
+      collectedCount < MAX_BATCH_COMMANDS &&
+      collectedBytes < MAX_BATCH_ESTIMATED_BYTES
+    ) {
+      const cmd = engineState.globalPendingCommands[end]!;
+      const estimateBytes = estimateEnvelopeBytes(cmd);
+      if (collectedBytes > 0 && collectedBytes + estimateBytes > MAX_BATCH_ESTIMATED_BYTES) {
+        break;
+      }
+      engineState.commandBatch.push(cmd);
+      collectedBytes += estimateBytes;
+      collectedCount++;
+      end++;
+    }
+    engineState.globalPendingCommandsHead = end;
+    engineState.globalPendingCommandsHead = maybeCompactQueue(
+      engineState.globalPendingCommands,
+      engineState.globalPendingCommandsHead,
+    );
+  }
 
   for (const [worldId, world] of engineState.worlds) {
-    if (collectedCount >= MAX_BATCH_COMMANDS) {
+    if (
+      collectedCount >= MAX_BATCH_COMMANDS ||
+      collectedBytes >= MAX_BATCH_ESTIMATED_BYTES
+    ) {
       // Backpressure: If we reached the limit, stop collecting for this frame.
       // Remaining commands will wait for the next frame.
       break;
     }
 
-    if (world.pendingCommands.length > 0) {
-      // Determine how many we can take from this world
-      const remainingSpace = MAX_BATCH_COMMANDS - collectedCount;
-      const amountToTake = Math.min(
-        world.pendingCommands.length,
-        remainingSpace,
-      );
-
-      const cmdsToPush = world.pendingCommands.splice(0, amountToTake);
-      for (const cmd of cmdsToPush) {
+    const worldAvailable = world.pendingCommands.length - world.pendingCommandsHead;
+    if (worldAvailable > 0) {
+      const start = world.pendingCommandsHead;
+      let end = start;
+      while (
+        end < world.pendingCommands.length &&
+        collectedCount < MAX_BATCH_COMMANDS &&
+        collectedBytes < MAX_BATCH_ESTIMATED_BYTES
+      ) {
+        const cmd = world.pendingCommands[end]!;
+        const estimateBytes = estimateEnvelopeBytes(cmd);
+        if (collectedBytes > 0 && collectedBytes + estimateBytes > MAX_BATCH_ESTIMATED_BYTES) {
+          break;
+        }
         engineState.commandBatch.push(cmd);
         engineState.commandTracker.set(cmd.id, worldId);
+        collectedBytes += estimateBytes;
+        collectedCount++;
+        end++;
       }
-      collectedCount += amountToTake;
+      world.pendingCommandsHead = end;
+      world.pendingCommandsHead = maybeCompactQueue(
+        world.pendingCommands,
+        world.pendingCommandsHead,
+      );
+    }
+  }
+}
+
+function ensureRoutingIndex(): void {
+  if (!engineState.routingIndex.dirty) return;
+
+  const byWindowId = new Map<number, number[]>();
+  const byRealmId = new Map<number, number[]>();
+  const byTargetId = new Map<number, number[]>();
+
+  for (const [worldId, world] of engineState.worlds) {
+    for (const boundWindowId of world.boundWindowIds) {
+      const ids = byWindowId.get(boundWindowId);
+      if (ids) ids.push(worldId);
+      else byWindowId.set(boundWindowId, [worldId]);
+    }
+
+    if (typeof world.coreRealmId === 'number') {
+      const ids = byRealmId.get(world.coreRealmId);
+      if (ids) ids.push(worldId);
+      else byRealmId.set(world.coreRealmId, [worldId]);
+    }
+
+    for (const targetId of world.targetLayerBindings.keys()) {
+      const ids = byTargetId.get(targetId);
+      if (ids) ids.push(worldId);
+      else byTargetId.set(targetId, [worldId]);
     }
   }
+
+  engineState.routingIndex.byWindowId = byWindowId;
+  engineState.routingIndex.byRealmId = byRealmId;
+  engineState.routingIndex.byTargetId = byTargetId;
+  engineState.routingIndex.dirty = false;
+}
+
+function extractEventScopeIds(event: EngineEvent): {
+  windowId?: number;
+  realmId?: number;
+  targetId?: number;
+} {
+  const content = event.content as
+    | { data?: Record<string, unknown> }
+    | Record<string, unknown>;
+  const scopedDataCandidate =
+    'data' in content && content.data && typeof content.data === 'object'
+      ? content.data
+      : content;
+
+  if (!scopedDataCandidate || typeof scopedDataCandidate !== 'object') {
+    return {};
+  }
+  const scopedData = scopedDataCandidate as Record<string, unknown>;
+
+  const windowId =
+    typeof scopedData.windowId === 'number' ? scopedData.windowId : undefined;
+  const realmId =
+    typeof scopedData.realmId === 'number' ? scopedData.realmId : undefined;
+  const targetId =
+    typeof scopedData.targetId === 'number' ? scopedData.targetId : undefined;
+
+  return { windowId, realmId, targetId };
 }
 
 /**
  * Routes core events to their respective worlds based on windowId.
  */
 export function routeEvents(events: EngineEvent[]): void {
+  ensureRoutingIndex();
+  const worldsByWindowId = engineState.routingIndex.byWindowId;
+  const worldsByRealmId = engineState.routingIndex.byRealmId;
+  const worldsByTargetId = engineState.routingIndex.byTargetId;
+
   for (const event of events) {
-    // Determine windowId from event content
-    // Events have structure: { type, content: { event, data: { windowId, ... } } }
-    let windowId: number | undefined;
-
-    if ('data' in event.content && event.content.data) {
-      const eventData = event.content.data as unknown as Record<
-        string,
-        unknown
-      >;
-      windowId =
-        typeof eventData.windowId === 'number' ? eventData.windowId : undefined;
-    } else if ('windowId' in event.content) {
-      const eventContent = event.content as Record<string, unknown>;
-      windowId =
-        typeof eventContent.windowId === 'number'
-          ? eventContent.windowId
-          : undefined;
-    }
+    const { windowId, realmId, targetId } = extractEventScopeIds(event);
 
     if (windowId !== undefined) {
-      const world = engineState.worlds.get(windowId);
-      if (world) {
-        world.inboundEvents.push(event);
+      const worldIds = worldsByWindowId.get(windowId);
+      if (!worldIds) {
+        continue;
       }
-    } else {
-      // Global events (if any) could be handled here
+      for (let i = 0; i < worldIds.length; i++) {
+        const world = engineState.worlds.get(worldIds[i]!);
+        if (world) {
+          world.inboundEvents.push(event);
+        }
+      }
+      continue;
+    }
+
+    if (realmId !== undefined) {
+      const worldIds = worldsByRealmId.get(realmId);
+      if (!worldIds) {
+        continue;
+      }
+      for (let i = 0; i < worldIds.length; i++) {
+        const world = engineState.worlds.get(worldIds[i]!);
+        if (world) {
+          world.inboundEvents.push(event);
+        }
+      }
+      continue;
+    }
+
+    if (targetId !== undefined) {
+      const worldIds = worldsByTargetId.get(targetId);
+      if (!worldIds) {
+        continue;
+      }
+      for (let i = 0; i < worldIds.length; i++) {
+        const world = engineState.worlds.get(worldIds[i]!);
+        if (world) {
+          world.inboundEvents.push(event);
+        }
+      }
+      continue;
+    }
+
+    // Broadcast non-scoped events (system/audio/ui-async notifications).
+    for (const world of engineState.worlds.values()) {
+      world.inboundEvents.push(event);
     }
   }
 }
@@ -110,6 +330,11 @@ export function routeResponses(responses: CommandResponseEnvelope[]): void {
         world.inboundResponses.push(res);
       }
       engineState.commandTracker.delete(res.id);
+      continue;
+    }
+    if (engineState.globalCommandTracker.has(res.id)) {
+      engineState.globalInboundResponses.push(res);
+      engineState.globalCommandTracker.delete(res.id);
     }
   }
 }

package/src/engine/bridge/guards.ts

@@ -1,6 +1,7 @@
 import { EngineError } from '../errors';
 import { engineState, type WorldState } from '../state';
 
+/** Ensures engine runtime is initialized and not disposed. */
 export function requireInitialized(): void {
   if (engineState.status === 'disposed') {
     throw new EngineError('Disposed', 'Engine has been disposed.');
@@ -10,6 +11,7 @@ export function requireInitialized(): void {
   }
 }
 
+/** Resolves world state or throws when world id is unknown. */
 export function getWorldOrThrow(worldId: number): WorldState {
   const world = engineState.worlds.get(worldId);
   if (!world) {
@@ -18,11 +20,12 @@ export function getWorldOrThrow(worldId: number): WorldState {
   return world;
 }
 
+/** Ensures entity exists in world entity set. */
 export function ensureEntity(world: WorldState, entityId: number): void {
   if (!world.entities.has(entityId)) {
     throw new EngineError(
       'EntityNotFound',
-      `Entity ${entityId} not found in World ${world.windowId}.`,
+      `Entity ${entityId} not found in World ${world.worldId}.`,
     );
   }
 }

package/src/engine/bridge/protocol.ts

@@ -5,7 +5,6 @@ import type {
   EngineCmdEnvelope,
 } from '../../types/cmds';
 import type { EngineEvent } from '../../types/events';
-import { engineState } from '../state';
 
 /**
  * Vulfram Core/ABI Invariants:
@@ -46,6 +45,73 @@ export type CoreCommandBatch = EngineCmdEnvelope[];
 const packr = new Packr({ useRecords: false });
 const unpackr = new Unpackr({ useRecords: false });
 
+function normalizeForMsgpack(value: unknown): unknown {
+  if (value === undefined || value === null) return value;
+  if (Array.isArray(value)) {
+    let out: unknown[] | undefined;
+    for (let i = 0; i < value.length; i++) {
+      const item = value[i];
+      const normalizedItem = normalizeForMsgpack(item);
+      const normalized = normalizedItem === undefined ? null : normalizedItem;
+      if (!out) {
+        if (normalized !== item) {
+          out = value.slice(0, i);
+          out.push(normalized);
+        }
+      } else {
+        out.push(normalized);
+      }
+    }
+    return out ?? value;
+  }
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return value;
+  }
+  if (typeof value === 'object') {
+    const input = value as Record<string, unknown>;
+    const entries = Object.entries(input);
+    let out: Record<string, unknown> | undefined;
+
+    for (let i = 0; i < entries.length; i++) {
+      const [key, item] = entries[i]!;
+      if (item === undefined) continue;
+      const normalized = normalizeForMsgpack(item);
+      if (normalized === undefined) {
+        continue;
+      }
+      if (!out) {
+        if (normalized !== item) {
+          out = {};
+          for (let j = 0; j < i; j++) {
+            const [prevKey, prevItem] = entries[j]!;
+            if (prevItem !== undefined) {
+              out[prevKey] = prevItem;
+            }
+          }
+          out[key] = normalized;
+        }
+      } else {
+        out[key] = normalized;
+      }
+    }
+    if (!out) {
+      for (const [, item] of entries) {
+        if (item === undefined) {
+          out = {};
+          for (const [prevKey, prevItem] of entries) {
+            if (prevItem !== undefined) {
+              out[prevKey] = prevItem;
+            }
+          }
+          break;
+        }
+      }
+    }
+    return out ?? value;
+  }
+  return value;
+}
+
 /**
  * Minimal Command Payload Requirement:
  * Most scene/window commands include a `windowId` so the Core can route them
@@ -60,57 +126,8 @@ export interface BaseCommandArgs {
  * Serializes a batch of commands into a byte buffer ready for vulframSendQueue.
  */
 export function serializeBatch(batch: CoreCommandBatch): TransportBuffer {
-  if (engineState.flags.debugEnabled) {
-    const types = batch.map((cmd) => cmd.type);
-    const hasModel =
-      types.includes('cmd-model-create') || types.includes('cmd-model-update');
-    const hasResource = types.some(
-      (type) =>
-        type === 'cmd-primitive-geometry-create' ||
-        type === 'cmd-geometry-create' ||
-        type === 'cmd-material-create' ||
-        type === 'cmd-texture-create-from-buffer' ||
-        type === 'cmd-texture-create-solid-color',
-    );
-    if (hasModel || hasResource) {
-      console.debug('[Debug] BatchTypes', types);
-      const modelCreate = batch.find((cmd) => cmd.type === 'cmd-model-create');
-      if (modelCreate) {
-        console.debug(
-          '[Debug] ModelCreatePayload',
-          JSON.stringify(modelCreate.content),
-        );
-      }
-      const primitiveGeo = batch.find(
-        (cmd) => cmd.type === 'cmd-primitive-geometry-create',
-      );
-      if (primitiveGeo) {
-        console.debug(
-          '[Debug] GeometryPayload',
-          JSON.stringify(primitiveGeo.content),
-        );
-      }
-      const materialCreate = batch.find(
-        (cmd) => cmd.type === 'cmd-material-create',
-      );
-      if (materialCreate) {
-        console.debug(
-          '[Debug] MaterialPayload',
-          JSON.stringify(materialCreate.content),
-        );
-      }
-      const textureCreate = batch.find(
-        (cmd) => cmd.type === 'cmd-texture-create-from-buffer',
-      );
-      if (textureCreate) {
-        console.debug(
-          '[Debug] TexturePayload',
-          JSON.stringify(textureCreate.content),
-        );
-      }
-    }
-  }
-  return packr.pack(batch);
+  const normalizedBatch = normalizeForMsgpack(batch) as CoreCommandBatch;
+  return packr.pack(normalizedBatch);
 }
 
 /**