@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/asciiMaze/browser-entry.ts

@@ -1,580 +1,14 @@
-import { BrowserTerminalUtility } from './browserTerminalUtility';
-import { createBrowserLogger } from './browserLogger';
-import { DashboardManager } from './dashboardManager';
-import { EvolutionEngine } from './evolutionEngine';
-import { INetwork } from './interfaces';
-import { MazeGenerator } from './mazes';
-import { NetworkRefinement } from './networkRefinement';
-import type Network from '../../../src/architecture/network';
-
-/**
- * Runtime type for DashboardManager with dynamic methods and hooks.
- * Dashboard gains runtime methods like redraw and telemetry hooks.
- */
-interface RuntimeDashboard {
-  _telemetryHook?: (telemetry: Record<string, unknown>) => void;
-  redraw?: (data: unknown[], state: unknown) => void;
-  getLastTelemetry?: () => Record<string, unknown>;
-  [key: string]: unknown;
-}
-
-/**
- * Runtime type for AbortSignal with dynamic properties.
- * Some environments extend AbortSignal with additional runtime flags.
- */
-interface RuntimeAbortSignal {
-  aborted?: boolean;
-  onabort?: (() => void) | null;
-  addEventListener: AbortSignal['addEventListener'];
-  removeEventListener: AbortSignal['removeEventListener'];
-  dispatchEvent: AbortSignal['dispatchEvent'];
-  reason?: unknown;
-  throwIfAborted?: () => void;
-}
-
-/**
- * Runtime type for AbortSignal constructor with dynamic any method.
- * Modern environments support AbortSignal.any for signal composition.
- */
-interface RuntimeAbortSignalConstructor {
-  prototype: AbortSignal;
-  new (): AbortSignal;
-  any?: (signals: AbortSignal[]) => AbortSignal;
-}
-
-/**
- * Runtime type for evolution result with dynamic properties.
- * Evolution loop returns results with bestResult, bestNetwork, etc.
- */
-interface RuntimeEvolutionResult {
-  bestResult?: {
-    progress?: number;
-    [key: string]: unknown;
-  };
-  bestNetwork?: INetwork;
-  [key: string]: unknown;
-}
-
-/**
- * Runtime type for global window with dynamic asciiMaze namespace.
- * Browser environments extend window with custom global namespaces.
- */
-interface RuntimeWindow extends Window {
-  asciiMaze?: {
-    start?: typeof start;
-    _autoStarted?: boolean;
-    [key: string]: unknown;
-  };
-  asciiMazeStart?: (containerElement?: unknown) => unknown;
-  [key: string]: unknown;
-}
-
-/** Default host container id used when a string is supplied to `start`. */
-const DEFAULT_CONTAINER_ID = 'ascii-maze-output';
-/** Width delta (px) that triggers a dashboard redraw to avoid noisy renders. */
-const RESIZE_WIDTH_THRESHOLD = 8;
-/** Debounce for fallback window.resize handler (ms). */
-const RESIZE_DEBOUNCE_MS = 120;
-/** Delay before auto-starting the demo when loaded as a script (ms). */
-const AUTO_START_DELAY_MS = 20;
-/** Minimum progress percentage required to consider a maze solved (mirrors e2e test). */
-const MIN_PROGRESS_TO_PASS = 90;
-/** Default stagnation generation threshold used across most curriculum phases. */
-const DEFAULT_MAX_STAGNANT_GENERATIONS = 50;
-/** Default max generations (hard cap) for most curriculum phases. */
-const DEFAULT_MAX_GENERATIONS = 100;
-/** Per-generation log/telemetry frequency for interactive demo (always 1). */
-const PER_GENERATION_LOG_FREQUENCY = 1;
-/** Initial side length (cells) of the generated procedural maze. */
-const INITIAL_MAZE_DIMENSION = 8;
-/** Maximum side length (cells) to grow the maze to. */
-const MAX_MAZE_DIMENSION = 40;
-/** Dimension increment (cells per axis) applied after each solved maze. */
-const MAZE_DIMENSION_INCREMENT = 4;
-/** Maximum agent steps before termination (scaled mazes). */
-const AGENT_MAX_STEPS = 600;
-/** Population size for evolution across maze scalings. */
-const POPULATION_SIZE = 20;
-
-/**
- * Create immutable evolution settings for a given maze dimension.
- *
- * @param dimension - Maze side length in cells (square maze).
- * @returns Readonly configuration object consumed by a single evolution run.
- */
-const createEvolutionSettings = (dimension: number) => {
-  return {
-    agentMaxSteps: AGENT_MAX_STEPS,
-    popSize: POPULATION_SIZE,
-    maxStagnantGenerations: DEFAULT_MAX_STAGNANT_GENERATIONS,
-    maxGenerations: DEFAULT_MAX_GENERATIONS,
-    lamarckianIterations: 4,
-    lamarckianSampleSize: 12,
-    mazeFactory: () => new MazeGenerator(dimension, dimension).generate(),
-  } as const;
-};
-
-/**
- * Lightweight telemetry hub using a Set + snapshot iteration (micro-optimized for small listener counts).
- * EventTarget would work here, but Set keeps call overhead extremely low and avoids string event names.
- */
-class TelemetryHub<TTelemetry extends Record<string, unknown>> {
-  /** Registered listener callbacks (unique). */
-  #listeners = new Set<(payload: TTelemetry) => void>();
-
-  /** Add a listener and return an unsubscribe function. */
-  add(listener: (payload: TTelemetry) => void): () => void {
-    this.#listeners.add(listener);
-    return () => this.#listeners.delete(listener);
-  }
-
-  /** Dispatch to a snapshot of listeners so mutations during iteration are safe. */
-  dispatch(payload: TTelemetry): void {
-    // Step: Snapshot listeners (defensive against unsubscribe inside callback)
-    const snapshot = Array.from(this.#listeners);
-    for (const listener of snapshot) {
-      try {
-        listener(payload);
-      } catch {
-        // Listener exceptions are isolated so evolution cannot be disrupted.
-      }
-    }
-  }
-}
-
-/**
- * Handle returned by {@link start} providing lifecycle & telemetry access.
- *
- * Consumers embedding the ASCII Maze demo can use this object to:
- * - Stop the evolutionary curriculum early (`stop()`)
- * - Check whether evolution is still active (`isRunning()`)
- * - Await natural completion (`done` Promise resolves when curriculum ends or stop() called)
- * - Subscribe to lightweight per-generation telemetry (`onTelemetry(cb)` returning an unsubscribe)
- * - Pull the latest snapshot on demand (`getTelemetry()`)
- */
-export interface AsciiMazeRunHandle {
-  /** Stop the running curriculum. This will also abort the internal signal. */
-  stop: () => void;
-  /** Whether the curriculum is currently active (not finished or stopped). */
-  isRunning: () => boolean;
-  /** Promise that resolves when the curriculum naturally finishes or is stopped. */
-  done: Promise<void>;
-  /** Subscribe to per-generation telemetry events. Returns an unsubscribe function. */
-  onTelemetry: (
-    listener: (telemetry: Record<string, unknown>) => void,
-  ) => () => void;
-  /** Return the last telemetry snapshot produced by the dashboard, if any. */
-  getTelemetry: () => unknown;
-}
-
 /**
- * Start the ASCII Maze evolutionary demo (progressively larger procedural mazes).
- *
- * Steps:
- * 1. Generate an initial procedural maze (20x20) and evolve a NEAT population.
- * 2. Emit telemetry each generation (logEvery=1) and pace via requestAnimationFrame for UI responsiveness.
- * 3. When solved (progress >= MIN_PROGRESS_TO_PASS) grow maze size by +2 on each axis (up to 40x40) and repeat.
- * 4. Continue until maximum dimension reached or `stop()` / external abort invoked.
+ * Compatibility entrypoint for the dedicated browser-entry module.
  *
- * This progressive curriculum demonstrates transfer of learned structure to larger mazes via fresh evolution runs.
- *
- * @param container - Element id or HTMLElement to host the demo (defaults to 'ascii-maze-output').
- * @param opts - Optional configuration. `opts.signal` (AbortSignal) can be supplied by the caller to
- *               cooperatively cancel the curriculum. Calling `stop()` will also trigger an abort.
- * @returns A {@link AsciiMazeRunHandle} exposing lifecycle controls and telemetry hooks.
+ * The real implementation now lives under `browser-entry/browser-entry.ts`.
+ * This file remains so existing imports such as `./browser-entry` continue to
+ * resolve without changes.
  */
-export const start = async (
-  container: string | HTMLElement = DEFAULT_CONTAINER_ID,
-  opts: { signal?: AbortSignal } = {},
-): Promise<AsciiMazeRunHandle> => {
-  // Step 0: Resolve host elements & loggers
-  const hostElement =
-    typeof container === 'string'
-      ? document.getElementById(container)
-      : container;
-
-  const archiveElement = hostElement
-    ? (hostElement.querySelector('#ascii-maze-archive') as HTMLElement)
-    : null;
-  const liveElement = hostElement
-    ? (hostElement.querySelector('#ascii-maze-live') as HTMLElement)
-    : null;
-
-  // clearer will clear only the live area; archive remains
-  const clearer = BrowserTerminalUtility.createTerminalClearer(
-    liveElement ?? undefined,
-  );
-  const liveLogger = createBrowserLogger(liveElement ?? undefined);
-  const archiveLogger = createBrowserLogger(archiveElement ?? undefined);
-
-  // DashboardManager will use live logger for ongoing redraws and archive logger to append solved blocks
-  const dashboard = new DashboardManager(
-    clearer,
-    liveLogger as unknown as (...args: unknown[]) => void,
-    archiveLogger as unknown as (...args: unknown[]) => void,
-  );
-
-  // Telemetry hub mediating dashboard -> external listeners
-  const telemetryHub = new TelemetryHub<Record<string, unknown>>();
-  const runtimeDashboard = dashboard as unknown as RuntimeDashboard;
-  runtimeDashboard._telemetryHook = (telemetry: Record<string, unknown>) =>
-    telemetryHub.dispatch(telemetry);
-
-  // Responsive resize: re-render dashboard when host width changes significantly.
-  try {
-    const observeTarget =
-      hostElement ?? document.getElementById('ascii-maze-output');
-    if (observeTarget && typeof ResizeObserver !== 'undefined') {
-      let lastObservedWidth = observeTarget.clientWidth;
-      const resizeObserver = new ResizeObserver((entries) => {
-        for (const entry of entries) {
-          const width = entry.contentRect.width;
-          if (Math.abs(width - lastObservedWidth) > RESIZE_WIDTH_THRESHOLD) {
-            // threshold to avoid noisy redraws
-            lastObservedWidth = width;
-            try {
-              runtimeDashboard.redraw?.([], undefined);
-            } catch {
-              // ignore redraw errors
-            }
-          }
-        }
-      });
-      resizeObserver.observe(observeTarget);
-    } else if (observeTarget) {
-      // Fallback: window resize listener (debounced)
-      let debounceTimer: number | undefined = undefined;
-      const handler = () => {
-        if (typeof debounceTimer === 'number') clearTimeout(debounceTimer);
-        debounceTimer = window.setTimeout(() => {
-          try {
-            runtimeDashboard.redraw?.([], undefined);
-          } catch {
-            // ignore
-          }
-        }, RESIZE_DEBOUNCE_MS);
-      };
-      window.addEventListener('resize', handler);
-    }
-  } catch {
-    // ignore resize wiring errors
-  }
-
-  // Inner runner (previously assigned to window.asciiMazeStart). Kept internal for ESM API.
-  let cancelled = false;
-  const internalController = new AbortController();
-  const externalSignal = opts.signal;
-
-  /**
-   * Compose an AbortSignal that will abort when either the internal controller
-   * or an optional external signal aborts. This helper prefers modern
-   * composition via `AbortSignal.any` when available, and falls back to
-   * best-effort wiring for older or test environments (jsdom, polyfills).
-   *
-   * @example
-   * // Create a composed signal that aborts when either source aborts
-   * const composed = composeAbortSignal(externalSignal);
-   * composed.addEventListener('abort', () => console.log('aborted'));
-   *
-   * @param externalSignalParam - Optional external AbortSignal provided by the caller.
-   *                              When omitted, the returned signal is the internal controller's signal.
-   * @returns A signal that will abort when either the internal controller or the external signal aborts.
-   */
-  const composeAbortSignal = (
-    externalSignalParam?: AbortSignal,
-  ): AbortSignal => {
-    // Step 0: fast-path when no external signal supplied
-    if (!externalSignalParam) return internalController.signal;
-
-    // Convert to descriptive locals for clarity
-    const externalSignal = externalSignalParam as RuntimeAbortSignal;
-    const internalSignal = internalController.signal;
-
-    // Use a switch-style flow to replace chained else-if logic and keep branches explicit.
-    // We switch on `true` so each case is a predicate; this keeps intent clear and
-    // satisfies the requirement to use switch/case rather than else-if chains.
-    switch (true) {
-      // Case: external already aborted -> return it immediately (race fast-path)
-      case !!externalSignal.aborted: {
-        return externalSignal as unknown as AbortSignal;
-      }
-
-      // Case: environment supports AbortSignal.any (modern browsers / Node 20+)
-      case typeof (AbortSignal as unknown as RuntimeAbortSignalConstructor)
-        .any === 'function': {
-        try {
-          // Prefer native composition when available for clarity & performance.
-          const composedSignal = (
-            AbortSignal as unknown as RuntimeAbortSignalConstructor
-          ).any!([externalSignal as unknown as AbortSignal, internalSignal]);
-          return composedSignal;
-        } catch {
-          // If native composition throws, intentionally fall through to manual
-          // wiring below so listeners are still attached.
-        }
-        // fallthrough
-      }
-
-      // Default: manual best-effort wiring for older environments and test runners.
-      default: {
-        // Step: try to attach an event listener to propagate abort.
-        try {
-          externalSignal.addEventListener(
-            'abort',
-            () => {
-              // Isolate listener exceptions to avoid destabilizing callers.
-              try {
-                internalController.abort();
-              } catch {
-                /* ignore */
-              }
-            },
-            { once: true },
-          );
-        } catch {
-          // ignore event wiring errors (some polyfills / minimal DOMs may throw)
-        }
-
-        // Step: defensive fallback - attempt to set `onabort` if supported.
-        try {
-          // Runtime assignment for environments lacking addEventListener
-          externalSignal.onabort = () => {
-            try {
-              internalController.abort();
-            } catch {
-              /* ignore */
-            }
-          };
-        } catch {
-          // ignore
-        }
-
-        // Step: microtask check to catch races where the external signal aborted
-        // before wiring handlers. queueMicrotask is preferred but may not exist
-        // in some minimal runtimes, so guard defensively.
-        try {
-          queueMicrotask(() => {
-            if (externalSignal.aborted) {
-              try {
-                internalController.abort();
-              } catch {
-                /* ignore */
-              }
-            }
-          });
-        } catch {
-          // queueMicrotask may not be available in some environments; ignore.
-        }
-      }
-    }
-
-    // Return the internal controller's signal as the composed signal when native
-    // composition isn't available. Manual wiring will propagate external aborts.
-    return internalSignal;
-  };
-
-  // Create done promise early so immediate-abort handling (below) can resolve it.
-  let resolveDone: (() => void) | undefined;
-  const donePromise = new Promise<void>((resolve) => (resolveDone = resolve));
-
-  const combinedSignal = composeAbortSignal(externalSignal);
-  let running = true;
-
-  // Immediate abort reaction: if the combined signal is already aborted (race),
-  // reflect the cancelled state immediately so callers polling `isRunning()` see
-  // the updated state without waiting for event listeners to be attached.
-  if (combinedSignal.aborted) {
-    cancelled = true;
-    running = false;
-    try {
-      resolveDone?.();
-    } catch {
-      /* ignore */
-    }
-  }
-
-  // Ensure we capture future abort events when they occur.
-  try {
-    combinedSignal.addEventListener(
-      'abort',
-      () => {
-        // Step: mark cancelled state so cooperative checks exit early.
-        cancelled = true;
-        // Step: reflect non-running state immediately for consumers polling isRunning().
-        running = false;
-        // Step: resolve done Promise eagerly; underlying evolution will short‑circuit soon.
-        try {
-          resolveDone?.();
-        } catch {
-          /* ignore */
-        }
-      },
-      { once: true },
-    );
-  } catch {
-    /* ignore listener wiring errors */
-  }
-
-  // Progressive scaling state
-  let currentDimension = INITIAL_MAZE_DIMENSION;
-
-  // --- Cross-maze curriculum transfer state ---
-  // Holds the best network from the most recently completed evolution run.
-  // Updated after each run finishes and passed as `initialBestNetwork` into the next
-  // run to encourage structural transfer to larger mazes. Starts undefined so the
-  // first maze evolves from a fresh random population.
-  let previousBestNetwork: INetwork | undefined;
-
-  /** Schedule a callback on the next animation frame with a setTimeout(0) fallback. */
-  const scheduleNextMaze = (cb: () => void) => {
-    try {
-      if (typeof requestAnimationFrame === 'function')
-        requestAnimationFrame(cb);
-      else setTimeout(cb, 0);
-    } catch {
-      setTimeout(cb, 0);
-    }
-  };
-
-  const runEvolution = async () => {
-    if (cancelled) {
-      running = false;
-      resolveDone?.();
-      return;
-    }
-    // Best network carried forward across curriculum phases (progressively larger mazes).
-    // This lets the next maze seed its population with the prior best to encourage transfer.
-    const settings = createEvolutionSettings(currentDimension);
-    const mazeLayout = settings.mazeFactory();
-    let solved = false;
-    try {
-      const result = await EvolutionEngine.runMazeEvolution({
-        mazeConfig: { maze: mazeLayout },
-        agentSimConfig: { maxSteps: settings.agentMaxSteps },
-        evolutionAlgorithmConfig: {
-          allowRecurrent: true,
-          popSize: settings.popSize,
-          maxStagnantGenerations: settings.maxStagnantGenerations,
-          minProgressToPass: MIN_PROGRESS_TO_PASS,
-          maxGenerations: settings.maxGenerations,
-          autoPauseOnSolve: false,
-          stopOnlyOnSolve: false,
-          lamarckianIterations: settings.lamarckianIterations,
-          lamarckianSampleSize: settings.lamarckianSampleSize,
-          initialBestNetwork: previousBestNetwork,
-        },
-        reportingConfig: {
-          dashboardManager: dashboard,
-          logEvery: PER_GENERATION_LOG_FREQUENCY,
-          label: `browser-procedural-${currentDimension}x${currentDimension}`,
-          paceEveryGeneration: true, // custom flag (consumed if supported) to yield between generations
-        },
-        cancellation: { isCancelled: () => cancelled },
-        signal: combinedSignal,
-      });
-      const runtimeResult = result as unknown as RuntimeEvolutionResult;
-      const progress = runtimeResult.bestResult?.progress;
-      // Capture & refine best network for seeding next curriculum phase (if any).
-      try {
-        const bestNet = runtimeResult.bestNetwork;
-        if (bestNet) {
-          const refined = NetworkRefinement.refineWinnerWithBackprop(
-            bestNet as unknown as Network,
-          );
-          previousBestNetwork = (refined as unknown as INetwork) || bestNet;
-        }
-      } catch {
-        /* ignore refinement */
-      }
-      solved = typeof progress === 'number' && progress >= MIN_PROGRESS_TO_PASS;
-      try {
-        console.log(
-          '[asciiMaze] maze complete',
-          currentDimension,
-          'solved?',
-          solved,
-          'progress',
-          progress,
-        );
-      } catch {
-        /* ignore */
-      }
-    } catch (error: unknown) {
-      console.error(
-        'Error while running procedural maze',
-        currentDimension,
-        error,
-      );
-    }
-
-    if (!cancelled && solved && currentDimension < MAX_MAZE_DIMENSION) {
-      currentDimension = Math.min(
-        currentDimension + MAZE_DIMENSION_INCREMENT,
-        MAX_MAZE_DIMENSION,
-      );
-      scheduleNextMaze(() => runEvolution());
-    } else {
-      running = false;
-      resolveDone?.();
-    }
-  };
-
-  // Kick off first maze immediately
-  runEvolution();
-
-  const handle: AsciiMazeRunHandle = {
-    stop: () => {
-      cancelled = true;
-      try {
-        internalController.abort();
-      } catch {
-        // ignore
-      }
-      // Reflect stopped state immediately.
-      running = false;
-    },
-    // Include AbortSignal aborted state so external aborts flip isRunning() without relying solely on listener side-effects.
-    isRunning: () => running && !cancelled && !combinedSignal.aborted,
-    done: Promise.resolve(donePromise).catch(() => {}) as Promise<void>,
-    onTelemetry: (telemetryCallback) =>
-      telemetryHub.add(
-        telemetryCallback as unknown as (
-          payload: Record<string, unknown>,
-        ) => void,
-      ),
-    getTelemetry: () => runtimeDashboard.getLastTelemetry?.(),
-  };
-
-  // (Pause UI removed; external host can manage pause via a future API if needed.)
-  return handle;
-};
 
-// UMD-style compatibility + deprecated global.
-// If loaded directly (no module loader), expose window.asciiMaze.start() and legacy asciiMazeStart().
-if (
-  typeof window !== 'undefined' &&
-  (window as unknown as RuntimeWindow).document
-) {
-  const globalWindow = window as unknown as RuntimeWindow;
-  globalWindow.asciiMaze = globalWindow.asciiMaze || {};
-  globalWindow.asciiMaze.start = start;
-  if (!globalWindow.asciiMazeStart) {
-    globalWindow.asciiMazeStart = (containerElement?: unknown) => {
-      console.warn(
-        '[asciiMaze] window.asciiMazeStart is deprecated; use import { start } ... or window.asciiMaze.start',
-      );
-      return start(containerElement as string | HTMLElement | undefined);
-    };
-  }
-  // Guard against duplicate auto-start
-  if (!globalWindow.asciiMaze._autoStarted) {
-    globalWindow.asciiMaze._autoStarted = true;
-    setTimeout(() => {
-      try {
-        if (document.getElementById(DEFAULT_CONTAINER_ID)) start();
-      } catch {
-        /* ignore */
-      }
-    }, AUTO_START_DELAY_MS);
-  }
-}
+export { start } from './browser-entry/browser-entry';
+export type {
+  AsciiMazeRunHandle,
+  BrowserEntryStartFunction,
+  BrowserEntryStartOptions,
+} from './browser-entry/browser-entry.types';