docs: add zone boundary overlay workplan

workplans/RAIL-FAB-WP-0021-zone-boundary-overlays.md

@@ -0,0 +1,173 @@
+---
+id: RAIL-FAB-WP-0021
+type: workplan
+title: "Zone Boundary Overlays"
+domain: railiance
+repo: railiance-fabric
+status: ready
+owner: codex
+topic_slug: railiance
+created: "2026-05-24"
+updated: "2026-05-24"
+state_hub_workstream_id: "e9e2d47f-a965-4e2e-b65d-379dbb206a65"
+---
+
+# RAIL-FAB-WP-0021 - Zone Boundary Overlays
+
+## Goal
+
+Make deployment zones visible as labeled rectangular boundaries in the Fabric
+graph explorer, so an operator can immediately see which nodes belong to local
+dev, shared test, and production contexts.
+
+This work builds on `RAIL-FAB-WP-0020` deployment overlay fields. Zone
+boundaries are visual annotations over graph elements. They must not create new
+fabric membership, ownership, security policy, or routing authority.
+
+Initial display labels:
+
+- `dev-tegwick` for the private developer-local overlay;
+- `test` for shared test-stage services;
+- `prod` for production services.
+
+The implementation should keep the underlying graph explorable and avoid
+turning zones into hard layout containers unless that proves necessary.
+
+## Background
+
+WP-20 added deployment overlay fields and graph explorer modes for:
+
+- deployment environment;
+- deployment scenario;
+- routing authority;
+- access zone;
+- policy authority;
+- route evidence.
+
+The current UI can filter and summarize zone-oriented data, but the operator
+still needs to infer the spatial grouping from node labels and details. The next
+step is to draw zone boundaries around the visible nodes that share a deployment
+zone, with a readable label on the boundary.
+
+The likely implementation path is a graph-canvas overlay layer that computes
+bounding rectangles from rendered node positions after layout, pan, zoom, filter,
+or mode changes. This is preferred over changing graph topology to compound
+parent nodes unless testing shows the overlay layer is too fragile.
+
+## T01 - Define Zone Grouping And Labels
+
+```task
+id: RAIL-FAB-WP-0021-T01
+status: todo
+priority: high
+state_hub_task_id: "91777c22-663c-443a-b682-38bfb7a864bf"
+```
+
+Define how graph explorer elements map to zone overlay groups.
+
+Expected grouping rules:
+
+- primary grouping field is `deploymentEnvironment`;
+- `dev` nodes in the private local scenario render as `dev-tegwick`;
+- `test` nodes render as `test`;
+- `prod` nodes render as `prod`;
+- nodes without deployment overlay data are not enclosed by a zone boundary;
+- edge-only overlay evidence should affect zone warnings/details but should not
+  create a rectangle unless at least one visible node belongs to the zone.
+
+Done when the grouping and label rules are documented in the graph explorer
+contract or operations docs and have focused tests.
+
+## T02 - Render Rectangle Boundary Overlays
+
+```task
+id: RAIL-FAB-WP-0021-T02
+status: todo
+priority: high
+state_hub_task_id: "98ef5ecc-fa4d-443c-a4fe-fa896984d6c4"
+```
+
+Draw labeled rectangular boundaries around the currently visible nodes in each
+zone group.
+
+Implementation expectations:
+
+- compute rectangles from rendered node bounding boxes;
+- add padding so borders do not collide with node labels;
+- draw borders above the canvas background but below interaction-critical UI;
+- keep zone labels readable at normal zoom levels;
+- update rectangles after layout, pan, zoom, resize, filter, mode, focus,
+  manual override, and rule changes;
+- hide a zone boundary when no visible nodes remain in that zone.
+
+Done when the UI shows stable labeled rectangles for `dev-tegwick`, `test`, and
+`prod` where matching nodes are visible.
+
+## T03 - Add Zone Overlay Controls
+
+```task
+id: RAIL-FAB-WP-0021-T03
+status: todo
+priority: medium
+state_hub_task_id: "30d48d5c-bd53-434b-9b8b-ed1a495cee4e"
+```
+
+Add lightweight controls for zone boundaries without cluttering the graph
+explorer toolbar.
+
+Expected controls:
+
+- toggle zone boundaries on or off;
+- choose whether boundaries group by deployment environment or access zone if
+  both are useful;
+- preserve the setting in copied URL state and browser-local profiles.
+
+Done when operators can turn the overlay off for dense graph inspection and
+restore it through shared/saved view state.
+
+## T04 - Surface Zone Boundary Details
+
+```task
+id: RAIL-FAB-WP-0021-T04
+status: todo
+priority: medium
+state_hub_task_id: "c002aa54-a243-4912-81ae-0d282910ebc6"
+```
+
+Make a zone boundary useful when inspected.
+
+Expected behavior:
+
+- clicking or selecting a zone label should show zone summary details;
+- details should include visible node count, deployment environment, scenarios,
+  access zones, routing authorities, and route-without-policy-authority warnings;
+- zone selection should not replace node/edge selection semantics permanently;
+- a zone-focused view should be possible via existing focus/rule mechanisms if
+  it can be done simply.
+
+Done when a zone label provides the same core answers as the WP-20 map overview,
+but scoped to that zone.
+
+## T05 - Verify Responsive And Dense Graph Behavior
+
+```task
+id: RAIL-FAB-WP-0021-T05
+status: todo
+priority: high
+state_hub_task_id: "03f265ad-f335-4caf-a882-35d8d30c75fc"
+```
+
+Verify that zone rectangles remain useful across normal operator viewports and
+dense graphs.
+
+Checks should cover:
+
+- desktop and narrower browser widths;
+- full graph mode and deployment zone modes;
+- filtered views where a zone has only one or two nodes;
+- hidden/removed nodes from rule and manual override controls;
+- graph pan/zoom/layout changes;
+- no incoherent overlap between labels, controls, and detail panels.
+
+Done when automated tests cover the computed grouping behavior and a browser
+smoke check confirms the canvas overlay is visible and aligned.