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

---
id: RAIL-FAB-WP-0021
type: workplan
title: "Zone Boundary Overlays"
domain: railiance
repo: railiance-fabric
status: finished
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: done
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.

Result: documented environment/access-zone boundary rules in
`docs/graph-explorer-contract.md`; graph explorer maps `dev` to `dev-tegwick`,
legacy `staging` to `test`, `prod` to `prod`, and ignores catch-all `all`
environment values for rectangle boundaries.

## T02 - Render Rectangle Boundary Overlays

```task
id: RAIL-FAB-WP-0021-T02
status: done
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.

Result: added a canvas overlay layer that computes padded rendered-node bounds,
draws labeled rectangles, updates after layout/pan/zoom/filter changes, and
hides empty zones.

## T03 - Add Zone Overlay Controls

```task
id: RAIL-FAB-WP-0021-T03
status: done
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.

Result: added map controls for zone visibility and grouping by deployment
environment or access zone, with URL/profile state preservation.

## T04 - Surface Zone Boundary Details

```task
id: RAIL-FAB-WP-0021-T04
status: done
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.

Result: zone labels are clickable and show scoped counts for visible nodes,
environments, scenarios, access zones, routing authorities, policy authorities,
and route-without-policy-authority warnings; existing focus/highlight/hide
orientation actions work for zone contexts.

## T05 - Verify Responsive And Dense Graph Behavior

```task
id: RAIL-FAB-WP-0021-T05
status: done
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.

Result: static UI tests cover the zone controls/helpers; JavaScript syntax was
checked with `node --check`; the full test suite and validator pass; a headless
Edge smoke screenshot confirmed visible labeled boundaries in deployment
environment mode.