@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -0,0 +1,120 @@
+import type { DashboardManager } from '../dashboardManager';
+import type {
+  AsciiMazeTelemetrySnapshot,
+  DashboardPresentationAdapter,
+  DashboardTelemetryPayload,
+} from '../dashboardManager/dashboardManager.types';
+import type { EvolutionHostAdapter } from '../evolutionEngine/evolutionEngine.types';
+
+/**
+ * Public lifecycle handle returned by the browser demo entrypoint.
+ *
+ * @example
+ * ```ts
+ * const handle = await start('ascii-maze-output');
+ * const unsubscribe = handle.onTelemetry((telemetry) => {
+ *   console.log('generation', telemetry.generation);
+ * });
+ *
+ * await handle.done;
+ * unsubscribe();
+ * ```
+ */
+export interface AsciiMazeRunHandle {
+  /** Stop the running curriculum. This also aborts the internal signal. */
+  stop: () => void;
+  /** Whether the curriculum is still active. */
+  isRunning: () => boolean;
+  /** Promise that resolves when the curriculum finishes or is stopped. */
+  done: Promise<void>;
+  /** Subscribe to per-generation telemetry payloads emitted by the dashboard boundary. */
+  onTelemetry: (
+    listener: (telemetry: DashboardTelemetryPayload) => void,
+  ) => () => void;
+  /** Pull the most recently emitted telemetry snapshot, if one exists. */
+  getTelemetry: () => AsciiMazeTelemetrySnapshot | undefined;
+}
+
+/** Options accepted by the browser-hosted ASCII Maze entrypoint. */
+export interface BrowserEntryStartOptions {
+  /** Optional external abort signal that cooperatively stops the curriculum. */
+  signal?: AbortSignal;
+}
+
+/** Stable callable shape used by globals compatibility wiring. */
+export type BrowserEntryStartFunction = (
+  container?: string | HTMLElement,
+  opts?: BrowserEntryStartOptions,
+) => Promise<AsciiMazeRunHandle>;
+
+/** Runtime AbortSignal shape used for older or polyfilled environments. */
+export interface RuntimeAbortSignal {
+  aborted?: boolean;
+  onabort?: (() => void) | null;
+  addEventListener: AbortSignal['addEventListener'];
+  removeEventListener: AbortSignal['removeEventListener'];
+  dispatchEvent: AbortSignal['dispatchEvent'];
+  reason?: unknown;
+  throwIfAborted?: () => void;
+}
+
+/** AbortSignal constructor shape with optional static composition helpers. */
+export interface RuntimeAbortSignalConstructor {
+  prototype: AbortSignal;
+  new (): AbortSignal;
+  any?: (signals: AbortSignal[]) => AbortSignal;
+}
+
+/** Global namespace exposed for direct browser-script loading compatibility. */
+export interface RuntimeWindow extends Window {
+  asciiMaze?: {
+    start?: BrowserEntryStartFunction;
+    _autoStarted?: boolean;
+    [key: string]: unknown;
+  };
+  asciiMazePaused?: boolean;
+  asciiMazeStart?: (containerElement?: unknown) => unknown;
+  [key: string]: unknown;
+}
+
+/** Resolved host elements used by logger, dashboard, and resize services. */
+export interface BrowserEntryHostElements {
+  hostElement: HTMLElement | null;
+  archiveElement: HTMLElement | null;
+  liveElement: HTMLElement | null;
+  observeTarget: HTMLElement | null;
+}
+
+/** Evolution settings used for a single procedural maze phase. */
+export interface BrowserEntryEvolutionSettings {
+  agentMaxSteps: number;
+  popSize: number;
+  maxStagnantGenerations: number;
+  maxGenerations: number;
+  lamarckianIterations: number;
+  lamarckianSampleSize: number;
+  mazeFactory: () => string[];
+}
+
+/** Lightweight telemetry hub contract shared between host and public handle. */
+export interface BrowserEntryTelemetryHub<TTelemetry extends object> {
+  add(listener: (payload: TTelemetry) => void): () => void;
+  dispatch(payload: TTelemetry): void;
+}
+
+/** Browser host services assembled for one running demo instance. */
+export interface BrowserEntryHostServices {
+  dashboard: DashboardManager;
+  runtimeDashboard: DashboardPresentationAdapter;
+  telemetryHub: BrowserEntryTelemetryHub<DashboardTelemetryPayload>;
+  disposeResizeHandling: () => void;
+}
+
+/** State and callbacks used by the curriculum runtime service. */
+export interface BrowserEntryCurriculumContext {
+  dashboard: DashboardManager;
+  combinedSignal: AbortSignal;
+  isCancelled: () => boolean;
+  finish: () => void;
+  hostAdapter: EvolutionHostAdapter;
+}

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

@@ -0,0 +1,98 @@
+import { MazeGenerator } from '../mazes';
+import { BROWSER_ENTRY_CONSTANTS as C } from './browser-entry.constants';
+import type {
+  BrowserEntryEvolutionSettings,
+  BrowserEntryHostElements,
+} from './browser-entry.types';
+
+/**
+ * Resolve the browser host elements used by the demo logger and dashboard.
+ *
+ * @param container - Element id or host element provided by the caller.
+ * @returns Resolved host, archive, live, and resize-observer targets.
+ */
+export const resolveBrowserEntryHostElements = (
+  container: string | HTMLElement,
+): BrowserEntryHostElements => {
+  const hostElement =
+    typeof container === 'string'
+      ? document.getElementById(container)
+      : container;
+  const archiveElement = hostElement
+    ? (hostElement.querySelector('#ascii-maze-archive') as HTMLElement | null)
+    : null;
+  const liveElement = hostElement
+    ? (hostElement.querySelector('#ascii-maze-live') as HTMLElement | null)
+    : null;
+
+  return {
+    hostElement,
+    archiveElement,
+    liveElement,
+    observeTarget:
+      hostElement ?? document.getElementById(C.DEFAULT_CONTAINER_ID),
+  };
+};
+
+/**
+ * Build immutable evolution settings for a single maze dimension.
+ *
+ * @param dimension - Side length in cells for the procedural square maze.
+ * @returns Per-phase evolution settings consumed by the curriculum runtime.
+ */
+export const createBrowserEvolutionSettings = (
+  dimension: number,
+): BrowserEntryEvolutionSettings => {
+  return {
+    agentMaxSteps: C.AGENT_MAX_STEPS,
+    popSize: C.POPULATION_SIZE,
+    maxStagnantGenerations: C.DEFAULT_MAX_STAGNANT_GENERATIONS,
+    maxGenerations: C.DEFAULT_MAX_GENERATIONS,
+    lamarckianIterations: C.LAMARCKIAN_ITERATIONS,
+    lamarckianSampleSize: C.LAMARCKIAN_SAMPLE_SIZE,
+    mazeFactory: () => new MazeGenerator(dimension, dimension).generate(),
+  };
+};
+
+/**
+ * Schedule follow-up curriculum work on the next animation tick when possible.
+ *
+ * @param callback - Follow-up phase callback.
+ */
+export const scheduleBrowserEntryFrame = (callback: () => void): void => {
+  try {
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(callback);
+      return;
+    }
+  } catch {
+    // Fall through to setTimeout when the browser scheduler is unavailable.
+  }
+
+  setTimeout(callback, 0);
+};
+
+/**
+ * Determine whether a reported progress value counts as solved for curriculum advancement.
+ *
+ * @param progress - Runtime progress emitted by the evolution layer.
+ * @returns Whether the maze phase should advance to the next dimension.
+ */
+export const didSolveBrowserMaze = (progress: unknown): boolean => {
+  return typeof progress === 'number' && progress >= C.MIN_PROGRESS_TO_PASS;
+};
+
+/**
+ * Advance the procedural maze dimension without exceeding the configured maximum.
+ *
+ * @param currentDimension - Current maze side length.
+ * @returns Next side length to use.
+ */
+export const getNextBrowserMazeDimension = (
+  currentDimension: number,
+): number => {
+  return Math.min(
+    currentDimension + C.MAZE_DIMENSION_INCREMENT,
+    C.MAX_MAZE_DIMENSION,
+  );
+};