@reicek/neataptic-ts 0.1.21 → 0.1.22

package/test/examples/flappy_bird/browser-entry/visualization/visualization.legend.utils.ts

@@ -1,6 +1,126 @@
 import Network from '../../../../../src/architecture/network';
-import type { NetworkLegendLayout } from '../browser-entry.types';
-import { resolveDefaultNetworkLegendLayoutInternal } from '../browser-entry.visualization.utils';
+import {
+  FLAPPY_NETWORK_LEGEND_BOTTOM_PADDING_PX,
+  FLAPPY_NETWORK_LEGEND_COMPACT_HEIGHT_THRESHOLD_PX,
+  FLAPPY_NETWORK_LEGEND_COMPACT_ROW_HEIGHT_PX,
+  FLAPPY_NETWORK_LEGEND_COMPACT_SECTION_GAP_PX,
+  FLAPPY_NETWORK_LEGEND_COMPACT_SECTION_TITLE_HEIGHT_PX,
+  FLAPPY_NETWORK_LEGEND_COMPACT_WIDTH_PX,
+  FLAPPY_NETWORK_LEGEND_COMPACT_WIDTH_THRESHOLD_PX,
+  FLAPPY_NETWORK_LEGEND_HEADER_HEIGHT_PX,
+  FLAPPY_NETWORK_LEGEND_MARGIN_PX,
+  FLAPPY_NETWORK_LEGEND_MIN_TOP_PX,
+  FLAPPY_NETWORK_LEGEND_REGULAR_ROW_HEIGHT_PX,
+  FLAPPY_NETWORK_LEGEND_REGULAR_SECTION_GAP_PX,
+  FLAPPY_NETWORK_LEGEND_REGULAR_SECTION_TITLE_HEIGHT_PX,
+  FLAPPY_NETWORK_LEGEND_REGULAR_WIDTH_PX,
+  FLAPPY_NETWORK_LEGEND_TARGET_TOP_PX,
+  FLAPPY_NETWORK_LEGEND_TOP_LEFT_THRESHOLD_PX,
+} from '../../constants/constants';
+import { clamp } from '../browser-entry.math.utils';
+import type {
+  ColorLegendRow,
+  NetworkLegendLayout,
+} from '../browser-entry.types';
+import { assertFiniteLegendBound } from './visualization.errors';
+import { resolveNetworkVisualizationColorScales } from './visualization.colors.utils';
+import type { DynamicColorScale } from './visualization.types';
+
+/**
+ * Creates legend rows from ordered tiers.
+ *
+ * @param scale - Dynamic color scale containing bounds, tiers, and overflow color.
+ * @param symbol - Label symbol.
+ * @returns Legend rows.
+ */
+export function createColorLegendRows(
+  scale: DynamicColorScale,
+  symbol: 'w' | 'b',
+): ColorLegendRow[] {
+  return scale.tiers.map((tier, tierIndex) => {
+    const lowerBound =
+      tierIndex === 0
+        ? scale.minimumValue
+        : scale.tiers[tierIndex - 1].upperBound;
+    return {
+      label: `${formatLegendBound(lowerBound)} <= ${symbol} <= ${formatLegendBound(tier.upperBound)}`,
+      color: tier.color,
+      minimumValue: lowerBound,
+      maximumValue: tier.upperBound,
+    };
+  });
+}
+
+/**
+ * Resolves network legend layout from canvas constraints.
+ *
+ * @param context - Render context.
+ * @param connectionLegendRows - Connection legend rows.
+ * @param biasLegendRows - Bias legend rows.
+ * @returns Computed legend layout.
+ */
+export function resolveNetworkLegendLayout(
+  context: CanvasRenderingContext2D,
+  connectionLegendRows: ColorLegendRow[],
+  biasLegendRows: ColorLegendRow[],
+): NetworkLegendLayout {
+  const compactLegend =
+    context.canvas.width < FLAPPY_NETWORK_LEGEND_COMPACT_WIDTH_THRESHOLD_PX ||
+    context.canvas.height < FLAPPY_NETWORK_LEGEND_COMPACT_HEIGHT_THRESHOLD_PX;
+  const legendWidthPx = compactLegend
+    ? FLAPPY_NETWORK_LEGEND_COMPACT_WIDTH_PX
+    : FLAPPY_NETWORK_LEGEND_REGULAR_WIDTH_PX;
+  const legendHeaderHeightPx = FLAPPY_NETWORK_LEGEND_HEADER_HEIGHT_PX;
+  const legendSectionTitleHeightPx = compactLegend
+    ? FLAPPY_NETWORK_LEGEND_COMPACT_SECTION_TITLE_HEIGHT_PX
+    : FLAPPY_NETWORK_LEGEND_REGULAR_SECTION_TITLE_HEIGHT_PX;
+  const legendRowHeightPx = compactLegend
+    ? FLAPPY_NETWORK_LEGEND_COMPACT_ROW_HEIGHT_PX
+    : FLAPPY_NETWORK_LEGEND_REGULAR_ROW_HEIGHT_PX;
+  const legendSectionGapPx = compactLegend
+    ? FLAPPY_NETWORK_LEGEND_COMPACT_SECTION_GAP_PX
+    : FLAPPY_NETWORK_LEGEND_REGULAR_SECTION_GAP_PX;
+  const legendHeightPx =
+    legendHeaderHeightPx +
+    legendSectionTitleHeightPx +
+    connectionLegendRows.length * legendRowHeightPx +
+    legendSectionGapPx +
+    legendSectionTitleHeightPx +
+    biasLegendRows.length * legendRowHeightPx +
+    FLAPPY_NETWORK_LEGEND_BOTTOM_PADDING_PX;
+  const legendMarginPx = FLAPPY_NETWORK_LEGEND_MARGIN_PX;
+  const preferTopLeft =
+    context.canvas.width < FLAPPY_NETWORK_LEGEND_TOP_LEFT_THRESHOLD_PX;
+
+  const maximumLeftPx = Math.max(
+    legendMarginPx,
+    context.canvas.width - legendWidthPx - legendMarginPx,
+  );
+  const legendLeftPx = preferTopLeft ? legendMarginPx : maximumLeftPx;
+
+  const maximumTopPx = Math.max(
+    legendMarginPx,
+    context.canvas.height - legendHeightPx - legendMarginPx,
+  );
+  const minimumTopPx = Math.min(FLAPPY_NETWORK_LEGEND_MIN_TOP_PX, maximumTopPx);
+  const legendTopPx = clamp(
+    FLAPPY_NETWORK_LEGEND_TARGET_TOP_PX,
+    minimumTopPx,
+    maximumTopPx,
+  );
+
+  return {
+    compactLegend,
+    legendLeftPx,
+    legendTopPx,
+    legendWidthPx,
+    legendHeightPx,
+    legendHeaderHeightPx,
+    legendSectionTitleHeightPx,
+    legendRowHeightPx,
+    legendSectionGapPx,
+  };
+}
 
 /**
  * Resolves default legend layout from internal tier definitions.
@@ -13,5 +133,20 @@ export function resolveDefaultNetworkLegendLayout(
   context: CanvasRenderingContext2D,
   network: Network | undefined,
 ): NetworkLegendLayout {
-  return resolveDefaultNetworkLegendLayoutInternal(context, network);
+  const colorScales = resolveNetworkVisualizationColorScales(network);
+  const connectionLegendRows = createColorLegendRows(
+    colorScales.connectionScale,
+    'w',
+  );
+  const biasLegendRows = createColorLegendRows(colorScales.biasScale, 'b');
+  return resolveNetworkLegendLayout(
+    context,
+    connectionLegendRows,
+    biasLegendRows,
+  );
+}
+
+function formatLegendBound(value: number): string {
+  assertFiniteLegendBound(value);
+  return value.toFixed(2);
 }

package/test/examples/flappy_bird/browser-entry/visualization/visualization.topology.utils.ts

@@ -1,9 +1,4 @@
-import Network from '../../../../../src/architecture/network';
-import type { VisualNetworkNodeLike } from '../browser-entry.types';
-import {
-  formatNodeBiasLabelInternal,
-  resolveNetworkVisualizationLayersInternal,
-} from '../browser-entry.visualization.utils';
+export { resolveNetworkVisualizationLayers } from '../network-view/network-view.topology.utils';
 
 /**
  * Formats node bias labels with fixed sign and precision.
@@ -12,25 +7,6 @@ import {
  * @returns Label text.
  */
 export function formatNodeBiasLabel(nodeBias: number): string {
-  return formatNodeBiasLabelInternal(nodeBias);
-}
-
-/**
- * Resolves layered node groups for visualization.
- *
- * @param network - Runtime network instance.
- * @param inputSize - Input count fallback.
- * @param outputSize - Output count fallback.
- * @returns Layered nodes for rendering.
- */
-export function resolveNetworkVisualizationLayers(
-  network: Network | undefined,
-  inputSize: number,
-  outputSize: number,
-): VisualNetworkNodeLike[][] {
-  return resolveNetworkVisualizationLayersInternal(
-    network,
-    inputSize,
-    outputSize,
-  );
+  const roundedBias = Number.isFinite(nodeBias) ? nodeBias : 0;
+  return `${roundedBias >= 0 ? '+' : ''}${roundedBias.toFixed(2)}`;
 }

package/test/examples/flappy_bird/browser-entry/visualization/visualization.ts

@@ -1,23 +1 @@
-import Network from '../../../../../src/architecture/network';
-import type { VisualNetworkNodeLike } from '../browser-entry.types';
-import { resolveNetworkVisualizationLayers as resolveNetworkVisualizationLayersFromTopology } from './visualization.topology.utils';
-
-/**
- * Public visualization entry for resolving layered network node groups.
- *
- * @param network - Runtime network instance.
- * @param inputSize - Input count fallback.
- * @param outputSize - Output count fallback.
- * @returns Layered nodes for rendering.
- */
-export function resolveNetworkVisualizationLayers(
-  network: Network | undefined,
-  inputSize: number,
-  outputSize: number,
-): VisualNetworkNodeLike[][] {
-  return resolveNetworkVisualizationLayersFromTopology(
-    network,
-    inputSize,
-    outputSize,
-  );
-}
+export { resolveNetworkVisualizationLayers } from '../network-view/network-view.topology.utils';

package/test/examples/flappy_bird/browser-entry/worker-channel/README.md

@@ -0,0 +1,156 @@
+# browser-entry/worker-channel
+
+## browser-entry/worker-channel/worker-channel.types.ts
+
+### WorkerChannelGenerationPayload
+
+Aliases the generation payload contract returned by the worker.
+
+### WorkerChannelMessage
+
+Aliases the shared worker message union for worker-channel modules.
+
+### WorkerChannelPlaybackStepPayload
+
+Aliases the playback-step payload contract returned by the worker.
+
+### WorkerChannelPlaybackStepRequest
+
+Request payload sent when asking the worker to advance playback simulation.
+
+## browser-entry/worker-channel/worker-channel.ts
+
+### createEvolutionWorker
+
+`() => Worker`
+
+Creates the evolution worker used to keep heavy NEAT compute off the UI thread.
+
+Returns: Initialized worker instance.
+
+### requestWorkerGeneration
+
+`(evolutionWorker: Worker) => Promise<import("test/examples/flappy_bird/browser-entry/browser-entry.worker.types").EvolutionGenerationPayload>`
+
+Waits for the next generation payload emitted by the evolution worker.
+
+Parameters:
+
+- `evolutionWorker` - - Worker emitting generation-ready messages.
+
+Returns: Next generation payload.
+
+### requestWorkerPlaybackStep
+
+`(evolutionWorker: Worker, playbackStepRequest: import("test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.types").WorkerChannelPlaybackStepRequest) => Promise<{ snapshot: import("test/examples/flappy_bird/browser-entry/browser-entry.worker.types").EvolutionPlaybackStepSnapshot; instrumentation?: { activationCallsPerFrame: number; simulationStepsPerRaf: number; } | undefined; done: boolean; averagePipesPassed?: number | undefined; p90FramesSurvived?: number | undefined; winnerPipesPassed?: number | undefined; winnerFramesSurvived?: number | undefined; }>`
+
+Requests one playback batch step from the worker.
+
+Parameters:
+
+- `evolutionWorker` - - Worker that owns playback simulation state.
+- `playbackStepRequest` - - Requested simulation budget and viewport width.
+
+Returns: Playback-step payload including snapshot and completion marker.
+
+## browser-entry/worker-channel/worker-channel.errors.ts
+
+### worker-channel.errors
+
+Error raised when the evolution worker responds with an explicit protocol error payload.
+
+### createWorkerChannelResponseError
+
+`(message: string) => Error`
+
+Converts worker protocol error payloads into typed worker-channel errors.
+
+Parameters:
+
+- `message` - - Message supplied by the worker error payload.
+
+Returns: Typed worker-channel protocol error.
+
+### resolveWorkerChannelRuntimeError
+
+`(errorLike: unknown, fallbackMessage: string) => Error`
+
+Resolves a worker `ErrorEvent` into a normalized `Error` instance.
+
+Parameters:
+
+- `errorLike` - - Optional `event.error` payload.
+- `fallbackMessage` - - Fallback message from `event.message`.
+
+Returns: Normalized runtime error.
+
+### WorkerChannelResponseError
+
+Error raised when the evolution worker responds with an explicit protocol error payload.
+
+## browser-entry/worker-channel/worker-channel.url.service.ts
+
+### worker-channel.url.service
+
+Resolves the evolution worker bundle URL relative to the active browser-entry bundle.
+
+@returns Absolute URL string for `flappy-evolution.worker.bundle.js`.
+
+### resolveEvolutionWorkerBundleUrl
+
+`() => string`
+
+Resolves the evolution worker bundle URL relative to the active browser-entry bundle.
+
+Returns: Absolute URL string for `flappy-evolution.worker.bundle.js`.
+
+## browser-entry/worker-channel/worker-channel.request.service.ts
+
+### requestWorkerResponse
+
+`(options: import("test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.request.service").WorkerChannelRequestOptions<ResponsePayload>) => Promise<ResponsePayload>`
+
+Sends one request to the worker and resolves with the first matching response payload.
+
+Parameters:
+
+- `options` - - Worker request options and response resolver callback.
+
+Returns: Promise resolving with the matched worker response payload.
+
+### WorkerChannelRequestMessage
+
+Message shape sent to the worker request channel.
+
+### WorkerChannelRequestOptions
+
+Configuration used for one worker request/response lifecycle.
+
+## browser-entry/worker-channel/worker-channel.playback.service.ts
+
+### requestWorkerPlaybackStep
+
+`(evolutionWorker: Worker, playbackStepRequest: import("test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.types").WorkerChannelPlaybackStepRequest) => Promise<{ snapshot: import("test/examples/flappy_bird/browser-entry/browser-entry.worker.types").EvolutionPlaybackStepSnapshot; instrumentation?: { activationCallsPerFrame: number; simulationStepsPerRaf: number; } | undefined; done: boolean; averagePipesPassed?: number | undefined; p90FramesSurvived?: number | undefined; winnerPipesPassed?: number | undefined; winnerFramesSurvived?: number | undefined; }>`
+
+Requests one playback batch step from the worker channel.
+
+Parameters:
+
+- `evolutionWorker` - - Worker that owns playback simulation state.
+- `playbackStepRequest` - - Requested simulation budget and viewport size.
+
+Returns: Playback-step payload including snapshot and completion marker.
+
+## browser-entry/worker-channel/worker-channel.generation.service.ts
+
+### requestWorkerGeneration
+
+`(evolutionWorker: Worker) => Promise<import("test/examples/flappy_bird/browser-entry/browser-entry.worker.types").EvolutionGenerationPayload>`
+
+Requests the next evolved generation payload from the worker channel.
+
+Parameters:
+
+- `evolutionWorker` - - Worker emitting generation-ready messages.
+
+Returns: Next generation payload.