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

id, type, title, domain, repo, status, owner, topic_slug, created, updated

id	type	title	domain	repo	status	owner	topic_slug	created	updated
RAIL-FAB-WP-0024	workplan	Stabilize zone containers and layout zone subgraphs	railiance	railiance-fabric	finished	codex	railiance-fabric	2026-05-25	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

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

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

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

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.