@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.playback.service.test.ts

@@ -0,0 +1,143 @@
+import { requestWorkerPlaybackStep } from './worker-channel.playback.service';
+import type { WorkerChannelPlaybackStepPayload } from './worker-channel.types';
+
+describe('requestWorkerPlaybackStep', () => {
+  it('registers playback listeners only once per worker across sequential requests', async () => {
+    const evolutionWorker = createMockWorker();
+    const firstRequestPromise = requestWorkerPlaybackStep(evolutionWorker, {
+      simulationSteps: 1,
+      visibleWorldWidthPx: 640,
+      visibleWorldHeightPx: 480,
+    });
+    evolutionWorker.emitMessage(createPlaybackStepMessage(1, 1));
+    await firstRequestPromise;
+
+    const secondRequestPromise = requestWorkerPlaybackStep(evolutionWorker, {
+      simulationSteps: 2,
+      visibleWorldWidthPx: 640,
+      visibleWorldHeightPx: 480,
+    });
+    evolutionWorker.emitMessage(createPlaybackStepMessage(2, 2));
+    await secondRequestPromise;
+
+    expect(evolutionWorker.addEventListener).toHaveBeenCalledTimes(2);
+  });
+
+  it('rejects concurrent playback-step requests on the same worker', async () => {
+    const evolutionWorker = createMockWorker();
+    const firstRequestPromise = requestWorkerPlaybackStep(evolutionWorker, {
+      simulationSteps: 1,
+      visibleWorldWidthPx: 640,
+      visibleWorldHeightPx: 480,
+    });
+
+    const concurrentRequestResult = requestWorkerPlaybackStep(evolutionWorker, {
+      simulationSteps: 1,
+      visibleWorldWidthPx: 640,
+      visibleWorldHeightPx: 480,
+    }).catch((error: Error) => error.message);
+
+    evolutionWorker.emitMessage(createPlaybackStepMessage(1, 1));
+
+    expect(
+      await Promise.all([firstRequestPromise, concurrentRequestResult]),
+    ).toEqual([
+      createPlaybackStepPayload(1, 1),
+      'Concurrent playback-step requests are not supported by the playback worker channel.',
+    ]);
+  });
+
+  it('ignores stale playback-step responses with older request ids', async () => {
+    const evolutionWorker = createMockWorker();
+    const playbackRequestPromise = requestWorkerPlaybackStep(evolutionWorker, {
+      simulationSteps: 1,
+      visibleWorldWidthPx: 640,
+      visibleWorldHeightPx: 480,
+    });
+
+    evolutionWorker.emitMessage(createPlaybackStepMessage(99, 0));
+    evolutionWorker.emitMessage(createPlaybackStepMessage(1, 1));
+
+    expect(await playbackRequestPromise).toEqual(
+      createPlaybackStepPayload(1, 1),
+    );
+  });
+});
+
+function createMockWorker(): Worker & {
+  emitMessage: (message: unknown) => void;
+} {
+  const messageListeners: Array<(event: MessageEvent<unknown>) => void> = [];
+  const errorListeners: Array<(event: ErrorEvent) => void> = [];
+
+  return {
+    addEventListener: jest.fn(
+      (
+        eventType: string,
+        listener: EventListenerOrEventListenerObject,
+      ): void => {
+        if (typeof listener !== 'function') {
+          return;
+        }
+
+        if (eventType === 'message') {
+          messageListeners.push(
+            listener as (event: MessageEvent<unknown>) => void,
+          );
+          return;
+        }
+
+        if (eventType === 'error') {
+          errorListeners.push(listener as (event: ErrorEvent) => void);
+        }
+      },
+    ),
+    postMessage: jest.fn(),
+    emitMessage: (message: unknown): void => {
+      for (const listener of messageListeners) {
+        listener({ data: message } as MessageEvent<unknown>);
+      }
+
+      for (const listener of errorListeners) {
+        void listener;
+      }
+    },
+  } as unknown as Worker & { emitMessage: (message: unknown) => void };
+}
+
+function createPlaybackStepMessage(frameIndex: number, requestId: number) {
+  return {
+    type: 'playback-step' as const,
+    payload: createPlaybackStepPayload(frameIndex, requestId),
+  };
+}
+
+function createPlaybackStepPayload(
+  frameIndex: number,
+  requestId: number,
+): WorkerChannelPlaybackStepPayload {
+  return {
+    requestId,
+    snapshot: {
+      format: 'packed-v1',
+      frameIndex,
+      cumulativePipeTravelPx: 0,
+      visibleWorldWidthPx: 640,
+      visibleWorldHeightPx: 480,
+      pipeCount: 0,
+      birdCount: 0,
+      pipes: {
+        xPositionsPx: new Float32Array([]),
+        gapCenterYPositionsPx: new Float32Array([]),
+        gapSizesPx: new Float32Array([]),
+      },
+      birds: {
+        yPositionsPx: new Float32Array([]),
+        pipesPassed: new Uint32Array([]),
+        framesSurvived: new Uint32Array([]),
+        doneFlags: new Uint8Array([]),
+      },
+    },
+    done: false,
+  };
+}

package/test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.playback.service.ts

@@ -3,32 +3,158 @@ import type {
   WorkerChannelPlaybackStepPayload,
   WorkerChannelPlaybackStepRequest,
 } from './worker-channel.types';
-import { requestWorkerResponse } from './worker-channel.request.service';
+import {
+  createWorkerChannelResponseError,
+  resolveWorkerChannelRuntimeError,
+} from './worker-channel.errors';
+
+/**
+ * Stateful playback request channel for one evolution worker.
+ *
+ * Playback is intentionally handled differently from generation requests. The
+ * browser asks for a sequence of incremental frames, and the channel keeps a
+ * small amount of per-worker state so each request can be matched to the
+ * correct reply.
+ */
+
+type PendingPlaybackRequest = {
+  requestId: number;
+  reject: (error: Error) => void;
+  resolve: (payload: WorkerChannelPlaybackStepPayload) => void;
+};
+
+type PlaybackWorkerChannelState = {
+  nextRequestId: number;
+  pendingPlaybackRequest: PendingPlaybackRequest | null;
+};
+
+const playbackWorkerChannelStateByWorker = new WeakMap<
+  Worker,
+  PlaybackWorkerChannelState
+>();
 
 /**
  * Requests one playback batch step from the worker channel.
  *
+ * A playback-step request is effectively "advance the simulation by this many
+ * internal steps, then send me a packed frame I can render". The request is
+ * tagged with a monotonically increasing request id so stale or out-of-order
+ * replies can be ignored safely.
+ *
  * @param evolutionWorker - Worker that owns playback simulation state.
  * @param playbackStepRequest - Requested simulation budget and viewport size.
  * @returns Playback-step payload including snapshot and completion marker.
+ * @example
+ * ```ts
+ * const playbackPayload = await requestWorkerPlaybackStep(evolutionWorker, {
+ *   simulationSteps: 2,
+ *   visibleWorldWidthPx: 640,
+ *   visibleWorldHeightPx: 480,
+ * });
+ * ```
  */
 export function requestWorkerPlaybackStep(
   evolutionWorker: Worker,
   playbackStepRequest: WorkerChannelPlaybackStepRequest,
 ): Promise<WorkerChannelPlaybackStepPayload> {
-  return requestWorkerResponse({
-    evolutionWorker,
-    requestMessage: {
+  const playbackWorkerChannelState =
+    resolvePlaybackWorkerChannelState(evolutionWorker);
+
+  return new Promise((resolve, reject) => {
+    if (playbackWorkerChannelState.pendingPlaybackRequest) {
+      reject(
+        new Error(
+          'Concurrent playback-step requests are not supported by the playback worker channel.',
+        ),
+      );
+      return;
+    }
+
+    const requestId = playbackWorkerChannelState.nextRequestId;
+    playbackWorkerChannelState.nextRequestId += 1;
+
+    playbackWorkerChannelState.pendingPlaybackRequest = {
+      requestId,
+      reject,
+      resolve,
+    };
+
+    evolutionWorker.postMessage({
       type: 'request-playback-step',
-      payload: playbackStepRequest,
-    },
-    resolveResponsePayload: (
-      workerMessage: WorkerChannelMessage,
-    ): WorkerChannelPlaybackStepPayload | undefined => {
-      if (workerMessage.type === 'playback-step') {
-        return workerMessage.payload;
-      }
-      return undefined;
-    },
+      payload: {
+        ...playbackStepRequest,
+        requestId,
+      },
+    });
   });
 }
+
+/**
+ * Resolves persistent playback worker-channel state for one worker instance.
+ *
+ * The state tracks request ids and the one allowed in-flight playback request.
+ * That single-flight rule keeps the protocol simple and avoids ambiguous frame
+ * ordering on the browser side.
+ *
+ * @param evolutionWorker - Worker that owns playback simulation state.
+ * @returns Persistent playback worker-channel state for the worker.
+ */
+function resolvePlaybackWorkerChannelState(
+  evolutionWorker: Worker,
+): PlaybackWorkerChannelState {
+  const cachedState = playbackWorkerChannelStateByWorker.get(evolutionWorker);
+  if (cachedState) {
+    return cachedState;
+  }
+
+  const playbackWorkerChannelState: PlaybackWorkerChannelState = {
+    nextRequestId: 1,
+    pendingPlaybackRequest: null,
+  };
+
+  evolutionWorker.addEventListener('message', ((
+    event: MessageEvent<WorkerChannelMessage>,
+  ): void => {
+    const pendingPlaybackRequest =
+      playbackWorkerChannelState.pendingPlaybackRequest;
+    if (!pendingPlaybackRequest) {
+      return;
+    }
+
+    if (event.data.type === 'playback-step') {
+      if (event.data.payload.requestId !== pendingPlaybackRequest.requestId) {
+        return;
+      }
+
+      playbackWorkerChannelState.pendingPlaybackRequest = null;
+      pendingPlaybackRequest.resolve(event.data.payload);
+      return;
+    }
+
+    if (event.data.type === 'error') {
+      playbackWorkerChannelState.pendingPlaybackRequest = null;
+      pendingPlaybackRequest.reject(
+        createWorkerChannelResponseError(event.data.payload.message),
+      );
+    }
+  }) as EventListener);
+
+  evolutionWorker.addEventListener('error', ((event: ErrorEvent): void => {
+    const pendingPlaybackRequest =
+      playbackWorkerChannelState.pendingPlaybackRequest;
+    if (!pendingPlaybackRequest) {
+      return;
+    }
+
+    playbackWorkerChannelState.pendingPlaybackRequest = null;
+    pendingPlaybackRequest.reject(
+      resolveWorkerChannelRuntimeError(event.error, event.message),
+    );
+  }) as EventListener);
+
+  playbackWorkerChannelStateByWorker.set(
+    evolutionWorker,
+    playbackWorkerChannelState,
+  );
+  return playbackWorkerChannelState;
+}

package/test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.request.service.ts

@@ -4,8 +4,19 @@ import {
 } from './worker-channel.errors';
 import type { WorkerChannelMessage } from './worker-channel.types';
 
+/**
+ * Generic request/response helper for worker-channel interactions.
+ *
+ * This module implements a small RPC-like pattern on top of browser worker
+ * events. The browser sends one message, listens for the first matching reply,
+ * and normalizes protocol failures into ordinary `Error` instances.
+ */
+
 /**
  * Message shape sent to the worker request channel.
+ *
+ * The worker protocol stays stringly-typed at the transport edge on purpose so
+ * the message stream is easy to inspect during debugging.
  */
 export interface WorkerChannelRequestMessage {
   type: string;
@@ -14,6 +25,9 @@ export interface WorkerChannelRequestMessage {
 
 /**
  * Configuration used for one worker request/response lifecycle.
+ *
+ * Callers provide the worker, the outbound message, and the predicate that says
+ * which inbound worker message should satisfy the request.
  */
 export interface WorkerChannelRequestOptions<ResponsePayload> {
   evolutionWorker: Worker;
@@ -26,8 +40,21 @@ export interface WorkerChannelRequestOptions<ResponsePayload> {
 /**
  * Sends one request to the worker and resolves with the first matching response payload.
  *
+ * This keeps generation requests simple: the caller describes the response it is
+ * waiting for, and this helper handles transient listeners, protocol errors,
+ * and runtime worker failures.
+ *
  * @param options - Worker request options and response resolver callback.
  * @returns Promise resolving with the matched worker response payload.
+ * @example
+ * ```ts
+ * const generation = await requestWorkerResponse({
+ *   evolutionWorker,
+ *   requestMessage: { type: 'request-generation' },
+ *   resolveResponsePayload: (message) =>
+ *     message.type === 'generation-ready' ? message.payload : undefined,
+ * });
+ * ```
  */
 export function requestWorkerResponse<ResponsePayload>(
   options: WorkerChannelRequestOptions<ResponsePayload>,

package/test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.ts

@@ -1,3 +1,11 @@
+/**
+ * Public worker-channel facade for the Flappy Bird browser runtime.
+ *
+ * This boundary wraps the lower-level message protocol in a smaller browser API:
+ * create the worker, request a generation result, or request the next playback
+ * step. The point is to keep the rest of the UI code thinking in terms of
+ * intent rather than raw `postMessage` plumbing.
+ */
 export {
   createEvolutionWorker,
   requestWorkerGeneration,

package/test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.types.ts

@@ -4,24 +4,47 @@ import type {
   EvolutionWorkerMessage,
 } from '../browser-entry.types';
 
+/**
+ * Shared protocol contracts for the browser-entry worker channel.
+ *
+ * These types define the thin translation layer between generic worker messages
+ * and the specific request/response flows used by the Flappy Bird browser UI.
+ *
+ * If you want background reading, the Wikipedia article on "message passing"
+ * gives the right mental model for this boundary.
+ */
+
 /**
  * Aliases the shared worker message union for worker-channel modules.
+ *
+ * Keeping the alias local makes submodules read as protocol-focused code rather
+ * than browser-entry plumbing.
  */
 export type WorkerChannelMessage = EvolutionWorkerMessage;
 
 /**
  * Aliases the generation payload contract returned by the worker.
+ *
+ * This payload arrives when one NEAT generation has finished evolving and the
+ * browser is ready to update its "best so far" view.
  */
 export type WorkerChannelGenerationPayload = EvolutionGenerationPayload;
 
 /**
  * Aliases the playback-step payload contract returned by the worker.
+ *
+ * This is the browser-side shape of one streamed playback frame plus its
+ * accompanying aggregate telemetry.
  */
 export type WorkerChannelPlaybackStepPayload =
   EvolutionPlaybackStepMessage['payload'];
 
 /**
  * Request payload sent when asking the worker to advance playback simulation.
+ *
+ * The request declares both simulation budget and viewport dimensions so the
+ * worker can package a frame that already matches the browser's current canvas
+ * world.
  */
 export interface WorkerChannelPlaybackStepRequest {
   simulationSteps: number;

package/test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.url.service.ts

@@ -1,6 +1,11 @@
 /**
  * Resolves the evolution worker bundle URL relative to the active browser-entry bundle.
  *
+ * The browser bundle and worker bundle are emitted side-by-side by the docs/demo
+ * build. Resolving the worker URL relative to the currently loaded browser
+ * bundle keeps the demo portable across local files, static hosting, and docs
+ * builds without hard-coding absolute paths.
+ *
  * @returns Absolute URL string for `flappy-evolution.worker.bundle.js`.
  */
 export function resolveEvolutionWorkerBundleUrl(): string {