@reicek/neataptic-ts 0.1.25 → 0.1.26

package/test/examples/flappy_bird/browser-entry/network-view/README.md

@@ -16,109 +16,107 @@ canvas helpers.
 
 ## browser-entry/network-view/network-view.ts
 
-### drawNetworkVisualization
+### clampRecommendedNetworkHeightPx
 
 ```ts
-drawNetworkVisualization(
-  context: CanvasRenderingContext2D,
-  network: default | undefined,
-  inputSize: number,
-  outputSize: number,
-): void
+clampRecommendedNetworkHeightPx(
+  recommendedHeightPx: number,
+): number
 ```
 
-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.
+Clamps a recommended network height into the configured panel range.
 
 Parameters:
-- `context` - - Canvas 2D drawing context.
-- `network` - - Network to visualize.
-- `inputSize` - - Input-layer size.
-- `outputSize` - - Output-layer size.
+- `recommendedHeightPx` - - Recommended panel height.
 
-Returns: Nothing.
+Returns: Clamped panel height.
 
-Example:
+### createPositionByNodeIndex
 
 ```ts
-drawNetworkVisualization(networkContext, bestNetwork, 38, 2);
+createPositionByNodeIndex(
+  centeredPositionedNodes: PositionedNetworkNodeLike[],
+): Map<number, PositionedNetworkNodeLike>
 ```
 
-### resolveNetworkVisualizationHeightPx
+Builds a node-index lookup map for resolved positioned nodes.
+
+Parameters:
+- `centeredPositionedNodes` - - Positioned nodes after centering.
+
+Returns: Map keyed by node index.
+
+### drawNetworkVisualization
 
 ```ts
-resolveNetworkVisualizationHeightPx(
+drawNetworkVisualization(
+  context: CanvasRenderingContext2D,
   network: default | undefined,
   inputSize: number,
   outputSize: number,
-): number
+): void
 ```
 
-Resolves responsive visualization canvas height from network shape.
+Draws a complete, layer-based visualization of the active network.
 
-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.
+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.
 
-Returns: Recommended height in pixels.
+Returns: Nothing.
 
 Example:
 
 ```ts
-const recommendedHeightPx = resolveNetworkVisualizationHeightPx(network, 38, 2);
+drawNetworkVisualization(networkContext, bestNetwork, 38, 2);
 ```
 
-### resolveNetworkArchitectureLabel
+### drawPositionedNetworkGraph
 
 ```ts
-resolveNetworkArchitectureLabel(
-  network: default | undefined,
-  inputSize: number,
-  outputSize: number,
-): string
+drawPositionedNetworkGraph(
+  context: CanvasRenderingContext2D,
+  networkVisualizationScene: NetworkVisualizationScene,
+  positionedNetworkGraphScene: PositionedNetworkGraphScene,
+): void
 ```
 
-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.
+Draws the positioned graph layers and optional guide overlays.
 
 Parameters:
-- `network` - - Network to describe.
-- `inputSize` - - Configured input size.
-- `outputSize` - - Configured output size.
+- `context` - - Canvas 2D drawing context.
+- `networkVisualizationScene` - - Frame scene context.
+- `positionedNetworkGraphScene` - - Positioned graph scene.
 
-Returns: Readable architecture label.
+Returns: Nothing.
 
-### resolveNetworkVisualizationScene
+### formatArchitectureLabel
 
 ```ts
-resolveNetworkVisualizationScene(
-  context: CanvasRenderingContext2D,
-  network: default | undefined,
-  inputSize: number,
-  outputSize: number,
-): NetworkVisualizationScene
+formatArchitectureLabel(
+  architectureInputSize: number,
+  hiddenLayersLabel: string,
+  architectureOutputSize: number,
+  totalNodeCount: number,
+  totalConnectionCount: number,
+): string
 ```
 
-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.
+Formats the two-line architecture label used by the header and legend.
 
 Parameters:
-- `context` - - Canvas 2D drawing context.
-- `network` - - Network to visualize.
-- `inputSize` - - Input-layer size.
-- `outputSize` - - Output-layer size.
+- `architectureInputSize` - - Input layer size.
+- `hiddenLayersLabel` - - Hidden-layer description.
+- `architectureOutputSize` - - Output layer size.
+- `totalNodeCount` - - Total node count.
+- `totalConnectionCount` - - Total connection count.
 
-Returns: Scene context for the current frame.
+Returns: Formatted architecture label.
 
 ### paintNetworkVisualizationCanvasBase
 
@@ -137,45 +135,28 @@ Parameters:
 
 Returns: Nothing.
 
-### resolvePositionedNetworkGraphScene
-
-```ts
-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.
-
-### drawPositionedNetworkGraph
+### resolveAdjustedGraphPaddingContext
 
 ```ts
-drawPositionedNetworkGraph(
+resolveAdjustedGraphPaddingContext(
   context: CanvasRenderingContext2D,
-  networkVisualizationScene: NetworkVisualizationScene,
-  positionedNetworkGraphScene: PositionedNetworkGraphScene,
-): void
+  network: default | undefined,
+  canvasWidthPx: number,
+  hideNetworkOverlays: boolean,
+  graphPaddingContext: NetworkGraphPaddingContext,
+): Pick<NetworkGraphPaddingContext, "graphLeftPaddingPx" | "graphRightPaddingPx">
 ```
 
-Draws the positioned graph layers and optional guide overlays.
+Adjusts graph-side padding to keep the floating legend from overlapping nodes.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
-- `networkVisualizationScene` - - Frame scene context.
-- `positionedNetworkGraphScene` - - Positioned graph scene.
+- `network` - - Network to visualize.
+- `canvasWidthPx` - - Canvas width.
+- `hideNetworkOverlays` - - Whether overlays are hidden.
+- `graphPaddingContext` - - Base graph padding context.
 
-Returns: Nothing.
+Returns: Adjusted graph padding context.
 
 ### resolveBaseGraphPaddingContext
 
@@ -187,45 +168,44 @@ Resolves the base graph padding before legend-aware adjustments are applied.
 
 Returns: Base graph padding context.
 
-### shouldHideNetworkOverlays
+### resolveHiddenLayersLabel
 
 ```ts
-shouldHideNetworkOverlays(
-  context: CanvasRenderingContext2D,
-  fallbackViewportWidthPx: number,
-): boolean
+resolveHiddenLayersLabel(
+  hiddenLayerSizes: number[],
+  architectureSource: "layer-metadata" | "graph-topology" | "inferred",
+): string
 ```
 
-Determines whether responsive rules hide auxiliary network overlays.
+Resolves the hidden-layer portion of the compact architecture label.
 
 Parameters:
-- `context` - - Canvas 2D drawing context.
-- `fallbackViewportWidthPx` - - Fallback viewport width.
+- `hiddenLayerSizes` - - Hidden-layer sizes.
+- `architectureSource` - - Architecture source metadata.
 
-Returns: True when overlays should be hidden.
+Returns: Hidden-layer label.
 
-### resolveAdjustedGraphPaddingContext
+### resolveNetworkArchitectureLabel
 
 ```ts
-resolveAdjustedGraphPaddingContext(
-  context: CanvasRenderingContext2D,
+resolveNetworkArchitectureLabel(
   network: default | undefined,
-  canvasWidthPx: number,
-  hideNetworkOverlays: boolean,
-  graphPaddingContext: NetworkGraphPaddingContext,
-): Pick<NetworkGraphPaddingContext, "graphLeftPaddingPx" | "graphRightPaddingPx">
+  inputSize: number,
+  outputSize: number,
+): string
 ```
 
-Adjusts graph-side padding to keep the floating legend from overlapping nodes.
+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:
-- `context` - - Canvas 2D drawing context.
-- `network` - - Network to visualize.
-- `canvasWidthPx` - - Canvas width.
-- `hideNetworkOverlays` - - Whether overlays are hidden.
-- `graphPaddingContext` - - Base graph padding context.
+- `network` - - Network to describe.
+- `inputSize` - - Configured input size.
+- `outputSize` - - Configured output size.
 
-Returns: Adjusted graph padding context.
+Returns: Readable architecture label.
 
 ### resolveNetworkDrawableArea
 
@@ -242,6 +222,25 @@ Parameters:
 
 Returns: Drawable area dimensions.
 
+### resolveNetworkNodeDimensionsFromTopologySummary
+
+```ts
+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
 
 ```ts
@@ -261,86 +260,95 @@ Parameters:
 
 Returns: Topology summary.
 
-### resolveNetworkNodeDimensionsFromTopologySummary
+### resolveNetworkVisualizationHeightPx
 
 ```ts
-resolveNetworkNodeDimensionsFromTopologySummary(
-  networkTopologySummary: NetworkTopologySummary,
-  drawableWidthPx: number,
-  drawableHeightPx: number,
-): NetworkNodeDimensionsLike
+resolveNetworkVisualizationHeightPx(
+  network: default | undefined,
+  inputSize: number,
+  outputSize: number,
+): number
 ```
 
-Resolves node rectangle dimensions from topology density and drawable bounds.
+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:
-- `networkTopologySummary` - - Topology summary.
-- `drawableWidthPx` - - Drawable graph width.
-- `drawableHeightPx` - - Drawable graph height.
+- `network` - - Network to visualize.
+- `inputSize` - - Input-layer size.
+- `outputSize` - - Output-layer size.
 
-Returns: Node dimensions.
+Returns: Recommended height in pixels.
 
-### resolveTopologyDrivenHeightPx
+Example:
 
 ```ts
-resolveTopologyDrivenHeightPx(
-  networkTopologySummary: NetworkTopologySummary,
-): number
+const recommendedHeightPx = resolveNetworkVisualizationHeightPx(network, 38, 2);
 ```
 
-Resolves the topology-driven minimum readable height.
-
-Parameters:
-- `networkTopologySummary` - - Topology summary.
-
-Returns: Minimum readable height in pixels.
-
-### resolveRecommendedNetworkHeightPx
+### resolveNetworkVisualizationScene
 
 ```ts
-resolveRecommendedNetworkHeightPx(
-  networkTopologySummary: NetworkTopologySummary,
-  topologyDrivenHeightPx: number,
-): number
+resolveNetworkVisualizationScene(
+  context: CanvasRenderingContext2D,
+  network: default | undefined,
+  inputSize: number,
+  outputSize: number,
+): NetworkVisualizationScene
 ```
 
-Resolves the recommended panel height from topology and density adjustments.
+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:
-- `networkTopologySummary` - - Topology summary.
-- `topologyDrivenHeightPx` - - Minimum readable topology height.
+- `context` - - Canvas 2D drawing context.
+- `network` - - Network to visualize.
+- `inputSize` - - Input-layer size.
+- `outputSize` - - Output-layer size.
 
-Returns: Recommended panel height.
+Returns: Scene context for the current frame.
 
-### clampRecommendedNetworkHeightPx
+### resolvePositionedNetworkGraphScene
 
 ```ts
-clampRecommendedNetworkHeightPx(
-  recommendedHeightPx: number,
-): number
+resolvePositionedNetworkGraphScene(
+  networkVisualizationScene: NetworkVisualizationScene,
+  network: default | undefined,
+  inputSize: number,
+  outputSize: number,
+): PositionedNetworkGraphScene
 ```
 
-Clamps a recommended network height into the configured panel range.
+Resolves positioned nodes, connection lookup state, and shared node dimensions.
 
 Parameters:
-- `recommendedHeightPx` - - Recommended panel height.
+- `networkVisualizationScene` - - Frame scene context.
+- `network` - - Network to visualize.
+- `inputSize` - - Input-layer size.
+- `outputSize` - - Output-layer size.
 
-Returns: Clamped panel height.
+Returns: Positioned graph scene.
 
-### createPositionByNodeIndex
+### resolveRecommendedNetworkHeightPx
 
 ```ts
-createPositionByNodeIndex(
-  centeredPositionedNodes: PositionedNetworkNodeLike[],
-): Map<number, PositionedNetworkNodeLike>
+resolveRecommendedNetworkHeightPx(
+  networkTopologySummary: NetworkTopologySummary,
+  topologyDrivenHeightPx: number,
+): number
 ```
 
-Builds a node-index lookup map for resolved positioned nodes.
+Resolves the recommended panel height from topology and density adjustments.
 
 Parameters:
-- `centeredPositionedNodes` - - Positioned nodes after centering.
+- `networkTopologySummary` - - Topology summary.
+- `topologyDrivenHeightPx` - - Minimum readable topology height.
 
-Returns: Map keyed by node index.
+Returns: Recommended panel height.
 
 ### resolveRuntimeConnections
 
@@ -357,45 +365,37 @@ Parameters:
 
 Returns: Runtime connection list.
 
-### formatArchitectureLabel
+### resolveTopologyDrivenHeightPx
 
 ```ts
-formatArchitectureLabel(
-  architectureInputSize: number,
-  hiddenLayersLabel: string,
-  architectureOutputSize: number,
-  totalNodeCount: number,
-  totalConnectionCount: number,
-): string
+resolveTopologyDrivenHeightPx(
+  networkTopologySummary: NetworkTopologySummary,
+): number
 ```
 
-Formats the two-line architecture label used by the header and legend.
+Resolves the topology-driven minimum readable height.
 
 Parameters:
-- `architectureInputSize` - - Input layer size.
-- `hiddenLayersLabel` - - Hidden-layer description.
-- `architectureOutputSize` - - Output layer size.
-- `totalNodeCount` - - Total node count.
-- `totalConnectionCount` - - Total connection count.
+- `networkTopologySummary` - - Topology summary.
 
-Returns: Formatted architecture label.
+Returns: Minimum readable height in pixels.
 
-### resolveHiddenLayersLabel
+### shouldHideNetworkOverlays
 
 ```ts
-resolveHiddenLayersLabel(
-  hiddenLayerSizes: number[],
-  architectureSource: "layer-metadata" | "graph-topology" | "inferred",
-): string
+shouldHideNetworkOverlays(
+  context: CanvasRenderingContext2D,
+  fallbackViewportWidthPx: number,
+): boolean
 ```
 
-Resolves the hidden-layer portion of the compact architecture label.
+Determines whether responsive rules hide auxiliary network overlays.
 
 Parameters:
-- `hiddenLayerSizes` - - Hidden-layer sizes.
-- `architectureSource` - - Architecture source metadata.
+- `context` - - Canvas 2D drawing context.
+- `fallbackViewportWidthPx` - - Fallback viewport width.
 
-Returns: Hidden-layer label.
+Returns: True when overlays should be hidden.
 
 ## browser-entry/network-view/network-view.types.ts
 
@@ -428,11 +428,11 @@ 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.
 
-### positionNetworkNodes
+### centerPositionedNodesInDrawableArea
 
 ```ts
-positionNetworkNodes(
-  networkLayers: VisualNetworkNodeLike[][],
+centerPositionedNodesInDrawableArea(
+  positionedNodes: PositionedNetworkNodeLike[],
   leftPaddingPx: number,
   topPaddingPx: number,
   drawableWidthPx: number,
@@ -442,13 +442,13 @@ positionNetworkNodes(
 ): PositionedNetworkNodeLike[]
 ```
 
-Positions network nodes into drawable canvas coordinates.
+Centers positioned nodes within the drawable graph area.
 
-The layout keeps layer ordering stable while adapting inter-node spacing to
-the amount of available vertical space.
+Positioning establishes relative structure first; centering then shifts the
+whole graph as a block so it sits comfortably within the padded draw region.
 
 Parameters:
-- `networkLayers` - - Resolved network layers.
+- `positionedNodes` - - Positioned nodes before centering.
 - `leftPaddingPx` - - Left graph padding.
 - `topPaddingPx` - - Top graph padding.
 - `drawableWidthPx` - - Drawable graph width.
@@ -456,13 +456,13 @@ Parameters:
 - `nodeLayoutPaddingPx` - - Inner graph padding.
 - `nodeDimensions` - - Node dimensions.
 
-Returns: Positioned nodes.
+Returns: Center-aligned positioned nodes.
 
-### centerPositionedNodesInDrawableArea
+### positionNetworkNodes
 
 ```ts
-centerPositionedNodesInDrawableArea(
-  positionedNodes: PositionedNetworkNodeLike[],
+positionNetworkNodes(
+  networkLayers: VisualNetworkNodeLike[][],
   leftPaddingPx: number,
   topPaddingPx: number,
   drawableWidthPx: number,
@@ -472,13 +472,13 @@ centerPositionedNodesInDrawableArea(
 ): PositionedNetworkNodeLike[]
 ```
 
-Centers positioned nodes within the drawable graph area.
+Positions network nodes into drawable canvas coordinates.
 
-Positioning establishes relative structure first; centering then shifts the
-whole graph as a block so it sits comfortably within the padded draw region.
+The layout keeps layer ordering stable while adapting inter-node spacing to
+the amount of available vertical space.
 
 Parameters:
-- `positionedNodes` - - Positioned nodes before centering.
+- `networkLayers` - - Resolved network layers.
 - `leftPaddingPx` - - Left graph padding.
 - `topPaddingPx` - - Top graph padding.
 - `drawableWidthPx` - - Drawable graph width.
@@ -486,7 +486,7 @@ Parameters:
 - `nodeLayoutPaddingPx` - - Inner graph padding.
 - `nodeDimensions` - - Node dimensions.
 
-Returns: Center-aligned positioned nodes.
+Returns: Positioned nodes.
 
 ## browser-entry/network-view/network-view.topology.utils.ts