@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -0,0 +1,14 @@
+/**
+ * Compatibility facade for the dedicated browser-entry service modules.
+ *
+ * The concrete implementations now live in focused files so callers can keep
+ * importing from this stable boundary while internals evolve independently.
+ */
+
+export { composeBrowserEntryAbortSignal } from './browser-entry.abort.services';
+export { runBrowserEntryCurriculum } from './browser-entry.curriculum.services';
+export {
+  createBrowserEntryEvolutionHostAdapter,
+  installBrowserEntryGlobals,
+} from './browser-entry.globals.services';
+export { createBrowserEntryHostServices } from './browser-entry.host.services';

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

@@ -0,0 +1,129 @@
+/**
+ * Public browser entry facade for the ASCII Maze demo module boundary.
+ *
+ * The folder now owns host bootstrap, runtime orchestration, globals
+ * compatibility, and resize handling behind focused helpers. This facade keeps
+ * the public API stable while presenting a small orchestration-first surface.
+ */
+
+import { BROWSER_ENTRY_CONSTANTS as C } from './browser-entry.constants';
+import {
+  composeBrowserEntryAbortSignal,
+  createBrowserEntryEvolutionHostAdapter,
+  createBrowserEntryHostServices,
+  installBrowserEntryGlobals,
+  runBrowserEntryCurriculum,
+} from './browser-entry.services';
+import type {
+  AsciiMazeRunHandle,
+  BrowserEntryStartOptions,
+} from './browser-entry.types';
+import { resolveBrowserEntryHostElements } from './browser-entry.utils';
+
+/**
+ * Start the browser-hosted ASCII Maze curriculum demo.
+ *
+ * @remarks
+ * The run starts with a small procedural maze and carries the best refined
+ * network forward into larger mazes until the configured maximum size is
+ * reached or cancellation stops the curriculum.
+ *
+ * @example
+ * ```ts
+ * const handle = await start('ascii-maze-output');
+ * handle.onTelemetry((telemetry) => console.log(telemetry));
+ * await handle.done;
+ * ```
+ *
+ * @param container - Element id or host element for the browser demo.
+ * @param opts - Optional cooperative cancellation settings.
+ * @returns Lifecycle handle for stop, status, completion, and telemetry access.
+ */
+export const start = async (
+  container: string | HTMLElement = C.DEFAULT_CONTAINER_ID,
+  opts: BrowserEntryStartOptions = {},
+): Promise<AsciiMazeRunHandle> => {
+  // Step 1: Resolve host elements and attach browser-specific services.
+  const hostElements = resolveBrowserEntryHostElements(container);
+  const hostServices = createBrowserEntryHostServices(hostElements);
+  const hostAdapter = createBrowserEntryEvolutionHostAdapter();
+
+  // Step 2: Create lifecycle state and compose cooperative cancellation.
+  let cancelled = false;
+  let running = true;
+  let finalized = false;
+  const internalController = new AbortController();
+  let resolveDonePromise = () => {};
+  const done = new Promise<void>((resolve) => {
+    resolveDonePromise = resolve;
+  });
+  const finalizeRun = () => {
+    if (finalized) {
+      return;
+    }
+
+    finalized = true;
+    running = false;
+    hostServices.disposeResizeHandling();
+    resolveDonePromise();
+  };
+  const combinedSignal = composeBrowserEntryAbortSignal(
+    internalController,
+    opts.signal,
+  );
+
+  if (combinedSignal.aborted) {
+    cancelled = true;
+    finalizeRun();
+  } else {
+    try {
+      combinedSignal.addEventListener(
+        'abort',
+        () => {
+          cancelled = true;
+          finalizeRun();
+        },
+        { once: true },
+      );
+    } catch {
+      // Ignore listener wiring failures in older or test environments.
+    }
+  }
+
+  // Step 3: Start curriculum orchestration only when the run is still active.
+  if (!cancelled) {
+    runBrowserEntryCurriculum({
+      dashboard: hostServices.dashboard,
+      combinedSignal,
+      isCancelled: () => cancelled,
+      finish: finalizeRun,
+      hostAdapter,
+    });
+  }
+
+  // Step 4: Return the stable lifecycle handle for embedding hosts.
+  return {
+    stop: () => {
+      cancelled = true;
+      finalizeRun();
+      try {
+        internalController.abort();
+      } catch {
+        // Ignore duplicate aborts or unsupported environments.
+      }
+    },
+    isRunning: () => running && !cancelled && !combinedSignal.aborted,
+    done,
+    onTelemetry: (telemetryCallback) =>
+      hostServices.telemetryHub.add(telemetryCallback),
+    getTelemetry: () => hostServices.runtimeDashboard.getLastTelemetry?.(),
+  };
+};
+
+installBrowserEntryGlobals(start);
+
+export type {
+  AsciiMazeRunHandle,
+  BrowserEntryStartFunction,
+  BrowserEntryStartOptions,
+} from './browser-entry.types';

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,
+  );
+};