How Archify's Route Probe Traces Paths Between Nodes

Archify's Route Probe uses a Dijkstra-style directed shortest-path algorithm to trace authored connections between nodes when you press R, computing the optimal route and rendering it as an interactive SVG overlay.

The Route Probe is a core interaction mode in the tt-a1i/archify repository that enables users to discover the shortest directed path between any two stable nodes in a diagram. When activated, the system enters a guided selection state, computes the traversal over the authored edge graph, and displays the result with journey controls. This functionality is implemented primarily in experiments/mco-showcase/mco-runtime.html and consumed by applications like examples/web-app.html.

Activating the Route Probe State Machine

Pressing R triggers Archify.routeProbe.toggle({ focusNode: true }) at line 13223 of the runtime, which sets the probe to active and records its state in the internal state object. The system maintains a single source of truth in Archify.routeProbe, tracking whether the probe is active, the current mode, and the selected start and end nodes.

Selecting Source and Target Nodes

Once activated, the UI presents a finder interface via Archify.routeProbe.finderOpening(). When you click a node, the system invokes Archify.routeProbe.choose(id) at line 11166, storing the first selection as routeProbe.context.start. The finder remains open for a second click, which again calls choose(id) but stores the value as routeProbe.context.end, completing the endpoint selection.

Computing the Shortest Path

With both endpoints defined, Archify.routeProbe.compute() executes an internal directed shortest-path algorithm over the diagram's authored edge graph. Unlike runtime-generated layout shortcuts, this traversal walks Archify.graph.edges to ensure the route reflects the author's intentional flow.

Directed Graph Traversal

The algorithm implements a classic Dijkstra-style search that respects edge directionality and any author-defined cost attributes associated with connections. This guarantees that the computed path represents the optimal authored route rather than geometric proximity.

Rendering the Route Overlay

After computation, the resulting node ID sequence is written into the SVG as data-route-active and data-route-match attributes. CSS rules defined at lines 4019-4022 activate the visualization, using selectors like svg[data-route-active] [data-route-match] { opacity: 1; } to highlight the active path.

Journey Controls and Animation

While the route displays, a journey UI (.route-journey-controls) provides playback controls. The Archify.routeProbe.syncMotion() method updates the journey state—tracking past, current, and future segments—on each animation tick at lines 1465-1467. Users can step forward, backward, pause, or replay the traversal.

Programmatic API and URL Sharing

Developers can interact with the Route Probe programmatically using the global Archify.routeProbe API.

// Activate the probe (equivalent to pressing R)
Archify.routeProbe.toggle({ focusNode: true });

// Programmatically select source and target nodes
Archify.routeProbe.choose('node-123');   // source
Archify.routeProbe.choose('node-456');   // target

Once computed, routes can be shared via URL serialization. The exportSnapshot() method (called at lines 6010 and 6290) serializes the route into the URL hash as #route=…, enabling deep linking to specific paths.

// Export a shareable URL
const snapshot = Archify.routeProbe.exportSnapshot();
console.log('Share this URL:', snapshot.url);

// Control playback programmatically
Archify.routeProbe.playJourney();
Archify.routeProbe.pauseJourney({ preserveElapsed: true });

Exiting and Cleanup

Pressing Esc or toggling R again invokes Archify.routeProbe.escape({ restoreFocus: true }) at lines 13248-13250. This method calls Archify.routeProbe.clear({ updateUrl: false, restoreFocus: false }) to remove temporary attributes and restore the normal view, ensuring no overlay data persists after deactivation.

Summary

• State Machine: The Route Probe uses Archify.routeProbe.toggle() to enter a guided selection mode that tracks start and end nodes in a centralized state object.
• Algorithm: A Dijkstra-style directed shortest-path search traverses Archify.graph.edges to compute optimal authored routes.
• Visualization: The system renders paths using SVG data attributes and CSS selectors, with data-route-active and data-route-match controlling visibility.
• Interactivity: Journey controls managed by syncMotion() allow step-by-step traversal of the computed path.
• Shareability: The exportSnapshot() method serializes routes into URL hashes for sharing specific paths.
• Accessibility: The implementation supports keyboard navigation via focusNode flags and ARIA attributes like aria-pressed and aria-current.

Frequently Asked Questions

What pathfinding algorithm does Archify's Route Probe use?

The Route Probe implements a directed shortest-path algorithm similar to Dijkstra's method. It traverses the authored edge graph stored in Archify.graph.edges while respecting edge directionality and any author-defined cost attributes, ensuring the result reflects intentional diagram structure rather than visual layout.

How can I share a specific route with another user?

After computing a route, call Archify.routeProbe.exportSnapshot() to serialize the current path into the URL hash (e.g., #route=…). This creates a shareable link that recipients can open to view the exact same route traversal automatically.

Is the Route Probe accessible for keyboard-only users?

Yes. The probe supports keyboard navigation through the focusNode: true parameter in toggle() and uses proper ARIA attributes including aria-pressed and aria-current. Users can activate the probe with R, navigate between nodes using standard focus management, and exit with Esc.

Where is the Route Probe implementation located in the codebase?

The core implementation resides in experiments/mco-showcase/mco-runtime.html, specifically around lines 13223 (activation), 11166 (node selection), and 4019-4022 (CSS rendering rules). A minimal integration example appears in examples/web-app.html, demonstrating consumption of the Archify.routeProbe API in a full application context.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}