@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/asciiMaze/browser-entry/README.md

@@ -0,0 +1,196 @@
+# browser-entry
+
+## browser-entry/browser-entry.types.ts
+
+### AsciiMazeRunHandle
+
+Public lifecycle handle returned by the browser demo entrypoint.
+
+### BrowserEntryCurriculumContext
+
+State and callbacks used by the curriculum runtime service.
+
+### BrowserEntryEvolutionSettings
+
+Evolution settings used for a single procedural maze phase.
+
+### BrowserEntryHostElements
+
+Resolved host elements used by logger, dashboard, and resize services.
+
+### BrowserEntryHostServices
+
+Browser host services assembled for one running demo instance.
+
+### BrowserEntryStartFunction
+
+`(container: string | HTMLElement | undefined, opts: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryStartOptions | undefined) => Promise<import("test/examples/asciiMaze/browser-entry/browser-entry.types").AsciiMazeRunHandle>`
+
+Stable callable shape used by globals compatibility wiring.
+
+### BrowserEntryStartOptions
+
+Options accepted by the browser-hosted ASCII Maze entrypoint.
+
+### BrowserEntryTelemetryHub
+
+Lightweight telemetry hub contract shared between host and public handle.
+
+### RuntimeAbortSignal
+
+Runtime AbortSignal shape used for older or polyfilled environments.
+
+### RuntimeAbortSignalConstructor
+
+AbortSignal constructor shape with optional static composition helpers.
+
+### RuntimeWindow
+
+Global namespace exposed for direct browser-script loading compatibility.
+
+## browser-entry/browser-entry.ts
+
+### browser-entry
+
+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.
+
+### AsciiMazeRunHandle
+
+Public lifecycle handle returned by the browser demo entrypoint.
+
+### BrowserEntryStartFunction
+
+`(container: string | HTMLElement | undefined, opts: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryStartOptions | undefined) => Promise<import("test/examples/asciiMaze/browser-entry/browser-entry.types").AsciiMazeRunHandle>`
+
+Stable callable shape used by globals compatibility wiring.
+
+### BrowserEntryStartOptions
+
+Options accepted by the browser-hosted ASCII Maze entrypoint.
+
+### start
+
+`(container: string | HTMLElement, opts: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryStartOptions) => Promise<import("test/examples/asciiMaze/browser-entry/browser-entry.types").AsciiMazeRunHandle>`
+
+## browser-entry/browser-entry.services.ts
+
+### browser-entry.services
+
+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.
+
+### composeBrowserEntryAbortSignal
+
+`(internalController: AbortController, externalSignal: AbortSignal | undefined) => AbortSignal`
+
+### createBrowserEntryEvolutionHostAdapter
+
+`() => import("test/examples/asciiMaze/evolutionEngine/evolutionEngine.types").EvolutionHostAdapter`
+
+### createBrowserEntryHostServices
+
+`(hostElements: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryHostElements) => import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryHostServices`
+
+### installBrowserEntryGlobals
+
+`(start: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryStartFunction) => void`
+
+### runBrowserEntryCurriculum
+
+`(context: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryCurriculumContext) => void`
+
+## browser-entry/browser-entry.constants.ts
+
+### browser-entry.constants
+
+Shared constants for the browser-hosted ASCII Maze demo lifecycle.
+
+These values keep the browser entry facade declarative while the host,
+resize, and curriculum services consume a single named configuration table.
+
+### BROWSER_ENTRY_CONSTANTS
+
+## browser-entry/browser-entry.host.services.ts
+
+### createBrowserEntryHostServices
+
+`(hostElements: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryHostElements) => import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryHostServices`
+
+### createTelemetryHub
+
+`() => import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryTelemetryHub<TTelemetry>`
+
+Create a minimal telemetry hub backed by a Set of listeners.
+
+Returns: A small hub optimized for browser demo listener counts.
+
+### installResizeRedraw
+
+`(observeTarget: HTMLElement | null, runtimeDashboard: import("test/examples/asciiMaze/dashboardManager/dashboardManager.types").DashboardPresentationAdapter) => () => void`
+
+Attach dashboard redraw behavior to host resizes and return a cleanup function.
+
+Parameters:
+- `observeTarget` - - Element whose width should trigger redraw checks.
+- `runtimeDashboard` - - Shared dashboard presentation adapter with redraw support.
+
+Returns: Cleanup function that removes active observers or listeners.
+
+### safelyRedrawDashboard
+
+`(runtimeDashboard: import("test/examples/asciiMaze/dashboardManager/dashboardManager.types").DashboardPresentationAdapter) => void`
+
+Safely request a dashboard redraw without letting host issues break the run.
+
+Parameters:
+- `runtimeDashboard` - - Shared dashboard presentation adapter with optional redraw support.
+
+## browser-entry/browser-entry.abort.services.ts
+
+### composeBrowserEntryAbortSignal
+
+`(internalController: AbortController, externalSignal: AbortSignal | undefined) => AbortSignal`
+
+## browser-entry/browser-entry.globals.services.ts
+
+### createBrowserEntryEvolutionHostAdapter
+
+`() => import("test/examples/asciiMaze/evolutionEngine/evolutionEngine.types").EvolutionHostAdapter`
+
+### installBrowserEntryGlobals
+
+`(start: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryStartFunction) => void`
+
+## browser-entry/browser-entry.curriculum.services.ts
+
+### runBrowserEntryCurriculum
+
+`(context: import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryCurriculumContext) => void`
+
+## browser-entry/browser-entry.utils.ts
+
+### createBrowserEvolutionSettings
+
+`(dimension: number) => import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryEvolutionSettings`
+
+### didSolveBrowserMaze
+
+`(progress: unknown) => boolean`
+
+### getNextBrowserMazeDimension
+
+`(currentDimension: number) => number`
+
+### resolveBrowserEntryHostElements
+
+`(container: string | HTMLElement) => import("test/examples/asciiMaze/browser-entry/browser-entry.types").BrowserEntryHostElements`
+
+### scheduleBrowserEntryFrame
+
+`(callback: () => void) => void`

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

@@ -0,0 +1,95 @@
+import type {
+  RuntimeAbortSignal,
+  RuntimeAbortSignalConstructor,
+} from './browser-entry.types';
+
+/**
+ * Browser abort-composition service boundary for the ASCII Maze browser entry.
+ *
+ * This leaf module isolates runtime-safe signal composition so browser-entry
+ * orchestration can stay focused on lifecycle flow instead of platform quirks.
+ */
+
+/**
+ * Compose an internal and external abort signal into one cooperative signal.
+ *
+ * @param internalController - Internal controller owned by the browser run handle.
+ * @param externalSignal - Optional caller-provided signal.
+ * @returns A signal that aborts when either source aborts.
+ */
+export const composeBrowserEntryAbortSignal = (
+  internalController: AbortController,
+  externalSignal?: AbortSignal,
+): AbortSignal => {
+  if (!externalSignal) {
+    return internalController.signal;
+  }
+
+  const runtimeExternalSignal = externalSignal as RuntimeAbortSignal;
+  const internalSignal = internalController.signal;
+
+  switch (true) {
+    case !!runtimeExternalSignal.aborted:
+      return runtimeExternalSignal as unknown as AbortSignal;
+
+    case typeof (AbortSignal as unknown as RuntimeAbortSignalConstructor)
+      .any === 'function': {
+      try {
+        return (AbortSignal as unknown as RuntimeAbortSignalConstructor).any!([
+          runtimeExternalSignal as unknown as AbortSignal,
+          internalSignal,
+        ]);
+      } catch {
+        // Fall through to manual wiring when native composition is unavailable at runtime.
+      }
+      break;
+    }
+
+    default:
+      break;
+  }
+
+  try {
+    runtimeExternalSignal.addEventListener(
+      'abort',
+      () => {
+        try {
+          internalController.abort();
+        } catch {
+          // Ignore duplicate or unsupported aborts.
+        }
+      },
+      { once: true },
+    );
+  } catch {
+    // Ignore event wiring failures in minimal DOM environments.
+  }
+
+  try {
+    runtimeExternalSignal.onabort = () => {
+      try {
+        internalController.abort();
+      } catch {
+        // Ignore duplicate or unsupported aborts.
+      }
+    };
+  } catch {
+    // Ignore environments that do not allow onabort assignment.
+  }
+
+  try {
+    queueMicrotask(() => {
+      if (runtimeExternalSignal.aborted) {
+        try {
+          internalController.abort();
+        } catch {
+          // Ignore duplicate or unsupported aborts.
+        }
+      }
+    });
+  } catch {
+    // Ignore environments that do not expose queueMicrotask.
+  }
+
+  return internalSignal;
+};

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

@@ -0,0 +1,23 @@
+/**
+ * Shared constants for the browser-hosted ASCII Maze demo lifecycle.
+ *
+ * These values keep the browser entry facade declarative while the host,
+ * resize, and curriculum services consume a single named configuration table.
+ */
+export const BROWSER_ENTRY_CONSTANTS = {
+  DEFAULT_CONTAINER_ID: 'ascii-maze-output',
+  RESIZE_WIDTH_THRESHOLD: 8,
+  RESIZE_DEBOUNCE_MS: 120,
+  AUTO_START_DELAY_MS: 20,
+  MIN_PROGRESS_TO_PASS: 90,
+  DEFAULT_MAX_STAGNANT_GENERATIONS: 50,
+  DEFAULT_MAX_GENERATIONS: 100,
+  PER_GENERATION_LOG_FREQUENCY: 1,
+  INITIAL_MAZE_DIMENSION: 8,
+  MAX_MAZE_DIMENSION: 40,
+  MAZE_DIMENSION_INCREMENT: 4,
+  AGENT_MAX_STEPS: 600,
+  POPULATION_SIZE: 20,
+  LAMARCKIAN_ITERATIONS: 4,
+  LAMARCKIAN_SAMPLE_SIZE: 12,
+} as const;

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

@@ -0,0 +1,115 @@
+import { EvolutionEngine } from '../evolutionEngine';
+import { resolveMazeEvolutionPhaseOutcome } from '../evolutionEngine';
+import type { INetwork } from '../interfaces';
+import { BROWSER_ENTRY_CONSTANTS as C } from './browser-entry.constants';
+import type { BrowserEntryCurriculumContext } from './browser-entry.types';
+import {
+  createBrowserEvolutionSettings,
+  getNextBrowserMazeDimension,
+  scheduleBrowserEntryFrame,
+} from './browser-entry.utils';
+
+/**
+ * Browser curriculum-runtime service boundary for the ASCII Maze browser entry.
+ *
+ * This module now owns browser-only curriculum progression concerns: dimension
+ * scheduling, frame pacing, and lifecycle completion. Evolution-phase result
+ * interpretation and winner carry-over refinement live behind the engine-owned
+ * curriculum helper so browser-entry stays focused on host runtime behavior.
+ */
+
+/**
+ * Run the progressive browser curriculum across increasingly larger mazes.
+ *
+ * @param context - Runtime dashboard, cancellation, and completion callbacks for one browser session.
+ * @returns Nothing.
+ */
+export const runBrowserEntryCurriculum = (
+  context: BrowserEntryCurriculumContext,
+): void => {
+  let currentDimension: number = C.INITIAL_MAZE_DIMENSION;
+  let previousBestNetwork: INetwork | undefined;
+
+  void runCurrentPhase();
+
+  async function runCurrentPhase(): Promise<void> {
+    if (context.isCancelled()) {
+      context.finish();
+      return;
+    }
+
+    const settings = createBrowserEvolutionSettings(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: C.MIN_PROGRESS_TO_PASS,
+          maxGenerations: settings.maxGenerations,
+          autoPauseOnSolve: false,
+          stopOnlyOnSolve: false,
+          lamarckianIterations: settings.lamarckianIterations,
+          lamarckianSampleSize: settings.lamarckianSampleSize,
+          initialBestNetwork: previousBestNetwork,
+        },
+        reportingConfig: {
+          dashboardManager: context.dashboard,
+          hostAdapter: context.hostAdapter,
+          logEvery: C.PER_GENERATION_LOG_FREQUENCY,
+          label: `browser-procedural-${currentDimension}x${currentDimension}`,
+          paceEveryGeneration: true,
+        },
+        cancellation: { isCancelled: () => context.isCancelled() },
+        signal: context.combinedSignal,
+      });
+      const phaseOutcome = resolveMazeEvolutionPhaseOutcome(
+        result,
+        previousBestNetwork,
+        C.MIN_PROGRESS_TO_PASS,
+      );
+      const progress = phaseOutcome.progress;
+
+      previousBestNetwork = phaseOutcome.nextBestNetwork;
+      solved = phaseOutcome.solved;
+
+      try {
+        console.log(
+          '[asciiMaze] maze complete',
+          currentDimension,
+          'solved?',
+          solved,
+          'progress',
+          progress,
+        );
+      } catch {
+        // Ignore console failures in minimal or proxied environments.
+      }
+    } catch (error: unknown) {
+      console.error(
+        'Error while running procedural maze',
+        currentDimension,
+        error,
+      );
+    }
+
+    if (
+      !context.isCancelled() &&
+      solved &&
+      currentDimension < C.MAX_MAZE_DIMENSION
+    ) {
+      currentDimension = getNextBrowserMazeDimension(currentDimension);
+      scheduleBrowserEntryFrame(() => {
+        void runCurrentPhase();
+      });
+      return;
+    }
+
+    context.finish();
+  }
+};

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

@@ -0,0 +1,106 @@
+import { BROWSER_ENTRY_CONSTANTS as C } from './browser-entry.constants';
+import type {
+  BrowserEntryStartFunction,
+  RuntimeWindow,
+} from './browser-entry.types';
+import type { EvolutionHostAdapter } from '../evolutionEngine/evolutionEngine.types';
+
+/**
+ * Browser globals-compatibility service boundary for the ASCII Maze browser entry.
+ *
+ * This module isolates script-loader compatibility and guarded auto-start
+ * behavior so runtime orchestration can stay focused on session lifecycle.
+ */
+
+/**
+ * Create the browser-owned engine host adapter used for pause polling and solve notifications.
+ *
+ * @returns Host adapter that keeps browser globals and DOM events out of engine internals.
+ */
+export const createBrowserEntryEvolutionHostAdapter =
+  (): EvolutionHostAdapter => ({
+    isPauseRequested: (): boolean => {
+      if (typeof window === 'undefined') {
+        return false;
+      }
+
+      return (window as RuntimeWindow).asciiMazePaused === true;
+    },
+    handleStop: ({
+      reason,
+      maze,
+      completedGenerations,
+      progress,
+      requestHostPause,
+    }): void => {
+      if (typeof window === 'undefined') {
+        return;
+      }
+
+      const globalWindow = window as RuntimeWindow;
+
+      if (reason === 'solved' && requestHostPause) {
+        globalWindow.asciiMazePaused = true;
+      }
+
+      if (reason !== 'solved') {
+        return;
+      }
+
+      try {
+        window.dispatchEvent(
+          new CustomEvent('asciiMazeSolved', {
+            detail: {
+              maze,
+              generations: completedGenerations,
+              progress,
+            },
+          }),
+        );
+      } catch {
+        // Ignore CustomEvent dispatch failures in restricted browser runtimes.
+      }
+    },
+  });
+
+/**
+ * Install browser globals and one-time auto-start compatibility hooks.
+ *
+ * @param start - Public browser entry function to expose on the window namespace.
+ * @returns Nothing.
+ */
+export const installBrowserEntryGlobals = (
+  start: BrowserEntryStartFunction,
+): void => {
+  if (typeof window === 'undefined' || !(window as RuntimeWindow).document) {
+    return;
+  }
+
+  const globalWindow = window 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);
+    };
+  }
+
+  if (globalWindow.asciiMaze._autoStarted) {
+    return;
+  }
+
+  globalWindow.asciiMaze._autoStarted = true;
+  setTimeout(() => {
+    try {
+      if (document.getElementById(C.DEFAULT_CONTAINER_ID)) {
+        void start();
+      }
+    } catch {
+      // Ignore auto-start failures so browser embedding can recover manually.
+    }
+  }, C.AUTO_START_DELAY_MS);
+};

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

@@ -0,0 +1,157 @@
+import { BrowserTerminalUtility } from '../browserTerminalUtility';
+import { createBrowserLogger } from '../browserLogger';
+import { DashboardManager } from '../dashboardManager';
+import type {
+  DashboardPresentationAdapter,
+  DashboardTelemetryPayload,
+} from '../dashboardManager/dashboardManager.types';
+import { BROWSER_ENTRY_CONSTANTS as C } from './browser-entry.constants';
+import type {
+  BrowserEntryHostElements,
+  BrowserEntryHostServices,
+  BrowserEntryTelemetryHub,
+} from './browser-entry.types';
+
+/**
+ * Browser host-service boundary for the ASCII Maze browser entry.
+ *
+ * This module owns the DOM-facing dashboard wiring, telemetry fan-out, and
+ * resize redraw behavior used by one browser-hosted ASCII Maze session.
+ */
+
+/**
+ * Create the browser host services used by one ASCII Maze demo run.
+ *
+ * @param hostElements - Resolved host elements for live output, archive output, and resize observation.
+ * @returns Dashboard, telemetry hub, runtime dashboard adapter, and resize cleanup.
+ */
+export const createBrowserEntryHostServices = (
+  hostElements: BrowserEntryHostElements,
+): BrowserEntryHostServices => {
+  const clearer = BrowserTerminalUtility.createTerminalClearer(
+    hostElements.liveElement ?? undefined,
+  );
+  const liveLogger = createBrowserLogger(hostElements.liveElement ?? undefined);
+  const archiveLogger = createBrowserLogger(
+    hostElements.archiveElement ?? undefined,
+  );
+  const dashboard = new DashboardManager(
+    clearer,
+    liveLogger as unknown as (...args: unknown[]) => void,
+    archiveLogger as unknown as (...args: unknown[]) => void,
+  );
+  const telemetryHub = createTelemetryHub<DashboardTelemetryPayload>();
+  const runtimeDashboard: DashboardPresentationAdapter = dashboard;
+
+  runtimeDashboard._telemetryHook = (telemetry: DashboardTelemetryPayload) => {
+    telemetryHub.dispatch(telemetry);
+  };
+
+  return {
+    dashboard,
+    runtimeDashboard,
+    telemetryHub,
+    disposeResizeHandling: installResizeRedraw(
+      hostElements.observeTarget,
+      runtimeDashboard,
+    ),
+  };
+};
+
+/**
+ * Create a minimal telemetry hub backed by a Set of listeners.
+ *
+ * @returns A small hub optimized for browser demo listener counts.
+ */
+function createTelemetryHub<
+  TTelemetry extends Record<string, unknown>,
+>(): BrowserEntryTelemetryHub<TTelemetry> {
+  const listeners = new Set<(payload: TTelemetry) => void>();
+
+  return {
+    add(listener: (payload: TTelemetry) => void): () => void {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    dispatch(payload: TTelemetry): void {
+      const snapshot = Array.from(listeners);
+      for (const listener of snapshot) {
+        try {
+          listener(payload);
+        } catch {
+          // Ignore listener failures so telemetry never destabilizes evolution.
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Attach dashboard redraw behavior to host resizes and return a cleanup function.
+ *
+ * @param observeTarget - Element whose width should trigger redraw checks.
+ * @param runtimeDashboard - Shared dashboard presentation adapter with redraw support.
+ * @returns Cleanup function that removes active observers or listeners.
+ */
+function installResizeRedraw(
+  observeTarget: HTMLElement | null,
+  runtimeDashboard: DashboardPresentationAdapter,
+): () => void {
+  if (!observeTarget) {
+    return () => {};
+  }
+
+  try {
+    if (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) > C.RESIZE_WIDTH_THRESHOLD) {
+            lastObservedWidth = width;
+            safelyRedrawDashboard(runtimeDashboard);
+          }
+        }
+      });
+      resizeObserver.observe(observeTarget);
+      return () => resizeObserver.disconnect();
+    }
+
+    let debounceTimer: number | undefined;
+    const handleResize = () => {
+      if (typeof debounceTimer === 'number') {
+        clearTimeout(debounceTimer);
+      }
+
+      debounceTimer = window.setTimeout(() => {
+        safelyRedrawDashboard(runtimeDashboard);
+      }, C.RESIZE_DEBOUNCE_MS);
+    };
+
+    window.addEventListener('resize', handleResize);
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      if (typeof debounceTimer === 'number') {
+        clearTimeout(debounceTimer);
+      }
+    };
+  } catch {
+    return () => {};
+  }
+}
+
+/**
+ * Safely request a dashboard redraw without letting host issues break the run.
+ *
+ * @param runtimeDashboard - Shared dashboard presentation adapter with optional redraw support.
+ */
+function safelyRedrawDashboard(
+  runtimeDashboard: DashboardPresentationAdapter,
+): void {
+  try {
+    runtimeDashboard.redraw?.([], undefined);
+  } catch {
+    // Ignore redraw failures because they are presentation-only.
+  }
+}