@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -1,10 +1,149 @@
 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';
+
+/**
+ * Legend-layout helpers for network visualization.
+ *
+ * The legend explains how colors map back to numeric weights and biases. These
+ * helpers turn color scales into labeled rows and place the legend so it stays
+ * readable across different canvas sizes.
+ */
+
+/**
+ * Creates legend rows from ordered tiers.
+ *
+ * Each row describes one closed numeric interval and the swatch used to paint
+ * it, making the dynamic color scale legible to a human reader.
+ *
+ * @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.
+ *
+ * The legend layout adapts between regular and compact modes so the network
+ * panel can stay informative on smaller viewports without swallowing the whole
+ * canvas.
+ *
+ * @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.
  *
+ * This convenience helper is used when the caller wants a layout driven by the
+ * currently active network and does not need to assemble the intermediate rows
+ * manually.
+ *
  * @param context - Render context.
  * @param network - Active network instance.
  * @returns Legend layout.
@@ -13,5 +152,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,36 +1,22 @@
-import Network from '../../../../../src/architecture/network';
-import type { VisualNetworkNodeLike } from '../browser-entry.types';
-import {
-  formatNodeBiasLabelInternal,
-  resolveNetworkVisualizationLayersInternal,
-} from '../browser-entry.visualization.utils';
+/**
+ * Shared topology formatting helpers used by network-view and visualization.
+ *
+ * The topology boundary resolves node layering, while this helper module adds a
+ * few small presentation-oriented utilities that are reused by the visualization
+ * panel.
+ */
+export { resolveNetworkVisualizationLayers } from '../network-view/network-view.topology.utils';
 
 /**
  * Formats node bias labels with fixed sign and precision.
  *
+ * Consistent sign and precision make dense node labels easier to scan quickly in
+ * the rendered network panel.
+ *
  * @param nodeBias - Node bias value.
  * @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,10 @@
-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.
+ * Public visualization facade for browser-entry network rendering.
  *
- * @param network - Runtime network instance.
- * @param inputSize - Input count fallback.
- * @param outputSize - Output count fallback.
- * @returns Layered nodes for rendering.
+ * The dedicated visualization folder focuses on turning network structure and
+ * parameter ranges into readable graphics. Layer resolution itself is shared
+ * with the neighboring network-view topology boundary, so this facade exposes
+ * that topology helper while keeping the visualization subsystem's public story
+ * in one place.
  */
-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/visualization/visualization.types.ts

@@ -1,7 +1,18 @@
 import type { ColorTier } from '../browser-entry.types';
 
+/**
+ * Visualization-specific color-scale contracts for network rendering.
+ *
+ * The Flappy Bird demo renders connection weights and node biases with tiered
+ * neon ramps so humans can quickly read sign and magnitude without parsing raw
+ * numbers on every edge and node.
+ */
+
 /**
  * Dynamic tiered color scale used by visualization render layers.
+ *
+ * The scale records the observed numeric range plus the ordered threshold tiers
+ * used to map values into colors.
  */
 export interface DynamicColorScale {
   minimumValue: number;
@@ -12,6 +23,9 @@ export interface DynamicColorScale {
 
 /**
  * Grouped color scales for connection and bias channels.
+ *
+ * Keeping the two scales together ensures the legend and drawing code read from
+ * one consistent view of the active network range.
  */
 export interface NetworkVisualizationColorScales {
   connectionScale: DynamicColorScale;

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

@@ -0,0 +1,238 @@
+# browser-entry/worker-channel
+
+## browser-entry/worker-channel/worker-channel.types.ts
+
+### WorkerChannelGenerationPayload
+
+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.
+
+### WorkerChannelMessage
+
+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.
+
+### WorkerChannelPlaybackStepPayload
+
+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.
+
+### WorkerChannelPlaybackStepRequest
+
+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.
+
+## browser-entry/worker-channel/worker-channel.ts
+
+### worker-channel
+
+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.
+
+### 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<{ requestId: number; 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.
+
+Protocol errors are different from runtime worker crashes: the worker is
+alive, but it is explicitly telling the browser that the requested operation
+could not be completed.
+
+### createWorkerChannelResponseError
+
+`(message: string) => Error`
+
+Converts worker protocol error payloads into typed worker-channel errors.
+
+Using a dedicated error class makes it easier for browser code to distinguish
+"worker rejected my request" from "the worker crashed".
+
+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.
+
+Browser worker errors are not always surfaced as proper `Error` objects, so
+this helper converts the event payload into a predictable error shape before
+it escapes the channel layer.
+
+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.
+
+Protocol errors are different from runtime worker crashes: the worker is
+alive, but it is explicitly telling the browser that the requested operation
+could not be completed.
+
+## 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.
+
+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`.
+
+### resolveEvolutionWorkerBundleUrl
+
+`() => string`
+
+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`.
+
+## 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.
+
+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.
+
+Parameters:
+- `options` - - Worker request options and response resolver callback.
+
+Returns: Promise resolving with the matched worker response payload.
+
+### WorkerChannelRequestMessage
+
+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.
+
+### WorkerChannelRequestOptions
+
+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.
+
+## browser-entry/worker-channel/worker-channel.playback.service.ts
+
+### PendingPlaybackRequest
+
+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.
+
+### requestWorkerPlaybackStep
+
+`(evolutionWorker: Worker, playbackStepRequest: import("test/examples/flappy_bird/browser-entry/worker-channel/worker-channel.types").WorkerChannelPlaybackStepRequest) => Promise<{ requestId: number; 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.
+
+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.
+
+Parameters:
+- `evolutionWorker` - - Worker that owns playback simulation state.
+- `playbackStepRequest` - - Requested simulation budget and viewport size.
+
+Returns: Playback-step payload including snapshot and completion marker.
+
+### resolvePlaybackWorkerChannelState
+
+`(evolutionWorker: Worker) => PlaybackWorkerChannelState`
+
+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.
+
+Parameters:
+- `evolutionWorker` - - Worker that owns playback simulation state.
+
+Returns: Persistent playback worker-channel state for the worker.
+
+## 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>`
+
+Generation request helper for the browser-entry worker channel.
+
+This module asks the worker to evolve until the next generation boundary and
+then returns the summary payload the browser needs for HUD updates and best
+network visualization.

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

@@ -1,5 +1,9 @@
 /**
  * Error raised when the evolution worker responds with an explicit protocol error payload.
+ *
+ * Protocol errors are different from runtime worker crashes: the worker is
+ * alive, but it is explicitly telling the browser that the requested operation
+ * could not be completed.
  */
 export class WorkerChannelResponseError extends Error {
   /**
@@ -14,6 +18,9 @@ export class WorkerChannelResponseError extends Error {
 /**
  * Converts worker protocol error payloads into typed worker-channel errors.
  *
+ * Using a dedicated error class makes it easier for browser code to distinguish
+ * "worker rejected my request" from "the worker crashed".
+ *
  * @param message - Message supplied by the worker error payload.
  * @returns Typed worker-channel protocol error.
  */
@@ -24,6 +31,10 @@ export function createWorkerChannelResponseError(message: string): Error {
 /**
  * Resolves a worker `ErrorEvent` into a normalized `Error` instance.
  *
+ * Browser worker errors are not always surfaced as proper `Error` objects, so
+ * this helper converts the event payload into a predictable error shape before
+ * it escapes the channel layer.
+ *
  * @param errorLike - Optional `event.error` payload.
  * @param fallbackMessage - Fallback message from `event.message`.
  * @returns Normalized runtime error.

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

@@ -4,9 +4,21 @@ import type {
 } from './worker-channel.types';
 import { requestWorkerResponse } from './worker-channel.request.service';
 
+/**
+ * Generation request helper for the browser-entry worker channel.
+ *
+ * This module asks the worker to evolve until the next generation boundary and
+ * then returns the summary payload the browser needs for HUD updates and best
+ * network visualization.
+ */
+
 /**
  * Requests the next evolved generation payload from the worker channel.
  *
+ * Unlike playback streaming, generation evolution is a simple single-response
+ * exchange: ask for the next generation and wait for the next
+ * `generation-ready` message.
+ *
  * @param evolutionWorker - Worker emitting generation-ready messages.
  * @returns Next generation payload.
  */