@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -0,0 +1,399 @@
+# browser-entry/network-view
+
+## browser-entry/network-view/network-view.types.ts
+
+### network-view.types
+
+Input-group label band geometry and style contract.
+
+### InputGroupLabelBand
+
+Input-group label band geometry and style contract.
+
+## browser-entry/network-view/network-view.ts
+
+### clampRecommendedNetworkHeightPx
+
+`(recommendedHeightPx: number) => number`
+
+Clamps a recommended network height into the configured panel range.
+
+Parameters:
+
+- `recommendedHeightPx` - - Recommended panel height.
+
+Returns: Clamped panel height.
+
+### createPositionByNodeIndex
+
+`(centeredPositionedNodes: import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").PositionedNetworkNodeLike[]) => Map<number, import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").PositionedNetworkNodeLike>`
+
+Builds a node-index lookup map for resolved positioned nodes.
+
+Parameters:
+
+- `centeredPositionedNodes` - - Positioned nodes after centering.
+
+Returns: Map keyed by node index.
+
+### drawNetworkVisualization
+
+`(context: CanvasRenderingContext2D, network: import("src/architecture/network").default | undefined, inputSize: number, outputSize: number) => void`
+
+Draws a complete, layer-based visualization of the active network.
+
+Parameters:
+
+- `context` - - Canvas 2D drawing context.
+- `network` - - Network to visualize.
+- `inputSize` - - Input-layer size.
+- `outputSize` - - Output-layer size.
+
+Returns: Nothing.
+
+### drawPositionedNetworkGraph
+
+`(context: CanvasRenderingContext2D, networkVisualizationScene: NetworkVisualizationScene, positionedNetworkGraphScene: PositionedNetworkGraphScene) => void`
+
+Draws the positioned graph layers and optional guide overlays.
+
+Parameters:
+
+- `context` - - Canvas 2D drawing context.
+- `networkVisualizationScene` - - Frame scene context.
+- `positionedNetworkGraphScene` - - Positioned graph scene.
+
+Returns: Nothing.
+
+### 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.
+
+### paintNetworkVisualizationCanvasBase
+
+`(context: CanvasRenderingContext2D, networkVisualizationScene: NetworkVisualizationScene) => void`
+
+Paints the base network visualization canvas background.
+
+Parameters:
+
+- `context` - - Canvas 2D drawing context.
+- `networkVisualizationScene` - - Frame scene context.
+
+Returns: Nothing.
+
+### resolveAdjustedGraphPaddingContext
+
+`(context: CanvasRenderingContext2D, network: import("src/architecture/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
+
+`() => NetworkGraphPaddingContext`
+
+Resolves the base graph padding before legend-aware adjustments are applied.
+
+Returns: Base graph padding context.
+
+### 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
+
+`(network: import("src/architecture/network").default | undefined, inputSize: number, outputSize: number) => string`
+
+Resolves compact architecture label text for headers and HUD rows.
+
+Parameters:
+
+- `network` - - Network to describe.
+- `inputSize` - - Configured input size.
+- `outputSize` - - Configured output size.
+
+Returns: Readable architecture label.
+
+### resolveNetworkDrawableArea
+
+`(networkVisualizationScene: NetworkVisualizationScene) => NetworkDrawableArea`
+
+Resolves the drawable graph area after scene padding is applied.
+
+Parameters:
+
+- `networkVisualizationScene` - - Frame scene context.
+
+Returns: Drawable area dimensions.
+
+### resolveNetworkNodeDimensions
+
+`(network: import("src/architecture/network").default | undefined, inputSize: number, outputSize: number, drawableWidthPx: number, drawableHeightPx: number) => import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").NetworkNodeDimensionsLike`
+
+Resolves node rectangle dimensions from topology density and drawable bounds.
+
+Parameters:
+
+- `network` - - Network to visualize.
+- `inputSize` - - Input-layer size.
+- `outputSize` - - Output-layer size.
+- `drawableWidthPx` - - Drawable graph width.
+- `drawableHeightPx` - - Drawable graph height.
+
+Returns: Node dimensions.
+
+### resolveNetworkNodeDimensionsFromTopologySummary
+
+`(networkTopologySummary: NetworkTopologySummary, drawableWidthPx: number, drawableHeightPx: number) => import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").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
+
+`(network: import("src/architecture/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.
+
+### resolveNetworkVisualizationHeightPx
+
+`(network: import("src/architecture/network").default | undefined, inputSize: number, outputSize: number) => number`
+
+Resolves responsive visualization canvas height from network shape.
+
+Parameters:
+
+- `network` - - Network to visualize.
+- `inputSize` - - Input-layer size.
+- `outputSize` - - Output-layer size.
+
+Returns: Recommended height in pixels.
+
+### resolveNetworkVisualizationScene
+
+`(context: CanvasRenderingContext2D, network: import("src/architecture/network").default | undefined, inputSize: number, outputSize: number) => NetworkVisualizationScene`
+
+Resolves all non-topology canvas state needed to draw the network view.
+
+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
+
+`(networkVisualizationScene: NetworkVisualizationScene, network: import("src/architecture/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
+
+`(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
+
+`(network: import("src/architecture/network").default | undefined) => import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").VisualNetworkConnectionLike[]`
+
+Resolves the runtime connection array from the active network.
+
+Parameters:
+
+- `network` - - Network to visualize.
+
+Returns: Runtime connection list.
+
+### resolveTopologyDrivenHeightPx
+
+`(networkTopologySummary: NetworkTopologySummary) => number`
+
+Resolves the topology-driven minimum readable height.
+
+Parameters:
+
+- `networkTopologySummary` - - Topology summary.
+
+Returns: Minimum readable height in pixels.
+
+### 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.constants.ts
+
+### network-view.constants
+
+Ordered labels for grouped Flappy network input bands.
+
+### FLAPPY_INPUT_GROUP_LABELS
+
+## browser-entry/network-view/network-view.draw.service.ts
+
+### drawInputGroupLabelBands
+
+`(context: CanvasRenderingContext2D, positionedNodes: import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").PositionedNetworkNodeLike[], nodeDimensions: import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").NetworkNodeDimensionsLike) => void`
+
+Draws vertical neon bands that label semantic groups in the input layer.
+
+Parameters:
+
+- `context` - - Canvas 2D rendering context.
+- `positionedNodes` - - Positioned nodes in graph coordinates.
+- `nodeDimensions` - - Resolved node dimensions.
+
+Returns: Nothing.
+
+### drawRoundedRect
+
+`(context: CanvasRenderingContext2D, leftXPx: number, topYPx: number, widthPx: number, heightPx: number, radiusPx: number, fillColor: string) => void`
+
+Draws a filled rounded rectangle path.
+
+## browser-entry/network-view/network-view.labels.utils.ts
+
+### resolveInputGroupLabelBands
+
+`(inputNodeCount: number) => import("test/examples/flappy_bird/browser-entry/network-view/network-view.types").InputGroupLabelBand[]`
+
+Resolves input-layer semantic label bands for Flappy temporal observation channels.
+
+Parameters:
+
+- `inputNodeCount` - - Input-layer node count.
+
+Returns: Group label ranges with band colors.
+
+## browser-entry/network-view/network-view.layout.utils.ts
+
+### centerPositionedNodesInDrawableArea
+
+`(positionedNodes: import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").PositionedNetworkNodeLike[], leftPaddingPx: number, topPaddingPx: number, drawableWidthPx: number, drawableHeightPx: number, nodeLayoutPaddingPx: number, nodeDimensions: import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").NetworkNodeDimensionsLike) => import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").PositionedNetworkNodeLike[]`
+
+Centers positioned nodes within the drawable graph area.
+
+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
+
+`(networkLayers: import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").VisualNetworkNodeLike[][], leftPaddingPx: number, topPaddingPx: number, drawableWidthPx: number, drawableHeightPx: number, nodeLayoutPaddingPx: number, nodeDimensions: import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").NetworkNodeDimensionsLike) => import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").PositionedNetworkNodeLike[]`
+
+Positions network nodes into drawable canvas coordinates.
+
+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
+
+### resolveNetworkVisualizationLayers
+
+`(network: import("src/architecture/network").default | undefined, inputSize: number, outputSize: number) => import("test/examples/flappy_bird/browser-entry/browser-entry.visualization.types").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.
+
+Parameters:
+
+- `network` - - Runtime network instance.
+- `inputSize` - - Input count fallback.
+- `outputSize` - - Output count fallback.
+
+Returns: Layered nodes for rendering.

package/test/examples/flappy_bird/browser-entry/network-view/network-view.topology.utils.ts

@@ -0,0 +1,255 @@
+import Network from '../../../../../src/architecture/network';
+import type {
+  VisualNetworkConnectionLike,
+  VisualNetworkNodeLike,
+} from '../browser-entry.types';
+
+/**
+ * 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.
+ *
+ * @param network - Runtime network instance.
+ * @param inputSize - Input count fallback.
+ * @param outputSize - Output count fallback.
+ * @returns Layered nodes for rendering.
+ */
+export function resolveNetworkVisualizationLayers(
+  network: Network | undefined,
+  inputSize: number,
+  outputSize: number,
+): VisualNetworkNodeLike[][] {
+  // Step 1: Build fallback layers when no runtime network is available.
+  if (!network) {
+    return [
+      Array.from({ length: inputSize }, (_unusedValue, inputNodeIndex) => ({
+        index: inputNodeIndex,
+        type: 'input',
+        bias: 0,
+      })),
+      Array.from({ length: outputSize }, (_unusedValue, outputNodeIndex) => ({
+        index: inputSize + outputNodeIndex,
+        type: 'output',
+        bias: 0,
+      })),
+    ];
+  }
+
+  // Step 2: Normalize runtime node records into the view-layer shape.
+  const runtimeNodes = (
+    (network.nodes ?? []) as Array<{
+      index?: number;
+      type?: string;
+      bias?: number;
+      layer?: number;
+    }>
+  ).map((runtimeNode, fallbackNodeIndex) => ({
+    index:
+      typeof runtimeNode.index === 'number'
+        ? runtimeNode.index
+        : fallbackNodeIndex,
+    type: runtimeNode.type ?? 'hidden',
+    bias: runtimeNode.bias ?? 0,
+    layer: runtimeNode.layer,
+  }));
+
+  // Step 3: Resolve input, hidden, and output partitions.
+  const inputAndConstantNodes = runtimeNodes
+    .filter(
+      (runtimeNode) =>
+        runtimeNode.type === 'input' || runtimeNode.type === 'constant',
+    )
+    .toSorted((leftNode, rightNode) => leftNode.index - rightNode.index);
+  const outputNodes = runtimeNodes
+    .filter((runtimeNode) => runtimeNode.type === 'output')
+    .toSorted((leftNode, rightNode) => leftNode.index - rightNode.index);
+  const hiddenNodes = runtimeNodes.filter(
+    (runtimeNode) =>
+      runtimeNode.type !== 'input' &&
+      runtimeNode.type !== 'constant' &&
+      runtimeNode.type !== 'output',
+  );
+
+  // Step 4: Prefer layer metadata, then fall back to topology-derived depth.
+  const hiddenLayersByMetadata = groupHiddenNodesByLayerMetadata(hiddenNodes);
+  const hiddenLayers =
+    hiddenLayersByMetadata.length > 0
+      ? hiddenLayersByMetadata
+      : groupHiddenNodesByTopology(network, runtimeNodes, hiddenNodes);
+  const layeredNodes = [
+    inputAndConstantNodes,
+    ...hiddenLayers,
+    outputNodes,
+  ].filter((layerNodes) => layerNodes.length > 0);
+
+  return layeredNodes.length > 0 ? layeredNodes : [runtimeNodes];
+}
+
+function groupHiddenNodesByLayerMetadata(
+  hiddenNodes: VisualNetworkNodeLike[],
+): VisualNetworkNodeLike[][] {
+  const hiddenNodesWithLayer = hiddenNodes.filter(
+    (hiddenNode) => typeof hiddenNode.layer === 'number',
+  );
+  if (hiddenNodesWithLayer.length === 0) {
+    return [];
+  }
+
+  const nodesByLayer = new Map<number, VisualNetworkNodeLike[]>();
+  hiddenNodesWithLayer.forEach((hiddenNode) => {
+    const layerIndex = hiddenNode.layer as number;
+    const existingLayerNodes = nodesByLayer.get(layerIndex) ?? [];
+    existingLayerNodes.push(hiddenNode);
+    nodesByLayer.set(layerIndex, existingLayerNodes);
+  });
+
+  return [...nodesByLayer.entries()]
+    .toSorted(
+      (leftLayerEntry, rightLayerEntry) =>
+        leftLayerEntry[0] - rightLayerEntry[0],
+    )
+    .map((layerEntry) =>
+      layerEntry[1].toSorted(
+        (leftNode, rightNode) => leftNode.index - rightNode.index,
+      ),
+    );
+}
+
+function groupHiddenNodesByTopology(
+  network: Network,
+  runtimeNodes: VisualNetworkNodeLike[],
+  hiddenNodes: VisualNetworkNodeLike[],
+): VisualNetworkNodeLike[][] {
+  if (hiddenNodes.length === 0) {
+    return [];
+  }
+
+  const hiddenDepthByNodeIndex = resolveHiddenNodeDepthByTopology(
+    runtimeNodes,
+    (network.connections ?? []) as VisualNetworkConnectionLike[],
+  );
+  const nodesByDepth = new Map<number, VisualNetworkNodeLike[]>();
+
+  hiddenNodes.forEach((hiddenNode) => {
+    const depth = hiddenDepthByNodeIndex.get(hiddenNode.index) ?? 1;
+    const existingDepthNodes = nodesByDepth.get(depth) ?? [];
+    existingDepthNodes.push(hiddenNode);
+    nodesByDepth.set(depth, existingDepthNodes);
+  });
+
+  return [...nodesByDepth.entries()]
+    .toSorted(
+      (leftDepthEntry, rightDepthEntry) =>
+        leftDepthEntry[0] - rightDepthEntry[0],
+    )
+    .map((depthEntry) =>
+      depthEntry[1].toSorted(
+        (leftNode, rightNode) => leftNode.index - rightNode.index,
+      ),
+    );
+}
+
+function resolveHiddenNodeDepthByTopology(
+  runtimeNodes: VisualNetworkNodeLike[],
+  runtimeConnections: VisualNetworkConnectionLike[],
+): Map<number, number> {
+  const nodeByIndex = new Map<number, VisualNetworkNodeLike>(
+    runtimeNodes.map((runtimeNode) => [runtimeNode.index, runtimeNode]),
+  );
+  const outgoingTargetsByNode = new Map<number, number[]>();
+  const incomingEdgeCountByNode = new Map<number, number>();
+
+  nodeByIndex.forEach((_runtimeNode, runtimeNodeIndex) => {
+    outgoingTargetsByNode.set(runtimeNodeIndex, []);
+    incomingEdgeCountByNode.set(runtimeNodeIndex, 0);
+  });
+
+  runtimeConnections.forEach((runtimeConnection) => {
+    if (runtimeConnection.enabled === false) {
+      return;
+    }
+
+    const fromNodeIndex = runtimeConnection.from?.index;
+    const toNodeIndex = runtimeConnection.to?.index;
+    if (
+      typeof fromNodeIndex !== 'number' ||
+      typeof toNodeIndex !== 'number' ||
+      !nodeByIndex.has(fromNodeIndex) ||
+      !nodeByIndex.has(toNodeIndex) ||
+      fromNodeIndex === toNodeIndex
+    ) {
+      return;
+    }
+
+    const outgoingTargets = outgoingTargetsByNode.get(fromNodeIndex) ?? [];
+    outgoingTargets.push(toNodeIndex);
+    outgoingTargetsByNode.set(fromNodeIndex, outgoingTargets);
+    incomingEdgeCountByNode.set(
+      toNodeIndex,
+      (incomingEdgeCountByNode.get(toNodeIndex) ?? 0) + 1,
+    );
+  });
+
+  const topologicalQueue = [...incomingEdgeCountByNode.entries()]
+    .filter((incomingEntry) => incomingEntry[1] === 0)
+    .map((incomingEntry) => incomingEntry[0]);
+  const topologicalOrder: number[] = [];
+
+  while (topologicalQueue.length > 0) {
+    const currentNodeIndex = topologicalQueue.shift();
+    if (typeof currentNodeIndex !== 'number') {
+      continue;
+    }
+
+    topologicalOrder.push(currentNodeIndex);
+
+    const outgoingTargets = outgoingTargetsByNode.get(currentNodeIndex) ?? [];
+    outgoingTargets.forEach((targetNodeIndex) => {
+      const remainingIncomingCount =
+        (incomingEdgeCountByNode.get(targetNodeIndex) ?? 0) - 1;
+      incomingEdgeCountByNode.set(targetNodeIndex, remainingIncomingCount);
+      if (remainingIncomingCount === 0) {
+        topologicalQueue.push(targetNodeIndex);
+      }
+    });
+  }
+
+  if (topologicalOrder.length !== nodeByIndex.size) {
+    return new Map<number, number>(
+      runtimeNodes
+        .filter((runtimeNode) => runtimeNode.type === 'hidden')
+        .map((runtimeNode) => [runtimeNode.index, 1]),
+    );
+  }
+
+  const depthByNodeIndex = new Map<number, number>();
+  runtimeNodes.forEach((runtimeNode) => {
+    const baseDepth =
+      runtimeNode.type === 'input' || runtimeNode.type === 'constant' ? 0 : 1;
+    depthByNodeIndex.set(runtimeNode.index, baseDepth);
+  });
+
+  topologicalOrder.forEach((fromNodeIndex) => {
+    const fromDepth = depthByNodeIndex.get(fromNodeIndex) ?? 0;
+    const outgoingTargets = outgoingTargetsByNode.get(fromNodeIndex) ?? [];
+    outgoingTargets.forEach((toNodeIndex) => {
+      const nextDepth = Math.max(
+        depthByNodeIndex.get(toNodeIndex) ?? 1,
+        fromDepth + 1,
+      );
+      depthByNodeIndex.set(toNodeIndex, nextDepth);
+    });
+  });
+
+  return new Map<number, number>(
+    runtimeNodes
+      .filter((runtimeNode) => runtimeNode.type === 'hidden')
+      .map((runtimeNode) => [
+        runtimeNode.index,
+        depthByNodeIndex.get(runtimeNode.index) ?? 1,
+      ]),
+  );
+}