NeatapticTS

browser-entry/runtime

Top-level browser runtime facade for the Flappy Bird example.

This is the narrowest public browser entry with real behavior behind it. Calling start resolves the DOM host, installs the worker-backed runtime, initializes the HUD, and launches the evolve-to-playback loop that powers the demo. The surrounding services keep those responsibilities split, but this file is the place where they are folded back into one lifecycle.

The boundary matters because the browser demo is more than a canvas render: it is host setup, worker orchestration, telemetry, HUD updates, and shutdown control presented as one small API.

browser-entry/runtime/runtime.ts

RuntimeRunHandle

Public run handle returned by the browser runtime entrypoint.

The handle is intentionally minimal so callers can treat the demo like a long-running process with start/stop/status semantics.

start

start(
  container: RuntimeContainerTarget,
): Promise<FlappyBirdRunHandle>

Starts the Flappy Bird NeatapticTS browser demo and returns lifecycle controls.

This function is intentionally orchestration-focused:

  1. resolve runtime dependencies (DOM host, worker, host UI),
  2. initialize worker and telemetry plumbing,
  3. run the evolve -> playback -> HUD fold loop until stopped,
  4. expose a small stop/isRunning/done handle for callers.

Parameters:

Returns: Run handle for stop/state control.

Example:

const runHandle = await start('flappy-bird-output');
// later
runHandle.stop();
await runHandle.done;

browser-entry/runtime/runtime.types.ts

Core runtime contracts for the Flappy Bird browser demo.

The runtime boundary is where the browser-side application comes together: DOM host setup, worker creation, telemetry wiring, lifecycle control, and the configuration passed into the evolution loop.

RuntimeContainerTarget

Container argument accepted by the browser runtime start function.

Callers can either pass a host element directly or provide an element id for late resolution inside the runtime startup path.

RuntimeGlobalWindow

Browser window extension shape used for global runtime wiring.

This keeps the auto-start and compatibility globals typed without coupling the runtime modules directly to ad hoc window-property access.

RuntimeHostViewContext

Browser host view handles used by the runtime entry orchestration.

This is the typed bundle of canvas, HUD, and visualization handles returned by the host layer once the browser DOM has been prepared.

RuntimeMutableLifecycleState

Mutable lifecycle state used to coordinate stop semantics and completion.

The runtime loop is asynchronous and long-lived, so the browser keeps a small shared lifecycle object for idempotent shutdown and completion signaling.

RuntimeRunHandle

Public run handle returned by the browser runtime entrypoint.

The handle is intentionally minimal so callers can treat the demo like a long-running process with start/stop/status semantics.

RuntimeStartConfig

Static runtime configuration resolved before the browser loop starts.

These values define the high-level NEAT and network shape used for the whole browser session.

RuntimeStartContext

Shared runtime startup dependencies created before evolution begins.

Once this context exists, the browser has everything it needs to launch the actual evolution/playback loop.

RuntimeStartupPreviewHandle

Internal legend-preview handle used while a pre-playback canvas card is active.

browser-entry/runtime/runtime.startup.service.ts

Runtime startup helpers for the Flappy Bird browser demo.

These functions cover the pre-loop phase: resolve the host container, build a typed browser view, derive static config, create telemetry state, spawn the worker, and paint the initial HUD before evolution begins.

createRuntimeStartConfig

createRuntimeStartConfig(): RuntimeStartConfig

Resolves the static runtime configuration used during browser startup.

Centralizing the configuration fold here makes the runtime entry read as orchestration instead of constant plumbing.

Returns: Runtime configuration derived from shared constants.

createRuntimeStartContext

createRuntimeStartContext(
  container: RuntimeContainerTarget,
): RuntimeStartContext

Creates the shared runtime startup dependencies used by the entry orchestration.

This is the main bootstrap fold for browser startup. After it returns, the runtime has a host view, a worker channel, telemetry state, and a resolved configuration object.

Parameters:

Returns: Shared runtime start context for setup and loop launch.

initializeRuntimeHud

initializeRuntimeHud(
  runtimeStartContext: RuntimeStartContext,
): void

Paints the initial runtime HUD values before the evolution loop starts.

The HUD is seeded immediately so the page communicates that startup is in progress rather than appearing blank while the worker and loop are booting.

Parameters:

Returns: Nothing.

browser-entry/runtime/runtime.startup-preview.service.ts

finalizeRuntimeLegendPreview

finalizeRuntimeLegendPreview(
  legendPreviewHandle: RuntimeStartupPreviewHandle,
): Promise<void>

Waits for a runtime legend preview to finish and then stops its animation loop.

Parameters:

Returns: Nothing.

paintRuntimeStartupPreviewFrame

paintRuntimeStartupPreviewFrame(
  context: CanvasRenderingContext2D,
  input: { canvasWidthPx: number; canvasHeightPx: number; legendText: string; opacity: number; frameIndex: number; scrollBasePx: number; legendFontSizePx: number; },
): void

Paints one full startup-preview frame.

Parameters:

Returns: Nothing.

presentRuntimeGenerationPreview

presentRuntimeGenerationPreview(
  options: RuntimeGenerationPreviewOptions,
): Promise<void>

Presents a short generation title card before playback begins.

Every generation-ready event can reuse the same background-plus-neon style as the startup loading screen, but with a bounded fade-in, hold, and fade-out lifecycle that automatically completes before playback starts.

Parameters:

Returns: Nothing.

renderRuntimeStartupPreviewLegend

renderRuntimeStartupPreviewLegend(
  context: CanvasRenderingContext2D,
  input: { canvasWidthPx: number; canvasHeightPx: number; legendText: string; opacity: number; legendFontSizePx: number; },
): void

Draws the centered neon loading legend over the startup preview canvas.

Parameters:

Returns: Nothing.

resolveRuntimeStartupPreviewNowMs

resolveRuntimeStartupPreviewNowMs(): number

Resolves the best available startup-preview clock source.

Returns: Current timestamp in milliseconds.

startRuntimeLegendPreview

startRuntimeLegendPreview(
  options: RuntimeLegendPreviewOptions,
): RuntimeStartupPreviewHandle

Starts a legend-driven runtime preview loop on the main playback canvas.

This shared helper powers both the startup loading screen and the bounded generation title cards. The difference is whether the fade-out is scheduled up front or started later by calling complete().

Parameters:

Returns: Handle used to complete or stop the preview.

startRuntimeStartupPreview

startRuntimeStartupPreview(
  options: RuntimeStartupPreviewOptions,
): RuntimeStartupPreviewHandle

Starts the animated browser startup preview shown before the first birds appear.

This preview owns only the initial loading window. It reuses the existing background renderer so the canvas stays alive during worker initialization, then fades a centered loading legend out before the first playback session is allowed to begin.

Parameters:

Returns: Handle used to begin the exit transition or stop the preview outright.

browser-entry/runtime/runtime.startup-preview.utils.ts

resolveRuntimeStartupPreviewLegendFontSizePx

resolveRuntimeStartupPreviewLegendFontSizePx(
  canvasWidthPx: number,
  canvasHeightPx: number,
): number

Resolves a responsive legend font size for the startup preview.

Parameters:

Returns: Responsive legend font size in pixels.

resolveRuntimeStartupPreviewVisualState

resolveRuntimeStartupPreviewVisualState(
  input: { nowMs: number; previewStartTimeMs: number; previewExitStartTimeMs?: number | undefined; canvasWidthPx: number; canvasHeightPx: number; pipeScrollSpeedPxPerFrame: number; },
): RuntimeStartupPreviewVisualState

Resolves the visual state needed to draw one startup-preview frame.

The preview needs only a few derived values: the current opacity for the fade-in/fade-out lifecycle, a deterministic frame index and scroll offset for the animated background, and a responsive font size that stays readable on both compact and wide canvases.

Parameters:

Returns: Resolved visual state for the current startup-preview frame.

RuntimeStartupPreviewVisualState

Resolved visual state for one startup-preview render frame.

browser-entry/runtime/runtime.lifecycle.service.ts

Lifecycle and teardown helpers for the browser runtime.

The runtime behaves like a small application process. These helpers create the mutable state and public handle needed to stop it cleanly, terminate the worker, and resolve the completion promise exactly once.

createRuntimeLifecycleState

createRuntimeLifecycleState(): RuntimeMutableLifecycleState

Creates mutable lifecycle state for stop semantics and completion signaling.

The returned object is shared across runtime orchestration paths so both expected shutdown and failure-driven shutdown follow the same completion flow.

Returns: Mutable lifecycle state used by the run handle.

createRuntimeRunHandle

createRuntimeRunHandle(
  runtimeStartContext: RuntimeStartContext,
  runtimeLifecycleState: RuntimeMutableLifecycleState,
): FlappyBirdRunHandle

Builds the public run handle and binds it to runtime teardown behavior.

The handle is the user-facing control surface for the demo. Internally it is just a thin closure layer over the mutable lifecycle state and startup context.

Parameters:

Returns: Public run handle exposed to callers.

browser-entry/runtime/runtime.evolution-launch.service.ts

Launch wrapper for the long-running browser runtime loop.

The evolution loop itself is asynchronous and may surface unexpected errors. This launcher keeps the entrypoint clean by centralizing the catch path that routes failures into the HUD before shutting the runtime down.

launchRuntimeEvolution

launchRuntimeEvolution(
  runtimeStartContext: RuntimeStartContext,
  runtimeLifecycleState: RuntimeMutableLifecycleState,
  stop: () => void,
): void

Starts the runtime evolution loop and routes unexpected failures to the HUD.

This is the boundary between normal browser startup and the long-running async loop that drives evolution plus playback.

Parameters:

Returns: Nothing.

browser-entry/runtime/runtime.evolution-loop.service.ts

Long-running evolution/playback orchestration for the browser runtime.

This loop is the heart of the interactive demo. It repeatedly asks the worker for the next evolved generation, updates the HUD and network view, plays back that generation on the canvas, then folds the outcome into best-so-far browser state.

finalizeStartupPreview

finalizeStartupPreview(
  startupPreviewHandle: RuntimeStartupPreviewHandle | undefined,
): Promise<void>

Completes and tears down the startup preview when one is active.

Parameters:

Returns: Nothing.

requestGenerationWithOptionalStartupPreview

requestGenerationWithOptionalStartupPreview(
  options: { evolutionWorker: Worker; canvas: HTMLCanvasElement; context: CanvasRenderingContext2D; isStopped: () => boolean; showStartupPreview: boolean; },
): Promise<EvolutionGenerationPayload>

Requests the next generation and optionally shows the first-load startup preview.

The browser should only show the animated loading preview while the very first generation is still booting. Later generations can reuse the same canvas style through the separate generation-presentation path.

Parameters:

Returns: The next generation payload from the worker.

resolveGenerationPopulationNetworks

resolveGenerationPopulationNetworks(
  generationPayload: { populationNetworksJson?: Record<string, unknown>[] | undefined; },
  bestNetwork: default | undefined,
): default[]

Resolves the browser-side network cache for the current playback generation.

Playback birds are created from the generation population in stable array order, so the browser can reuse this ordered cache to redraw the network panel when the red-bird champion changes.

Parameters:

Returns: Ordered population networks for the upcoming playback session.

resolveGenerationPresentationLegendText

resolveGenerationPresentationLegendText(
  generation: number,
): string

Resolves the centered legend text used to present one ready generation.

Parameters:

Returns: Generation presentation legend text.

runRuntimeEvolutionLoop

runRuntimeEvolutionLoop(
  options: RuntimeEvolutionLoopOptions,
): Promise<void>

Runs generation orchestration and playback until a stop signal is observed.

The loop alternates between two phases:

  1. Evolve off-thread until the worker emits the next best-generation summary.
  2. Play that generation back on the main thread while streaming HUD updates.

This rhythm makes the demo feel like a live training dashboard instead of a one-shot batch job.

Parameters:

Returns: Nothing.

RuntimeEvolutionLoopOptions

Dependencies required to run the browser runtime evolution loop.

Grouping these dependencies into one object keeps the public loop entry more declarative and avoids a long positional parameter list.

browser-entry/runtime/runtime.telemetry.service.ts

Runtime telemetry helpers for live browser HUD updates.

The runtime tracks a small rolling window of operational signals such as HUD update frequency and minor GC activity. These are not part of the simulation itself; they are observability features for understanding how expensive the browser playback loop is.

createRuntimeTelemetryState

createRuntimeTelemetryState(): RuntimeTelemetryState

Creates telemetry state and attaches optional minor-GC observer.

Instrumentation is feature-gated so the demo can run in a low-noise mode when telemetry is not desired.

Returns: Initialized telemetry state.

disconnectRuntimeTelemetry

disconnectRuntimeTelemetry(
  telemetryState: RuntimeTelemetryState,
): void

Disconnects runtime telemetry observers.

This is part of runtime teardown and prevents instrumentation observers from lingering after the demo has stopped.

Parameters:

Returns: Nothing.

resolveInitialRuntimeTelemetryHudValues

resolveInitialRuntimeTelemetryHudValues(): { telemetryHeader: string; telemetryActivationsPerFrame: string; telemetrySimulationStepsPerRaf: string; telemetryHudUpdatesPerSecond: string; telemetryMinorGcPerMinute: string; }

Resolves default telemetry HUD values used before first playback updates.

The initial values make the instrumentation section self-describing even before the first playback frame arrives.

Returns: Initial telemetry field values.

resolveRuntimeTelemetryHudValues

resolveRuntimeTelemetryHudValues(
  frameStats: PlaybackFrameStats,
  telemetryState: RuntimeTelemetryState,
): { telemetryActivationsPerFrame: string; telemetrySimulationStepsPerRaf: string; telemetryHudUpdatesPerSecond: string; telemetryMinorGcPerMinute: string; }

Resolves per-frame telemetry HUD values and updates rolling windows.

On each published playback frame, the runtime folds the new telemetry sample into rolling windows and emits human-readable HUD strings.

Parameters:

Returns: Formatted telemetry HUD values for this frame.

RuntimeTelemetryState

Runtime telemetry mutable state used for rolling HUD metrics.

The state keeps timestamp windows rather than pre-aggregated counters so the HUD can report smoothed recent rates instead of lifetime totals.

browser-entry/runtime/runtime.browser-globals.service.ts

Browser-global wiring for the Flappy Bird runtime entrypoint.

The demo supports both module-style startup and traditional global-page usage. This module publishes the small global surface used by standalone docs pages and compatibility integrations.

installRuntimeBrowserGlobals

installRuntimeBrowserGlobals(
  startRuntime: RuntimeStartFunction,
): void

Publishes browser globals for demo auto-start and host-driven control.

This keeps the runtime friendly to static docs pages where the bundle may be loaded by script tag rather than imported programmatically.

This keeps parity with the asciiMaze entry style:

Parameters:

Returns: Nothing.

RuntimeStartFunction

RuntimeStartFunction(
  container: RuntimeContainerTarget | undefined,
): Promise<FlappyBirdRunHandle>

Runtime start function signature used by browser-global wiring.

The signature accepts an optional host target so global callers can either rely on the default container or explicitly direct the runtime to another element.

browser-entry/runtime/runtime.errors.ts

Runtime-specific error helpers for the browser entrypoint.

These errors normalize two user-facing failure modes: the browser cannot find the requested host container, or the runtime needs to report an unexpected failure back into the HUD.

resolveRequiredRuntimeHostElement

resolveRequiredRuntimeHostElement(
  container: RuntimeContainerTarget,
): HTMLElement

Resolves and validates the browser runtime host element.

The runtime accepts either a string id or a concrete element so this helper folds that loose input into one validated host node.

Parameters:

Returns: Resolved host element.

resolveRuntimeHudErrorStatus

resolveRuntimeHudErrorStatus(
  error: unknown,
): string

Formats unknown runtime failures into a stable HUD status string.

The HUD should not need to understand arbitrary thrown values, so this helper normalizes anything throwable into one readable status line.

Parameters:

Returns: Normalized status string for HUD output.

RuntimeContainerNotFoundError

Error raised when the browser runtime host container cannot be resolved.

This usually means the caller passed the wrong element id or attempted to start the demo before the target container existed in the DOM.

Generated from source JSDoc • GitHub