@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/asciiMaze/dashboardManager/dashboardManager.ts

@@ -0,0 +1,181 @@
+/**
+ * Public DashboardManager facade for the dedicated dashboardManager module boundary.
+ *
+ * The folder now owns local contracts, constants, pure formatting helpers, and
+ * stateful rendering and telemetry services. This facade keeps the established
+ * class-based API stable while delegating the heavy work to focused helpers.
+ */
+
+import type Neat from '../../../../src/neat';
+import { colors } from '../colors';
+import type {
+  IDashboardManager,
+  IMazeRunResult,
+  INetwork,
+} from '../interfaces';
+import { NetworkVisualization } from '../networkVisualization';
+import { DASHBOARD_MANAGER_CONSTANTS as C } from './dashboardManager.constants';
+import {
+  applyDashboardUpdate,
+  getDashboardLastTelemetry,
+  redrawDashboard,
+  resetDashboardState,
+} from './dashboardManager.services';
+import type {
+  AsciiMazeTelemetrySnapshot,
+  DashboardArchiveFunction,
+  DashboardClearFunction,
+  DashboardLogFunction,
+  DashboardManagerContext,
+  DashboardManagerState,
+  DashboardTelemetryHook,
+  RuntimeDashboardManager,
+} from './dashboardManager.types';
+import { formatDashboardStat } from './dashboardManager.utils';
+
+/**
+ * Rich ASCII maze dashboard used by browser and terminal example hosts.
+ *
+ * @remarks
+ * Create one instance per evolution run. The dashboard stores bounded history
+ * buffers and solved-archive output so a fresh instance gives the cleanest
+ * example lifecycle.
+ */
+export class DashboardManager
+  implements IDashboardManager, RuntimeDashboardManager
+{
+  /** Allow runtime host hooks such as `_telemetryHook`. */
+  [key: string]: unknown;
+
+  #state: DashboardManagerState = {
+    solvedMazes: [],
+    solvedMazeKeys: new Set(),
+    currentBest: null,
+    lastTelemetry: null,
+    lastBestFitness: null,
+    histories: {
+      bestFitness: [],
+      complexityNodes: [],
+      complexityConns: [],
+      hypervolume: [],
+      progress: [],
+      speciesCount: [],
+    },
+    lastDetailedStats: null,
+    runStartTs: null,
+    perfStart: null,
+    lastGeneration: null,
+    lastUpdateTs: null,
+    scratch: {
+      scores: [],
+      speciesSizes: [],
+      operatorStats: [],
+      mutationEntries: [],
+    },
+  };
+
+  #clearFn: DashboardClearFunction;
+  #logFn: DashboardLogFunction;
+  #archiveFn?: DashboardArchiveFunction;
+
+  /**
+   * Create a dashboard instance bound to the host's clear, live-log, and archive outputs.
+   *
+   * @param clearFn - Function that clears the live dashboard region.
+   * @param logFn - Function used for live framed dashboard lines.
+   * @param archiveFn - Optional function used for solved-maze archive output.
+   */
+  constructor(
+    clearFn: () => void,
+    logFn: (...args: unknown[]) => void,
+    archiveFn?: (...args: unknown[]) => void,
+  ) {
+    const noop = () => {};
+    this.#clearFn = typeof clearFn === 'function' ? clearFn : noop;
+    this.#logFn = typeof logFn === 'function' ? logFn : noop;
+    this.#archiveFn = typeof archiveFn === 'function' ? archiveFn : undefined;
+  }
+
+  /** Optional log function exposed for engine-side safe-writer fallbacks. */
+  get logFunction(): ((msg: string) => void) | undefined {
+    return this.#logFn as (msg: string) => void;
+  }
+
+  /**
+   * Clear and repaint the live dashboard using the current best candidate and histories.
+   *
+   * @param currentMaze - Maze currently shown in the live panel.
+   * @param neat - Optional NEAT instance used to enrich stats.
+   */
+  redraw(currentMaze: string[], neat?: unknown): void {
+    redrawDashboard(this.#createContext(), currentMaze, neat);
+  }
+
+  /**
+   * Ingest one evolution update, refresh the live dashboard, and emit telemetry.
+   *
+   * @param maze - Current maze layout.
+   * @param result - Latest run result for the tracked candidate.
+   * @param network - Candidate network used for the run.
+   * @param generation - Current generation number.
+   * @param neatInstance - Optional NEAT runtime used for advanced telemetry.
+   */
+  update(
+    maze: string[],
+    result: IMazeRunResult | undefined,
+    network: INetwork | null,
+    generation: number,
+    neatInstance?: Neat,
+  ): void {
+    applyDashboardUpdate(this.#createContext(), {
+      maze,
+      result,
+      network,
+      generation,
+      neatInstance,
+      telemetryHook: this._telemetryHook as DashboardTelemetryHook | undefined,
+    });
+  }
+
+  /**
+   * Return the latest public telemetry snapshot, including rich detail history when available.
+   *
+   * @returns Latest dashboard telemetry snapshot.
+   */
+  getLastTelemetry(): AsciiMazeTelemetrySnapshot {
+    return getDashboardLastTelemetry(this.#state);
+  }
+
+  /** Clear archive, current best, and telemetry state so the instance can be reused. */
+  reset(): void {
+    resetDashboardState(this.#state);
+  }
+
+  #createContext(): DashboardManagerContext {
+    return {
+      state: this.#state,
+      clearFn: this.#clearFn,
+      logFn: this.#logFn,
+      archiveFn: this.#archiveFn,
+      logBlank: () => this.#logBlank(),
+      formatStat: (
+        label: string,
+        value: string | number,
+        colorLabel?: string,
+        colorValue?: string,
+        labelWidth?: number,
+      ) =>
+        formatDashboardStat(label, value, colorLabel, colorValue, labelWidth),
+    };
+  }
+
+  #logBlank(): void {
+    this.#logFn(
+      `${colors.blueCore}║${NetworkVisualization.pad(
+        ' ',
+        C.FRAME_INNER_WIDTH,
+        ' ',
+      )}${colors.blueCore}║${colors.reset}`,
+    );
+  }
+}

package/test/examples/asciiMaze/dashboardManager/dashboardManager.types.ts

@@ -0,0 +1,267 @@
+import type Neat from '../../../../src/neat';
+import type {
+  IDashboardManager,
+  IMazeRunResult,
+  INetwork,
+} from '../interfaces';
+
+/** NEAT genome/network with runtime properties used by dashboard telemetry. */
+export interface NeatGenome {
+  score?: number;
+  nodes?: Array<{ type?: string; [key: string]: unknown }>;
+  connections?: Array<{ enabled?: boolean; [key: string]: unknown }>;
+  [key: string]: unknown;
+}
+
+/** NEAT species collection entry surface used by dashboard telemetry. */
+export interface NeatSpecies {
+  members?: unknown[];
+  length?: number;
+  [key: string]: unknown;
+}
+
+/** NEAT instance shape needed by dashboard helpers. */
+export interface NeatInstance {
+  population?: NeatGenome[];
+  species?: NeatSpecies[];
+  getTelemetry?: () => unknown[];
+  getOperatorStats?: () => unknown[];
+  getMutationStats?: () => Record<string, number>;
+  getNoveltyArchive?: () => unknown[];
+  [key: string]: unknown;
+}
+
+/** Operator stats entry from NEAT. */
+export interface OperatorStatsEntry {
+  name: string;
+  success: number;
+  attempts: number;
+  accepted?: number;
+  total?: number;
+  [key: string]: unknown;
+}
+
+export type NumericTelemetryMap = Record<string, number | null | undefined>;
+
+export interface AsciiMazeComplexityStats extends NumericTelemetryMap {
+  meanNodes?: number | null;
+  meanConns?: number | null;
+  growthNodes?: number | null;
+  growthConns?: number | null;
+}
+
+export type MutationStatsMap = Record<string, unknown>;
+
+/** Raw telemetry shape received from NEAT dashboard integrations. */
+export interface DashboardTelemetry {
+  complexity?: AsciiMazeComplexityStats | null;
+  perf?: NumericTelemetryMap | null;
+  lineage?: NumericTelemetryMap | null;
+  diversity?: NumericTelemetryMap | null;
+  fronts?: ReadonlyArray<ReadonlyArray<unknown>> | null;
+  objectives?: NumericTelemetryMap | null;
+  hyper?: number | null;
+  mutationStats?: MutationStatsMap | null;
+  mutation?: { stats?: MutationStatsMap | null } | null;
+  species?: number | null;
+  saturationFraction?: number | null;
+  actionEntropy?: number | null;
+  populationMean?: number | null;
+  populationMedian?: number | null;
+  enabledConnRatio?: number | null;
+  bestFitness?: number | null;
+  bestFitnessDelta?: number | null;
+  topSpeciesSizes?: number[] | null;
+  noveltyArchiveSize?: number | null;
+  operatorAcceptance?: Array<{ name: string; acceptancePct: number }> | null;
+  topMutations?: Array<{ name: string; count: number }> | null;
+  trends?: {
+    fitness?: string | null;
+    nodes?: string | null;
+    conns?: string | null;
+    hyper?: string | null;
+    progress?: string | null;
+    species?: string | null;
+  } | null;
+  histories?: {
+    bestFitness?: number[];
+    nodes?: number[];
+    conns?: number[];
+    hyper?: number[];
+    progress?: number[];
+    species?: number[];
+  } | null;
+  timestamp?: number;
+  generation?: number;
+}
+
+/** Expanded telemetry details retained by the dashboard between redraws. */
+export interface AsciiMazeDetailedStats {
+  generation: number;
+  bestFitness: number | null;
+  bestFitnessDelta: number | null;
+  saturationFraction: number | null;
+  actionEntropy: number | null;
+  populationMean: number | null;
+  populationMedian: number | null;
+  enabledConnRatio: number | null;
+  complexity: AsciiMazeComplexityStats | null;
+  simplifyPhaseActive: boolean;
+  perf: NumericTelemetryMap | null;
+  lineage: NumericTelemetryMap | null;
+  diversity: NumericTelemetryMap | null;
+  speciesCount: number | null;
+  topSpeciesSizes: number[] | null;
+  objectives: NumericTelemetryMap | null;
+  paretoFrontSizes: number[] | null;
+  firstFrontSize: number;
+  hypervolume: number | null;
+  noveltyArchiveSize: number | null;
+  operatorAcceptance: Array<{ name: string; acceptancePct: number }> | null;
+  topMutations: Array<{ name: string; count: number }> | null;
+  mutationStats: MutationStatsMap | null;
+  trends: {
+    fitness: string | null;
+    nodes: string | null;
+    conns: string | null;
+    hyper: string | null;
+    progress: string | null;
+    species: string | null;
+  };
+  histories: {
+    bestFitness: number[];
+    nodes: number[];
+    conns: number[];
+    hyper: number[];
+    progress: number[];
+    species: number[];
+  };
+  timestamp: number;
+}
+
+/** Public telemetry snapshot surfaced to browser consumers. */
+export interface AsciiMazeTelemetrySnapshot {
+  generation: number;
+  bestFitness: number | null;
+  progress: number | null;
+  speciesCount: number | null;
+  gensPerSec: number;
+  timestamp: number;
+  details: AsciiMazeDetailedStats | null;
+}
+
+/** Telemetry payload emitted through events, postMessage, and runtime hooks. */
+export interface DashboardTelemetryPayload {
+  type: 'asciiMaze:telemetry';
+  generation: number;
+  bestFitness: number | null;
+  progress: number | null;
+  speciesCount: number | null;
+  gensPerSec: number;
+  timestamp: number;
+  details: AsciiMazeDetailedStats | null;
+}
+
+/** Stored solved-maze archive entry. */
+export interface SolvedMazeRecord {
+  maze: string[];
+  result: IMazeRunResult;
+  network: INetwork;
+  generation: number;
+}
+
+/** Latest best candidate used by live rendering and telemetry. */
+export interface CurrentBestRecord {
+  result: IMazeRunResult;
+  network: INetwork | null;
+  generation: number;
+}
+
+/** Bounded numeric histories used for trends and exports. */
+export interface DashboardHistoryState {
+  bestFitness: number[];
+  complexityNodes: number[];
+  complexityConns: number[];
+  hypervolume: number[];
+  progress: number[];
+  speciesCount: number[];
+}
+
+/** Reused scratch arrays to keep redraw allocations predictable. */
+export interface DashboardScratchState {
+  scores: number[];
+  speciesSizes: number[];
+  operatorStats: OperatorStatsEntry[];
+  mutationEntries: [string, number][];
+}
+
+/** Mutable runtime state owned by one dashboard instance. */
+export interface DashboardManagerState {
+  solvedMazes: SolvedMazeRecord[];
+  solvedMazeKeys: Set<string>;
+  currentBest: CurrentBestRecord | null;
+  lastTelemetry: DashboardTelemetry | null;
+  lastBestFitness: number | null;
+  histories: DashboardHistoryState;
+  lastDetailedStats: AsciiMazeDetailedStats | null;
+  runStartTs: number | null;
+  perfStart: number | null;
+  lastGeneration: number | null;
+  lastUpdateTs: number | null;
+  scratch: DashboardScratchState;
+}
+
+export type DashboardClearFunction = () => void;
+export type DashboardLogFunction = (...args: unknown[]) => void;
+export type DashboardArchiveFunction = (...args: unknown[]) => void;
+export type DashboardTelemetryHook = (
+  payload: DashboardTelemetryPayload,
+) => void;
+
+/** Shared runtime context passed into dashboard services. */
+export interface DashboardManagerContext {
+  state: DashboardManagerState;
+  clearFn: DashboardClearFunction;
+  logFn: DashboardLogFunction;
+  archiveFn?: DashboardArchiveFunction;
+  logBlank: () => void;
+  formatStat: (
+    label: string,
+    value: string | number,
+    colorLabel?: string,
+    colorValue?: string,
+    labelWidth?: number,
+  ) => string;
+}
+
+/** Input accepted by the update orchestration service. */
+export interface DashboardManagerUpdateArgs {
+  maze: string[];
+  result: IMazeRunResult | undefined;
+  network: INetwork | null;
+  generation: number;
+  neatInstance?: Neat;
+  telemetryHook?: DashboardTelemetryHook;
+}
+
+/**
+ * Shared presentation adapter used by browser and non-browser hosts.
+ *
+ * @remarks
+ * Host wiring should prefer this interface when it needs redraw and telemetry
+ * access without depending on the concrete `DashboardManager` implementation.
+ */
+export interface DashboardPresentationAdapter extends IDashboardManager {
+  _telemetryHook?: DashboardTelemetryHook;
+  redraw?: (currentMaze: string[], neat?: unknown) => void;
+  getLastTelemetry?: () => AsciiMazeTelemetrySnapshot;
+}
+
+/**
+ * Compatibility alias for older runtime-facing imports.
+ *
+ * @remarks
+ * Step 7 promotes `DashboardPresentationAdapter` as the primary owner of this
+ * presentation seam while preserving the existing export name.
+ */
+export interface RuntimeDashboardManager extends DashboardPresentationAdapter {}

package/test/examples/asciiMaze/dashboardManager/dashboardManager.utils.ts

@@ -0,0 +1,254 @@
+import { colors } from '../colors';
+import type { IMazeRunResult, INetwork } from '../interfaces';
+import { MazeUtils } from '../mazeUtils';
+import { NetworkVisualization } from '../networkVisualization';
+import { DASHBOARD_MANAGER_CONSTANTS as C } from './dashboardManager.constants';
+
+/**
+ * Format a single framed dashboard stat line with aligned label and value columns.
+ *
+ * @param label - Descriptive stat label.
+ * @param value - String or number value displayed after the label.
+ * @param colorLabel - Color token applied to the label segment.
+ * @param colorValue - Color token applied to the value segment.
+ * @param labelWidth - Fixed width used for the label column.
+ * @returns Ready-to-log framed stat line.
+ */
+export function formatDashboardStat(
+  label: string,
+  value: string | number,
+  colorLabel = colors.neonSilver,
+  colorValue = colors.cyanNeon,
+  labelWidth: number = C.STAT_LABEL_WIDTH,
+): string {
+  const canonicalLabel = label.endsWith(':') ? label : `${label}:`;
+  const paddedLabel = canonicalLabel.padEnd(labelWidth, ' ');
+  const valueString = typeof value === 'number' ? `${value}` : String(value);
+  const coloredContent = `${colorLabel}${paddedLabel}${colorValue} ${valueString}${colors.reset}`;
+  return `${colors.blueCore}║${' '.repeat(C.LEFT_PADDING)}${NetworkVisualization.pad(
+    coloredContent,
+    C.CONTENT_WIDTH,
+    ' ',
+    'left',
+  )}${' '.repeat(C.RIGHT_PADDING)}${colors.blueCore}║${colors.reset}`;
+}
+
+/**
+ * Convert the recent tail of a numeric series into a compact sparkline.
+ *
+ * @param series - Numeric history in chronological order.
+ * @param width - Maximum sample count included in the sparkline.
+ * @returns Unicode sparkline string.
+ */
+export function buildDashboardSparkline(series: number[], width = 32): string {
+  if (!Array.isArray(series) || !series.length || width <= 0) return '';
+
+  const tailSlice = MazeUtils.tail<number>(series, width);
+  if (!tailSlice.length) return '';
+
+  const numericSamples = tailSlice.filter((sampleValue) =>
+    Number.isFinite(sampleValue),
+  );
+  if (!numericSamples.length) return '';
+
+  const minValue = Math.min(...numericSamples);
+  const maxValue = Math.max(...numericSamples);
+  const safeRange =
+    Math.abs(maxValue - minValue) < C.DELTA_EPSILON
+      ? C.DELTA_EPSILON
+      : maxValue - minValue;
+  const rampTopIndex = C.SPARK_BLOCKS.length - 1;
+
+  return numericSamples
+    .map((sampleValue) => {
+      const normalized = (sampleValue - minValue) / safeRange;
+      const blockIndex = Math.min(
+        rampTopIndex,
+        Math.max(0, Math.floor(normalized * rampTopIndex)),
+      );
+      return C.SPARK_BLOCKS[blockIndex];
+    })
+    .join('');
+}
+
+/**
+ * Build a lightweight dedupe key for a maze layout.
+ *
+ * @param maze - Maze rows in display order.
+ * @returns Joined maze key used by the solved archive.
+ */
+export function getDashboardMazeKey(maze: string[]): string {
+  return maze.join('');
+}
+
+/**
+ * Compute solved-path efficiency and visitation metrics for archive output.
+ *
+ * @param maze - Maze layout containing start and exit markers.
+ * @param result - Run result with path, steps, and fitness.
+ * @returns Derived path metrics used by solved archive formatting.
+ */
+export function computeDashboardPathMetrics(
+  maze: string[],
+  result: Pick<IMazeRunResult, 'path' | 'steps' | 'fitness'>,
+): {
+  optimalLength: number;
+  pathLength: number;
+  efficiencyPct: string;
+  overheadPct: string;
+  uniqueCellsVisited: number;
+  revisitedCells: number;
+  totalSteps: number;
+  fitnessValue: number;
+} {
+  const startPosition = MazeUtils.findPosition(maze, 'S');
+  const exitPosition = MazeUtils.findPosition(maze, 'E');
+  const bfsLength = MazeUtils.bfsDistance(
+    MazeUtils.encodeMaze(maze),
+    startPosition,
+    exitPosition,
+  );
+  const optimalLength = typeof bfsLength === 'number' ? bfsLength : 0;
+  const pathLength = Math.max(0, result.path.length - 1);
+
+  let efficiencyPct = '0.0';
+  let overheadPct = '0.0';
+  if (pathLength > 0 && optimalLength > 0) {
+    const efficiency = Math.min(1, optimalLength / pathLength) * 100;
+    efficiencyPct = efficiency.toFixed(1);
+    overheadPct = ((pathLength / optimalLength) * 100 - 100).toFixed(1);
+  }
+
+  const uniqueCells = new Set<string>();
+  let revisitedCells = 0;
+  for (const [cellX, cellY] of result.path) {
+    const cellKey = `${cellX},${cellY}`;
+    if (uniqueCells.has(cellKey)) {
+      revisitedCells++;
+      continue;
+    }
+    uniqueCells.add(cellKey);
+  }
+
+  return {
+    optimalLength,
+    pathLength,
+    efficiencyPct,
+    overheadPct,
+    uniqueCellsVisited: uniqueCells.size,
+    revisitedCells,
+    totalSteps: result.steps,
+    fitnessValue: result.fitness,
+  };
+}
+
+/**
+ * Infer a compact architecture string from a network-like runtime object.
+ *
+ * @param networkInstance - Network instance from the maze example runtime.
+ * @returns Architecture string such as `6 - 8 - 4`, or `n/a` when unavailable.
+ */
+export function deriveDashboardArchitecture(
+  networkInstance?: INetwork | null,
+): string {
+  if (!networkInstance) return 'n/a';
+
+  const networkRecord = networkInstance as unknown as Record<string, unknown>;
+  const layerArray = networkRecord.layers;
+  if (Array.isArray(layerArray) && layerArray.length >= 2) {
+    const layerSizes = layerArray.map((layerValue) => {
+      const layerRecord = layerValue as Record<string, unknown>;
+      if (Array.isArray(layerRecord.nodes)) return layerRecord.nodes.length;
+      if (Array.isArray(layerValue)) return layerValue.length;
+      return 0;
+    });
+    return layerSizes.join(' - ');
+  }
+
+  const flatNodes = networkRecord.nodes;
+  if (Array.isArray(flatNodes)) {
+    type NodeWithType = {
+      type?: string;
+      connections?: { in?: Array<{ from?: unknown }> };
+      [key: string]: unknown;
+    };
+
+    const inputNodes = flatNodes.filter(
+      (nodeValue) => (nodeValue as NodeWithType).type === 'input',
+    );
+    const outputNodes = flatNodes.filter(
+      (nodeValue) => (nodeValue as NodeWithType).type === 'output',
+    );
+    const hiddenNodes = flatNodes.filter(
+      (nodeValue) => (nodeValue as NodeWithType).type === 'hidden',
+    );
+
+    if (!hiddenNodes.length) {
+      if (
+        typeof networkInstance.input === 'number' &&
+        typeof networkInstance.output === 'number'
+      ) {
+        return `${networkInstance.input} - ${networkInstance.output}`;
+      }
+      return `${inputNodes.length} - ${outputNodes.length}`;
+    }
+
+    const assignedNodes = new Set<unknown>(inputNodes);
+    let remainingHidden = hiddenNodes.slice();
+    const inferredHiddenSizes: number[] = [];
+    const safetyLimit = hiddenNodes.length * C.LAYER_INFER_LOOP_MULTIPLIER;
+    let iterationCount = 0;
+
+    while (remainingHidden.length && iterationCount < safetyLimit) {
+      iterationCount++;
+      const currentLayer = remainingHidden.filter((hiddenNode) => {
+        const hiddenNodeRecord = hiddenNode as NodeWithType;
+        return hiddenNodeRecord.connections?.in?.every((connectionValue) =>
+          assignedNodes.has(connectionValue.from),
+        );
+      });
+
+      if (!currentLayer.length) {
+        inferredHiddenSizes.push(remainingHidden.length);
+        break;
+      }
+
+      inferredHiddenSizes.push(currentLayer.length);
+      for (const currentNode of currentLayer) {
+        assignedNodes.add(currentNode);
+      }
+      remainingHidden = remainingHidden.filter(
+        (hiddenNode) => !assignedNodes.has(hiddenNode),
+      );
+    }
+
+    return [
+      `${inputNodes.length}`,
+      ...inferredHiddenSizes.map((hiddenSize) => `${hiddenSize}`),
+      `${outputNodes.length}`,
+    ].join(' - ');
+  }
+
+  if (
+    typeof networkInstance.input === 'number' &&
+    typeof networkInstance.output === 'number'
+  ) {
+    return `${networkInstance.input} - ${networkInstance.output}`;
+  }
+
+  return 'n/a';
+}
+
+/**
+ * Return the recent export window of a bounded numeric history buffer.
+ *
+ * @param history - History buffer in chronological order.
+ * @returns Independent tail slice suitable for telemetry export.
+ */
+export function sliceDashboardHistoryForExport(
+  history: number[] | undefined | null,
+): number[] {
+  if (!Array.isArray(history) || !history.length) return [];
+  const startIndex = Math.max(0, history.length - C.HISTORY_EXPORT_WINDOW);
+  return history.slice(startIndex);
+}