browser-entry/network-view

Network-view orchestration for the browser-side architecture panel.

This module is the browser-facing fold from a live evolved controller to a readable inspection panel. It does not own the low-level drawing primitives, and it does not invent topology semantics from scratch. Instead it composes both into one higher-level question: how should this network be laid out so a human can actually learn from it?

The boundary exists because "draw the network" hides several distinct jobs: summarize topology, size the panel, place nodes, choose overlay policy, and then delegate the final painting work. Keeping those steps together here makes the generated README read like an inspection chapter instead of a pile of canvas helpers.

browser-entry/network-view/network-view.ts

clampRecommendedNetworkHeightPx

clampRecommendedNetworkHeightPx(
  recommendedHeightPx: number,
): number

Clamps a recommended network height into the configured panel range.

Parameters:

• recommendedHeightPx - - Recommended panel height.

Returns: Clamped panel height.

createPositionByNodeIndex

createPositionByNodeIndex(
  centeredPositionedNodes: PositionedNetworkNodeLike[],
): Map<number, PositionedNetworkNodeLike>

Builds a node-index lookup map for resolved positioned nodes.

Parameters:

• centeredPositionedNodes - - Positioned nodes after centering.

Returns: Map keyed by node index.

drawNetworkVisualization

drawNetworkVisualization(
  context: CanvasRenderingContext2D,
  network: default | undefined,
  inputSize: number,
  outputSize: number,
  hoverState: NetworkVisualizationHoverState | undefined,
): NetworkVisualizationPositionedScene

Draws a complete, layer-based visualization of the active network.

Conceptually, this is the main fold from network object to finished panel: resolve scene state, compute layout, paint the graph, then paint overlays.

Parameters:

• context - - Canvas 2D drawing context.
• network - - Network to visualize.
• inputSize - - Input-layer size.
• outputSize - - Output-layer size.
• hoverState - - Optional host-owned hover state for interactive emphasis.

Returns: Positioned node snapshot reused by host-side hover hit testing.

Example:

drawNetworkVisualization(networkContext, bestNetwork, 38, 2);

drawPositionedNetworkGraph

drawPositionedNetworkGraph(
  context: CanvasRenderingContext2D,
  resolvedNetworkVisualizationFrame: NetworkVisualizationResolvedFrame,
  hoverState: NetworkVisualizationHoverState | undefined,
): void

Draws the positioned graph layers and optional guide overlays.

Parameters:

• context - - Canvas 2D drawing context.
• resolvedNetworkVisualizationFrame - - Resolved network visualization frame containing positioned scene, connections, and color scales.
• hoverState - - Optional host-owned hover state for interactive emphasis.

Returns: Nothing.

drawResolvedNetworkVisualization

drawResolvedNetworkVisualization(
  context: CanvasRenderingContext2D,
  resolvedNetworkVisualizationFrame: NetworkVisualizationResolvedFrame,
  hoverState: NetworkVisualizationHoverState | undefined,
): NetworkVisualizationPositionedScene

Draws a previously resolved network-visualization frame.

The host uses this path for hover-only repaint work because it can reuse the cached static frame and only vary interactive emphasis.

Parameters:

• context - - Canvas 2D drawing context.
• resolvedNetworkVisualizationFrame - - Reusable frame cache.
• hoverState - - Optional host-owned hover state for interactive emphasis.

Returns: Positioned node snapshot reused by host-side hover hit testing.

formatArchitectureLabel

formatArchitectureLabel(
  architectureInputSize: number,
  hiddenLayersLabel: string,
  architectureOutputSize: number,
  totalNodeCount: number,
  totalConnectionCount: number,
): string

Formats the two-line architecture label used by the header and legend.

Parameters:

• architectureInputSize - - Input layer size.
• hiddenLayersLabel - - Hidden-layer description.
• architectureOutputSize - - Output layer size.
• totalNodeCount - - Total node count.
• totalConnectionCount - - Total connection count.

Returns: Formatted architecture label.

NetworkVisualizationResolvedFrame

Reusable resolved frame cache for hover-only network redraws.

The host can keep this resolved frame between pointer-driven redraws so it does not recompute topology, layout, legend inputs, or connection lookups until the network payload or canvas size changes.

paintNetworkVisualizationCanvasBase

paintNetworkVisualizationCanvasBase(
  context: CanvasRenderingContext2D,
  networkVisualizationScene: Pick<NetworkVisualizationResolvedFrame, "canvasWidthPx" | "canvasHeightPx">,
): void

Paints the static background fill for the network visualization canvas.

Parameters:

• context - - Canvas 2D drawing context.
• networkVisualizationScene - - Frame scene context.

Returns: Nothing.

resolveAdjustedGraphPaddingContext

resolveAdjustedGraphPaddingContext(
  context: CanvasRenderingContext2D,
  network: default | undefined,
  canvasWidthPx: number,
  hideNetworkOverlays: boolean,
  graphPaddingContext: NetworkGraphPaddingContext,
): Pick<NetworkGraphPaddingContext, "graphLeftPaddingPx" | "graphRightPaddingPx">

Adjusts graph-side padding to keep the floating legend from overlapping nodes.

Parameters:

• context - - Canvas 2D drawing context.
• network - - Network to visualize.
• canvasWidthPx - - Canvas width.
• hideNetworkOverlays - - Whether overlays are hidden.
• graphPaddingContext - - Base graph padding context.

Returns: Adjusted graph padding context.

resolveBaseGraphPaddingContext

resolveBaseGraphPaddingContext(): NetworkGraphPaddingContext

Resolves the base graph padding before legend-aware adjustments are applied.

Returns: Base graph padding context.

resolveHiddenLayersLabel

resolveHiddenLayersLabel(
  hiddenLayerSizes: number[],
  architectureSource: "layer-metadata" | "graph-topology" | "inferred",
): string

Resolves the hidden-layer portion of the compact architecture label.

Parameters:

• hiddenLayerSizes - - Hidden-layer sizes.
• architectureSource - - Architecture source metadata.

Returns: Hidden-layer label.

resolveNetworkArchitectureLabel

resolveNetworkArchitectureLabel(
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): string

Resolves compact architecture label text for headers and HUD rows.

The label compresses the active network into a short human-readable summary: input size, hidden-layer structure, output size, and graph size metadata.

Parameters:

• network - - Network to describe.
• inputSize - - Configured input size.
• outputSize - - Configured output size.

Returns: Readable architecture label.

resolveNetworkDrawableArea

resolveNetworkDrawableArea(
  networkVisualizationScene: NetworkVisualizationScene,
): NetworkDrawableArea

Resolves the drawable graph area after scene padding is applied.

Parameters:

• networkVisualizationScene - - Frame scene context.

Returns: Drawable area dimensions.

resolveNetworkNodeDimensionsFromTopologySummary

resolveNetworkNodeDimensionsFromTopologySummary(
  networkTopologySummary: NetworkTopologySummary,
  drawableWidthPx: number,
  drawableHeightPx: number,
): NetworkNodeDimensionsLike

Resolves node rectangle dimensions from topology density and drawable bounds.

Parameters:

• networkTopologySummary - - Topology summary.
• drawableWidthPx - - Drawable graph width.
• drawableHeightPx - - Drawable graph height.

Returns: Node dimensions.

resolveNetworkTopologySummary

resolveNetworkTopologySummary(
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): NetworkTopologySummary

Resolves a reusable topology summary for layout and sizing helpers.

Parameters:

• network - - Network to visualize.
• inputSize - - Input-layer size.
• outputSize - - Output-layer size.

Returns: Topology summary.

resolveNetworkVisualizationFrame

resolveNetworkVisualizationFrame(
  context: CanvasRenderingContext2D,
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): NetworkVisualizationResolvedFrame

Resolves a reusable network-visualization frame from the active payload.

This fold captures the expensive static work for the panel in one object so hover-only redraws can repaint from cached layout and legend data.

Parameters:

• context - - Canvas 2D drawing context.
• network - - Network to visualize.
• inputSize - - Input-layer size.
• outputSize - - Output-layer size.

Returns: Reusable resolved frame for subsequent draw passes.

resolveNetworkVisualizationHeightPx

resolveNetworkVisualizationHeightPx(
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): number

Resolves responsive visualization canvas height from network shape.

Dense or deeper networks need more vertical room to stay readable, so panel height is driven by topology rather than fixed to a single constant.

Parameters:

• network - - Network to visualize.
• inputSize - - Input-layer size.
• outputSize - - Output-layer size.

Returns: Recommended height in pixels.

Example:

const recommendedHeightPx = resolveNetworkVisualizationHeightPx(network, 38, 2);

resolveNetworkVisualizationScene

resolveNetworkVisualizationScene(
  context: CanvasRenderingContext2D,
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): NetworkVisualizationScene

Resolves all non-topology canvas state needed to draw the network view.

This separates frame-scene concerns such as canvas size, overlays, and color scales from the later graph-topology layout step.

Parameters:

• context - - Canvas 2D drawing context.
• network - - Network to visualize.
• inputSize - - Input-layer size.
• outputSize - - Output-layer size.

Returns: Scene context for the current frame.

resolvePositionedNetworkGraphScene

resolvePositionedNetworkGraphScene(
  networkVisualizationScene: NetworkVisualizationScene,
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): PositionedNetworkGraphScene

Resolves positioned nodes, connection lookup state, and shared node dimensions.

Parameters:

• networkVisualizationScene - - Frame scene context.
• network - - Network to visualize.
• inputSize - - Input-layer size.
• outputSize - - Output-layer size.

Returns: Positioned graph scene.

resolveRecommendedNetworkHeightPx

resolveRecommendedNetworkHeightPx(
  networkTopologySummary: NetworkTopologySummary,
  topologyDrivenHeightPx: number,
): number

Resolves the recommended panel height from topology and density adjustments.

Parameters:

• networkTopologySummary - - Topology summary.
• topologyDrivenHeightPx - - Minimum readable topology height.

Returns: Recommended panel height.

resolveRuntimeConnections

resolveRuntimeConnections(
  network: default | undefined,
): VisualNetworkConnectionLike[]

Resolves the runtime connection array from the active network.

Parameters:

• network - - Network to visualize.

Returns: Runtime connection list.

resolveTopologyDrivenHeightPx

resolveTopologyDrivenHeightPx(
  networkTopologySummary: NetworkTopologySummary,
): number

Resolves the topology-driven minimum readable height.

Parameters:

• networkTopologySummary - - Topology summary.

Returns: Minimum readable height in pixels.

shouldHideNetworkOverlays

shouldHideNetworkOverlays(
  context: CanvasRenderingContext2D,
  fallbackViewportWidthPx: number,
): boolean

Determines whether responsive rules hide auxiliary network overlays.

Parameters:

• context - - Canvas 2D drawing context.
• fallbackViewportWidthPx - - Fallback viewport width.

Returns: True when overlays should be hidden.

browser-entry/network-view/network-view.types.ts

Shared type contracts for network-view overlays.

The most notable overlay is the input-group label band system, which annotates stacked temporal observation channels so the input layer reads as grouped semantics instead of a flat strip of anonymous nodes.

InputGroupLabelBand

Input-group label band geometry and style contract.

Each band identifies a contiguous span of input nodes and the visual style used to render that group marker.

browser-entry/network-view/network-view.constants.ts

Ordered labels for grouped Flappy network input bands.

FLAPPY_INPUT_GROUP_LABELS

Ordered labels for grouped Flappy network input bands.

browser-entry/network-view/network-view.layout.utils.ts

Node-positioning helpers for the browser network view.

Once topology has been resolved into layers, these helpers place nodes inside the drawable panel and then center the final graph so it feels balanced inside the available canvas space.

centerPositionedNodesInDrawableArea

centerPositionedNodesInDrawableArea(
  positionedNodes: PositionedNetworkNodeLike[],
  leftPaddingPx: number,
  topPaddingPx: number,
  drawableWidthPx: number,
  drawableHeightPx: number,
  nodeLayoutPaddingPx: number,
  nodeDimensions: NetworkNodeDimensionsLike,
): PositionedNetworkNodeLike[]

Centers positioned nodes within the drawable graph area.

Positioning establishes relative structure first; centering then shifts the whole graph as a block so it sits comfortably within the padded draw region.

Parameters:

• positionedNodes - - Positioned nodes before centering.
• leftPaddingPx - - Left graph padding.
• topPaddingPx - - Top graph padding.
• drawableWidthPx - - Drawable graph width.
• drawableHeightPx - - Drawable graph height.
• nodeLayoutPaddingPx - - Inner graph padding.
• nodeDimensions - - Node dimensions.

Returns: Center-aligned positioned nodes.

positionNetworkNodes

positionNetworkNodes(
  networkLayers: VisualNetworkNodeLike[][],
  leftPaddingPx: number,
  topPaddingPx: number,
  drawableWidthPx: number,
  drawableHeightPx: number,
  nodeLayoutPaddingPx: number,
  nodeDimensions: NetworkNodeDimensionsLike,
): PositionedNetworkNodeLike[]

Positions network nodes into drawable canvas coordinates.

The layout keeps layer ordering stable while adapting inter-node spacing to the amount of available vertical space.

Parameters:

• networkLayers - - Resolved network layers.
• leftPaddingPx - - Left graph padding.
• topPaddingPx - - Top graph padding.
• drawableWidthPx - - Drawable graph width.
• drawableHeightPx - - Drawable graph height.
• nodeLayoutPaddingPx - - Inner graph padding.
• nodeDimensions - - Node dimensions.

Returns: Positioned nodes.

browser-entry/network-view/network-view.topology.utils.ts

Topology resolution helpers for the browser network view.

These helpers answer a key visualization question: how should the current network be partitioned into ordered layers so layout and architecture labels stay meaningful even when some metadata is missing?

resolveNetworkVisualizationLayers

resolveNetworkVisualizationLayers(
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): VisualNetworkNodeLike[][]

Resolves layered node groups for network-view layout and rendering.

Educational note: Layer grouping is a network-view concern because it drives sizing, node placement, and architecture presentation. Visualization code can still reuse the result, but this helper now lives with the module that owns layout.

The resolver prefers explicit layer metadata when it exists, then falls back to a topology-derived depth estimate so even loosely structured networks can still be drawn in an intelligible left-to-right order.

Parameters:

• network - - Runtime network instance.
• inputSize - - Input count fallback.
• outputSize - - Output count fallback.

Returns: Layered nodes for rendering.

browser-entry/network-view/network-view.draw.service.ts

Overlay drawing helpers specific to the network-view panel.

These helpers render semantic guides that sit on top of the raw graph, most notably the colored input-group bands that explain how temporal observation channels are organized.

drawInputGroupLabelBands

drawInputGroupLabelBands(
  context: CanvasRenderingContext2D,
  inputGroupLabelBandScenes: NetworkInputGroupLabelBandScene[],
): void

Draws vertical neon bands that label semantic groups in the input layer.

Parameters:

• context - - Canvas 2D rendering context.
• inputGroupLabelBandScenes - - Positioned label-band scenes.

Returns: Nothing.

drawRoundedRect

drawRoundedRect(
  context: CanvasRenderingContext2D,
  leftXPx: number,
  topYPx: number,
  widthPx: number,
  heightPx: number,
  radiusPx: number,
  fillColor: string,
): void

Draws a filled rounded rectangle path.

This is the small geometry primitive used by the input-group band renderer.

resolveInputGroupLabelBandScenes

resolveInputGroupLabelBandScenes(
  positionedNodes: PositionedNetworkNodeLike[],
  nodeDimensions: NetworkNodeDimensionsLike,
): NetworkInputGroupLabelBandScene[]

Resolves vertical neon band scenes that label semantic groups in the input layer.

Resolving the bands up front lets drawing and hover hit testing reuse the same geometry instead of maintaining duplicate layout logic.

Parameters:

• positionedNodes - - Positioned nodes in graph coordinates.
• nodeDimensions - - Resolved node dimensions.

Returns: Positioned label-band scenes.

browser-entry/network-view/network-view.labels.utils.ts

Semantic input-label helpers for the network-view panel.

The Flappy controller input layer is not just a list of anonymous scalars; it is organized into stacked observation frames plus action-history channels. These helpers recover that grouping for visual annotation.

resolveInputGroupLabelBands

resolveInputGroupLabelBands(
  inputNodeCount: number,
): InputGroupLabelBand[]

Resolves input-layer semantic label bands for Flappy temporal observation channels.

When the input size matches the expected temporal-memory layout, the view can annotate groups such as stacked frames and action channels directly beside the input layer.

Parameters:

• inputNodeCount - - Input-layer node count.

Returns: Group label ranges with band colors.