# P2b — deterministic pure node layout ## What changed New app-only, pure-Dart files. No existing file, server, web client, legacy client, shell, `main.dart`, pubspec, other feature or platform source was edited. | File | Lines | Responsibility | | --- | --- | --- | | `lib/features/graph/layout/layout_models.dart` | 127 | measured extents, gap config, immutable node box, layout + ranks | | `lib/features/graph/layout/graph_ranks.dart` | 191 | deterministic SCC ranks over the landed definition nodes/edges | | `lib/features/graph/layout/graph_node_layout.dart` | 142 | column/row placement, bounds, validation | | `test/features/graph/layout/layout_fixtures.dart` | 102 | shared definitions and measured extents | | `test/features/graph/layout/graph_ranks_test.dart` | 116 | linear/diamond/cycle/self-loop/disconnected/unknown/long-chain ranks | | `test/features/graph/layout/graph_node_layout_test.dart` | 224 | ordering, terminals, heterogeneous and expanded extents, bounds, determinism | | `test/features/graph/layout/graph_layout_validation_test.dart` | 96 | empty input, missing/extra measurements, duplicate keys, invalid sizes | No layout widgets, painters, edge routing, styling or shell wiring were added. ## Public API ```dart GraphRanks assignGraphRanks(List nodes, List edges); GraphLayout layoutGraphNodes({ required List nodes, required List edges, required Map extents, required GraphLayoutConfig config, }); ``` `NodeExtent` is the caller's measured width/height after text layout. `GraphLayoutConfig` takes `columnGap`, `rowGap` and an optional outer `padding`. No node size, font, colour or device value is assumed in the library. `GraphLayout` returns an unmodifiable `nodes` list of `GraphNodeBox` (`key`, `terminal`, `stageIndex`, `rank`, `x`, `y`, `width`, `height`), an unmodifiable `ranks` map, `rankCount`, and total `width`/`height` including padding. Node keys, terminal flags and stage indices are copied from the landed `graphNodes` identities unchanged. ## Ranking behavior Ranks are read from the definition supplied by the caller; the existing `graphNodes`/`graphEdges` helpers remain the source of identities. - Iterative Tarjan strongly connected components (no recursion; a 2000-stage chain is covered), then longest-path ranks over the condensation DAG. - Every member of a cycle shares one rank, so cyclic routes cannot recurse or push members apart. Self loops are internal supervision and add no rank. - Disconnected stages and disconnected terminals stay at rank 0. - Edges whose source or target is not a node are ignored. An unknown or empty target never creates a node or a rank. - Ranking is linear in nodes plus edges and stable for repeated input. ## Placement behavior - One column per rank; nodes keep definition order inside a rank. - A column is as wide as its widest measured node; columns are separated by `columnGap` and top-aligned. - Nodes are centred in their column and stacked with exactly `rowGap` between measured boxes (centres are compared in the heterogeneous test). - Supplied widths/heights are placed verbatim, so expanded text is never clipped to a fixed box; growing the extents grows the total bounds. - Bounds include every box: tests assert `right <= width` and `bottom <= height` for every fixture. - The result is immutable and identical for identical input. Measurements are required for every node; a missing key throws `ArgumentError` rather than inventing a default size. Extra measurements are ignored because they cannot become nodes. Duplicate/empty node keys, negative or non-finite gaps and extents are rejected. ## Checks actually run ``` flutter pub get dart format lib/features/graph/layout test/features/graph/layout flutter test test/features/graph/layout # 21 passed flutter analyze # No issues found! flutter test # 173 passed git diff --check # clean ``` Tests cover linear, diamond, cycle, self-loop, disconnected, terminals, unknown/empty targets, heterogeneous extents, 2.6x expanded text, determinism, bounds and invalid input. ## Honest limits - **Nodes only.** Edge routing, ports, labels, lanes, hit testing, selection highlighting, painting and native controls are separate later items. - **Not rendered.** A pure nonvisual slice has no browser behavior to capture; no screenshot or browser check applies. - **No server or device.** Tests use local fixtures only; no run, pipeline, schedule, service, emulator, ADB, Android/iOS build or live chat was touched. - **Mobile unverified.** Only web-targeted Flutter test/analyze ran. - **Uncommitted candidate.** Per this stage's instruction the slice is left in the worktree; no commit, push or deployment was made.