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

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
RAIL-FAB-WP-0009	workplan	Graph Explorer UI Refinement	railiance	railiance-fabric	finished	codex	railiance	high	9	2026-05-18	2026-05-19	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

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

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

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

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

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

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

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.