railiance-fabric/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md

---
id: RAIL-FAB-WP-0009
type: workplan
title: "Graph Explorer UI Refinement"
domain: railiance
repo: railiance-fabric
status: finished
owner: codex
topic_slug: railiance
planning_priority: high
planning_order: 9
created: "2026-05-18"
updated: "2026-05-19"
state_hub_workstream_id: "1d797e74-bb26-4107-9221-db1248c2cb0e"
---

# RAIL-FAB-WP-0009 - Graph Explorer UI Refinement

## Goal

Refine the interactive Fabric graph explorer user interface before extracting
it into a shared `graph-explorer-engine` repository. The shell is still local
to `railiance-fabric`, so this is the right moment to improve the interaction
model, visual hierarchy, orientation workflows, and large-graph ergonomics
while the engine boundary is still flexible.

This workplan intentionally comes before extraction. The goal is to learn from
using the Fabric map against the current local registry, then turn the refined
UI into a stronger reusable engine candidate.

## Design Direction

The explorer should feel like an operational map, not a demo page. It should
make the registered infrastructure legible at a glance, then let a user narrow
into services, interfaces, dependencies, onboarding gaps, and saved operational
views without losing context.

Refinement should focus on:

- a calmer, denser toolbar that still exposes the important controls
- clearer information architecture for the graph, selection details,
  orientation hints, saved views, node visibility, and edge visibility
- map-first behavior where the graph remains the dominant surface
- useful empty, loading, and error states
- visual encodings that make repo/service/interface/dependency/binding node types
  distinguishable without becoming noisy
- explicit node-type and edge-type controls that support multi-selection
- a filtering model that separates hiding from removing entities from layout
- contextual controls that explain which attributes and modifiers apply to
  which node and edge types
- floating map navigation controls and selection anchors that do not depend on
  changing node borders
- better onboarding-gap and unresolved-dependency workflows
- URL and browser-local saved views that are understandable to a human user
- responsive behavior that remains usable on laptop and narrow screens
- bubble-help explanations, keyboard, focus, contrast, and screen-reader basics
- explicit seams for a later repo-scoping adapter and shared engine extraction

## Extraction Guardrail

Do not extract during this workplan. Extraction should wait until:

- the Fabric UI refinement has produced a clearer shell contract
- the repo-scoping adapter parity work has proven a second real host
- any UI assumptions that are Fabric-specific have been moved behind manifest
  fields, payload metadata, or host-provided mode definitions

## Tasks

### T01 - Baseline UI Review

```task
id: RAIL-FAB-WP-0009-T01
status: done
priority: high
state_hub_task_id: "a8cfcf75-d03d-4c2f-8d9a-72ea3607775b"
```

Run the current graph explorer against the local registry and capture concrete
UI friction before changing the implementation.

Acceptance notes:

- Start the local registry and open `/ui/graph-explorer`.
- Review desktop and narrow viewport behavior.
- Exercise search, filters, mode switching, selection, focus, manual
  overrides, saved views, copied state URLs, and reset behavior.
- Capture a concise refinement backlog in repo docs or the workplan.
- Identify which issues block real use and which can wait for extraction.
- Confirm where the current UI still says `Layer`, where global controls like
  Review and Unresolved are ambiguous, and which terms need bubble help.

Closeout note, 2026-05-19: this task is intentionally dropped as a remaining
Codex-side blocker. The in-app browser visual review is unreliable in the
desktop sandbox, and it is not required for the actual local service review.
The explorer runs locally at `http://127.0.0.1:8765/ui/graph-explorer`, so
visual review should happen in a normal browser while Codex continues to use
tests, generated JavaScript compilation, and live HTTP checks.

### T02 - Node And Edge Control Architecture

```task
id: RAIL-FAB-WP-0009-T02
status: done
priority: high
state_hub_task_id: "751a2fc5-2263-48b0-9ef2-d55e37a0735c"
```

Refine terminology, toolbar structure, side panel placement, map controls,
saved-view controls, legend, hidden-summary surface, and orientation hints so
the graph remains central and the controls are easier to scan.

Acceptance notes:

- Replace user-facing `Layer` wording with `Nodes`, `Node type`, or
  `Node types`. Internal manifest fields may keep `layer` until extraction if
  that avoids churn.
- Replace the single node layer selector with a multi-select node type control.
- Add a multi-select edge type control for showing and hiding relationships by
  edge type.
- Move pan, zoom, fit, focus, and reset navigation controls into a floating map
  menu.
- Reduce visual clutter in the toolbar without hiding core workflows.
- Give selection details, orientation workflows, saved views, and legend
  predictable places.
- Make hidden/blurred overrides and active filters easy to understand.
- Keep the first screen as the working map, not documentation.

### T03 - Graph Readability, Layout Semantics, And Selection Anchors

```task
id: RAIL-FAB-WP-0009-T03
status: done
priority: high
state_hub_task_id: "3e60397c-c833-4bd7-ba1b-b754b203dade"
```

Improve graph readability through better node-type styling, labels, edge
treatment, selection affordances, unresolved/onboarding markers, layout
defaults, and repo-local layout affinity.

Acceptance notes:

- Node type colors are distinguishable and not dominated by one hue family.
- Node and edge labels do not overwhelm dense views.
- Selected, hovered, hidden, blurred, unresolved, and registered-only states are
  visually distinct.
- Selection is represented by an arrow or anchor pointing to the focused entity
  rather than by relying on border changes.
- A selected entity can be hidden and unhidden without losing the selection
  anchor; the anchor changes only when focus changes.
- Repo-local nodes stay closer together than cross-repo relationships, while
  servers and deployments bind tightly to their runtime/deployment entities and
  more loosely to service repos.
- Default layout gives a useful first impression with the current registry data.

### T04 - Filter Rule Builder And Visibility Semantics

```task
id: RAIL-FAB-WP-0009-T04
status: done
priority: high
state_hub_task_id: "1b446ac8-eeba-4de6-9a32-d7f980d70b93"
```

Design and implement an optional filtering panel that can express detailed
node and edge rules without turning type-specific attributes into unexplained
global controls.

Acceptance notes:

- Users can create a list of rules that target nodes or edges by type and by
  supported attributes.
- Type-specific concepts such as Review and Unresolved appear only when they
  apply to the selected node or edge types, either as contextual controls or
  rule templates.
- Rules can apply modifiers such as show, hide, blur, highlight, or remove.
- Node and edge filtering supports two explicit result modes: hide while
  preserving the current layout, or remove from layout and redraw the graph.
- The active rule list is inspectable, editable, reorderable, and resettable.

### T05 - Bubble Help, Accessibility, Responsiveness, And Failure States

```task
id: RAIL-FAB-WP-0009-T05
status: done
priority: medium
state_hub_task_id: "67a9cbc9-ebaa-4cb1-bec9-46bf250faf41"
```

Harden the graph explorer UI for basic accessibility, responsive use, and
failure handling before it becomes a candidate shared engine. Explain the
domain terms directly where users encounter them.

Acceptance notes:

- Add bubble-help explanations to graph terms and controls, including Nodes,
  Node types, Edge types, Layout, Review, Unresolved, Hide, Remove, Blur,
  Focus, Fit, and saved views.
- Bubble help must explain what the control changes, whether it affects layout,
  and why a term might not apply to every node or edge type.
- Controls have useful labels, focus order, and keyboard-accessible behavior.
- Text fits on narrow and desktop viewports.
- Loading, empty graph, fetch failure, and missing Cytoscape states are
  understandable.
- Tests cover the static UI wiring for new states and controls.

### T06 - Repo-Scoping Adapter Readiness Review

```task
id: RAIL-FAB-WP-0009-T06
status: done
priority: medium
state_hub_task_id: "934ea4d9-0d36-414d-9ed7-10f39410da8d"
```

Review the refined UI against the repo-scoping parity checklist before creating
the adapter workplan.

Acceptance notes:

- Identify remaining Fabric-specific assumptions in the UI shell.
- Confirm which controls should be manifest-driven before extraction.
- Confirm that user-facing node and edge terminology can be supplied through
  manifest labels or host-provided vocabulary without leaking Fabric internals.
- Confirm that the rule-panel data model can support repo-scoping manifests as
  well as Fabric ecosystem manifests.
- Update `docs/graph-explorer-operations.md` or contract docs with any refined
  engine boundary.
- Recommend whether the next workplan should be repo-scoping adapter parity or
  one more Fabric-side UI hardening pass.

### T07 - Orientation Workflow Polish

```task
id: RAIL-FAB-WP-0009-T07
status: done
priority: medium
state_hub_task_id: "6cf1fb8b-9d50-4550-942a-69bc29d14eaa"
```

Make the Fabric-specific orientation workflows easier to use for service
dependencies, interface consumers, onboarding gaps, unresolved dependencies,
and saved operational contexts after the node, edge, and rule controls are in
place.

Acceptance notes:

- Selecting a service shows a readable dependency/provider chain.
- Selecting an interface shows consumers and impact context.
- Registered-only repos are visible as actionable onboarding gaps.
- Saved local views have understandable names, status, and sharing behavior.
- Orientation workflows reuse the same hide/remove, node type, edge type, and
  selection anchor semantics as the rest of the map.