feat: stabilize graph zone containers

workplans/RAIL-FAB-WP-0024-stable-zone-containers-and-layout.md

@@ -0,0 +1,129 @@
+---
+id: RAIL-FAB-WP-0024
+type: workplan
+title: "Stabilize zone containers and layout zone subgraphs"
+domain: railiance
+repo: railiance-fabric
+status: finished
+owner: codex
+topic_slug: railiance-fabric
+created: "2026-05-25"
+updated: "2026-05-25"
+---
+
+# Stabilize Zone Containers And Layout Zone Subgraphs
+
+## Context
+
+RAIL-FAB-WP-0022 made zones first-class visualization entities and
+RAIL-FAB-WP-0023 added plain labels plus view-only zone dragging. The current
+prototype still derives a zone rectangle directly from the current positions of
+its member nodes. When the operator changes the layout algorithm or reruns
+layout, the zone surface moves with the global graph layout instead of staying
+where the operator placed it.
+
+The current resolver also treats every edge attached to a zoned node as zone
+context. That includes display-only repository declaration edges. Those edges
+help explain where graph declarations came from, but they should not be read as
+direct deployment or operational connections across a zone boundary.
+
+This workplan moves the graph explorer toward the intended model: a zone is a
+stable drawing surface, and the assigned subgraph is laid out inside that
+surface as a separate view concern.
+
+## Task 1: Separate Context Edges From Zone Boundary Connectivity
+
+```task
+id: RAIL-FAB-WP-0024-T01
+status: done
+priority: high
+```
+
+Exclude display-only/context edges, especially repository `declares` edges,
+from zone boundary diagnostics and collapsed-zone boundary edges.
+
+Expected result: zone detail may still mention contextual evidence when useful,
+but display-only declaration edges do not make it look as if every zoned node is
+directly connected to an unzoned repository.
+
+Result: Display-only edges and repository `declares` edges are now treated as
+context-only in both the shared zone resolver and the browser view. They do not
+create boundary diagnostics, attraction paths, or collapsed-zone boundary
+edges.
+
+## Task 2: Persist Stable Zone Container Positions
+
+```task
+id: RAIL-FAB-WP-0024-T02
+status: done
+priority: high
+```
+
+Introduce a view-level zone container state keyed by stable zone id.
+
+The implementation should:
+
+- remember zone container center and size after layout and drag;
+- keep user-moved zone positions stable when the global layout algorithm
+  changes;
+- keep saved/copied view state compatible with the nested `zone` object;
+- avoid mutating the Fabric graph payload.
+
+Expected result: switching between layout algorithms keeps zone papers in the
+same operator-chosen positions.
+
+Result: The graph explorer now stores stable zone containers in view state.
+Containers remember graph-coordinate position and size, survive global layout
+reruns, can be saved/copied through the nested `zone` state, and remain separate
+from Fabric graph payload data.
+
+## Task 3: Layout Zone Subgraphs Inside Containers
+
+```task
+id: RAIL-FAB-WP-0024-T03
+status: done
+priority: high
+```
+
+Add a per-zone layout pass that positions assigned visible nodes inside their
+zone container after the global layout places the surrounding graph.
+
+The first implementation may use a deterministic compact layout rather than a
+full nested Cytoscape layout, as long as it:
+
+- only moves visible nodes assigned to the zone;
+- keeps each node inside the zone's drawing surface;
+- treats unzoned nodes as part of the base canvas;
+- keeps edge routing intact through Cytoscape's normal renderer.
+
+Expected result: the visible subgraph inside each zone is arranged by the zone
+view model, not merely enclosed after the global layout.
+
+Result: After global layout, each visible zone projects its assigned nodes into
+a local compact layout inside its stable container. New, not-yet-moved zones are
+packed into readable rows so the default deployment-environment papers start as
+separate drawing surfaces.
+
+## Task 4: Verify And Document Zone Layout Semantics
+
+```task
+id: RAIL-FAB-WP-0024-T04
+status: done
+priority: medium
+```
+
+Update the graph explorer contract and run focused validation.
+
+Verification should cover:
+
+- static UI assertions for context-edge filtering and zone container helpers;
+- JavaScript syntax validation;
+- focused graph explorer and zone resolver tests;
+- a visual smoke check of the graph explorer.
+
+Expected result: documentation and tests describe the new semantics, and the
+running UI shows stable zone containers with locally arranged member nodes.
+
+Result: Updated the graph explorer contract and zone entity documentation.
+Focused tests, generated JavaScript syntax validation, full tests, CLI
+validation, and a headless Edge visual smoke check all passed.