Stabilize Visualization Layer (draw / draw_live) #13

Right now:

• Visualization behavior is loosely defined
• Styling and layout are limited
• No clear separation between static and interactive rendering
• No way to explore graphs dynamically

Goal

Stabilize and formalize the visualization layer so it is:

• Predictable
• Extensible
• Useful for debugging and demos
• Safe to use in development workflows

Additionally, introduce an optional live visualization mode for interactive exploration.

Scope

1️⃣ Stabilize draw() (Static Visualization)

Responsibilities

• Clearly define what draw(graph) guarantees:

  • Deterministic layout (same graph → same layout)
  • Directed edges visually distinct
  • Node labels rendered consistently

• Support basic customization:

  • Color by node_type
  • Style by relation

• Handle edge cases gracefully:

  • Empty graphs
  • Single-node graphs
  • Disconnected components

• No side effects (no file writes, no servers)

Non-goals

• Interactivity
• Animation
• Live updates

draw() should be boring, predictable, and reliable.

2️⃣ Introduce draw_live() (Interactive Visualization)

Concept
draw_live(graph) starts a local, lightweight visualization server for interactive graph exploration.

This is optional, developer-facing tooling.

Expected Behavior

• Starts a small local server (ephemeral, dev-only)

• Opens a browser window automatically

• Renders the current graph state

• Allows:

  • Zoom / pan
  • Hover to inspect node/edge metadata
  • Toggle node/edge types

• Clean shutdown on process exit or user interrupt

Important Constraints

• No external cloud dependencies
• No persistent state unless explicitly enabled
• Must not block core library usage

3️⃣ Architecture Requirements

• Clear separation between:

  • Core graph logic
  • Visualization adapters

• Visualization should be a thin layer

• Core graph must not depend on visualization internals

• draw_live must fail gracefully if dependencies are missing

4️⃣API Sketch (Non-binding)

draw(graph)

draw_live(
    graph,
    host="127.0.0.1",
    port=0,  # auto-pick free port
    open_browser=True
)

Deliverables

• Stable draw() implementation with documented guarantees

• draw_live() with local interactive visualization

• Clear documentation and examples

• Graceful error handling (missing deps, port conflicts)

• Tests for:

  • Rendering edge cases
  • API stability (non-regression)

Acceptance Criteria

• draw() produces consistent output for the same graph
• Visualization does not mutate graph state
• draw_live() starts and shuts down cleanly
• No hard dependency on visualization for core usage
• Works on common dev environments without setup pain

Out of Scope

• Production-grade dashboards
• Multi-user collaboration
• Remote hosting
• Agent-driven visual updates (for now)